Every knob that configures a Chainsaw deployment: environment variables, YAML keys, and server flags, with their defaults.

Most of this configures the chainsaw-proxy server. A subset applies to the free CLI — the CHAINSAW_SERVER target, the telemetry toggles, and the offline switches. A server-only value set for the CLI has no effect.

If you are on managed Chain305, almost nothing here needs setting: these are the knobs behind a deployment you run yourself, whether that is the CLI on a workstation, a self-hosted proxy, or the K8s admission webhook.

Every environment variable the server and CLI read is on this page. That is enforced: a build fails when code reads a variable this page does not document.

Contents

• A1. Mode / umbrella switches
• A2. Risk / intelligence engine
• A3. Auth / signup / security
• A4. Policy enforcement
• A5. Scanners / detection
• A6. Observability / telemetry
• A7. Operational toggles
• A8. UI feature flags (ui_new/)
• A11. Background workers (env-gated, default-OFF)
• A13. Optional / experimental scanners + intelligence (env-gated, default-OFF)
• A14. Hardening and limit controls
• B1. Server bootstrap
• B2. Database (Postgres)
• B3. Blob store
• B4. Metadata store
• B5. Message queue
• B6. Cache
• B7. Leader election
• B8. Auth secrets / keys
• B9. Observability values
• B10. Policy / release / webhooks
• B11. Docker layer scanning sizing + inspector
• B12. Hidden-Unicode scanner
• B13. Provenance trust roots
• B14. Intelligence refresh tuning
• B15. Reaper
• B16. Upstream HTTP
• B17. ClamAV
• B18. Email / LLM / billing
• B19. Misc server
• B20. UI runtime endpoints (server-side env)
• B21. UI runtime endpoints (client-side, baked at build)
• B27a. Background-worker tuning
• B27b. Hardening / phone-home values
• B27c. K8s admission webhook CLI flags
• B27d. CLI flags
• B27e. Webhook destination columns (webhooks table)
• B27f. Auth-surface per-IP rate limits
• B27g. Audit-export ceiling
• B27h. Random token entropy
• B27. CLI / installer (client-side env)
• B28. HuggingFace proxy
• B30. Credential env-var vocabulary

Precedence

For the Go server, highest → lowest:

env vars → explicit CLI flags → DB-persisted settings → YAML config → hardcoded defaults

Note the middle two: the settings table outranks the YAML file, not the other way round. That is deliberate and it is what makes the admin UI work — a blocking-mode or ClamAV toggle set in the dashboard writes a settings row, and that row has to survive the next restart even though the YAML on disk still says something else.

The YAML is a seed, not a live source. Passing --config imports the file into the settings table (keys the operator declared explicitly overwrite; the rest seed-if-absent), and from that point the DB row is what the server reads. A boot without --config never re-reads the file at all — the server WARNs when it detects a YAML edited in place since the last import, because those edits do not take effect until you pass --config again.

YAML still wins in one important case: a key the settings table does not hold. The store is layered onto the boot config rather than replacing it (config.OverlayFromStoreForOrg), so an absent row leaves the YAML/flag/default value standing instead of resetting it to the Go zero value.

This section previously read “env vars → CLI flags → YAML config → DB-persisted settings”, which was wrong in two ways. YAML did not outrank the DB — the DB copy replaced it wholesale — and CLI flags were silently dropped on any boot that did not also pass --config, because the store-loaded config replaced the flag-patched one. Both are fixed; flags are now re-applied after the store merge, so an explicitly-passed flag really is the highest non-env source.

Every field of the config struct must either round-trip through the settings layer or be listed as deliberately ephemeral with a reason; a reflection test (core/config/roundtrip.go + roundtrip_test.go) fails CI when a new field is neither.

This precedence holds for every key. It did not always: loadAndPersistConfig used to replace the whole config with a settings-table-hydrated copy built from an explicit key list, so any YAML block the list omitted was reconstructed at its zero value. The store is now layered over the YAML/flag/default config — a settings row wins for the key it holds, and a key with no row keeps the value already in memory. See B29 for which keys the table does and does not hold.

PART A — FEATURE FLAGS

A1. Mode / umbrella switches

A2. Risk / intelligence engine

Security note — these two Swift knobs are different risks and deliberately do not share a default. Do not align them.

git_fallback_enabled clones a URL the operator wrote down. github_convention guesses a URL from a package name, and nothing in SE-0292 binds an identifier to a repository. With the convention on and no allowlist, SwiftPM asking for acme.utils makes Chainsaw clone github.com/acme/utils — so anyone who registers the org acme on GitHub has their code served as the legitimate package, by the security proxy itself. That is scope squatting, and the proxy would be the delivery mechanism.

Wave AF flipped github_convention on to make Swift resolve work out of the box. That contradicted the documented posture and has been reverted. The supported way to resolve Swift packages is swift.identifier_map_path — an explicit identifier → git-URL map, which works with the convention off and is not guessable. Use the convention only when you also pin swift.github_org_allowlist to orgs you control or trust.

Enforcement is two-layer and fails closed: config.SwiftConfig.ValidateForRuntime rejects the unconstrained combination at boot, and swift.NewIdentifierMap rejects it again at the construction choke point (which also catches a github_convention: true set inside the identifier-map file). Both errors name the setting. Air-gapped deployments are covered too: the Swift git fallback now honours CHAINSAW_OFFLINE / runtime.offline and refuses network git operations. | swift.trust_swift_root | off | Trust Apple’s Swift Package Collection root | | malware.enable_ghsa (YAML) | on | Supplementary GHSA malware detection |

A3. Auth / signup / security

A4. Policy enforcement

A5. Scanners / detection

Deprecated compatibility knob: --trivial-path / hooks.trivial.binary_path are accepted but ignored because the scanner runs in-process. Configure the in-process scanner with hooks.trivial.db_path, hooks.trivial.timeout_seconds, and hooks.trivial.max_concurrent_scans.

A6. Observability / telemetry

CLI telemetry is consent-gated, default deny. The chainsaw CLI emits nothing until a human grants consent (chainsaw telemetry on, or the first-run prompt). Declined, undecided, and unreadable consent state all mean do not send — so a CI runner that never answered a prompt transmits nothing, and chainsaw telemetry off genuinely stops the session events, not just the guard events. The consent gate runs before the client is constructed, so a non-consenting run opens no socket and writes no install_id. See TELEMETRY.md. | CHAINSAW_REFUSAL_SHARING | false | Proxy/server only: opt in to sharing refused-package identifying data off-box (fail-closed). The free local guard does NOT use this — it shares identifying data only after first-run consent | | OTEL_EXPORTER_OTLP_INSECURE | true | Disable TLS for OTLP endpoint | | CHAINSAW_EVENTS_PARTITIONED | false | Monthly partitioning of events table | | CHAINSAW_UI_DEBUG_HTTP / NEXT_PUBLIC_* | false | HTTP request/response logging in UI |

