claudetools/INITIAL_DATA.md

ClaudeTools Initial Data Specification

Created: 2026-01-15 Purpose: Document all initial data and configuration required BEFORE implementation begins Status: Planning - Ready for implementation

---

1. Database Deployment

Recommended Host: Jupiter (172.16.3.20)

Rationale:

• Existing MariaDB infrastructure (already hosting GuruRMM database)
• 24/7 uptime (primary Unraid server)
• Internal network access (172.16.0.0/16)
• Backed by Unraid array
• Accessible via VPN (Tailscale network)
• Proven reliability

Alternative: Build Server (172.16.3.30)

• Also has PostgreSQL for GuruConnect
• Less critical if down (not primary infrastructure)
• Decision: Use Jupiter for centralized database management

Database Configuration

Database Details:

• Host: 172.16.3.20
• Port: 3306 (MariaDB default)
• Database Name: claudetools
• Character Set: utf8mb4
• Collation: utf8mb4_unicode_ci

Connection String:

# Python (SQLAlchemy)
DATABASE_URL = "mysql+pymysql://claudetools:{password}@172.16.3.20:3306/claudetools?charset=utf8mb4"

# Python (direct)
import pymysql
conn = pymysql.connect(
    host='172.16.3.20',
    port=3306,
    user='claudetools',
    password='{password}',
    database='claudetools',
    charset='utf8mb4'
)

User Credentials (To Be Generated)

Database User: claudetools Password: CT_$(openssl rand -hex 16) Example: CT_a7f82d1e4b9c3f60e8d4a2b9c1f3e5d7

Privileges:

CREATE DATABASE IF NOT EXISTS claudetools CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'claudetools'@'%' IDENTIFIED BY '{generated_password}';
GRANT ALL PRIVILEGES ON claudetools.* TO 'claudetools'@'%';
FLUSH PRIVILEGES;

Storage Location: C:\Users\MikeSwanson\claude-projects\shared-data\credentials.md

Entry Format:

### ClaudeTools Database (MariaDB on Jupiter)
- **Host:** 172.16.3.20
- **Port:** 3306
- **Database:** claudetools
- **User:** claudetools
- **Password:** {generated_password}
- **Notes:** Created 2026-01-15, MSP tracking database

---

2. Current Machine Profile

Detected Machine Information

Hostname: ACG-M-L5090 Username: AzureAD+MikeSwanson (Azure AD joined) Platform: Win32NT (Windows) OS Version: Windows 11 (build 26100) Home Directory: C:\Users\MikeSwanson PowerShell Version: 5.1.26100.7019

Network Access

VPN Status: Connected (Tailscale) Access Verified:

• Jupiter (172.16.3.20): [OK] Accessible
• Build Server (172.16.3.30): [OK] Accessible
• pfSense (172.16.0.1): Accessible via SSH port 2248
• Internal network (172.16.0.0/16): [OK] Full access

Tailscale Network:

• This machine: 100.125.36.6 (acg-m-l5090)
• Gateway: 100.79.69.82 (pfsense-1)
• Subnet routes: 172.16.0.0/16

Docker Availability

Status: [ERROR] Not installed on Windows host Note: Not needed for ClaudeTools (API runs on Jupiter Docker)

Machine Fingerprint

Generated Fingerprint:

machine_id: ACG-M-L5090-WIN32NT-MIKESWANSON
platform: windows
os_version: 26100
architecture: x64 (assumed)
tailscale_ip: 100.125.36.6
vpn_network: 172.16.0.0/16
primary_user: MikeSwanson
home_dir: C:\Users\MikeSwanson
powershell_version: 5.1.26100.7019

Storage Format (for database):

{
  "hostname": "ACG-M-L5090",
  "username": "MikeSwanson",
  "platform": "windows",
  "os_version": "26100",
  "home_directory": "C:\\Users\\MikeSwanson",
  "powershell_version": "5.1.26100.7019",
  "tailscale_ip": "100.125.36.6",
  "vpn_access": true,
  "docker_available": false,
  "last_seen": "2026-01-15T00:00:00Z"
}

---

3. Client Data (from credentials.md)

MSP Clients to Import

Total Clients: 8 active + 1 potential

1. Dataforth

• Status: Active
• Network: 192.168.0.0/24
• Domain: INTRANET (intranet.dataforth.com)
• Key Infrastructure:
  • UDM (192.168.0.254) - UniFi gateway/firewall
  • AD1 (192.168.0.27) - Primary DC, NPS/RADIUS
  • AD2 (192.168.0.6) - Secondary DC, file server
  • D2TESTNAS (192.168.0.9) - SMB1 proxy for DOS machines
