# 🏗️ Klaus Proxy Local - Architecture Deep Dive
## System Overview
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Code Client │
│ (with HTTPS_PROXY env) │
└────────────────────────┬────────────────────────────────────┘
│ HTTPS://api.anthropic.com
│ (intercept & pseudonymize)
▼
┌──────────────────────────────────────────────────────────────┐
│ Klaus Proxy Local (mitmproxy + addons) │
│ mitmdump -p 8899 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Addon: anthropic_payload_pseudonymize.py │ │
│ │ - Bidirectional vault (real ↔ pseudo) │ │
│ │ - Salt-based deterministic hashing │ │
│ │ - Request: real → pseudo │ │
│ │ - Response: pseudo → real │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Addon: anthropic_payload_capture.py │ │
│ │ - Captures original/ and sent/ pairs │ │
│ │ - Stores in captures/ directory │ │
│ │ - Enables audit trail │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Addon: sensitive_data_scanner.py │ │
│ │ - Tier 1: Pattern detection (20+ patterns) │ │
│ │ - Tier 2: Contextual detection (JSON, vars) │ │
│ │ - Tier 3: Heuristic (entropy, diversity) │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│ Anthropic API response
│ (already reverted by addon)
▼
┌──────────────────────────────────────────────────────────────┐
│ Claude Code Client (response handling) │
│ Tool calls work with REAL values │
└──────────────────────────────────────────────────────────────┘
```
## Core Components
### 1. Pseudonymization Engine (`anthropic_payload_pseudonymize.py`)
**Design:**
- Bidirectional vault: `real ↔ pseudo` mapping
- Deterministic hashing: hash(salt + value)
- Salt-based (ANTHROPIC_PSEUDO_SALT environment)
**Key Classes:**
- `Vault`: In-memory + persistent JSON mapping
- `PseudonymizationRules`: Regex + path rules
- Functions: `pseudonymize_text()`, `restore_text()`
**Flow:**
```
Request (real values)
↓ [apply rules + hash]
Pseudonymized payload → Anthropic/gateway
↓ [response]
Reverse vault (pseudo → real)
↓ [restore all values]
Response (real values) → Claude Code
```
### 2. Sensitive Data Scanner (`sensitive_data_scanner.py`)
**Three Detection Tiers:**
**Tier 1: Pattern-Based (CRITICAL confidence)**
- 20+ regex patterns for known secret formats
- AWS keys: `AKIA[0-9A-Z]{16}`
- GitHub tokens: `gh[pousr]_[A-Za-z0-9]{36,}`
- Private keys, URLs, emails, IPs, etc.
- **False positive rate:** ~0%
**Tier 2: Contextual (HIGH confidence)**
- Variable names: `password=`, `api_key:`, `token:`
- File types: `.env`, `.credentials`, `.pem`
- JSON keys: `"password": "xxx"`
- **False positive rate:** ~5%
**Tier 3: Heuristic (MEDIUM confidence)**
- Shannon entropy analysis (> 4.5 bits/char)
- Character diversity (mixed charset)
- Length heuristics (8-64 chars)
- **False positive rate:** ~30% (review needed)
### 3. Capture & Audit (`anthropic_payload_capture.py`)
**Structure:**
```
captures/
├── original/
│ ├── 20260903_120000_payload_001.json (real values)
│ └── ...
├── sent/
│ ├── 20260903_120000_payload_001.json (pseudonymized)
│ └── ...
├── .pseudonym_vault.json (mapping)
└── scan_results.json (findings)
```
**Purpose:**
- Immutable audit trail
- Enables forensics & compliance
- **Never versioned** (gitignored)
### 4. Zero-Config Setup (`launcher.py`, `setup.py`, `setup_shell.py`)
**Auto-setup sequence:**
1. Check for config → generate if missing
2. Check for TLS certs → generate if missing
3. Detect shell → add proxy env vars
4. Start mitmproxy with addons
5. Show dashboard with URLs
## Data Flow Examples
### Example 1: Request Pseudonymization
```python
# Input (Claude Code → Proxy)
{
"messages": [
{
"content": "Read /home/alice/project/secrets.txt"
}
]
}
# After pseudonymization (Proxy → Anthropic)
{
"messages": [
{
"content": "Read /proj_a1b2c3d4/secrets.txt"
}
]
}
# Vault mapping
{
"/home/alice/project": "/proj_a1b2c3d4",
"alice": "/user_x9y8z7w6"
}
```
### Example 2: Response Restoration
```python
# Input (Anthropic → Proxy)
{
"tool_calls": [
{
"arguments": "path: /proj_a1b2c3d4/file.txt"
}
]
}
# After restoration (Proxy → Claude Code)
{
"tool_calls": [
{
"arguments": "path: /home/alice/project/file.txt"
}
]
}
# Tool execution works with REAL paths!
```
## Security Guarantees
### ✅ Guaranteed
1. **No plaintext secrets in transit** (pseudonymized)
2. **Deterministic mapping** (same value → same pseudo)
3. **Immutable audit trail** (captures/)
4. **Fail-closed** (no request if pseudonymization fails)
5. **Salt-based** (unpredictable without ANTHROPIC_PSEUDO_SALT)
### ⚠️ Assumptions
1. ANTHROPIC_PSEUDO_SALT kept secret
2. captures/ directory kept private
3. Proxy runs on localhost:8899
4. TLS certs from ~/.mitmproxy/ trusted
## Performance Characteristics
| Operation | Latency | Throughput |
|-----------|---------|-----------|
| Pseudonymize request | ~5ms | 200/sec |
| Restore response | ~2ms | 500/sec |
| Scan payload (Tier 1-3) | ~50ms | 20/sec |
| Vault lookup | <1ms | >1000/sec |
**Optimization opportunities for v0.4.0:**
- Vault caching (in-memory LRU)
- Parallel scanning tiers
- Batch pseudonymization