claudetools/.claude/VAULT-SETUP-GUIDE.md

Vault Setup Guide - Multi-Machine Reference

Last Updated: 2026-04-21 Tested On: Mikes-MacBook-Air.local (Mac), DESKTOP-0O8A1RL (Windows) Purpose: Complete guide for setting up vault access on any machine

---

Overview

The vault repository contains encrypted credentials (SOPS files) required for remediation-tool to acquire tokens. This guide covers full setup from scratch on any machine.

---

Prerequisites

Before starting, you need:

• ClaudeTools repository cloned
• Network access to Gitea server (http://172.16.3.20:3000)
• Gitea credentials (username: azcomputerguru, password: see below)
• Age key (private key shared across team - see below)

---

Quick Reference - Credentials

Gitea Password

Gptf*77ttb123!@#-git

Age Private Key

# created: 2026-03-30T13:53:19-07:00
# public key: age1qz7ct84m50u06h97artqddkj3c8se2yu4nxu59clq8rhj945jc0s5excpr
AGE-SECRET-KEY-1DE3V6V0ZLLZ45A7GA77M79CTN4LZQMTRCURP8VRGNLV6T2FSZEEQXUW2EU

---

Installation Steps

Step 1: Install Dependencies

Mac (Homebrew):

brew install sops age jq

Windows (Chocolatey):

choco install sops age jq

Windows (Manual):

• Download SOPS: https://github.com/mozilla/sops/releases
• Download age: https://github.com/FiloSottile/age/releases
• Download jq: https://jqlang.github.io/jq/download/
• Add to PATH

Linux (apt):

sudo apt install age jq
# SOPS from GitHub releases (not in apt)
wget https://github.com/mozilla/sops/releases/download/v3.12.2/sops-v3.12.2.linux.amd64 -O /usr/local/bin/sops
chmod +x /usr/local/bin/sops

Step 2: Clone Vault Repository

Mac/Linux:

git clone http://azcomputerguru@172.16.3.20:3000/azcomputerguru/vault.git ~/vault
# Password when prompted: Gptf*77ttb123!@#-git

Windows:

git clone http://azcomputerguru@172.16.3.20:3000/azcomputerguru/vault.git D:\vault
REM Password when prompted: Gptf*77ttb123!@#-git

Important: Must use real terminal, not Claude Code shell (auth prompts don't work in Claude Code).

Step 3: Configure Age Key

Mac/Linux:

mkdir -p ~/.config/sops/age
cat > ~/.config/sops/age/keys.txt << 'AGEEOF'
# created: 2026-03-30T13:53:19-07:00
# public key: age1qz7ct84m50u06h97artqddkj3c8se2yu4nxu59clq8rhj945jc0s5excpr
AGE-SECRET-KEY-1DE3V6V0ZLLZ45A7GA77M79CTN4LZQMTRCURP8VRGNLV6T2FSZEEQXUW2EU
AGEEOF
chmod 600 ~/.config/sops/age/keys.txt

Windows (PowerShell):

$KeyDir = "$env:USERPROFILE\.config\sops\age"
New-Item -ItemType Directory -Force -Path $KeyDir | Out-Null

$KeyContent = @"
# created: 2026-03-30T13:53:19-07:00
# public key: age1qz7ct84m50u06h97artqddkj3c8se2yu4nxu59clq8rhj945jc0s5excpr
AGE-SECRET-KEY-1DE3V6V0ZLLZ45A7GA77M79CTN4LZQMTRCURP8VRGNLV6T2FSZEEQXUW2EU
"@

Set-Content -Path "$KeyDir\keys.txt" -Value $KeyContent -NoNewline

Windows (Git Bash):

mkdir -p /c/Users/$USER/.config/sops/age
cat > /c/Users/$USER/.config/sops/age/keys.txt << 'AGEEOF'
# created: 2026-03-30T13:53:19-07:00
# public key: age1qz7ct84m50u06h97artqddkj3c8se2yu4nxu59clq8rhj945jc0s5excpr
AGE-SECRET-KEY-1DE3V6V0ZLLZ45A7GA77M79CTN4LZQMTRCURP8VRGNLV6T2FSZEEQXUW2EU
AGEEOF

Step 4: Configure SOPS Environment Variable

Mac (zsh):

echo 'export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt' >> ~/.zshenv
source ~/.zshenv

Mac (bash):

echo 'export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt' >> ~/.bash_profile
source ~/.bash_profile

Windows (PowerShell - permanent):

[Environment]::SetEnvironmentVariable("SOPS_AGE_KEY_FILE", "$env:USERPROFILE\.config\sops\age\keys.txt", "User")

Windows (Git Bash):

echo 'export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt' >> ~/.bashrc
source ~/.bashrc

Linux:

echo 'export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt' >> ~/.bashrc
source ~/.bashrc

Step 5: Fix vault.sh Line Endings (If Needed)

If you see error: env: bash\r: No such file or directory

This means vault.sh has Windows line endings (CRLF). Fix with:

Mac/Linux:

# Using perl (always available)
perl -pi -e 's/\r\n/\n/g' ~/vault/scripts/vault.sh

# Or using dos2unix if installed
dos2unix ~/vault/scripts/vault.sh

Windows (Git Bash):

dos2unix /d/vault/scripts/vault.sh

Make executable:

chmod +x ~/vault/scripts/vault.sh  # Mac/Linux
chmod +x /d/vault/scripts/vault.sh  # Windows Git Bash

Step 6: Add vault_path to identity.json

Edit ClaudeTools identity.json:

Mac:

# File: ~/ClaudeTools/.claude/identity.json
# Add this field:
"vault_path": "/Users/azcomputerguru/vault"

Windows:

# File: D:\ClaudeTools\.claude\identity.json
# Add this field:
"vault_path": "D:/vault"

Linux:

# File: ~/ClaudeTools/.claude/identity.json
# Add this field:
"vault_path": "/home/<username>/vault"

Full example:

{
  "user": "mike",
  "full_name": "Mike Swanson",
  "email": "mike@azcomputerguru.com",
  "role": "admin",
  "machine": "Mikes-MacBook-Air",
  "mode": "general",
  "last_updated": "2026-04-19T08:40:00Z",
  "vault_path": "/Users/azcomputerguru/vault"
}

---

Verification Steps

Test 1: Verify SOPS Can Decrypt

Mac/Linux:

sops --decrypt ~/vault/msp-tools/computerguru-security-investigator.sops.yaml | head -10

Windows:

sops --decrypt D:/vault/msp-tools/computerguru-security-investigator.sops.yaml | head -10

Expected output: YAML content starting with kind: entra-app

If you see: Failed to get the data key → Age key not configured correctly

Test 2: Verify vault.sh Works

Mac/Linux:

~/vault/scripts/vault.sh get-field msp-tools/computerguru-security-investigator.sops.yaml credentials.client_id

Windows:

bash D:/vault/scripts/vault.sh get-field msp-tools/computerguru-security-investigator.sops.yaml credentials.client_id

Expected output: bfbc12a4-f0dd-4e12-b06d-997e7271e10c

Test 3: Verify Token Acquisition

Mac/Linux:

cd ~/ClaudeTools/.claude/skills/remediation-tool/scripts
./get-token.sh grabblaw.com investigator

Windows:

cd D:\ClaudeTools\.claude\skills\remediation-tool\scripts
bash get-token.sh grabblaw.com investigator

Expected output: JWT token starting with eyJ0eXAiOiJKV1Qi...

Test 4: Test All Tiers

Mac/Linux/Windows (Git Bash):

for tier in investigator investigator-exo user-manager tenant-admin; do
    echo "Testing tier: $tier"
    ./get-token.sh grabblaw.com $tier | head -c 50
    echo "..."
    echo "---"
done

Expected: JWT tokens for all 4 tiers (defender will fail - not consented in grabblaw.com)

---

Common Issues and Solutions

Issue 1: "Device not configured" when cloning vault

Symptom:

fatal: could not read Password for 'http://azcomputerguru@172.16.3.20:3000': Device not configured

Cause: Git cannot prompt for password in Claude Code shell

Solution: Clone in real terminal (Terminal.app, PowerShell, etc.)

Issue 2: "env: bash\r: No such file or directory"

Symptom: vault.sh won't execute, complains about bash\r

Cause: Windows line endings (CRLF) in vault.sh

Solution:

perl -pi -e 's/\r\n/\n/g' ~/vault/scripts/vault.sh
chmod +x ~/vault/scripts/vault.sh

Issue 3: "Failed to get the data key"

Symptom: SOPS can't decrypt files

Cause: Age key not found or SOPS_AGE_KEY_FILE not set

Solution:

1. Verify age key exists: cat ~/.config/sops/age/keys.txt
2. Set environment variable: export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt
3. Add to shell RC file for persistence

Issue 4: "vault_path not set in identity.json"

Symptom: get-token.sh fails with vault_path error

Cause: Missing vault_path field in .claude/identity.json

Solution: Add "vault_path": "/path/to/vault" to identity.json

Issue 5: Python "pipefail: invalid option name"

Symptom: vault.sh fails on Mac with pipefail error

Cause: macOS ships with old bash (3.2) that doesn't support set -o pipefail

Solution: Already fixed in vault.sh - ensure you have latest version

Issue 6: "command not found: sops"

Symptom: SOPS not in PATH

Cause: SOPS not installed or not in PATH

Solution:

• Mac: brew install sops
• Windows: choco install sops or add to PATH manually
• Linux: Download from GitHub releases

---

What Gets Installed

After successful setup, these files/directories exist:

Mac/Linux

~/.config/sops/age/keys.txt           # Age private key
~/vault/                               # Vault repository
~/vault/.sops.yaml                     # SOPS config
~/vault/msp-tools/*.sops.yaml          # Encrypted credentials (6 files)
~/vault/scripts/vault.sh               # Vault CLI wrapper
~/ClaudeTools/.claude/identity.json    # Contains vault_path
~/.zshenv (or ~/.bashrc)               # Contains SOPS_AGE_KEY_FILE

Windows

C:\Users\<user>\.config\sops\age\keys.txt    # Age private key
D:\vault\                                     # Vault repository
D:\vault\.sops.yaml                           # SOPS config
D:\vault\msp-tools\*.sops.yaml                # Encrypted credentials (6 files)
D:\vault\scripts\vault.sh                     # Vault CLI wrapper
D:\ClaudeTools\.claude\identity.json          # Contains vault_path
Environment variable: SOPS_AGE_KEY_FILE       # System environment

---

Vault Repository Structure

vault/
├── .sops.yaml                    # SOPS encryption config
├── README.md                     # Vault documentation
├── scripts/
│   ├── vault.sh                  # CLI wrapper
│   └── yaml-query.py             # YAML parser (yq fallback)
├── msp-tools/
│   ├── computerguru-security-investigator.sops.yaml    # Tier 1: Graph read
│   ├── computerguru-exchange-operator.sops.yaml        # Tier 2: EXO write
│   ├── computerguru-user-manager.sops.yaml             # Tier 3: Graph user write
│   ├── computerguru-tenant-admin.sops.yaml             # Tier 4: Graph admin
│   ├── computerguru-defender-addon.sops.yaml           # Tier 5: MDE only
│   └── computerguru-management.sops.yaml               # Legacy (deprecated)
├── infrastructure/
├── clients/
├── services/
└── projects/

---

Security Notes

Age Key Security

The age private key decrypts ALL vault secrets. Treat it like a master password.

• Never commit to git repositories
• Never share in plaintext over unsecured channels
• File permissions: 600 (owner read/write only)
• Store in .config/sops/age/ (standard location)

Gitea Credentials

• Password: Gptf*77ttb123!@#-git
• Used for vault repo clone/pull/push
• Same credentials on all machines
• Consider using SSH keys instead of HTTPS for better security

SOPS Files

• Encrypted at rest with age
• Only credentials, password, secret, api_key, token fields are encrypted
• Metadata (kind, name, description) is plaintext
• Encrypted regex defined in .sops.yaml

---

Maintenance

Pulling Latest Vault Changes

Mac/Linux:

cd ~/vault
git pull origin main

Windows:

cd D:\vault
git pull origin main

Run this periodically to get:

• New SOPS files
• Updated credentials
• Vault script improvements

Rotating Age Key

If the age key needs to be rotated:

1. Generate new age key: age-keygen -o new-key.txt
2. Re-encrypt all SOPS files with new key
3. Distribute new key to all machines
4. Update .config/sops/age/keys.txt on each machine
5. Update .sops.yaml with new public key

Note: This is a team-wide operation requiring coordination.

---

Multi-Machine Status

Machine	Vault Status	Notes
DESKTOP-0O8A1RL (Windows)	✓ WORKING	Original setup, all tiers tested
Mikes-MacBook-Air (Mac)	✓ WORKING	Full setup completed 2026-04-21
ACG-Tech03L (Howard)	PENDING	Needs vault clone + age key setup
HOWARD-HOME	PENDING	Needs vault clone + age key setup

---

For Howard (ACG-Tech03L Setup)

Howard, when you're ready to set up remediation-tool:

Quick Setup (Git Bash)

# 1. Clone vault
git clone http://azcomputerguru@172.16.3.20:3000/azcomputerguru/vault.git D:/vault
# Password: Gptf*77ttb123!@#-git

# 2. Install age key
mkdir -p ~/.config/sops/age
cat > ~/.config/sops/age/keys.txt << 'AGEEOF'
# created: 2026-03-30T13:53:19-07:00
# public key: age1qz7ct84m50u06h97artqddkj3c8se2yu4nxu59clq8rhj945jc0s5excpr
AGE-SECRET-KEY-1DE3V6V0ZLLZ45A7GA77M79CTN4LZQMTRCURP8VRGNLV6T2FSZEEQXUW2EU
AGEEOF

# 3. Set environment variable (PowerShell)
# Run this in PowerShell (not Git Bash):
[Environment]::SetEnvironmentVariable("SOPS_AGE_KEY_FILE", "$env:USERPROFILE\.config\sops\age\keys.txt", "User")

# 4. Add vault_path to identity.json
# Edit C:\claudetools\.claude\identity.json
# Add: "vault_path": "D:/vault"

# 5. Fix line endings if needed
dos2unix /d/vault/scripts/vault.sh
chmod +x /d/vault/scripts/vault.sh

# 6. Test
bash C:/claudetools/.claude/skills/remediation-tool/scripts/get-token.sh grabblaw.com investigator

---

References

• SOPS: https://github.com/mozilla/sops
• age: https://github.com/FiloSottile/age
• Vault repo: http://172.16.3.20:3000/azcomputerguru/vault
• ClaudeTools repo: http://172.16.3.20:3000/azcomputerguru/claudetools

---

Last tested: 2026-04-21 on Mikes-MacBook-Air.local Status: Complete and validated - all 4 tiers working Maintainer: Mike Swanson