Access Control¶

This document details access control mechanisms for Project Aegis services and APIs.

Service Access Credentials¶

VS Code Server¶

Service: Web-based VS Code IDE URL: https://code.aegisagent.ai Authentication: Password-based

Password location: ~/.secure/service-passwords.txt

Example entry:

VS Code: <password>

Session Management: Sessions persist for 7 days with "Remember me" enabled.

Security Notes: - Exposed publicly via Traefik with TLS - Rate limiting: 5 failed attempts → 15-minute lockout - No 2FA available (built-in VS Code server limitation) - Consider IP allowlisting via Traefik middleware for production

VNC Access¶

Service: Remote desktop access URL: https://vnc.aegisagent.ai Authentication: VNC password

Password location: ~/.secure/service-passwords.txt

Example entry:

VNC: <password>

Security Notes: - TLS-encrypted via Traefik - VNC protocol runs on port 5900 (internal only) - No built-in account management - Consider disabling when not actively needed

PostgreSQL Database¶

Service: Primary database Host: localhost:5432 (internal only) Authentication: Username/password

Credentials: - Username: agent - Password: agent (stored in ~/.secure/.env)

Access Control: - Not exposed publicly (Traefik doesn't route to port 5432) - Docker containers access via host.docker.internal - No external network access

Connection String:

postgresql://agent:agent@localhost:5432/aegis

FalkorDB (Knowledge Graph)¶

Service: Graph database for Graphiti URL: http://localhost:6379 (Redis protocol) Browser UI: http://localhost:3001 Authentication: None (localhost only)

Security Notes: - Redis-compatible protocol (no auth required) - Not exposed publicly - Data persists in Docker volume falkordb_data

API Authentication¶

Dashboard API¶

Base URL: https://aegisagent.ai/api Authentication Method: Bearer token OR X-API-Key header

User API Keys¶

Location: ~/.secure/aegis_api_key

Example:

sk_live_abc123def456ghi789

Usage:

curl https://aegisagent.ai/api/endpoint \
  -H "Authorization: Bearer sk_live_abc123def456ghi789"

Admin API Keys¶

Location: ~/.secure/.env

Environment variable: INTEL_DIGEST_ADMIN_KEY

Usage (Intel digest trigger):

curl -X POST https://aegisagent.ai/api/intel/digest/send \
  -H "X-API-Key: <INTEL_DIGEST_ADMIN_KEY>"

Open Notebook API¶

Base URL: https://api.notebooks.aegisagent.ai Authentication Method: API key (header or query param)

API key location: /home/agent/projects/open-notebook/.env

Example:

# Via header
curl https://api.notebooks.aegisagent.ai/api/search \
  -H "X-API-Key: <key>" \
  -d '{"query": "AI agents"}'

# Via query param
curl "https://api.notebooks.aegisagent.ai/api/search?api_key=<key>&query=AI+agents"

Rate Limiting: 100 requests/minute per API key (configurable in Open Notebook settings)

Services API (Product Listings)¶

Base URL: https://aegisagent.ai/api/services Authentication Method: None (public read), API key (write)

Public endpoints: - GET /api/services - List available services - GET /api/services/{id} - Get service details

Protected endpoints (require API key): - POST /api/services - Create service listing - PUT /api/services/{id} - Update service

Future: Stripe-integrated usage-based billing

WhatsApp Command Authorization¶

Service: Two-way WhatsApp command channel Number: +44 7441 443388 (Vonage WABA)

Authorized Users¶

Hardcoded in webhook handler (aegis/dashboard/routes/vonage.py):

AUTHORIZED_NUMBERS = [
    "+447490195079",  # Personal mobile
    "+447816246275",  # Work mobile
]

Authorization Check:

def is_authorized(from_number: str) -> bool:
    return from_number in AUTHORIZED_NUMBERS

Command Access Levels¶

All authorized users have full access to all commands:

Command	Description	Authorization
`status`	System health	Authorized users
`tasks`	Pending tasks	Authorized users
`deploy <service>`	Deploy container	Authorized users
`stop <service>`	Stop container	Authorized users
`task: <desc>`	Start Claude session	Authorized users
`c: <prompt>`	Continue session	Authorized users

Unauthorized numbers receive: "Unauthorized. This WhatsApp number is not registered."

Adding New Users¶

Edit aegis/dashboard/routes/vonage.py:

AUTHORIZED_NUMBERS = [
    "+447490195079",
    "+447816246275",
    "+44XXXXXXXXXXX",  # New user
]

Restart dashboard:

cd /home/agent/projects/aegis-core && docker compose restart dashboard

Test with a message to +44 7441 443388

MCP Tool Authorization¶

MCP tools do not have built-in user-level authorization. Access is binary:

If MCP server is running: Full access to all tools
If MCP server is stopped: No access

Risk-Based Access Control¶

The mcp-security-audit.py hook logs access with risk levels:

Risk Level	MCP Servers	Operations Logged
High	docker, postgres, filesystem, stackwiz	All operations
Medium	github, google-workspace, discord, telegram, vonage	Flagged operations only
Low	memory, ollama, notebooklm, playwright, wallet	Not logged

Flagged Operations (always logged): - docker: remove_container, remove_image, remove_volume - postgres: execute (DML queries) - filesystem: write_file, edit_file, move_file - github: push_files, merge_pull_request - stackwiz: manage_stack (remove operations)

Audit log location: ~/memory/security/mcp-audit.jsonl

Review flagged operations:

jq 'select(.flagged == true)' ~/memory/security/mcp-audit.jsonl | tail -20

Session Management¶

Claude Code Sessions¶

Authentication: Not applicable (runs locally as agent user)

Session Persistence: Sessions stored in ~/.claude/history.jsonl

Access Control: File system permissions (agent user owns files)

WhatsApp Sessions¶

Session Storage: PostgreSQL (claude_sessions table)

Session Ownership: Tied to WhatsApp phone number

Isolation: Users can only access their own sessions:

SELECT * FROM claude_sessions
WHERE phone_number = '<authorized_number>'
ORDER BY created_at DESC;

Session Commands: - sessions - List your sessions only - session <id> - View your session (ID validation ensures ownership) - stop session - Stop your running session

Traefik TLS Termination¶

Certificate Management¶

Provider: Cloudflare DNS-01 challenge Cert Resolver: cf (configured in Traefik)

Traefik automatically provisions and renews Let's Encrypt certificates for: - aegisagent.ai - *.aegisagent.ai (wildcard) - rbnk.uk - *.rbnk.uk (wildcard)

Certificate Storage: Traefik container volume (persists across restarts)

TLS Configuration¶

All services use Traefik labels for TLS:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.aegis.rule=Host(`aegisagent.ai`)"
  - "traefik.http.routers.aegis.entrypoints=websecure"
  - "traefik.http.routers.aegis.tls.certresolver=cf"

Entrypoints: - web: Port 80 (HTTP, redirects to HTTPS) - websecure: Port 443 (HTTPS, TLS-terminated)

TLS Version: TLS 1.2+ (Traefik default)

Cipher Suites: Traefik's default Mozilla Intermediate profile

Public Service Matrix¶

Domain	Service	TLS	Auth Method
aegisagent.ai	Dashboard	Yes (Cloudflare)	None (public)
intel.aegisagent.ai	Intel Dashboard	Yes (Cloudflare)	None (free tier)
code.aegisagent.ai	VS Code	Yes (Cloudflare)	Password
vnc.aegisagent.ai	VNC	Yes (Cloudflare)	VNC password
notebooks.aegisagent.ai	Open Notebook	Yes (Cloudflare)	None (public)
api.notebooks.aegisagent.ai	Notebook API	Yes (Cloudflare)	API key

IP Allowlisting¶

Current Status: Not implemented

Recommended for Production:

Traefik middleware for IP allowlisting:

# /srv/dockerdata/traefik/dynamic/middleware-ipallowlist.yml
http:
  middlewares:
    aegis-allowlist:
      ipWhiteList:
        sourceRange:
          - "100.114.189.93/32"  # Tailscale IP
          - "203.0.113.0/24"     # Office IP range

Apply to VS Code and VNC:

labels:
  - "traefik.http.routers.code.middlewares=aegis-allowlist@file"

SSH Access¶

GitHub SSH Key¶

Key Location: ~/.ssh/id_ed25519_github Public Key: ~/.ssh/id_ed25519_github.pub

Usage: - GitHub authentication - Dockerhost SSH access

SSH Config:

Host dockerhost
  HostName 10.10.10.10
  User agent
  IdentityFile ~/.ssh/id_ed25519_github

Security Notes: - Private key has 600 permissions (owner read/write only) - Protected by block-sensitive-files.py hook (cannot be edited by Claude) - No passphrase (automation requirement)

Host SSH Access¶

From Aegis LXC to Dockerhost:

ssh dockerhost "docker ps"

From External to Aegis LXC: Not directly accessible. Must SSH to Proxmox host first, then LXC console.

Tailscale VPN¶

Network: rickoslyder@ tailnet Aegis IP: 100.114.189.93 Hostname: aegis

Access Control: Managed via Tailscale admin console

Usage:

# From Tailscale device
ssh agent@aegis  # If SSH enabled
curl http://aegis:8080/health

Security Notes: - Tailscale provides end-to-end encryption - ACLs managed centrally (not on Aegis LXC) - Consider enabling MagicDNS for aegis.tailnet-name.ts.net

Role-Based Access (Future)¶

Current State: No formal RBAC

Proposed for v2.0:

Role	Permissions
Admin	Full system access, deploy services, manage users
Developer	Read code, create branches, open PRs
Observer	Read-only dashboard, logs, metrics
API Consumer	Rate-limited API access, no admin functions

Implementation plan: ~/memory/semantic/rbac-design.md (TODO)

Compliance Considerations¶

Personal Data: WhatsApp phone numbers stored in PostgreSQL
Right to Access: Implement endpoint to export user's session data
Right to Deletion: Implement endpoint to delete user's sessions and messages
Data Retention: Configure retention policy (e.g., 90 days)

SOC 2 (US)¶

Access Logging: MCP audit logs provide trail (already implemented)
Least Privilege: MCP risk levels enforce (already implemented)
Password Complexity: Not enforced (TODO: implement for VS Code/VNC)
MFA: Not available (VS Code server limitation)

Audit Checklist¶

Perform quarterly:

Emergency Access Procedures¶

Lockout from VS Code/VNC¶

SSH to Aegis LXC via Proxmox console
Verify password in ~/.secure/service-passwords.txt

If forgotten, reset VS Code config:

# Stop code-server, remove config, restart with new password
systemctl stop code-server@agent
rm -f ~/.config/code-server/config.yaml
code-server --password "<new_password>"

Lost API Keys¶

Generate new keys from service provider dashboard
Update ~/.secure/.env

Restart affected services:

cd /home/agent/projects/aegis-core && docker compose restart

Compromised WhatsApp Channel¶

Edit AUTHORIZED_NUMBERS in aegis/dashboard/routes/vonage.py
Restart dashboard
Consider rotating Vonage webhook signature secret
Review ~/memory/security/mcp-audit.jsonl for suspicious activity