• M365 Tenant: dataforth tenant (7dfa3ce8-c496-4b51-ab8d-bd3dcd78b584)
• Notable: ~30 DOS 6.22 QC machines (custom SMB1 setup)

2. Grabb & Durando (Law Firm)

• Status: Active
• Network: Unknown (VPN access via IX server)
• Key Infrastructure:
  • data.grabbanddurando.com - Custom web app on IX server
  • Database: MariaDB on IX (grabblaw_gdapp_data)
• Notable: Calendar/user management web application

3. Valley Wide Plastering (VWP)

• Status: Active
• Network: 172.16.9.0/24
• Key Infrastructure:
  • UDM (172.16.9.1) - UniFi gateway/firewall
  • VWP-DC1 (172.16.9.2) - Primary DC, NPS/RADIUS
• VPN: RADIUS authentication configured (2025-12-22)

4. BG Builders LLC

• Status: Active
• M365 Tenant: bgbuildersllc.com (ededa4fb-f6eb-4398-851d-5eb3e11fab27)
• CIPP Name: sonorangreenllc.com
• Admin: sysadmin@bgbuildersllc.com
• Notable: Security incident resolved 2025-12-22 (compromised user Shelly@bgbuildersllc.com)

5. CW Concrete LLC

• Status: Active
• M365 Tenant: cwconcretellc.com (dfee2224-93cd-4291-9b09-6c6ce9bb8711)
• Default Domain: NETORGFT11452752.onmicrosoft.com
• Notable: De-federated from GoDaddy 2025-12, security incident resolved 2025-12-22

6. Khalsa

• Status: Active
• Network: 172.16.50.0/24
• Key Infrastructure:
  • UCG (172.16.50.1) - UniFi Cloud Gateway
  • Accountant Machine (172.16.50.168)
• Notable: VPN routing issue

7. Scileppi Law Firm

• Status: Active
• Key Infrastructure:
  • DS214se (172.16.1.54) - Source NAS (1.8TB, migration complete)
  • Unraid (172.16.1.21) - Source (migration complete)
  • RS2212+ (172.16.1.59) - Destination NAS (25TB, 6.9TB used)
• Notable: Major NAS migration completed 2025-12-29

8. MVAN Inc

• Status: Active
• M365 Tenant: mvan.onmicrosoft.com
• Admin: sysadmin@mvaninc.com
• Notable: Tenant merger project pending

9. Glaztech Industries (GLAZ)

• Status: Test/Demo client (for GuruRMM)
• Client ID: d857708c-5713-4ee5-a314-679f86d2f9f9
• Site: SLC - Salt Lake City
• Site Code: DARK-GROVE-7839
• API Key: grmm_Qw64eawPBjnMdwN5UmDGWoPlqwvjM7lI

Database Import Structure

-- Example client entries
INSERT INTO clients (client_id, name, status, notes) VALUES
(UUID(), 'Dataforth', 'active', 'DOS machines, custom SMB1 proxy'),
(UUID(), 'Grabb & Durando', 'active', 'Law firm, custom web app'),
(UUID(), 'Valley Wide Plastering', 'active', 'VPN RADIUS setup'),
(UUID(), 'BG Builders LLC', 'active', 'M365 security incident 2025-12-22'),
(UUID(), 'CW Concrete LLC', 'active', 'De-federated from GoDaddy'),
(UUID(), 'Khalsa', 'active', 'VPN routing issue'),
(UUID(), 'Scileppi Law Firm', 'active', 'NAS migration completed'),
(UUID(), 'MVAN Inc', 'active', 'Tenant merger pending'),
(UUID(), 'Glaztech Industries', 'test', 'GuruRMM test client');

---

4. Project Data (from session logs & repos)

Internal Projects (azcomputerguru organization)

1. GuruRMM (Custom RMM System)

• Gitea Repo: azcomputerguru/gururmm
• Status: Active development
• Location: C:\Users\MikeSwanson\claude-projects\gururmm\
• Components:
  • gururmm-server (Rust API)
  • gururmm-dashboard (React)
  • gururmm-agent (Rust, cross-platform)
• Infrastructure:
  • API: https://rmm-api.azcomputerguru.com (172.16.3.20:3001)
  • Database: PostgreSQL on Jupiter (gururmm-db container)
  • Build Server: 172.16.3.30
• Technologies: Rust, React, PostgreSQL, Docker, JWT, SSO

2. GuruConnect (Remote Access System)

