tirith Agent工作流

Ecosystem scan and dependency risk

tirith ecosystem scan [path] is the directory-level companion to package risk. It walks a project, discovers every dependency manifest it understands, npm (package.json, package-lock.json), Python (requirements*.txt, pyproject.toml), Rust (Cargo.toml), Go (go.mod), Ruby (Gemfile), and scores every declared dependency with the same deterministic package_risk factor engine.

tirith ecosystem scan                       # scan the current project
tirith ecosystem scan ./my-project          # scan a specific directory
tirith ecosystem scan --online ./my-project # also consult the registry API
tirith ecosystem scan --format json ./      # full machine-readable report

It folds in slopsquat detection. Slopsquatting is the registration of a plausible-but-fake name that LLMs tend to hallucinate as a dependency. ecosystem scan flags one only when all three hold: the name is not known-real or popular, it is shaped like an AI hallucination (a language prefix like python- / node- plus descriptive tokens, a stack of generic filler like helper / utils / client, or an unusually long name), and it sits near a real popular name (a one-edit near-miss, or it embeds a popular name as a word). Requiring all three keeps false positives low: an honest data-utils with no popular anchor does not fire.

Offline by default, opt-in --online. Name and typosquat signals come from the local threat database; --online adds registry provenance, gated and degraded exactly as package risk --online. This flag controls the ecosystem scan and does not alter tirith check's independent runtime-enrichment policy. Findings flow through tirith's normal Verdict / Finding model: explainable (tirith explain --rule threat_suspicious_package), audit-logged, and respecting the policy allowlist (an allowlisted package, by bare name or ecosystem:name, is suppressed). Exit codes match tirith scan: 1 for a blocking finding, 2 for advisory, 0 when clean.

This helps catch known-malicious packages, confirmed typosquats, slopsquatted package names, malicious download infrastructure, and packages with live OSV / CISA KEV advisory data.

Python artifact inspection and enforcing installs

Package-name risk is only one layer. Tirith can inspect the exact Python bytes you already have and, on supported hosts, enforce a hash-pinned install plan:

```bash

Enforcing pip workflow: x86_64 Linux only

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 ```

Inspection covers wheel structure and identity, RECORD integrity and file ownership, Python startup hooks, native ELF/Mach-O/PE extensions, execution edges, and loader/payload splits across distributions. pkg graph, pkg diff, pkg attest, and pkg receipt expose the corresponding provenance and receipt evidence.

The enforcing path supports pip on x86_64 Linux only and requires the documented native authority, a newly dedicated target directory, and an enrolled fully static native uv. Every unsupported platform fails closed before pip starts; it never falls back to an ordinary install. npm and Cargo remain non-enforcing evidence surfaces. See the 0.4.0 release notes and command reference.

Attack families tirith is built for (illustrative, not a caught-by-current-code claim):

Package-name extraction currently covers language ecosystems (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), not distro-level package managers (apt / dnf / yum / pacman). That's why xz-utils, which entered through Linux distro tarballs, is not in the table despite being a headline incident.

---

Install

or try without installing: nix run github:sheeki03/tirith -- --version

```

Download the musl build from the latest GitHub release:

curl -fsSL -o tirith.tar.gz \ https://github.com/sheeki03/tirith/releases/latest/download/tirith-aarch64-unknown-linux-musl.tar.gz tar xzf tirith.tar.gz install -Dm755 tirith "$PREFIX/bin/tirith" tirith --version

Then activate the shell hook in `~/.bashrc` (Termux's default shell is bash):

[!NOTE] Termux support is best-effort. The musl artifact is built and smoke-tested in CI, but tirith is not yet continuously tested on a real Android device. If a hook misbehaves under Termux, please open an issue with tirith doctor output.

Upgrade an existing Chocolatey installation:

choco upgrade tirith ```

Chocolatey moderation can lag the GitHub release. Run choco info tirith to see the currently approved version. Use Scoop or a signed artifact from GitHub Releases when the newest release is required before Chocolatey moderation finishes.

