SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstirith-config

tirith-config

Testing & quality

View repository

Updated 10-16 02:34

About this skill

tirith-config

Tirith intercepts shell commands and pasted content to catch homograph URLs (Cyrillic lookalikes, mixed scripts), ANSI escape injection, and curl | bash–style pipe-to-shell patterns. This skill encodes operating procedure — decision logic, verification rituals, and inherent gotchas. The current allowlist and tool version are not encoded here; query them at runtime.

Operating model

Tirith has four moving parts. Treat the live config as source of truth, not memory:

  • Shell hook — sourced via eval "$(tirith init --shell zsh)" in the user's shell profile. This is what wires per-command interception. Hook source files at ~/.local/share/tirith/shell/ are inert until the eval line is added to the profile.
  • Policy file — ~/.config/tirith/policy.yaml (global) and .tirith/policy.yaml (per-project, walks up from cwd). The per-project file wins when present.
  • Audit log — ~/.local/share/tirith/log.jsonl. Redacted previews, not full commands.
  • Receipts — created by tirith run <url>. Verifiable later with tirith receipt verify <sha256>.

tirith doctor is the canonical health check; it surfaces hook status, policy detection, and bypass mode in one shot.

Decision tree: a command was blocked

Four responses, each appropriate for a different shape of problem:

Run tirith why first. The rule ID decides which response fits: a pipe-to-shell rule (curl_pipe_shell) and a hostname rule (lookalike_tld, which flags .dev, .app, .zip and similar TLDs) both clear through trust, but only the first is about the script itself.

  1. Trust the source — for a vendor you trust. tirith trust last shows the last trigger and offers to trust its domain interactively; tirith trust from-last-trigger prints the narrowest matching tirith trust add command (--apply runs it). Entries are scoped to one rule when --rule is given, expire after 30 days unless --permanent or --ttl says otherwise, and are recorded in the trust audit (tirith trust list, tirith trust audit). Prefer this over the policy allowlist for anything short of a canonical installer.
  2. Allowlist the hostname — only for canonical installer domains you pipe-shell from repeatedly (e.g., get.docker.com, sh.rustup.rs). Add to allowlist: in ~/.config/tirith/policy.yaml. An entry suppresses every hostname-scoped rule for that exact host, lookalike_tld included; content-level checks (homograph, mixed-script, ANSI) still run. It never expires, which is why trust (1) is the better default.
  3. Download, read, run — curl -fsSL <url> -o /tmp/install.sh, read the file, then sh /tmp/install.sh. A plain download is not pipe-to-shell and only trips hostname rules, which warn. This is the most reliable one-off path, and the only one that takes interpreter arguments (curl … | bash -s -- --prefix /opt).
  4. tirith run <url> — downloads to a temp file, shows SHA256, runs static analysis, and writes a receipt. It fetches the URL itself, so the original curl flags have no counterpart. Execution is Linux-only: on macOS it inspects and stops, so follow it with (3) to actually install. tirith run <url> | sh pipes the analysis report, not the script, into the shell.
  5. TIRITH=0 prefix — honored when the command is checked at Enter, not by the paste scanner. The paste scanner analyzes the pasted text and does not read an assignment inside it, so pasting TIRITH=0 curl … | sh is still blocked at paste time, and typing TIRITH=0 before pasting does not help because only the pasted chunk is scanned. It works for a command typed in full. export TIRITH=0 disables both checks for the whole shell until unset TIRITH, which is broader than the problem. Policy's allow_bypass_env governs both. Confirm against the installed build: tirith check --interactive --shell posix -- 'TIRITH=0 curl -fsSL https://example.com/x.sh | sh' exits 0, while the same text piped to tirith paste --shell posix --interactive exits 1.

If none of these fit, the command probably shouldn't run.

Adding to the allowlist

allowlist:
  - "vendor.example.com"   # one entry per line, exact hostname

Hostnames only — no globs, no path-aware matching. After editing:

tirith doctor                                              # confirm policies: still resolves
tirith check -- curl -fsSL https://vendor.example.com \| bash  # should exit 0
tirith check -- curl -fsSL https://vendor-not-listed.com \| bash  # should still exit 1 with curl_pipe_shell

