tirith — Terminal Security for Developer Environments

tirith intercepts shell commands and pasted text, detecting supply-chain
attacks before they execute. It catches pipe-to-shell patterns, homograph
domains (Cyrillic/Greek lookalikes), ANSI terminal injection, bidi text
overrides, zero-width characters, shortened URLs, punycode tricks, and
config poisoning. It runs as a shell hook for real-time protection and as
a standalone CLI for scanning, scoring, auditing, and AI agent security.

Quick Start

# Install shell hooks (zsh/bash/fish/powershell/nushell)
eval "$(tirith init --shell zsh)"              # zsh
eval "$(tirith init --shell bash)"             # bash
tirith init --shell fish | source              # fish
tirith init --shell nushell | source           # nushell

# Check a command before running it
tirith check -- 'curl https://example.com/install.sh | bash'

# Verify installation health
tirith doctor

Detection Rules

tirith uses a three-tier analysis pipeline:

1. Tier 1 — compiled regex fast gate (sub-millisecond)
2. Tier 2 — URL/Docker ref extraction, byte scanning for control chars
3. Tier 3 — full rule evaluation with policy overrides

Rule categories

Category	Examples
hostname	Homograph domains, punycode tricks, mixed-script attacks, confusable characters
transport	Plain HTTP, insecure TLS flags (--no-check-certificate), shortened URLs
command	Pipe-to-shell (curl | bash), dotfile overwrite, archive extract to sensitive paths
terminal	ANSI escape injection, bidi overrides, zero-width chars, hidden multiline, hangul filler
ecosystem	Git typosquat, Docker untrusted registry, npm/PyPI lookalike packages
path	Non-ASCII paths, homoglyph filenames, double-encoding attacks
credential	Exposed tokens, API keys in command arguments

Additional categories (codefile, configfile, environment, rendered, threatintel,
custom) are also available.

List all rules: tirith explain --list
Filter by category: tirith explain --list --category terminal
Explain a specific rule: tirith explain --rule pipe_to_interpreter

Common Workflows

Intercept dangerous commands

tirith hooks into the shell and checks every command before execution.
Manual check:

tirith check -- 'curl https://example.com | bash'
tirith check --format json -- 'npm install suspicious-pkg'
tirith check --shell powershell -- 'iwr https://example.com | iex'

Scan a repository for hidden threats

Scan files for invisible Unicode, ANSI escapes, config poisoning, and
hidden content:

tirith scan ./
tirith scan --ci --fail-on high ./
tirith scan --format sarif ./ > results.sarif
tirith scan --file suspicious.sh
echo "$CLIPBOARD" | tirith scan --stdin

Use --profile to load a named scan profile from your policy file.

Score a URL

Get a risk score for a URL before visiting or using it:

tirith score https://get.example-tool.sh
tirith score --format json https://suspicious-domain.com

Detect server-side cloaking (Unix)

Check if a server returns different content to bots versus browsers:

tirith fetch https://example.com/install.sh
tirith fetch --format json https://example.com/install.sh

Download and execute safely (Unix)

Download a script, analyze it, and optionally execute with SHA-256
verification and receipt logging:

tirith run https://get.example-tool.sh
tirith run --no-exec https://example.com/install.sh     # analyze only
tirith run --sha256 abc123... https://example.com/install.sh

Verify past executions:

tirith receipt last
tirith receipt verify a1b2c3d4e5f6

Set up AI tool protection

Configure tirith to guard AI coding agents against prompt injection
and malicious tool calls:

tirith setup claude-code --with-mcp    # Claude Code + MCP server
tirith setup cursor                     # Cursor
tirith setup codex                      # OpenAI Codex
tirith setup copilot-cli                # GitHub Copilot CLI (run from repo root)
tirith setup gemini-cli --with-mcp     # Gemini CLI + MCP
tirith setup kiro                       # Kiro CLI (formerly Amazon Q)
tirith setup vscode                     # VS Code
tirith setup windsurf                   # Windsurf
tirith setup pi-cli                     # Pi CLI
tirith setup openclaw                   # OpenClaw

Preview changes: tirith setup claude-code --dry-run
Update hook scripts: tirith setup claude-code --update-configs

MCP gateway proxy

Intercept tool calls from AI agents through an MCP gateway:

tirith gateway run \
  --upstream-bin npx \
  --upstream-arg @modelcontextprotocol/server-filesystem \
  --config gateway.yaml
tirith gateway validate-config --config gateway.yaml

Investigate a detection

After tirith blocks or warns:

tirith why                                    # explain last trigger
tirith why --format json                      # machine-readable
tirith explain --rule pipe_to_interpreter     # rule documentation
tirith explain --list --category terminal     # list rules in category
tirith diff https://install.example-cli.dev   # compare against patterns

Manage trusted patterns

Allow specific domains or URLs after review with TTL and rule scoping:

