Spec

Policy file — surety.policy.yaml

Surety policy is repo-owned and explicit. No hidden environment variables. The policy file is the contract teams use to declare what Surety should enforce and how.

Example

version: 0
mode: shadow                # shadow | advisory | required

risk_tiers:
  default: medium
  high_paths:
    - "infra/**"
    - "auth/**"
    - "package.json"
    - "pnpm-lock.yaml"

executors:
  allowed:
    - claude-code
    - codex
    - openhands
    - manual

runtime:
  default: docker
  unsafe_host_allowed: false
  egress:
    default: deny
    allow:
      - "registry.npmjs.org"
      - "api.github.com"

paths:
  forbidden:
    - ".git/**"
    - ".env"
    - "secrets/**"

gates:
  low:
    required: [typecheck, tests]
  medium:
    required: [typecheck, tests, secrets, dependency_vulns]
  high:
    required: [typecheck, tests, secrets, dependency_vulns, sast, sbom]
  critical:
    required: [typecheck, tests, secrets, dependency_vulns, sast, sbom, approval]

approvals:
  high:
    min_reviewers: 1
  critical:
    min_reviewers: 2
    segregation_of_duties: true

waivers:
  require_reason: true
  require_expiry: true
  require_signature: true

Validation

The policy is validated before use. Missing required fields fail with actionable errors. The policy hash is recorded in every evidence pack so reviewers know which version of the policy produced the verdict.

Modes

• Shadow — Surety runs and reports; merge is never blocked. Use for evaluation.
• Advisory — Surety publishes verdict and Check Run; teams can choose to act on it.
• Required — Branch protection requires a Surety Pass before merge.

Most teams start in shadow on a few repos, move to advisory once the gate set is tuned, and enable required mode once the false-block rate is acceptable.