Environment variables

.env.example is the canonical list; this page is its documented form. Settings are grouped by what they govern, and each required variable states what happens if it is absent.

Required

Four variables must be present in a deployed environment. Two of them are also required in development, and two are generated for you there.

Variable	Default	Purpose
`DATABASE_URL`	—	PostgreSQL connection string. Fatal if unset, in every environment: it is the system of record, and there is nothing sensible to fall back to
`REDIS_URL`	`redis://localhost:6379`	The scan wakeup queue. Startup fails if the address is unreachable
`JWT_SECRET`	—	Signs access and refresh tokens. Minimum 32 characters
`TOKEN_ENCRYPTION_KEY`	—	Master key, AES-256-GCM. Exactly 64 hex characters (32 bytes)

Generate both secrets with openssl rand -hex 32. JWT_SECRET_PREVIOUS (optional) is set only while rotating JWT_SECRET: the old secret, which still verifies the tokens it signed — each token names its key in a kid header — but never signs a new one. Set it to the old value when you install the new JWT_SECRET, keep it for REFRESH_EXPIRY days (default 7), then remove it. Rotating without it logs every user out. It must be at least 32 characters and must differ from JWT_SECRET.

What happens when a secret is missing

It depends on ENV, and that is the point. In development or test, the backend generates 32 random bytes per process and logs loudly that it did so. There is no setup step, and sessions do not survive a restart. A previously hardcoded default for JWT_SECRET — the same published literal the config layer defaulted to — meant anyone who read the repository could forge a token for any user. That was a real security finding, and generating an ephemeral key is what replaced it: a key that does not exist cannot leak. In any other environment, a missing or weak secret is a fatal startup error. Values equal to or prefixed by a known placeholder are refused at any length, in any environment, because a placeholder that once shipped in a repository is public by definition. TOKEN_ENCRYPTION_KEY is a master key from which the cursor-signing key, the webhook signing secret and the secret-finding salt are all derived. Setting one value sets all four, so a deployment cannot forget one and silently fall back to an empty secret. Rotating it makes every stored provider token unreadable and forces users to reconnect their accounts; there is no key-rotation mechanism yet.

Server

Variable	Default	Purpose
`ENV`	`production`	A security control, not a label. Anything other than `development` — unset and `test` included — is treated as deployed and validated strictly, so a typo or a forgotten variable fails closed
`PORT`	`8080`	The API listener. Canonical across the compose file, the Dockerfile and every OAuth redirect URI

Frontend origins

DASHBOARD_URL is also the whole CORS allow-list, and CORS permits credentials, so it matters more than a display URL would. WEBSITE_URL is not on the allow-list: the website never calls the API, and because the website and the API are usually same-site, listing it would let any script on the website read authenticated API responses.

Variable	Default	Purpose
`WEBSITE_URL`	`http://localhost:3001`	The marketing site origin (used by deployment scripts; not a CORS origin)
`DASHBOARD_URL`	`http://localhost:3002`	The dashboard origin, and the only origin allowed to make credentialed cross-origin API calls

There is deliberately no wildcard option. A previous AllowOrigins: "*" let any origin call the API with a stolen bearer token, which combined with a token readable from localStorage turned any XSS into a full account takeover. Sessions are HttpOnly cookies with SameSite=Lax, which imposes a deployment constraint: the API and the dashboard must share a registrable domain. api.example.com and app.example.com do; example.com and example.net do not. The default arrangement proxies the API under the dashboard’s own origin, which is same-site trivially.

Sessions and tokens

Variable	Default	Purpose
`JWT_EXPIRY`	`15`	Access token lifetime in minutes. Keep it short: an access token cannot be revoked before it expires
`REFRESH_EXPIRY`	`7`	Refresh token lifetime in days. Refresh tokens are revocable, stored only as a SHA-256 hash, and single-use — presenting a rotated one revokes the whole family

Data

Variable	Default	Purpose
`MIGRATIONS_PATH`	`migrations`	Where the `.sql` migration files live. `/app/migrations` inside the image

Redis is an optimisation, not the system of record. Job state lives in PostgreSQL, so losing Redis costs latency rather than work — see Scaling.

Scanning

