AiFirewallPolicy

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. 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
Status	Served. The config engine 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.
Applied after	AiProvider (deleted before them)
CEL fields	spec.guardrails[].when (request): see CEL rule expressions
Terraform resource	vulnetix_ai_firewall_policy, imported by name (see Terraform and OpenTofu)
CLI	vulnetix config apply, CLI v3.157.0 and later.
Pinned schema	v1.18.0/AiFirewallPolicy.schema.json
Newest schema	latest/AiFirewallPolicy.schema.json
First released in	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-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/AiFirewallPolicy.schema.json
apiVersion: vulnetix.com/v1
kind: AiFirewallPolicy
metadata:
  name: default

HCL (resource vulnetix_ai_firewall_policy)

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

resource "vulnetix_ai_firewall_policy" "default" {
}

CLI (applies it)

export VULNETIX_ORG_ID=...    # the organization UUID
export VULNETIX_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/Vulnetix/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-language-server: $schema=https://github.com/Vulnetix/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)

# 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"
  }
}

CLI (applies it)

export VULNETIX_ORG_ID=...    # the organization UUID
export VULNETIX_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/Vulnetix/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
apiVersion	string	yes		exactly vulnetix.com/v1	The document format version. Every kind in this release is vulnetix.com/v1.
kind	string	yes		exactly AiFirewallPolicy	Always AiFirewallPolicy.
metadata	object	no		no other keys	metadata.org, when set, makes apply refuse to run against any other tenant.
metadata.name	string	no		exactly default
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.
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.
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.
spec	object	no		no other keys
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.
spec.settings	object	no		no other keys
spec.settings.logsEnabled	boolean	no			Record per-inference metadata (model, decision, tokens, latency, never the prompt or completion). Paid plans only.
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.
spec.baseline.enabled	boolean	no
spec.baseline.ref	string	no			A named baseline set to pin.
spec.baseline.exclude	array of string	no		each item: length 1 to any	Baseline guardrail ids to leave out.
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.
spec.providers[].slug	string	yes		length 1 to any	A built-in provider slug, or the metadata.name of an AiProvider.
spec.providers[].action	string	yes		allow, deny, default	allow pins the provider as allowed, deny blocks it, default removes any pin.
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.
spec.providers[].key.fromEnv	string	no		pattern ^[A-Za-z_][A-Za-z0-9_]*$
spec.providers[].key.fromFile	string	no		length 1 to any
spec.models	array of object	no			Model allow and deny entries. Once a provider has any allowed model, its other models are denied.
spec.models[].slug	string	yes		length 1 to any	The model’s id at its provider.
spec.models[].provider	string	no		length 1 to any	The provider slug the entry applies to.
spec.models[].anyProvider	boolean	no			Apply the entry to every provider listing this model.
spec.models[].action	string	yes		allow, deny
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.
spec.guardrails[].name	string	yes		length 1 to any
spec.guardrails[].baselineId	string	no			The baseline guardrail this one came from.
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: _allow and _deny for tool, mcp, skill and client. expression: the request matches when its when expression is true, over the request variables.
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).
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.
spec.guardrails[].priority	integer	no		>= 0	Evaluation order, lowest first.
spec.guardrails[].enabled	boolean	no	true
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.
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.
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 _ (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.
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).
spec.capabilities.<key>.list	string	yes		allow, deny
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.
spec.capabilities.<key>.priority	integer	no	100	>= 0	Evaluation order among guardrails, lowest first.
spec.capabilities.<key>.enabled	boolean	no	true
spec.capabilities.<key>.patterns	array of string	yes		1 to any items; items unique; each item: pattern ^[^\^\s](.*[^$\s])?$; length 1 to any
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.
spec.holdPolicy.holdUnknown	boolean	no	false		Hold a request that carries an unseen capability until someone approves or denies it.
spec.holdPolicy.holdTimeoutMinutes	integer	no	0	0 to 10080	How long a hold waits for a decision, up to 7 days. 0 waits indefinitely.
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. The functions, limits and error codes are on CEL rule expressions.

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: 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 and the config engine.
• Order. Applied after AiProvider, 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.
• 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
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 console 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 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 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.

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.

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

# 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.

More examples

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

# yaml-language-server: $schema=https://github.com/Vulnetix/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 Vulnetix/config-schemas:

# yaml-language-server: $schema=https://github.com/Vulnetix/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. In an editor, start the file with the schema comment.