One YAML schema, with env-var overrides.

DFENS is configured from a single YAML file, layered over built-in defaults, with any value overridable from the environment. The image ships a minimal working config so an out-of-the-box container runs with sensible defaults.

How configuration loads

Three layers are merged, later winning over earlier:

1. Built-in defaults. Every key has one, so a config file may set only what it changes.
2. YAML file. Passed with serve --config <path>. The image's entrypoint points this at /etc/ai-firewall/config.yaml.
3. Environment variables. Override any key (see below).

A representative config.yaml:

server:
  listen: ":8080"
  state_dir: "/data"            # must be writable — see deployment

rules:
  dir: "/etc/ai-firewall/rules.d"
  registry_path: "/etc/ai-firewall/registry.yaml"

engine:
  block_response: error         # or "soft"

audit:
  sink: stdout                  # stdout | file | both

auth:
  mode: passthrough             # or "vault"

providers:
  openai:
    enabled: true
  anthropic:
    enabled: true

metrics:
  enabled: true
  listen: ":9090"               # MUST differ from server.listen

admin:
  token_env: "AI_FIREWALL_ADMIN_TOKEN"
  healthz_path: "/health"

Environment-variable overrides

Any key maps to an environment variable: prefix AI_FIREWALL_, and a double underscore (__) for each level of nesting. The double underscore is needed because key names themselves contain single underscores.

server

auth (upstream)

auth.mode controls how DFENS authenticates to the upstream provider. This is separate from inbound client authentication below.

• passthrough (default). The caller sends its own upstream credential (e.g. Authorization: Bearer …) and DFENS forwards it untouched. Keys stay with the caller.
• vault. DFENS injects the provider credential itself, read from the environment at request time, so callers never hold the key. Provider defaults: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, AZURE_API_KEY (or Entra ID), and the AWS credential chain for Bedrock (SigV4). Each variable name is configurable under auth.vault.

Client authentication (inbound)

DFENS can require callers to authenticate to the proxy before any request reaches a provider route or /v1/inspect. It's controlled by admin.client_token_env, the name of an environment variable holding the token:

admin:
  client_token_env: "AI_FIREWALL_CLIENT_TOKEN"   # names the env var…

# …and the value lives in the environment, out of the config file
export AI_FIREWALL_CLIENT_TOKEN=$(openssl rand -hex 32)

Callers then present the token in a dedicated header:

curl -X POST http://dfens.internal:8080/v1/inspect \
  -H "X-AI-Firewall-Key: $AI_FIREWALL_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"hi"}'

• Off by default, backward compatible. When the token resolves to empty, the data plane accepts unauthenticated traffic. Enabling it is opt-in.
• Works in any upstream mode. Independent of auth.mode; you can require a client token in passthrough mode too.
• Never leaked upstream. DFENS strips X-AI-Firewall-Key before forwarding, so it never reaches the model provider (it uses a dedicated header rather than Authorization precisely to avoid colliding with the upstream key).
• Per-tenant. Each tenant can carry its own token via tenants.<name>.client_token_env, falling back to the global one. A tenant's token is rejected on another tenant's traffic.
• Audited & rate-limited. Failed attempts emit an ingress.auth audit event (with a token fingerprint, never the raw token) and are rate-limited per IP via admin.client_auth_rate_limit_per_minute (default 60); successful traffic is never throttled.

providers

Each provider block controls whether its adapter is active and where clean traffic is forwarded. Enabling a provider requires an absolute scheme://host upstream.

Per-provider upstream_timeout defaults to 60s for the enabled three.

rules & engine

The image bakes in the default rule set and registry. To run your own rules, mount a directory over rules.dir (see Deployment).

audit

Every block decision emits a structured JSONL audit event naming the firing rule, its severity, phase, and matched snippet.

• audit.sink: stdout (default), file, or both.
• audit.file_path: /var/log/ai-firewall/audit.jsonl when the sink writes to a file.

stdout is the right default in containers: your existing log pipeline (Fluent Bit, Vector, Loki, Cloud Logging) is the durable record.

metrics

DFENS exposes Prometheus metrics on a separate listener so the metrics surface is never served on the same port as proxy traffic.

admin

The control-plane endpoints (/admin/*: disable/enable a rule at runtime, list state) are token-authenticated and off by default.

Next: Deployment. Docker, Compose, and Kubernetes.