Textbook 15 Policy Language Reference

Policy Language Reference

This chapter is the compact reference for writing CAVRA policy packs. Earlier chapters show how policy fits into runtime authority. This chapter shows the policy shape, syntax, matching rules, and practical examples.

Policy Pack Shape

A CAVRA policy pack is a YAML document with identity, metadata, default behavior, rules, approval routes, evidence requirements, and optional test cases.

id: cavra-ai-agent-baseline
version: 1.0.0
description: Baseline runtime authority policy for AI-assisted engineering.
mode: enforce

defaults:
  decision: deny
  evidence_required: true

actors:
  allowed_agent_profiles:
    - claude-code
    - codex
  human_approvers:
    - platform-security
    - release-manager

rules:
  - id: allow-safe-readme-edit
    action: write_file
    resources:
      - README.md
      - docs/**/*.md
    decision: allow
    evidence:
      level: standard

  - id: protect-identity-and-infra
    action: write_file
    resources:
      - iam/**
      - terraform/**
      - .github/workflows/**
    decision: requires_approval
    approval_route: production-change
    evidence:
      level: signed

  - id: block-dangerous-shell
    action: execute_command
    command_patterns:
      - "terraform apply -auto-approve*"
      - "kubectl delete namespace production*"
      - "rm -rf /"
    decision: deny
    evidence:
      level: signed

mcp_trust:
  allowed_servers:
    - github-mcp
  blocked_servers:
    - unknown-filesystem

approval_routes:
  production-change:
    required_approvers: 1
    approvers:
      - platform-security
      - release-manager
    expires_after: 8h
    require_reason: true

tests:
  - name: dangerous terraform apply is blocked
    action: execute_command
    target: "terraform apply -auto-approve"
    expect: deny
  - name: IAM write is approval routed
    action: write_file
    target: iam/admin-role.tf
    expect: requires_approval

Top-Level Fields

Field	Required	Purpose
id	Yes	Stable policy pack identifier used in evidence and decisions.
version	Yes	Semantic policy version for audit and rollback.
description	Recommended	Human-readable policy purpose.
mode	Yes	enforce, shadow, or another supported runtime mode.
defaults	Recommended	Fallback decision and evidence posture when no rule matches.
actors	Optional	Agent profiles and human roles expected by the policy.
rules	Yes	Ordered runtime decision rules.
mcp_trust	Optional	MCP server trust and block rules.
approval_routes	Optional	Human or provider-backed approval routes.
tests	Recommended	Policy examples that can be validated repeatedly.

Rule Matching

Rules should be specific enough to explain the decision. CAVRA policies usually match by:

• action family, such as write_file, execute_command, git_operation, or mcp_tool_call;
• resource path, such as iam/**, .github/workflows/**, or docs/**/*.md;
• command pattern, such as terraform apply* or kubectl delete*;
• Git branch or ref, such as main, release/*, or origin/main;
• MCP server, capability, and tool name;
• actor, profile, tenant, or approval state where available.

Rules are easiest to operate when they are ordered from specific to broad. A precise allow rule for docs/**/*.md should appear before a broad approval rule for repository writes.

Decisions

Decision	Use when
allow	The action is low risk and should proceed with evidence.
deny	The action is not permitted under the policy.
requires_approval	The action may be legitimate but needs human or provider-backed approval.
shadow	The action should be observed without hard enforcement during rollout.
break_glass	Emergency action is allowed only with explicit justification and audit trail.

Evidence Requirements

Evidence policy should say what proof is required after the decision.

Evidence level	Typical use
standard	Local development, low-risk decisions, learning labs.
signed	Protected branches, infrastructure, identity, CI/CD, and release workflows.
delivery_audit	Reports, connector delivery, SMTP/provider validation, ticketing, and incident workflows.
retained	Compliance, trial evidence rooms, production readiness, and customer operating archives.

Policy Authoring Workflow

Use this loop for any new policy:

cavra policy init --destination .cavra/policy.yaml
cavra policy validate .cavra/policy.yaml
cavra policy explain execute_command "terraform apply -auto-approve"
cavra policy test --policy-pack cavra-ai-agent-baseline
cavra policy sign .cavra/policy.yaml --private-key .cavra/keys/policy-ed25519-private.pem --output .cavra/policy.yaml.sig
cavra policy verify .cavra/policy.yaml --signature .cavra/policy.yaml.sig --public-key .cavra/keys/policy-ed25519-public.pem

Common Recipes

Protect Production Infrastructure

- id: route-production-infra
  action: write_file
  resources:
    - terraform/prod/**
    - kubernetes/prod/**
    - iam/**
  decision: requires_approval
  approval_route: production-change

Block Dangerous Commands

- id: block-destructive-commands
  action: execute_command
  command_patterns:
    - "rm -rf /*"
    - "kubectl delete namespace production*"
    - "terraform apply -auto-approve*"
  decision: deny

Govern MCP Tools

mcp_trust:
  allowed_servers:
    - github-mcp
  approval_required:
    - filesystem-mcp
  blocked_servers:
    - unknown-filesystem

Require Evidence For Pull Requests

- id: require-pr-attestation
  action: git_operation
  resources:
    - main
    - release/*
  decision: requires_approval
  evidence:
    level: signed
    attest_pr: true

Policy Review Checklist

• Does every high-risk resource have a rule?
• Are broad deny or allow patterns justified?
• Are production, identity, secrets, CI/CD, and MCP tool changes approval-routed?
• Does evidence include the policy pack ID and version?
• Are tests included for expected allow, deny, and approval decisions?
• Has the policy been validated, tested, signed, and verified?

Check Your Understanding

1. Why should a policy route some actions for approval instead of denying them outright?
2. Which field gives auditors a stable identifier for the policy that made a decision?
3. What command explains why a specific action was blocked or allowed?
4. Why should policy tests include both safe and risky examples?

What's Next

Next, read Troubleshooting Playbook to diagnose policy, evidence, connector, GUI, and AISPM issues in a production-like workflow.