dwarvesf/claude-guardrails

# claude-guardrails Claude Code 的强化安全配置 — 内置拒绝规则、钩子和提示注入防御。 ## 存在的原因 Claude Code 可以读取你的文件系统、执行 shell 命令并自主获取 URL。克隆仓库中的中毒文件可以通过提示注入劫持其行为。粗心的工具调用可能泄露你的 SSH 密钥或 `.env` 机密。这些配置提供了纵深防御，让你在每个会话中无需刻意思考。 ## 完整版与精简版 | | **精简版** | **完整版** | |---|---|---| | **适用场景** | 内部/可信项目 | 开源仓库、不可信代码库、生产凭证 | | 凭证拒绝规则 | 21 条（SSH、AWS、GPG、kube、Azure、.env、.pem、破坏性 Bash 等） | 40 条（新增敏感目录、Shell 配置文件、加密钱包等） | | PreToolUse 钩子 | 4（破坏性删除、直接推送、管道到 Shell、提交时密钥扫描） | 6（新增数据外泄、权限提升） | | UserPromptSubmit 密钥扫描器 | 是（`scan-secrets.sh`） | 是（`scan-secrets.sh`） | | PreToolUse 提交时密钥扫描 | 是（`scan-commit.sh`） | 是（`scan-commit.sh`） | | PostToolUse 提示注入扫描器 | 否 | 是（`prompt-injection-defender.sh`） | | 隐私环境标志 | 是（遥测、错误报告、反馈调查关闭） | 是 | | CLAUDE.md 安全规则 | 是 | 是 | | 沙箱指引 | 是 — 此为执行层 | 是 + devcontainer 指针 | | **前置条件** | `jq` | `jq` | ## 快速开始 ``` # 安装 jq（如果尚未安装） brew install jq # macOS # sudo apt install jq # Debian/Ubuntu # 精简版（4 个钩子，21 条拒绝规则——适用于受信项目） npx claude-guardrails install # 完整版（6 个钩子 + 提示注入扫描器——适用于不受信代码库） npx claude-guardrails install full ``` 该脚本会合并到你的 `~/.claude/settings.json`（先备份），并且可以重复安全运行。

从源码安装（git 克隆）

``` git clone https://github.com/dwarvesf/claude-guardrails.git cd claude-guardrails ./install.sh # lite ./install.sh full # full ```

手动安装

如果你更喜欢手动安装，请参考 [`full/SETUP.md`](full/SETUP.md) 的逐步说明。关键步骤如下： 1. 将变体的 `settings.json` 复制到 `~/.claude/settings.json`（或将 `permissions.deny` 和 `hooks.PreToolUse` 数组合并到现有配置） 2. 将变体的 `CLAUDE-security-section.md` 追加到 `~/.claude/CLAUDE.md` 3. 将 `patterns/secrets.json` 复制到 `~/.claude/hooks/patterns/secrets.json`（下方两个扫描器共享的模式列表） 4. 将 `scan-secrets.sh` 复制到 `~/.claude/hooks/scan-secrets/` 并在设置中添加 `UserPromptSubmit` 钩子条目 5. 将 `scan-commit.sh` 复制到 `~/.claude/hooks/scan-commit/`（其 `PreToolUse` 钩子条目已在变体的 `settings.json` 中） 6.（仅完整版）将 `prompt-injection-defender.sh` 复制到 `~/.claude/hooks/prompt-injection-defender/` 并在设置中添加 `PostToolUse` 钩子条目

## 卸载 ``` # 移除精简版防护栏 npx claude-guardrails uninstall # 移除完整版防护栏 npx claude-guardrails uninstall full ```

从源码卸载

``` ./uninstall.sh # lite ./uninstall.sh full # full ```

