Guardrail rule files

Guardrails are rules in versioned JSON files. Keep the file in your repository, review changes by pull request, and publish what was reviewed. Any agent or person with write access can publish a version. Every published version is an audit event with its author and digest.

overlane guard rules put --file rules.json --reason "freeze deploys on Fridays"
overlane guard rules list

A rule file

{
  "version": "1",
  "rules": [
    {
      "id": "team.protect-infra",
      "description": "Nobody pushes infrastructure changes directly",
      "effect": "deny",
      "match": { "tools": ["git.push"], "paths": ["infra/**"] },
      "code": "path_protected",
      "nextCommand": "overlane guard approvals list"
    },
    {
      "id": "team.spend-cap",
      "description": "Stop paid work at 50 dollars a month",
      "effect": "deny",
      "match": { "usage": { "metric": "usd", "atLeast": 50 } },
      "code": "spend_cap_reached",
      "message": "the monthly spend cap of 50 dollars is reached"
    },
    {
      "id": "team.egress",
      "description": "CI may not reach unknown hosts",
      "effect": "deny",
      "match": { "tools": ["egress.fetch"], "hosts": ["*.untrusted.example"] },
      "code": "egress_blocked"
    },
    {
      "id": "team.prod-deploy",
      "description": "Production deploys need an approval",
      "effect": "require_approval",
      "match": { "tools": ["deploy.run"], "environments": ["production"] }
    }
  ]
}

What a rule can match

Every field that is present must match; the values inside one field are alternatives. Globs use * within a segment and ** across segments.

The effect is allow, deny or require_approval. Plan limits are ordinary rules with a usage match.

How layers combine

There are three layers: platform (built in), team and project. Inside a layer the first matching rule wins, so a layer can carve an exception into its own rules. Across layers the result is the intersection: the most restrictive answer stands, and a lower layer can never weaken a higher one. A project rule that allows a push the platform denies changes nothing.

The platform layer protects main, master, production and release/** from agents, protects credential files and CI workflows from agents, refuses force-pushes to protected branches, requires approval for production deploys and release promotion, and requires an active task for agent pushes.

Test a file before you publish it

overlane guard rules test --file rules.json --tool git.push --path infra/main.tf
overlane guard rules test --file rules.json --tool ci.run --usage usd=50

The command evaluates the file locally as the team layer and exits 6 when it would refuse the action.

What a refusal looks like

A refusal carries a stable code, the rule ID and the exact next command or approval path, and exits with code 6.

overlane guard check --tool git.push --branch main --task held