# TrustShield Security & Transparency Platform — Design Document

**Date**: 2026-02-22
**Status**: Approved
**Issues**: #122, #123, #124 + new security pillars
**Branch**: `feature/trustshield-security`

---

## Problem

LLMHosts.com runs on users' personal machines with GPU access. This creates three trust challenges:

1. **Inbound threat**: Malicious prompts (injection, jailbreak, data exfiltration) flowing through our proxy to LLM backends
2. **Outbound trust**: Users need proof that LLMHosts isn't snooping, phoning home, or misusing their GPU
3. **Compliance gap**: Missing controls for SOC 2, FedRAMP, HIPAA, GDPR, PCI-DSS readiness

## Solution: 5 Pillars

### Pillar 1: PromptGuard — Prompt Injection Defense

**File**: `llmhosts/security/prompt_guard.py`

Configurable middleware scanning every prompt before it reaches any LLM backend.

**Detection tiers**:
- **Tier 1 — Rule-based** (<1ms): Regex patterns for known injection signatures
  - "ignore previous instructions", "you are now", "system prompt:", "ADMIN OVERRIDE"
  - Role hijacking: "act as", "pretend you are", "your new role"
  - Data exfiltration: "repeat everything above", "show me your instructions", "what was the system prompt"
  - Encoding attacks: base64-encoded instructions, unicode homoglyphs, zero-width characters
  - Delimiter injection: markdown/XML/JSON breaking patterns
- **Tier 2 — Heuristic** (<5ms): Statistical analysis
  - Instruction-to-data ratio (high instruction density = suspicious)
  - Entropy analysis (encoded payloads have distinctive entropy)
  - Language switching (sudden shift to instruction-like content mid-prompt)
  - Nested instruction detection (instructions within data fields)

**Scoring**: Each prompt gets:
- `threat_score`: 0.0-1.0 float
- `threat_categories`: list of detected categories (injection, jailbreak, data_exfil, role_hijack, encoding_attack)
- `threat_details`: human-readable explanation

**Configurable modes** (per-user in config.toml):
```toml
[security.prompt_guard]
mode = "warn"  # off | warn | block | sanitize
threshold = 0.7  # score above which action triggers
log_all = true   # log even clean prompts for audit
custom_patterns = []  # user-defined regex patterns
```

**Mode behaviors**:
- `off`: No scanning (passthrough)
- `warn`: Log + `X-LLMHosts-Threat-Score` header + dashboard alert. Request proceeds.
- `block`: Return 403 with explanation. Request never reaches backend.
- `sanitize`: Strip detected patterns, log original + sanitized, forward sanitized.

**Response headers** (always present when mode != off):
- `X-LLMHosts-Threat-Score: 0.15`
- `X-LLMHosts-Threat-Category: none` (or `injection,jailbreak`)

**Middleware position**: After auth, before PII detector and router.

---

### Pillar 2: TrustLedger — Tamper-Evident Audit (Issue #123)

**Files**: `llmhosts/audit/exporter.py`, `llmhosts/audit/hmac_chain.py`, CLI commands in `llmhosts/cli.py`

Extends existing SQLite audit logger with HMAC chain and export capabilities.

**HMAC chain**:
- Each audit entry includes `hmac` field: HMAC-SHA256 of (previous_hmac + current_entry_json)
- First entry uses HMAC of a genesis seed derived from the Fernet master key
- Chain is append-only — any modification breaks all subsequent HMACs
- Verification: `llmhosts audit verify` walks the chain and reports any breaks

**Export formats**:
- JSONL: One JSON object per line, includes HMAC chain
- CSV: Flat export for spreadsheet analysis (HMAC in final column)

**CLI commands**:
```bash
llmhost audit export --format jsonl --since 2026-02-01 --until 2026-02-22 -o audit.jsonl
llmhost audit export --format csv --event-type security -o security.csv
llmhost audit verify audit.jsonl  # Verify HMAC chain integrity
llmhost audit live                # Real-time tail of audit events
llmhost audit stats               # Summary statistics
```

**Filters**: `--since`, `--until`, `--event-type`, `--model`, `--threat-score-min`

**Aut-O T-15 compliance**:
- Structured JSON format with required fields (timestamp, event_type, user_id, session_id, resource, action, result, source_ip, correlation_id)
- UTC timestamps with millisecond precision
- Never logs PII values
- Tamper-evident via HMAC chain
- 1-year retention minimum (configurable)

