Config Reference

Every field in wardline.yaml, grouped by section. Config maps 1:1 to this shape (internal/platform/config/config.go).

Top level

Field	Type	Purpose
`listen`	string	Address Wardline binds to, e.g. `0.0.0.0:8080`.
`upstream`	string	Upstream MCP server URL.
`policy_file`	string	Path to the policy file.
`policy_backend`	string	`yaml` (default), `opa`, or `cedar`.
`grpc_listen`	string	`host:port` for the gRPC listener — required when `features.grpc_transport` is true. See gRPC Transport.
`grpc_upstream`	string	Upstream gRPC target (`host:port`, plaintext) — required when `features.grpc_transport` is true.
`grpc_upstream_tls`	bool	Dial the gRPC upstream over TLS instead of plaintext. Default false. See gRPC Transport.
`shutdown_delay_seconds`	int	How long a replica keeps serving requests normally after receiving SIGTERM/SIGINT before it begins its own drain sequence. Zero (the default) preserves current shutdown behavior exactly: draining begins the instant the signal arrives. An in-process substitute for a Kubernetes `preStop` hook — see High Availability.
`features`	map[string]bool	Feature flags — see each feature’s own page.

`audit`

Field	Type	Purpose
`output`	string	`stdout` or a file path.
`postgres_dsn`	string	Only used when `features.postgres_storage` is true. Shared by every Postgres-backed feature (audit, credential revocation/refresh, budget, job/cost budget, SCIM, anomaly baselines/blocks/tenant aggregates) — not audit-specific despite living here.
`postgres_max_open_conns`	int	Size of the ONE connection pool shared by every Postgres-backed feature (see `postgres_dsn` above). Default 25 when unset/zero. See Budget Enforcement’s “Known limitations” for the fail-open behavior under sustained load beyond this.
`retention_days`	int	Age past which audit entries are purged by the retention job. Only meaningful when `features.log_retention` is true; see `retention`.

`budget`

Field	Type	Purpose
`requests_per_window`	int	See Budget Enforcement.
`window_seconds`	int	Window length in seconds.
`tenants.<name>.requests_per_window` / `.window_seconds`	int×2	Per-tenant override of the two global fields above, keyed by tenant name. A tenant absent from this map uses the global default unchanged. Only one level deep — a nested `tenants.acme.tenants.*` is silently ignored, not an error.
`tools.<name>.requests_per_window` / `.window_seconds`	int×2	Per-tool override, same shape and same one-level-deep caveat as `tenants` above.

`tracing`

Field	Type	Purpose
`otlp_endpoint`	string	`host:port`, no scheme.
`service_name`	string	Defaults to `"wardline"`.

`credential`

Field	Type	Purpose
`identities_file`	string	Path to the identities file.
`signing_key_file`	string	Optional PEM RSA key path — see HA Deployment. Mutually exclusive with `kms.key_id`.
`previous_signing_key_files`	list of string	PEM RSA private keys whose public halves are accepted for verification only — the key-rotation window. Empty (default) means no rotation in progress.
`access_token_ttl_seconds`	int	How long an issued access token is valid for. 0 (default) uses 900s (15m). Negative is a validation error.
`refresh_token_ttl_seconds`	int	How long an issued refresh token remains redeemable. 0 (default) uses 86400s (24h). Negative is a validation error.
`kms.key_id` / `.region`	string×2	AWS KMS-backed signing key instead of a local PEM file — the private key never leaves KMS. `region` optional (defaults to the AWS SDK’s own region resolution). Mutually exclusive with `signing_key_file`. See HA Deployment.
`bootstrap_source`	string	`presharedsecret` (default), `oidc`, or `mtls`. See SSO and mTLS/SPIFFE Bootstrap.
`oidc.issuer` / `.jwks_uri` / `.audience` / `.identity_claim` / `.tenant_claim`	string×5	Single-IdP OIDC bootstrap. `jwks_uri` optional (resolved via discovery when unset). See SSO.
`oidc_providers`	list	Multi-IdP OIDC bootstrap — a list of the same 5 fields `oidc` above has, one entry per issuer, routed by the token’s own `iss` claim. Mutually exclusive with `oidc`. See SSO’s “More than one IdP” section.
`spiffe_workload.socket_path`	string	Unix socket of the local SPIFFE Workload API (a SPIRE agent). Optional — defaults to the `SPIFFE_ENDPOINT_SOCKET` env var when unset. Requires `features.spiffe_workload_identity`. See mTLS/SPIFFE Bootstrap.
`spiffe_workload.upstream_peer_id`	string	The exact SPIFFE ID Wardline requires the gRPC upstream to present. Optional but recommended — without it, any SPIFFE-authenticated peer is accepted.
`mtls.header`	string	The header name Wardline trusts to carry an already-verified SPIFFE ID from a terminating mTLS proxy/mesh. No default — required when `bootstrap_source: mtls`. See mTLS/SPIFFE Bootstrap.

