team-hlab/keel

# keel **只需编写一次您的 agent 安全策略，即可在任何 agent 上运行。** `keel` 是一个精简的、单二进制 hook 框架，专为第一方 AI 编程 agent 设计 —— **Claude Code**、**OpenAI Codex** 和 **Google Antigravity**。每一次工具调用都会通过 keel，它会**自动允许**安全的操作，**自动拒绝**灾难性的操作，并在遇到模棱两可的情况时**询问**您。 - **单一静态二进制文件** — Rust 编写，约 1 MB，**零运行时依赖**。 - **Busybox 风格** — 一个二进制文件，两种模式：透明 shim 和 `keel` CLI。 - **透明安装** — `brew install keel && keel init` 会将 keel 的 hook 注入到检测到的每一个 agent 中；您可以像以前一样继续运行 `claude`。 - **故障开放** — bug 或缺失的组件绝不会阻塞 agent。 - **可扩展** — 各项功能都是基于单一 trait 编译进来的小型 applet。 ## 工作原理 1. **Shim (PATH 劫持 + busybox)。** `keel init` 会将 `~/.keel/bin/{claude,codex,agy}` 符号链接到 keel 二进制文件（Antigravity 的 CLI 为 `agy`），使其排在 PATH 中真实 CLI 的前面。运行 `claude` 实际上运行的是 keel（通过 `argv[0]`），它会重新应用最新的 hook（幂等，通过 `__keel` 标记实现非破坏性），然后 `exec` 真实的 `claude` —— 相同的 PID，在 `ps` 中不可见。 2. **Hook 处理程序。** 在工具使用时，应用的 hook 会调用 `keel run claude PreToolUse`；策略引擎会返回 allow / deny / ask（或进行推迟）。 请参阅 **[docs/keel-architecture.html](docs/keel-architecture.html)** 了解全貌。 ## 安装 ``` brew tap team-hlab/keel brew install keel keel init # attach to your installed agents brew upgrade keel # update later ``` ## 状态 keel 使用 Rust 编写，其行为由 Rust 测试套件（单元测试 + 集成测试 + 针对真实 agent CLI 的 Docker 化 e2e 测试）覆盖。它最初是一个经过验证的 Python 实现，在移植过程中作为规范/基准；该覆盖率后来已被移植到 Rust，Python 版本也已退役。 - ✅ **Hook 引擎** — `keel run `、`autopermit` 功能（文件**和**完整的 shell 解析）以及 Claude/Codex/Antigravity 适配器。 - ✅ **透明 shim** — `keel init` / `apply` / `uninstall` / `doctor`：PATH 劫持符号链接、非破坏性 `__keel` 标记、`exec` 真实的 agent。 - ✅ **全部五大功能** — autopermit、branch-guard、secret-scan、audit-log（可选开启）、session-banner。**53 个 Rust 测试**（单元测试 + 集成测试，包括边缘情况和容错测试）**外加一个 Docker 化的 e2e 测试**，该测试会安装真实的 Claude/Codex/`agy` CLI 并执行完整的生命周期；clippy/fmt 无报错。 ## 功能 | 功能 | 阶段 | 作用 | |---|---|---| | **autopermit** | PreToolUse, PermissionRequest | 允许非机密读取 + worktree 写入 + 安全的 shell；对机密信息进行 `ask`；拒绝 worktree 外的写入及灾难性命令 | | **branch-guard** | PreToolUse | 拒绝在受保护分支上进行修改 git 的操作 | | **secret-scan** | PreToolUse | 当写入的内容看起来像凭证时进行询问 | | **audit-log** | PreToolUse | 将每次调用追加到 JSONL 中（可选开启 — 因为它会写入文件） | | **session-banner** | SessionStart | 宣布启用的功能 | 判决结果按**最严格优先**原则聚合：`deny > ask > pass > allow`。可通过 `.keel.json` 进行调整 — 参见 **[docs/CONFIG.md](docs/CONFIG.md)**。 ## 开发 ``` cargo test # unit + integration tests cargo clippy --all-targets -- -D warnings cargo fmt --check cargo build --release # → target/release/keel (~1 MB) ``` 如需在容器中针对真实的 agent CLI 运行完整生命周期，请参阅 **[docker/README.md](docker/README.md)**。 CI 会运行 fmt + clippy + test + release 构建，外加一个 **Docker 化的 e2e 测试**，该测试会安装真实的 Claude/Codex/Antigravity (`agy`) CLI，并在每次 push 和 PR 时运行 keel 完整的 安装 → 附加 → 判决 → shim → 卸载 生命周期。版本发布由合并触发（更新 `Cargo.toml`）— 参见 [docs/RELEASING.md](docs/RELEASING.md)。 ## 许可证 MIT © team-hlab

标签：AI编程助手, Rust, SOC Prime, 可视化界面, 安全策略, 开发工具, 提示词设计, 网络流量审计, 请求拦截, 通知系统, 钩子机制