Skip to content

Security

This page is the security reference for operating a self-hosted install: how TruePPM authenticates and rate-limits, what to check before exposing it to the internet, and the procedure to follow after a suspected credential leak (see Secret management). Read it once at deploy time for the Helm secure-by-default checklist, and come back to Reporting vulnerabilities or the breach-recovery steps if something goes wrong later.

TruePPM uses JWT (JSON Web Tokens) via djangorestframework-simplejwt:

  • Access token — short-lived (15 minutes by default), held in browser memory only and sent on every API request as Authorization: Bearer <token>. The short lifetime bounds the blast radius of a leaked access token.
  • Refresh token — exchanged for new access tokens via POST /api/v1/auth/token/refresh/. It rides in an httpOnly, Secure, SameSite=Strict cookie — never in localStorage and never readable by JavaScript, so an XSS bug cannot exfiltrate it. The refresh endpoint reads the token from the cookie.
  • Session persistence (“Remember me”) — the login form’s Keep me signed in choice controls how long the session lasts. Checked issues a persistent cookie (survives browser close) with a long-lived token (30 days by default). Unchecked (the default) issues a session cookie that the browser drops on close, with a short sliding idle lifetime (12 hours by default) — so “don’t remember me” on a shared machine is honored. SSO logins are always session-scoped. Both windows are tunable (TRUEPPM_REFRESH_TOKEN_REMEMBER_DAYS, TRUEPPM_REFRESH_TOKEN_SESSION_HOURS).
  • Rotation and revocation — refresh tokens rotate on every use (ROTATE_REFRESH_TOKENS). The token_blacklist app ships in INSTALLED_APPS by default, so revocation-on-rotation (BLACKLIST_AFTER_ROTATION) is active: once a refresh token is rotated, the previous token is rejected on replay rather than living out its remaining TTL. Logging out (POST /api/v1/auth/logout/) likewise blacklists the presented refresh token. A lean deployment that removes the token_blacklist app degrades gracefully to TTL-only expiry — the refresh/logout endpoints tolerate its absence.

Token lifetimes and the cookie attributes are configurable — see Configuration for AUTH_REFRESH_COOKIE_*.

With the token_blacklist app installed, every issued refresh token is recorded in an OutstandingToken row, and rotated/revoked tokens add a BlacklistedToken row. To stop these tables growing unbounded, a Celery Beat job (access.flush_expired_blacklisted_tokens, nightly at 04:30 UTC) deletes rows whose tokens have already expired — bounding the tables to roughly the active refresh-token window. The job requires a running Celery Beat scheduler (the same one that drives retention and outbox-drain jobs); deployments that run the API without Beat should schedule the flushexpiredtokens management command out-of-band instead. See Management commands.

WebSocket connections authenticate with a short-lived, single-use ticket (?ticket=<ticket>), minted via POST /api/v1/ws/ticket/, so no JWT ever reaches a URL or an access log. The legacy ?token=<jwt> handshake is disabled by default and opt-in only via TRUEPPM_WS_LEGACY_TOKEN_AUTH_ENABLED (deprecated). From 0.5 the handshake also validates the Origin header against ALLOWED_HOSTS and TRUEPPM_WS_ALLOWED_ORIGINS; a refused handshake gets an HTTP 403 on the upgrade, which a browser reports as close code 1006, so the client retries. See WebSocket connections.

Login rate limiting and per-account lockout

Section titled “Login rate limiting and per-account lockout”

The login endpoint carries two stacked throttles, because one of them alone leaves a hole:

ScopeKeyed onDefaultBounds
loginclient IP10/min, fixedGuesses from a single source address
login_accounthashed, normalized submitted username5/min, tunable via TRUEPPM_THROTTLE_LOGIN_ACCOUNT_RATEGuesses against one account, from any number of addresses

The per-IP throttle on its own is not a lockout. A credential-stuffing run from a rotating IP pool gets the full per-IP allowance from every fresh address, so attempts against a single account are unbounded in aggregate — which is exactly the shape of a real attack. login_account keys on the submitted username instead, so targeting one account stays expensive no matter how many addresses participate. The username is hashed before it becomes a cache key: the key needs to be stable and collision-resistant, not reversible.

A request carrying no username skips login_account entirely rather than being charged against an empty-string bucket — the per-IP throttle still applies to those.

This is brute-force hardening, not an org-wide lockout policy. Admin-configurable escalation and unlock workflows are Enterprise capabilities; what is described here is the table-stakes protection every self-hosted install gets.

Auth events themselves are not an Enterprise capability. Recording of single sign-on administration — sso_provider_created, sso_provider_updated (with a per-field before/after diff), sso_provider_deleted, sso_secret_rotated — and of sso_account_linked in the audit log, together with structured trueppm.auth lines for login success and failure, shipped in 0.4 in the community edition. What stays Enterprise is the governed trail layered on top: an immutable, signed, retained trail with SOC 2 evidence export, plus the auth events of the identity-governance layer itself (group→role mapping, enforced org-wide SSO).

Basic single sign-on — pointing TruePPM at your own identity provider so your team logs in through it — shipped in the OSS core in 0.4. Nine providers have a built-in preset (Keycloak, Authentik, Zitadel, Okta, Auth0, Microsoft Entra ID, Google, GitLab, GitHub), and any other standards-compliant OIDC provider — Authelia, for instance — is configured through Generic OIDC with its issuer URL. It is login federation only: no directory sync, no provisioning. The org identity-governance layer (SAML 2.0, SCIM provisioning, LDAP/AD directory sync, enforced org-wide SSO) is an enterprise-edition feature. For why that line falls where it does, and how it compares to the open-core competition, see SSO Is Not an Enterprise Feature.

TruePPM must be served from a single hostname — the SPA, the API, and the WebSocket endpoint routed by path on one origin. There is no CORS support in the codebase (no django-cors-headers, no CORS_* setting), so a browser blocks every cross-origin request from a SPA served elsewhere, and no combination of CSRF_TRUSTED_ORIGINS, TRUEPPM_AUTH_REFRESH_COOKIE_SAMESITE, or CSP_CONNECT_SRC changes that. The secure defaults — SameSite=Strict on the refresh cookie and connect-src 'self' wss: — are correct as shipped for that topology and need no relaxing. See Split-origin deploys and One origin, four variables.

