Policy Reference

Complete reference for policy syntax, matching rules, and all available options.

Policy Schema

A policy file is a YAML document with a rules array:

rules:
  - match: { ... }
    allow: true | false
    deny: true | false
    require_approval: true | false
    description: "string"
    risk: "low" | "medium" | "high"

Match Conditions

The match object defines conditions that must be met:

tool

Match by tool name (string or "*" for any):

match:
  tool: "shell"     # Exact match
  tool: "*"         # Match any tool

op / operation

Match by operation name (string or "*" for any):

match:
  op: "exec"        # Exact match
  op: "*"           # Match any operation

pattern

Regex pattern matching against action parameters:

match:
  tool: "shell"
  op: "*"
  pattern: "rm -rf|shutdown|reboot"  # Matches if params contain these strings

amount_gt

Numeric comparison for financial operations:

match:
  tool: "stripe"
  op: "refund"
  amount_gt: 1000    # Matches if amount > 1000

Combining Conditions

All conditions in a match must be satisfied:

match:
  tool: "stripe"
  op: "refund"
  amount_gt: 1000
  # Matches Stripe refunds over $1000

Rule Actions

Each rule must specify exactly one action:

allow

Allow the action to proceed immediately:

match: { tool: "http", op: "GET" }
allow: true
description: "Allow HTTP GET requests"

deny

Block the action immediately:

match: { tool: "shell", pattern: "rm -rf" }
deny: true
description: "Block destructive commands"
risk: "high"

require_approval

Require human approval before execution:

match: { tool: "shell", op: "*" }
require_approval: true
description: "Shell commands require approval"
risk: "medium"

Rule Fields

description

Human-readable explanation of what the rule does (required):

description: "Allow HTTP GET requests"

risk

Risk level indicator (optional):

"low" - Low risk actions
"medium" - Medium risk, may need review
"high" - High risk, should be carefully reviewed

risk: "high"

Complete Example

rules:
  # Allow HTTP GET requests
  - match:
      tool: "http"
      op: "GET"
    allow: true
    description: "Allow HTTP GET requests"
    risk: "low"
  
  # Require approval for shell commands
  - match:
      tool: "shell"
      op: "*"
    require_approval: true
    description: "Shell commands require approval"
    risk: "medium"
  
  # Block destructive shell commands
  - match:
      tool: "shell"
      op: "*"
      pattern: "rm -rf|shutdown|reboot"
    deny: true
    description: "Block destructive commands"
    risk: "high"
  
  # Default deny everything else
  - match:
      tool: "*"
      op: "*"
    deny: true
    description: "Default deny"

Policy Validation

Validate a policy file before using it:

faracore policy-validate policies/default.yaml

Policy Testing

Test how a policy evaluates a specific action:

# Create test-action.json
{
  "tool": "shell",
  "operation": "run",
  "params": {"cmd": "ls -la"},
  "context": {"agent_id": "test"}
}

# Test it
faracore policy-test test-action.json