`dashboard`

Field	Type	Purpose
`allow_insecure_session_cookie`	bool	Default false (Secure). Set true only for a genuinely plaintext-HTTP deployment (local dev, loopback-only) — a Secure cookie is never sent over plain HTTP. See Web Dashboard’s login flow.

`rbac`

Field	Type	Purpose
`config_file`	string	Path to the roles/bindings file.

`anomaly`

Field	Type	Purpose
`output`	string	Anomaly log output.
`buffer_capacity`	int	Ring buffer size.
`gc_interval_seconds`	int	State garbage-collection interval.
`window_seconds`	int	Detection window.
`rate_spike.enabled` / `.rate_multiplier` / `.min_calls`	bool/float/int	Rate-spike heuristic.
`novel_tool.enabled`	bool	Novel-tool heuristic.
`deny_rate_spike.enabled` / `.threshold` / `.min_calls`	bool/float/int	Deny-rate-spike heuristic.
`ml_score.enabled` / `.score_threshold` / `.min_calls`	bool/float/int	Combined z-score heuristic (`min_calls` must be ≥ 2). See Anomaly Detection.
`auto_block.enabled` / `.score_threshold` / `.block_duration_seconds`	bool/float/int	Rejects a flagged identity’s calls for a bounded TTL. Requires `ml_score.enabled`.
`drift_detection.enabled` / `.k` / `.h` / `.min_calls`	bool/float/float/int	CUSUM control chart over `call_rate` and `tool_diversity`, catching sustained drift a per-window z-score test misses. `k`/`h` are in units of the scored feature’s own baseline standard deviation (Montgomery’s SPC defaults: `k: 0.5`, `h: 4.0`–`5.0`). Requires `ml_score.enabled`. See Anomaly Detection’s “Drift detection” section.
`drift_detection.h_jitter_fraction` / `.jitter_secret_file`	float/string	Optional moving-target defense: perturbs each identity’s own effective `h` by up to this fraction, keyed by HMAC-SHA256 of a per-deployment secret (`jitter_secret_file`, required whenever the fraction is > 0). Raises the cost of an attack calibrated to the public default `h` — does not defeat an adaptive attacker who can probe the live system repeatedly, and in isolation remains vulnerable to an attacker minting disposable identities to re-roll for a favorable draw; `identity_churn` (below) is the actual defense against that specific rotation exploit. See “Adversarial scenarios” in the same doc.
`tenant_anomaly.enabled` / `.rate_multiplier` / `.min_calls`	bool/float/int	Detects a coordinated call-volume spike aggregated across every identity in a tenant — closes the gap no per-identity heuristic can (see “Adversarial scenarios”). Logs only, never auto-blocks: there is no single identity to block for a tenant-level signal. HA-safe when `features.postgres_storage` is also on: window totals merge atomically across replicas; falls back to per-replica, in-memory-only aggregation otherwise.
`identity_churn.enabled` / `.rate_multiplier` / `.min_new_identities`	bool/float/int	Detects a burst of never-before-seen identities aggregated across a tenant, per window — the fingerprint of an attacker discarding identities caught by per-identity heuristics (including `h_jitter_fraction`’s own per-identity jitter) and retrying fresh ones. Logs only, same “no single identity to block” reasoning as `tenant_anomaly`. HA-safe when `features.postgres_storage` is also on: window totals merge atomically across replicas; falls back to per-replica, in-memory-only aggregation otherwise. See “Adversarial scenarios” in the same doc.
`identity_churn.cusum_enabled` / `.k` / `.h`	bool/float/float	Optional CUSUM (cumulative-sum) extension over `identity_churn`’s own window totals, closing the slow-trickle gap `rate_multiplier` alone can’t: one new disposable identity every many windows, individually always below `rate_multiplier`, still accumulates toward and crosses `h`. Same `cusumStep` mechanics `drift_detection.k`/`.h` already use for `call_rate`/`tool_diversity` — a separate, independent `k`/`h` pair, not a reuse of `drift_detection`’s (no single identity to jitter here).
`retention_days`	int	Age past which anomaly-log entries are purged. Only meaningful when `features.log_retention` is true.

