Policy YAML Reference

Complete reference for the Agent Policy YAML format. This page documents every field in the agent.yaml policy document.

Document Structure

An AIP policy document has four top-level sections:

apiVersion: aip.io/v1alpha2
kind: AgentPolicy
metadata:
  # Policy identification and signatures
spec:
  # Policy rules and configuration

Top-Level Fields

apiVersion

string

required

The API version of the policy schema. Must be aip.io/v1alpha2.Implementations will reject policies with unknown API versions.

kind

string

required

The type of policy document. Must be AgentPolicy.

Metadata Fields

The metadata section identifies the policy and provides integrity verification.

metadata.name

string

required

Unique identifier for this policy. Used as the default audience for identity tokens.

metadata:
  name: "production-agent"

metadata.version

string

Semantic version of the policy (e.g., "1.0.0", "2.1.3").

metadata:
  version: "2.1.0"

metadata.owner

string

Contact email for policy questions.

metadata:
  owner: "[email protected]"

metadata.signature

string

v1alpha2 feature. Cryptographic signature for policy integrity.Format: <algorithm>:<base64-signature>Supported algorithms:

ed25519 - Ed25519 signature (RECOMMENDED)

When present, implementations MUST verify the signature before applying the policy.

metadata:
  signature: "ed25519:YWJjZGVm..."

Spec Fields

The spec section contains the policy rules and enforcement configuration.

Enforcement Mode

spec.mode

string

default:"enforce"

Controls whether policy violations are blocked or just logged.

Value	Behavior
`enforce`	Block violations (default)
`monitor`	Log violations but allow through

Use case: Set to monitor to dry-run new policies before enforcement.

spec:
  mode: enforce

Tool Authorization

spec.allowed_tools

array<string>

Allowlist of tool names the agent may invoke. Tool names must exactly match the MCP server’s tool list.Default behavior: If a tool is not in this list AND not in tool_rules with action: allow, it will be blocked.

spec:
  allowed_tools:
    - github_get_repo
    - read_file
    - list_directory

Method Authorization

spec.allowed_methods

array<string>

Allowlist of JSON-RPC methods permitted. If not specified, implementations use a default safe list.Default safe list (when not specified):