Both checks together confirm the allowlist took effect and didn't accidentally widen the policy.

Quieting a noisy rule

When a rule fires mostly on legitimate traffic, lower its severity instead of disabling tirith or allowlisting around it:

severity_overrides:
  lookalike_tld: LOW

At paranoia 1–2, only Medium+ findings surface, so LOW keeps the rule in the audit log without interrupting. tirith warnings and tirith doctor's detection-coverage block still count it. tirith explain --rule <id> documents any rule (--list enumerates them), and tirith policy tune --from-audit suggests changes from the log.

Anti-patterns for the allowlist

  • Don't allowlist broad CDNs. raw.githubusercontent.com, gist.githubusercontent.com, cdn.jsdelivr.net, s3.amazonaws.com, *.vercel.app — anyone can host arbitrary scripts on these. Allowlisting them gives a security tool a wide blind spot. Use download-read-run, or a URL-scoped tirith trust add <host>/<path>, for one-off scripts hosted on shared infrastructure.
  • Don't allowlist subdomains preemptively. Add what you actually use, not what you might use someday.
  • Don't allowlist as a way to silence noise. If tirith blocks something repeatedly that you don't actually trust, the right move is to stop running that command, not to suppress the warning.

Verification ritual after any config change

Run all four:

tirith policy validate                        # 0 errors, 0 warnings
tirith doctor                                 # hook status: configured / policies: <path>
tirith policy test '<a known-blocked cmd>'    # action: Block — rules still fire
tirith policy test '<an allowlisted cmd>'     # action: Allow — the change took effect

tirith doctor alone is not sufficient — it reports config detection, not rule behavior. tirith policy validate is the only check that catches misspelled fields: tirith ignores unknown keys with a warning, so allow_bypass: (the real key is allow_bypass_env) or version: (the real key is schema_version) silently do nothing. tirith policy effective prints the fully resolved policy with defaults filled in.

To test a candidate policy without touching the live file, point TIRITH_POLICY_ROOT at a directory holding .tirith/policy.yaml and run tirith policy test with it set.

After a brew upgrade

brew upgrade tirith may re-materialize hook source files. The shell profile line stays put, so usually nothing breaks, but verify:

tirith --version
tirith doctor

If hook status ever drops back to NOT CONFIGURED after an upgrade, re-run eval "$(tirith init --shell zsh)" and confirm the profile line is still present. Do not blindly append a duplicate.

Reading the audit log

tail -20 ~/.local/share/tirith/log.jsonl | jq .   # last 20 events
tirith why                                         # explains last triggered rule
tirith receipt last                                # last `tirith run` receipt
tirith receipt list                                # all receipts

The log only stores redacted command previews — not full commands, env vars, or file contents. Disable logging entirely with export TIRITH_LOG=0.

Per-project policies

For client work that needs stricter rules than the global config, drop a .tirith/policy.yaml at the project root. Tirith walks up from the current directory and uses the first match. A repo-scoped policy is tightening-only: weakening fields such as allowlist are ignored with a notice, so a cloned repo cannot loosen your protection. Loosen at user scope (global policy or tirith trust add --scope user). tirith policy effective shows which fields were neutralized.

Inherent gotchas

  • Profile edits affect new shells only. After modifying the shell profile, open a fresh terminal tab or source ~/.zshrc. The current shell will not pick up the change.
  • tirith check -- <cmd> — the -- is required. Without it, flags on <cmd> (e.g., -sSL) get parsed as tirith's own flags.
  • Shell quoting matters in tirith check. Pipe characters and parens need escaping (\|, \() since the command is parsed by your shell first.
  • fail_mode: open allows commands through when tirith itself errors internally. Use fail_mode: closed only in environments where blocking on parser errors is acceptable.
  • License key absence is normal. OSS rules work without one; only paid features (e.g., team audit) require activation.

What this skill deliberately does not encode

  • The current allowlist contents — read ~/.config/tirith/policy.yaml directly.
  • The current tirith version — tirith --version.
  • Whether the hook is currently configured — tirith doctor.
  • Specific zshrc line text — tirith init --shell zsh always prints the current correct line; pipe its output rather than copy-pasting from anywhere.

The skill is a stable operating manual. Live state is queried at runtime.