Free install-guard telemetry is consent-gated, not env-defaulted. The guard asks once on the first interactive run and sends nothing until the user opts in; CI/non-TTY collects nothing until chainsaw telemetry on. chainsaw telemetry on|off persists the decision; the kill switches above still force-off regardless. See TELEMETRY.md. | CHAINSAW_USE_FALLBACK_DATA / NEXT_PUBLIC_* | false | Mock data fallback in UI |

A7. Operational toggles

A8. UI feature flags (ui_new/)

A11. Background workers (env-gated, default-OFF)

Each gate is env-mode and opt-in. Producer-side wiring (where applicable) is unconditional so the underlying tables grow even when the consumer is off; this keeps the next operator-flip cheap.

A13. Optional / experimental scanners + intelligence (env-gated, default-OFF)

Single-instance escape hatches. Each flag is a process-level toggle the operator flips on the chainsaw container; no PostHog, no DB persistence. Truthy = 1 / true / yes / on (case-insensitive). Wave-4 flags also accept a comma-separated ecosystem allowlist (e.g. npm,pypi) for per-ecosystem canarying.

A14. Hardening and limit controls

Single-purpose escape hatches and dev/CI gates added by the production-readiness audit-fix sweep. All default OFF; production should leave them unset.

Pre-existing additions also referenced by the audit fix wave: CHAINSAW_ALLOW_PRIVATE_UPSTREAMS (A4 above) is the escape hatch for legitimate on-prem SIEM/webhook destinations whose hostnames resolve to RFC1918 / loopback. Corrected 2026-08-23: this row previously claimed it was used by internal/webhook/ssrf.go::ValidateURL. It is not, and never was — the flag is read only by the dial-time guard in core/httpclient (SafeDialer, and the SIEM CEF raw-TCP SafeNetDial path). The create/update validators do not consult it, so an operator who set it expecting to save an RFC1918 webhook URL got a rejection with no explanation. Use CHAINSAW_ALLOW_CGNAT_UPSTREAMS for tailnet destinations; it is honoured at both layers precisely because a URL you cannot save is a hatch that does not work. Cloud-metadata literals (169.254.169.254, 100.100.100.200, 192.0.0.192, fd00:ec2::254) are refused under every flag combination. CHAINSAW_XREPLICA_SINGLEFLIGHT (A7 above) is the correct env var name for the cross-replica single-flight gate (a stale CHAINSAW_XREPLICAFLIGHT typo in the README was fixed under Y-Y6).

PART B — CONFIGURATION PARAMETERS

B1. Server bootstrap

CLI flags (cmd/chainsaw-proxy/main.go): --config, --user-config, --listen (:8787), --log-level (info), --admin-password, --password-file, --blob-store (data/blobs), --http-timeout (30s), --max-idle-conns (100), --index (data/index.json), --release-age (0), --hook-script, --hook-timeout (5).

YAML: server.listen, server.admin.username (admin), server.tls.{cert_file,key_file,min_version=1.2}, blob_store.root, index.path, exceptions.path, exceptions.age_days.

B2. Database (Postgres)

• CHAINSAW_DATABASE_URL, CHAINSAW_DATABASE_READ_URL
• CHAINSAW_BILLY_DATABASE_URL — DSN for the least-privilege billy_ro Postgres role: a second pool where row-level security, not a predicate in a query string, decides which tenant’s rows exist (core/pgstore/rls.go). Billy’s named query tools (query_events, query_policies) prefer this pool and fall back to the ordinary read pool when it is unset — their SQL is server-authored and their org predicate is bound from the session, so they are correctly scoped either way. run_sql, when enabled at all (see CHAINSAW_BILLY_RUN_SQL_DEBUG below), requires it: that tool executes SQL an LLM wrote from attacker-shapeable input, and is refused outright without the boundary underneath it. The remaining Billy tools (lookup_*, check_vulnerabilities, …) keep using the ordinary read pool from CHAINSAW_DATABASE_URL, because billy_ro deliberately cannot see the tables they read. This must be a different Postgres role, not just a different DSN string: RLS binds only a role that is neither the table owner nor a superuser. Startup refuses a DSN resolving to the writer’s role, or to a role with SUPERUSER/BYPASSRLS (pgstore.VerifyBillyRole) — either would silently restore the pre-RLS behaviour. It also refuses two failures that no role attribute reveals: a role covered by any permissive policy other than chainsaw_org_isolation, including through role membership (GRANT chainsaw TO billy_ro hands it the chainsaw_writer_all policy, whose qual is true, while rolsuper and rolbypassrls both still read false), and a Billy-readable table with row-level security switched off — the state the documented incident rollback in docs/OPERATIONS.md#migrations leaves behind. Both are mutation-verified in core/pgstore/rls_test.go. Unset → run_sql is refused (logged, and surfaced to the model as a rejection) and the database-level tenant boundary is not installed; the rest of Billy, including the named query tools, is unaffected. There is deliberately no fallback to CHAINSAW_DATABASE_URL for run_sql. migrate() creates the role NOLOGIN and grants it column-level SELECT on events, policies, repositories, package_metadata; the operator gives it credentials out of band (ALTER ROLE billy_ro WITH LOGIN PASSWORD '…' NOSUPERUSER NOBYPASSRLS). Setup and the pre-rollout check for other readers: MIGRATIONS.md.
• CHAINSAW_BILLY_RUN_SQL_DEBUG — default unset (off). Set to 1 to offer Billy’s free-form run_sql tool again. Internal debugging only. run_sql lets the model author SQL from a context that includes attacker-controlled package text (a README reaches it as untrusted data), and the SQL guard documents three verified residual bypasses it cannot close, so the only real boundary under it is RLS. The named tools query_events and query_policies cover the questions it was actually used for with typed parameters and a server-authored org predicate, so the default is off — for the authenticated tenant tier as well as the public docs tier. With the flag off the tool is neither offered to the model nor dispatchable if the model emits it anyway, and it is absent from the system prompt. The flag cannot widen the docs-public tier: that tier is gated on an explicit allowlist which run_sql is not in, and never becomes part of.
• Pool: CHAINSAW_DB_MAX_OPEN_CONNS, _MAX_IDLE_CONNS. CHAINSAW_DB_POOL_SIZE is NOT read by any code — the two names above are the real knobs (parsed in cmd/chainsaw-proxy/init_database.go). Two Prometheus alert annotations in monitoring/alerts.yml still tell on-call to “scale CHAINSAW_DB_POOL_SIZE”; that instruction is a no-op.
• Lifetimes: CHAINSAW_DB_CONN_MAX_LIFETIME_SECONDS, _CONN_MAX_IDLE_TIME_SECONDS, _STATEMENT_TIMEOUT_SECONDS
• Read replica: CHAINSAW_DB_READ_MAX_OPEN_CONNS, _MAX_IDLE_CONNS, _CONN_MAX_LIFETIME_SECONDS, _CONN_MAX_IDLE_TIME_SECONDS
• Compose: POSTGRES_USER (chainsaw), POSTGRES_PASSWORD (chainsaw), POSTGRES_DB (chainsaw)

