oabrivard
/
simple-agent
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'eca444f04a'
${ noResults }
simple-agent/docs/security.md

2.8 KiB
Raw Blame History

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
  • In oauth mode, set MCP_RESOURCE_SERVER_URL to the public MCP URL and keep it HTTPS

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.