The API sends a strict Content-Security-Policy header on every response, including frame-ancestors 'none' (the app cannot be framed — clickjacking protection) and default-src 'self'. The connect-src directive defaults to 'self' wss: so the SPA can open same-origin XHR and the WebSocket collaboration channel.

That default is complete for the supported single-origin topology. Widen CSP_CONNECT_SRC only for a genuinely external destination — an analytics endpoint, or an object store you serve attachment downloads from directly. Serving the SPA from a different origin than the API is not supported and cannot be fixed here; see Configuration.

Django’s CSP, X-Frame-Options, and X-Content-Type-Options middleware decorate responses Django produces — the API. The SPA’s index.html and its JavaScript bundles are served off disk by nginx and never reach Django, so a correctly-configured API does not protect the document that runs the application. Those headers are set by whichever nginx config your deployment uses, and every shipped path sets the same baseline:

Deployment pathWhere the headers are set
Helmweb.securityHeaders.* — see SPA security headers
Docker Compose (TLS)nginx/app.conf.template, plus Strict-Transport-Security
Docker Compose (HTTP)nginx/app-http.conf.template
Published web image, run directlybaked packages/web/nginx.conf

If you replace the web tier with your own nginx, CDN, or object-store hosting, those headers become yours to set — nothing in the application can add them. scripts/check-nginx-security-headers.sh (CI job nginx:headers) asserts the shipped configs never drift apart on this baseline.

The same nginx tier also sets the Cache-Control policy for the SPA, because a rolling upgrade is a brief window where old and new pods serve different builds. Every shipped path answers:

