simple-agent/docs/security.md

Security Runbook

Security model

The service supports three auth modes via AUTH_MODE:

• api_key: static shared secret (AGENT_API_KEY)
• jwt: bearer JWT with scope checks
• hybrid: API key accepted first, then JWT fallback

The same backend is used across:

• REST API
• A2A adapter
• MCP tools

MCP can override auth mode independently with MCP_AUTH_MODE:

• inherit (default): use AUTH_MODE
• api_key|jwt|hybrid|oauth: MCP-only override

Recommended deployment posture

External traffic:

• Use AUTH_MODE=jwt
• Require HTTPS at reverse proxy/gateway
• Restrict exposed routes to required protocol endpoints
• For MCP connectors, MCP_AUTH_MODE=oauth is recommended

Internal traffic:

• AUTH_MODE=hybrid is acceptable during migration
• Prefer mTLS/private network for service-to-service traffic

Scope matrix

• availability:read: availability access
• mail:scan: inbox scan and triage
• unsubscribe:read: candidate discovery
• unsubscribe:execute: unsubscribe execution
• unsubscribe:digest: digest scan and send

Secret and token handling

Never commit secrets:

• .env
• token.json
• Google OAuth client secret files

Always persist and back up:

• token.json
• data/sent_unsubscribe_links.json
• data/unsubscribed_methods.json

Key and token rotation

API key rotation (api_key/hybrid)

1. Generate new strong key.
2. Update environment (AGENT_API_KEY) in deployment.
3. Restart services.
4. Update all clients.
5. Remove old key from all stores.

JWT secret rotation (jwt/hybrid)

1. Generate new signing secret.
2. Roll out issuer/signing config first.
3. Update server AUTH_JWT_SECRET.
4. Restart services.
5. Force token refresh for clients.

Incident response checklist

If credential leak is suspected:

1. Revoke compromised key/secret immediately.
2. Rotate API key and JWT secret.
3. Invalidate active tokens (issuer-side).
4. Review logs for unusual scans/unsubscribe operations.
5. Disable mutation MCP tools (MCP_ENABLE_MUTATION_TOOLS=false) until investigation completes.
6. Re-enable features after containment and verification.

Release rollout checklist

Preflight:

1. uv run pytest -q
2. uv run python -c "import app.main, app.mcp_main; print('import_ok')"
3. docker compose config --services

Canary:

1. Deploy to one node/environment.
2. Validate:
   • GET /health
   • GET /.well-known/agent-card.json
   • A2A SendMessage
   • MCP tool listing
3. Monitor errors for 30-60 minutes.

Full rollout:

1. Deploy all nodes.
2. Re-run smoke checks.
3. Confirm scheduler jobs continue as expected.

Rollback:

1. Redeploy previous image/tag.
2. Verify health and protocol smoke checks.
3. Keep state files (data/*.json) unchanged during rollback.