Policy file reference, cookbook recipes, bypass mechanism, and data handling.
Tirith uses a YAML policy file. Discovery order:
TIRITH_POLICY_ROOT env var → $TIRITH_POLICY_ROOT/.tirith/policy.yaml.tirith/policy.yaml (or .yml)~/.config/tirith/policy.yaml (user-level fallback)tirith policy init scaffolds a starter .tirith/policy.yaml. Pass --template <name> for a curated, well-commented preset; with no template it writes the full default policy.
| Template | For |
|---|---|
| individual | Solo developer defaults (alias: personal) |
| ci-strict | Fail-closed, no bypass, scan fail-on thresholds |
| ai-agent-heavy | Tuned for heavy AI-agent / autonomous use |
| oss-maintainer | Open-source maintainer posture |
| startup | Fast-moving small team |
| enterprise | Strict org defaults with an active package_policy block |
| mcp-strict | Locked-down MCP server posture |
Not sure which? tirith onboard inspects your repo (shell, IDE configs, AI-config files, package managers, CI, MCP) and recommends one.
| Field | Type | Description |
|---|---|---|
| version | number | Policy format version (currently 1) |
| fail_mode | "open" | "closed" | open allows execution on engine error; closed blocks. Default: open |
| allowlist | string[] | Glob patterns for domains/URLs excluded from findings |
| blocklist | string[] | Glob patterns for domains that are always blocked. Overrides allowlist. |
| severity_overrides | map<rule_id, severity> | Override default severity for specific rule IDs (CRITICAL, HIGH, MEDIUM, LOW) |
| allow_bypass_env | boolean | Allow TIRITH=0 bypass. Default: true. Set false for strict environments. |
All findings block execution. No bypass mechanism. Shortened URLs and plain HTTP escalated.
Default severity mappings. Allowlisted URLs skip analysis.
All Docker-related findings escalated. Other rules use default severity.
Everything becomes a LOW-severity warning. Nothing blocks. Useful for onboarding.
Escalate the vet_not_configured rule for Rust projects using cargo-vet.
To suppress instead (e.g. for non-Rust repos), add vet_not_configured to your allowlist.
For the rare case you know exactly what you're doing:
This is a standard shell per-command prefix. The variable only exists for that single command. Bypasses are logged to the audit trail with bypass_requested: true.
Note: Organizations can disable bypass entirely with allow_bypass_env: false in policy.
Local JSONL audit log at ~/.local/share/tirith/log.jsonl:
Disable: export TIRITH_LOG=0
Turn your local audit log into a security dashboard. export (the default) writes a self-contained static HTML file with 0600 permissions. serve is opt-in and binds 127.0.0.1 only, gated by an ephemeral in-memory token (TTL ≤ 1h, never written to disk). Zero telemetry, zero network beyond the bound loopback port.