somoore/sir
GitHub: somoore/sir
一个为 AI 编码代理设计的运行时安全框架，通过多层防护与可验证日志解决智能工具链的意图滥用与数据泄露问题。
Stars: 1 | Forks: 0
# 先生 — 反向沙箱
session → SECRET"] A -->|② curl external| S2["sir: DENY
session is SECRET"] S1 -. IFC taint .-> S2 ``` 同一回合，两次工具调用，不同裁决 —— 预言机的决策因两者之间的会话状态变化而改变。这是[信息流控制](mister-core/src/ifc.rs)，而不是静态规则列表。 - **Claude Code** — **Reference support.** 完整的 10 个生命周期钩子，支持原生交互式批准和完整的工具路径覆盖。 - **Gemini CLI** — **Near-parity support.** 6 个钩子事件在 Gemini CLI 0.36.0+ 上触发，完整的工具路径覆盖用于文件 IFC 标记、Shell 分类、MCP 扫描和凭据输出扫描。缺失的生命周期钩子：SubagentStart、ConfigChange、InstructionsLoaded 和 Elicitation。参见 [gemini-support.md](docs/user/gemini-support.md)。 - **Codex** — **Limited support.** 在 `codex-cli` 0.118.0+ 上启用 `codex_hooks` 特性标志后，触发 5 个钩子事件，且上游钩子表面仅限于 Bash。Bash 介导的敏感读取预先拦截，但原生文件写入和 MCP 工具仍处于 PreToolUse 之外；sir 依赖哨兵哈希加上最终的 `Stop` 扫描作为后备。参见 [codex-support.md](docs/user/codex-support.md)。 ## 为什么要使用 sir 沙箱看到进程发起网络调用。sir 看到 *原因* —— 代理读取了 `.env` 中的 AWS 凭证、不可信 MCP 服务器指示它“转发凭证用于分析”，现在将其编码在查询参数中。对沙箱来说，这与 `npm install` 看起来完全相同。sir 添加了上下文层，使包含决策变得智能而非二元。 - **密钥和污点传播。** 读取的密钥会污染后续的每一次写入、提交或推送尝试（通过 IFC，与工具无关）。 - **MCP 提示注入。** 扫描 MCP 参数中的凭证和响应中的注入模式，污化不可信服务器，强制重新批准。 - **本地审计追踪。** 代理实际执行操作的可篡改证据账本 —— 记录提供者日志无法捕获。 - **安静处理正常编码，危险转换时告警。** 仅外部网络、秘密外发、姿态篡改和 MCP 注入会触发提示或拒绝。 ### 三层防护 | 层 | 机制 | 捕获内容 | 绕过方式 | |----|------|----------|----------| | **1. 意图分类** | 钩子层动词/目标分析 | 明显的 exfil 路径（`curl evil.com`、`git push evil-fork`、`.env` + 出站） | 编码、工具替换 | | **2. IFC 污点传播** | 会话状态 — 工具无关 | 任何在读取密钥之后的退出，无论使用什么工具 | 回合边界重置、未识别的密钥路径 | | **3. 运行时 containment** | OS 级（`sir run`）— 网络命名空间（Linux）、`sandbox-exec`（macOS） | 所有网络外发，无论钩子 | OS 原语逃逸（不同威胁类别）。实验性。 | exfiltration 需要同时突破这三层。提供者审计日志止步于治理层；sir 在所有三层（治理、检测、调查）记录脱敏证据。参见 [observability-design.md](docs/research/observability-design.md)。 ## 安装 **预构建二进制文件（推荐）：** ``` curl -fsSL https://raw.githubusercontent.com/somoore/sir/main/scripts/download.sh | bash # 或固定特定版本： curl -fsSL https://raw.githubusercontent.com/somoore/sir/main/scripts/download.sh | bash -s -- v0.0.6 ``` 安装程序会在安装前验证 `checksums.txt` 上的 cosign 签名（如果可用）以及 tarball 的 SHA-256 校验和。两个安装路径都会写入 `~/.sir/binary-manifest.json`，以便 `sir verify` 能检测到安装后的篡改。完整的发行版验证请参见 [`scripts/verify-release.sh`](scripts/verify-release.sh)。 **从源码构建**（需要克隆仓库）： ``` git clone https://github.com/somoore/sir.git && cd sir # 需要 [Rust 1.94.0](https://rustup.rs/)（在 rust-toolchain.toml 中固定） # 需要 [Go 1.22+](https://go.dev/dl/) 并启用工具链自动获取至 go1.25.9 make build make install ``` 然后在任何项目中运行：`sir install # 自动检测本机已支持的代理` **更新：** 重新运行相同的下载命令。安装程序会就地覆盖二进制文件；`~/.sir/` 中的钩子和会话状态会被保留。`sir version --check` 会告诉你是否有新版本（仅提示信息，不会自动更新）。 **托管式部署**（企业）：`export SIR_MANAGED_POLICY_PATH=/etc/sir/managed-policy.json && sir install --agent claude` **卸载：** `sir uninstall && rm -f ~/.local/bin/sir ~/.local/bin/mister-core` ## 验证其有效性 ``` sir status # hooks installed, session posture, last contained-run info sir doctor # hook subtree intact, ledger chain verifies, sentinels unchanged sir verify # binary integrity — sir and mister-core match install-time manifest sir log verify # walk the hash chain and report first corruption, if any ``` 1. 让代理读取 `.env`。sir 标记会话被污染。 2. 在同一回合中，让它执行 `curl https://httpbin.org/get`。sir 拒绝该请求。 3. 运行 `sir explain --last` 查看因果链。 这就是 IFC 污点传播 —— 第 1 层和第 2 层协同工作。第 3 层请参见上方 [三层防护](#three-enforcement-layers) 章节中的 `sir run`。 ## 硬限制 sir 目前处于 v1 实验阶段。做出的工程权衡包括： - 钩子和工具边界仅此而已 —— 不是主机防火墙。如果工具执行器忽略钩子响应，sir 无法阻止它。 - MCP 注入检测基于约 50 个正则表达式 —— 编码、意译或非英文表述可能绕过。污化服务器需要重新批准。 - 回合边界使用 30 秒间隔启发式（可被博弈）。Shell 分类基于前缀感知，而非完整的 POSIX。 - 默认许可允许推送到源、提交、循环回路和委派。可通过 `sir trust`、`sir allow-host` 或托管策略收紧。 - 模型内部推理不在考虑范围内。Codex 受限于上游仅支持 Bash 的钩子表面。 - 如果 `mister-core` 不在 `PATH` 中，Go 会回退到故意受限的子集。兼容性测试确保回退绝不会更宽松。 - `mister-core` 在每个进程首次使用时会根据安装时清单进行验证。篡改后的预言机会对所有工具调用执行硬拒绝。 ## 日常使用 - 在每台机器上运行一次 `sir install`。正常使用你的代理。 - `sir log`、`sir explain --last`、`sir why` 和 `sir doctor` 是你的调查工具。 - `sir mcp` 和 `sir mcp wrap` 检查或加固基于命令的 MCP 服务器。`sir unlock`、`sir allow-host`、`sir allow-remote` 和 `sir trust` 可扩大许可范围。 ## 文档 **用户** — [运行时行为](docs/user/runtime-security-overview.md) · [常见问题](docs/user/faq.md) · 代理设置：[Claude](docs/user/claude-code-hooks-integration.md) · [Gemini](docs/user/gemini-support.md) · [Codex](docs/user/codex-support.md) **贡献者** — [CONTRIBUTING.md](CONTRIBUTING.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/README.md](
[](https://github.com/somoore/sir/releases/latest) [](#what-it-is) [](#hard-limits)
[](https://securityscorecards.dev/viewer/?uri=github.com/somoore/sir) [](https://www.bestpractices.dev/projects/12462) [](LICENSE)
**Supported platforms: macOS (Apple Silicon) and Linux (amd64, arm64).** Intel Mac and Windows are not yet supported.
## 快速开始
```
curl -fsSL https://raw.githubusercontent.com/somoore/sir/main/scripts/download.sh | bash
cd /path/to/project
sir install # auto-detect supported agents already on this machine
```
仅此而已。sir 在危险发生前是隐形的。
## 它是什么
一个 Go CLI + Rust 策略预言机 + 哈希链式账本。sir 拦截代理工具调用，决定允许 / 询问 / 拒绝，并将每个裁决写入仅追加的账本，可通过 `sir log verify` 验证。没有守护进程，也不打电话回家。
```
flowchart LR
A[Agent] -->|① Read .env| S1["sir: allowsession → SECRET"] A -->|② curl external| S2["sir: DENY
session is SECRET"] S1 -. IFC taint .-> S2 ``` 同一回合，两次工具调用，不同裁决 —— 预言机的决策因两者之间的会话状态变化而改变。这是[信息流控制](mister-core/src/ifc.rs)，而不是静态规则列表。 - **Claude Code** — **Reference support.** 完整的 10 个生命周期钩子，支持原生交互式批准和完整的工具路径覆盖。 - **Gemini CLI** — **Near-parity support.** 6 个钩子事件在 Gemini CLI 0.36.0+ 上触发，完整的工具路径覆盖用于文件 IFC 标记、Shell 分类、MCP 扫描和凭据输出扫描。缺失的生命周期钩子：SubagentStart、ConfigChange、InstructionsLoaded 和 Elicitation。参见 [gemini-support.md](docs/user/gemini-support.md)。 - **Codex** — **Limited support.** 在 `codex-cli` 0.118.0+ 上启用 `codex_hooks` 特性标志后，触发 5 个钩子事件，且上游钩子表面仅限于 Bash。Bash 介导的敏感读取预先拦截，但原生文件写入和 MCP 工具仍处于 PreToolUse 之外；sir 依赖哨兵哈希加上最终的 `Stop` 扫描作为后备。参见 [codex-support.md](docs/user/codex-support.md)。 ## 为什么要使用 sir 沙箱看到进程发起网络调用。sir 看到 *原因* —— 代理读取了 `.env` 中的 AWS 凭证、不可信 MCP 服务器指示它“转发凭证用于分析”，现在将其编码在查询参数中。对沙箱来说，这与 `npm install` 看起来完全相同。sir 添加了上下文层，使包含决策变得智能而非二元。 - **密钥和污点传播。** 读取的密钥会污染后续的每一次写入、提交或推送尝试（通过 IFC，与工具无关）。 - **MCP 提示注入。** 扫描 MCP 参数中的凭证和响应中的注入模式，污化不可信服务器，强制重新批准。 - **本地审计追踪。** 代理实际执行操作的可篡改证据账本 —— 记录提供者日志无法捕获。 - **安静处理正常编码，危险转换时告警。** 仅外部网络、秘密外发、姿态篡改和 MCP 注入会触发提示或拒绝。 ### 三层防护 | 层 | 机制 | 捕获内容 | 绕过方式 | |----|------|----------|----------| | **1. 意图分类** | 钩子层动词/目标分析 | 明显的 exfil 路径（`curl evil.com`、`git push evil-fork`、`.env` + 出站） | 编码、工具替换 | | **2. IFC 污点传播** | 会话状态 — 工具无关 | 任何在读取密钥之后的退出，无论使用什么工具 | 回合边界重置、未识别的密钥路径 | | **3. 运行时 containment** | OS 级（`sir run`）— 网络命名空间（Linux）、`sandbox-exec`（macOS） | 所有网络外发，无论钩子 | OS 原语逃逸（不同威胁类别）。实验性。 | exfiltration 需要同时突破这三层。提供者审计日志止步于治理层；sir 在所有三层（治理、检测、调查）记录脱敏证据。参见 [observability-design.md](docs/research/observability-design.md)。 ## 安装 **预构建二进制文件（推荐）：** ``` curl -fsSL https://raw.githubusercontent.com/somoore/sir/main/scripts/download.sh | bash # 或固定特定版本： curl -fsSL https://raw.githubusercontent.com/somoore/sir/main/scripts/download.sh | bash -s -- v0.0.6 ``` 安装程序会在安装前验证 `checksums.txt` 上的 cosign 签名（如果可用）以及 tarball 的 SHA-256 校验和。两个安装路径都会写入 `~/.sir/binary-manifest.json`，以便 `sir verify` 能检测到安装后的篡改。完整的发行版验证请参见 [`scripts/verify-release.sh`](scripts/verify-release.sh)。 **从源码构建**（需要克隆仓库）： ``` git clone https://github.com/somoore/sir.git && cd sir # 需要 [Rust 1.94.0](https://rustup.rs/)（在 rust-toolchain.toml 中固定） # 需要 [Go 1.22+](https://go.dev/dl/) 并启用工具链自动获取至 go1.25.9 make build make install ``` 然后在任何项目中运行：`sir install # 自动检测本机已支持的代理` **更新：** 重新运行相同的下载命令。安装程序会就地覆盖二进制文件；`~/.sir/` 中的钩子和会话状态会被保留。`sir version --check` 会告诉你是否有新版本（仅提示信息，不会自动更新）。 **托管式部署**（企业）：`export SIR_MANAGED_POLICY_PATH=/etc/sir/managed-policy.json && sir install --agent claude` **卸载：** `sir uninstall && rm -f ~/.local/bin/sir ~/.local/bin/mister-core` ## 验证其有效性 ``` sir status # hooks installed, session posture, last contained-run info sir doctor # hook subtree intact, ledger chain verifies, sentinels unchanged sir verify # binary integrity — sir and mister-core match install-time manifest sir log verify # walk the hash chain and report first corruption, if any ``` 1. 让代理读取 `.env`。sir 标记会话被污染。 2. 在同一回合中，让它执行 `curl https://httpbin.org/get`。sir 拒绝该请求。 3. 运行 `sir explain --last` 查看因果链。 这就是 IFC 污点传播 —— 第 1 层和第 2 层协同工作。第 3 层请参见上方 [三层防护](#three-enforcement-layers) 章节中的 `sir run`。 ## 硬限制 sir 目前处于 v1 实验阶段。做出的工程权衡包括： - 钩子和工具边界仅此而已 —— 不是主机防火墙。如果工具执行器忽略钩子响应，sir 无法阻止它。 - MCP 注入检测基于约 50 个正则表达式 —— 编码、意译或非英文表述可能绕过。污化服务器需要重新批准。 - 回合边界使用 30 秒间隔启发式（可被博弈）。Shell 分类基于前缀感知，而非完整的 POSIX。 - 默认许可允许推送到源、提交、循环回路和委派。可通过 `sir trust`、`sir allow-host` 或托管策略收紧。 - 模型内部推理不在考虑范围内。Codex 受限于上游仅支持 Bash 的钩子表面。 - 如果 `mister-core` 不在 `PATH` 中，Go 会回退到故意受限的子集。兼容性测试确保回退绝不会更宽松。 - `mister-core` 在每个进程首次使用时会根据安装时清单进行验证。篡改后的预言机会对所有工具调用执行硬拒绝。 ## 日常使用 - 在每台机器上运行一次 `sir install`。正常使用你的代理。 - `sir log`、`sir explain --last`、`sir why` 和 `sir doctor` 是你的调查工具。 - `sir mcp` 和 `sir mcp wrap` 检查或加固基于命令的 MCP 服务器。`sir unlock`、`sir allow-host`、`sir allow-remote` 和 `sir trust` 可扩大许可范围。 ## 文档 **用户** — [运行时行为](docs/user/runtime-security-overview.md) · [常见问题](docs/user/faq.md) · 代理设置：[Claude](docs/user/claude-code-hooks-integration.md) · [Gemini](docs/user/gemini-support.md) · [Codex](docs/user/codex-support.md) **贡献者** — [CONTRIBUTING.md](CONTRIBUTING.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/README.md](
标签：AI安全, AMD64, Apple Silicon, ARM64, Chat Copilot, EVTX分析, Go CLI, Hook层, IFC, NIDS, Rust, 不可变日志, 信息流控制, 可视化界面, 哈希链账本, 实验性, 审计验证, 容器化, 意图分类, 操作系统级隔离, 日志审计, 权限控制, 沙箱, 策略编排, 网络流量审计, 逆向沙箱, 防篡改, 预发布