Variable	Default	Purpose
`SCAN_WORKER_ENABLED`	`true`	Run the scan worker inside the API process, so one binary with a database and a Redis is a complete TRUSTIVAN. Set `false` on API replicas once workers run separately
`SCAN_CONCURRENCY`	`2`	Concurrent scans per worker process. Bounded on purpose: the engine shares an on-disk cache, so unbounded concurrency produces lock contention rather than throughput
`SCAN_TENANT_CONCURRENCY`	`4`	How many scans one tenant may have running at once when its plan cannot be read. Normally the plan’s concurrent-scan limit decides (Free 1, Pro 5, Enterprise 20). A throttle, not a quota — excess work stays queued
`SCAN_TIMEOUT_MINUTES`	`10`	Hard bound on a single scan. Scanning untrusted caller-supplied input without one is a denial-of-service vector against a shared worker
`SCANNER_CACHE_DIR`	engine default	Where the blob and vulnerability-database caches live. Persist it, or every worker restart re-downloads roughly 50 MB

See Scanning for how these interact.

Registry policy

Variable	Default	Purpose
`SCAN_ALLOW_PRIVATE_REGISTRIES`	`false`	Permit registries on loopback or private addresses. Link-local stays refused. Leave it false unless you understand what you are enabling
`SCAN_ALLOWED_REGISTRIES`	empty	Comma-separated exact-match allow-list of registry hosts. Empty means any public registry; setting it supersedes the private-address rule for the hosts named
`SCAN_ALLOW_PRIVATE_GIT_HOSTS`	`false`	Permit repository targets on loopback or private addresses. Link-local stays refused
`SCAN_ALLOWED_GIT_HOSTS`	empty	Comma-separated exact-match allow-list of git hosts. It narrows which hosts may be named and does not open private addresses

The private-address rule is checked on the target when a scan is requested, and again on every connection the scan makes, after the name is resolved. See Scanning. These are about network reachability, not authentication. Credentials for registries that require a login are stored per registry host through /api/v1/registry-credentials and are not configured by environment variable — a secret in a process environment is a secret in docker inspect, in a crash dump and in every child process.

Vulnerability database

Variable	Default	Purpose
`VULN_DB_PROVIDER`	`upstream`	`upstream` pulls from the engine’s public infrastructure; `mirror` pulls from a registry you operate
`VULN_DB_REPOSITORIES`	—	Required when the provider is `mirror`. Startup fails if empty rather than silently reaching for the public internet
`VULN_DB_JAVA_REPOSITORIES`	—	The Java database, same rules
`VULN_DB_OPERATOR`	—	Who operates the mirror. Recorded for attribution
`VULN_DB_MAX_AGE_HOURS`	`48`	Beyond this age, a scan’s result carries a caveat and is reported as stale
`VULN_DB_HARD_MAX_AGE_HOURS`	`336`	Beyond this (14 days), scanning is refused rather than reported

See Vulnerability database, which is where the reasoning behind two thresholds belongs.

Threat intelligence: KEV and EPSS

The two feeds the risk score reads. The worker fetches each on a schedule, stores it, and re-applies it to every stored finding. Nothing is fetched at startup, and a failed fetch never stops the process: the previous data stays in force, the error is recorded, and the data is flagged stale as it ages. GET /api/v1/system/status reports each feed’s source, version, age, staleness and last error.

Variable	Default	Purpose
`KEV_SOURCE`	`url`	`none`, `file` or `url`. The CISA Known Exploited Vulnerabilities catalogue, which CISA publishes under CC0
`KEV_URL`	the CISA feed	An https mirror of the catalogue. Redirects to plain http are refused
`KEV_PATH`	—	Required when the source is `file`. Re-read on every refresh, so replacing the file is how an air-gapped site updates
`KEV_TIMEOUT_SECONDS`	`60`	Fetch timeout
`EPSS_SOURCE`	`none`	Opt-in. FIRST asks for attribution when EPSS is used in a product and publishes no licence, so fetching it is your decision. `url` fetches the published daily file
`EPSS_URL`	the FIRST daily file	An https mirror of `epss_scores-current.csv.gz`
`EPSS_PATH`	—	Required when the source is `file`. Gzipped or plain CSV
`EPSS_TIMEOUT_SECONDS`	`60`	Fetch timeout
`RISK_FEED_REFRESH_HOURS`	`24`	How often the feeds are fetched and the risk pass re-runs over every finding. A failed fetch is retried hourly

A URL source goes through the same SSRF-guarded transport as webhook delivery, so it cannot reach a private or link-local address. An in-perimeter mirror is served with the file source. See Risk scoring.

Rate limiting and webhooks