ResponseCache-ControlWhy
index.html (direct and the SPA fallback)no-cacheAlways revalidate with the origin — cheap, because nginx still sends ETag. A browser’s heuristic freshness on an uncached shell can otherwise keep serving a pre-upgrade index.html that names chunks no pod has any more.
/assets/* hitpublic, max-age=31536000, immutableEvery build ships its JS/CSS under a new content hash, so a cached hit is never stale — it is a different URL next release.
/assets/* missno-storeA transient 404 for a chunk a still-rolling pod has not finished serving yet must never be cached by a CDN or browser — see the blank-page rollout behavior.

If you front the web tier with a CDN (Cloudflare or similar), confirm it honors origin Cache-Control rather than applying its own extension-based defaults, or a 404 on /assets/* can be cached at the edge for everyone behind that PoP, well past the window described above.

TruePPM does not terminate TLS itself — the API container speaks plain HTTP on :8000, always. In production, place a reverse proxy in front of the API and web services:

  • nginx — proxy_pass to the API container; the shipped Compose templates are a working reference
  • Caddy — automatic TLS with Let’s Encrypt
  • Cloud load balancer — AWS ALB, GCP HTTPS LB, etc.
  • Kubernetes — the chart’s Ingress, with cert-manager or your own TLS Secret

Two things must be right whichever you pick, and both have their own failure mode: the proxy has to forward the WebSocket Upgrade / Connection headers and raise its idle timeout, and it has to set X-Forwarded-Proto correctly — settings.prod trusts that header unconditionally, so the API Service must not be reachable directly. Networking has the topology table, a complete cert-manager ClusterIssuer for HTTP-01 and DNS-01, bring-your-own-certificate recipes, and the WebSocket timeout knob for each proxy.

  • PostgreSQL should not be exposed to the public internet
  • Use network policies or firewall rules to restrict access to the API and Celery containers
  • Use a strong, unique password for the trueppm database user
  • Enable PostgreSQL SSL in production

Encrypt the database connection. TruePPM does not force TLS on the database link — the sslmode is whatever your DATABASE_URL specifies. For any deployment where the API and PostgreSQL are not on the same trusted host, append ?sslmode=require (or stricter — verify-ca / verify-full with a CA bundle) to DATABASE_URL. When the API boots in a production configuration (DEBUG=False) with a DATABASE_URL that has no sslmode, it logs an advisory warning so the gap is visible in your logs rather than silent.

The Helm chart generates a strong random password for the bundled PostgreSQL on first install rather than shipping a default credential — see Helm secure-by-default below.

Features that fetch a user- or admin-supplied URL run behind an egress guard that rejects requests resolving to private, loopback, link-local, or otherwise non-public address ranges, blocking the common server-side request forgery (SSRF) vectors.

The guard checks every address a hostname resolves to before connecting, and then resolves once more at connection time, refuses if any answer is non-public, and only dials those checked addresses (re-checking the connected peer as defense in depth) — before the TLS handshake or any request byte is sent. A name that answers the pre-flight lookup with a public IP and the connection’s own lookup with a private one (DNS-rebinding) is therefore refused without ever opening a connection to the private address, so an open and a closed internal port look identical. The hostname is never rewritten, so TLS SNI and certificate hostname verification are unchanged. Webhook delivery, SSO discovery, JWKS, token-exchange and GitHub OAuth/user calls, Jira external task sources, link previews, git-link status refresh, and PAT verification all share this one guarded opener.

Two behaviors to know:

  • The connected-IP guard is for direct egress only. HTTP_PROXY / HTTPS_PROXY / NO_PROXY are honored with urllib’s normal semantics. A request that goes direct (no proxy configured, or the host matches NO_PROXY) gets the connect-time check. A request that goes through a proxy keeps only the resolve-time pre-flight, which refuses a destination host that resolves to a non-public address but is advisory: the proxy does the real resolving, so the proxy must enforce your egress policy. TruePPM logs a one-time warning when a proxied request is first made. This is the same behavior proxied installs had before the connected-IP guard existed, so there is no upgrade action. Using an egress proxy or NetworkPolicy that denies internal ranges remains the right layered defense.
  • The operator egress allow-lists apply identically at connect time (exact, case-insensitive hostname; no wildcards) and are not widened.
  • Each allow-list is scoped to one surface (0.5). TRUEPPM_EGRESS_ALLOWLISTED_HOSTS_SSO (and the legacy TRUEPPM_EGRESS_ALLOWLISTED_HOSTS) exempts a host for single sign-on only; SMTP, Connected Accounts, and webhooks each read their own TRUEPPM_EGRESS_ALLOWLISTED_HOSTS_SMTP / _INTEGRATIONS / _WEBHOOKS list. The purpose is bound into the connection itself, so an in-cluster IdP trusted for SSO cannot be reached through a project Admin’s webhook URL or a user’s pasted git link. A caller that declares no purpose honors no list. In 0.4 a single list applied to every caller.

The SMTP relay is checked with the same deny-list at save and send time, and in 0.5 its connection is dialed through the same connect-time guard: the relay name is resolved once, refused if any answer is non-public, and only those checked addresses are dialed, before STARTTLS or any SMTP byte. STARTTLS and implicit-TLS certificate verification are unchanged. Only TRUEPPM_EGRESS_ALLOWLISTED_HOSTS_SMTP exempts a relay, by exact hostname. In 0.4 the relay host was re-resolved when Django connected, which left a DNS-rebinding window; keep a NetworkPolicy denying internal ranges in front of mail egress as a layered defense.

The two sections above cover requests the server makes. This one covers the end user’s browser, which is a separate egress surface: a request made from there carries the user’s own IP and referrer, and no server-side egress proxy or NetworkPolicy can see it, let alone stop it.

Loading a page of the TruePPM web app makes zero requests to any host other than your own. No font CDN, no analytics, no error-reporting service, no remote scripts or stylesheets. The three typefaces (Space Grotesk, Inter, JetBrains Mono) are vendored into the bundle and served from your origin under /fonts/, licensed SIL OFL 1.1 which expressly permits redistribution.

This matters twice over for a self-hosted install:

  • Air-gapped and network-restricted deployments render correctly. Nothing about the app’s appearance depends on reaching the public internet. Previously a blocked font request meant the whole type scale silently fell back to a substitute face, with no warning to the operator (#2419).
  • No undisclosed third-party data flow. An operator who deployed TruePPM specifically to keep data on their own infrastructure is not quietly emitting a per-page-load request to someone else.

A Playwright assertion (e2e/self-hosted-fonts.spec.ts) fails the build if any third-party request appears on a page load, so this cannot regress silently. It is a whole-origin check, not a font allowlist — the next accidental CDN reference will not be a font one.

Features you turn on can still make outbound calls, and they are opt-in by design and documented where they live: client telemetry and OTLP export (Observability), SMTP delivery (Email), an external identity provider (Single sign-on), and outbound webhooks. Nothing in that list is enabled by default.

  • The cache requires authentication by default in the Helm chart (valkey.auth.enabled: true); a generated password is injected via requirepass. When running your own Valkey/Redis, enable requirepass or keep it on a private network.
  • The cache is used as a broker and Channels layer; it does not store persistent data
  • If the cache is compromised, an attacker could inject WebSocket events or manipulate the Celery task queue
SecretWhere it’s usedImpact if leaked
SECRET_KEYDjango session/CSRF signing; JWT signing when JWT_SIGNING_KEY is unsetFull account takeover — attacker can forge any session or token
JWT_SIGNING_KEY (optional)Access/refresh JWT signing onlyToken forgery for any user — but a leak no longer also compromises session/CSRF signing
INTEGRATION_ENCRYPTION_KEYFernet key for stored third-party secrets: the single sign-on client secret, every user’s stored external-source (Jira) credential, outgoing webhook secrets, board-automation secrets, and the outbound SMTP passwordOffline decryption of every one of those secrets from a database copy
DATABASE_URLPostgreSQL connectionFull data access
REDIS_URLCelery broker, Channels layerTask injection, event spoofing

One encryption key covers every stored third-party secret

Section titled “One encryption key covers every stored third-party secret”

INTEGRATION_ENCRYPTION_KEY is a single primary key. It encrypts the OIDC/OAuth client secret you configure for single sign-on, each user’s stored Jira credential, the secrets of your outgoing webhooks, your board-automation secrets, and the outbound SMTP password. There is no separate key per class, so treat its leak as the leak of every one of them at once. Nothing outside these five is encrypted with this key. Back the key up with your database backups.

To rotate it without losing those values, keep the old key in INTEGRATION_ENCRYPTION_KEY_FALLBACKS and re-encrypt (see Rotating secrets without downtime). Changing the key without a fallback is a recovery event: every stored value becomes undecryptable and an administrator must re-enter each secret (the SSO client secret, each user’s Jira connection, each webhook secret, each board-automation secret, and the SMTP password). A KMS-backed key is an Enterprise hardening item (the design is recorded in the auth architecture).

Each of the three application secrets has a primary value and an optional comma-separated *_FALLBACKS list of additional keys (the incoming key during phase 1, the outgoing key after phase 2). The primary is the only key ever used to sign or encrypt. Fallbacks are accepted for verification or decryption only, so you can roll a new primary out while values created under the old one keep working, then retire the old one.

PrimaryFallback listWhat the fallback keeps working
SECRET_KEYSECRET_KEY_FALLBACKSSigned cookies, password-reset and email-verification links, signing.loads payloads (Django’s own fallback mechanism)
JWT_SIGNING_KEYJWT_SIGNING_KEY_FALLBACKSIn-flight access and refresh tokens. When JWT_SIGNING_KEY is unset it inherits SECRET_KEY, and its fallbacks inherit SECRET_KEY_FALLBACKS
INTEGRATION_ENCRYPTION_KEYINTEGRATION_ENCRYPTION_KEY_FALLBACKSDecrypting stored third-party secrets written under the old key

Every fallback entry is validated at boot exactly like its primary (length, placeholder, Fernet format). A malformed or empty entry (for example a stray comma) stops the process from starting with an error naming the list and the position (SECRET_KEY_FALLBACKS[1]); it is never silently ignored. Error messages never print the key.

Runbook (any of the three) — two phases, never one step:

A rolling restart runs old and new pods side by side (the Helm production values run two API replicas). If you set the new key as primary and keep the old one as a fallback in a single step, a restarted pod signs or encrypts under the new key while a pod that has not restarted yet only knows the old key. That old pod cannot verify a token or session value signed under the new key, or decrypt a secret written under it, so users see 401 responses and sign-outs. The old pods are missing the new key, so the new key must reach every pod as a fallback before it becomes primary.

  1. Generate the new key B (python3 -c "import secrets; print(secrets.token_urlsafe(50))", or a new Fernet key for INTEGRATION_ENCRYPTION_KEY). The current key is A.

  2. Phase 1 — distribute B. Keep A as the primary and add B to the matching *_FALLBACKS variable. Update your Secret, then restart the api, celery-worker, and celery-beat Deployments. Wait until the rollout has finished and every pod of all three Deployments runs the new configuration. Nothing signs under B yet, so nothing can break.

  3. Phase 2 — promote B. Set B as the primary and A as the fallback, update the Secret, and restart the same three Deployments again. Wait until the rollout has finished and every pod of all three Deployments (api, celery-worker, celery-beat) runs B as primary. During this rollout both old and new pods know both keys, so each can verify what the other produced.

  4. For INTEGRATION_ENCRYPTION_KEY, re-encrypt stored values under the new primary. The command measures “already on primary” against the primary key of the pod it runs in, so run it only from a pod on the phase-2 configuration (check the pod’s start time against the rollout first). A pod that has not restarted still holds A as primary and would rewrite B-encrypted values back to A. Then run --dry-run again to confirm nothing is left:

    Terminal window
    python manage.py reencrypt_integration_secrets # rewrites; reports per column
    python manage.py reencrypt_integration_secrets --dry-run # confirm: would rewrite 0, undecryptable 0

    The command covers all five encrypted columns, runs in transactional batches (--batch-size, default 500), and prints one line per column, for example Model.field: rewrote 3, already on primary 12, empty 0, undecryptable 0 (would rewrite N under --dry-run). It is idempotent. It exits non-zero if any value cannot be decrypted by any configured key; add the missing old key to the fallback list and re-run rather than dropping anything. The final dry-run must report would rewrite 0 and undecryptable 0 for every column.

  5. Retire A. After the longest-lived value signed under A has expired, remove A from the fallback list and restart again. For JWTs that is the longer of TRUEPPM_REFRESH_TOKEN_REMEMBER_DAYS (default 30, the “Keep me signed in” refresh lifetime) and 7 days (the lifetime of refresh tokens issued before the remember-me change); a non-remembered session lasts 12 hours (TRUEPPM_REFRESH_TOKEN_SESSION_HOURS). For SECRET_KEY, use your longest password-reset or cookie lifetime; when JWT_SIGNING_KEY is unset, SECRET_KEY also signs JWTs and the JWT fallbacks inherit SECRET_KEY_FALLBACKS, so the wait also covers the refresh-token lifetime above, counted from the end of phase 2 (tokens are still signed under A until then). For INTEGRATION_ENCRYPTION_KEY, remove A only after the final --dry-run in step 4 reports would rewrite 0 and undecryptable 0 for every column.

On Kubernetes, SECRET_KEY, JWT_SIGNING_KEY, INTEGRATION_ENCRYPTION_KEY, and any other application-level key arrive via the envFrom Secret referenced in the production install walkthrough (conventionally named trueppm-env). DATABASE_URL and REDIS_URL are a separate case: the chart always sets them as an explicit env: entry — a secretKeyRef against whichever Secret you pointed env.DATABASE_URL / env.REDIS_URL at (trueppm-db / trueppm-cache in the walkthrough), never through envFrom — because an explicit env: key wins over an envFrom key of the same name, so routing them through trueppm-env would silently not take effect. Rotating either kind the same way — updating the Secret’s data in place via kubectl apply, an External Secrets refresh, a Vault Agent template render — does not restart anything: the Deployment’s pod template is unchanged either way, so Kubernetes has nothing to notice and old pods keep the old value indefinitely. Only the chart’s web tier carries a pod-template checksum annotation, and that one guards its nginx ConfigMap, not either of these Secrets.

After rotating SECRET_KEY, JWT_SIGNING_KEY, INTEGRATION_ENCRYPTION_KEY, DATABASE_URL, REDIS_URL, or any other key delivered either way, restart the three Deployments that read them and otherwise never pick up the new value on their own:

Terminal window
kubectl rollout restart deployment/trueppm-api \
deployment/trueppm-celery-worker deployment/trueppm-celery-beat \
-n trueppm

(Replace trueppm with your release name and namespace if you installed under different ones.) The migrate init container that bootstraps the api pod reads the same values, so restarting that Deployment also re-runs it against whichever one you rotated.

If you run the chart’s demo mode (demo.enabled: true), the demo-reset CronJob and demo-seed Job read the same values too, but need no restart: Kubernetes starts a fresh pod for each of their runs, so the next scheduled reset or seed already uses the rotated value.

A chart-rendered checksum annotation that rolls these Deployments automatically on every Secret change — the same mechanism the web tier’s nginx ConfigMap already has — is tracked in #3405.

Django’s deploy check enforces the key rules at boot, so you can prove a deployment will start before you roll it:

Terminal window
DJANGO_SETTINGS_MODULE=trueppm_api.settings.prod \
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))") \
ALLOWED_HOSTS=example.com \
python manage.py check --deploy --fail-level=ERROR

Each failure has its own id, so the output says which rule you broke: an empty key is trueppm.E001, one still carrying the Django django-insecure- placeholder prefix is trueppm.E002, and one shorter than 32 characters is trueppm.E003. Any of them exits non-zero.

The JWT signing key has its own ids too: a JWT_SIGNING_KEY carrying the Django placeholder prefix or a documented placeholder value is trueppm.E004, and one shorter than 32 characters is trueppm.E015. Attachment storage on ephemeral local disk, or an unusable TRUEPPM_ALLOW_LOCAL_ATTACHMENT_STORAGE opt-in, is trueppm.E014. These ids are what you would put in SILENCED_SYSTEM_CHECKS, and each now names exactly one rule. trueppm.E004 used to also cover the attachment-storage check; if you silenced it, decide about trueppm.E014 explicitly. Likewise trueppm.E005 used to also cover the JWT signing-key length rule (now trueppm.E015; trueppm.E005 is the integration encryption key only), and trueppm.E010 used to also cover the project soft-delete retention check (now trueppm.E016; trueppm.E010 is the DATABASE_URL placeholder password only).

secrets.token_urlsafe(50) produces a ~67-character URL-safe string; store it in your .env (mode 0600) or, on Kubernetes, set the secrets.djangoSecretKey Helm value.

Separating the JWT signing key and forcing a global sign-out

Section titled “Separating the JWT signing key and forcing a global sign-out”

By default the JWT signing key is SECRET_KEY. Setting a dedicated JWT_SIGNING_KEY (optional; same strength rules — ≥ 32 chars, not the django-insecure- placeholder, enforced at boot in production) decouples the two so that:

  • a leaked SECRET_KEY alone can no longer forge tokens; and
  • you gain a rotate-to-sign-everyone-out lever that does not also churn Django’s session/CSRF signing.

To force every user to sign in again (after a suspected token leak or an admin offboarding), rotate the JWT signing key: set JWT_SIGNING_KEY to a fresh value and, on Kubernetes, restart the api, celery-worker, and celery-beat Deployments (docker compose up -d on the Compose deploy — docker compose restart recreates nothing and keeps serving the old key from the running container, silently defeating this rotation). Every outstanding access and refresh token immediately fails signature verification; the web app treats the next call as a 401, attempts one (also-failing) refresh, and routes users to the sign-in screen. No data is lost. If you have not set a separate JWT_SIGNING_KEY, rotating SECRET_KEY has the same effect but also rotates session/CSRF signing. Do not list the old key in JWT_SIGNING_KEY_FALLBACKS when the goal is to sign everyone out.

Deactivating a resource in the Workspace catalog is not one of those paths. It removes the person from rosters and capacity figures but leaves their login, project memberships and API tokens untouched, so the catalog row disappearing does not mean the person is off-boarded. Deactivate the member (Settings → Members) to revoke their credentials, and review their project memberships separately.

The Helm chart installs securely with no extra flags. The full reference lives in the chart README; the operator-facing highlights:

  • Generated datastore credentials. Leave postgresql.auth.password and valkey.auth.password empty and the chart mints a strong random password on first install, persisting it in a chart-owned connection Secret (<release>-trueppm-connection) annotated helm.sh/resource-policy: keep. Re-renders read the existing password back, so helm upgrade never churns the credential or orphans the database PVC. The kept Secret also survives helm uninstall. Retrieve the DB password with:
    Terminal window
    kubectl get secret <release>-trueppm-connection \
    -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d
  • No plaintext credentials in any manifest. DATABASE_URL and REDIS_URL are built server-side and injected via secretKeyRef against the connection Secret — they are never rendered into a Deployment. The bundled datastores read their password from the same Secret, so the server credential and the URL can never drift apart.
  • Cache auth on by default (valkey.auth.enabled: true).
  • Hardened containers. API and worker run with runAsNonRoot, allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, all capabilities dropped, and the RuntimeDefault seccomp profile, with writable emptyDir mounts only where required (/tmp, /app/staticfiles, /run/trueppm). Tune via podSecurityContext / containerSecurityContext.
  • automountServiceAccountToken: false on the API and worker pods.
  • NetworkPolicy on by default (networkPolicy.enabled: true) restricting ingress to the bundled PostgreSQL (5432) and Valkey (6379) to only the pods that legitimately open them — the API, Celery worker, Celery beat, backup, and demo-seed tiers — and applying a default-deny egress posture to the datastore pods themselves. See datastore network isolation for what enforcement requires and how it is verified.
  • Default-deny ingress on the app tier itself (api, web, celery-worker, celery-beat) — this one is not gated by postgresql.enabled / valkey.enabled, so it renders on the recommended production overlay (values-prod.yaml, managed datastores) as well as the bundled-subchart topology. api and web admit only the configured ingress controller (networkPolicy.ingressControllerSelector) plus each other where the chart’s own topology needs it; celery-worker and celery-beat have no Service and admit nothing. Egress is unaffected — this control is ingress-only, same caveat as the datastore policy above. In-cluster monitoring (Prometheus or Blackbox scraping the api Service from another namespace) is dropped unless you name it in networkPolicy.monitoringSelector. The first upgrade that adds these policies refuses to render on the default controller selector until you confirm it; see Upgrading to 0.4. The same refusal also fires on a fresh install with no chart-rendered Ingress when demo.enabled is true or service.web.type is LoadBalancer/NodePort — a tunnel (demo mode’s documented Cloudflare Tunnel path) and a LoadBalancer/NodePort Service both bypass any in-cluster ingress controller entirely, so the default selector is wrong for them rather than merely unconfirmed. See Public read-only demo mode.
  • Django admin off, and denied at the edge. The primary control is the application one: the API answers 404 for every /admin/ path unless env.TRUEPPM_DJANGO_ADMIN_ENABLED is "true", which holds on every topology, including web.enabled: false and a port-forward. As defense in depth the web tier’s nginx answers 403 for /admin/ from every source until you name one (web.adminAccess.allowCIDRs: []), and rate-limits the surface at 5 requests/minute per IP. See Reaching Django admin.

Django admin is a plain Django view, which means none of the API’s login defenses reach it by inheritance. The login throttles are applied by Django REST Framework, which never sees a request to /admin/login/; the auth.login_failed / auth.login_succeeded audit lines are emitted by TruePPM’s own login view; and the enforced-SSO policy hook that single sign-on hangs off is consulted there too. There is also no account-lockout backend in the dependency set. Meanwhile the admin bootstrap creates a superuser on first deploy — so an unrestricted /admin/ is a guessing surface against a known-present privileged account.

From 0.4 the admin is off unless you ask for it. Every /admin/ path answers 404 — not 403, so the path is not even advertised — unless the API is started with:

Terminal window
TRUEPPM_DJANGO_ADMIN_ENABLED=true

This is an application control, not an edge one, so it holds on every topology: Docker Compose, a bare single-server install, a Helm release with the web tier disabled, and a kubectl port-forward straight at the API pod. The web.adminAccess deny below is unchanged and still correct — it is the edge half of the same posture — but it only governs traffic that traverses the web tier’s nginx, and Compose and bare deploys have no such tier.

When you do turn it on, the door is hardened rather than bare. The admin login then carries the same controls as POST /api/v1/auth/token/:

  • The same two throttle buckets — the per-IP login scope and the per-account login_account lockout, sharing one allowance with the API login rather than each door handing out its own. An attacker who spends the budget on one door finds the other already spent. A refused attempt answers 429 with Retry-After.
  • The same audit lines. A failed admin login emits auth.login_failed with the hashed identifier and client IP; a successful one emits auth.login_succeeded with method=admin. Both land on the trueppm.auth logger, so one alerting rule covers both doors — see Login rate limiting and per-account lockout.
  • The same enforced-SSO seam. An account an enterprise policy has blocked from password sign-in is refused here too, with the session torn down again rather than merely a 403 body over a live cookie.

The recommended access path needs no chart change and no exposure at all. Port-forward straight to the API Service, bypassing the web tier (the API must have been started with TRUEPPM_DJANGO_ADMIN_ENABLED=true for this to answer):

Terminal window
# Resolve the API Service by label — the chart's fullname helper collapses the
# release name when it already contains "trueppm", so `helm install trueppm ...`
# yields `trueppm-api` while `helm install foo ...` yields `foo-trueppm-api`.
kubectl port-forward "svc/$(kubectl get svc \
-l app.kubernetes.io/component=api \
-o jsonpath='{.items[0].metadata.name}')" 8000:8000
# then visit http://localhost:8000/admin/

This is the in-cluster equivalent of the SSH tunnel the Docker Compose deployment documents inline (ssh -L 8443:127.0.0.1:443 user@yourserver), and it is the right answer for the occasional administrative task.

If you genuinely need /admin/ on the public listener — a jump host or an office egress range, for example — allowlist it explicitly:

web:
adminAccess:
allowCIDRs:
- 203.0.113.0/24

To remove the path from the public listener entirely — nginx returns 404 instead of 403, so the surface is not even advertised — set:

web:
adminAccess:
enabled: false

Port-forwarding still works, because it never traverses nginx.

The bundled PostgreSQL and Valkey pods speak plaintext on the pod network, so the NetworkPolicy is the transport-security boundary for the bundled dev/demo posture — not a defense-in-depth extra. The chart leans on it directly: it auto-injects TRUEPPM_ALLOW_UNENCRYPTED_DB whenever postgresql.enabled && networkPolicy.enabled, which relaxes the API’s unencrypted-database boot guard on the strength of this isolation.

Enforcement requires a CNI that implements NetworkPolicy — Calico, Cilium, Antrea, or similar. On a cluster whose CNI does not, the policy objects are accepted by the API server and then silently ignored, leaving the datastores reachable from any pod. This is a property of the cluster, not of the chart, and nothing in the chart can detect it.

Two CI gates cover the policy, and they cover different things:

GateClusterWhat it proves
helm:templatenone (render only)The policy objects render, with valid schema, for the current values.
helm:installkind, default CNIThe chart boots with the policy enabled. Does not prove enforcement — kind’s default CNI (kindnetd) does not implement NetworkPolicy, by design, so the objects are admitted and ignored.
helm:netpolkind + CalicoEnforcement itself. Positive probes (every allowed tier reaches the datastores), negative probes (an unlabeled pod, and a pod with the chart’s labels but a non-client component, are both denied), datastore egress default-deny, and two controls proving a denial came from the policy rather than a broken CNI.

helm:netpol runs on every merge request that touches the chart, on main, and nightly. It is the gate that makes the TRUEPPM_ALLOW_UNENCRYPTED_DB auto-injection defensible; before it existed, the isolation the chart relies on was never actually tested.

The app-tier default-deny ingress policies (api/web/celery-worker/ celery-beat, described above) are covered by helm:template only — render-and-assert, not a live CNI-enforcement drill like helm:netpol runs for the datastores. Enforcement still depends on your cluster’s CNI the same way; nothing chart-side proves it beyond the render.

The chart restricts the bundled datastore pods only. It deliberately does not restrict ingress to, or egress from, the API and Celery worker pods: their outbound endpoints (your identity provider, SMTP relay, object store, OTLP collector) are deployment-specific, so a chart-imposed allow-list would break real installs.

Two gaps are therefore yours to close at the platform layer:

  • API pod ingress. settings.prod trusts X-Forwarded-Proto unconditionally, so anything that can open a socket to the API pod on :8000 can claim its request arrived over HTTPS. Restrict that port to the ingress controller / edge. The host is not taken from a header at all — USE_X_FORWARDED_HOST is pinned False, so X-Forwarded-Host is ignored and your edge must preserve the original Host. That keeps the host bounded by ALLOWED_HOSTS rather than by this network rule; see The scheme comes from the proxy; the host does not.
  • API and worker egress. Restrict it to the destinations you actually use.

Ports and firewall is the full source → destination → port matrix to build both allow-lists from, including every optional egress need (SMTP, OIDC, S3/MinIO/SeaweedFS, OTLP, image registry, ACME, outbound webhooks).

Adding a component that talks to a datastore

Section titled “Adding a component that talks to a datastore”

The policy allow-lists clients by app.kubernetes.io/component. A new Deployment, Job, or CronJob that opens PostgreSQL or Valkey must be added to the corresponding list in templates/networkpolicy.yaml, or its connections are dropped on any enforcing cluster — while helm lint, helm template, and helm:install all stay green. helm:netpol is scoped to the whole chart precisely so that adding such a template triggers it.

When you disable the bundled subcharts (postgresql.enabled: false / valkey.enabled: false) to use managed services, the chart can no longer build the connection strings for you, so env.DATABASE_URL and env.REDIS_URL become required — the render fails with a clear message if either is missing.

Both supported shapes are injected via secretKeyRef, so neither renders a credential into a Deployment, Job, or CronJob. They differ in whether the credential passes through Helm:

  • secretKeyRef map (preferred) — the chart points every consumer at a Secret you manage and never sees the URL, so it is absent from your values file, your shell history, and the Helm release Secret.
  • URL string — the chart moves it into the chart-owned connection Secret and injects it from there. It stays out of the workload manifests, but it persists in whatever held it on the way in.

See Deployment, Helm values, and the chart README.

demo.interactive publishes a real login and lets a visitor tour the whole app, read-only. It is a different shape from the plain share-link demo (demo.enabled), which publishes no login at all — see ADR-1197 for the full design. Four layers combine to make it safe to expose:

  1. The write fence is server-side and role-independent. DemoReadOnlyMiddleware refuses every unsafe HTTP method under /api/ except sign-in, token refresh and sign-out — regardless of the visitor’s role. This is the guarantee; the remaining three layers are defense in depth over it.
  2. A method fence at the edge. The web tier’s nginx renders a third server block for this mode: limit_except GET HEAD OPTIONS over /api/, with the same three sign-in paths exact-matched around it. /admin/ and /ws/ still return 404. A request refused here never reaches Django.
  3. Egress-deny on the api and celery-worker pods. This mode needs no outbound access at all — no IdP, no SMTP, no object storage, no OTLP — so the chart restricts their egress to DNS and the bundled PostgreSQL/Valkey pods only, the one exception to the “API and worker egress stays open” rule described in Ports and firewall. It also covers the outbound effects of comments and webhooks, not only the obvious integration path.
  4. Per-account throttles re-aimed for a shared, published credential. Every visitor authenticates as the same account, so a throttle keyed on the account rather than the caller’s IP bounds the whole crowd together. The login-lockout scope described in Login rate limiting is raised in this mode from its ordinary credential-stuffing posture to one sized for concurrent visitors — the per-IP login and anon scopes stay the real limiters for the sign-in request itself only. They do not bound a signed-in visitor’s ordinary reads: DRF’s stock anonymous throttle skips authenticated requests, so once a visitor is signed in, the shared "user" scope (demo.throttle.userRate) is the only throttle on their traffic, with no independent per-IP ceiling. It is set high enough to be effectively lifted — a bucket shared by every visitor fails all of them at once when it trips, so it cannot protect any one of them. This is a shared-fate resource-consumption tradeoff, not a per-visitor fairness guarantee: the real bounds are the api pod’s capacity and whatever edge sits in front of the host (an edge rate limit such as a Cloudflare WAF rule). The demo’s login page tells visitors the limits are lifted for the demo account only. See the demo.throttle.* keys in Helm values.

None of that makes the following true, and the design is deliberately not built assuming they are:

  • A hostname gate in front of the demo (Cloudflare Access or similar) is bot reduction and an email list, not a security control. It is passed by anyone with any working email address and mitigates none of the threat model’s findings. Run one if you want fewer automated signups; do not treat it as a reason to skip the layers above.
  • The scheduled reset (demo.reset) bounds contamination — it prevents nothing. It caps how long a successful write or a piece of vandalism stays visible at one reset interval. It is not a control and must not be cited as mitigating any finding above; with the write fence armed there is normally nothing for it to clean up in the first place.
  • Host isolation from your CI runners is a precondition this chart cannot verify. Give the interactive demo its own host, separate from anything a CI job can reach — no chart flag, render-time guard, or CI job can check this for you, because it depends on infrastructure outside the release. Treat it as a deployment requirement with a human owner, the same way you would treat “do not point this at your production database.”

No writable media path is rendered for the api pod in this mode either way — see persistence.media in Helm values. The bundled Atlas sample’s task attachments are external-link references, not uploaded files, so nothing is lost by that restriction.

All API endpoints enforce role-based access control. See the RBAC documentation for the full permission matrix.

Key security properties:

  • No global admin role — permissions are scoped to individual projects
  • Role escalation prevention — you can only assign roles below your own
  • IDOR prevention — querysets are scoped to the user’s project memberships; non-members see empty results, not 403 errors
  • Last-Owner guard — prevents accidental removal of all project owners

Every artifact TruePPM publishes — the api and web images, the Helm chart, and the trueppm-scheduler / trueppm-mcp / trueppm-api PyPI packages — is signed in the release pipeline before it is published. This has been live since the 0.4 beta (GHCR publishing, #939) for the images, chart, and the trueppm-scheduler / trueppm-mcp packages. trueppm-api’s CI job was migrated onto the same Trusted Publishing + attestation flow in #3943, but the release-tag job that runs it is unproven until the next v* tag — every trueppm-api wheel/sdist on PyPI through 0.4.0-beta.3 was published with a static upload token and carries no attestation; only versions published after #3943’s tag are covered by the claims below. Scanning and SBOM inventory are narrower: see Vulnerability scanning and SBOM below for exactly what each covers — trueppm-api’s PyPI package is signed but does not carry a CycloneDX SBOM.

The api image’s Python dependencies are installed from a hash-verified export of packages/api/uv.lock — the same lockfile CI tests against — rather than a fresh resolution against PyPI at build time. Building the same commit weeks apart therefore produces the same package versions every time. The trueppm-scheduler package is the one exception: it is built from this image’s own copy of packages/scheduler’s source, not resolved from the lock, so the engine you get always matches the commit the image was built from. The image carries the resolved set it installed from at /app/requirements-locked.txt for anyone auditing a running container, and CI’s api:image-lock-check job fails the merge request if a future change ever lets the installed set drift from the lock again.

Trivy scans the api and web images and fails the release on any fixable HIGH/CRITICAL CVE. Base-image CVEs with no available patch (--ignore-unfixed) do not block, since they are not actionable by the operator.

Every image, the Helm chart, and all three PyPI packages are signed keyless — Sigstore, via GitLab’s own ambient OIDC identity, no key material to manage or leak. Verify what you pull actually came from this pipeline:

Terminal window
# Docker images (api, web)
cosign verify \
--certificate-identity-regexp 'https://gitlab\.com/trueppm/trueppm' \
--certificate-oidc-issuer https://gitlab.com \
ghcr.io/trueppm/api:<version>
# Helm chart
cosign verify \
--certificate-identity-regexp 'https://gitlab\.com/trueppm/trueppm' \
--certificate-oidc-issuer https://gitlab.com \
ghcr.io/trueppm/charts/trueppm@<digest>

The trueppm-scheduler, trueppm-mcp, and trueppm-api wheels and sdists carry PEP 740 provenance attestations instead — visible under “View details” on each release’s PyPI page — rather than a Cosign signature, since they publish through PyPI’s own Trusted Publishing attestation flow.

Every published artifact carries a CycloneDX SBOM except the trueppm-api PyPI package, which is signed (see above) but does not yet generate one:

ArtifactGenerated byWhere to find it
api / web imagesSyft, against the exact published imageAttached as a Cosign attestation on the image digest (cosign verify-attestation --type cyclonedx ..., same identity flags as above) — no GitLab access needed — and as a non-expiring api-sbom-<tag> / web-sbom-<tag> CI job artifact
Helm chartGenerated from the chart’s own dependency graph (helm dependency list — the bundled postgresql/valkey subcharts and their versions; it does not describe the container images those subcharts reference)Attached as a Cosign attestation on the chart digest, and as a non-expiring helm-sbom-<tag> CI job artifact
trueppm-scheduler / trueppm-mcpcyclonedx-py, against the locked uv.lock runtime closureAttached to the package’s GitLab Release (scheduler-v<version> / mcp-v<version>) as a CycloneDX SBOM asset link, served from the Generic Package Registry at a stable, versioned URL: https://gitlab.com/api/v4/projects/trueppm%2Ftrueppm/packages/generic/trueppm-scheduler-sbom/<version>/sbom.cdx.json (and trueppm-mcp-sbom), where <version> is the PyPI version — 0.4.0b1, not the tag. Still retained as a non-expiring CI job artifact (packages/scheduler/dist/sbom.cdx.json, packages/mcp/dist/sbom.cdx.json) as a second copy. It is not attached to the PyPI upload itself, which carries PEP 740 attestations rather than an SBOM. The automation attaches this Release asset starting with the first package tag cut after 0.4.0-beta.1; scheduler-v0.4.0b1 and mcp-v0.4.0b1 were cut before that automation existed and were backfilled manually onto their Release pages — for any version published before 0.4.0b1, use the tag pipeline’s artifact

OpenSSF Scorecard (project posture report)

Section titled “OpenSSF Scorecard (project posture report)”

The security:scorecard CI job runs OpenSSF Scorecard against the TruePPM repository on the nightly scheduled pipeline only. It is report-only: the job is allow_failure, never runs on merge requests or pushes, and cannot block a pipeline. There is no minimum score yet; one will be set once a baseline exists.

Reading the result. Open the job log for a per-check list sorted worst first, an aggregate score, and a banner naming every check below 5/10. A low score makes the job exit 2, which GitLab shows as an orange warning rather than green, so a passing-looking job is not read as a good posture. A check marked n/a could not be evaluated on that target and is not counted as low.

Two checks are waived from that warning verdict because Scorecard cannot see the tooling on a GitLab-hosted repository: Fuzzing (the scheduler’s Hypothesis property-based fuzz suites are not counted by Scorecard’s local-mode detector) and SAST (semgrep and bandit run in GitLab CI, and CodeQL runs on the GitHub mirror, but Scorecard only detects SAST from GitHub workflow files and check runs). A waived check still appears in the list, marked [waived: ...], and a line below the list names it, but it does not turn the job orange, so an orange job means a real regression. A waived check that scores 5 or higher prints normally. The waiver list is WAIVERS in scripts/scorecard-report.sh; revisit it whenever the pinned Scorecard version changes, since an improved detector makes a waiver obsolete. The full JSON is kept for 30 days as the scorecard-local.json (and, when enabled, scorecard-remote.json) job artifact.

Scan target. The canonical repository is on GitLab, and the GitHub mirror is read-only, so:

  • --local=. always runs. It needs no token and reads the checked-out tree. Observed with Scorecard v5.5.0, it returns 11 checks: Binary-Artifacts, Dangerous-Workflow, Dependency-Update-Tool, Fuzzing, License, Packaging, Pinned-Dependencies, SAST, Security-Policy, Token-Permissions and Vulnerabilities. In that run Dangerous-Workflow, Packaging and Token-Permissions were not evaluable (no GitHub Actions workflows exist), Fuzzing and SAST scored 0, and Pinned-Dependencies scored 5. SAST scored 0 because Scorecard detected no tool from the file tree, even though semgrep and bandit run in GitLab CI and CodeQL runs on the GitHub mirror. A local run on a developer checkout also counts gitignored files such as __pycache__, so Binary-Artifacts can score lower there than on a clean CI checkout.
  • --repo=gitlab.com/trueppm/trueppm runs in addition when the masked CI/CD variable SCORECARD_GITLAB_TOKEN (scopes read_api, read_repository) is set. Per the Scorecard v5.5.0 README (not run here), Branch-Protection, Code-Review, CI-Tests, Maintained and similar checks need the hosting platform’s API, so they are only possible in this mode, and GitLab support is marked partial (“Validating” or “Unsupported” for several checks). The remote mode has not been run against this project yet. Without the variable the log says remote checks were skipped.
  • The GitHub mirror is not scanned. It does not carry GitLab’s branch protection or review history, so its score would describe the mirror, not the project.

The tool is pinned to a release version with a SHA-256 checksum verified in the job (SCORECARD_VERSION and SCORECARD_SHA256 in .gitlab-ci.yml); bump both together.

Beyond semgrep and bandit, the repository’s CI runs these gates:

  • Semgrep packs. The vendored rules under .semgrep/ cover Python, Django, React, TypeScript, and JavaScript. The job fails if semgrep abandons a file after repeated rule timeouts, so partial coverage is never silent.
  • checkov on the Helm chart. security:checkov:helm renders the chart with default values and hard-gates the Kubernetes hardening checks for non-root containers, no privilege escalation, dropped capabilities, and no NET_RAW. A second, informational pass lists the remaining findings.
  • gitleaks history scan. security:gitleaks:history scans the full git history with .gitleaks.toml on main. Merge requests get the working-tree scan, security:gitleaks.
  • curl redirect hardening. scripts/check-curl-hardening.sh (make curl-hardening-check) fails any tracked *.sh file whose curl follows redirects (-L, --location, or a bundle such as -fsSL) without --proto-redir '=https', which stops a redirect from downgrading to plaintext http://. A site that must allow http carries a comment on the line above the call: # curl-hardening-ok: <reason>. The reason is required. The gate scans shell scripts only, not CI YAML or Dockerfiles.

If you discover a security vulnerability in TruePPM, please report it privately — do not open a public issue. Report through either channel:

  • Email — security@trueppm.com (preferred).
  • Confidential GitLab issue — open an issue in the GitLab repository and tick “This issue is confidential” so it is visible only to project members.

Our full policy — supported versions, response SLAs (2 business days to acknowledge), coordinated-disclosure process, and safe-harbor terms for good-faith research — lives in SECURITY.md at the repository root. We publish a GitLab Security Advisory and credit reporters (unless anonymity is requested) when a fix ships.