`scim`

Field	Type	Purpose
`bearer_token_env`	string	Env var holding the SCIM bearer token (never inline) — required when `features.scim` is true. See SCIM.
`persist_postgres`	bool	Persist provisioned group→member bindings in Postgres (requires `features.postgres_storage`). Default in-memory.

`federation`

Only meaningful when features.federation is true (which itself requires features.anomaly_detection). See Federation.

Field	Type	Purpose
`instance_id`	string	Unique instance identifier. Defaults to `os.Hostname()` — set explicitly when co-locating instances.
`peers_file`	string	Path to the peers file (`id`, `endpoint`, `public_key_file` per peer) — required.
`signing_key_file`	string	PEM RSA private key this instance signs its summaries with — required.
`shared_secret_file`	string	Shared secret (byte-identical across peers) for pseudonymizing fingerprints — required.
`publish_interval_seconds`	int	How often signed anomaly summaries are published to peers.
`min_instances_for_correlation`	int	Distinct instances that must see a fingerprint before an alert (must be ≥ 2).
`correlation_window_seconds`	int	Window over which fingerprints from peers are correlated.
`gc_interval_seconds`	int	Stale correlation-state eviction interval.

`compliance`

Only meaningful when features.compliance_scheduled_export is true. See Compliance Evidence Export.

Field	Type	Purpose
`scheduled_export_interval_seconds`	int	How often a scheduled evidence bundle is exported.
`scheduled_export_output_dir`	string	Directory each tick’s bundle is written to — required when the flag is on.
`signing_key_file`	string	Optional PEM RSA private key to sign each scheduled bundle. `""` (default) produces unsigned bundles.

`retention`

Only meaningful when features.log_retention is true. A single shared cadence for both the audit and anomaly retention checks (whichever of audit.retention_days / anomaly.retention_days is non-zero).

Field	Type	Purpose
`check_interval_seconds`	int	How often the retention purge job runs.

`taint`

Only meaningful when features.taint_tracking is true. See Taint Tracking.

Field	Type	Purpose
`untrusted_sources`	list of string	Tool names whose invocation taints the calling (tenant, identity, session).
`declassify_sources`	list of string	Tool names that clear an existing taint.
`ttl_seconds`	int	How long a taint persists before expiring on its own.
`session_window_seconds`	int	Fallback session-window width used when a call carries no session header.
`session_header`	string	Header name carrying an explicit agent session ID.

`approval`

Only meaningful when features.approval_workflow is true. See Approval Workflow.

Field	Type	Purpose
`grant_ttl_seconds`	int	How long an approved grant remains valid before requiring re-approval.

`job_budget`

Only meaningful when features.job_budget is true. See Job Budget.

Field	Type	Purpose
`requests_per_job`	int	Per-job request ceiling.
`session_window_seconds`	int	Fallback session-window width used when a call carries no `X-Wardline-Session` header.

`job_cost_budget`

Only meaningful when features.job_cost_budget is true. See Cost Budget.

Field	Type	Purpose
`ceiling`	int	Per-job cost/token ceiling.
`tool_costs`	map[string]int	Per-tool cost override, keyed by tool name.
`default_cost`	int	Cost charged for a tool with no entry in `tool_costs`.
`session_window_seconds`	int	Fallback session-window width, same role as `job_budget.session_window_seconds`.