tirith: a terminal gate that blocks Cyrillic hostnames, only warns about curl to shell, and documents its own bypass
Terminal security for developers and AI agents. Intercepts homograph URLs, pipe-to-shell, ANSI injection, obfuscated payloads, data exfiltration, and malicious AI skills/configs before they execute.
At a glance
- What is it?
- A Rust tool that intercepts shell commands, pasted text and scanned files before they run, claiming 244 detection rules across 35 categories. The interesting parts are its severity ladder, its refusal to be called an authorization boundary, and a manifest that pins five dependencies below the versions their maintainers require.
- Who is it for?
- tirith is worth installing for a developer workstation that pastes commands from chat, issues and model output, and for a team that wants the obvious attacks to stop before they execute. It is not a control you can hand to a security review as an enforcement point, because the project says so itself.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- sheeki03/tirith2,785 ★ · +74
| Repository | 2026-09-11 | 2026-11-22 |
|---|---|---|
| sheeki03/tirith | 2.7k | 2.8k |
74 Stars in the last 72 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The block output prints the bypass line as part of the block
The opening example sets up the problem with two nearly identical curl commands, one safe and one compromised, where the compromised host contains two Cyrillic i characters identified as U+0456 in place of Latin ones. When that command runs through the hook, the output is a block with a severity in brackets, the rule name non_ascii_hostname, and an explanation that the URL mimics a legitimate domain while resolving somewhere else. The last line of that block is a bypass instruction: prefix your command with TIRITH=0, which applies to that one command. Printing the escape hatch inside the refusal is a deliberate choice, and it cuts both ways. It means a false positive is one variable away from harmless, and it means the protection is one copy and paste away from gone for anyone who reads the output.
A Cyrillic hostname blocks, a clean curl to shell only warns
The severity ladder is the most useful thing to understand about this tool, because the examples in the README are ordered so the difference is visible. The homograph command is blocked at CRITICAL. A base64 decode piped into a shell is blocked at HIGH, with a second HIGH line for the pipe itself, and the same rule catches chains hidden behind sudo or env wrappers and behind the PowerShell encoded command flag. An upload of a local file to a remote address is blocked at HIGH as data exfiltration, covering curl and wget upload flags, environment variables and command substitution. Then there is the case almost everybody hits: curl piped into sh with an entirely clean URL. That one is a MEDIUM pipe_to_interpreter warning printed to stderr, and the command still runs. The everyday pattern is the permissive one.
The README asks you not to treat the hook as an authorization boundary
The installation section is unusually candid about its own limits. The tool installs with a single line, brew install tirith, and then adds itself to your shell profile with one of these:
# zsh
eval "$(tirith init --shell zsh)"
# bash
eval "$(tirith init --shell bash)"
# fish
tirith init --shell fish | sourceThe default form inspects the parent process and falls back to the shell environment variable. What follows is the candid part: commands accepted by that shell are checked while the hook is loaded and healthy, and exact blocking behavior depends on the shell and mode. It tells you to run tirith doctor after installation and after upgrades, and to read the section on enforcement by shell before treating the hook as an authorization boundary. That last clause is the whole story: a shell hook is code another process injects into your interactive shell, it can fail to load, and different shells integrate differently. The tool is a filter, and the documentation declines to pretend otherwise.
244 rules across 35 categories, calibrated against named actor tooling
The detection table is the substance of the project and it is organized by what an attacker is trying to do rather than by data type. Hostname attacks cover Cyrillic and Greek lookalikes, punycode, mixed script labels, confusable domains, lookalike top level domains and text level confusables including mathematical alphanumerics. Terminal injection covers ANSI escapes, bidirectional overrides, zero width characters, unicode tags, invisible math operators, variation selectors and Hangul fillers, and there is a separate steganography category covering twelve unicode space variants, the Mongolian vowel separator and defenses against text steganography tooling. The post compromise category is the one with teeth in terms of intent: process memory reads through proc, Docker remote privilege escalation and credential file sweeps, described as calibrated against TeamPCP and UNC1069 tooling. Two more categories are aimed squarely at agent setups: MCP server configuration problems, and scanning of JS and Python files for obfuscated payloads and secret exfiltration.
AGPL-3.0-only in the manifest, a commercial licence file in the root
The license story takes two forms and the repository does not hide either. The Cargo workspace declares license AGPL-3.0-only, matching the metadata, and the root carries a LICENSE-AGPL file, a NOTICE file, and a LICENSE-COMMERCIAL file beside them. The workspace members include two tools that are not part of the detector at all: a sign-license tool and a license-server crate. That pairing is the clearest sign of a dual licensing arrangement, and it connects to how the tool gets its data, since the README says known bad packages, domains and addresses come from a signed threat intelligence database and the root holds a manifest file describing that database. For an organization that cannot run AGPL software in a shipped product, the commercial file is the path, and the license server in the workspace is probably part of how it is exercised.
Five dependencies are pinned below the versions their maintainers require
The workspace sets rust-version to 1.83, and the dependency table then holds the floor in place with comments explaining each one. home is held below 0.5.12 because the newer release needs edition 2024, which means Rust 1.85. time is held below 0.3.38, and the comment is the most interesting line in the file: a later advisory, RUSTSEC-2026-0009, is ignored in the cargo deny configuration because tirith never parses user controlled RFC 2822 dates. base64ct is held below 1.8 for the same edition reason, reached transitively through the ed25519 chain. idna_adapter is held below 1.2.2, reached through URL and IDNA handling. toml_edit is pinned to an exact version with a note that keeping the line lock compatible preserves the 1.83 floor. So the MSRV is defended at the cost of current dependency versions, and one known advisory is accepted on the record.
The container copies a binary built elsewhere and pins the base image by digest
The Dockerfile is three lines of policy and a copy. It declares itself runtime only, using pre-built binaries from CI with no compilation, and its comments spell out what the build context must already contain: a binary for the target platform and the shell hook directory. The base image is pinned by digest rather than by tag, with a comment explaining that a movable tag could silently swap the base image for attacker controlled content, and recommending the digest be refreshed regularly through a dependency bot so Debian security updates keep arriving. It installs certificate authorities only, removes the apt lists, creates an unprivileged user named tirith, copies the binary into the local bin directory and the hook scripts under share, and ends with the non-root user and an entrypoint of tirith with a default of help. The design is careful and it depends on CI having produced the artifact first.
A scanner for agent skills and configs that ships its own skill, MCP and editor config
One of the categories the tool checks is malicious AI skills and configuration files, and the repository itself is laid out like an agent integration. There is a SKILL.md at the root, a TIRITH.md, a main.md, a .claude directory, a .cursor directory and an mcp directory, plus a Dockerfile and packaging directories for the npm path. There is also an action file, which makes the scanner usable as a GitHub Action, a pre-commit hooks file for the same purpose in a local checkout, a fuzz directory for the Rust targets, and Nix files pinning the development environment. A pre-commit hook and a CI action are the two integrations that matter for a team, and both are configuration files sitting next to the detection rules rather than documented deployment steps.
Editorial conclusion
tirith is worth installing for a developer workstation that pastes commands from chat, issues and model output, and for a team that wants the obvious attacks to stop before they execute. It is not a control you can hand to a security review as an enforcement point, because the project says so itself. Four things to weigh. The severity ladder is uneven: a clean looking curl piped to a shell is a warning while a homograph hostname blocks, so the common case is the permissive one. The shell hook is only as good as the shell it wraps, and the README asks you to run tirith doctor after every upgrade. Each block prints a one command bypass through an environment variable, which is a feature for a false positive and a hole for anyone who learns it. And the workspace pins five dependencies below their current versions to hold an MSRV of 1.83, with one advisory explicitly ignored and the reason written in a comment.
Frequently asked questions
What does tirith block in a terminal?
The README claims 244 detection rules across 35 categories, covering Cyrillic and Greek lookalikes in hostnames, punycode and confusable domains, ANSI escapes and bidirectional overrides, zero width and invisible characters, curl or wget piped to a shell, base64 decode chains including the PowerShell encoded command flag, data exfiltration through upload flags and environment variables, credential detection for cloud keys, provider tokens and private key blocks, and MCP server configuration problems.
Does tirith block every curl to shell command?
No. The README's own example shows a clean curl piped into sh producing a MEDIUM pipe_to_interpreter warning on stderr while the command still runs, whereas the same tool blocks a host containing Cyrillic characters at CRITICAL and blocks a base64 decode chain at HIGH.
How do I bypass tirith for a single command?
The block output includes a bypass line stating that prefixing the command with TIRITH=0 applies to that command only. The feature exists so a false positive does not block work, and it is printed inside the refusal itself.
Is the tirith shell hook an authorization boundary?
The README tells you to read its enforcement by shell section before treating the hook as one, notes that exact blocking behavior depends on the shell and mode, and says commands are checked while the hook is loaded and healthy. It also asks you to run tirith doctor after installation and after upgrades.
What license does tirith use?
The Cargo workspace declares license AGPL-3.0-only, and the repository root holds LICENSE-AGPL, a NOTICE file and a separate LICENSE-COMMERCIAL file. The workspace also builds a tools/license-server and a tools/sign-license crate.
Where does tirith get its list of bad packages and domains?
The README describes a signed threat intelligence database covering known bad packages, domains and IP addresses, and the repository root carries a threatdb-manifest.json describing it. The workspace includes sign-license and license-server tools alongside the detector crates.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sheeki03-tirith)Star history chart for your README
[](https://hysenlabs.com/projects/sheeki03-tirith)Was this useful?