B3. Blob store

CHAINSAW_BLOBSTORE_TYPE (file|s3). S3: CHAINSAW_S3_ENDPOINT, _REGION, _BUCKET, _ACCESS_KEY, _SECRET_KEY, _SESSION_TOKEN, _USE_PATH_STYLE, _INSECURE, _SSE, _KMS_KEY_ID, _KEY_PREFIX.

CHAINSAW_S3_INSECURE (default off) sends blob-store traffic in plaintext HTTP. When truthy it rewrites the endpoint to http:// — even an endpoint written as https:// — so cached package bytes cross the network unencrypted and can be read or altered in transit. It is for a local MinIO in development. Do not set it in production. chainsaw-proxy logs it at startup under enforcement posture: controls weakened by environment (core/enforcementposture/inventory.go).

B4. Metadata store

CHAINSAW_META_STORE (auto|sidecar|postgres|file).

B5. Message queue

• CHAINSAW_QUEUE_TYPE (channel|nats|redis), _BUFFER_SIZE, _MAX_DELIVERIES (5), _DLQ_TOPIC
• NATS: CHAINSAW_NATS_URL, _CREDS, _USER, _PASSWORD, _STREAM_PREFIX, _MAX_BYTES, _MAX_MSGS
• Redis queue: CHAINSAW_QUEUE_REDIS_URL, _PASSWORD, _MAXLEN

B6. Cache

• CHAINSAW_CACHE_TYPE (""|redis), CHAINSAW_CACHE_KEY_PREFIX
• Redis: CHAINSAW_CACHE_REDIS_URL, _USERNAME, _PASSWORD, _POOL_SIZE, _MODE (standalone|sentinel|cluster), _SENTINEL_MASTER, _SENTINEL_ADDRS, _CLUSTER_ADDRS, _TLS
• Top-level alias set: CHAINSAW_CACHE_REDIS_URL, _PASSWORD, _KEY_PREFIX, _MODE, _POOL_SIZE, _TLS

B7. Leader election

CHAINSAW_LEADER_TYPE (local|redis|postgres), CHAINSAW_LEADER_REDIS_URL, CHAINSAW_LEADER_TTL_SECONDS (1800).

CHAINSAW_RATELIMIT_REDIS_URL — Redis for the shared rate-limit budgets (public Billy chat, run_sql, API buckets), independent of leader election. Unset: the leader’s Redis client is reused when CHAINSAW_LEADER_TYPE=redis, else buckets are in-process (exact at one replica, per-replica beyond it). A malformed URL fails startup rather than silently falling back. The Billy buckets are FailOpen:false, so an unreachable Redis makes public Billy refuse requests. Manifest: dockerized/k8s/redis-ratelimit.yaml.

B8. Auth secrets / keys

• JWT: CHAINSAW_JWT_SECRET, CHAINSAW_JWT_TTL (24h)
• CLI key lifetime: CHAINSAW_CLI_KEY_TTL (default 90 days, sliding) — how long a key minted by chainsaw auth login survives without being used. The window slides: every authenticated request pushes the deadline out, so an actively used credential never expires and only abandoned ones lapse. That is what makes a non-never default safe — a fixed TTL would log out every user and every CI job on the same day. Set 0 (or 0s) for the old unbounded behaviour. A malformed or negative value falls back to the default and logs invalid cli key ttl; using default — deliberately not to never, since a typo must not silently return a deployment to unbounded credentials. Applies to newly minted keys only; keys issued before this shipped keep expires_at NULL and are never retro-dated.
• TLS: CHAINSAW_TLS_CERT_FILE, CHAINSAW_TLS_KEY_FILE, CHAINSAW_TLS_MIN_VERSION (1.2)
• Encryption envelope chain: CHAINSAW_INTEGRATION_ENCRYPTION_KEY → CHAINSAW_SSO_ENCRYPTION_KEY → CHAINSAW_TOTP_ENCRYPTION_KEY (32-byte hex)
• TOTP key rotation: CHAINSAW_TOTP_ENCRYPTION_KEY_NEW — the new key during a rotation, read only by chainsaw-proxy -rotate-totp-key (a dry run unless -rotate-totp-key-apply is also given). Every stored secret is re-sealed in one transaction; only after the apply run succeeds do you move the value into CHAINSAW_TOTP_ENCRYPTION_KEY and restart. Swapping the main key without this locks out every 2FA user. Read in internal/server/authapi/totp_rotate.go.
• Server identity: CHAINSAW_SIGNING_KEY, CHAINSAW_SIGNING_KEY_FINGERPRINT — not implemented. Neither name is read by any Go file, shell script, container manifest or UI file in the repository; setting them has no effect on what the server signs. Policy-bundle signature verification is gated by CHAINSAW_REQUIRE_SIGNED_POLICY_BUNDLE (§B10) and release signing happens in CI, not from server env. Rows kept so the names are not re-documented as live.
• Test rotation: CHAINSAW_TEST_ENCRYPTION_KEY_A/_B
• Captcha: TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY (+ NEXT_PUBLIC_TURNSTILE_SITE_KEY)

B9. Observability values

• CHAINSAW_LOG_FORMAT (text|json)
• OTEL: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME (chain305). CHAINSAW_OTLP_ENDPOINT is documented elsewhere as an alias but is not read by any code — only OTEL_EXPORTER_OTLP_ENDPOINT is (cmd/chainsaw-proxy/main.go, internal/observability/tracing.go).
• Telemetry: CHAINSAW_TELEMETRY_ENDPOINT

B10. Policy / release / webhooks

