DOCSEARCHbyAlgolia
Submit Docs

tirith

repository·main·Indexed 25 days ago

https://github.com/sheeki03/tirith

A terminal security tool that acts as a pre-execution gate to detect homograph attacks, obfuscated payloads, and credential exfiltration. It provides shell hooks to protect against malicious commands and pastes, scans files and ecosystems for supply-chain risks, and offers an MCP server for AI agents. Features include a signed threat database, package risk scoring, and workstation hygiene auditing.

Tokens
69.3K
Snippets
188
Records
386
Agent score
79%

What's inside tirith

  1. Overview of the tirith product line

    main

    tirith offers several tiers of protection:

    1. tirith (OSS, free): The core shell hook for individual developers.
    2. tirith feed (paid): A live threat intelligence feed consumed by the free tool. Includes a policy engine, audit export, and admin dashboard for teams.
    3. tirith ci (paid): A GitHub App and CI scanner that finds execution-prone links and commands in documentation, scripts, and workflows.
    4. tirith monitor (paid): Continuous domain monitoring for project maintainers, providing actionable alerts and abuse report templates.

  2. Overview of tirith CLI commands

    main

    tirith provides a wide range of commands for security analysis, policy management, and system protection.

    Core Commands:

    • tirith check -- <cmd>: Analyze a command without executing it. Use --suggest for a safer rewrite.
    • tirith paste: Check pasted content (used by shell hooks).
    • tirith scan [path]: Scan files, directories, and configs. Supports --profile, --format sarif, and --ci.
    • tirith run <url>: A safe replacement for curl | bash. Downloads, analyzes, reviews, and then executes.
    • tirith fix -- <cmd>: Interactively rewrite a risky command into a safer form.
    • tirith score <url> / diff <url>: Analyze a URL's trust signals or identify suspicious characters.
    • tirith explain --rule <id> / why: View rule documentation/remediation or explain the last trigger.
    • tirith status / doctor: Check protection status and diagnose installation/hooks/policy issues.
    • tirith setup <tool> / init: One-command AI-tool setup or print shell hooks.
    • tirith policy {init,validate,test}: Scaffold, validate, or dry-run your policy.
    • tirith trust {add,list,remove}: Manage trusted patterns (30-day TTL by default).
    • tirith threat-db update: Download and verify the signed threat database.
    • tirith package risk <eco> <name>: Score a package's supply-chain risk.
    • tirith ecosystem scan [path]: Score every declared dependency in a project.
    • tirith mcp {lock,verify}: Pin and gate a repository's MCP servers.
    • tirith daemon start: Start a background daemon for faster checks (Unix).

    Use the global --quiet flag or TIRITH_QUIET=1 to silence advisory output while keeping errors and security notices.

  3. Compare tirith with other security tools

    main
    Unlike tools that focus on code vulnerabilities (Semgrep), known CVEs in dependencies (Snyk), or malicious packages in registries (Socket), tirith protects the human developer at the moment of command execution. It targets terminal-specific attacks such as spoofed URLs, hostile scripts, and terminal injection by using a byte-level URL + source-sink model and terminal escape detection.

  4. Understand the Tirith Shell-Hook Conformance Contract

    main

    Tirith installs shell hooks (bash, zsh, fish, PowerShell, nushell) to intercept commands before execution. To ensure safety and correctness, every hook must satisfy seven core invariants:

    1. Executes exactly once: Allowed commands run exactly once.
    2. Not swallowed: Allowed commands are delivered to the shell and their output reaches the terminal.
    3. No history duplication: Executed commands appear in shell history exactly once.
    4. A blocked command does not execute: Blocked commands have no side effects.
    5. A warned command executes once: warn verdicts are advisory; the command still runs once.
    6. Degradation is visible, not silent: If protection guarantees cannot be met, the tool must notify the user and potentially persist a safe-mode flag rather than failing silently.
    7. Non-interactive shells carry no tirith status: Sourcing the hook in non-interactive shells (e.g., bash -c, scripts) installs nothing. The TIRITH_STATUS prompt indicator is a non-exported variable and is not inherited by non-interactive children.

  5. Understand tirith Privacy Design

    main

    tirith is designed with a privacy-first approach:

    • Local Execution: Commands, URLs, and audit logs are analyzed entirely locally and never leave the machine by default.
    • One-way Feed Sync: The client performs a one-way pull to download threat feeds; it does not upload local data.
    • Opt-in Receipt Sharing: Users can optionally share anonymized receipt hashes (URL + SHA256 only) to help detect compromised scripts. This is off by default.
    • Explicit Team Ingestion: Audit log shipping to the team dashboard requires explicit enrollment and per-machine configuration.
    • Aggressive Redaction: Shared data (like opt-in hashes or team logs) has path components, environment variables, and git branch names stripped. Only the URL, action, and timestamp are transmitted.

  6. Understand the tirith product line and pricing

    main

    tirith offers several tiers of protection ranging from free open-source tools to paid enterprise services:

    1. tirith: The core Open Source Software (OSS) version, which is free to use.
    2. tirith feed: A paid subscription ($7/mo for individuals, $15/seat/mo for teams) providing a continuously updated threat feed of known-malicious domains.
    3. tirith ci: A paid service ($50-500/mo depending on organization size) that scans repositories for URL execution surfaces in documentation, scripts, and configurations.
    4. tirith monitor: A paid service ($30/mo per domain) for domain monitoring and actionable alerts.

  7. Understand the tirith threat model and protection policies

    main

    tirith protects against several classes of terminal-based attacks by applying specific security policies to pasted content:

    Terminal Escape and Control Character Attacks

    Any control character other than \n (newline) and \t (tab) is BLOCK by default. Any ANSI escape sequence is BLOCK by default. This prevents:

    • ANSI escape injection: Rewriting displayed text to hide malicious commands.
    • Carriage return (\r) tricks: Forcing immediate submission or overwriting visible text.
    • Backspace (\b) tricks: Visually overwriting characters while keeping the malicious bytes in the buffer.
    • Unicode bidi override: Using RTL/LTR characters (e.g., U+202E) to flip display order.
    • Zero-width characters: Using ZWJ, ZWNJ, or zero-width spaces to create visually deceptive domains/paths.

    Source-Sink Execution Model

    tirith identifies risks by modeling commands as a graph of sources (fetching remote content) and sinks (executing content). A connection between a source and a sink triggers a warning.

    Sources include: curl, wget, fetch, aria2c, httpie, git clone/pull, docker pull/build, scp, rsync, nc, ncat, socat, and language-specific fetchers (e.g., python -c "import urllib...").

    Sinks include: Shells (sh, bash, zsh, fish, etc.), interpreters (python, node, perl, ruby, php), and execution primitives (eval, exec, source, ., sudo sh, xargs sh -c).

    PowerShell specific mappings:

    • Sources: Invoke-WebRequest (iwr), Invoke-RestMethod (irm), wget (alias), curl (alias).
    • Sinks: Invoke-Expression (iex), & (call operator), Start-Process, powershell -Command.

  8. Understand the Agent Governance threat model

    main

    Tirith's agent governance provides observability and policy capabilities based on the identity of the caller (e.g., a human, an AI agent, an MCP client, or a CI runner).

    Important Security Note: The attribution signals used to determine AgentOrigin are not adversary-resistant. Signals like TIRITH_INTEGRATION, GITHUB_ACTIONS, or MCP clientInfo are set by the process running as the user. An attacker who has already executed code as that user can spoof these values. Tirith is not a replacement for OS-level sandboxing; it is an operator-trust mechanism for auditing and policy enforcement.

  9. Understand the TIRITH_STATUS variable

    main

    When the tirith shell hook is active, it sets a non-exported shell variable named TIRITH_STATUS to describe the live protection level of the current shell. This variable is intended to be referenced in your prompt (PS1, fish_prompt, or PowerShell prompt function) to make the protection state visible.

    Important Note: TIRITH_STATUS is a non-exported shell variable, not an environment variable. This prevents non-interactive child processes (like scripts) from inheriting a misleading protection status. Because it is not exported, external prompt renderers that run as separate processes (like Starship) cannot see it unless you explicitly export it in your shell configuration.

  10. Compare `tirith doctor` Full vs Quick modes

    main

    Choose between the default full diagnostic and the quick snapshot based on your requirements:

    FeatureFull (tirith doctor)Quick (tirith doctor --quick)
    PurposeComplete installation/config diagnosticFast, read-only status snapshot
    PerformanceCan be expensive (parses large logs, walks PATH)Very cheap; safe for frequent polling
    Probes IncludedShell/hook state, policy discovery, threat-DB, anomaly-baseline, audit logs, shadow-binaries, bash enter-modeOnly essential status fields
    OutputDetailed diagnostic reportShort summary (human) or minimal JSON

  11. Understand Tirith Stability Tiers

    main

    Tirith subcommands are categorized into two stability tiers which dictate how much you can rely on their interface:

    • Stable: Flags, exit codes, and output formats are guaranteed to be backwards-compatible within a major version. Use these for critical integrations like shell hooks or MCP.
    • Experimental: The interface (flags, schema, etc.) may change without notice. Use these for testing new features.

    Stable Commands:

    • check: Analyze commands before execution.
    • paste: Analyze pasted content.
    • score: Risk-score a URL.
    • diff: Compare a URL against known-good patterns.
    • why: Explain the last triggered rule.
    • receipt: Manage execution receipts.
    • init: Initialize shell hooks.

    Experimental Commands include:

    • scan, doctor, run, fetch, checkpoint, gateway, setup, policy, trust, warnings, threat-db, daemon, audit, activate, license, mcp-server, lab, completions, manpage.

  12. Install the tirith shell hook

    main

    To enable tirith protection in your terminal, source the tirith.sh wrapper in your shell configuration file (e.g., .zshrc or .bashrc). This installs the shell hook that intercepts commands containing URLs or suspicious characters.

    # One line in .zshrc / .bashrc
source ~/.tirith/tirith.sh