Variable	Default	Purpose
`RATE_LIMIT_PER_MINUTE`	`600`	Requests one credential may make per minute. Counted per API key, per workload credential and per session rather than per tenant, so one runaway CI job cannot lock its colleagues out of the dashboard
`TRUSTED_PROXIES`	—	Comma-separated IPs or CIDRs of the reverse proxies in front of the API. Only from these peers is `TRUSTED_PROXY_HEADER` believed as the client address. Unset, the client is the TCP peer — so behind a proxy, every client shares the sign-in limiter’s per-IP allowance. An invalid entry stops the server from starting
`TRUSTED_PROXY_HEADER`	`X-Forwarded-For`	The header a trusted proxy sets. Its first address is used, so the proxy must overwrite `X-Forwarded-For` rather than append to it; use `X-Real-IP` for a proxy that appends
`WEBHOOK_ALLOW_PRIVATE_DESTINATIONS`	`false`	Allow webhook delivery to loopback and private addresses. Development only

The rate limit is protection, not billing — nothing here meters usage or prices a plan. It is generous on purpose: a pipeline polling a scan every two seconds for ten minutes makes three hundred requests, and a limiter that interrupts legitimate work teaches customers to retry harder. WEBHOOK_ALLOW_PRIVATE_DESTINATIONS logs a prominent warning when enabled, and the server refuses to start with it set when ENV is not development. Even when set, the link-local range 169.254.0.0/16 — which hosts cloud instance metadata — stays blocked.

Observability

Variable	Default	Purpose
`METRICS_ADDR`	`127.0.0.1:9090`	Where Prometheus metrics are served, on its own listener, never on the public API

Metrics are cross-tenant aggregates, so binding this to 0.0.0.0 publishes facts about your business to anything that can route to the host. See Health and metrics.

Identity providers

Optional. Configure only the providers you intend to offer.

Variable	Default	Purpose
`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `GITHUB_REDIRECT_URI`	—	GitHub sign-in
`GITHUB_APP_ID`, `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET`, `GITHUB_PRIVATE_KEY`	—	The GitHub App, for repository access
`GITHUB_WEBHOOK_SECRET`	—	Required whenever the GitHub App is configured and `ENV` is deployed. Without it deliveries cannot be authenticated, and unsigned deliveries are rejected rather than trusted
`GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`, `GITLAB_REDIRECT_URI`	—	GitLab sign-in
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI`	—	Google sign-in

Redirect URIs default to http://localhost:8080/api/v1/auth/<provider>/callback and must match what is registered with the provider.

Outbound mail

Optional. With no relay, address verification, password reset, invitation mail and email alerts answer that mail is not configured (503, mail_unavailable: true); invitations still work, and the administrator is handed the link to send. See Send mail through your SMTP relay.

Variable	Default	Purpose
`SMTP_HOST`	—	The relay. Empty means no mail
`SMTP_PORT`	`587` (`465` with `tls`)	The relay port
`SMTP_FROM`	—	Sender address. Required with `SMTP_HOST`
`SMTP_USERNAME`, `SMTP_PASSWORD`	—	Relay credentials, both or neither
`SMTP_TLS_MODE`	`starttls`	`starttls` (the relay must offer STARTTLS; no plaintext fallback), `tls` (implicit TLS), or `none` (a local relay; refused with credentials outside development)
`BRAND_NAME`	`TRUSTIVAN`	The product name in mail subjects, bodies and the From display name
`REQUIRE_EMAIL_VERIFICATION`	`false`	Refuse a password sign-in until the address is verified. Needs `SMTP_HOST` outside development

A half-configured relay — any SMTP_ variable without SMTP_HOST, or a host without SMTP_FROM — stops the process at startup. Links in mail point at DASHBOARD_URL.

Settings that no longer exist

S3_* were declared but never read, and were removed. If you find them in an old .env, they do nothing. (SMTP_* were removed the same way and have since returned with real meaning; see above.) The MinIO service they configured was removed along with them — it is AGPL-3.0, the one copyleft licence whose network clause reaches a service, and an unused dependency is cheap to delete and expensive to explain in a compliance review.

Installation

Configuration

Operations

CLI reference

Environment variables

Required

What happens when a secret is missing

Server

Frontend origins

Sessions and tokens

Data

Scanning

Registry policy

Vulnerability database

Threat intelligence: KEV and EPSS

Rate limiting and webhooks

Observability

Identity providers

Outbound mail

Settings that no longer exist

​Required

​What happens when a secret is missing

​Server

​Frontend origins

​Sessions and tokens

​Data

​Scanning

​Registry policy

​Vulnerability database

​Threat intelligence: KEV and EPSS

​Rate limiting and webhooks

​Observability

​Identity providers

​Outbound mail

​Settings that no longer exist

Required

What happens when a secret is missing

Server

Frontend origins

Sessions and tokens

Data

Scanning

Registry policy

Vulnerability database

Threat intelligence: KEV and EPSS

Rate limiting and webhooks

Observability

Identity providers

Outbound mail

Settings that no longer exist