• CHAINSAW_POLICY_EVAL_CACHE_TTL_SECONDS (60), CHAINSAW_POLICY_BUS_DSN
• CHAINSAW_RELEASE_MIN_AGE_DAYS, release_policy.min_age_days
• Webhook retry: CHAINSAW_WEBHOOK_MAX_ATTEMPTS (1), _RETRY_BASE_MS (1000), _RETRY_MAX_MS (32000), _BUFFER_SIZE, _FAILURE_THRESHOLD, _ORG_RATE_LIMIT
• CHAINSAW_WEBHOOK_LEGACY_PERUSER_ROUTING (default off) — restores the legacy install.blocked / install.flagged routing keyed off the client credential’s created_by_user_id. Off, those events fan out org-wide, which is the safer default: a security signal belongs to the org, not to whichever CI user created the credential. Only for operators mid-migration off the per-user path. Wins over YAML runtime.webhook_legacy_peruser_routing. Read in core/config/offline.go.
• Slack connector (Connectors Phase 2, gated by connectors_slack_oauth): CHAINSAW_SLACK_CLIENT_ID, CHAINSAW_SLACK_CLIENT_SECRET — the Slack OAuth app credentials used by /api/connectors/slack/oauth/{start,callback}. Both must be set for the install flow to start (it returns HTTP 501 otherwise). The client_secret is sent only in the server-side oauth.v2.access POST body and is never logged. The bot token returned by the exchange is encrypted at rest (oauth_token_ciphertext, via CHAINSAW_INTEGRATION_ENCRYPTION_KEY — see §B8). The OAuth callback redirect URI is derived from CHAINSAW_PUBLIC_BASE_URL (§B1) and must be registered in the Slack app’s allowed redirect URLs. The bot-token chat.postMessage client is pinned to slack.com and dials through the SafeDialer (honoring CHAINSAW_ALLOW_PRIVATE_UPSTREAMS, §A4).
• Bidirectional sync (Connectors Phase 4, gated by connectors_bidirectional): inbound endpoints are POST /api/connectors/slack/events/{connector_id} (authenticated by the Slack v0 request signature — the connector’s Slack signing secret in secret_ciphertext, verified HMAC-SHA256 over v0:{timestamp}:{body} with a 5-min replay window) and POST /api/connectors/jira/events/{connector_id}. Jira classic webhooks carry no HMAC, so the inbound URL is a credential: a per-connector high-entropy token rides in ?token=… (or the X-Chainsaw-Connector-Token header) and is verified against the sha256 stored in the connector config’s inbound_token_hash (constant-time). Treat the configured Jira webhook URL as a secret; rotate by re-issuing the connector’s inbound token. Optionally pin Atlassian’s published egress IP ranges at your edge. Both endpoints resolve org/subject from the stored conversation mapping, never the request body, and dedup every event through connector_inbound_events.
  • Producer fan-out (capture-on-send / sync-on-resolve): when bidirectional is on for an org, a vuln/finding alert that fans out to a Slack-OAuth (bot-token) or Jira connector also records a connector_conversations mapping (the Slack thread_ts / Jira issue key) so a later inbound reply / status webhook / reconcile poll routes back to the right finding or routed violation. When a finding or routed violation is resolved in Chainsaw, a confirmation reply is posted into the captured Slack thread. Both are best-effort and never block the resolution.
  • Jira reconcile poll (finding #12, GA — required because Jira webhook delivery is best-effort): a background worker periodically re-fetches the upstream status for every still-open Jira-issue conversation and reconciles drift through the same idempotent transition shim a webhook uses (no status regression — monotonicity guard; org/subject from the stored mapping, never the polled payload; SafeDialer on the GET /rest/api/3/issue client). Env (ops, not PostHog): CHAINSAW_JIRA_RECONCILE_ENABLED (default off — opt in once a Jira connector is live and connectors_bidirectional is on for the org), CHAINSAW_JIRA_RECONCILE_INTERVAL (15m), CHAINSAW_JIRA_RECONCILE_PAGE_SIZE (100), CHAINSAW_JIRA_RECONCILE_CONCURRENCY (1 — serial, gentle on Jira), CHAINSAW_JIRA_RECONCILE_PER_ROW_PAUSE (0 — optional extra rate-limit between issue polls).

B11. Docker layer scanning sizing + inspector

CHAINSAW_DOCKER_LAYER_SIZE_CAP_BYTES (1 GiB), CHAINSAW_DOCKER_LAYER_SCAN_TIMEOUT_SECONDS (60), CHAINSAW_DOCKER_LAYER_BODY_CAP_BYTES (512 MiB per-layer body buffer). All three are read in internal/hooks/docker_layer_scanner.go. Inspector selector lives in §A5: CHAINSAW_DOCKER_INSPECTOR (eol/oci/both, default both since Wave AF).

Not implemented: CHAINSAW_DOCKER_MALWARE_FEED_URL and CHAINSAW_HUGGINGFACE_MALWARE_FEED_URL are not read by any code. The underlying supplychain.BootstrapConfig.DockerMalwareFeedURL / .HuggingFaceMalwareFeedURL fields exist and are honoured by the syncers, but the only production caller (cmd/chainsaw-proxy/init_server.go) never populates them from the environment. Setting either variable leaves Docker / HuggingFace malware coverage at the embedded seed corpus. internal/server/howtos/tutorials/42-scan-container-image-layers.md still instructs operators to export the Docker one; that instruction is a no-op until the env wiring lands.

YAML hooks.docker_layer.{mode,size_cap_bytes,timeout_seconds} is parsed and defaulted but never consumed — initHooks builds hooks.DockerLayerScannerConfig with only Inspector + Logger, so the scanner falls through to the env vars above on every boot. Use the env vars; hooks.docker_layer.mode: off does not disable layer scanning.

B12. Hidden-Unicode scanner

CHAINSAW_HIDDEN_UNICODE_MAX_FILES (500), CHAINSAW_HIDDEN_UNICODE_MAX_BYTES (50 MiB), CHAINSAW_HIDDEN_UNICODE_THRESHOLD (1), CHAINSAW_HIDDEN_UNICODE_ZEROWIDTH_THRESHOLD (32 — surviving zero-width hits needed before zero-width ALONE moves a verdict; one smuggled ASCII character is ~8 runes). A non-positive or unparseable value falls back to the default. Read in core/hiddenunicode/scan.go.

B13. Provenance trust roots

CHAINSAW_APT_KEYRING, CHAINSAW_RPM_KEYRING, swift.trust_root_bundle_path, swift.identifier_map_path, swift.git_cache_dir, swift.github_org_allowlist (mandatory when swift.github_convention is on — see §A2), swift.swift_registry_url, provenance.disabled_ecosystems (npm/pypi/maven/etc.).

CHAINSAW_PGP_KEYSERVER (default https://keys.openpgp.org) — where Maven PGP verification fetches the signing key named by a signature. The keyserver is the trust anchor: a signature verifies if it was made by whatever key the keyserver returns for that fingerprint; there is no web of trust and no pinned key list. Point it only at a keyserver you trust. Read in core/provenance/pgpverify/verify.go.

npm provenance has no registry key of its own — it follows the npm upstream you already configured. The probe asks <registry>/-/npm/v1/attestations/<pkg>@<ver>, and an attestation only exists on the registry that served the tarball, so asking registry.npmjs.org about a package pulled from a mirror answers about a registry the bytes never came from. Resolution order (config.Config.NPMRegistryURL, threaded through supplychain.BootstrapConfig.NPMRegistryURL into provenance.WithNPMRegistryURL):

1. repositories[].remote.url of the first enabled, non-hosted format: npm repository;
2. remotes.npm.url (the per-format default, seeded from the builtin public registry when neither is set).

Repository first because RepositoryConfig.normalize only copies the format default into an empty repo remote and never the reverse. When neither is set the probe falls back to https://registry.npmjs.org — deliberate and explicit, see defaultNPMRegistryURL in core/provenance/npm.go. provenance.offline still short-circuits every ecosystem before any registry is consulted. On the CLI the equivalent is chainsaw verify npm <pkg> <ver> --source-url <registry>; omitting it keeps the same public fallback.

B14. Intelligence refresh tuning

CHAINSAW_INTELLIGENCE_SERVICE (openssf|osv), _REFRESH_INTERVAL (6h), _REFRESH_MAX_STALENESS (7d), _REFRESH_CONCURRENCY (10), _REFRESH_PAGE_SIZE (1000), _REFRESH_ARTIFACT, CHAINSAW_GITHUB_TOKEN. CHAINSAW_TRIVY_DB_PATH is NOT read by any code — the trivy database location comes only from YAML hooks.trivial.db_path (or --trivial-db). The offline-preflight error string in cmd/chainsaw-proxy/offline.go used to name it; that has been corrected. Datasource (per openssf|trivy_db|epss|clamav_db): refresh_interval_seconds, timeout_seconds, jitter_percent (10).

• CHAINSAW_OSV_BUNDLE_PATH (default /system/osv-bundle.json.gz, the in-image location) — the OSV advisory bundle. The OSV refresher rewrites this file in place, so its parent directory must be writable or the refresher stays dormant. Read in core/intelligence/provider_osv.go.
• CHAINSAW_OSV_REFRESH_INTERVAL (default 6h; Go duration or bare seconds) — OSV bundle refresh cadence. 0, 0s, off, disabled, false or no disables the refresher; CHAINSAW_OFFLINE also disables it. Read in core/intelligence/osv/refresher.go.
• CHAINSAW_TRANSITIVE_DEPTH (default 5, clamped to 10) — how many levels of cached dependencies the transitive-risk rollup walks. A non-positive or unparseable value falls back to 5. Read in core/intelligence/provider_transitiverisk.go.

B15. Reaper

CHAINSAW_REAPER_INTERVAL (24h), CHAINSAW_REAPER_MIN_AGE_HOURS (24).

B16. Upstream HTTP

CHAINSAW_UPSTREAM_MAX_RETRIES (3), CHAINSAW_UPSTREAM_MAX_BACKOFF (30s), CHAINSAW_UPSTREAM_NEGATIVE_CACHE_TTL (30s, capped at 60s; Go duration or bare seconds — how long an upstream error response is cached; read once per process). Per-host: CHAINSAW_UPSTREAM_LIMIT_<HOST>. Observed: _PYPI_ORG, _REGISTRY_NPMJS_ORG, _RUBYGEMS_ORG, _CRATES_IO, _PACKAGIST_ORG, _SEARCH_MAVEN_ORG, _HUGGINGFACE_CO, _HUGOVK_DEV, _AZURESEARCH_USNC_NUGET_ORG. YAML: http_client.{timeout_seconds=60, tls_insecure, max_idle_conns=64}.

B17. ClamAV

clamav.socket_path (/tmp/clamd.socket), clamav.timeout_seconds (60), clamav.max_stream_bytes (512 MiB), CHAINSAW_CLAMAV_SOCKET_ALLOWED_PREFIXES, CHAINSAW_CLAMAV_DB_DIR (a relocated freshclam DatabaseDirectory, probed first by the signature-freshness check; defaults probed after it are /data/clamav, /var/lib/clamav, /var/clamav, /usr/local/share/clamav).

B18. Email / LLM / billing

• Email: POSTMARK_SERVER_TOKEN, POSTMARK_FROM_EMAIL, POSTMARK_MESSAGE_STREAM (outbound)
• Postmark webhook basic auth: POSTMARK_WEBHOOK_USER, POSTMARK_WEBHOOK_PASSWORD — credentials Postmark must present on /api/webhooks/postmark. Unset, or only one set, and every request is rejected as unconfigured. A weak password (under 24 characters, equal to the user, or a stock value) makes the server refuse to register the route at boot. Read in cmd/chainsaw-proxy/init_server.go and internal/server/postmark_webhook.go.
• LLM: OPENROUTER_API_KEY, OPENROUTER_MODEL, BILLY_MODEL (google/gemini-2.5-flash), BILLY_FALLBACK_MODELS (comma-separated fallback list — empty disables failover; non-empty wires the FailoverCompleter with a per-model circuit breaker, see docs/ARCHITECTURE.md#billy-safety-matrix)
• Billy public docs tier: BILLY_DOCS_CORPUS_PATH — the published llms-full.txt the public docs_search tool retrieves from; it must be a PUBLISHED artifact, never internal source. Unset, the corpus is empty. BILLY_PUBLIC_TOKEN_KEY — HMAC key for public-tier session tokens; unset, one is derived from the JWT secret with a domain-separation label, and with neither, minting is disabled (fails closed). Read in internal/billy/public_tier.go and internal/server/public_billy_token.go.
• Paddle: PADDLE_ENV, PADDLE_API_KEY, PADDLE_CLIENT_TOKEN, PADDLE_WEBHOOK_SECRET, PADDLE_PRICE_{PRO,UNLIMITED}_{MONTHLY,ANNUAL}
• Signup gating: CHAINSAW_BLOCKED_EMAIL_DOMAINS, CHAINSAW_BLOCK_CONTACT
• Analytics / feature flags (server-side; the CLI and UI never hold these keys): POSTHOG_API_KEY (project ingestion key — with it unset the flag client returns a nil-safe sentinel and every IsEnabled call falls back to the default baked into its call site, so the server runs normally without PostHog), POSTHOG_HOST (self-hosted endpoint), POSTHOG_PERSONAL_API_KEY (opt-in local flag evaluation — the SDK polls an in-memory map every ~30s instead of making one decide() HTTP call per check, which is what makes flag lookups cheap on hot paths), POSTHOG_REVERSE_ETL_KEY + POSTHOG_PROJECT_ID (both required together for the reverse-ETL export; the exporter errors out if either is missing)
• Procurement-kit (GTM W5, lead-form delivery): POSTMARK_PROCUREMENT_KIT_TEMPLATE_ID (Postmark template ID for the kit-delivery email; unset → handler falls back to inline HTML body so the surface is exercisable in dev), CHAINSAW_PROCUREMENT_KIT_URL (overrides the embedded download link; defaults to <base>/procurement/chainsaw-procurement-kit-latest.zip).
• Trust packet: CHAINSAW_TRUST_PACKET_NOTIFY_EMAIL — optional internal mailbox that gets a one-line heads-up per /security trust-packet request. Unset sends no internal mail; the leads table is then the only record. Read in internal/server/leads_trust_packet.go.

B19. Misc server

CHAINSAW_DEFAULT_DOCKER_REPO, CHAINSAW_DEFAULT_DOCKER_ORG, CHAINSAW_WEB_UI_URL, CHAINSAW_HOWTOS_DIR, CHAINSAW_API_BASE_URL, CHAINSAW_DOCS_URL, geoip.db_path, hooks.{request_script,timeout_seconds=5,docker_layer.*}.

B19a. Source-forge API tokens (repo-activity intelligence)

Optional. The repo-activity signal reads commit/contributor statistics from the forge that hosts a package’s source. Each token is used only to raise that forge’s anonymous rate limit — unset means anonymous requests, which work until the limit is hit and then degrade the signal rather than failing the scan. Grant read-only scopes; none of these need write access.

B20. UI runtime endpoints (server-side env)

CHAINSAW_API_BASE_URL, _INTERNAL_API_BASE_URL, CHAINSAW_API_ORIGIN, CHAINSAW_API_BASEPATH, _UI_BASEPATH, NEXT_APP_BASEPATH, NEXT_APP_HOSTNAME, CHAINSAW_UI_DIR, CHAINSAW_API_AUTH_HEADER, _API_USERNAME, _API_PASSWORD, _API_BASIC_AUTH. CHAINSAW_API_SESSION_COOKIE is not implemented — no Go, shell or UI file reads it; the dashboard’s session cookie name is not configurable. Name kept here so it is not re-documented as live.

The Go server reads four of these too (client-guide URLs, hardening bundle callback URLs, the request base path), and falls back to the build-time spelling when the plain name is unset: CHAINSAW_REPO_BASE_URL → NEXT_PUBLIC_CHAINSAW_REPO_BASE_URL, CHAINSAW_API_BASE_URL → NEXT_PUBLIC_CHAINSAW_API_BASE_URL, CHAINSAW_API_BASEPATH → NEXT_PUBLIC_CHAINSAW_API_BASEPATH, CHAINSAW_API_ORIGIN → NEXT_PUBLIC_CHAINSAW_API_ORIGIN (firstEnv in core/config/client_guides.go, internal/server/server_core.go, internal/server/hardeningapi/bundle.go).

B21. UI runtime endpoints (client-side, baked at build)

NEXT_PUBLIC_CHAINSAW_API_BASE_URL, _API_BASEPATH, _BASEPATH, _API_AUTH_HEADER, _AUDIT_API_BASE_URL, NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST.

B27a. Background-worker tuning

• Feedback tuner: CHAINSAW_FEEDBACK_TUNER_INTERVAL (Go duration, default 1h) — cmd/chainsaw-proxy/init_feedback_tuner.go
• Ownership SLA: CHAINSAW_OWNERSHIP_SLA_INTERVAL (Go duration, default 1m — from ownershipsla.DefaultInterval) — cmd/chainsaw-proxy/init_ownership_sla.go
• Bypass-history snapshotter: CHAINSAW_BYPASS_HISTORY_INTERVAL (Go duration, default 1h) — cmd/chainsaw-proxy/init_bypass_history.go
• Datacleanup loop:
  • CHAINSAW_DATACLEANUP_INTERVAL (Go duration, default 6h)
  • CHAINSAW_FEEDBACK_RETENTION_DAYS (int, default 90) — prunes feedback_events rows older than N days
  • CHAINSAW_NONCE_RETENTION_EXPIRED_DAYS (int, default 7) — prunes hardening_approval_nonces rows past expires_at and never consumed
  • CHAINSAW_NONCE_RETENTION_CONSUMED_DAYS (int, default 30) — prunes consumed hardening_approval_nonces rows; longer window because consumed rows are audit-relevant
  • CHAINSAW_GUARD_BLOCK_RETENTION_DAYS (int, default 90) — prunes guard_block_events on blocked_at and guard_installs on last_seen_at. One knob for both deliberately: a block insert advances its install’s last_seen_at in the same transaction, so a shorter block window can never orphan a live block and a divergent pair could
  • All read in cmd/chainsaw-proxy/init_datacleanup.go (defaults sourced from internal/datacleanup/cleanup.go)
• Dormancy flagger: CHAINSAW_DORMANCY_INTERVAL (Go duration, default 24h), CHAINSAW_DORMANCY_THRESHOLD_DAYS (int, default 14; non-positive falls back to 14) — cmd/chainsaw-proxy/init_dormancy.go
• Exception reminders: CHAINSAW_EXCEPTION_REMINDER_INTERVAL (Go duration, default 1h) — cmd/chainsaw-proxy/init_exception_reminders.go
• Stale-finding reminders: CHAINSAW_STALE_FINDING_REMINDERS_INTERVAL (Go duration, default 1h) — cmd/chainsaw-proxy/init_stale_finding_reminders.go
• SBOM snapshotter: CHAINSAW_SBOM_SNAPSHOT_INTERVAL (Go duration, default 24h) — cmd/chainsaw-proxy/init_sbom_snapshotter.go
• Security digest: CHAINSAW_SECURITY_DIGEST_INTERVAL (Go duration, default 6h, the periodic backstop — a feed refresh normally triggers a pass immediately) — cmd/chainsaw-proxy/init_security_digest.go
• Flywheel capture: CHAINSAW_FLYWHEEL_INTERVAL (Go duration, default 1h) — cmd/chainsaw-proxy/init_flywheel.go
• Inventory drift detector: CHAINSAW_INVENTORY_DRIFT_INTERVAL (Go duration, default 60s) — how often the package_versions write count is compared against the success counter; a >10% divergence logs inventory drift detected. Overridable for testing; leave the default in production. cmd/chainsaw-proxy/init_server.go
• Billy ledger retention: BILLY_LEDGER_RETENTION_DAYS (int, default 30), BILLY_LEDGER_RETENTION_INTERVAL (Go duration, default 6h) — cmd/chainsaw-proxy/init_billy_ledger_retention.go
• Every Go-duration knob above falls back to its default when unset, unparseable or non-positive.

B27b. Hardening / phone-home values

• CHAINSAW_PUBLIC_URL — the API base (including any ingress mount, e.g. https://chain305.com/chainproxy) stamped into hardening bundle scripts and ack-callback URLs. Unset, falls back to CHAINSAW_API_BASE_URL with /api/v1 removed, then to the request host plus its X-Forwarded-Prefix mount. Read in internal/server/hardeningapi/bundle.go.
• CHAINSAW_WEBHOOK_HMAC_SECRET — shared HMAC secret for shadow-mode admission POSTs and the K8s bundle phone-home channel. Required when phone-home is configured. Read in internal/server/admission_shadow_api.go, enforcement/k8s-admission/cmd/server/main.go.
• CHAINSAW_API_BASE_URL / CHAINSAW_REPO_BASE_URL — existing knobs, also consumed by hardening ack-callback URL rendering and client guides.
• POD_NAME — Kubernetes downward-API value used as leader-election identity by the admission webhook. Read in enforcement/k8s-admission/cmd/server/leader.go.

B27c. K8s admission webhook CLI flags

Read in enforcement/k8s-admission/cmd/server/main.go. Each flag mirrors a CHAINSAW_* env var as its default.

B27d. CLI flags

Global output-control flags (CLI UX wave)

Registered on rootCmd.PersistentFlags() in core/cli/root.go — available on every chainsaw subcommand. Purely additive; existing --json/--no-color behaviour is unchanged. The output helpers that read them live in core/cli/output.go.

Guard safety. -v, -o, and -q are now bound at the persistent-flag level. Every chainsaw global flag is registered in chainsawGlobalBoolFlags / chainsawGlobalValueFlags (core/cli/guard_install.go) so a guard subcommand (which runs with DisableFlagParsing) can never leak a chainsaw global to the wrapped package manager. The guard_globalflags_test.go regression test enforces this.

For the related process exit codes (block vs. operational error, and the 1 → 2 behaviour change for operational errors), see docs/ERRORS.md#errors-readme → CLI process exit codes.

• chainsaw doctor --bundle-id=<sha256> — W11 MDM phone-home channel. When supplied with --attest, the attest POST body includes bundle_id; the proxy stamps applied_at on the matching hardening_bundles row. MDM-rendered install scripts pre-fill this from the hardening wizard (/admin/hardening). Defined in core/cli/doctor.go.

Removed in the open-core split: the chainsaw harden CLI family (incl. lint-firewall) was removed; hardening-bundle generation, approval, and emission now live behind the admin wizard at /admin/hardening and the /api/hardening/* API. The generated firewall allowlist is correct by construction (the emitter injects RequiredIntelHosts()), so the standalone firewall linter is obsoleted by regeneration. See docs/RUNBOOKS.md#runbooks-hardened-enforcement.

B27e. Webhook destination columns (webhooks table)

Added by the post-merge migration in core/pgstore/store.go (around L2088); both columns gracefully degrade to legacy behaviour when missing.

• format TEXT NOT NULL DEFAULT 'generic' — body shape: generic, slack, teams. Selects the renderer used by the webhook outbox.
• topic TEXT NOT NULL DEFAULT 'all' — coarse subscription filter: all (every event) or a specific topic key (today: hardening_approvals). ListEnabledForTopicAndFormats filters on (topic = 'all' OR topic = ?) and format IN (...).

B27f. Auth-surface per-IP rate limits

Hard-coded per-IP token-bucket limits on the unauthenticated auth surface — no env tuning today; values live in internal/server/auth_ratelimit.go. Documented here so operators can size CDN/WAF rules around them.

On deny the response is HTTP 429 with a Retry-After: <seconds> header (seconds rounded up to ≥1). IP resolution mirrors the anonymous-scan gate (X-Forwarded-For aware via requestIP, falls back to anonClientID). Cold per-IP buckets are evicted by sweepAuthIPLimiters from StartScanReaper (2h TTL). Turnstile (when configured) runs INSIDE the rate-limit envelope so a CAPTCHA solve still hits the 429 ceiling.

B27g. Audit-export ceiling

GET /api/audit/logs?export=true rejects requests when the estimated row count exceeds the in-memory ceiling. Returns HTTP 413 with error code CHW-4519 CodeAuditExportTooLarge. The dashboard audit view UI is unaffected (paginated reads).

A streaming export replacement is tracked as a TODO — see the comment block immediately above the constant.

B27h. Random token entropy

generateRandomToken (internal/server/auth.go) is the single entropy source for session tokens, JWT signing material, SSO state/nonce/binding, magic-link tokens, and pending-auth tokens. The function reads 256 bits from crypto/rand and base64url-encodes; on crypto/rand failure it returns ("", err) — there is intentionally no fallback path. Bootstrap callers (loadOrGenerateJWTSecret, SSO encryption-key materialisation) treat the error as fatal and refuse to start the process; per-request callers return HTTP 500. The previous wall-clock fallback (base64(time.Now().UnixNano())) was removed and must not be reintroduced.

B27. CLI / installer (client-side env)

CHAINSAW_CONFIG, CHAINSAW_CONFIG_HOME, CHAINSAW_DATA_DIR, CHAINSAW_BIN, CHAINSAW_BIN_SOURCE, CHAINSAW_INSTALL_DIR, CHAINSAW_INSTALLER_URL, CHAINSAW_DEFAULT_SERVER, CHAINSAW_SERVER (alias CHAINSAW_SERVER_URL), CHAINSAW_TOKEN, CHAINSAW_REPOSITORY / _REPO / _REPO_BASE / _REPO_BASE_URL / _REPOSITORY_URL, CHAINSAW_PACKAGE, _PACKAGE_ID, _VERSION, _URL, _METHOD, _STATUS_CODE, _HOST, _LOGICAL_PATH, _FROM_CACHE, _FORMAT, _FLAGS, _ARGS, _PID, _CLIENT_TYPE, _UI_HOSTNAME, CHAINSAW_REPLICAS.

Install guard (chainsaw npm/pip/go, core/cli/guard_*.go): CHAINSAW_GUARD_DB — path to the local known-malicious cache the guard merges on top of its embedded floor; written by chainsaw guard update (the one opt-in networked command). Default: <user-cache>/chainsaw/known_malicious.json. The guard’s default path is offline and sends nothing. Its other env:

• CHAINSAW_GUARD_ALLOWLIST — path to the local waiver file. Default: guard_allowlist.json in the CLI config dir. Every coordinate in that file is let through, so whoever controls this path controls what the guard waives.
• CHAINSAW_GUARD_ARTIFACT_DIR — directory of pre-staged archives (<dir>/<ecosystem>/<name>-<version>.<ext>) for offline behavioural analysis. Unset: no pre-staged analysis.
• CHAINSAW_GUARD_DEEP — truthy fetches a pinned npm/cargo archive from the registry to analyse it BEFORE install. This is a network egress, announced once on stderr and recorded in guard_state.json; CHAINSAW_OFFLINE always wins over it.
• CHAINSAW_GUARD_NPM_REGISTRY (default https://registry.npmjs.org), CHAINSAW_GUARD_CARGO_BASE (default https://static.crates.io) — where deep mode fetches from. Set them to the registry your package manager actually installs from, or the guard analyses a different copy than the one that gets installed.

chainsaw doctor --upgrade-check / --fix (core/doctor/doctor.go) also reads CHAINSAW_FLAGS and CHAINSAW_ARGS (scanned for removed CLI flags). Its TLS check resolves the cert and key the way the server does: CHAINSAW_TLS_CERT_FILE / CHAINSAW_TLS_KEY_FILE (§B8) win, per field, over YAML server.tls.{cert_file,key_file} from --config (or CHAINSAW_CONFIG). It cannot see a path stored only in the database settings table, and says so when it finds none.

Cargo credentials (core/cli/cargo_credentials.go). lookupCargoCredentials walks four sources and takes the first hit, in this order:

Error messages name which of the four a malformed credential came from.

B27i. Third-party and OS environment variables the CLI reads

Not Chainsaw configuration — these are variables the CLI consumes because they already govern something it has to locate or respect. Listed so the set is complete and so nobody re-adds a Chainsaw-prefixed alias for a variable the ecosystem already owns.

B28. HuggingFace proxy

Built-in seeded repository (builtinRepositories[].huggingface in core/config/config.go). Defaults map to upstream huggingface.co with AnonymousAccess: true (HF public models don’t require credentials), 600s negative-cache TTL, and a 120s upstream timeout.

Error codes for the HF surface live at internal/errcodes/registry_huggingface.go (CHW-8301 … CHW-8313) — CHW-8307 repo-name invalid, CHW-8308 LFS SHA missing, CHW-8309 LFS object not found, CHW-8310 LFS path invalid, CHW-8311 LFS object too large, CHW-8312 LFS OID mismatch, CHW-8313 LFS size mismatch. See docs/ERRORS.md for human-readable descriptions.

ML-model intelligence (pickle-opcode scan, AI-artifact provider, capability detection) runs on HF artifacts automatically via internal/intelligence/premium/provider_aiartifact.go — no separate enable flag. Per-ecosystem coverage: run chainsaw policy preflight against your server (the same matrix is POLICY_PROXY_MATRIX.md in the source repo).

B30. Credential env-var vocabulary

Chainsaw issues two unrelated kinds of credential, and one variable name — CHAINSAW_TOKEN — is used for both. Nothing here is being renamed: the forms below are different shapes, not synonyms, so neither converts into the other, and every rename breaks a customer already scripted against the old name. This table is the map instead (P8-30, ruled 2026-09-02).

Verified against the code that consumes each value, not against the surfaces that teach it.

The two credentials

They are disjoint in both directions, and this is enforced by the parsers, not by convention. A c305_… key contains no colon, so splitTokenCredential returns ok=false and a package fetch 401s. An <id>:<secret> pair has no c305_ prefix, so IsAPIKey is false, the request falls through to the JWT branch, and signature parsing fails. Pasting either into the other’s slot produces a 401 with no hint about which credential was wrong.

Because the split is SplitN(…, ":", 2), a client_id may not contain a colon; a client_secret may. Everything after the first colon is the secret.

Variable-by-variable

Converting between the forms

• Split pair → combined: "$CHAINSAW_CLIENT_ID:$CHAINSAW_CLIENT_SECRET". Plaintext, one colon, no quoting beyond the shell’s own. Never base64-encode it: the proxy splits a Bearer token on a literal :, and base64 output has none, so an encoded value fails with E401 client credentials required on the first request. Authorization: Basic is the one place base64 is correct, and the tool builds that header itself.
• Combined → split pair: split on the first colon.
• Either → a management-API key: impossible. Mint one at Access → API keys. There is no derivation, and no endpoint accepts both.

Present-but-empty means anonymous

An empty --token "" or an exported-but-empty CHAINSAW_TOKEN= is a decision, not an omission: the CLI treats it as “no credential” and does not fall back to the keyring / file credential store for that server. It used to — viper folds an empty value to unset, so a job whose secret was never populated, or an operator who cleared the variable to run anonymously, was silently authenticated with whatever the machine had stored. Anonymous-capable commands (doctor, status, scan, intel, guard status, the GitHub Action’s offline path, which exports CHAINSAW_TOKEN: ${{ inputs.token }} with default: "") keep running anonymously; a command that needs a credential exits 3 (ExitConfigAuth) with --token / CHAINSAW_TOKEN is set but empty; refusing to fall back to the stored credential (unset it, or pass a value). A non-empty --token still outranks both the env var and the store. Whitespace-only values count as empty. A YAML token: "" key is not an override (it is migrated to the credential store on first run). Pinned by core/cli/token_empty_test.go.

Why both vocabularies stay

CHAINSAW_TOKEN and CHAINSAW_CLIENT_ID/_SECRET carry different shapes, so standardising on one is a value change, not a rename — every pipeline holding the old name in a secret store breaks, and the failure mode is a 401 with no diagnostic. The cost of keeping both is confusion, which this table pays off; the cost of unifying them is breakage with a deprecation window. Pinned by TestHowtoCredentialVocabularyIsPinnedPerFile and its siblings in internal/server/credential_vocabulary_test.go, plus TestSeedGuidesTeachOnlyTheCombinedTokenVocabulary in core/config/seed_guide_lint_test.go, so a guide cannot switch vocabularies silently.