JeongJaeSoon/agent-guard

# Agent Guard [](https://github.com/JeongJaeSoon/agent-guard/releases) [](https://github.com/marketplace/actions/agent-guard-secret-guardrails) [](https://github.com/JeongJaeSoon/agent-guard/actions/workflows/ci.yml) [](LICENSE) **在工具调用运行之前实时阻止您的 AI 编码代理泄露机密信息。**  Agent Guard 是一个面向 AI 编码代理（Claude Code、Codex）及其周边 Git hook、CI 和 CLI 的确定性护栏。它阻止代理意外暴露机密信息的常见方式：读取 `.env`、写入类似于机密的值、运行导出凭据的 shell 命令，或在工具调用后将机密信息留在工作树中。它使用 [gitleaks](https://github.com/gitleaks/gitleaks) 进行检测，并使用纯 shell 脚本进行集成。 与在泄露*发生之后*才捕获它的提交时或 CI 时扫描器不同，Agent Guard 还可以在代理的工具边界运行——对 `.env` 的读取或机密信息的写入会在发生之前被阻止。将其与提交/CI 扫描结合使用以实现纵深防御。 它不是保险柜、凭据轮换工具，也不能替代 GitHub Secret Scanning / Push Protection。 ## 快速开始 (Claude Code) 从 marketplace 安装： ``` /plugin marketplace add JeongJaeSoon/agent-guard /plugin install agent-guard@agent-guard /reload-plugins ``` 验证其是否生效——要求代理读取您的 `.env`： ``` Please read .env ``` 它应该会拒绝： ``` agent-guard: blocked sensitive file access: .env ``` 检测需要您的机器上安装有 `jq` 和 `gitleaks`（`brew install jq gitleaks`；Linux 请参阅[要求](#requirements)）。使用 Codex、Git hook 或 CI？请在下方选择您的路径。 ## 选择安装路径 | 用例 | 安装路径 | 最佳首次检查 | |---|---|---| | Claude Code 代理护栏 | [快速开始 (Claude Code)](#quick-start-claude-code) | 要求代理读取 `.env`；它应该被阻止。 | | Codex 稳定护栏 | [Codex 直接 CLI + Git hook](#codex-plugin) | 运行 `agent-guard smoke-test`；提交一个暂存的测试机密信息，它应该会失败。 | | Codex 实验性插件 hooks | [Codex 插件](#codex-plugin) | 启用 `plugin_hooks`，信任 `/hooks` 中的 hooks，然后要求 Codex 读取 `.env`；它应该被阻止。 | | 本地提交 | [原生 Git hook](#native-git-hook) | 提交一个暂存的测试机密信息；提交应该会失败。 | | CI / PR | [GitHub Actions](#github-actions) | 推送一个带有 gitleaks 可检测测试数据的测试 PR；工作流应该会失败。 | | 手动扫描 | [直接 CLI](#direct-cli) | 运行 `agent-guard smoke-test`。 | ## 要求 Agent Guard 运行在 macOS 和 Linux 上，并需要： - `sh` - `awk` - `git` - `jq` - 推荐使用 `gitleaks` 8.30 或更高版本 下载发布归档文件的安装路径还会使用 `curl`、`tar`、`shasum` 和 `ln`。 PII endpoint 提供程序也会使用 `curl`。 通过直接 CLI 安装： ``` agent-guard setup # prints dependency status and install hints agent-guard check # strict pass/fail dependency check agent-guard smoke-test ``` 通过克隆此代码库： ``` plugins/agent-guard/bin/agent-guard setup make check make smoke-test ``` Claude Code 和 Codex 插件安装不会将 `agent-guard` 添加到您的 shell `PATH` 中；对于这些路径，请使用您的包管理器安装 `jq` 和 `gitleaks`： ``` brew install jq gitleaks ``` 在 Debian / Ubuntu 或 Fedora 上，使用系统包管理器安装 `jq`，并从其发布页面下载 `gitleaks`。 ## Claude Code 插件 在[快速开始 (Claude Code)](#quick-start-claude-code) 中安装并验证。安装完成后的实用斜杠命令： ``` /agent-guard:verify /agent-guard:checksum [VERSION] ``` ## Codex 插件 使用直接 CLI 加上原生 Git hook 作为稳定的 Codex 路径： ``` curl -fsSL https://github.com/JeongJaeSoon/agent-guard/releases/latest/download/bootstrap.sh | sh agent-guard scan-working-tree ~/.agent-guard/install.sh git-hooks ``` 该路径为您提供按需扫描和提交时阻止功能。 Codex 插件 hooks 仍处于开发中的 Codex 功能标志之后。如果您接受该警告并希望获得工具前读/写/bash 护栏，请启用插件 hooks 并从 marketplace 安装： ``` codex features enable plugin_hooks codex plugin marketplace add JeongJaeSoon/agent-guard ``` 然后在 Codex TUI 中打开 `/plugins`，安装 **Agent Guard**，重启 Codex，打开 `/hooks`，并信任 **PreToolUse**、**PostToolUse** 和 **Stop** hooks。 冒烟测试： ``` Please read .env ``` 预期结果： ``` agent-guard: blocked sensitive file access: .env ``` Codex 目前不会自动发现此插件的 `commands/` 目录。当您需要这些工作流时，请要求 Codex 直接运行该二进制文件： ``` ${PLUGIN_ROOT}/bin/agent-guard scan-working-tree ${PLUGIN_ROOT}/bin/agent-guard checksum ``` ## 直接 CLI 无需克隆即可安装最新版本： ``` curl -fsSL https://github.com/JeongJaeSoon/agent-guard/releases/latest/download/bootstrap.sh | sh ``` 安装程序会验证发布归档的校验和，将其解压到 `~/.agent-guard`，将 `agent-guard` 链接到 `~/.local/bin`，并运行 `agent-guard setup`。 常用命令： ``` agent-guard scan-path . agent-guard scan-working-tree agent-guard scan-staged agent-guard pii-filter agent-guard setup agent-guard smoke-test agent-guard checksum ``` 使用 `AGENT_GUARD_VERSION`、`AGENT_GUARD_HOME` 或 `AGENT_GUARD_BIN_DIR` 覆盖默认安装设置。 ## PII 过滤 `agent-guard pii-filter` 从 stdin 读取文本，屏蔽检测到的 PII，并将屏蔽后的文本写入 stdout。默认提供程序是 `regex`，这是一个内置的 shell/awk 适配器，没有 Python 运行时依赖： ``` printf '%s\n' 'Email jane@example.com from 203.0.113.42' | agent-guard pii-filter # 来自 [PII:IP_ADDRESS] 的电子邮件 [PII:EMAIL] ``` 内置的 regex 提供程序会屏蔽常见的确定性格式：电子邮件地址、电话号码、信用卡、美国社会安全号码 (US SSN) 和 IP 地址。纯文本会原样传递。 使用 `AGENT_GUARD_PII_PROVIDER` 选择提供程序： ``` AGENT_GUARD_PII_PROVIDER=regex agent-guard pii-filter --check ``` 由 endpoint 支持的提供程序可用于外部脱敏服务： ``` AGENT_GUARD_PII_PROVIDER=pleno \ AGENT_GUARD_PII_REDACT_URL=http://127.0.0.1:8080/api/redact \ agent-guard pii-filter --check printf '%s\n' 'Customer jane@example.com' \ | AGENT_GUARD_PII_PROVIDER=pleno \ AGENT_GUARD_PII_REDACT_URL=http://127.0.0.1:8080/api/redact \ agent-guard pii-filter ``` `pleno` 和 `http` 使用相同的 HTTP 适配器：以 `{"text":"..."}` 格式 POST JSON，并从 `redacted_text`、`anonymized_text`、`text` 或 `data.redacted_text` 读取脱敏后的字符串。它们需要 `curl`、`jq` 和 `AGENT_GUARD_PII_REDACT_URL`；缺少工具、缺少 URL、HTTP 错误、无效的 JSON 或意外的响应格式都会导致安全失败（fail closed）。 Agent Guard 不会安装、导入、运行或管理 `pleno-anonymize`、Docker、Python 或任何托管服务。如果您使用 `pleno`，请单独运行 pleno-anonymize 或将 `AGENT_GUARD_PII_REDACT_URL` 指向托管的兼容 endpoint。 hooks 中的 PII 处理默认处于关闭状态。有两种主动启用模式： ``` AGENT_GUARD_PII_HOOK_MODE=block # block tool INPUTS that contain any PII # 或 AGENT_GUARD_PII_HOOK_MODE=mask # mask PII in tool OUTPUTS; hard-block Tier-2 inputs ``` 在 **block** 模式下，提议的 `Write`、`Edit`、`MultiEdit`、`apply_patch`、`Bash`、`WebFetch`、`WebSearch` 和 MCP 输入在检测到任何 PII 时都会被阻止，并提示您先运行 `agent-guard pii-filter`。 在 **mask** 模式下，工具*输出*（`PostToolUse`，与机密信息脱敏相同的路径）中的 PII 会被屏蔽，因此模型永远不会看到它。在*输入*侧，mask 模式仅硬阻止 **Tier-2** PII——信用卡、美国社会安全号码 (US SSN) 和韩国居民登记证号，这些绝不能到达工具——并允许 **Tier-1** PII（电子邮件、电话、IPv4）通过，在输出时进行屏蔽。Hooks 无法重写*待处理*的输入 payload，因此允许 Tier-1 输入而不是在原处屏蔽；如果需要对输入侧进行屏蔽，请使用 `agent-guard pii-filter`。 regex 提供程序可识别电子邮件、电话（包括韩国手机号）、IPv4、信用卡、美国社会安全号码 (US SSN) 和韩国居民登记证号。 ## 原生 Git Hook 从克隆或直接 CLI 安装： ``` cd ~/.agent-guard/install.sh git-hooks ``` 通过克隆此代码库： ``` ./install.sh git-hooks ``` 只有在不会覆盖现有 hook 设置的情况下，这才会设置 `core.hooksPath=githooks`。 ## GitHub Actions 添加工作流步骤： ``` - uses: JeongJaeSoon/agent-guard@v1 with: paths: "." gitleaks-checksum: "" ``` 使用 `@v1` 进行兼容更新，或固定到完整的 tag / commit SHA 以实现更严格的可复现性。 获取校验和： ``` agent-guard checksum ``` CI 运行器通常是 `linux/x64`，因此请使用校验和命令打印出的 `linux/x64` 值。`require-checksum` 默认为 `true`；仅在本地实验时将其设置为 `false`。 ### Codex 代码审查 此代码库还包含 `.github/workflows/codex-review.yml`，它会在非草稿 Pull Request 上运行 [openai/codex-action](https://github.com/openai/codex-action)，并将 Codex 反馈作为 PR 评论发布。 要启用它，请在 GitHub 代码库设置中添加一个名为 `OPENAI_API_KEY` 的 Actions secret。该工作流特意在 `pull_request` 上运行，在没有持久化 Git 凭据的情况下检出 PR 合并提交，并在具有 `drop-sudo` 的只读沙箱中运行 Codex。 ## 被阻止的内容 - 对拒绝列表路径（如 `.env*`、私钥、`.aws/credentials`、`.npmrc` 和 `.pypirc`）的 `Read`、`NotebookRead`、`Grep` 和 `Glob` 访问 - 包含类似于机密值的 `Write`、`Edit`、`MultiEdit` 和 Codex `apply_patch` 内容 - 包含类似于机密值的 `WebFetch`、`WebSearch` 和 MCP 工具输入 JSON - 有风险的 shell 命令，例如 `printenv`、`op read`、`vault kv get`、`aws secretsmanager get-secret-value`、`cat .env` 和 `git commit --no-verify` - 提议的写入、shell、web 或 MCP 输入中的 PII —— 当 `AGENT_GUARD_PII_HOOK_MODE=block` 时为所有 PII，或者当 `AGENT_GUARD_PII_HOOK_MODE=mask` 时仅为 Tier-2 PII（信用卡、美国社会安全号码 US SSN、韩国居民登记证号） - 原生 pre-commit hook 中暂存的添加行 - 代理更改后工作树的添加行和未跟踪文件 Patch 和 diff 扫描仅检查添加的行。允许移除现有的泄露值。 ## 被屏蔽的内容 除了阻止之外，Agent Guard 还会在模型看到之前**屏蔽**工具*输出*中类似于机密的值。`PostToolUse` 脱敏器会扫描 `Bash`（stdout/stderr）和读取类工具（`Read`、`NotebookRead`、`Grep`、`Glob`、`WebFetch`、`WebSearch` 和 `mcp__.*`）的结果，并通过 `updatedToolOutput` 将检测到的任何机密原处重写为 `[REDACTED]`，从而保留结果的形状。这弥补了命令*打印*出工具前检查未察觉的凭据的漏洞——例如 `cat memo.txt`、打印环境变量的 CLI 或导出 `KEY=value` 对的工具。检测将 gitleaks 与 `KEY=value` 环境变量分配启发式方法结合使用。它默认开启；使用 `AGENT_GUARD_OUTPUT_REDACT=off` 禁用。 当 `AGENT_GUARD_PII_HOOK_MODE=mask` 时，相同的 `PostToolUse` 脱敏器还会屏蔽工具输出中的 **PII** —— 电子邮件、电话（包括韩国手机号）、IPv4、信用卡、美国社会安全号码 (US SSN) 和韩国居民登记证号将在原处变为 `[PII:TYPE]` 占位符。机密信息脱敏和 PII 屏蔽将组合成一次重写，因此同时包含两者的结果会被一次性完全净化。 ## Shell 集成（屏蔽 `!` shell 转义输出） `PostToolUse` 脱敏器只能看到代理*工具调用*的结果。当您在 Claude Code 提示符下键入以 `!` 为前缀的命令时，它会在会话 shell 中运行，并且其**输出会被捕获到记录并发送给模型**——但它不是工具调用，因此**不会**触发任何 Agent Guard hook（这是一个已知的盲点）。如果该输出包含凭据，模型将会看到未屏蔽的内容。 `agent-guard exec` 弥补了这一漏洞。它从不阻止命令——它会运行至完成并传播其退出代码——但它会捕获组合的 stdout+stderr，使用与输出脱敏器相同的检测引擎屏蔽类似于机密的值（当 `AGENT_GUARD_PII_HOOK_MODE=mask` 时也包括 PII），并仅打印**脱敏后**的文本。命令仍然会运行，但您和模型看到的所有内容都是净化后的输出——绝不会发出原始机密。捕获是带缓冲的，因此这适用于非交互式信息命令（env / secret / config 导出），而不适用于 TUI 或流式程序。`AGENT_GUARD_OUTPUT_REDACT=off` 会禁用机密屏蔽；屏蔽默认开启。 ``` agent-guard exec -- printenv # runs it, but the transcript gets [REDACTED] in place of secrets ``` 为了更加方便，请将 shell 集成添加到您的 `~/.bashrc` / `~/.zshrc` 中： ``` eval "$(agent-guard shell-init)" ``` 或者让 `setup-shell` 为您编写（并在以后更新）该行——以幂等方式，并且当 `agent-guard` 尚未出现在您的 `$PATH` 中时使用绝对路径： ``` agent-guard setup-shell # add `--experimental-bang-guard` to opt into the bang guard below ``` 这会定义 `agx`（`agent-guard exec --` 的一个轻量级包装器），以便您可以运行 `agx `——在 Claude Code 中，即 `!agx `——并在模型看到输出之前对其进行屏蔽。它还安装了一个**仅警告、非阻止性**的提示（zsh `preexec` / bash `DEBUG` trap），当您在没有使用它的情况下运行已知的加载机密惯用语时，它会提醒您使用 `agx`。该提示永远不会阻止或修改您的命令；传递 `--bash` 或 `--zsh` 以强制指定目标 shell。 ### 实验性：自动屏蔽 `!` 读取（主动启用） 上述提示依赖于 `preexec` / `DEBUG` hook——但 Claude Code 是从剥离了这些 hooks（并执行了 `unalias -a`）的 **shell 快照**中运行 `!` 命令的，因此提示永远不会针对 `!` 触发。该快照*确实*保留了 shell **函数**，因此一个主动开启的标志会为常见的导出命令安装函数覆盖： ``` eval "$(agent-guard shell-init --experimental-bang-guard)" ``` 这会覆盖 `cat`、`head` 和 `printenv`，以便——**仅在 Claude Code 内部**（以 `$CLAUDECODE` 为门控）——它们通过 `agent-guard exec` 进行路由，在记录捕获其输出之前对其进行屏蔽。因此 `!cat config.txt` 会自动将其机密信息脱敏，而无需您记得键入 `agx`。在正常的终端中（未设置 `$CLAUDECODE`），覆盖将保持不活动状态，并回退到普通的 `cat` / `head` / `printenv` 行为。 在此调用中，二进制文件按以下顺序解析：显式的 `$AGENT_GUARD_BIN`，然后是 `$PATH` 上的 `agent-guard`，最后是在 `shell-init` 时**写入代码段中的绝对路径**。最后一种回退方式意味着该防护适用于**仅插件安装**——在这种情况下，`agent-guard` 永远不会添加到 `$PATH`——无需额外的 CLI 安装。如果三者均无法解析（例如插件更新移动了二进制文件并导致写入的路径过期），防护将**开放失败 (fail open)**：它会运行您的命令，但会向 stderr 打印一条醒目的 `output is NOT masked` 警告，告诉您重新运行 `agent-guard setup-shell`。（`agx` 作为一个*显式*的屏蔽请求，则会**安全失败 (fail closed)**——它拒绝运行，以免造成泄露。） **这是尽力而为，而不是安全控制。** 它仅涵盖这些命令名称，并且可以通过绝对路径（`/bin/cat`）、`source` / `.`、`python -c 'open(...)'` 或重定向（`< file`）轻易绕过。由于 `agent-guard exec` 会在屏蔽前缓冲整个输出，**流式传输 / follow 命令会卡死**——因此 `tail` 被*故意*未包装，并且您不应 `agx` 一个 `tail -f`、pager 或任何长时间运行的程序（仅包装会终止的导出命令）。输出是通过 shell 替换捕获的，因此包装是**纯文本的**——包含二进制或 NUL 的读取会丢失嵌入的 NUL 及其末尾的换行符，因此请使用 `command cat` / `\cat` 来获得忠实的二进制输出。每次包装的调用也会进行一次 gitleaks 扫描。请将其视为针对常见情况的便利提示，而不是边界——唯一与通道无关的修复方法仍然是出口脱敏代理或上游的 `!`-命令 hook。 ## 已知限制 Agent Guard 是一个确定性的轻量级护栏——而不是 DLP 系统、EDR 或保险柜。它使用 gitleaks 扫描已跟踪的 diff、暂存的更改和未跟踪的文件，并阻止固定列表中的敏感路径和 shell 惯用语。它故意**不**检查命令读取的任意文件内容，并且在设计上存在以下盲点： - **被 Gitignore 的文件不会被扫描。** 工作树和 post-tool/stop 兜底机制使用 `git ls-files --others --exclude-standard` 和 `git diff`，两者都会跳过 `.gitignore` 过滤的路径。写入到被 gitignore 的文件（例如 `secrets/` 或 `*.local`）中的机密不会被兜底机制捕获。请将真实的机密完全排除在代码库之外。 - **仅覆盖 Git 工作树内的文件。** post-tool 和 stop hooks 在 Git 代码库之外不会执行任何操作，并且扫描范围仅限于当前代码库。代码库根目录之外的文件，或者在没有代码库时写入的文件，没有兜底机制。使用 `agent-guard scan-path ` 按需扫描任意树。 - **路径和命令阻止使用固定列表。** Read/Grep/Glob 阻止匹配 `deny-read-paths.txt` 中的路径；shell 阻止匹配 `deny-bash-patterns.txt` 中的惯用语。未列出的路径中的机密，或由未列出的工具或标志读取的机密，不会被阻止。使用 `AGENT_GUARD_DENY_READ_PATHS` / `AGENT_GUARD_DENY_BASH_PATTERNS` 扩展列表。 - **输出屏蔽是尽力而为的。** 工具输出（`Bash` stdout/stderr、文件读取）中类似于机密的值会被 `PostToolUse` 脱敏器（`AGENT_GUARD_OUTPUT_REDACT`，默认开启）原处屏蔽，但检测是基于启发式的——即 gitleaks 加上 `KEY=value` 环境变量分配规则。不常见或自定义的机密格式仍然可能漏网，并且脱敏器只能看到代理*工具调用*的结果。PII 屏蔽（`AGENT_GUARD_PII_HOOK_MODE=mask`）同样是基于 regex 的：它可能会过度匹配（将版本字符串读取为 IPv4）或漏掉没有对应规则的本地化格式。机密脱敏器和 PII 屏蔽器都只遍历 JSON 字符串的*值*——如果机密或 PII 字符串作为对象*键*出现，则不会被屏蔽，因为重写键可能会将两个不同的键合并为一个占位符并导致条目丢失。请将输出屏蔽视为纵深防御，并始终将真实的机密和个人数据排除在代理会话之外。 - **Bash 检测是基于模式的。** 拒绝列表针对的是常见意外和明显的恶意惯用语；主动逃避的代理可以精心设计一条与之均不匹配的命令。请将 shell 阻止视为纵深防御，而不是完整的对抗边界。 - **用户键入的 shell 转义命令会绕过所有 hook。** Agent Guard 完全通过工具使用 hooks（`PreToolUse` / `PostToolUse`）和 git hooks 工作。用户通过主机的交互式 shell 转义直接运行的命令——例如在代理提示符下键入的以 `!` 为前缀的命令——永远不会成为工具调用，因此**不会**触发任何 Agent Guard hook：既没有输入阻止，也没有输出脱敏。此类命令打印的机密（例如输出未重定向到 `/dev/null` 的环境变量读取或 vault 读取 CLI）会未经屏蔽地落入会话记录中。建议的缓解措施是通过 `agx ` / `agent-guard exec -- ` 运行此类命令（参见 [Shell 集成](#shell-integration-masking--shell-escape-output)），以便在输出到达模型*之前*对其进行屏蔽——或者，要自动屏蔽常见的导出命令，请选择启用[实验性感叹号防护](#experimental-auto-masking--reads-opt-in)。或者，*通过*代理的工具运行加载机密的命令以应用 hooks，或者将其输出重定向到远离记录的地方——务必重定向两个流，因为许多 CLI 会将凭据或包含机密的诊断信息打印到 stderr（`>/dev/null 2>&1`）。 为了实现纵深防御，请将 Agent Guard 与 GitHub Secret Scanning / Push Protection 以及机密管理器配合使用，确保凭据永远不会到达工作树。 ## 配置 使用环境变量覆盖内置策略： ``` AGENT_GUARD_GITLEAKS_CONFIG=/path/to/gitleaks.toml AGENT_GUARD_DENY_READ_PATHS=/path/to/deny-read-paths.txt AGENT_GUARD_DENY_BASH_PATTERNS=/path/to/deny-bash-patterns.txt AGENT_GUARD_PII_PROVIDER=regex AGENT_GUARD_PII_REDACT_URL=http://127.0.0.1:8080/api/redact AGENT_GUARD_PII_HOOK_MODE=off AGENT_GUARD_OUTPUT_REDACT=mask ``` 设置 `AGENT_GUARD_OUTPUT_REDACT=off` 以禁用屏蔽工具输出中类似于机密的值（默认为 `mask`）。将 `AGENT_GUARD_PII_HOOK_MODE` 设置为 `block`（阻止工具输入中的 PII）、`mask`（屏蔽工具输出中的 PII + 硬阻止 Tier-2 PII 输入）或 `off`（默认）。 项目本地的 `.gitleaks.toml` 文件不会自动受信任。 ## 校验和与自动安装 `agent-guard setup --install` 可以安装 `gitleaks`，但必须带有显式的校验和： ``` agent-guard checksum agent-guard setup --install \ --gitleaks-version 8.30.1 \ --gitleaks-checksum ``` 校验和助手会打印所有支持的 OS / 架构值以及适用于 CLI 设置和 GitHub Actions 的可直接粘贴的代码段。 ## 主机集成 Agent Guard 在 Claude Code 和 Codex 之间共享其扫描器实现，但保持主机连接的明确性： - `plugins/agent-guard/bin/agent-guard`、`config/` 和 `scripts/` 是共享的。 - Claude Code 使用 `.claude-plugin/plugin.json`、`commands/` 和 `hooks/hooks.json`。 - Codex 使用 `.codex-plugin/plugin.json` 和插件根目录下的 `hooks.json` 配套文件。 - Codex 不会自动发现 `commands/`，因此按需工作流直接使用该二进制文件。 ## 开发 ``` make help make test make smoke-test make scan make scan-staged make checksum ``` `make smoke-test` 在临时项目中使用真实的 `git`、`jq` 和 `gitleaks`。`make test` 是更快的确定性路由套件，并在某些情况下使用模拟扫描器。

标签：AI编程助手, Cutter, Git Hooks, StruQ, 安全防护