tirith trust add example.com                              # permanent global
tirith trust add example.com --ttl 7d                     # expires in 7 days
tirith trust add example.com --rule pipe_to_interpreter   # rule-scoped
tirith trust add example.com --scope repo                 # repo-scoped
tirith trust list                                          # show all entries
tirith trust list --format json --expired                  # include expired
tirith trust last                                          # trust from last trigger
tirith trust gc                                            # remove expired entries

Audit and compliance

Export verdicts, generate statistics, and produce compliance reports:

tirith audit export                                    # JSON export
tirith audit export --format csv --since 2025-01-01    # CSV with date filter
tirith audit stats --format json                       # summary statistics
tirith audit report --format html > report.html        # compliance report
tirith audit report --format markdown                  # markdown report

Session warnings

Track accumulated warnings across a shell session:

tirith warnings                         # full warning table
tirith warnings --format json           # machine-readable
tirith warnings --summary               # one-line (for shell exit hooks)
tirith warnings --hidden                # show paranoia-filtered findings
tirith warnings --clear                 # clear after display

Threat intelligence

Manage the threat intelligence database for enhanced detection:

tirith threat-db update          # download/update threat DB
tirith threat-db update --force  # force re-download
tirith threat-db status          # show DB age and entry counts

Policy management

Configure detection behavior with YAML policies:

tirith policy init              # generate starter policy
tirith policy init --minimal    # minimal template
tirith policy validate          # check for errors
tirith policy test 'curl https://example.com | bash'  # test a command

Policy discovery: walks up from cwd to .git boundary looking for
.tirith/policy.yaml. Fallback: ~/.config/tirith/policy.yaml.

Features: allowlists, blocklists, severity overrides, fail-open/closed
modes, scan profiles, org trust lists. See docs/cookbook.md.

Diagnostics

tirith doctor                   # full diagnostic
tirith doctor --fix             # auto-fix detected issues
tirith doctor --fix --yes       # non-interactive fix
tirith doctor --format json     # machine-readable diagnostic

Background daemon

Speed up repeated checks with a persistent daemon:

tirith daemon start     # start in foreground
tirith daemon stop      # stop running daemon
tirith daemon status    # check status and measure latency

Output Behavior

Exit codes

Code	Action	Meaning
0	Allow	Safe — no findings or all findings are informational
1	Block	Dangerous — execution prevented
2	Warn	Suspicious — execution allowed, user notified
3	WarnAck	Warn with strict acknowledgement required

Output streams per command

Command	JSON	Human
check, paste	stdout	stderr
run, score, diff	stdout	stderr
receipt	stdout	stderr
scan	stdout	stderr
warnings	stdout	stdout
warnings --summary	n/a	stderr
checkpoint	stdout	stdout
fetch	stdout	stdout
explain	stdout	stdout
doctor	stdout	stdout
audit	stdout	stdout

Format flags

Most commands accept --format human|json (default: human).

Scope	Valid formats
Most commands	--format human|json
scan	--format human|json|sarif
audit export	--format json|csv
audit report	--format markdown|json|html

Legacy --json is accepted on most JSON-capable commands.
audit export and audit report use --format only.

MCP Tools

When running as an MCP server (tirith mcp-server), these tools are
available to AI agents:

Tool	Description
tirith_check_command	Analyze shell commands for pipe-to-shell, homograph URLs, env injection
tirith_check_url	Score URLs for homograph attacks, punycode tricks, shortened URLs
tirith_check_paste	Check pasted content for ANSI escapes, bidi controls, zero-width chars
tirith_scan_file	Scan a file for hidden content, invisible Unicode, config poisoning
tirith_scan_directory	Recursive scan with AI config file prioritization
tirith_verify_mcp_config	Validate MCP configs for insecure servers, shell injection in args
tirith_fetch_cloaking	Detect server-side cloaking (different content for bots vs browsers)

Register: tirith setup claude-code --with-mcp
Run manually: tirith mcp-server (JSON-RPC over stdio)

Subcommand Reference

Command	Purpose
check	Analyze a command before execution
paste	Check pasted content for threats
run	Safely download and execute a script (Unix)
score	Risk-score a URL
diff	Compare a URL against known-good patterns
scan	Scan files for hidden content and config poisoning
fetch	Detect server-side cloaking (Unix)
why	Explain the last triggered rule
explain	Show documentation for a detection rule
setup	Configure tirith for an AI coding tool
init	Generate shell hook source line
doctor	Diagnose installation and configuration
policy	Manage security policies (init, validate, test)
audit	Export verdicts, stats, and compliance reports
trust	Manage trusted patterns with TTL and rule scoping
receipt	Manage execution receipts from tirith run
checkpoint	File checkpoints for rollback before risky operations
warnings	Show accumulated session warnings
threat-db	Manage threat intelligence database
gateway	MCP gateway proxy for AI agent security
mcp-server	Run as MCP server (JSON-RPC over stdio)
daemon	Background daemon for faster checks
license	Show or manage license status
activate	Activate a license key