---

### Pillar 3: AdaptiveShield — Smart Rate Limiting (Issue #122)

**File**: `llmhosts/security/adaptive_rate_limit.py`

Replaces token bucket with sliding window + model-aware weighting.

**Algorithm**: Sliding window counter (60-second windows)
- Tracks request count per window with sub-second granularity
- Weighted by model cost: each model has a `weight` multiplier

**Model weights** (configurable in config.toml):
```toml
[security.rate_limit]
algorithm = "sliding_window"
window_seconds = 60

[security.rate_limit.model_weights]
"gpt-4" = 4
"gpt-4-turbo" = 3
"gpt-3.5-turbo" = 1
"claude-3-opus" = 4
"claude-3-sonnet" = 2
"llama-3-70b" = 2
"llama-3-8b" = 1
default = 1
```

**Quota structure**:
- Plan-based base quota (requests per minute): free=30, pro=300, team=1000
- Model-weighted: a gpt-4 request consumes 4 units from the 300 budget
- Per-model caps (optional): `max_concurrent.gpt-4 = 5`
- Burst allowance: 1.5x base for 10-second bursts

**Headers** (on every response):
```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1708599660
X-RateLimit-Model-Weight: 4
```

**429 response**: Includes `Retry-After` header and helpful JSON body.

**Storage**: In-memory with `RateLimitBackend` protocol for future Redis swap.

---

### Pillar 4: SecureMesh — mTLS for Backend Connections (Issue #124)

**Files**: `llmhosts/security/tls_manager.py`, `llmhosts/security/mtls.py`, CLI in `llmhosts/cli.py`

mTLS between LLMHosts proxy and backend inference servers (Ollama, vLLM, remote nodes).

**Certificate management**:
```bash
llmhost tls init                    # Generate local CA + proxy server cert
llmhost tls issue --name ollama     # Issue cert for a backend
llmhost tls list                    # Show all certs with expiry
llmhost tls rotate --name ollama    # Rotate cert without downtime
llmhost tls revoke --name ollama    # Revoke a cert
```

**Storage**: `~/.config/llmhost/tls/` directory
- `ca.key`, `ca.crt` — local CA (encrypted with Fernet master key)
- `proxy.key`, `proxy.crt` — proxy server certificate
- `backends/<name>.key`, `backends/<name>.crt` — per-backend certs

**Config**:
```toml
[security.mtls]
enabled = false  # opt-in
ca_path = "~/.config/llmhost/tls/ca.crt"
cert_expiry_days = 365
auto_rotate = true
rotate_before_days = 30
```

**Verification**: Proxy validates backend cert against local CA. Backend validates proxy cert. Mutual authentication.

