Security

Authentication

API Keys

All API requests (except health check) require authentication via API keys:

Authorization: Bearer als_<64-hex-chars>

• Keys are generated via POST /api/keys
• The raw key is shown only once at creation time
• Server stores only the SHA-256 hash of each key
• Authentication is a constant-time hash comparison

Development Mode

Set AUTH_DISABLED=true to skip authentication during development. Never use this in production.

Webhook Verification

Inbound webhooks from AgentGate and FormBridge are verified using HMAC-SHA256:

1. Sender computes HMAC-SHA256(raw_body, shared_secret) as hex
2. Signature sent in X-Webhook-Signature header
3. AgentLens verifies using timing-safe comparison (prevents timing attacks)

Tamper Evidence

Hash Chain

Every event includes a SHA-256 hash that chains to the previous event in its session:

hash = SHA-256(canonical_json(id, timestamp, sessionId, agentId, 
               eventType, severity, payload, metadata, prevHash))

If any event is modified after ingestion, verifyChain() will detect the break.

Append-Only Storage

The events table has no UPDATE or DELETE operations (except retention cleanup). This ensures the audit trail is immutable.

Data Protection

Payload Truncation

Payloads exceeding 10 KB are automatically truncated. This prevents:

• Storage exhaustion from large payloads
• Query performance degradation
• Potential denial-of-service via oversized events

CORS

Configurable via CORS_ORIGIN environment variable:

• Default: * (development)
• Production: set to your dashboard domain

Network Isolation

AgentLens makes no outbound network calls except:

• Alert webhook notifications (to configured URLs)
• The MCP server's HTTP calls to the API server

No telemetry, no phone-home, no external dependencies at runtime.

Recommendations for Production

1. Set AUTH_DISABLED=false (the default)
2. Generate unique API keys per agent
3. Set CORS_ORIGIN to your specific domain
4. Use HMAC secrets for all webhook integrations
5. Run behind a reverse proxy (nginx/caddy) with TLS
6. Set RETENTION_DAYS according to your compliance requirements
7. Back up the SQLite database file regularly