tirith-config

What this skill does

# 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

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

1. **Allowlist the hostname** — only when the vendor is trusted *and* you'll pipe-shell from them repeatedly. Add to `allowlist:` in `~/.config/tirith/policy.yaml`. Reserve for canonical installer domains (e.g., `get.docker.com`, `sh.rustup.rs`). Allowlist only suppresses pipe-shell rules for that exact hostname; content-level checks (homograph, mixed-script, ANSI) still run.
2. **`tirith run <url>`** — for one-off installs you want to inspect. Downloads to a temp file, shows SHA256, runs static analysis, opens in a pager for review, executes only after confirmation, and writes a receipt.
3. **`TIRITH=0 <cmd>` prefix** — per-command bypass when you've already vetted the script elsewhere or are operating in a known-safe context. The variable only persists for that single command. Disabled if `allow_bypass: false` in policy.

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

## Adding to the allowlist

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

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

```bash
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.

## 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 `tirith run` or `TIRITH=0` 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 three:

```bash
tirith doctor                          # hook status: configured / policies: <path>
tirith check -- <a known-blocked cmd>  # confirm rules still fire
tirith check -- <an allowlisted cmd>   # confirm allowlist still works
```

`tirith doctor` alone is not sufficient — it reports config detection, not rule behavior.

## 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:

```bash
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

```bash
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 where defaults differ from the global config, drop a `.tirith/policy.yaml` at the project root. Tirith walks up from the current directory and uses the first match, so the per-project file fully overrides the global one — it doesn't merge. Re-declare any global allowlist entries the project also needs.

## 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.