postrv/sanctum-oss
GitHub: postrv/sanctum-oss
为 AI 编程时代的开发者打造的运行时安全守护进程，提供供应链攻击拦截、凭证防火墙和 LLM 消费追踪。
Stars: 3 | Forks: 0
# Sanctum
**为使用 AI 交付代码的开发者打造的运行时安全工具。**
你的 AI 编程助手可以读取你的 SSH 密钥，泄露你的 AWS 凭证，并在你察觉之前产生高达 $10,000 的 API 账单。Sanctum 会在后台默默监控这一切，毫不打扰，也不会拖慢你的速度。
```
curl -fsSL https://raw.githubusercontent.com/postrv/sanctum-oss/main/scripts/install.sh | sh
sanctum init
# 就是这样。daemon 随你的 shell 启动。
```
## 为什么会有这个项目
在 2026 年 3 月 24 日至 31 日的一周内，三大主要的供应链攻击袭击了开发者每天都在使用的生态系统：
- **LiteLLM**（3 月 24 日）—— 被泄露的 PyPI 凭证向 Python 的 `site-packages` 中注入了恶意的 `.pth` 文件。每次解释器启动时 —— 即使只是运行 `python3 --version` —— 都会执行攻击者的代码，窃取 SSH 密钥、云 token 和 `.env` 文件。（[CVE-2026-33634](https://github.com/BerriAI/litellm/issues/24512)，CVSS 9.4）
- **Telnyx Python SDK**（3 月 27 日）—— 恶意的 PyPI 版本利用音频隐写术（payload 隐藏在 WAV 文件中）窃取凭证。相同的威胁行为者 利用了之前从 Trivy 泄露的 CI/CD 密钥。
- **Axios**（3 月 31 日）—— npm 上的维护者账户被接管。这个最受欢迎的 HTTP 客户端（每周下载量约 1 亿次）的两个恶意版本添加了一个幽灵依赖，其 `postinstall` 脚本部署了一个跨平台的 RAT（远程访问木马）。尽管存活了不到 3 个小时，但其爆炸半径极大。（[GHSA-fw8c-xr5c-95f9](https://github.com/advisories/GHSA-fw8c-xr5c-95f9)）
这些攻击之所以能够成功，是因为在代码运行的那一刻，没有任何东西在进行监控。
而 Sanctum 在监控。
## 它能拦截什么
### 供应链攻击
监控每一个 Python `site-packages` 目录中新增或修改的 `.pth` 文件。每一行都会被分类为良性（仅包含 `import`）、可疑（包含动态代码）或严重（包含 exec/eval/网络请求）。被判定为严重的文件会被立即隔离，并替换为空存根。
当一个 `.pth` 文件出现时，Sanctum 会追踪进程谱系以确定是*谁*创建了它。`pip install` 创建了 `.pth` 文件？这是符合预期的。如果是 Python 启动时静默写入了新的 `.pth` 文件？这就是攻击行为。
```
$ sanctum review
Quarantined items (1 total):
------------------------------------------------------------------------
ID: a1b2c3d4
Original: /usr/lib/python3/site-packages/evil-package.pth
Reason: CRITICAL: exec(open('/tmp/.payload').read())
Quarantined: 2026-03-28 14:23:01
------------------------------------------------------------------------
Actions:
sanctum review --approve — restore file to original location
sanctum review --delete — permanently remove quarantined file
```
### 垃圾包 squatting 与安装时代码执行
AI 编程助手会凭空捏造不存在的包名。Sanctum 在执行每一个 `npm install`、`pip install`、`go get`、`cargo add` 和 `brew install` 命令之前，都会根据真实的软件源进行检查。不存在的包会被拦截 —— 在运行之前就阻断拼写欺骗 和 AI 幻觉导致的包安装。
除了存在性检查之外，Sanctum 还在各个生态系统中强制执行安装时安全策略：
| 生态系统 | 保护措施 |
|-----------|-----------|
| **npm** | 拦截未使用 `--ignore-scripts` 的安装（Axios 攻击向量） |
| **pip** | 警告/拦截未使用 `--only-binary :all:` 的安装（防止 `setup.py` 被执行） |
| **Cargo** | 当在编译时下载带有 `build.rs` 的新 crate 时发出警告 |
| **Homebrew** | 验证官方 formulae/cask，对不受信任的 tap 和 Brewfile 发出警告，拦截直接通过 URL/路径安装的 formula |
| **Docker** | 对 `:latest`/无标签镜像、不受信任的镜像源以及不安全的 Dockerfile 模式发出警告 |
具备 Shell 感知能力的命令分割功能可以检测出链式命令（`cd /tmp && npm install evil`），这些命令原本可以绕过一般检测。
### 泄露给 AI 工具的凭证
使用 37 种凭证模式，对通过 AI 工具 hook 传递的所有内容进行扫描 —— 涵盖 OpenAI、Anthropic、AWS、GitHub、Stripe、Slack、GCP、Azure、Docker Hub、Vault 等。在秘密信息离开你的设备之前将其捕获，而不是等它们进了训练集才发现。
同时还会运行 Shannon 熵分析，以检测那些*看起来*像秘密信息的高熵字符串，即使它们与任何已知模式都不匹配。
```
$ echo '{"command": "cat ~/.aws/credentials"}' | sanctum hook pre-bash
{"decision":"block","reason":"Reads sensitive credential path: ~/.aws/credentials"}
```
### AI 失控消费
追踪 OpenAI、Anthropic 和 Google API 在每个提供商、每个会话以及每天的支出。设定预算阈值，在达到设定的百分比时收到警报，并限制每个提供商可以使用的模型。
```
$ sanctum budget
Provider Session Spend Session Limit Daily Spend Daily Limit
openai $8.20 $30.00 $12.40 $100.00
anthropic $4.20 $20.00 $4.20 $100.00
```
### 凭证文件访问
监控对 `~/.ssh`、`~/.aws/credentials`、`~/.kube/config` 及其他敏感路径的访问。当有异常进程触碰你的凭证时，你会第一时间收到通知。
### 网络异常
检测异常端口上的出站连接、连接到黑名单目的地、或来自异常进程的网络请求。使用可配置的基于规则的检测，以及安全的端口白名单和进程白名单。
### 数据泄露量检测
在滑动时间窗口内，追踪发送至每个目标主机的累计字节数。达到设定的阈值会触发警告（默认 5MB）或拦截（默认 20MB），并伴有桌面通知和审计日志。警报抑制功能可防止通知泛滥，10K 的主机上限则确保了内存占用可控。
## Claude Code 集成
Sanctum 为 [Claude Code](https://claude.ai/code) 提供了前置和后置工具 hook：
```
sanctum hooks install claude
```
这会安装五个 hook 处理器：
| Hook | 功能描述 |
|------|-------------|
| `pre-bash` | 阻止凭证访问、环境变量泄露、垃圾包 squatting、危险的包管理器模式以及 Docker 镜像安全检查 |
| `pre-write` | 防止写入敏感路径，检测凭证注入，进行 Dockerfile linting |
| `pre-read` | 阻止读取 SSH 密钥、云凭证、私钥 |
| `pre-mcp` | 强制执行 MCP 工具策略，审计所有调用 |
| `post-bash` | 扫描命令输出中泄露的凭证，发出 cargo build.rs 警告，提取 API 消费情况 |
恶意的仓库配置无法禁用这些保护措施 —— Sanctum 强制设定了一个安全基线，项目本地的配置无法将其降低。
## 使用方法
```
sanctum init # Set up Sanctum in your project
sanctum status # Daemon status (works offline too)
sanctum doctor # Health check your installation
sanctum scan # Scan project for credential exposure
sanctum review # Review quarantined threats
sanctum run -- # Run a command with protections active
sanctum config # View config (--edit to modify, --recommended for defaults)
sanctum audit # Threat event log (--last 24h, --level critical, --json)
sanctum fix list # Unresolved threats (--category, --level, --json)
sanctum fix resolve # Remediate a threat (--action restore|delete|dismiss)
sanctum fix all --yes # Batch-remediate all unresolved threats
sanctum budget # View current spend
sanctum budget set # Set session/daily limits
sanctum budget extend # Extend session budget
sanctum budget reset # Reset counters
sanctum hook # Hook handler (called by Claude Code, not you)
sanctum hooks install claude # Install Claude Code hooks
sanctum hooks remove claude # Remove Claude Code hooks
sanctum daemon start|stop|restart
sanctum proxy start|status # stop: terminate the proxy process manually
```
## 配置
```
# .sanctum/config.toml
[sentinel]
watch_pth = true
watch_credentials = true
watch_network = false # network anomaly detection (opt-in)
pth_response = "quarantine" # quarantine | alert | log
# [sentinel.cargo]
# allowlist = ["my-internal-crate"]
# warn_build_scripts = true # 警告新的 crate 下载 (build.rs 风险)
# [sentinel.pip]
# warn_source_installs = true # 警告 setup.py 执行风险
# require_binary_only = false # 设置为 true 可在没有 --only-binary :all: 的情况下阻止 pip
[sentinel.homebrew]
trusted_taps = ["homebrew/core", "homebrew/cask", "homebrew/services", "homebrew/bundle"]
warn_untrusted_taps = true # warn on brew tap or owner/repo/formula outside trusted_taps
warn_no_quarantine = true # warn on cask --no-quarantine
block_external_formula_installs = true
warn_brewfile = true # warn on brew bundle/Brewfile installs
[ai_firewall]
redact_credentials = true
claude_hooks = true
mcp_audit = true
check_package_existence = true # slopsquatting detection (npm, pip, go, cargo, brew)
[[ai_firewall.mcp_rules]]
tool = "filesystem_write"
restricted_paths = ["/etc/*", "/usr/*", "~/.ssh/*"]
[ai_firewall.docker]
trusted_registries = ["docker.io", "ghcr.io", "gcr.io", "public.ecr.aws", "registry.k8s.io"]
warn_latest = true # warn on :latest or untagged images
[budgets]
default_session = "$50"
default_daily = "$200"
alert_at_percent = 75
[budgets.providers.openai]
session = "$30"
daily = "$100"
allowed_models = ["gpt-5.4", "gpt-5.4-mini"]
```
### 泄露告警
```
[sentinel.network]
exfiltration_warn_bytes = 5242880 # 5MB — desktop notification
exfiltration_block_bytes = 20971520 # 20MB — block + audit event
exfiltration_window_secs = 60 # sliding window (1-3600s)
```
### CEL 策略规则
```
[[ai_firewall.mcp_cel_rules]]
expression = 'tool_name == "filesystem_write" && paths.exists(p, p.startsWith("/etc"))'
action = "deny"
[[ai_firewall.mcp_cel_rules]]
expression = 'payload_size > 1048576'
action = "warn"
```
CEL 表达式是非图灵完备的，且没有副作用。可用的上下文变量包括：`tool_name`（字符串），`paths`（字符串列表），`payload_size`（整数）。
使用 `sanctum config --recommended` 生成推荐的初始配置。
完整配置参考：请查看 `sanctum config --recommended` 以获取带有注释的默认值。
## 安装
### 从源码构建（推荐注重安全的用户使用）
```
git clone https://github.com/postrv/sanctum-oss
cd sanctum-oss
cargo build --release
# 二进制文件：target/release/sanctum, target/release/sanctum-daemon
```
需要 Rust 1.94.0+（版本已固定在 `rust-toolchain.toml` 中）。
### 脚本安装器
```
curl -fsSL https://raw.githubusercontent.com/postrv/sanctum-oss/main/scripts/install.sh | sh
```
安装器会验证 SHA-256 校验和（强制执行）以及 Sigstore 签名（如果安装了 `cosign`）。有关验证模型，请参阅 [SECURITY.md](docs/SECURITY.md)。
### 接下来
```
# 添加到你的 ~/.zshrc (或 ~/.bashrc, ~/.config/fish/config.fish)：
eval "$(sanctum init --shell zsh)"
# 安装 Claude Code hooks：
sanctum hooks install claude
```
请参阅 [入门指南](docs/GETTING_STARTED.md) 获取完整的操作演示。
## 工作原理
Sanctum 作为后台 daemon 运行，随你的 shell 一起启动。该 daemon 负责监控文件系统、监视进程，并为 CLI 和 hook 处理器提供 IPC socket 服务。
```
Claude Code Your shell
| |
[pre-bash hook] [shell hook]
| |
sanctum hook ----IPC----> sanctum-daemon
| | |
.pth watch | credential watch
|
network monitor
```
CLI 是无状态的 —— 它通过 Unix socket 与 daemon 通信。Hook 处理器非常快（仅需一次 IPC 往返），因此不会拖慢你的 AI 编程会话。
## 与 nono 组合使用
Sanctum 可以与 [nono.sh](https://nono.sh) 组合使用，以实现内核级别的沙箱隔离：
```
# nono：kernel 沙箱 + phantom 代理
# sanctum：runtime 监控 + AI 防火墙 + 预算控制
nono run --profile claude-code -- claude
```
Sanctum **并不**强制依赖 nono。这两个工具各自都能提供独立的价值。
## 架构
包含 8 个 crate，约 51,000 行 Rust 代码，6 个生态系统集成（npm、pip、Go、Cargo、Homebrew、Docker）：
| Crate | 用途 |
|-------|---------|
| `sanctum-cli` | CLI 接口 —— 通过 clap 提供 14 个命令 |
| `sanctum-daemon` | 后台 daemon，IPC 服务器（14 个命令），事件循环 |
| `sanctum-sentinel` | `.pth` 监控，隔离，凭证监控，网络异常检测 |
| `sanctum-firewall` | 凭证脱敏（37 种模式），Shannon 熵，MCP 策略引擎，垃圾包 squatting 检测（5 个软件源），包管理器安全检查 |
| `sanctum-budget` | 消费追踪，3 个提供商的解析器（OpenAI、Anthropic、Google） |
| `sanctum-proxy` | 带有 body 限制、凭证脱敏、预算强制执行、SSRF 防护和使用量提取的 HTTP 预算代理 |
| `sanctum-types` | 共享类型，配置 schema，威胁模型，平台路径 |
| `sanctum-notify` | 跨平台桌面通知（macOS + Linux） |
## 安全态势
Sanctum 是一款安全工具。它对自己设定的标准高于它所保护的代码。
**编译时保证**（由 workspace lints 强制执行 —— 不是约定，而是*编译器错误*）：
- 零 `unsafe` 代码
- 在测试之外没有 `unwrap()`、`expect()` 或 `panic!()`
- 没有 `print!()` / `println!()` / `eprint!()` —— 所有输出都通过结构化通道处理
**测试**：
- 2,000+ 个测试（单元测试、集成测试、端到端测试、loom 并发测试）
- 9 个 Kani 有限模型检验证明（确保无 panic、状态机正确性、溢出安全性）
- 针对安全关键解析器的 2 个模糊测试目标（CI 在 PR 时每个目标运行 30 秒，每晚运行 2.5 小时）
- 9 个基于属性的测试，在随机输入下验证核心不变量
- 0 个 clippy 警告（启用了 pedantic + nursery lints）
**供应链**：
- 所有依赖项均经过审计并锁定版本（Cargo.lock 中有 344 个 crate）
- `cargo-deny` 在 CI 中强制执行许可证策略和咨询数据库检查
- 使用 Sigstore 签名的发布二进制文件，附带 SBOM 和 Rekor 透明度日志
- 在 CI 中验证可复现构建（构建两次，比对 SHA-256）
**文档**：
- [SECURITY.md](docs/SECURITY.md) —— 漏洞报告和安全保证
- [THREAT_MODEL.md](docs/THREAT_MODEL.md) —— Sanctum 能够和不能够防御的威胁
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) —— 设计决策及其安全考量
- [DEPENDENCY_AUDIT.md](docs/DEPENDENCY_AUDIT.md) —— 每一个依赖项的合理性说明
## 贡献
Sanctum 是采用 MIT 许可证的开源项目。欢迎提交贡献。
在提交 PR 之前，请确保：
```
cargo fmt --all -- --check
cargo clippy --all-targets --all-features # must be 0 warnings
cargo test --all --all-features # must pass
```
workspace lint 配置之所以严格是有意为之。如果 clippy 报错了，请修复代码 —— 不要抑制 lint。
## 许可证
MIT —— 请参阅 [LICENSE](LICENSE)。
标签：AI安全, AI编码, API接口, AWS凭据保护, Chat Copilot, CI/CD安全, DevSecOps, DNS 反向解析, Llama, LLM支出追踪, Node.js安全, npm安全, .pth文件监控, PyPI安全, RAT防护, SSH密钥保护, 上游代理, 供应链攻击, 凭据防火墙, 动态代码检测, 可视化界面, 合规监控, 后台监控, 后门检测, 安全守护进程, 安全隔离, 密钥泄露防护, 开发者安全, 机器学习安全, 白名单, 终端安全, 结构化查询, 网络信息收集, 网络安全审计, 自动化安全, 运行时完整性监控, 通知系统, 零信任安全