Security Overview

Security architecture and credential management for Project Aegis.

Security Boundaries

Container Isolation

• LXC unprivileged container
• No SSH access to host
• Docker socket read-only (for container management only)
• UID remapping enabled

File Protection

• Credentials in ~/.secure/ only
• Pre-tool hooks block access to sensitive files
• No credentials in git commits
• Environment variables for runtime secrets

Network Isolation

• Internal Docker network for services
• Traefik handles external traffic
• SSL/TLS for all public endpoints
• No direct database exposure

Credential Management

Storage Locations

~/.secure/
├── .env                    # All API keys (primary)
├── stripe.env              # Stripe keys
├── stripe-intel-config.json
├── stripe-services-config.json
├── vscode_password.txt     # Code editor password
├── restic-password         # Backup encryption
└── service-passwords.txt   # Service passwords

~/.claude.json              # MCP server tokens
~/.claude/settings.json     # Claude SDK config

Credential Categories

Category	Location	Examples
Database	.env	POSTGRES_PASSWORD
LLM APIs	.env	ZAI_API_KEY, ANTHROPIC_API_KEY
Communication	.env + .claude.json	DISCORD_BOT_TOKEN
Payment	stripe.env	STRIPE_SECRET_KEY
Storage	.env	GITHUB_TOKEN

Hook Protection

PreToolUse Hooks

block-sensitive-files.py - Blocks access to .env, .secure/, credentials - Runs before every file operation

bash-validator.py - Blocks dangerous commands (rm -rf, force push) - Validates bash commands before execution

PostToolUse Hooks

cost-tracker.sh - Logs tool usage to ~/memory/tool-usage.jsonl - Tracks API costs

episodic-recorder.py - Records significant actions to episodic memory

Access Control

API Key System

• Keys stored in PostgreSQL api_keys table
• Rate limiting per key
• Usage tracking and credits
• Permission levels

Authentication

• JWT tokens for API access
• API key headers for service-to-service
• OAuth for Google Workspace

Security Checklist

Daily

• No credentials in recent commits
• All services using HTTPS
• Logs don't contain secrets

Weekly

• Review access logs
• Check for failed auth attempts
• Verify backup encryption

Monthly

• Rotate API keys where possible
• Review MCP server permissions
• Audit user access

Incident Response

1. Credential Exposure
2. Immediately rotate affected key
3. Check for unauthorized usage

4. Document in journal

5. Unauthorized Access

6. Block source IP/token
7. Review access logs

8. Escalate to Discord #alerts

9. Data Breach

10. Assess scope
11. Notify affected parties
12. Document and remediate

Documentation

• credentials.md - Credential storage and rotation
• access-control.md - API keys and permissions
• hooks.md - Security hooks configuration

---

Last Updated: 2026-01-25