Policy Reference

Complete syntax for policy rules.

Rule structure

- match:
    tool: string       # e.g. shell, github, stripe
    operation: string  # or "op"
    # optional: params, agent_id, contains, etc.
  allow: true         # exactly one: allow, deny, or require_approval
  reason: string      # optional, for audit
  risk: low|medium|high|critical  # optional

- match:
    tool: string       # e.g. shell, github, stripe
    operation: string  # or "op"
    # optional: params, agent_id, contains, etc.
  allow: true         # exactly one: allow, deny, or require_approval
  reason: string      # optional, for audit
  risk: low|medium|high|critical  # optional

- match:
    tool: string       # e.g. shell, github, stripe
    operation: string  # or "op"
    # optional: params, agent_id, contains, etc.
  allow: true         # exactly one: allow, deny, or require_approval
  reason: string      # optional, for audit
  risk: low|medium|high|critical  # optional

Match keys

Key	Example	Description
tool	`shell`, `github`	Tool or service
operation	`exec`, `refund`	Operation (or use `op`)
contains	`rm -rf`	Block if params contain this
agent_id	`my-agent`	Specific agent
amount_gt, amount_lt	`1000`	For payment amounts (numeric comparison on `params.amount`)
pattern	Regex string	Match params (or a field) against a regex

Conforming implementations support at least these; see Faramesh Core Spec §7.4 for the full list. If a predicate references a missing field, it does not match.

Pattern (regex)

Match command or params with a regex:

- match:
    tool: shell
    pattern: "rm\\s+-rf|sudo\\s+"
  deny: true
  reason: "Destructive or privileged commands blocked"

- match:
    tool: shell
    pattern: "rm\\s+-rf|sudo\\s+"
  deny: true
  reason: "Destructive or privileged commands blocked"

- match:
    tool: shell
    pattern: "rm\\s+-rf|sudo\\s+"
  deny: true
  reason: "Destructive or privileged commands blocked"

amount_gt / amount_lt

For payment or refund tools, gate by amount:

- match:
    tool: stripe
    operation: refund
    amount_gt: 500
  require_approval: true
  reason: "Refunds over 500 require approval"

- match:
    tool: stripe
    operation: refund
    amount_lt: 100
  allow: true
  reason: "Small refunds auto-approved"

- match:
    tool: stripe
    operation: refund
    amount_gt: 500
  require_approval: true
  reason: "Refunds over 500 require approval"

- match:
    tool: stripe
    operation: refund
    amount_lt: 100
  allow: true
  reason: "Small refunds auto-approved"

- match:
    tool: stripe
    operation: refund
    amount_gt: 500
  require_approval: true
  reason: "Refunds over 500 require approval"

- match:
    tool: stripe
    operation: refund
    amount_lt: 100
  allow: true
  reason: "Small refunds auto-approved"

Risk rules (optional)

You can attach a risk level to a rule (risk: low|medium|high). Risk is evaluated separately; if the result is high and the policy would allow, the outcome is upgraded to require approval (see Core Spec §8.3). Example:

rules:
  - match:
      tool: shell
      operation: exec
    allow: true
    risk: high
    reason: "Shell allowed but high risk"
# Result: action requires approval (high-risk upgrade)

rules:
  - match:
      tool: shell
      operation: exec
    allow: true
    risk: high
    reason: "Shell allowed but high risk"
# Result: action requires approval (high-risk upgrade)

rules:
  - match:
      tool: shell
      operation: exec
    allow: true
    risk: high
    reason: "Shell allowed but high risk"
# Result: action requires approval (high-risk upgrade)

Wildcards

tool: "*" — Any tool
operation: "delete_*" — Any operation starting with "delete_"

Validation

Each rule must have exactly one effect (allow, deny, or require_approval). Use faramesh policy validate to check your policy before deploying.

Table of content