Skip to content

Security configuration

The security-relevant subset of configuration, with hardening guidance. Full parameter list: Configuration reference.

Secrets that must be explicit in production

# .env — production minimum
APP_ENV=production
JWT_SECRET="$(openssl rand -hex 32)"
ENCRYPTION_KEY="$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")"
DB_PASSWORD="$(openssl rand -hex 16)"
REDIS_PASSWORD="$(openssl rand -hex 16)"
SETUP_TOKEN="$(openssl rand -hex 32)"        # gates first-run admin creation
WEBHOOK_HMAC_SECRET="$(openssl rand -hex 32)" # if webhooks are reachable

Behavior enforced by the application in APP_ENV=production:

  • Missing or malformed ENCRYPTION_KEY is a startup error, not a silent regeneration.
  • The session cookie gets the Secure flag automatically (COOKIE_SECURE=true unless overridden) — serve the app behind TLS.

Key management

  • ENCRYPTION_KEY is the global key-encryption key (KEK). Each project additionally wraps its own data-encryption key (DEK) under it; rotating a project's DEK is a UI action (Admin → Encryption), rotating the KEK uses backend/scripts/rekey.py (dry-run first).
  • Backups without the key are unrecoverable. Store the key in your secret manager, not next to the backup.
  • Losing the key decrypts nothing ever again — by design there is no recovery path.

Network exposure

  • Umbryx assumes a trusted operator network behind a reverse proxy. Terminate TLS at the proxy, restrict access by IP/VPN, and let the proxy rate-limit.
  • PUBLIC_BASE_URL should be set explicitly in production (OIDC redirect URIs are built from it; leaving it derived from the request trusts the Host header).
  • /docs, /redoc, /openapi.json are disabled unless ENABLE_API_DOCS=true — keep them off for internet-adjacent deployments.

Webhooks

Without WEBHOOK_HMAC_SECRET, webhook ingestion is disabled outright (fail-closed). With it, every request must carry X-Hub-Signature-256: sha256=<hmac> computed over the raw body. Verify the current state with the hmac_required field of GET /api/projects/{pid}/webhook.

Audit integrity

Set AUDIT_INTEGRITY_KEY to enable per-event HMAC fingerprints, and optionally forward events to a WORM bucket (AUDIT_S3_*). Run GET /api/admin/audit/verify after first start to confirm fingerprints are being applied.

Module (plugin) security

PLUGIN_SIGNING_KEY + PLUGIN_REQUIRE_SIGNATURE=true (default) enforce signed server-side module uploads. Uploaded modules pass AST validation; eval/exec/__import__/compile are rejected.