卸载采用**外科式移除**方式：它读取变体配置以精确识别添加了哪些拒绝规则和钩子，然后仅移除这些条目。你的自定义规则、钩子和其他设置将保持不变。它**不会**从备份恢复，这意味着即使你在安装后修改了设置也能正确工作。 卸载前会将备份保存到 `~/.claude/settings.json.pre-uninstall`，以防需要回滚。 ## 工作原理 基于模式的钩子和拒绝规则是纵深防御，而非安全边界。足够巧妙的提示注入可以重写或混淆我们提供的任何正则表达式。实际强制执行限制的是 OS 级的沙箱。启用它每一会话，然后将其余内容视为对常见、意外和明显情况的捕获网。 ### 沙箱是边界 运行 `/sandbox` 开始会话。在 macOS 上使用 Seatbelt，在 Linux 上使用 bubblewrap。写入被限制在当前工作目录；网络访问被限制到允许的域名。这是 `bash cat ~/.ssh/id_rsa` 无法逃逸的层级，这也是为什么我们的拒绝规则和钩子严格建立在其之上。 对于检查不可信代码的会话 — 未知仓库、开源分支、承包商提交的代码 — 升级到容器。Trail of Bits 的 [claude-code-devcontainer](https://github.com/trailofbits/claude-code-devcontainer) 提供基于 Docker 的设置并包含可选的 iptables 允许列表。我们尚未在此仓库中提供；请使用他们的。 ### 护栏层级（可被绕过，但仍值得拥有） 这些层级捕获沙箱不需要处理的内容。它们无法阻止坚定的提示注入： 1. **权限拒绝规则** — 阻止 Claude 的读/写/Bash 工具触碰敏感路径并执行明显危险的命令（SSH、AWS、GPG、kubeconfig、Azure、加密钱包，以及 Bash 模式中的 `sudo`/`mkfs`/`dd`/`rm -rf`）。_覆盖 Claude 的内置工具；混淆的 Bash 可能绕过。_ 2. **PreToolUse 钩子** — 在执行前匹配危险的 Bash 命令（破坏性删除、直接推送、管道到 Shell）。`完整版` 新增数据外泄和权限提升模式。两者均包含 `scan-commit.sh`，它在 `git commit` 时拦截暂存区并通过相同的密钥正则集扫描提交内容 — 捕获被写入代码并尝试提交的凭证。_基于模式，混淆可绕过。_ 3. **UserPromptSubmit 密钥扫描器** — `scan-secrets.sh`（bash + jq）阻止包含活动凭证（AWS 密钥、GitHub / Anthropic / OpenAI 令牌、PEM 块、BIP39 短语）的提示。防止粘贴的密钥到达模型或落地到会话记录。 4. **PostToolUse 提示注入扫描器**（仅完整版）— 扫描 Read/WebFetch/Bash 输出中的注入模式。警告但不阻止，因此合法安全内容不会中断。 5. **CLAUDE.md 安全规则** — Claude 通常会遵循的自然语言指令（不写硬编码密钥、对外部内容保持不信任等）。 6. **隐私环境标志** — 两者均设置 `DISABLE_TELEMETRY=1`、`DISABLE_ERROR_REPORTING=1`、`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。我们有意不设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` — 该标志也会阻止自动更新，导致你停留在未修补的版本。 没有单一层级足够。堆叠使用。 详见 [`full/SETUP.md`](full/SETUP.md) 以了解每层及其限制。 ## 已知权衡 这些护栏以便利性换取安全性。请清楚你正在接受的内容： **误报会中断你的工作流。** 通配符模式故意宽泛。`Read **/*.key` 会阻止所有 `.key` 文件 — 包括 `translation.key` 或 `config.key` 等合法文件。`Read **/*secret*`（完整版）会阻止如 `secret_santa.py` 的文件。`rm -rf` 钩子会触发清理构建目录（`rm -rf dist/`）。发生时，你需要手动运行命令或临时调整规则。 **拒绝规则仅覆盖 Claude 的内置工具，不覆盖 Bash。** `Read ~/.ssh/id_rsa` 被拒绝，但 `bash cat ~/.ssh/id_rsa` 不会被阻止。钩子能捕获部分 Bash 模式，但无法覆盖全部。这是模式匹配的基本限制 — 参见上文“为什么沙箱是边界”。 **钩子为每个 Bash 调用增加延迟。** 每个 PreToolUse 钩子都会启动子 shell，通过 `jq` 管道并运行 `grep`。4 个钩子（精简版）意味着每次 Bash 工具调用额外 4 个进程。6 个钩子加 PostToolUse 扫描器（完整版）为 7 个。仅在慢速机器或快速连续命令时明显。`scan-commit` 钩子仅在实际包含 `git commit` 时执行大量工作（`git diff --cached`），非提交调用的成本仅为一次 `jq` 调用加对命令字符串的正则匹配。 **提示注入扫描器较嘈杂。** 它匹配类似 “ previous instructions” 和 “system prompt:” 的字符串 — 这些也出现在合法的安全文档、CTF 写本和本 README 中。阅读安全相关内容时会收到警告。它警告但不阻止，因此代价是干扰而非中断。 **完整变体会覆盖部分全局设置。** `full/settings.json` 设置 `alwaysThinkingEnabled: true` 和 `cleanupPeriodDays: 90`。`install.sh` 中的合并使用 jq 的 `*` 运算符，因此这些值会覆盖你现有的对应键值。安装后请检查差异，如果你有自定义全局设置。 **没有简单的按文件例外。** 如果你确实需要 Claude 读取 `.env.example` 或测试用的 `.pem` 文件，没有允许列表机制。你只能移除拒绝规则、用 Bash 读取文件，或将文件复制到不匹配的路径。这是 Claude Code 权限模型的缺口，我们无法在此修复。 ## 不可信仓库 在用 Claude Code 打开任何克隆仓库前，检查隐藏配置： ``` find . -path "*/.claude/*" -o -name ".mcp.json" -o -name "CLAUDE.md" | head -20 ``` 恶意仓库可能携带 `.claude/hooks/` 中的任意 Shell 脚本、`.mcp.json` 中的外泄能力 MCP 服务器，或 `CLAUDE.md` 中的提示注入。查看后再信任。 ## 参考 - [Trail of Bits — claude-code-config](https://github.com/trailofbits/claude-code-config) - [Trail of Bits — claude-code-devcontainer](https://github.com/trailofbits/claude-code-devcontainer) - [Lasso Security — Claude hooks 提示注入防御器](https://github.com/lasso-security/claude-hooks) - [Anthropic — Claude Code 安全文档](https://code.claude.com/docs/en/security) - [Anthropic — 钩子参考](https://code.claude.com/docs/en/hooks) - [Snyk — ToxicSkills 研究](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/) - [Check Point Research — CVE-2025-59536](https://research.checkpoint.com/2026/rce-and-api-token-exfiltration-through-claude-code-project-files-cve-2025-59536/) 维护者：[Dwarves Foundation](https://dwarves.foundation)。

标签：AWS, Azure, Claude Code, CLAUDE.md安全规则, DNS 解析, DPI, .env, GPG, jq依赖, JSON合并备份, npx安装, .pem, Shell Hook, SSH, StruQ, 全量防护, 凭据防护, 协议分析, 子域名变形, 安全配置, 密钥保护, 开源仓库, 提交时扫描, 提示注入扫描器, 提示注入防御, 数据外泄, 权限拒绝规则, 权限提升, 沙箱指引, 源代码安全, 生产凭据, 破坏性Shell命令, 秘密扫描, 网络安全审计, 轻量防护, 遥测关闭, 防御深度, 隐私标志