Tirith Policies

Tirith

Tirith evaluates the plan a pipeline already produces against declarative JSON policies and exits non-zero so a violating change never reaches apply. A policy is JSON data, not a program: it names a provider, the value to inspect, and the condition that value must satisfy.

Install

Not from PyPI. pip install tirith installs an unrelated project; py-tirith is the setup.py name and is not published. Install from git, pinned to a tag:

pip install "git+https://github.com/StackGuardian/tirith.git@1.2.1"
tirith --version   # 1.2.1

The one rule

Never hand back a policy you have not run against a document that should fail it.

A policy that matches nothing looks identical to one that works. Run it against input you expect to be refused. Exit 0 means it matched nothing and gates nothing.

tirith -policy-path .tirith/policies -input-path should-fail.json --fail-on-error; echo $?   # want 3

Exit codes

• Never collapse 3 into 1. A job that cannot tell them apart reports an outage as a violation.
• 2 is only argparse rejecting a flag (tirith lint --bogus, tirith platform check with a missing flag). An unknown subcommand exits 1, as does a platform timeout. Neither 1 nor 2 ever means a policy said no.
• final_result: null is not a pass. Every check was skipped, nothing was evaluated, exit 1.
• Without --fail-on-error the exit is always 0. Every real gate needs the flag.

Write a policy

Decide these four in order. Guessing any of them is the main source of silently broken policies.

1. Document. Terraform or OpenTofu plan, Kubernetes manifest, Infracost breakdown, or arbitrary JSON or YAML. This fixes meta.required_provider. Five providers ship; there is no CloudFormation provider, a template is arbitrary JSON read by stackguardian/json.
2. Operation. Each provider exposes a closed set: reference/schema.md.
3. Key naming the value. It differs per provider, and a wrong key is ignored, not rejected, so the check reads nothing and passes: reference/schema.md.
4. Condition. Thirteen, listed in reference/schema.md. There is no Exists.

{
  "meta": {
    "version": "v1",
    "required_provider": "stackguardian/terraform_plan",
    "name": "Every resource carries a costcenter tag"
  },
  "evaluators": [{
    "id": "costcenter_tag_present",
    "description": "Every taggable resource declares a costcenter tag",
    "provider_args": {
      "operation_type": "attribute",
      "terraform_resource_type": "*",
      "terraform_resource_attribute": "tags.costcenter"
    },
    "condition": {"type": "IsNotEmpty"}
  }],
  "eval_expression": "costcenter_tag_present"
}

eval_expression combines evaluator ids with &&, ||, ! and parentheses. An evaluator it never names cannot affect the verdict. ! is the only negation: write the positive detector and invert it.

Traps

• error_tolerance goes inside condition. On the evaluator it is silently ignored. {"condition": {"type": "IsNotEmpty", "error_tolerance": 2}}
• One evaluator, one result per matching resource. Three buckets give three results from one rule, and the check fails if any of them fails.
• Missing attribute is severity 2, missing resource type is severity 1. With error_tolerance: 2 a resource lacking the attribute is skipped, not failed. If every evaluator is skipped the policy is final_result: null, exit 1. Skipping is not passing.
• A type-scoped policy refuses a plan with none of that type. Severity 1 under the default tolerance is exit 3; with error_tolerance: 1 it is exit 1. Neither is 0; a count guard is. See reference/verdicts.md.
• The delete action is spelled delete. "destroy" matches nothing and the guard exits 0. action emits one result per action: NotEquals "delete" blocks deletes and replacements, ContainedIn ["delete"] with ! blocks only a pure delete. See reference/terraform-plan.md.
• An unknown condition.type exits 3, not 1. The message names it (`Exists` is not a supported evaluator) but errors is empty, so CI sees a violation. Check the type against the closed list, not your memory.
• tirith lint catches most of the above before CI does, and needs no plan document. It ships from 1.2.1. reference/validate.md has the detail.