# AiFirewallPolicy

The tenant's AI Firewall policy: which providers and models its agents may use, the guardrails the gateway applies to every request.

The tenant's AI Firewall policy: which providers and models its agents may use, the guardrails the gateway applies to every request, the hold for review setting, and capability allow and deny lists. One per tenant. This is the document vulnetix ai-firewall apply reads from .vulnetix/ai-firewall.yaml, and every file that command accepts is valid here; metadata, and metadata.name, may be left out.

The same document is the file `.vulnetix/ai-firewall.yaml`, which `vulnetix ai-firewall apply` reconciles and `vulnetix ai-firewall export` writes. The product reference for that file, with the workflow around it, is [Policy file reference](/ai-firewall/reference/policy-file.md). This page is the schema reference, and covers what the config engine does with the same document.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `AiFirewallPolicy` |
| Group | [AI firewall](/platform-iac/kinds/catalogue.md#ai-firewall) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | one (`metadata.name: default`) |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Applied after | [`AiProvider`](/platform-iac/kinds/ai-provider.md) (deleted before them) |
| CEL fields | `spec.guardrails[].when` (`request`): see [CEL rule expressions](/platform-iac/reference/cel.md) |
| Terraform resource | [`vulnetix_ai_firewall_policy`](/platform-iac/terraform/resources.md#vulnetix_ai_firewall_policy), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.157.0 and later. |
| Pinned schema | [`v1.19.1/AiFirewallPolicy.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/AiFirewallPolicy.schema.json) |
| Newest schema | [`latest/AiFirewallPolicy.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json) |
| First released in | [`v1.1.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.1.0) |
| Print the built-in copy | `vulnetix config schema AiFirewallPolicy` |

## Minimal

Only the fields the kind requires. From `examples/AiFirewallPolicy/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  name: default
```

**HCL** (resource `vulnetix_ai_firewall_policy`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/AiFirewallPolicy/minimal.yaml.

resource "vulnetix_ai_firewall_policy" "default" {
}
```

Every field that has a schema default, set to that default: [`terraform/ai_firewall_policy.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/ai_firewall_policy.tf) and [`yaml/AiFirewallPolicy.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/AiFirewallPolicy.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  name: default
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/AiFirewallPolicy/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  name: default
  org: 6f2a1c3e-0000-0000-0000-000000000001
  labels:
    team: platform-security
  annotations:
    ticket: https://tracker.example.com/SEC-2210
spec:
  prune: true
  settings:
    logsEnabled: true
  baseline:
    enabled: true
    ref: recommended
    exclude:
      - pii-phone
  providers:
    - slug: anthropic
      action: allow
      key:
        fromEnv: ANTHROPIC_PROVIDER_KEY
    - slug: acme-vllm
      action: allow
      key:
        fromFile: ~/.config/acme/vllm.key
    - slug: openrouter
      action: deny
    - slug: groq
      action: default
  models:
    - slug: claude-sonnet-4-5
      provider: anthropic
      anyProvider: false
      action: allow
    - slug: qwen3-coder-30b
      provider: acme-vllm
      action: allow
    - slug: gpt-4o-mini
      anyProvider: true
      action: deny
  guardrails:
    - name: block-aws-keys
      baselineId: secrets-aws-access-key
      ruleType: blocked_pattern
      action: block
      pattern: '(?i)AKIA[0-9A-Z]{16}'
      priority: 10
      enabled: true
    - name: cap-conversation
      ruleType: max_messages
      action: block
      pattern: 200
      priority: 50
    - name: redact-pii
      ruleType: pii_redact
      action: redact
      priority: 20
    - name: sealed-blocks
      ruleType: delimiter_integrity
      action: block
      priority: 5
    - name: strip-shell-for-codex
      ruleType: tool_deny
      action: strip
      pattern: Bash
      priority: 30
      when: client == 'codex'
    - name: flag-filesystem-writes
      ruleType: expression
      action: flag
      priority: 40
      enabled: false
      when: "'filesystem' in mcpServers && tools.exists(t, t.startsWith('mcp__filesystem__write'))"
  capabilities:
    approved-mcp:
      family: mcp
      list: allow
      action: block
      patterns: [github, "linear*"]
    banned-clients:
      family: client
      list: deny
      action: block
      priority: 10
      patterns: [unknown]
  holdPolicy:
    holdUnknown: true
    holdTimeoutMinutes: 240
    holdTimeoutAction: deny
```

**HCL** (resource `vulnetix_ai_firewall_policy`)

```hcl
# Every argument the kind supports. From config-schemas examples/AiFirewallPolicy/advanced.yaml.

resource "vulnetix_ai_firewall_policy" "default" {
  baseline = {
    enabled = true
    exclude = ["pii-phone"]
    ref     = "recommended"
  }
  capabilities = {
    approved-mcp = {
      action   = "block"
      family   = "mcp"
      list     = "allow"
      patterns = ["github", "linear*"]
    }
    banned-clients = {
      action   = "block"
      family   = "client"
      list     = "deny"
      patterns = ["unknown"]
      priority = 10
    }
  }
  guardrails = [
    {
      action      = "block"
      baseline_id = "secrets-aws-access-key"
      enabled     = true
      name        = "block-aws-keys"
      pattern     = "(?i)AKIA[0-9A-Z]{16}"
      priority    = 10
      rule_type   = "blocked_pattern"
    },
    {
      action    = "block"
      name      = "cap-conversation"
      pattern   = "200"
      priority  = 50
      rule_type = "max_messages"
    },
    {
      action    = "redact"
      name      = "redact-pii"
      priority  = 20
      rule_type = "pii_redact"
    },
    {
      action    = "block"
      name      = "sealed-blocks"
      priority  = 5
      rule_type = "delimiter_integrity"
    },
    {
      action    = "strip"
      name      = "strip-shell-for-codex"
      pattern   = "Bash"
      priority  = 30
      rule_type = "tool_deny"
      when      = "client == 'codex'"
    },
    {
      action    = "flag"
      enabled   = false
      name      = "flag-filesystem-writes"
      priority  = 40
      rule_type = "expression"
      when      = "'filesystem' in mcpServers && tools.exists(t, t.startsWith('mcp__filesystem__write'))"
    },
  ]
  hold_policy = {
    hold_timeout_action  = "deny"
    hold_timeout_minutes = 240
    hold_unknown         = true
  }
  models = [
    {
      action       = "allow"
      any_provider = false
      provider     = "anthropic"
      slug         = "claude-sonnet-4-5"
    },
    {
      action   = "allow"
      provider = "acme-vllm"
      slug     = "qwen3-coder-30b"
    },
    {
      action       = "deny"
      any_provider = true
      slug         = "gpt-4o-mini"
    },
  ]
  providers = [
    {
      action = "allow"
      key = {
        from_env = "ANTHROPIC_PROVIDER_KEY"
      }
      slug = "anthropic"
    },
    {
      action = "allow"
      key = {
        from_file = "~/.config/acme/vllm.key"
      }
      slug = "acme-vllm"
    },
    {
      action = "deny"
      slug   = "openrouter"
    },
    {
      action = "default"
      slug   = "groq"
    },
  ]
  prune = true
  settings = {
    logs_enabled = true
  }
  labels = {
    team = "platform-security"
  }
  annotations = {
    ticket = "https://tracker.example.com/SEC-2210"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/ai_firewall_policy.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/ai_firewall_policy.tf) and [`yaml/AiFirewallPolicy.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/AiFirewallPolicy.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  name: default
  org: 6f2a1c3e-0000-0000-0000-000000000001
  labels:
    team: platform-security
  annotations:
    ticket: https://tracker.example.com/SEC-2210
spec:
  prune: true
  settings:
    logsEnabled: true
  baseline:
    enabled: true
    ref: recommended
    exclude:
      - pii-phone
  providers:
    - slug: anthropic
      action: allow
      key:
        fromEnv: ANTHROPIC_PROVIDER_KEY
    - slug: acme-vllm
      action: allow
      key:
        fromFile: ~/.config/acme/vllm.key
    - slug: openrouter
      action: deny
    - slug: groq
      action: default
  models:
    - slug: claude-sonnet-4-5
      provider: anthropic
      anyProvider: false
      action: allow
    - slug: qwen3-coder-30b
      provider: acme-vllm
      action: allow
    - slug: gpt-4o-mini
      anyProvider: true
      action: deny
  guardrails:
    - name: block-aws-keys
      baselineId: secrets-aws-access-key
      ruleType: blocked_pattern
      action: block
      pattern: '(?i)AKIA[0-9A-Z]{16}'
      priority: 10
      enabled: true
    - name: cap-conversation
      ruleType: max_messages
      action: block
      pattern: 200
      priority: 50
    - name: redact-pii
      ruleType: pii_redact
      action: redact
      priority: 20
    - name: sealed-blocks
      ruleType: delimiter_integrity
      action: block
      priority: 5
    - name: strip-shell-for-codex
      ruleType: tool_deny
      action: strip
      pattern: Bash
      priority: 30
      when: client == 'codex'
    - name: flag-filesystem-writes
      ruleType: expression
      action: flag
      priority: 40
      enabled: false
      when: "'filesystem' in mcpServers && tools.exists(t, t.startsWith('mcp__filesystem__write'))"
  capabilities:
    approved-mcp:
      family: mcp
      list: allow
      action: block
      patterns: [github, "linear*"]
    banned-clients:
      family: client
      list: deny
      action: block
      priority: 10
      patterns: [unknown]
  holdPolicy:
    holdUnknown: true
    holdTimeoutMinutes: 240
    holdTimeoutAction: deny
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `AiFirewallPolicy` | Always AiFirewallPolicy. |
| <span id="metadata"></span>`metadata` | object | no |  | no other keys | metadata.org, when set, makes apply refuse to run against any other tenant. |
| <span id="metadata-name"></span>`metadata.name` | string | no |  | exactly `default` |  |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | no |  | no other keys |  |
| <span id="spec-prune"></span>`spec.prune` | boolean | no | `false` |  | Delete guardrails and model entries on the server that this document does not mention. Off by default, so an apply never removes rules someone made in the console. A provider entry is never pruned: clearing a deny opens access. |
| <span id="spec-settings"></span>`spec.settings` | object | no |  | no other keys |  |
| <span id="spec-settings-logsEnabled"></span>`spec.settings.logsEnabled` | boolean | no |  |  | Record per-inference metadata (model, decision, tokens, latency, never the prompt or completion). Paid plans only. |
| <span id="spec-baseline"></span>`spec.baseline` | object | no |  | no other keys | The server's recommended guardrails. Left out, they are added to the desired set; set enabled to false to decline them. |
| <span id="spec-baseline-enabled"></span>`spec.baseline.enabled` | boolean | no |  |  |  |
| <span id="spec-baseline-ref"></span>`spec.baseline.ref` | string | no |  |  | A named baseline set to pin. |
| <span id="spec-baseline-exclude"></span>`spec.baseline.exclude` | array of string | no |  | each item: length 1 to any | Baseline guardrail ids to leave out. |
| <span id="spec-providers"></span>`spec.providers` | array of object | no |  |  | Provider allow and deny entries, and where each provider's API key comes from. A provider with no entry is usable. |
| <span id="spec-providers-slug"></span>`spec.providers[].slug` | string | yes |  | length 1 to any | A built-in provider slug, or the metadata.name of an AiProvider. |
| <span id="spec-providers-action"></span>`spec.providers[].action` | string | yes |  | `allow`, `deny`, `default` | allow pins the provider as allowed, deny blocks it, default removes any pin. |
| <span id="spec-providers-key"></span>`spec.providers[].key` | object | no |  | 1 to any keys; no other keys | Where the client reads the provider API key it uploads. Never the key itself. fromEnv wins when both are set. |
| <span id="spec-providers-key-fromEnv"></span>`spec.providers[].key.fromEnv` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  |
| <span id="spec-providers-key-fromFile"></span>`spec.providers[].key.fromFile` | string | no |  | length 1 to any |  |
| <span id="spec-models"></span>`spec.models` | array of object | no |  |  | Model allow and deny entries. Once a provider has any allowed model, its other models are denied. |
| <span id="spec-models-slug"></span>`spec.models[].slug` | string | yes |  | length 1 to any | The model's id at its provider. |
| <span id="spec-models-provider"></span>`spec.models[].provider` | string | no |  | length 1 to any | The provider slug the entry applies to. |
| <span id="spec-models-anyProvider"></span>`spec.models[].anyProvider` | boolean | no |  |  | Apply the entry to every provider listing this model. |
| <span id="spec-models-action"></span>`spec.models[].action` | string | yes |  | `allow`, `deny` |  |
| <span id="spec-guardrails"></span>`spec.guardrails` | array of object | no |  |  | Rules the gateway applies to each request, reconciled by name, so names must be unique. Content rules match what a request says; capability rules match the tools, MCP servers and skills it offers and the client sending it. |
| <span id="spec-guardrails-name"></span>`spec.guardrails[].name` | string | yes |  | length 1 to any |  |
| <span id="spec-guardrails-baselineId"></span>`spec.guardrails[].baselineId` | string | no |  |  | The baseline guardrail this one came from. |
| <span id="spec-guardrails-ruleType"></span>`spec.guardrails[].ruleType` | string | yes |  | `blocked_pattern`, `max_messages`, `pii_redact`, `delimiter_integrity`, `tool_allow`, `tool_deny`, `mcp_allow`, `mcp_deny`, `skill_allow`, `skill_deny`, `client_allow`, `client_deny`, `expression` | Content rules: blocked_pattern (an RE2 regex over the request text), max_messages (a cap on messages per request), pii_redact (email, card, SSN and phone detectors, or your own regex), delimiter_integrity (sealed harness blocks left intact). Capability rules: <family>_allow and <family>_deny for tool, mcp, skill and client. expression: the request matches when its when expression is true, over the request variables. |
| <span id="spec-guardrails-action"></span>`spec.guardrails[].action` | string | yes |  | `block`, `redact`, `flag`, `strip` | block refuses the request. redact rewrites the matched content (content rules only). flag lets it through and records the match. strip removes the matched tool or MCP server (tool_* and mcp_* rules only). |
| <span id="spec-guardrails-pattern"></span>`spec.guardrails[].pattern` | string or integer | no |  |  | What the rule matches. blocked_pattern: an RE2 regex, required (RE2 has no lookahead or lookbehind). pii_redact: an RE2 regex, or empty for the built-in detectors. max_messages: a positive integer, required. delimiter_integrity: none. Capability rules: a name or * glob, required, anchors implied. |
| <span id="spec-guardrails-priority"></span>`spec.guardrails[].priority` | integer | no |  | >= 0 | Evaluation order, lowest first. |
| <span id="spec-guardrails-enabled"></span>`spec.guardrails[].enabled` | boolean | no | `true` |  |  |
| <span id="spec-guardrails-when"></span>`spec.guardrails[].when` | string | no |  | length 1 to 4096 | A CEL condition over the request variables (provider, model, client, tools, mcpServers, skills, now). The rule applies only to requests for which it is true; left out, it applies to every request. For an expression rule it is the match itself, and is required. A rule whose condition fails to evaluate is skipped and named in the decision's skipped list. |
| <span id="spec-capabilities"></span>`spec.capabilities` | object | no |  | map of string to object | Capability allow and deny lists, keyed by a name for the list. Each pattern becomes one guardrail, the same rows the guardrails list writes; this is the shorter way to write a list of them. An AiGovernanceList is the same thing as its own object. |
| <span id="spec-capabilities-key"></span>`spec.capabilities.<key>` | object | no |  | no other keys | An allow or deny list for one AI capability family. Each pattern becomes one AI Firewall guardrail row of rule type <family>_<list> (tool_deny, mcp_allow and so on). A deny always wins. Any enabled allow rule puts its family into allowlist mode, where everything it does not name is refused. |
| <span id="spec-capabilities-key-family"></span>`spec.capabilities.<key>.family` | string | yes |  | `tool`, `mcp`, `skill`, `client` | tool: a tool offered to the model. mcp: an MCP server wired into the session. skill: an agent skill. client: the calling client, named by its headers (claude-code, codex-cli). |
| <span id="spec-capabilities-key-list"></span>`spec.capabilities.<key>.list` | string | yes |  | `allow`, `deny` |  |
| <span id="spec-capabilities-key-action"></span>`spec.capabilities.<key>.action` | string | yes |  | `block`, `flag`, `strip` | block refuses the request. flag lets it through and records the match. strip removes the matched tool or MCP server and sends the rest of the request; it applies to the tool and mcp families only, because a skill is a value inside another tool and a client is a header. |
| <span id="spec-capabilities-key-priority"></span>`spec.capabilities.<key>.priority` | integer | no | `100` | >= 0 | Evaluation order among guardrails, lowest first. |
| <span id="spec-capabilities-key-enabled"></span>`spec.capabilities.<key>.enabled` | boolean | no | `true` |  |  |
| <span id="spec-capabilities-key-patterns"></span>`spec.capabilities.<key>.patterns` | array of string | yes |  | 1 to any items; items unique; each item: pattern `^[^\^\s](.*[^$\s])?$`; length 1 to any |  |
| <span id="spec-holdPolicy"></span>`spec.holdPolicy` | object | no |  | no other keys | Hold for review: what the gateway does with a tool, MCP server, skill or client it has not seen before. An approved capability is recorded as reviewed rather than written as an allow rule, which would put its whole family into allowlist mode. |
| <span id="spec-holdPolicy-holdUnknown"></span>`spec.holdPolicy.holdUnknown` | boolean | no | `false` |  | Hold a request that carries an unseen capability until someone approves or denies it. |
| <span id="spec-holdPolicy-holdTimeoutMinutes"></span>`spec.holdPolicy.holdTimeoutMinutes` | integer | no | `0` | 0 to 10080 | How long a hold waits for a decision, up to 7 days. 0 waits indefinitely. |
| <span id="spec-holdPolicy-holdTimeoutAction"></span>`spec.holdPolicy.holdTimeoutAction` | string | no | `wait` | `wait`, `deny`, `allow` | What happens when the wait runs out: keep waiting, deny the capability, or allow it. |

## Rules

Conditions the schema enforces beyond each field's own type. `vulnetix config validate` and the engine's plan report a document that breaks one.

| On | Rule |
|---|---|
| `spec.models[]` | Exactly one of these holds: (1) `provider` is required and `anyProvider` must be `false`; (2) `anyProvider` is required, `anyProvider` must be `true` and `provider` is not allowed. |
| `spec.guardrails[]` | When `ruleType` is `expression`: `when` is required, `action` must be `block`, `flag` and `pattern` must be pattern `^\s*$`. |
| `spec.guardrails[]` | When `ruleType` is `max_messages`: `pattern` is required and `pattern` must be >= 1, or pattern `^\s*\+?0*[1-9][0-9]*\s*$`. |
| `spec.guardrails[]` | When `ruleType` is `blocked_pattern`: `pattern` is required and `pattern` must be pattern `\S`. |
| `spec.guardrails[]` | When `ruleType` is `delimiter_integrity`: `action` must be `block`, `flag` and `pattern` must be pattern `^\s*$`. |
| `spec.guardrails[]` | When `ruleType` matches `_(allow\|deny)$`: `pattern` is required, `action` must not be `redact` and `pattern` must be pattern `^\s*[^\^\s](.*[^$\s])?\s*$`. |
| `spec.guardrails[]` | When `action` is `strip`: `ruleType` must be `tool_allow`, `tool_deny`, `mcp_allow`, `mcp_deny`. |
| `spec.capabilities.<key>` | When `family` is one of `skill`, `client`: `action` must be `block`, `flag`. |

## CEL variables

`spec.guardrails[].when` is a CEL expression in the `request` context, returning `bool`. It is evaluated by the AI firewall gateway, for each request. The rule is skipped, named in the decision's skipped list, and the gateway logs it. See [where each expression is evaluated](/platform-iac/reference/cel.md#where-each-expression-is-evaluated). The functions, limits and error codes are on [CEL rule expressions](/platform-iac/reference/cel.md).

| Variable | Type | Bound | Description |
|---|---|---|---|
| `provider` | `string` | 256 chars | Provider slug, such as `anthropic` or `openai`. |
| `model` | `string` | 256 chars | Model slug as requested. |
| `client` | `string` | 256 chars | Calling client's name, such as `claude-code` or `codex`. |
| `tools` | `list(string)` | 512 items of 256 chars | Tool names the request declares or calls, including flattened MCP tools such as `mcp__github__create_issue`. |
| `mcpServers` | `list(string)` | 128 items of 256 chars | Labels of the remote MCP servers the request wires in. |
| `skills` | `list(string)` | 256 items of 256 chars | Skill names the request offers. |
| `now` | `timestamp` |  | The time of evaluation. Callers may fix it; otherwise it is the clock when Eval runs. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Order.** Applied after [`AiProvider`](/platform-iac/kinds/ai-provider.md), so a document that refers to one by `metadata.name` can be in the same apply. Deleted before them.
- **Status.** Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).
- **Singleton.** There is one per tenant, and its name is always `default`.

## Two ways to apply it

| | `vulnetix ai-firewall apply` | The config engine |
|---|---|---|
| Reads | `.vulnetix/ai-firewall.yaml`, or `-f <file>` | Documents sent to [`POST /config/plan` and `/config/apply`](/platform-iac/reference/engine.md) |
| `metadata.org` | Compared with the authenticated principal | Compared with the tenant, as for every kind |
| A guardrail with no `priority` | Sent as `0` | Written at `100`, the column default the Resolve Platform uses |
| `baselineId` | Not stored | Stored on the guardrail row and exported, so a composed baseline rule round-trips |
| `providers[].key` | Read on the machine running the CLI and stored as the provider key | Not stored; the plan warns. Use [`AiProvider`](/platform-iac/kinds/ai-provider.md) `apiKey` for a custom provider's key |
| An `allow` rule whose action is `flag` | Applied | Applied, with a plan warning: it refuses nothing |

Both leave guardrails and model entries the document does not mention alone unless `spec.prune` is `true`, and neither ever prunes a provider entry. Guardrail rows that belong to an [`AiGovernanceList`](/platform-iac/kinds/ai-governance-list.md) or to `spec.capabilities` are never touched by `spec.guardrails` or its prune.

## How vulnetix ai-firewall apply behaves

- **Order.** Guardrails, then models, then providers, then keys, then settings, so tightening a policy never passes through a moment where a provider is on and its guardrails are not.
- **Org guard.** If `metadata.org` is set and does not match the authenticated organization, apply refuses. `--force` overrides.
- **Drift.** Guardrails and model entries on the server that the file does not mention are reported and left alone, unless you prune.
- **Dry run.** `--dry-run` prints the plan and changes nothing.
- **Export.** `export` writes the live policy with the baseline pinned off, so applying an export is a no-op. Provider keys are never exported.

> [!WHY] The file works in both places
> Since CLI v3.157.0 `vulnetix config validate`, `plan` and `apply` know this kind, and a file is a Platform IaC document by its content, not its folder. `.vulnetix/ai-firewall.yaml` and a document under `.vulnetix/config` are the same thing: define the policy in one of them. `validate` reads the well-known file since v3.164.0. `plan` and `apply` read the well-known file too since CLI v4.0.0 when no `-f` is given, so `config apply --prune` adopts it. `ai-firewall apply` and `export` are aliases of the config engine for this kind since v4.0.0. See [Which files are Platform IaC documents](/platform-iac/cli/validate.md#which-files-are-platform-iac-documents).

## Terraform and OpenTofu

The resource is `vulnetix_ai_firewall_policy` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_ai_firewall_policy](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/ai_firewall_policy).

Import an object that already exists by its name (`default`):

```shell
# Import an existing AiFirewallPolicy by its name (metadata.name).
terraform import vulnetix_ai_firewall_policy.default default
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

## More examples

`examples/AiFirewallPolicy/cli-policy-file.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
# The .vulnetix/ai-firewall.yaml shape vulnetix ai-firewall apply reads: no metadata.name.
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  org: 6f2a1c3e-0000-0000-0000-000000000001
spec:
  prune: false
  settings:
    logsEnabled: false
  baseline:
    enabled: true
    ref: recommended
    exclude:
      - pii-phone
  providers:
    - slug: openai
      action: allow
      key:
        fromEnv: OPENAI_PROVIDER_KEY
    - slug: openrouter
      action: deny
  models:
    - slug: gpt-4o
      provider: openai
      action: allow
    - slug: claude-sonnet-4-5
      anyProvider: true
      action: allow
  guardrails:
    - name: block-aws-keys
      ruleType: blocked_pattern
      action: block
      pattern: '(?i)AKIA[0-9A-Z]{16}'
      priority: 10
      enabled: true
    - name: cap-conversation
      ruleType: max_messages
      action: block
      pattern: "50"
      priority: 50
```

`examples/AiFirewallPolicy/default.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  name: default
spec:
  baseline:
    enabled: true
  guardrails:
    - name: redact-pii
      ruleType: pii_redact
      action: redact
    - name: sealed-blocks
      ruleType: delimiter_integrity
      action: block
    - name: no-shell
      ruleType: tool_deny
      action: strip
      pattern: Bash
  capabilities:
    approved-mcp:
      family: mcp
      list: allow
      action: block
      patterns: [github, "linear*"]
    banned-clients:
      family: client
      list: deny
      action: block
      priority: 10
      patterns: [unknown]
  holdPolicy:
    holdUnknown: true
    holdTimeoutMinutes: 60
    holdTimeoutAction: deny
```

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
