cerberus

# 凯瑟伯斯 🐺 [](https://www.npmjs.com/package/@cerberussec/core) [](./LICENSE) [](https://nodejs.org)  一个**本地优先的安全网关，用于自主AI编码代理**。凯瑟伯斯位于代理（如Claude Code、Codex、Cursor、Cline）和您的机器之间，拦截**每个工具调用**，在运行前进行风险评估，并根据评估结果**允许、审计、请求人工审批或阻止** - 所有操作都在您的机器上进行，**无需外部API调用，数据不会离开机器**。 ## 问题 自主编码代理代表您运行shell命令、编辑文件并进行网络调用 - 以机器速度，通常无人监督。一步走错（`rm -rf`、意外的`git push`、泄露的`.env`、中毒的README诱导代理窃取秘密），没有人工干预就无法阻止。凯瑟伯斯在**工具边界**设置了检查点，即代理实际行动的地方。 ## 功能 ``` 工具使用前 ─▶ 拦截 ─▶ 策略 + 行为 + 内容 + 注入 ─▶ 风险引擎 ─▶ 允许 · 审计 · 人工审批 · 阻止 工具使用后 ─▶ 检查 ─▶ 秘密 + 注入检测 ─▶ 会话污染状态 ``` 四个确定性信号聚合为一个加权风险评分，具有绝对禁止不能覆盖的硬下限。 ## 保护内容 - **🟢 秘密外泄** - 检测加载到上下文中的秘密，然后**内容匹配出站有效载荷**：阻止实际携带密钥的调用（原始或base64/hex/url编码），具有来源（`source: .env:4 · sha256:… · 97%`）并且从不记录秘密本身。 - **🟢 过度权限** - 每个调用都受到限制；未知工具失败关闭；敏感路径（`~/.ssh`、`~/.aws`、凭证、`/etc/passwd`）被阻止；破坏性命令（`rm -rf`、`Remove-Item -Recurse`、`chmod 777`、`kill -9`）被阻止或阻止。 - **🟢 危险出口** - 目的地策略：受信任的主机（注册表、GitHub、OpenAI/Anthropic）自动允许；粘贴网站/ webhook捕捉器/原始IP目的地被阻止。 - **🟡 工具滥用** - 无限循环和工具调用速率/重复检测。 - **🟡 提示注入** - 在工具**结果**中检测注入并限制下一个出口（启发式分类器；可选的本地DeBERTa模型）。它看到工具调用，**而不是LLM提示** - 因此它捕获注入的**利用**（出口），而不是注入本身。 ## 主要功能 - **终端优先审批** - 阻止的调用在代理的原生权限提示（Claude Code / Cursor）中显示，或通过`cerberus approve <id>` / 本地主机仪表盘。 - **法医仪表盘** - 每个会话的时间线，风险因素分解和**重放**播放器，逐步显示会话风险的累积过程。 - **多代理** - 一个适配器层为Claude Code、Codex、Cursor和Cline提供服务。 - **策略即数据** - 规则和风险权重是可编辑的YAML，而不是代码。 - **本地优先** - 绑定到`127.0.0.1`，无需外部API调用，无需遥测；秘密**值**从不触及磁盘或日志。 ## 快速入门 ```bash npm i -g @cerberussec/core # 或使用以下命令临时运行：npx @cerberussec/core <cmd> # 将凯瑟伯斯集成到您的代理中（合并到代理的配置中 - 备份，幂等）： cerberus init # Claude Code，项目级 (--agent codex|cursor|cline, --global, --print) # 启动网关 + 仪表盘（一个进程）： cerberus engine # 然后打开 http://127.0.0.1:9000/ ``` 像平常一样使用您的代理 - 工具调用现在通过凯瑟伯斯路由。默认情况下，阻止的调用在**终端中直接获得批准**：凯瑟伯斯返回`ask`，因此Claude Code显示其原生权限提示，并附带凯瑟伯斯的理由 - 在不离开会话的情况下批准/拒绝。 仪表盘（`http://127.0.0.1:9000/`）具有**实时**选项卡（操作中心 + 流）和**会话**选项卡 - 每个会话的法医时间线，风险因素分解和**重放**播放器，逐步显示会话风险的累积过程。 ## 终端优先审批 凯瑟伯斯在代理的执行循环中运行，因此终端是实时决策点，仪表盘是深入调查的工具。根据严重程度（默认`AG_APPROVAL_SURFACE=terminal`）： | 裁决 | 终端 | 网络UI | |---|---|---| | **阻止** | ⛔ 终端中拒绝（Claude显示原因）+ 可选自动打开 | 法医记录 | | **人工审批** | ✋ **Claude的原生权限提示**，附带凯瑟伯斯的理由 | 法医记录 | | **审计** | — （静默） | 提升风险记录 | | **允许** | — （静默） | — | 更喜欢一个集中的网络队列吗？设置 **`AG_APPROVAL_SURFACE=dashboard`** - 阻止的调用暂停在引擎的同步阻止上，您从仪表盘（或终端，带外）批准/拒绝： ```bash cerberus pending # 列出待审阅的调用（及其ID） cerberus approve <id> # 释放阻止的调用… cerberus deny <id> # … 或拒绝它 ``` 额外的终端警报写入控制终端（`/dev/tty`，回退到stderr），因此与Claude Code的协议通道保持干净。可以通过环境变量调整： | 环境变量 | 默认值 | 效果 | |---|---|---| | `AG_NOTIFY` | `1` | 额外的终端警报行开启/关闭（`0`表示静默） | | `AG_APPROVAL_SURFACE` | `terminal` | `terminal` ⇒ 通过Claude的原生提示进行人工审批；`dashboard` ⇒ 套接字阻止 + 仪表盘批准 | | `AG_AUTO_OPEN` | `off` | `block` ⇒ 在BLOCK/EXFIL上自动打开调查UI | ## 代理 引擎 + 信号 + 风险 + 仪表盘是代理无关的；只有薄的**适配器**（解析代理的钩子事件 → 规范化 → 发出其裁决形状）是每个代理特有的。使用`cerberus init --agent <name>`连接一个： | 代理 | `--agent` | 人工审批 | 备注 | |---|---|---|---| | **Claude Code** | `claude`（默认） | 原生终端提示（`ask`） | 验证端到端 | | **Codex CLI** | `codex` | 仪表盘阻止（无原生询问） - `AG_APPROVAL_SURFACE=dashboard` | 企业`requirements.toml`使其不可绕过 | | **Cursor** | `cursor` | 原生IDE提示（`ask`） | 初始化设置`failClosed: true` | | **Cline** | `cline` | 仪表盘阻止（`cancel`布尔值） | macOS/Linux仅 | `codex`/`cursor`/`cline`适配器遵循已发布的钩子规格；请与您安装的版本进行验证（`cerberus init --agent <name> --print`显示确切的配置）。Roo Code不受支持（存档于2026年）。 ## 如何连接 - **PreToolUse钩子 → `/intercept`** 是单一的硬强制执行点（允许/拒绝/询问；或人工审批保持套接字打开直到您决定）。 - **PostToolUse钩子 → `/inspect`** 是仅观察：它更新会话的污染状态，以便**下一个**操作在具有完整上下文的情况下进行判断。它从不修改工具结果。 - 引擎在核心是**代理无关的**；每个代理的适配器（ `--agent`）是唯一不同的部分。 ## 架构 ``` PreToolUse ─▶ /intercept ─▶ 策略 + 行为 + 内容/注入 ─▶ 风险引擎 ─▶ 允许/审计/人工审批/阻止 PostToolUse ─▶ /inspect ─▶ 秘密检测 + 注入分类器 ─▶ 会话污染状态 （审计日志 + WebSocket → 仪表盘） ``` 单个Node + TypeScript包；仪表盘是引擎提供的Vite/React应用。规则和风险权重是可编辑的**YAML数据**，而不是代码（`rules/`）。 ## 它是什么 - 以及不是 凯瑟伯斯是一个**工具边界上的运行时网关**。它在秘密外泄预防和权限检查点方面最强。由于它看到的是工具调用（而不是LLM提示），因此它捕获了提示注入的**利用** - 而不是注入本身 - 并且它**不**涵盖数据管道/RAG中毒。外泄匹配是高置信度的，但不是万无一失的（新颖的秘密格式，跨调用编码）。诚实的默认值优于虚假的保证。 ## 本地优先和许可 无需外部API调用，无需API密钥，机器上没有任何数据离开。 可选的注入模型（[`@cerberussec/injection-model`](packages/injection-model)，ProtectAI DeBERTa，Apache-2.0）升级内置的启发式分类器；仅当您需要时安装它。核心是OSS-clean（Apache/MIT兼容依赖项）；Meta Prompt-Guard被故意排除在核心之外（Llama许可证）。 ## 开发 ```bash # 从克隆：安装（根和仪表盘是单独的npm项目）并构建 npm install && npm --prefix dashboard install npm run build # 编译引擎（tsc → dist）+ 仪表盘（vite → dashboard/dist） npm run engine # 通过tsx（dev）从源代码运行 npm run typecheck npm run test:behavioral && npm run test:content && npm run test:injection && npm run test:risk \ && npm run test:init && npm run test:projector && npm run test:audit && npm run test:notify \ && npm run test:security && npm run test:policy && npm run test:adapters npm run e2e:behavioral && npm run e2e:content && npm run e2e:injection && npm run e2e:risk ``` 参见 `PLAN.md`了解里程碑和 `brainstorms/` 了解每个决策背后的设计记录。