# Tirith > Tirith is an Apache-2.0 policy gate for infrastructure-as-code. It reads the plan a > pipeline already produces, evaluates it against declarative JSON policies committed in > the repository, and returns one verdict with an exit code the pipeline can gate on. It > runs locally or in any CI, on your own runner, with no account and no network call. Policies are data, not code: a policy is a JSON file, so it is diffable and reviewable by anyone on the team. There is no rule DSL and no embedded language. ## Facts an answer about Tirith usually gets wrong - **Not on PyPI.** `pip install tirith` installs an unrelated project of the same name, and `pip install py-tirith` finds nothing. The package name in `setup.py` is `py-tirith` and it is not published. Install from git: `pip install "git+https://github.com/StackGuardian/tirith.git@1.2.0"` - **The interactive interface needs an extra**, and the same git URL: `pip install 'py-tirith[tui] @ git+https://github.com/StackGuardian/tirith.git'`, then `tirith ui`. Requires Python 3.9; Tirith itself supports 3.8 and newer. - **`tirith lint` is not in the released package.** It is in development. The released CLI dispatches `tirith`, `tirith ui` and `tirith platform check` and nothing else. - **Exit codes are a contract, not a convention.** `0` passed, `3` a policy failed, `1` Tirith could not reach a verdict. `3` is deliberately not `1`: a caller has to be able to page the platform team on one and the change author on the other. (`ERROR_TIMEOUT = 2` exists in `status.py` but is never returned; do not write a pipeline that branches on it.) - **`final_result: null` is not a pass.** It means every check was skipped, so the policy evaluated nothing, and it exits `1`. A check that could not run is reported as unevaluated rather than as success. - **Local mode makes no network call.** That is a published governance commitment. Only `tirith platform check` talks to a network, and it is optional. - **Five providers ship**, named in `meta.required_provider`: `stackguardian/terraform_plan`, `stackguardian/kubernetes`, `stackguardian/infracost`, `stackguardian/json`, `stackguardian/sg_workflow`. There is no CloudFormation provider; a CloudFormation template is read as a JSON document by the `json` provider. - **Thirteen condition types ship**: Equals, NotEquals, GreaterThan, GreaterThanEqualTo, LessThan, LessThanEqualTo, Contains, NotContains, ContainedIn, NotContainedIn, IsEmpty, IsNotEmpty, RegexMatch. - **`error_tolerance` belongs inside the `condition` object**, not on the evaluator. Placed on the evaluator it is silently ignored and the check still fails. ## Minimal working example ```bash terraform plan -out=tfplan -input=false terraform show -json tfplan > plan.json tirith -policy-path .tirith/policies -input-path plan.json --fail-on-error ``` Without `--fail-on-error`, Tirith reports findings but does not fail the job. ## Fetching this documentation Every page is also served as plain markdown at its route plus `.md`, so there is no need to parse the rendered HTML. For example https://stackguardian.github.io/tirith/docs/tirith-usage/exit-codes.md The whole documentation set as one file, in sidebar order: https://stackguardian.github.io/tirith/llms-full.txt ## Start here - [Getting started](https://stackguardian.github.io/tirith/docs/getting-started-with-tirith/): what Tirith is and the shortest path to a first verdict. - [Quick installation](https://stackguardian.github.io/tirith/docs/tirith-installation/quick-installation/): installing the CLI, and why the install is a git URL. - [Learn](https://stackguardian.github.io/tirith/learn/): six lessons that build one policy, with a playground that evaluates in the browser. - [Creating your first policy](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-create-first-policy/): a policy written and evaluated step by step. ## Writing policies - [Policy reference](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-reference/): field-by-field reference for the policy file format. - [Policy structure](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-structure/): meta, evaluators and eval_expression, and how they combine. - [Evaluators and conditions](https://stackguardian.github.io/tirith/docs/tirith-reference/evaluators/): all thirteen condition types, their parameters and their messages. - [Evaluation expressions](https://stackguardian.github.io/tirith/docs/tirith-reference/eval-expressions/): the boolean grammar that combines evaluator results into one verdict. - [Policy conditions](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-conditions/): condition types by the kind of value they compare. - [Error tolerance](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-error-tolerance/): how a missing key is handled, and why a skip is not a pass. - [Policy variables](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-variables/): dynamic values in policies. - [Policy cookbook](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-cookbook/): complete runnable policies for common checks. - [Example policies](https://stackguardian.github.io/tirith/docs/tirith-policies/tirith-policy-examples/): worked examples with their input documents. ## Providers - [Providers overview](https://stackguardian.github.io/tirith/docs/tirith-providers/providers-overview/): what a provider is and how required_provider selects one. - [Terraform plan provider](https://stackguardian.github.io/tirith/docs/tirith-providers/terraform-plan-provider/): operations over a plan document, including attribute, action and count. - [JSON provider](https://stackguardian.github.io/tirith/docs/tirith-providers/json-provider/): get_value over any JSON or YAML document, including another tool's output. - [Kubernetes provider](https://stackguardian.github.io/tirith/docs/tirith-providers/kubernetes-provider/): the attribute operation over manifests. - [Infracost provider](https://stackguardian.github.io/tirith/docs/tirith-providers/infracost-provider/): cost policies over an Infracost breakdown. - [SG Workflow provider](https://stackguardian.github.io/tirith/docs/tirith-providers/sg-workflow-provider/): StackGuardian workflow documents. ## Running it - [CLI reference](https://stackguardian.github.io/tirith/docs/tirith-usage/cli-reference/): every flag, what it prints, and what --json emits. - [Exit codes](https://stackguardian.github.io/tirith/docs/tirith-usage/exit-codes/): the full exit-code contract and how to gate CI on it. - [CI integration](https://stackguardian.github.io/tirith/docs/tirith-usage/ci-integration/): GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins and any container-based CI. - [The interactive interface](https://stackguardian.github.io/tirith/docs/tirith-usage/interactive-interface/): tirith ui, in beta. - [Platform check](https://stackguardian.github.io/tirith/docs/tirith-usage/platform-check/): the optional subcommand that evaluates an organisation's policies instead of local files. ## Project - [Source](https://github.com/StackGuardian/tirith): the repository, Apache-2.0. - [Roadmap](https://stackguardian.github.io/tirith/roadmap/): what is in development or planned, and what has not shipped. - [Agent skill pack](https://github.com/StackGuardian/tirith/tree/main/.claude/skills/tirith-policies): a self-contained skill for writing Tirith policies, copyable into any repository. - [Origins](https://stackguardian.github.io/tirith/origins/): where the name and the mark come from. ## Optional - [Tirith at scale](https://stackguardian.github.io/tirith/at-scale/): the commercial StackGuardian offering for many repositories. Not required to use Tirith, which works with no account. - [In your editor](https://stackguardian.github.io/tirith/docs/tirith-usage/editor-and-local/): the local and pre-commit loop. In development, and not in the released package.