**Scope**: Initially for Hive Mode multi-node connections. Optional for local Ollama (localhost doesn't need mTLS, but power users can enable it).

---

### Pillar 5: TransparencyDashboard — "Nothing to Hide" User Trust

**Files**: `llmhosts/security/transparency.py`, `llmhosts/security/privacy_manifest.py`, `llmhosts/security/resource_monitor.py`

Addresses the psychological trust challenge: "I'm installing this on my personal machine — what is it doing?"

**Privacy Manifest** (`~/.config/llmhost/privacy-manifest.json`):
```json
{
  "version": "1.0",
  "generated": "2026-02-22T12:00:00Z",
  "data_collection": {
    "telemetry": false,
    "crash_reports": false,
    "usage_analytics": false,
    "note": "Zero data leaves your machine unless you explicitly configure cloud APIs or tunnels"
  },
  "network_connections": [
    {"destination": "localhost:11434", "purpose": "Ollama inference", "direction": "outbound_local"},
    {"destination": "api.openai.com", "purpose": "Cloud API (user-configured BYOK)", "direction": "outbound_internet", "data_sent": "prompts", "condition": "only when cloud routing is active"}
  ],
  "local_storage": [
    {"path": "~/.config/llmhost/", "purpose": "Configuration and encrypted keys", "encrypted": true},
    {"path": "~/.local/share/llmhost/audit.db", "purpose": "Local audit log", "encrypted": false},
    {"path": "~/.local/share/llmhosts/cache/", "purpose": "Semantic cache", "encrypted": false}
  ],
  "gpu_usage": {
    "purpose": "LLM inference only",
    "mining": false,
    "third_party_compute": false,
    "note": "GPU is used exclusively for your own inference requests. Never for mining, never shared without your explicit opt-in via Hive Mode."
  },
  "permissions_required": ["network (localhost + configured APIs)", "disk (config + cache + audit)"],
  "permissions_never_used": ["camera", "microphone", "contacts", "location", "clipboard (read)", "screen recording"]
}
```

**Resource Monitor** (`llmhosts monitor`):
- Real-time display of LLMHosts-specific resource usage
- CPU%, GPU%, VRAM, RAM, disk I/O, network bytes in/out
- Per-request attribution: which request caused which resource spike
- Historical: last 24h graph in TUI dashboard

**Activity Log** (`llmhosts audit live`):
- Real-time tail of all activity
- Color-coded: green=normal, yellow=warning, red=security event
- Shows every network connection opened/closed
- Shows every GPU inference request with model, tokens, latency

**Open Book Guarantees**:
- No phone-home: verified by privacy manifest + network monitoring
- No background processes: `llmhosts serve` is the only process, visible in task manager
- No data exfiltration: all outbound connections logged and visible
- Reproducible builds: published checksums for every release
- SBOM: CycloneDX bill of materials with every release

---

## Aut-O Compliance Matrix

### T-10 (Security & Privacy by Default) — Gaps Addressed

| Requirement | Current | After TrustShield |
|------------|---------|-------------------|
| CSP headers | Missing | Strict CSP with nonce |
| SRI | Missing | All external scripts |
| Prompt injection defense | Missing | PromptGuard (Pillar 1) |
| DOMPurify for UGC | Partial | Explicit sanitization |
| Argon2id for passwords | Uses bcrypt | Migrate to Argon2id |

### T-15 (Military-Grade Compliance) — Gaps Addressed

| Requirement | Current | After TrustShield |
|------------|---------|-------------------|
| Tamper-evident audit | Missing | HMAC chain (Pillar 2) |
| SBOM | Missing | CycloneDX in CI |
| mTLS | Missing | SecureMesh (Pillar 4) |
| Audit export | Missing | JSONL/CSV export (Pillar 2) |
| Continuous compliance | Partial | Privacy manifest + dashboard |
| Breach notification | Missing | IR playbook + alerts |

---

## Testing Strategy

- **PromptGuard**: 50+ test cases covering known injection patterns, false positive scenarios, encoding attacks, configurable modes
- **TrustLedger**: HMAC chain integrity, export format validation, filter accuracy, verify command
- **AdaptiveShield**: Sliding window accuracy, model weight calculation, burst handling, concurrent access
- **SecureMesh**: Certificate generation, rotation, revocation, mTLS handshake, expiry warnings
- **TransparencyDashboard**: Privacy manifest generation, resource monitor accuracy, audit live streaming

---

## Implementation Order

1. **PromptGuard** — highest user-facing impact, unique selling point
2. **TrustLedger** — compliance backbone, extends existing audit
3. **AdaptiveShield** — extends existing rate limiter
4. **TransparencyDashboard** — user trust, privacy manifest
5. **SecureMesh** — mTLS for multi-node (less urgent for single-node)

---

## Files to Create/Modify

### New files:
- `llmhosts/security/__init__.py`
- `llmhosts/security/prompt_guard.py` — Pillar 1
- `llmhosts/security/patterns.py` — Injection pattern database
- `llmhosts/audit/exporter.py` — Pillar 2 export
- `llmhosts/audit/hmac_chain.py` — Pillar 2 HMAC
- `llmhosts/security/adaptive_rate_limit.py` — Pillar 3
- `llmhosts/security/tls_manager.py` — Pillar 4
- `llmhosts/security/mtls.py` — Pillar 4
- `llmhosts/security/transparency.py` — Pillar 5
- `llmhosts/security/privacy_manifest.py` — Pillar 5
- `llmhosts/security/resource_monitor.py` — Pillar 5
- `tests/test_prompt_guard.py`
- `tests/test_trustledger.py`
- `tests/test_adaptive_rate_limit.py`
- `tests/test_mtls.py`
- `tests/test_transparency.py`

### Modified files:
- `llmhosts/server.py` — wire new middleware
- `llmhosts/cli.py` — add audit/tls subcommands
- `llmhosts/config.py` — add security config sections
- `llmhosts/proxy/middleware.py` — add CSP, SRI headers
- `.github/workflows/ci.yml` — add SBOM generation
- `pyproject.toml` — add cryptography extras if needed
