home-beekeeper/beekeeper

# Beekeeper **面向自主编程智能体的威胁情报。** Beekeeper 位于智能体及其工具之间。它在每次执行前，会根据基于印证的威胁情报和结构化策略，对每个包安装、文件访问、网络调用和工具调用进行评估，并拦截未通过检查的操作。它是一个单一的静态 Go 二进制文件，没有外部运行时依赖。 威胁来自供应链，而不是模型。你的智能体会因为任务需要而安装某个依赖项，却无法知道该版本在其训练截止日期之后发布了凭证窃取程序。Beekeeper 携带了模型所缺乏的最新且经过印证的知识，并在安装运行前进行检查。它涵盖了哪些内容以及覆盖范围的终点在哪里，请参阅[工具支持](#harness-support)和[已知缺口](#known-gaps)。在信任它处理任何事务之前，请先阅读这些内容。 ## 为什么需要 编程智能体对哪些包是安全的认知冻结在其训练截止日期。它因为任务需要而安装 `some-build-tool@1.4.2`，却无法知道该版本在截止日期之后发布了用于窃取凭证的 postinstall 脚本，也没有将常规依赖项视为风险的直觉。2026 年的供应链攻击浪潮（Nx Console、Shai-Hulud、npm 受信任发布者 OIDC 攻击）正是瞄准了这个缺口：通过受信任且善意的安装操作，将恶意代码传递给开发者。Beekeeper 在安装操作前设置了一项经过印证的威胁检查，该检查每两小时同步一次，具备第二来源要求并留有审计追踪。 ## 安装说明 ``` go install github.com/home-beekeeper/beekeeper/cmd/beekeeper@latest # 同步威胁目录 beekeeper catalogs sync # 为你的 agent 安装 hook（以 Claude Code 为例） beekeeper hooks install --target claude-code ``` 手动检查工具调用（stdin 为工具调用 JSON）： ``` echo '{"tool_name":"Bash","tool_input":{"command":"cat ~/.ssh/id_rsa"}}' \ | beekeeper check --hook claude-code # exit 2 + 一个 Claude Code deny payload：读取操作在运行前被阻止 ``` 发布版本以可复现方式构建，经 Sigstore 签名（通过 GitHub Actions OIDC 进行无密钥签名），并提供 SLSA Level 3 来源证明和 CycloneDX SBOM。验证命令请见[安装页面](https://github.com/home-beekeeper/beekeeper/blob/main/docs)。 ## 它的功能 Beekeeper 分为三层。每一层都有不同的职责，且它们的防护强度各不相同。 ### 1. Hook 和网关强制执行（负责拦截的层） PreToolUse hook 会在每次工具调用前运行 `beekeeper check --hook `。如果触发拦截，它将以代码 `2` 退出，并发出相应 harness 实际认可的专有拒绝负载（Claude Code 使用 `hookSpecificOutput`，Hermes 使用 `{"action":"block"}`）。退出代码 `2` 是经过深思熟虑的：退出代码 `1` 会被视为 hook 错误，而大多数 harness 会忽略它，导致工具依然会运行。 对于没有预执行 hook 的 harness，MCP 网关会通过本地代理拦截传输中的 MCP 工具调用。 敏感路径强制执行机制会拦截智能体读取，以及通过 shell 重定向写入工作目录之外的凭证路径（`~/.ssh`、`~/.aws`、`~/.cargo/credentials`、`.env` 通配符、编辑器 MCP 配置目录），并通过规范化路径来封堵针对波浪号、`$VAR`、符号链接、Windows 备用数据流和末尾点号的规避行为。该拦截机制采用“最严格优先”策略合并，因此白名单无法降级针对凭证读取的拦截。 此处的所有机制均默认为“故障封闭”（fail-closed，即安全失效）：崩溃、超时、超大输入或缺失索引都会导致拦截，而不是放行。`fail_mode: open` 是显式启用的选项，可由项目级配置进行设置，因此默认行为是“故障封闭”，但可以针对每个工作树关闭此行为。 ### 2. 目录印证（供应链层） 拦截决策需要第二验证因素： | 标记包的来源数量 | 操作 | |----------------------------|--------| | 1 | 警告 (warn) | | 2 | 拦截 (block) | | 3+ | 拦截 + 隔离 | 只有经过签名的来源才会计入拦截条件；未签名的来源只能发出警告，绝不能单独触发拦截。控制了单一目录来源的攻击者可以引发警告，但无法强制实施拦截。来源包括 Bumblebee、OSV 和 Socket。基于严重程度的阈值允许 `critical`（严重）级别的匹配在更低计数下即触发升级，并防范单一被投毒或通配符的条目。 包管理器引导机制会在 `npm`、`pnpm`、`bun` 和 `yarn` 安装运行前匹配目录情报，包括链式命令（`cd x && npm install ...`）和带环境变量前缀的命令。未列出的管理器（`deno`、`mvn`、`nuget`）目前会被解析为“未识别出包”并予以放行；行为层将作为该场景下的第二信号。 在目录同步产生增量时，只读的交叉引用机制会根据最新情报检查已安装的包。经过印证的命中结果可被转移至可逆隔离区（通过目录移动结合还原清单实现）。此功能为可选，且默认以试运行方式进行：全新安装不会隔离任何内容，永久清除操作始终需由人工把关。 对于已确认的安全事件，Beekeeper 还会将该包记录到本地、仅限追加、仅限所有者访问的已裁决语料库中（v1.4.0）。在非关键路径下（仅在执行 `catalogs sync` 期间），裁决引擎会分配结果，并将已确认的恶意包写入本地目录覆盖层，以便所在机器在上游提要更新之前立即对其强制执行拦截。仅限本地：不会有任何数据离开本机（参见 [docs/THREAT-MODEL.md §13](https://github.com/home-beekeeper/beekeeper/blob/main/docs/THREAT-MODEL.md））。 ### 3. Sentry 行为关联（仅用于检测，需手动启用） 一个需提权的可选监视器（`beekeeper protect install`）会将进程、文件和网络事件关联到 `SENTRY-001` 到 `SENTRY-008` 规则中：凭证文件集群、凭证 CLI 爆发、首次出站回连、新扩展关联、泄露签名融合、智能体 CLI 凭证集群、通用泄露融合以及持久化位置写入。 这些规则适用于源自编辑器（`code/cursor/windsurf/codium`）或已知智能体 CLI（`claude/codex/cursor-agent/gemini/copilot/qwen/aider/opencode/hermes`）的进程，因此独立终端智能体也在监控范围内，而不仅限于编辑器扩展。文件写入事件在 Linux、macOS 和 Windows 上被采集；DNS 查询事件在 Linux 和 Windows 上被采集。 Sentry 仅用于检测：它仅写入审计记录，不会进行隔离或终止进程。目录命中结果可以加强对被标记产物进程子树的关联监控，但依然仅限于检测目的。 ## 工具支持 支持 17 种智能体 harness，分为三个层级。包含配置位置和注意事项的完整表格请见：[docs/harness-support-matrix.md](https://github.com/home-beekeeper/beekeeper/blob/main/docs/harness-support-matrix.md)。 | 层级 | Harnesses | 覆盖范围 | |------|-----------|----------| | 1: 完整 hook 拦截 | Claude Code, Codex, Cursor, Augment, CodeBuddy, Qwen Code, Gemini CLI, Copilot, Antigravity, Windsurf | 预执行 hook：退出码 2 + 对应 harness 的拒绝负载 | | 2: hook 拦截，存在注意事项 | Hermes, Cline, OpenCode | Hermes 为故障开放；Cline 仅限 macOS/Linux；OpenCode 会漏掉子智能体的 `task` 调用 | | 3: 仅限 MCP 网关 | Kilo, Trae, Continue, OpenClaw | 拦截 MCP 工具；原生 Bash 和文件工具处于未受保护状态 (UNGUARDED) | **验证范围。** 只有 Claude Code 进行了端到端的实时拦截验证（凭证读取触发了 hook，工具未运行，拦截被记录在案）。其他 16 种 harness 是根据其文档化的契约进行实现并进行了契约形态测试（正确的退出码和拒绝负载），但并未在 CI 中针对真实的 harness 运行。每种 harness 的实时拦截流程及签字确认字段详见 [docs/validation-register.md](https://github.com/home-beekeeper/beekeeper/blob/main/docs/validation-register.md)。 ## 已知缺口 在此记录是为了避免你产生错误的信心。这些问题都没有放宽“故障封闭”的执行路径；大多数属于检测覆盖率或配置信任方面的限制。 - **仅 Claude Code 经过实时验证。** 其他 16 种仅经过契约测试，未针对真实的 harness 运行。 - **第 3 层的原生工具未受保护。** Kilo 和 Trae 没有上游 hook；只有 MCP 工具通过网关路由。原生的 Bash、文件和 shell 工具会绕过 Beekeeper。 - **Hermes 为故障开放**，而 Windsurf 在遇到任何非 2 的退出码时均为故障开放。OpenCode 会漏掉子智能体的 `task` 调用。 - **项目配置可以放宽故障封闭状态。** 包含 `{"fail_mode":"open"}` 的 `.beekeeper/config.json` 配置对该工作树有效。 - **网关远程绑定是明文的。** `--bind 0.0.0.0` 会通过纯 HTTP 暴露代理，且 bearer token 为明文；`allow_remote_gateway` 限制开关尚未实现。请将其保持在回环地址上。 - **未列出的包管理器。** `deno`、`mvn` 和 `nuget` 会被解析为“未识别出包”并默认放行。命令链式和带环境变量前缀的安装已得到处理。 - **DNS 会被采集但未进行关联**，因此 DNS 隧道数据泄露会被捕获但尚未被检测到。目前没有进程内存事件源，因此针对 `/proc//maps` 的凭证抓取行为无法被检测。 - **`release_age` 和 `lifecycle_script_allowlist` 策略规则会被接受但不予强制执行**（仅供参考）。 - **事件响应隔离区和 Sentry 升级功能已接入并通过 CI 验证，但尚未经过专门构建的实时漏洞利用的红队测试。** 结构已被证明有效；实时终止操作尚未得到验证。 - **残留问题，主机无法检测：** 通过合法端点进行的泄露（GitHub API 死信箱、AWS 服务 C2、npm registry 传播）。仅能通过架构层面进行缓解。 ## 它是如何被验证的 覆盖率是可审计的，而非凭空断言。验证工作分为三个方面： - **A 类（本地可测试）：** 通过测试门槛保持全面覆盖率，该门槛将每个生产环境的 Go 文件计为已测试，或归类为带有原因代码的故障封闭白名单条目。包含 17 种 harness 的合规性测试套件对所有安装程序配置和拒绝契约进行了 golden-file 测试。 - **B 类（平台绑定）：** 跨越两个 Linux 内核、macOS 和 Windows 的 CI 矩阵，测试了 eBPF、eslogger、ETW 和 Unix peer-cred。包含 Sentry 规则评估器在内的五个模糊测试目标作为发布阻塞关卡运行。 - **C 类（不可避免的手动测试）：** 带有签名确认的注册表，包含实时拦截流程，以及针对 16 种非 Claude Code harness 和受控模型 sidecar 的各自签字确认行。 详细信息：[docs/validation-posture.md](https://github.com/home-beekeeper/beekeeper/blob/main/docs/validation-posture.md)。 ## 架构 - 单一静态二进制文件。`cmd/beekeeper/main.go` 只是简单的 Cobra 装配逻辑；所有业务逻辑均位于 `internal/` 中。 - `internal/policy` 是一个无 I/O 操作的纯函数库，由 hook 处理程序、网关和 Sentry 关联层进行完全一致的调用。 - 在所有执行路径上默认采用故障封闭机制。 - hook 处理程序通过 mmap 加载目录，避免每次调用产生冷加载。 - `internal/corpus` 是一个本地已裁决语料库循环：仅限追加、仅限所有者、优先进行脱敏处理，不进行网络导入（由测试强制执行），并且裁决过程在非关键路径上运行。仅限本地：不会有任何数据离开本机。 Beekeeper 还具有自我保护机制：智能体无法读取或写入其状态目录、覆盖其二进制文件、删除自身的 hook 条目，也无法通过 Bash 调用 Beekeeper 的修改性子命令。采用独立密钥的 `beekeeper-self` 提要可确保被篡改的构建版本拒绝运行。 ## 安全 漏洞披露策略：[SECURITY.md](https://github.com/home-beekeeper/beekeeper/blob/main/SECURITY.md)。威胁模型：[docs/THREAT-MODEL.md](https://github.com/home-beekeeper/beekeeper/blob/main/docs/THREAT-MODEL.md)。 ## 许可证 Apache 2.0。威胁情报的灵感来源于 Perplexity 的 [Bumblebee](https://github.com/perplexityai/bumblebee)（Apache-2.0），作为目录来源被使用，并以 [Pollen](https://github.com/home-beekeeper/pollen) 作为 Windows 支持扫描器的后备方案。Beekeeper 不包含任何 Bumblebee 或 Pollen 的代码；两者均作为子进程被调用。

标签：AI代理安全, Docker镜像, EVTX分析, Go, Lerna, Ruby工具, StruQ, 威胁情报, 开发者工具, 日志审计, 策略执行, 网络信息收集