• Gitea Repo: azcomputerguru/guru-connect
• Status: Active
• Location: C:\Users\MikeSwanson\claude-projects\guru-connect\
• Infrastructure:
  • Server: Build Server (172.16.3.30)
  • Database: PostgreSQL (local on build server)
  • Static files: /home/guru/guru-connect/server/static/
• Technologies: Rust, WebSockets, PostgreSQL

3. ClaudeTools (This Project)

• Gitea Repo: azcomputerguru/claudetools (to be created)
• Status: Planning phase
• Location: D:\ClaudeTools\
• Purpose: Custom Claude Code modes for MSP tracking
• Technologies: Python, FastAPI, SQLAlchemy, MariaDB, JWT

4. claude-projects (Meta Repository)

• Gitea Repo: azcomputerguru/claude-projects
• Status: Active
• Location: C:\Users\MikeSwanson\claude-projects\
• Contents:
  • .claude/ - Commands, settings, templates
  • shared-data/ - credentials.md
  • session-logs/ - 37+ session logs
  • CLAUDE.md - Project guidance

5. ai-3d-printing

• Gitea Repo: azcomputerguru/ai-3d-printing
• Status: Active
• Technologies: OpenSCAD, Bambu Lab P1S

Database Import Structure

INSERT INTO projects (project_id, name, client_id, type, status, repo_url, technologies, notes) VALUES
(UUID(), 'GuruRMM', NULL, 'internal_product', 'active', 'git@git.azcomputerguru.com:azcomputerguru/gururmm.git', 'Rust,React,PostgreSQL', 'Custom RMM system'),
(UUID(), 'GuruConnect', NULL, 'internal_product', 'active', 'git@git.azcomputerguru.com:azcomputerguru/guru-connect.git', 'Rust,WebSockets', 'Remote access system'),
(UUID(), 'ClaudeTools', NULL, 'dev_tool', 'planning', 'git@git.azcomputerguru.com:azcomputerguru/claudetools.git', 'Python,FastAPI,MariaDB', 'MSP tracking modes'),
(UUID(), 'claude-projects', NULL, 'infrastructure', 'active', 'git@git.azcomputerguru.com:azcomputerguru/claude-projects.git', 'Markdown', 'Meta repository'),
(UUID(), 'ai-3d-printing', NULL, 'internal_project', 'active', 'git@git.azcomputerguru.com:azcomputerguru/ai-3d-printing.git', 'OpenSCAD', '3D printing models');

---

5. Infrastructure Inventory (from credentials.md)

MSP Infrastructure (Owned & Managed)

Core Servers

Jupiter (172.16.3.20)

