Security Architecture
Technical details on encryption, threat model, and security boundaries. The CLI provides the current encrypted workflow; native macOS vault and biometric integration remain pending.
Found a Security Issue?
We take security seriously. Please report vulnerabilities privately:
- ✉️ Email security@gh0st.dev
- 🔒 Use GitHub Private Vulnerability Reporting
- 📋 Include steps to reproduce if possible
- ⏱️ Allow 90 days for remediation before public disclosure
We acknowledge receipt within 48 hours and provide a timeline for fix.
Cryptographic Primitives
| Primitive | Purpose | Implementation | Status |
|---|---|---|---|
| AES-256-GCM | Content encryption | Web Crypto API (browser) / Ring (native) | Implemented |
| HKDF-SHA-256 | Key derivation | Purpose-separated subkeys from master | Implemented |
| Argon2id | Passphrase KDF | 64MB memory, 3 iterations, 4 parallel | Implemented |
| ChaCha20-Poly1305 | Alternative cipher | Available via Ring for native builds | Available |
Key Architecture
Master Key Derivation
User Passphrase │ ▼ Argon2id (64MB, 3 iter, 4 parallel) │ ▼ Master Key (256-bit) │ ├── HKDF → Conversations Key ├── HKDF → Attachments Key ├── HKDF → Agents Key ├── HKDF → Preferences Key ├── HKDF → MCP Credentials Key └── HKDF → Export Key
Encryption Properties
- Algorithm
- AES-256-GCM
- Key derivation
- HKDF-SHA-256
- Passphrase KDF
- Argon2id (64MB, 3i, 4p)
- Nonce
- 12-byte random per encryption
- Versioning
- v1 in ciphertext header
- Integrity
- AEAD authentication tag
- Tamper detection
- AEAD tag verification
- Key wipe
- Zeroize on lock (native)
Vault Operations
| Operation | Trigger |
|---|---|
| Lock | CLI manual lock; native integration pending |
| Unlock | CLI passphrase flow; native integration pending |
| Rotate keys | CLI export/import workflow |
| Wipe | Explicit <code>gh0st wipe --force</code> |
Threat Model — What We Protect Against (and What We Don't)
Honest threat modeling means being explicit about boundaries. This table shows the current threat model.
| Threat | Protected | Zone | Notes |
|---|---|---|---|
| Casual filesystem inspection | Device | — | |
| Stolen app data directory (locked) | Device | — | |
| Accidental plaintext backups | Device | — | |
| Provider-side persistence (ZDR) | xAI | Verified via response header | |
| Remote gh0st server compromise | None | No gh0st server exists | |
| Fully compromised OS / malware | Device | — | |
| xAI seeing plaintext during inference | xAI | Required for AI to work | |
| Network metadata (ISP/VPN) | Network | — | |
| Screenshots / shoulder surfing | Physical | — | |
| Deliberately shared MCP data | MCP | Outside xAI ZDR |
What gh0st Does NOT Protect Against
This honesty is important. These are outside gh0st's control regardless of encryption strength.
Fully compromised OS / malware (process memory readable when unlocked)
xAI seeing plaintext during inference (required for model to generate response)
Network metadata — ISP, VPN, DNS traffic analysis reveals usage patterns
Screenshots / shoulder surfing / physical observation
Keyboard / input compromise (keyloggers capture before encryption)
Deliberately shared MCP data (you chose to send it to that provider)
Hardware backdoors / firmware (below software trust boundary)
Rubber-hose cryptanalysis (coercion to reveal passphrase)
Side-channel attacks (timing, power, EM emanations)
Related Documents
Threat Model (Full)
Complete threat model with attack trees, trust boundaries, and mitigations
Cryptography (Full)
Detailed cryptographic design, key management, and implementation notes
ZDR Verification (Full)
Zero Data Retention implementation and runtime verification details
Security Policy
Vulnerability disclosure process and supported versions