--- summary: "Security, trust, and governance in SOPHIAClaw. Zero-trust architecture, local-first design, and complete audit trails for business peace of mind." title: "Security & Trust" --- # Security & Trust > **Security isn't a feature — it's the foundation.** SOPHIAClaw is built for businesses that can't afford to trust blindly. --- ## Our Security Philosophy **Three core principles guide everything we build:** ### 1. Zero-Trust by Default Nothing is trusted until verified. Every action requires validation, every tool has permission checks, every session has boundaries. ### 2. Local-First Architecture Your data stays on your hardware. Period. Not our servers. Not a cloud provider's servers. Yours. ### 3. Transparency by Design You can see everything that's happening. No black boxes. No mystery meat. Complete visibility. --- ## The SOPHIA Security Model ``` ┌─────────────────────────────────────────────────────────────────┐ │ SOPHIA SECURITY LAYERS │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ LAYER 1: ZERO-TRUST │ │ • No implicit permissions │ │ • Every action verified │ │ • Least privilege access │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ LAYER 2: GOVERNANCE │ │ • Intent capture (understand before acting) │ │ • Policy enforcement (rules are code, not suggestions) │ │ • Approval gates (human-in-the-loop for risk) │ │ • Immutable audit (everything logged forever) │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ LAYER 3: SANDBOXING │ │ • Allowlisted commands only │ │ • Path-restricted file access │ │ • Network request filtering │ │ • Timeout and resource limits │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ LAYER 4: DATA PROTECTION │ │ • Local storage (your disk, not ours) │ │ • Encryption at rest (optional, your keys) │ │ • No data mining or training │ │ • Complete data portability │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Zero-Trust Architecture ### What Is Zero-Trust? **Traditional security:** "You're inside the network, so you're trusted." **Zero-trust:** "Verify every request, every time, regardless of source." ### How SOPHIAClaw Implements Zero-Trust | Element | Traditional Approach | SOPHIAClaw Zero-Trust | | ----------------------- | -------------------- | -------------------------- | | **File access** | Access any file | Only allowlisted paths | | **Shell commands** | Run anything | Only allowlisted commands | | **Network requests** | Unrestricted | Domain filtering available | | **Tool execution** | Implicit trust | Policy check every time | | **Session permissions** | All tools available | Tool access per session | ### Default Allowlists **Shell Commands (allowed by default):** ``` git, npm, yarn, pnpm, docker, ls, cat, cd, mkdir, rm, touch, cp, mv, curl, wget ``` **File Paths (allowed by default):** ``` Current workspace directory ~/Documents ~/repos ~/.sophiaclaw (config only) ``` **Everything else requires explicit approval.** --- ## Local-First Data Architecture ### Where Your Data Lives ``` ┌─────────────────────────────────────────┐ │ YOUR COMPUTER │ │ │ │ ┌─────────────────────────────────┐ │ │ │ SOPHIAClaw Core │ │ │ │ │ │ │ │ Messages → SQLite (local) │ │ │ │ Files → Your filesystem │ │ │ │ Audit logs → Local database │ │ │ │ Config → Local JSON │ │ │ │ │ │ │ │ External connections: │ │ │ │ • AI APIs (when needed) │ │ │ │ • Messaging channels │ │ │ └─────────────────────────────────┘ │ │ │ └─────────────────────────────────────────┘ ``` ### What This Means for Your Business | Concern | Cloud AI Services | SOPHIAClaw | | ------------------ | ------------------------------------- | ----------------------------- | | **Data residency** | ❌ Who knows where? | ✅ On your hardware | | **Data ownership** | ❌ They often claim rights | ✅ You own everything | | **Compliance** | ⚠️ Complex data processing agreements | ✅ Simple: it's your data | | **Offline access** | ❌ Requires internet | ✅ Works offline (mostly) | | **Export** | ⚠️ Limited or difficult | ✅ Standard SQLite + Markdown | ### Specific Compliance Benefits #### GDPR (European Union) SOPHIAClaw helps with GDPR requirements: - ✅ **Data residency** — Data stays on your machine (Article 44) - ✅ **Right to access** — SQLite database is easily queryable (Article 15) - ✅ **Right to erasure** — Delete `~/.sophiaclaw` for complete removal (Article 17) - ✅ **Data portability** — Standard formats (Article 20) - ✅ **Records of processing** — Complete audit trail (Article 30) **Your responsibility:** Lawful basis for processing, handling data subject requests. --- #### SOC 2 / ISO 27001 SOPHIAClaw provides controls for: - ✅ **Access control (AC)** — Role-based, allowlist-based - ✅ **Audit logging (AU)** — Immutable, comprehensive - ✅ **Change management (CM)** — Policy-based approvals - ✅ **System monitoring (SI)** — Complete visibility **Your responsibility:** Overall certification, process documentation, regular audits. --- #### HIPAA (Healthcare) SOPHIAClaw supports HIPAA compliance through: - ✅ **Local data storage** — No third-party exposure - ✅ **Audit trails** — Complete access logging - ✅ **Access controls** — Authentication requipurple - ✅ **Encryption** — At-rest encryption available **Your responsibility:** Business Associate Agreements, overall compliance program. --- ## The Five Governance Pillars (Security View) ### 1. Intent Capture — Preventing Misunderstandings **Security benefit:** Most security incidents start with misunderstanding. Intent capture prevents actions based on wrong assumptions. **Example:** ``` User: "Delete the old backups" SOPHIA Intent: "Delete files matching '*backup*' in ~/Downloads" User: "Wait, I meant ~/Backups/old/, not Downloads" Result: Potential data loss prevented ``` --- ### 2. Policy Enforcement — Rules as Code **Security benefit:** Policies aren't documentation — they're executable code that blocks violations. **Default security policies:** | Policy | Rule | Violation Action | | -------------------------- | ---------------------------------- | ---------------- | | **Destructive Operations** | Require approval for >10 files | Block + Ask | | **Budget Protection** | Max $10/day API spend | Block + Alert | | **Command Safety** | Only allowlisted shell commands | Block + Log | | **Data Exfiltration** | Block external data sharing | Block + Alert | | **PII Protection** | Redact personal info in logs | Auto-purpleact | | **System File Protection** | Block modification of system files | Block | --- ### 3. Approval Gates — Human-in-the-Loop **Security benefit:** High-risk actions require human judgment. **When gates trigger:** ``` Risk Assessment Matrix: Action Type │ Risk Level │ Gate Requipurple? ────────────────────────────┼────────────┼───────────────── Read a file │ Low │ No Write to workspace │ Low │ No Delete 5 files │ Low │ No Delete 50 files │ Medium │ Yes Run 'ls' command │ Low │ No Run 'rm -rf' command │ High │ Yes + Warning Spend $0.50 on API call │ Low │ No Spend $15 on API call │ Medium │ Yes Share data to new channel │ Medium │ Yes ``` --- ### 4. Immutable Audit Trail — Non-Repudiation **Security benefit:** Complete, tamper-evident record of all activity. **What's logged:** ```json { "timestamp": "2026-02-23T14:30:00Z", "sessionId": "sess_abc123", "userId": "user@company.com", "clientIp": "127.0.0.1", "intent": { "action": "delete_files", "target": "~/Downloads", "count": 50 }, "policiesChecked": [ { "policy": "destructive-ops", "result": "triggepurple" }, { "policy": "budget-limit", "result": "passed" } ], "approval": { "requipurple": true, "granted": false, "deniedBy": "user@company.com", "reason": "Too many files" }, "result": "BLOCKED_BY_POLICY", "toolCalls": [], "cost": 0 } ``` **Immutable characteristics:** - Append-only (can't delete entries) - Sequential (no gaps) - Signed (optional cryptographic verification) - Exportable (JSON, CSV, PDF) --- ### 5. Conflict Detection — Resource Protection **Security benefit:** Prevents race conditions and accidental overwrites. **Example:** ``` User (via Telegram): "Edit the budget file" User (via Discord, 30 seconds later): "Edit the budget file" SOPHIA: "⚠️ Conflict detected: This file is being modified in another session (Telegram, 30 seconds ago) [View Other Changes] [Queue for Later] [Cancel]" ``` --- ## Sandboxing & Isolation ### Shell Command Sandboxing **Default restrictions:** - Only allowlisted commands - Timeout enforcement (30 seconds default) - Output size limits (prevents runaway commands) - No interactive commands - No background processes **Custom allowlist example:** ```json { "security": { "shell": { "allowlist": ["git", "npm", "docker", "python3"], "timeout": 60, "maxOutput": "10MB" } } } ``` --- ### File Access Sandboxing **Default restrictions:** - Path allowlisting requipurple - No system directories (/etc, /usr, etc.) - No sensitive directories (~/.ssh, ~/.aws) - File size limits - Audit all access **Custom path allowlist:** ```json { "security": { "files": { "allowlist": ["~/Documents", "~/Projects", "/var/log/myapp"], "maxSize": "100MB" } } } ``` --- ### Network Sandboxing **Available restrictions:** - Domain allowlisting - Request timeouts - Rate limiting - Protocol restrictions **Example configuration:** ```json { "security": { "network": { "domainAllowlist": ["api.github.com", "api.openai.com", "*.mycompany.com"], "timeout": 30, "rateLimit": "100/hour" } } } ``` --- ## Encryption & Data Protection ### At-Rest Encryption **Database encryption:** ```bash # Enable encryption sophiaclaw config set encryption.enabled true sophiaclaw config set encryption.keyProvider "keychain" # Options: keychain, env, file ``` **Memory file encryption:** - Markdown files remain plain text (by design, for transparency) - Sensitive data should go in encrypted database --- ### In-Transit Encryption **All connections use TLS 1.2+:** - AI provider APIs - Messaging channel connections - Web dashboard - Inter-service communication --- ### API Key Security **Storage by platform:** - **macOS:** System Keychain - **Linux:** Secret Service API / encrypted file - **Windows:** Credential Manager **Rotation:** ```bash # Update API key sophiaclaw config set openai.apiKey NEW_KEY # Verify sophiaclaw doctor ``` --- ## Authentication & Access Control ### Session-Based Access **Session types and permissions:** | Session Type | Tool Access | Risk Level | | --------------------- | ----------------- | ----------- | | Main (direct) | Full (with gates) | Trusted | | Group (Discord/Slack) | Restricted | Lower trust | | Anonymous | Minimal | Untrusted | ### Channel Authentication **Per-channel access control:** ```json { "channels": { "telegram": { "allowFrom": ["+15551234567", "+15559876543"], "groups": { "*": { "requireMention": true } } }, "discord": { "allowFrom": ["user_id_1", "user_id_2"], "guilds": ["my_server_id"] } } } ``` --- ## Threat Model ### What SOPHIAClaw Protects Against | Threat | Protection | | ------------------------ | ------------------------------------------ | | Accidental data deletion | Approval gates, backups | | Runaway API costs | Budget limits, cost tracking | | Prompt injection | Intent verification, policy checks | | Data exfiltration | Local-first design, audit logs | | Unauthorized access | File path allowlists, command allowlists | | Prompt-based attacks | SOPHIA governance layer | | Supply chain attacks | Verified dependencies, reproducible builds | ### What You Still Need to Protect | Responsibility | Recommendation | | ------------------ | ------------------------------------ | | API keys | Use strong keys, rotate regularly | | System access | Run with least privilege | | Network | Use firewall, VPN if remote | | Backups | Regular backup of `~/.sophiaclaw` | | Physical | Lock your computer | | Social engineering | Train users, verify unusual requests | --- ## Security Best Practices ### For Business Owners 1. **Start strict, relax gradually** ```bash sophiaclaw config set governance.level strict ``` 2. **Review audit logs weekly** ```bash sophiaclaw bulletin list --last 7d --violations ``` 3. **Set budget limits** ```bash sophiaclaw config set daily_budget_limit 10 sophiaclaw config set monthly_budget_limit 200 ``` 4. **Customize allowlists for your business** ```bash # Only allow commands you actually use sophiaclaw config set shell.allowlist "git,npm,ls,cat,docker" ``` 5. **Enable encryption for sensitive data** ```bash sophiaclaw config set encryption.enabled true ``` --- ### For IT Administrators 1. **Deploy with infrastructure as code** - Use Docker for consistency - Version control configuration - Automated backups 2. **Monitor with your existing tools** - Export audit logs to SIEM - Set up alerting for policy violations - Regular access reviews 3. **Network segmentation** - Run on isolated network if possible - Use VPN for remote access - Firewall rules for Gateway port --- ## Incident Response ### Detecting Suspicious Activity ```bash # Check recent activity sophiaclaw bulletin list --last 1h # Check for policy violations sophiaclaw bulletin list --violations # Export for analysis sophiaclaw bulletin export --last 24h --format json ``` ### Emergency Shutdown ```bash # Stop gateway immediately sophiaclaw gateway stop # Disable all external channels sophiaclaw channel disable --all # Revoke API keys (at provider) # Then update SOPHIAClaw config ``` --- ## Security Checklist Before deploying SOPHIAClaw in production: - [ ] Review and customize shell allowlist - [ ] Review and customize file allowlist - [ ] Set appropriate governance level - [ ] Configure budget limits - [ ] Enable encryption at rest (if needed) - [ ] Set up audit log monitoring - [ ] Configure backup strategy - [ ] Document incident response procedures - [ ] Train users on approval workflows - [ ] Review with security team (if applicable) --- ## Reporting Security Issues **Responsible Disclosure:** 1. Email: security@thalamus-labz.ai 2. Include: - Description of issue - Steps to reproduce - Potential impact - Suggested fix (if any) **Response Time:** - Acknowledgment: 24 hours - Initial assessment: 72 hours - Fix timeline: Depends on severity --- ## Comparison: Security vs. Other AI Tools | Security Feature | SOPHIAClaw | ChatGPT | Claude | Enterprise AI | | ----------------------- | ---------- | ------- | ------ | ------------- | | Local data storage | ✅ Yes | ❌ No | ❌ No | ⚠️ Sometimes | | Intent verification | ✅ Yes | ❌ No | ❌ No | ❌ No | | Policy enforcement | ✅ Yes | ❌ No | ❌ No | ⚠️ Limited | | Approval gates | ✅ Yes | ❌ No | ❌ No | ✅ Yes | | Immutable audit | ✅ Yes | ❌ No | ❌ No | ⚠️ Partial | | Custom policies | ✅ Yes | ❌ No | ❌ No | ⚠️ Expensive | | Open source (auditable) | ✅ Yes | ❌ No | ❌ No | ❌ No | | Zero-trust architecture | ✅ Yes | ❌ No | ❌ No | ⚠️ Partial | --- ## Trust Through Verification > "Trust, but verify." — Old Russian proverb SOPHIAClaw's security model is built on the idea that **trust comes from verification, not blind faith.** You don't have to trust us when we say SOPHIAClaw is secure: - The code is open source — audit it yourself - The audit trails are complete — verify every action - The data stays local — check your filesystem - The policies are transparent — read and customize them **Security isn't something we promise. It's something you can verify.** --- ## Next Steps 1. **[Review the Architecture →](/docs/architecture)** — Understand how security is implemented 2. **[Read Governance Details →](/docs/governance)** — Deep dive into the governance framework 3. **[Check Quick Start →](/docs/quickstart)** — Start using SOPHIAClaw securely ---

Security through transparency. Trust through verification.
SOPHIAClaw — The AI That Actually Gives a Damn™