• Type: server
• OS: Unraid 6.x
• Role: Primary container host
• Services: Gitea, NPM, GuruRMM API, Seafile, MariaDB
• SSH: root@172.16.3.20:22
• Credentials: See credentials.md (root, Th1nk3r^99##)
• iDRAC: 172.16.1.73 (DHCP)

Saturn (172.16.3.21)

• Type: server
• OS: Unraid 6.x
• Role: Secondary (being decommissioned)
• Status: Migration to Jupiter complete
• SSH: root@172.16.3.21:22
• Credentials: See credentials.md (root, r3tr0gradE99)

pfSense (172.16.0.1)

• Type: firewall
• OS: FreeBSD (pfSense)
• Role: Firewall, Tailscale gateway, VPN server
• SSH: admin@172.16.0.1:2248
• Tailscale IP: 100.79.69.82 (pfsense-1)
• Subnet Routes: 172.16.0.0/16
• Credentials: See credentials.md (admin, r3tr0gradE99!!)

OwnCloud VM (172.16.3.22)

• Type: vm
• OS: Rocky Linux 9.6
• Hostname: cloud.acghosting.com
• Role: OwnCloud file sync server
• SSH: root@172.16.3.22:22
• Services: Apache, MariaDB, PHP-FPM, Redis
• Storage: SMB mount from Jupiter

Build Server (172.16.3.30)

• Type: server
• OS: Ubuntu 22.04
• Hostname: gururmm
• Role: GuruRMM/GuruConnect build server
• SSH: guru@172.16.3.30:22
• Services: nginx, PostgreSQL, gururmm-server, guruconnect-server
• Credentials: See credentials.md (guru, Gptf*77ttb123!@#-rmm)

Hosting Servers

IX Server (172.16.3.10)

• Type: server
• OS: CentOS 7 (WHM/cPanel)
• Hostname: ix.azcomputerguru.com
• Role: Primary cPanel hosting server
• SSH: root@ix.azcomputerguru.com:22 (VPN required)
• Internal IP: 172.16.3.10
• Credentials: See credentials.md (root, Gptf*77ttb!@#!@#)

WebSvr (websvr.acghosting.com)

• Type: server
• OS: CentOS 7 (WHM/cPanel)
• Role: Legacy hosting (migration source to IX)
• SSH: root@websvr.acghosting.com:22
• Credentials: See credentials.md (root, r3tr0gradE99#)

Client Infrastructure

Dataforth:

• UDM (192.168.0.254) - network_device, UniFi gateway
• AD1 (192.168.0.27) - server, Windows Server 2012 R2, Primary DC
• AD2 (192.168.0.6) - server, Windows Server 2012 R2, Secondary DC
• D2TESTNAS (192.168.0.9) - nas, Netgear ReadyNAS, SMB1 proxy

Valley Wide Plastering:

• UDM (172.16.9.1) - network_device, UniFi Dream Machine
• VWP-DC1 (172.16.9.2) - server, Windows Server, DC + NPS/RADIUS

Khalsa:

• UCG (172.16.50.1) - network_device, UniFi Cloud Gateway
• Accountant Machine (172.16.50.168) - workstation, Windows

Scileppi Law Firm:

• DS214se (172.16.1.54) - nas, Synology (migration complete, decommission pending)
• Unraid (172.16.1.21) - server, Unraid (migration complete, decommission pending)
• RS2212+ (172.16.1.59) - nas, Synology RS2212+ (active, 25TB)

Database Import Structure

-- Example infrastructure entries
INSERT INTO infrastructure (infra_id, client_id, site_id, name, ip_address, type, os, role, status, notes) VALUES
-- MSP Infrastructure
(UUID(), NULL, NULL, 'Jupiter', '172.16.3.20', 'server', 'Unraid', 'Primary container host', 'active', 'Gitea, NPM, GuruRMM, Seafile'),
(UUID(), NULL, NULL, 'Saturn', '172.16.3.21', 'server', 'Unraid', 'Secondary', 'decommissioned', 'Migration to Jupiter complete'),
(UUID(), NULL, NULL, 'pfSense', '172.16.0.1', 'firewall', 'FreeBSD', 'Firewall + VPN gateway', 'active', 'Tailscale gateway'),
(UUID(), NULL, NULL, 'Build Server', '172.16.3.30', 'server', 'Ubuntu 22.04', 'GuruRMM build server', 'active', 'nginx, PostgreSQL'),
(UUID(), NULL, NULL, 'IX Server', '172.16.3.10', 'server', 'CentOS 7', 'cPanel hosting', 'active', 'VPN required'),
-- Client Infrastructure (example)
(UUID(), {dataforth_id}, {dataforth_site_id}, 'AD1', '192.168.0.27', 'server', 'Windows Server 2012 R2', 'Primary DC', 'active', 'NPS/RADIUS'),
(UUID(), {dataforth_id}, {dataforth_site_id}, 'D2TESTNAS', '192.168.0.9', 'nas', 'Netgear ReadyNAS', 'SMB1 proxy', 'active', 'DOS machine access');

---

6. Environmental Insights (from session logs)

Known Technical Constraints

These are battle-tested insights that should be seeded into the problem_solutions table for future reference.

1. D2TESTNAS: Manual WINS Install

• Problem: ReadyNAS doesn't have native WINS service
• Constraint: Must install manually via SSH, custom package
• Solution: Use ReadyNAS SDK to build WINS package, install via dpkg
• Context: DOS 6.22 machines require NetBIOS/WINS for SMB1 name resolution
• Technologies: ReadyNAS, WINS, SMB1, DOS
• Date Discovered: 2025-12-14

2. Server 2008: PowerShell 2.0 Limitations

• Problem: Windows Server 2008 ships with PowerShell 2.0
• Constraint: No modern cmdlets (Invoke-WebRequest, ConvertFrom-Json, etc.)
• Solution: Use .NET methods directly or upgrade to PowerShell 5.1
• Context: Many client DCs still run Server 2008 R2
• Technologies: PowerShell, Windows Server 2008
• Date Discovered: Multiple sessions

3. DOS 6.22: SMB1 Only, NetBIOS Required

• Problem: DOS 6.22 machines can only use SMB1 protocol
• Constraint: Modern Windows/NAS disable SMB1 by default (security risk)
• Solution: Dedicated SMB1 proxy (ReadyNAS) with WINS server
• Context: Dataforth has ~30 DOS QC machines that must access network shares
• Technologies: DOS 6.22, SMB1, NetBIOS, WINS
• Date Discovered: 2025-12-14

4. Elasticsearch 7.16.2 + Kernel 6.12 Incompatibility

• Problem: Elasticsearch 7.16.2 fails on Linux kernel 6.12+
• Constraint: Kernel syscall changes break older ES versions
• Solution: Upgrade to Elasticsearch 7.17.26 (latest 7.x)
• Context: Seafile migration to Jupiter hit this issue
• Technologies: Elasticsearch, Linux kernel, Docker
• Date Discovered: 2025-12-27

5. pfSense: Tailscale Reinstall After Upgrade

• Problem: pfSense package upgrades can break Tailscale
• Constraint: Tailscale package not always compatible with new pfSense versions
• Solution: Uninstall, reinstall Tailscale, re-enable subnet routes
• Context: Happened after pfSense 2.7 upgrade
• Technologies: pfSense, Tailscale, VPN
• Date Discovered: 2025-12-12, 2025-12-26

6. MariaDB: Strict Mode + Django

• Problem: Django CSRF_TRUSTED_ORIGINS requires list format
• Constraint: MariaDB strict mode rejects invalid data types
• Solution: Use JSON list format: ["https://sync.azcomputerguru.com"]
• Context: Seafile (Django 4.x) migration to Jupiter
• Technologies: MariaDB, Django, Seafile
• Date Discovered: 2025-12-27

7. NPM Proxy: CSRF Header Stripping

• Problem: NPM (Nginx Proxy Manager) strips some headers
• Constraint: Django applications require CSRF_TRUSTED_ORIGINS config
• Solution: Add domain to Django CSRF settings, not NPM config
• Context: Multiple Django apps behind NPM
• Technologies: NPM, Nginx, Django
• Date Discovered: Multiple sessions

8. GuruRMM: Sudo -S Password Input Issues

• Problem: Special characters in password break sudo -S echo piping
• Constraint: Bash escaping conflicts with special chars like *!@#
• Solution: Run services as non-root user (guru), use pkill instead of sudo systemctl
• Context: Build server deployment automation
• Technologies: Bash, sudo, systemd
• Date Discovered: 2025-12-21

9. Azure AD Join: Username Format

• Problem: Azure AD joined machines have AzureAD+ prefix in usernames
• Constraint: Some scripts expect simple usernames
• Solution: Strip prefix or use environment variables
• Context: This machine (ACG-M-L5090)
• Technologies: Azure AD, Windows
• Date Discovered: 2026-01-15

Database Import Structure

INSERT INTO problem_solutions (problem_id, title, symptom, root_cause, solution, verification, technologies, date_discovered, notes) VALUES
(UUID(), 'ReadyNAS WINS Installation', 'DOS machines cannot resolve NetBIOS names', 'ReadyNAS lacks native WINS service', 'Build custom WINS package using ReadyNAS SDK, install via dpkg', 'DOS machines can ping by name', 'ReadyNAS,WINS,SMB1,DOS', '2025-12-14', 'Required for Dataforth DOS 6.22 QC machines'),
(UUID(), 'PowerShell 2.0 Cmdlet Limitations', 'Modern PowerShell cmdlets not available on Server 2008', 'Server 2008 ships with PowerShell 2.0 only', 'Use .NET methods directly or upgrade to PowerShell 5.1', 'Commands run successfully', 'PowerShell,Windows Server 2008', '2025-12-01', 'Many client DCs still on Server 2008 R2'),
(UUID(), 'DOS SMB1 Network Access', 'DOS 6.22 machines cannot access modern file shares', 'DOS only supports SMB1, disabled by default on modern systems', 'Deploy dedicated SMB1 proxy (ReadyNAS) with WINS', 'DOS machines can map network drives', 'DOS 6.22,SMB1,NetBIOS,WINS', '2025-12-14', '~30 Dataforth QC machines affected'),
(UUID(), 'Elasticsearch Kernel 6.12 Crash', 'Elasticsearch 7.16.2 crashes on startup', 'Kernel 6.12+ syscall changes incompatible with ES 7.16.x', 'Upgrade to Elasticsearch 7.17.26', 'Elasticsearch starts successfully, no errors in logs', 'Elasticsearch,Linux kernel,Docker', '2025-12-27', 'Seafile migration issue'),
(UUID(), 'Tailscale pfSense Package Failure', 'Tailscale stops working after pfSense upgrade', 'Package incompatibility with new pfSense version', 'Uninstall and reinstall Tailscale, re-enable subnet routes', 'VPN clients can reach internal networks', 'pfSense,Tailscale,VPN', '2025-12-26', 'Recurring issue after upgrades'),
(UUID(), 'Django CSRF Trusted Origins Format', 'Django returns CSRF verification failed', 'CSRF_TRUSTED_ORIGINS requires list format in Django 4.x', 'Use JSON list: ["https://domain.com"]', 'Application loads without CSRF errors', 'Django,MariaDB,Seafile', '2025-12-27', 'Affects all Django apps'),
(UUID(), 'NPM Proxy Header Stripping', 'Django apps fail CSRF check behind NPM', 'NPM strips some HTTP headers', 'Configure CSRF_TRUSTED_ORIGINS in Django, not NPM', 'Application accepts requests from proxied domain', 'NPM,Nginx,Django', '2025-12-20', 'Multiple apps affected'),
(UUID(), 'Sudo Password Special Characters', 'sudo -S fails with password containing special chars', 'Bash escaping conflicts with *!@# characters', 'Run services as non-root user, use pkill instead of sudo', 'Services restart successfully without sudo', 'Bash,sudo,systemd', '2025-12-21', 'Build server automation'),
(UUID(), 'Azure AD Join Username Prefix', 'Scripts fail with AzureAD+ username prefix', 'Azure AD joined machines prefix usernames', 'Strip prefix or use %USERNAME% environment variable', 'Scripts run successfully', 'Azure AD,Windows', '2026-01-15', 'This machine affected');

---

7. Credential Encryption

Encryption Strategy

Algorithm: AES-256-GCM (Galois/Counter Mode)

• Authenticated encryption (prevents tampering)
• 256-bit key strength
• Unique IV per credential
• Authentication tag included

Key Derivation: PBKDF2 with random salt

• 100,000 iterations (OWASP recommendation)
• SHA-256 hash function
• 32-byte salt per master key

Encryption Key Generation

Master Key Generation:

# Generate 256-bit (32-byte) encryption key
openssl rand -hex 32
# Example output: a7f82d1e4b9c3f60e8d4a2b9c1f3e5d7b4a8c6e2f9d1a3b5c7e9f0d2a4b6c8e0

Storage Location: C:\Users\MikeSwanson\claude-projects\shared-data\.encryption-key

Key File Format:

# ClaudeTools Encryption Key
# Generated: 2026-01-15
# DO NOT COMMIT TO GIT
ENCRYPTION_KEY=a7f82d1e4b9c3f60e8d4a2b9c1f3e5d7b4a8c6e2f9d1a3b5c7e9f0d2a4b6c8e0

Gitignore Entry:

# Add to .gitignore
.encryption-key
*.key

Backup Location: Manual backup to secure location (NOT in Git)

Credentials to Import Initially

Priority 1: MSP Infrastructure (Owned)

• Jupiter (root, webui, iDRAC)
• Saturn (root)
• pfSense (admin)
• Build Server (guru)
• OwnCloud VM (root)
• IX Server (root)
• WebSvr (root)

Priority 2: Services

• Gitea (mike@azcomputerguru.com)
• NPM (mike@azcomputerguru.com)
• GuruRMM Dashboard (admin@azcomputerguru.com)
• Seafile (mike@azcomputerguru.com)

Priority 3: Client Infrastructure

• Dataforth: UDM, AD1, AD2, D2TESTNAS
• VWP: UDM, VWP-DC1
• Khalsa: UCG
• Scileppi: RS2212+

Priority 4: API Tokens

• Gitea API Token
• Cloudflare API Token
• SyncroMSP API Key
• Autotask API Credentials
• CIPP API Client (ClaudeCipp2)

Priority 5: Database Connections

• GuruRMM PostgreSQL
• GuruConnect PostgreSQL
• ClaudeTools MariaDB (after creation)

Encryption Format in Database

-- credentials table structure
CREATE TABLE credentials (
    credential_id CHAR(36) PRIMARY KEY,
    client_id CHAR(36),
    site_id CHAR(36),
    service_id CHAR(36),
    credential_type ENUM('password', 'api_key', 'oauth', 'ssh_key', ...),
    username VARCHAR(255),
    encrypted_value BLOB NOT NULL,  -- AES-256-GCM encrypted
    iv BINARY(16) NOT NULL,          -- Initialization Vector
    auth_tag BINARY(16) NOT NULL,    -- GCM authentication tag
    url VARCHAR(512),
    port INT,
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    expires_at TIMESTAMP NULL,
    last_accessed TIMESTAMP NULL,
    FOREIGN KEY (client_id) REFERENCES clients(client_id),
    INDEX idx_client_service (client_id, service_id)
);

Encryption Process:

1. Generate random IV (16 bytes)
2. Encrypt credential with AES-256-GCM using master key + IV
3. Store encrypted_value, IV, and auth_tag in database
4. Never store plaintext credentials

Decryption Process:

1. Retrieve encrypted_value, IV, auth_tag from database
2. Verify auth_tag (prevents tampering)
3. Decrypt using master key + IV
4. Log access to credential_audit_log
5. Return plaintext credential (only in memory, never stored)

---

8. API Deployment Details

Recommended Host: Jupiter (172.16.3.20)

Rationale:

• Same host as database (low latency)
• Existing Docker infrastructure
• NPM already configured for proxying
• 24/7 uptime
• Internal + external access

Docker Container Configuration

Container Name: claudetools-api Image: python:3.11-slim (base) + custom Dockerfile Network: Bridge (access to host MariaDB) Restart Policy: always

Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Non-root user
RUN useradd -m -u 1000 apiuser && chown -R apiuser:apiuser /app
USER apiuser

# Expose port
EXPOSE 8000

# Run with uvicorn
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt:

fastapi==0.109.0
uvicorn[standard]==0.27.0
sqlalchemy==2.0.25
pymysql==1.1.0
cryptography==41.0.7
pyjwt==2.8.0
python-multipart==0.0.6
pydantic==2.5.3
pydantic-settings==2.1.0
alembic==1.13.1

Port Assignment

Internal Port: 8000 (standard FastAPI/uvicorn) External Port: Via NPM proxy (443 → 8000)

Docker Run Command:

docker run -d \
  --name claudetools-api \
  --restart always \
  -p 8000:8000 \
  -v /mnt/user/appdata/claudetools/logs:/app/logs \
  -e DATABASE_URL="mysql+pymysql://claudetools:{password}@172.16.3.20:3306/claudetools" \
  -e ENCRYPTION_KEY="{encryption_key}" \
  -e JWT_SECRET="{jwt_secret}" \
  claudetools-api:latest

Nginx Proxy Configuration (NPM)

Proxy Host Settings:

• Domain: claudetools-api.azcomputerguru.com
• Scheme: http
• Forward Hostname / IP: 172.16.3.20
• Forward Port: 8000
• Websockets Support: No (REST API only)
• Block Common Exploits: Yes
• SSL Certificate: npm-claudetools (Let's Encrypt)

Custom Nginx Config:

# Add to Advanced tab in NPM
location / {
    proxy_pass http://172.16.3.20:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Timeouts for long-running queries
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

Cloudflare DNS Entry:

Type: A
Name: claudetools-api
Content: {external_ip}
Proxy: Yes (Orange cloud)
TTL: Auto

API Base URL

External: https://claudetools-api.azcomputerguru.com Internal: http://172.16.3.20:8000

Usage from ClaudeTools:

# .claudetools/config.json
{
    "api_url": "https://claudetools-api.azcomputerguru.com",
    "api_internal_url": "http://172.16.3.20:8000",
    "use_internal": true  # When on VPN
}

JWT Secret Generation

Generate Secret:

openssl rand -base64 32
# Example: ZNzGxghru2XUdBVlaf2G2L1YUBVcl5xH0lr/Gpf/QmE=

Storage: Environment variable in Docker container + .claudetools/config.json (encrypted)

API Authentication Flow

1. Initial Setup:

   • Admin creates user via database insert (username, hashed password)
   • User credentials stored in credentials.md (for reference)

2. Token Request:

   curl -X POST https://claudetools-api.azcomputerguru.com/auth/token \
     -H "Content-Type: application/json" \
     -d '{"username":"mike","password":"..."}'
   

3. Token Response:

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "token_type": "bearer",
     "expires_in": 3600
   }
   

4. API Request:

   curl https://claudetools-api.azcomputerguru.com/api/sessions \
     -H "Authorization: Bearer {access_token}"
   

5. Token Storage: .claudetools/tokens.json (encrypted with encryption key)

Security Configuration

CORS: Restrict to specific origins

# main.py
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://claudetools-api.azcomputerguru.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)

Rate Limiting: slowapi library

from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address, default_limits=["100/minute"])
app.state.limiter = limiter

HTTPS Only: Force HTTPS via NPM (SSL required)

---

9. Initial Database Seeding Plan

Phase 1: Core Setup

1. Create database and user
2. Run Alembic migrations (30 tables)
3. Verify schema integrity

Phase 2: Reference Data

1. Tags: Insert 157+ pre-identified tags
2. Infrastructure: Insert MSP infrastructure (Jupiter, Saturn, pfSense, etc.)
3. Services: Insert core services (Gitea, NPM, GuruRMM, etc.)
4. Networks: Insert known network segments

Phase 3: Client Data

1. Clients: Insert 8 active MSP clients
2. Sites: Create client sites (where applicable)
3. Client Infrastructure: Insert client servers, network devices
4. M365 Tenants: Insert known Microsoft 365 tenants

Phase 4: Projects

1. Insert internal projects (GuruRMM, GuruConnect, ClaudeTools, etc.)
2. Link projects to repositories

Phase 5: Problem Solutions

1. Insert 9 known problem/solution patterns from session logs

Phase 6: Credentials (Encrypted)

1. Generate encryption key
2. Encrypt and insert Priority 1 credentials (MSP infrastructure)
3. Verify encryption/decryption cycle
4. Insert Priority 2-5 credentials

Phase 7: Machine Registration

1. Register current machine (ACG-M-L5090)
2. Generate machine fingerprint
3. Link to user account

Seeding Scripts

Location: D:\ClaudeTools\seeding\

Files to Create:

• 01_tags.sql - 157+ tags
• 02_infrastructure.sql - MSP servers, services, networks
• 03_clients.sql - 8 clients + sites
• 04_projects.sql - 5 internal projects
• 05_problem_solutions.sql - 9 known solutions
• 06_credentials.py - Encrypted credential insertion (Python script)
• 07_machine_registration.py - Current machine profile

---

10. Summary Checklist

Before Implementation Starts

• Generate database user password (CT_[random])
• Add credentials to shared-data/credentials.md
• Generate encryption key (256-bit)
• Store encryption key in shared-data/.encryption-key
• Add .encryption-key to .gitignore
• Generate JWT secret (base64 32 bytes)
• Create database on Jupiter MariaDB
• Grant user privileges
• Test database connection from Windows machine
• Create D:\ClaudeTools\seeding\ directory
• Prepare seeding SQL scripts
• Create Dockerfile for API
• Configure NPM proxy host
• Add Cloudflare DNS entry
• Create Gitea repository (azcomputerguru/claudetools)

Data to Seed

• 157+ tags (5 categories)
• 8 MSP clients
• 5 internal projects
• 10+ MSP infrastructure items
• 20+ client infrastructure items
• 9 known problem solutions
• 50+ credentials (encrypted, phased)
• Current machine profile

API Deployment

• Build Docker image
• Deploy container on Jupiter
• Configure environment variables
• Test API health endpoint
• Configure NPM proxy
• Test external access (https://claudetools-api.azcomputerguru.com)
• Create initial admin user
• Generate and test JWT tokens
• Verify authentication flow

---

11. Storage Estimates

Database Size (Year 1):

• Tables + indexes: ~100 MB
• Sessions (500-1000): ~50 MB
• Work items (5,000-10,000): ~200 MB
• Commands/files: ~100 MB
• Credentials (encrypted): ~10 MB
• Audit logs: ~100 MB
• Total: ~500 MB - 1 GB

Growth Rate: ~1 GB/year (conservative estimate)

5-Year Storage: ~5 GB (negligible for Jupiter Unraid array)

---

12. Dependencies

Python Packages (API)

• fastapi (web framework)
• uvicorn (ASGI server)
• sqlalchemy (ORM)
• pymysql (MariaDB driver)
• cryptography (AES encryption)
• pyjwt (JWT tokens)
• alembic (database migrations)
• pydantic (validation)

Infrastructure Requirements

• MariaDB 10.6+ (already on Jupiter)
• Docker (already on Jupiter)
• NPM (already on Jupiter)
• Python 3.11+ (for API)

Network Requirements

• VPN access (Tailscale) - [OK] Already configured
• Internal network access (172.16.0.0/16) - [OK] Already accessible
• External domain (claudetools-api.azcomputerguru.com) - To be configured

---

Change Log

• 2026-01-15: Initial data specification created
  • Documented database deployment (Jupiter MariaDB)
  • Detected current machine profile (ACG-M-L5090)
  • Extracted 8 MSP clients from credentials.md
  • Identified 5 internal projects from session logs
  • Catalogued 10+ MSP infrastructure items
  • Documented 9 known problem solutions
  • Planned credential encryption strategy (AES-256-GCM)
  • Designed API deployment (Jupiter Docker + NPM)
  • Created initial seeding plan

---

Status: Ready for implementation phase Next Step: Review and approve this specification, then begin implementation