Skip to main content

Security & Compliance

Cirrus CDN incorporates security best practices across authentication, data storage, transport, and operational workflows. This chapter catalogs the implemented controls and identifies considerations for compliance-driven environments.

Identity & Access Management​

  • User Authentication – Passwords are hashed with Argon2 (core/security.py). Sessions are HTTP-only cookies with configurable domain, secure flag, and SameSite attribute. Failed logins return generic errors to prevent user enumeration.
  • Session Management – Sessions are stored in-memory (SESSIONS dict). Each request refreshes the expiration timestamp (SESSION_TTL_SECONDS, default 7 days). Logout explicitly removes session cookies and erases the server-side entry.
  • Service Tokens – Tokens are generated with secrets.token_urlsafe, hashed using SHA-256, and stored without cleartext. Token suffixes (last two characters) enable safe identification. Deleting a token removes both hash and ID entries.
  • Master Token – Environment variable MASTER_API_TOKEN grants elevated rights (listing/creating/deleting service tokens). Endpoints verify request.state.cirrus_auth_method == "master" before allowing operations.
  • Bootstrap Mode – When no users or tokens exist, require_user allows unauthenticated access for initial setup. Once accounts are created, authentication becomes mandatory.

Data Protection​

  • Redis Storage – Sensitive values (password hashes, token hashes, certificates) reside in Redis. No plaintext passwords or tokens are stored. Certificates (cdn:cert:{domain}) include both fullchain and private key; ensure Redis infrastructure is secured (TLS, network segmentation).
  • TLS Certificates – OpenResty loads certificates directly from Redis into memory during handshakes; private keys are not written to disk post-issuance. Dummy certificates exist only to bootstrap handshake flows.
  • ACME Credentials – acme-dns usernames/passwords are stored in cdn:acme:{domain} hashes. Consider encrypting or isolating Redis instances if regulatory requirements dictate.
  • Logs – Access logs contain client IPs and request metadata. Plan retention and redaction policies consistent with privacy regulations.

Transport Security​

  • Edge HTTPS – TLS protocols (TLSv1.2, TLSv1.3) are enabled; session cache and stapling are configured in nginx.conf. QUIC is supported for modern clients.
  • Internal Trust – Celery workers copy the internal CA certificate from Caddy (docker/entrypoint.sh) so HTTP client libraries trust ACME endpoints.
  • Redis Connections – Default deployment uses plaintext Redis on local network. Production environments should enable TLS or restrict access to management networks.
  • Metrics Endpoint – /metrics listens on 9145 and is restricted to loopback; build-time NGX_METRICS_ALLOW expands the allowlist.

Purge & Configuration Safety​

  • Purge requests are authenticated via the API; OpenResty’s /cache/purge location is locked to 127.0.0.1 to avoid unauthorized invalidations.
  • Domain and node payload validators (schemas.py) enforce structure, IP formatting, and status fields to guard against malformed configuration injection.
  • ACME tasks enforce CNAME checks when ENFORCE_ACME_CNAME_CHECK is true, preventing issuance if DNS is misaligned.

Secrets Management​

  • .env files (loaded via set dotenv-load in the justfile) typically supply secrets such as MASTER_API_TOKEN, ACME endpoints, and Redis credentials. Ensure .env is excluded from version control and stored securely.
  • Docker secrets or orchestration-specific secret stores (e.g., Kubernetes Secrets) should replace plain environment variables in production.

Compliance Considerations​

  • Audit Logging – Application logs capture key events (login attempts, certificate issuance). For stricter compliance, extend logging to include user IDs for CRUD operations and emit structured events to a SIEM (see the Appendices).
  • RBAC – Current implementation provides binary access (authenticated vs. master token). Enterprises may require roles (read-only, operator, admin); plan RBAC enhancements as part of the security backlog.
  • Data Residency – Redis and log volumes must comply with residency requirements; use managed services or region-specific deployments as needed.
  • Certificate Handling – Private keys in Redis may need encryption or HSM-backed storage in regulated environments.
  • Vulnerability Management – Docker base images (ghcr.io/astral-sh/uv:python3.13-trixie-slim, openresty/openresty:jammy) should be patched regularly. Dependabot/Snyk integration is recommended.

Threat Model Summary​

ThreatMitigation
Credential theftArgon2 hashing, HTTP-only cookies, session invalidation on password change.
Token leakageHash-at-rest tokens, suffix-only listing, master token gating, no client-side storage.
Cache poisoningStrict origin selection, optional header overrides, Redis-backed configuration preventing arbitrary Lua injection.
Unauthorized purgesAPI authentication + local-only purge endpoint.
Certificate misuseACME locks prevent concurrent issuance; enforcement ensures CNAME alignment.

Security posture is strong out of the box, with clear paths to extend toward stricter compliance regimes. See Operations & Observability for operational tooling and observability.