sharma-open-source/CapWarden
GitHub: sharma-open-source/CapWarden
CapWarden 是一个 Node.js 依赖能力守护工具，通过观察依赖运行时行为生成策略基线，并在 CI 中拦截超出基线的权限访问。
Stars: 0 | Forks: 0
# CapWarden
[](https://github.com/sharma-open-source/CapWarden/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/capwarden)
[](https://nodejs.org)
[](LICENSE)
[](https://www.typescriptlang.org)
**针对 Node.js / npm 的逐依赖能力守护工具。**
Node 项目中的每个依赖都拥有与该进程相同的完整权限。依赖树深层的一个日期格式化工具可以读取 `process.env`（API key、数据库 URL）、打开网络 socket、写入文件并生成子进程——runtime 不会区分你的代码与陌生人编写的代码。CapWarden 会监控每个依赖的实际行为，将其冻结为经过审查的基线，如果依赖后续尝试使用其从未用过的能力，它将使你的 CI 构建失败。
## 工作原理
1. **观察**你的应用或测试套件。CapWarden 会拦截对 `env`、`net`、`fs` 和 `proc` 的访问，将每次访问归因于相应的 package，并编写建议的策略。
2. **审查并提交** `capwarden-policy.json` —— 这是一个小而可读的基线，明确了哪个 package 可以使用哪种能力类型。
3. **强制执行**于 CI 中。任何超出已提交策略的访问都会被拦截并以非零状态码退出，因此引入该变更的 diff 将无法通过审查。
## 快速开始
```
npm install --save-dev capwarden
# 1. 记录你的依赖项做了什么（不拦截任何内容）
npx capwarden observe -- npm test
# 2. 审查 capwarden-policy.json，然后提交它
git add capwarden-policy.json && git commit -m "Add CapWarden baseline"
# 3. 强制执行它 — 在 CI 中，或在本地
npx capwarden enforce -- npm test
```
当依赖后续执行了新操作时：
```
⛔ CAPWARDEN BLOCKED
package : leaky-util
tried : net:evil.example.com:443
policy : grants [env]
→ this capability was never part of leaky-util's frozen behavior.
```
若要接受有意的变更，请重新生成并审查 diff：
```
npx capwarden update --write -- npm test # rewrites the policy; you commit it
```
## 命令
| 命令 | 用途 |
|---|---|
| `capwarden observe -- ` | 在观察模式下运行 ``；输出报告并生成建议的策略。 |
| `capwarden enforce -- ` | 在已提交的策略下运行 ``；出现任何偏离都以非零状态码退出。 |
| `capwarden update --write -- ` | 重新观察，显示策略 diff，并重写策略。永远不会自动提交。 |
| `capwarden report` | 以人类可读的形式打印上一次的观察报告（使用 `--json` 获取原始数据）。 |
| `capwarden inventory [--diff\|--write]` | 列出/比较声明了生命周期 install script 的 package。 |
| `capwarden scripts [--enforce] [--run]` | 根据策略管理生命周期 install script；可选择在观察下运行允许的脚本。 |
| `capwarden coverage [--json]` | 列出 CapWarden 无法完全插桩的 package（如 native addon、ESM-only）。 |
| `capwarden migrate [--out ]` | 将已提交的 v1 策略转换为 v2（支持严格能力的）schema。 |
所有模式也可以在不使用 runner 的情况下通过 preload 激活：
`CAPWARDEN=observe node --require capwarden/register app.js`。
## 配置
项目根目录中可选的 `capwarden.config.json`：
```
{
"onViolation": "block",
"onInternalError": "fail-open",
"ignored": ["some-trusted-internal-pkg"],
"denied": { "*": ["proc"], "analytics-sdk": ["net"] }
}
```
- **`onViolation`** —— `block`（默认值；作为 CI 门禁）或 `log`（仅警告）。用于管控*策略违规*。
- **`onInternalError`** —— `fail-open`（默认值）或 `fail-closed`。用于管控 CapWarden 自身的 bug：fail-open 意味着守护工具的 bug 永远不会搞垮你的应用（NFR-4）。与 `onViolation` 不同。
- **`ignored`** —— 无条件允许的 package（请谨慎使用）。
- **`denied`** —— 手动预设的拒绝覆盖：即使基线授予了权限，package 也不得使用的某些能力类型。`"*"` 适用于所有 package。
## GitHub Action 示例
```
# .github/workflows/capwarden.yml
name: CapWarden
on: [pull_request]
jobs:
guard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm ci
- run: npx capwarden enforce -- npm test
```
## 能力覆盖范围
子细节（host、path、env key）会记录在报告中。支持两种策略 schema，并在加载时自动检测：
- **v1**（默认）—— 类型级别：一个 package 可能被允许或禁止使用 `net`。
- **v2** —— 严格的子细节锁定：一个 package 只能访问 `net:api.stripe.com:443`，除此之外什么也不能访问。可通过 `capwarden observe --schema v2 --strict -- ` 生成，或者使用 `capwarden migrate` 迁移现有的 v1 基线（行为保持不变：所有授权都会变成通配符，直到你对其进行收紧）。v2 的 package 以 `name@version` 作为键，并可携带 `resolvedVia` 溯源信息。
## Monorepo
## 隐私
CapWarden 仅记录能力**元数据** —— env key、hostname 和 file path —— 绝不会记录 env 的值或 file 的内容（NFR-5）。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
标签：GNU通用公共许可证, MITM代理, Node.js, 依赖管理, 安全防护, 暗色界面, 权限控制, 自动化攻击