bitdeep/agent-safe-guard

# agent-safe-guard [](https://github.com/regen-dev/agent-safe-guard/actions/workflows/ci.yml) [](LICENSE) Linux 上 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 的原生安全钩子。 `agent-safe-guard` 位于 Claude Code 及其工具调用之间。它能拦截破坏性命令、精简冗余输出、保护大型文件读取、强制执行子代理预算、记录审计事件，并提供原生的规则/包控制台。 ## 为什么需要它 AI 编码代理会代表你执行 shell 命令、读取文件并做出权限决策。如果没有防护措施，一次产生幻觉的 `rm -rf /` 或泄露的 `.env` 读取都可能造成真正的破坏。`agent-safe-guard` 增加了一个默认拒绝（fail-closed）的执行层，会在每次工具调用触达你的系统之前运行。 ## 当前版本 - 优先支持 Linux，仅原生运行时（C++20 守护进程 + 钩子客户端） - 目前支持源码安装 - 计划支持 `.deb` 和 AppImage - Windows 和 macOS 的支持正在路线图中，排在传输层抽象之后 ## 功能特性 - 拦截破坏性的 shell 模式（`rm -rf /`、fork 炸弹、`curl | bash`、强制推送到受保护分支） - 对于可能会淹没上下文的命令，要求使用静默标志 - 拒绝对捆绑、生成、二进制或超大文件目标的 `Read` 操作 - 将大型 `Read` 输出压缩为结构化摘要 - 自动决策安全与不安全的权限请求 - 在读取文件时掩盖密码和凭证 - **在 SessionStart 注入基于排序的 tree-sitter 仓库映射，让 Claude 停止在每次会话中重复读取文件**（新增 — 见下方 [Repo Map](#repo-map-primer)） - 跟踪会话指标、规则匹配、工具延迟、压缩和子代理使用情况 - 支持从远程目录（应用市场）安装扩展包 - 允许你使用 `asg-cli` 在包和规则级别检查并覆盖策略 ## 截图 ### 规则 浏览包及其规则。可单独开启/关闭规则。  ### 规则详情 检查规则元数据、匹配统计和覆盖状态。  ### 目录 从远程目录同步扩展包并进行安装。  ### 包详情 查看已安装包的信息、版本、标签及包含的规则。  ### 设置 开启/关闭防御功能并查看各项控制内容。包含 **Repo Map Primer**（tree-sitter SessionStart 上下文 — 见 [Repo Map](#repo-map-primer))。  ## 快速开始 环境要求： - Linux (x86_64) - `jq` - `coreutils` - `cmake` 3.20+ - C++20 编译器 (`g++` 10+ 或 `clang++` 13+) 从源码安装： ``` git clone https://github.com/regen-dev/agent-safe-guard.git cd agent-safe-guard git submodule update --init --recursive # required — tree-sitter grammars + doctest + bats cmake -S . -B build/native -DSG_BUILD_NATIVE=ON cmake --build build/native -j$(nproc) ./build/native/native/asg-install ``` 注意事项： - 安装程序会在 `~/.claude/hooks/asg-*` 中创建原生钩子符号链接。 - 它会将 `asg-cli`、`asg-statusline`、`asg-repomap`、`asg-install` 和 `asg-uninstall` 安装到 `~/.local/bin`。 - 它会尝试为 `sgd` 安装并启用用户的 `systemd` socket 单元。 - `~/.local/bin` 应包含在你的 `PATH` 中。 - 安装后启动一个新的 Claude Code 会话。 如果你的环境中没有正常运行的 `systemd --user` 会话，请使用手动守护进程路径： ``` ./build/native/native/asg-install --no-enable-systemd-user ./build/native/native/sgd --socket /tmp/agent-safe-guard/sgd.sock ``` 原生客户端已经会探测 `/tmp/agent-safe-guard/sgd.sock`，因此这种手动模式无需额外的钩子更改即可工作。 ## 验证安装 检查已安装的入口点： ``` ls -l ~/.claude/hooks/asg-pre-tool-use ls -l ~/.local/bin/asg-cli ~/.local/bin/asg-install ~/.local/bin/asg-uninstall ``` 检查公共 CLI： ``` asg-install --help asg-uninstall --help asg-cli --print-rules ``` ## 日常命令 安装或重新安装： ``` asg-install ``` 打开策略控制台： ``` asg-cli ``` 非交互式打印包和规则状态： ``` asg-cli --print-rules ``` 卸载钩子和启动器，同时保留本地配置/状态： ``` asg-uninstall ``` ## 工作原理 热路径执行是原生的： 1. Claude Code 在标准输入上发出 JSON 格式的钩子事件。 2. 原生钩子客户端 (`sg-hook-*`) 通过 Unix socket 将 payload 转发给 `sgd`。 3. 守护进程评估内置规则和已编译的目录模式，然后返回钩子 JSON。 4. Claude Code 接收决策（拒绝、允许、修改输出、停止会话）。 所有执行都是默认拒绝的：如果守护进程不可达，钩子客户端将拒绝工具调用，而不是让其通过。 仓库结构： ``` config.env # Default thresholds and limits native/ # Native daemon, hook clients, CLI tools queries/ # Tree-sitter tag queries (TS/JS) for the repo map hooks/ # Legacy/reference Bash implementation, not installed systemd/ # User systemd socket + service unit templates third_party/ # Pinned submodules (tree-sitter + grammars, doctest) docs/ # Architecture, roadmap, and feature docs tests/ # bats-core integration tests (547 tests) screenshots/ # README assets ``` ## 配置与状态 主要配置文件和状态目录： - `~/.claude/.safeguard/config.env` - `~/.claude/.safeguard/features.env` - `~/.claude/.safeguard/policy/packages.json` - `~/.claude/.safeguard/policy/installed.json` - `~/.claude/.safeguard/policy/catalogs.json` - `~/.claude/.safeguard/policy/stats/` - `~/.claude/.statusline/events.jsonl` 实用的事件检查命令： ``` rg '"event_type":"rule_match"' ~/.claude/.statusline/events.jsonl rg '"event_type":"blocked"' ~/.claude/.statusline/events.jsonl rg '"event_type":"permission_decision"' ~/.claude/.statusline/events.jsonl rg '"event_type":"read_guard"' ~/.claude/.statusline/events.jsonl ``` ## 测试 安装不需要 git 子模块。但测试需要。 ``` git submodule update --init --recursive make native-build make test ``` 实用的测试目标： - `make test` — 所有 547 个测试，并行执行 - `make test-unit` — 仅单元测试 - `make test-integration` — 仅集成测试 - `make coverage` — 附带行覆盖率报告 - `make test-native-pre-smoke` — 针对原生守护进程的预工具使用冒烟测试 - `make test-native-rule-audit` — 验证所有规则均已编译并与预期输入匹配 测试套件在隔离的临时主目录中运行。它不会触碰你真实的 `~/.claude` 状态。 ## Repo Map 入门指南 这是 [aider](https://github.com/Aider-AI/aider) 的 `RepoMap` 移植到原生 C++20 的实现，已集成到现有的守护进程中。 在会话开始时，守护进程使用 tree-sitter 遍历你的仓库，通过交叉引用的 PageRank 对文件进行排序，并将排名靠前文件的紧凑型 `path:line kind name` 映射注入到 Claude 的 `additionalContext` 中。Claude 在每次会话开始时就已经知道类、接口、函数和方法的位置 — 无需预热 Read/Grep 交互。  通过 `asg-cli` → 设置 → "Repo Map Primer" 实时切换。 **示例。** 此功能生效后，在全新会话中询问“这个仓库有 `Promises` 类吗？”可以直接从 primer 中获得即时解答，无需任何文件 I/O： ``` > o repo tem uma classe Promises? em qual arquivo e linha? Sim, há duas cópias — ambas definem class Promises na linha 4: - app-gps-INOVA/src/Promises.js:4 - app-gps-SAMU/src/Promises.js:4 ``` ### 工作原理 1. Tree-sitter 解析每个 `.ts` / `.mts` / `.cts` / `.js` / `.mjs` / `.cjs` 文件（计划在 v0.3 中支持 TSX 和更多语言）。声明文件 (`.d.ts`) 会被跳过。 2. 从跨文件的标识符引用构建文件图，并通过名称形态启发式方法进行加权。 3. 手写的 PageRank 算法（50 次迭代，阻尼系数 0.85）对文件进行排序。 4. 排名靠前的 N 个标签被渲染为 `rel_path:line kind subkind name` 形式的行，其大小通过在 N 上进行二分搜索控制在 `SG_REPOMAP_MAX_TOKENS`（默认 4096）以内。每文件的标签上限（默认 40）可防止批量重新导出耗尽预算。 5. 结果缓存在 `/.asg-repomap/tags.v1.bin`。在 git 仓库中，首次构建会将 `.asg-repomap/` 追加到 `.git/info/exclude`。后续的会话启动会对每个文件进行 mtime 检查，仅重新解析发生更改的文件 — 即使在包含 3k 文件的仓库中，典型的热更新也低于 100 ms。 ### 性能测量 在 Ryzen 9 9950X3D、单线程环境下，针对真实的 TS/JS 工作仓库： | 仓库大小 | 冷启动构建 | 热更新 | 缓存 | 渲染 (预算 4096) | |--- |--- |--- |--- |--- | | 370 个源文件 | 3.3 s | 10 ms | 1.0 MB | 4 个文件 / 160 个标签 | | 1 227 个源文件 | 10.0 s | 40 ms | 3.1 MB | 3 个文件 / 120 个标签 | | 3 235 个源文件 | 21.6 s | 100 ms | 6.8 MB | 3 个文件 / 120 个标签 | 一旦存在缓存，渲染本身的耗时将低于 200 ms。 ### 配置 所有配置项均为可选。默认配置为启用状态。 ``` # ~/.claude/.safeguard/features.env SG_FEATURE_REPOMAP=1 # toggle the SessionStart injection # ~/.claude/.safeguard/config.env (或环境变量) SG_REPOMAP_MAX_TOKENS=4096 # chars/4 budget for the injected map SG_REPOMAP_MAX_FILE_BYTES=524288 # skip source files > 512 KB SG_REPOMAP_MAX_TAGS_PER_FILE=40 # per-file tag cap (0 = unlimited) ``` 通过 `asg-cli` → 设置标签页 → "Repo Map Primer" 进行交互式切换。 ### 直接使用 CLI `asg-repomap` 二进制文件可单独用于调试、脚本编写或预热缓存： ``` asg-repomap build --root ~/src/my-repo # full cache build asg-repomap update --root ~/src/my-repo # incremental (mtime-skip) asg-repomap render --root ~/src/my-repo # print the map asg-repomap render --root ~/src/my-repo --budget 8192 asg-repomap stats --root ~/src/my-repo # files, tags, cache size asg-repomap clean --root ~/src/my-repo # rm -rf .asg-repomap/ asg-repomap build --file some.ts --tags # single-file inspection ``` 完整详情请参阅 [docs/repomap.md](docs/repomap.md)。 ## 扩展包（目录） `agent-safe-guard` 支持从远程目录安装额外的规则包。默认目录托管在 [regen-dev/agent-safe-guard-rules](https://github.com/regen-dev/agent-safe-guard-rules)。 通过 `asg-cli` 的目录标签页同步并安装，或非交互式地执行： ``` asg-cli --catalog-sync asg-cli --catalog-install cloud-defense ``` 目录包使用 SHA256 完整性检查。守护进程在启动时会将目录规则模式编译为正则表达式匹配器。 ## 路线图 分发和平台规划详见 [docs/distribution-roadmap.md](docs/distribution-roadmap.md)。 当前方向： - 优先发布干净稳定的源码版本 - 为 Debian/Ubuntu 用户添加 `.deb` 打包 - 添加 AppImage 以支持便携式 Linux 安装 - 将 Windows 和 macOS 作为探索性工作保留在路线图中，排在传输层/服务抽象检查点之后 ## 文档 - [native/README.md](native/README.md) — 原生运行时、协议、事件日志 - [docs/repomap.md](docs/repomap.md) — 仓库映射算法、CLI、配置、性能测量 - [docs/rule-engine-architecture.md](docs/rule-engine-architecture.md) — 阶段模型、ModSecurity 风格的引擎 - [docs/policy-catalog-console-plan.md](docs/policy-catalog-console-plan.md) — 目录和控制台 UX 设计 - [docs/distribution-roadmap.md](docs/distribution-roadmap.md) — 打包和平台计划 - [docs/memory-safety.md](docs/memory-safety.md) — 面向贡献者的不可妥协的内存与资源安全契约（修改涉及分配器的代码前必读） ## 安全 有关漏洞报告，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：AI代理防护, Bash脚本, C++, C++20, Claude Code, DevSecOps, Fail-closed, Tree-sitter, 上游代理, 云计算, 人工智能安全, 代理监控, 代码安全, 合规性, 命令拦截, 大语言模型安全, 守护进程, 安全助手, 安全策略, 安全钩子, 开源, 提示词设计, 数据擦除, 文件访问控制, 机密信息遮蔽, 机密管理, 权限管理, 模型越狱, 沙箱, 漏洞枚举, 端点防护, 网络安全, 网络安全审计, 规则引擎, 资源限制, 防御破坏性命令, 隐私保护, 预算控制