Security

Security

How Argus is secured, what is exposed, and how to deploy it safely. For reporting a vulnerability, see SECURITY.md (private advisory via the GitHub Security tab, or email).

What is exposed, and how to gate it

Surface	Default	Gate
Bot /metrics	open	scrape-only aggregate data; keep open for Prometheus, restrict at the network if needed
Bot dashboard / + /api/*	open	set dashboard_auth_token (or ARGUS_DASHBOARD_AUTH_TOKEN)
Bot /healthz	open	liveness only
Fleet control plane (all routes)	refuses to start on a public bind without a token	ARGUS_FLEET_TOKEN (or split ingest/viewer), /healthz + /readyz open

The no-PII guarantee (invariant 2)

guild_id, user_id, and channel_id are never Prometheus labels - enforced by a test, not convention. Per-entity questions go only to the optional analytical path (ClickHouse), which is separate storage and fails closed without a token. The fleet control plane reads aggregate metrics only and cannot expose per-entity data.

Dashboard (per-bot)

• Set dashboard_auth_token for anything not strictly localhost. It gates / and every /api/* route with a constant-time comparison; /metrics//healthz stay open so a scraper does not need the token. If the dashboard binds off-loopback with no token, Argus logs a startup warning pointing at the fix - it cannot refuse to start (that would also take down /metrics, which Prometheus needs), so the warning is your signal to add a token or bind to 127.0.0.1.
• The browser remembers a ?token= link in localStorage. Query-string tokens can land in proxy/access logs; prefer the Authorization: Bearer header for programmatic clients, and treat the link as a credential.
• Every response carries the same security headers as the fleet plane (X-Frame-Options: DENY, X-Content-Type-Options: nosniff, a CSP, and a Referrer-Policy), the version banner is stripped, and the request body is capped. The live SSE stream caps concurrent connections so it cannot be turned into a resource-exhaustion vector.
• Disable the UI entirely with dashboard=False and rely on Grafana if you only want scraping.
• On a shared/public host you can also gate /metrics itself with metrics_auth_token (or ARGUS_METRICS_AUTH_TOKEN): the scraper then sends Authorization: Bearer <token> (or ?token=). It is a separate token from the dashboard's, since the scraper is a different audience, and /healthz stays open. Prefer push (OTLP/Fleet) when you can avoid exposing a port at all.

Fleet control plane

Secure-by-default and hardened (see Fleet for the full table):

• Refuse-insecure bind: a non-loopback bind with no token will not start. Set a token, bind loopback, or ARGUS_FLEET_INSECURE=1 (local testing only).
• Split tokens (optional): a low-privilege ARGUS_FLEET_INGEST_TOKEN lives on every bot; an ARGUS_FLEET_VIEWER_TOKEN gates the UI/read APIs - so a leaked bot token cannot read the dashboard. Each falls back to the shared token. *_FILE variants read from mounted secrets.
• Token rotation (zero downtime): any token var accepts a comma-separated list; every value is accepted. Rotate by adding the new token, rolling it out, then dropping the old one - no window where requests are rejected.
• Per-identity lease secret (optional): with ARGUS_FLEET_REQUIRE_LEASE=1 the control plane mints a high-entropy secret at register and a member must present it on every heartbeat/re-register; a mismatch is 409. So even a leaked ingest token can't hijack an existing cluster's slot. The secret is stored only as an HMAC-SHA256 digest, optionally keyed by ARGUS_FLEET_SECRET_PEPPER kept in a separate boundary from the state file; verification is constant-time. The member persists its lease 0600 and resends it automatically.
• Abuse resistance: request body cap (413); per-IP register, per-identity heartbeat, and per-client read (ARGUS_FLEET_READ_BURST, GET view/api/metrics) rate limits (429); and a ARGUS_FLEET_MAX_CLUSTERS cap. /healthz//readyz stay exempt from the read limit.
• Audit log (optional): ARGUS_FLEET_AUDIT_LOG=1 emits one INFO line per ingest event (register/heartbeat) with the identity, client address, and outcome (including denied:lease). Inputs are sanitized for log injection; the secret is never logged.
• Scanner/fingerprint reduction: the version banner is stripped and security headers (X-Frame-Options: DENY, CSP, nosniff, Referrer-Policy) are sent on every response; unknown paths and bad tokens get flat, detail-free responses.
• Single writer: an advisory lock on the state file refuses a second instance; the on-disk state is schema-versioned (unknown versions refuse to load).
• Duplicate-identity detection: a CLUSTER_ID/fleet_id reused from two hosts increments argus_fleet_identity_conflicts_total and logs a warning.
• Owner-only state: the control-plane state file and the member's identity file are written 0600.
• Fail-open member: the bot's heartbeat is bounded and never raises into the bot loop, so a fleet outage cannot affect your bot.

Avoiding identity collisions

The identity is an address, not a secret, but two processes must never share one (it makes the per-fleet number and health flap). The robust way: derive it from a stable per-instance value - set cluster_id (or fleet_id) from the orchestrator (a StatefulSet pod name, the hostname, ...). The identity resolves to fleet_id -> cluster_id -> a random per-instance UUID, so this is automatic.

Don'ts:

• Don't bake the argus-fleet-id file into a container image - every copy would share it. Generate it on a per-instance writable volume, or set cluster_id/fleet_id instead.
• Don't mount one fleet_state_dir into multiple replicas.
• Don't set the same cluster_id/fleet_id on two processes.

CORS

You do not need CORS for the bundled, same-origin fleet UI - the browser only ever talks to the control plane, which serves both the SPA and the API. Hosting the bot and the dashboard on different machines/providers does not change this. CORS is only needed if you serve the SPA from a different origin than the API; then set ARGUS_FLEET_CORS_ORIGINS to an explicit allowlist (never a wildcard on a token-gated surface).

Deployment recommendations

• Terminate TLS at a reverse proxy (or a tunnel) for any public deployment; tokens are bearer credentials. Behind a proxy, set ARGUS_FLEET_TRUSTED_PROXY=1 so rate limits key on the real client IP, and add Strict-Transport-Security at the proxy.
• Run as non-root. The published images already do (uid 10001) and ship a HEALTHCHECK; the k8s example uses a read-only root filesystem and drops all capabilities.
• Restrict exposure. IP-allowlist or VPN-gate the control plane where possible; a non-default port and /metrics behind the token trim opportunistic scanning.
• Pin versions of the package and images so a mid-development change cannot reach a deployment.
• Secrets: use *_TOKEN_FILE / Kubernetes Secrets rather than inline env vars where you can; never commit tokens.

Supply chain

• Releases publish to PyPI via OIDC Trusted Publishing with attestations (no stored long-lived credentials).
• A CycloneDX SBOM of the wheel is attached to each GitHub release; the GHCR images (argus, argus-fleet) ship their own SBOM and max provenance attestation.
• CI runs CodeQL and a pip-audit dependency audit on every change, and Dependabot watches dependencies.
• The repo's threat model documents assets, trust boundaries, and the threats Argus defends against.