Imported from sheeki03/tirith (SKILL.md). Install upstream with npx skills add sheeki03/tirith. Copyright stays with the author.

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:

Tier 1 — compiled regex fast gate (sub-millisecond)
Tier 2 — URL/Docker ref extraction, byte scanning for control chars
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 checks commands accepted by a supported interactive shell while its hook is loaded and healthy. Blocking behavior is shell/mode-specific; use tirith doctor to verify effective protection. 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   # blocking PreToolUse; project/user
tirith setup cline                    # POSIX/Windows PreToolUse + MCP; user
tirith setup codex                    # MCP gateway; optional --install-zshenv
tirith setup copilot-cli              # blocking hook; project/repo root
tirith setup continue                 # MCP only; project
tirith setup cursor                   # hook + gateway; project/user
tirith setup fx                       # MCP only; trusted user profile
tirith setup gemini-cli --with-mcp    # blocking hook; optional MCP
tirith setup grok-build               # POSIX hook + MCP; project/user
tirith setup kiro                     # agent-scoped hook; project/user
tirith setup omp                      # blocking guard + MCP; user/profile
tirith setup openclaw                 # blocking plugin; project/user
tirith setup opencode                 # MCP only; project/user
tirith setup openhands                # POSIX hook + user MCP
tirith setup pi-cli                   # blocking extension; project/user
tirith setup prime-agent              # bash/IPython guard + MCP; user
tirith setup roo-code                 # MCP only; project
tirith setup vscode                   # workspace hook + gateway; project
tirith setup windsurf                 # hook + gateway; user

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

MCP-only registration is cooperative and does not force a command check. Host-native hooks are automatic only after the host loads and honors them. Restart the host and run its documented allow/block verification after setup or an upgrade. See mcp/clients/mcp-only-agents.md for the complete trust matrix.

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

Inspect and enforce Python packages

Inspect exact local artifacts without downloading them:

tirith package inspect --artifact dist/example-1.0-py3-none-any.whl
tirith package inspect --artifact-set ./downloaded-wheels
tirith package inspect --installed ./.venv

On x86_64 Linux, approve and install a hash-pinned pip plan through the native authority and containment capsule:

tirith pkg trust-tool /absolute/path/to/static-uv
tirith pkg approve pip requests==2.31.0 --target .tirith-pkg
tirith pkg install pip requests==2.31.0 --target .tirith-pkg
tirith pkg verify-env --target .tirith-pkg requests
tirith pkg receipt last

Unsupported platforms refuse before pip starts. npm and Cargo are evidence surfaces, not enforcing package-firewall backends.

Explicit task, capsule, browser, and attestation workflows

tirith task check --file task-envelope.json       # diagnostic; executes nothing
tirith capsule run --preset untrusted-project \
  --project ./untrusted -- /bin/sh -c 'make test' # x86_64 Linux only
tirith browser audit --browser chrome
tirith pkg attest-npm --project .
tirith attest build --help
tirith attest deployment --help

These commands have command-specific evidence exit codes; do not assume the tirith check 0/1/2/3 ladder. See docs/compatibility.md.

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

This is the tirith check and shell-hook verdict ladder. Evidence-oriented commands such as task check, capsule run, browser audit, pkg attest-npm, and attest define command-specific codes in docs/compatibility.md.

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)

The preview tirith_check_task tool is absent and refused by name unless the server starts with TIRITH_MCP_PREVIEW=1. The default tool list is a frozen compatibility contract.

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
`package`	Package risk, installed-tree scan, and exact artifact/environment inspection
`pkg`	Python package approval/install/verification plus provenance and receipt evidence
`ecosystem`	Scan a project's declared or installed dependencies
`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 download receipts recorded by `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`	Lock, verify, diff, and explain repository MCP configuration
`mcp-server`	Run as MCP server (JSON-RPC over stdio)
`task`	Diagnostic untrusted-task assessment (preview)
`capsule`	Fail-closed untrusted-project containment on supported x86_64 Linux
`browser`	Native-messaging setup and Chromium-family extension audit
`attest`	Point-in-time build and deployment receipts
`daemon`	Background daemon for faster checks
`license`	Show or manage license status
`activate`	Activate a license key

tirith

About