initialize, initialized, ping
tools/call, tools/list
completion/complete
notifications/*
cancelled

The wildcard * allows all methods.

spec:
  allowed_methods:
    - initialize
    - tools/call
    - tools/list

spec.denied_methods

array<string>

Explicit denylist of JSON-RPC methods. Denied methods take precedence over allowed methods.

spec:
  denied_methods:
    - resources/read
    - resources/write

Path Protection

spec.protected_paths

array<string>

File paths that tools must not access. Any tool argument containing a protected path will be blocked.Automatic protections:

The policy file itself is automatically protected
~ is expanded to the user’s home directory

spec:
  protected_paths:
    - ~/.ssh
    - ~/.aws/credentials
    - .env

spec.strict_args_default

boolean

default:false

When true, tool rules reject arguments not explicitly declared in allow_args.

spec:
  strict_args_default: true

Tool Rules

The spec.tool_rules array provides fine-grained control over individual tools.

spec.tool_rules[]

array<ToolRule>

Array of tool-specific rules.

ToolRule Fields

tool_rules[].tool

string

required

Tool name this rule applies to. Must match exactly.

tool_rules:
  - tool: github_delete_repo

tool_rules[].action

string

default:"allow"

Action to take when this tool is called.

Value	Behavior
`allow`	Permit (subject to argument validation)
`block`	Deny unconditionally
`ask`	Require interactive user approval

tool_rules:
  - tool: deploy_production
    action: ask  # Human-in-the-loop

tool_rules[].rate_limit

string

Rate limit for this tool. Format: <count>/<period>Supported periods: second, minute, hour (or s, m, h)When exceeded, requests return error code -32002.

tool_rules:
  - tool: list_gpus
    rate_limit: "10/minute"

tool_rules[].strict_args

boolean

Override strict_args_default for this specific tool.

tool_rules:
  - tool: exec_command
    strict_args: true

tool_rules[].schema_hash

string

v1alpha2 feature. Cryptographic hash of the tool’s schema to prevent tool poisoning.Format: <algorithm>:<hex-digest>Supported algorithms: sha256, sha384, sha512If the tool’s schema changes, requests return error code -32013.

tool_rules:
  - tool: read_file
    schema_hash: "sha256:a3c7f2e8d9b4f1e2c8a7d6f3e9b2c4f1..."

tool_rules[].allow_args

object

Argument validation patterns. Maps argument names to regex patterns.Validation rules:

Regex must match the entire argument value
Uses RE2-compatible regex syntax
If any pattern fails, the request is blocked
Missing constrained arguments are treated as violations

tool_rules:
  - tool: postgres_query
    allow_args:
      query: "^SELECT\\s+.*"  # Only SELECT queries
  
  - tool: http_request
    allow_args:
      url: "^https://github\\.com/.*"

DLP Configuration

Data Loss Prevention scanning detects and redacts sensitive data in tool responses (and optionally requests).

spec.dlp

DLPConfig

DLP configuration block.

dlp.enabled

boolean

default:true

Enable DLP scanning. Defaults to true when the dlp block is present.

spec:
  dlp:
    enabled: true

dlp.scan_requests

boolean

default:false

v1alpha2 feature. Scan tool arguments before forwarding.Use case: Prevent data exfiltration via arguments (e.g., secrets embedded in API queries).

dlp:
  scan_requests: true

dlp.scan_responses

boolean

default:true

Scan tool responses for sensitive data.

dlp:
  scan_responses: true

dlp.max_scan_size

string

default:"1MB"

v1alpha2 feature. Maximum content size to scan per request/response.Content exceeding this limit is truncated for scanning (first N bytes only).Format: Size string (e.g., "1MB", "512KB", "10MB")

dlp:
  max_scan_size: "5MB"

dlp.on_request_match

string

default:"block"

v1alpha2 feature. Action when DLP pattern matches in a request.

Value	Behavior
`block`	Reject with error `-32001`
`redact`	Replace matched content and forward
`warn`	Log warning and forward unchanged

dlp:
  on_request_match: "block"

dlp.detect_encoding

boolean

default:false

Detect and scan base64-encoded content.

dlp:
  detect_encoding: true

dlp.filter_stderr

boolean

default:false

Scan stderr output from tools.

dlp:
  filter_stderr: true

dlp.patterns[]

array<Pattern>

Array of regex patterns to detect.

DLP Pattern Fields

patterns[].name

string

required

Rule identifier for audit logs and redaction markers.Matched content is replaced with [REDACTED:<name>]

patterns[].regex

string

required

RE2-compatible regex pattern.Built-in patterns:

patterns:
  - name: "AWS Key"
    regex: "(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}"
  
  - name: "GitHub Token"
    regex: "ghp_[a-zA-Z0-9]{36}"
  
  - name: "Generic Secret"
    regex: "(?i)(api_key|secret|password)\\s*[:=]\\s*['\"]?([a-zA-Z0-9-_]+)['\"]?"

patterns[].scope

string

default:"all"

v1alpha2 feature. Where to apply this pattern.

Value	Description
`all`	Scan both requests and responses
`request`	Only scan requests
`response`	Only scan responses

patterns:
  - name: "SQL Injection"
    regex: "(?i)(DROP|DELETE|TRUNCATE)\\s+TABLE"
    scope: "request"  # Detect exfiltration attempts

Identity Configuration (v1alpha2)

Agent identity and session management features.

spec.identity

IdentityConfig

Identity configuration block.

identity.enabled

boolean

default:false

Enable identity token generation and management.

spec:
  identity:
    enabled: true

identity.token_ttl

duration

default:"5m"

Token time-to-live. Format: Go duration string (e.g., "5m", "1h", "300s").Recommended: 5-15 minutes to limit token theft window.

identity:
  token_ttl: "10m"

identity.rotation_interval

duration

default:"4m"

How often to rotate tokens before expiry.Constraint: Must be less than token_ttl.

identity:
  rotation_interval: "8m"

identity.require_token

boolean

default:false

When true, all tool calls MUST include a valid identity token.Requests without tokens are rejected with error code -32008.

identity:
  require_token: true

identity.session_binding

string

default:"process"

Session binding mode.

Value	Binding
`process`	Bound to OS process ID
`policy`	Bound to policy hash
`strict`	Bound to process + policy + hostname

identity:
  session_binding: "strict"

identity.audience

string

Intended audience for identity tokens. Defaults to metadata.name.Purpose: Prevents tokens issued for one MCP server from being accepted by another.

identity:
  audience: "https://mcp.example.com/api"

identity.nonce_window

duration

Duration to retain nonces for replay detection. Defaults to token_ttl.

identity:
  nonce_window: "10m"

identity.policy_transition_grace

duration

default:"0s"

Grace period for tokens with old policy hash after policy update.

identity:
  policy_transition_grace: "2m"

Server Configuration (v1alpha2)

HTTP server for remote validation endpoints.

spec.server

ServerConfig

Server configuration block.

server.enabled

boolean

default:false

Enable HTTP server for remote validation.

spec:
  server:
    enabled: true

server.listen

string

default:"127.0.0.1:9443"

Bind address and port. Format: <host>:<port>Security: Binding to 0.0.0.0 requires TLS configuration.

server:
  listen: "127.0.0.1:9443"

server.failover_mode

string

default:"fail_closed"

Behavior when validation server is unreachable.

Value	Behavior	Security
`fail_closed`	Deny all requests	High
`fail_open`	Allow all requests	Low
`local_policy`	Fall back to local policy	Medium

server:
  failover_mode: "fail_closed"

server.timeout

duration

default:"5s"

Maximum time to wait for server response.

server:
  timeout: "3s"

server.tls

TLSConfig

TLS configuration. Required when listen is not localhost.

server.tls.cert

string

Path to TLS certificate file (PEM format).

server:
  tls:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"

server.tls.key

string

Path to TLS private key file (PEM format).

Complete Example

apiVersion: aip.io/v1alpha2
kind: AgentPolicy
metadata:
  name: production-agent
  version: "2.0.0"
  owner: [email protected]
  signature: "ed25519:YWJjZGVm..."

spec:
  mode: enforce
  
  allowed_tools:
    - github_get_repo
    - github_list_pulls
    - read_file
    - list_directory
  
  tool_rules:
    - tool: github_delete_repo
      action: block
    
    - tool: deploy_production
      action: ask
    
    - tool: postgres_query
      action: allow
      rate_limit: "100/minute"
      allow_args:
        query: "^SELECT\\s+.*"
  
  protected_paths:
    - ~/.ssh
    - ~/.aws/credentials
    - .env
  
  dlp:
    scan_requests: true
    scan_responses: true
    patterns:
      - name: "AWS Key"
        regex: "AKIA[A-Z0-9]{16}"
      - name: "GitHub Token"
        regex: "ghp_[a-zA-Z0-9]{36}"
  
  identity:
    enabled: true
    token_ttl: "10m"
    rotation_interval: "8m"
    require_token: true
    session_binding: "policy"
  
  server:
    enabled: true
    listen: "0.0.0.0:9443"
    failover_mode: "fail_closed"
    tls:
      cert: "/etc/aip/cert.pem"
      key: "/etc/aip/key.pem"

Validation

Common policy validation errors:

Error	Cause	Fix
`invalid apiVersion`	Wrong API version	Use `aip.io/v1alpha2`
`empty allowed_tools`	No tools specified	Add tools or tool_rules
`invalid regex`	Bad regex pattern	Validate regex syntax
`invalid rate_limit`	Wrong format	Use `<N>/<period>`
`rotation_interval >= token_ttl`	Rotation must happen before expiry	Reduce rotation_interval

Next Steps

Error Codes

JSON-RPC error codes reference

Audit Format

Audit log format specification

Token Format

AAT token structure and claims

Examples

Example policies for common use cases

Specifications

API Reference

SDKs & Implementations

Document Structure

Top-Level Fields

Metadata Fields

Spec Fields

Enforcement Mode

Tool Authorization

Method Authorization

Path Protection

Tool Rules

ToolRule Fields

DLP Configuration

DLP Pattern Fields

Identity Configuration (v1alpha2)

Server Configuration (v1alpha2)

Complete Example

Validation

Next Steps

Error Codes

Audit Format

Token Format

Examples

Build docs developers (and LLMs) love

Specifications

API Reference

SDKs & Implementations

​Document Structure

​Top-Level Fields

​Metadata Fields

​Spec Fields

​Enforcement Mode

​Tool Authorization

​Method Authorization

​Path Protection

​Tool Rules

​ToolRule Fields

​DLP Configuration

​DLP Pattern Fields

​Identity Configuration (v1alpha2)

​Server Configuration (v1alpha2)

​Complete Example

​Validation

​Next Steps

Error Codes

Audit Format

Token Format

Examples

Build docs developers (and LLMs) love

Document Structure

Top-Level Fields

Metadata Fields

Spec Fields

Enforcement Mode

Tool Authorization

Method Authorization

Path Protection

Tool Rules

ToolRule Fields

DLP Configuration

DLP Pattern Fields

Identity Configuration (v1alpha2)

Server Configuration (v1alpha2)

Complete Example

Validation

Next Steps