Config file scanning

tirith scan detects prompt injection and hidden payloads in AI config files. It prioritizes and scans 50+ known AI config file patterns:

• .cursorrules, .windsurfrules, .clinerules, CLAUDE.md, copilot-instructions.md
• .claude/ settings, agents, skills, plugins, rules
• .cursor/, .vscode/, .windsurf/, .cline/, .continue/, .roo/, .codex/ configs
• mcp.json, .mcp.json, mcp_settings.json
• .github/copilot-instructions.md, .github/agents/*.md

What it catches in configs:

• Prompt injection (skill activation triggers, permission bypass attempts, safety dismissal, identity reassignment, cross-tool override instructions). Each file is scanned both raw and deobfuscated (invisible characters, confusables, inter-character spacing, leetspeak, short base64 / hex), so a seed hidden behind encoding still fires
• Invisible Unicode: zero-width characters (including Mongolian Vowel Separator), bidi controls, soft hyphens, Unicode tags, Hangul fillers, invisible whitespace encoding, math alphanumeric confusables
• MCP config issues: insecure HTTP connections, raw IP servers, shell metacharacters in args, duplicate server names, wildcard tool access

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; (3) install / lifecycle scripts and (4) bundled binary blobs, detected only when the package content is locally available (under node_modules / site-packages, or via --path). tirith never downloads the package.

--online adds registry provenance. It consults the package's registry (npm, PyPI, or crates.io) for six more factors in the same factor-sum model: package/version age, an established package with no owners, an abnormal version spike, very low downloads, a missing source repo, and yanked/deprecated status. It is the only path on which package risk itself reaches the network; tirith check and daemon mode have a separate, policy-controlled runtime enrichment path. --offline / TIRITH_OFFLINE force this scorer offline regardless. Failures fall back to the offline score with an honest api signals: unavailable, and responses are cached with a TTL so repeated runs do not hammer the registries.

The score is advisory and standalone: package risk is not a detection rule and changes no verdict, exit code, or audit log.

Linux Packages

Debian / Ubuntu (.deb):

Download from GitHub Releases, then:

sudo dpkg -i tirith_*_amd64.deb

Fedora / RHEL / CentOS 8+ and Amazon Linux 2023 (.rpm):

Download from GitHub Releases, then:

sudo dnf install ./tirith-*.rpm

The Linux GNU release binaries target a GLIBC 2.28 ceiling. CI runs both x86_64 and aarch64 tarballs on AlmaLinux 8, Amazon Linux 2023, and Rocky Linux 9; the .deb and x86_64 .rpm contain those same canonical binaries.

Arch Linux (AUR):

```bash yay -S tirith

Shell Integrations

Oh-My-Zsh:

```bash git clone https://github.com/sheeki03/ohmyzsh-tirith \ ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/tirith

Add tirith to plugins in ~/.zshrc:

plugins=(... tirith) ```

AI Agent Integrations

Use tirith setup <tool> for one-command configuration. This is the complete named setup surface, including both the earlier integrations and the additions released in 0.4.0:

An MCP-only row exposes Tirith's tools but does not force the host to call them. A hook row is automatic only after the host has loaded the generated artifact and still honors its refusal contract. Run tirith doctor, restart the host, and perform the host-shaped allow/block check after setup and every upgrade. Full config paths, precedence rules, fail-open behavior, and verification steps are in the agent integration and trust matrix. See mcp/clients/ for the host-specific guides that are available.

CI/CD Integration

GitHub Action with SARIF upload to GitHub Security tab:

- uses: sheeki03/tirith@v1
  with:
    fail_on: high
    sarif: true

The action's pinned dependencies use the Node 24 action runtime. Self-hosted runners must use Actions Runner v2.327.1 or newer; GitHub-hosted runners already satisfy this requirement.

Also available as a pre-commit hook: see .pre-commit-hooks.yaml in this repo.

Scan supports --include, --exclude, --profile (loads named profiles from policy), and --ignore filters for targeted CI scanning.