克劳德代码安全网

一个克劳德代码插件，充当安全网，在破坏性 Git 和文件系统命令执行前将其拦截。

目录

• 为何存在此项目
• 为何不使用权限拒绝规则？
• 沙箱又如何？
• 先决条件
• 快速入门
  • 克劳德代码安装
  • OpenCode 安装
  • Gemini CLI 安装
  • GitHub Copilot CLI 安装
• 状态栏集成
  • 通过斜杠命令设置
  • 手动设置
  • 表情符号模式指示器
• 诊断
• 解释（调试分析）
• 被阻止的命令
• 允许的命令
• 被阻止时会发生什么
• 测试钩子
• 开发
• 自定义规则（实验性）
  • 配置文件位置
  • 规则模式
  • 匹配行为
  • 示例
  • 错误处理
• 高级功能
  • 严格模式
  • 偏执模式
  • Shell 包装检测
  • 解释器单行命令检测
  • 敏感信息脱敏
  • 审计日志记录
• 许可证

为何存在此项目

我们以惨痛的教训认识到，仅靠指令并不能有效约束 AI 代理的行为。Reddit 上的一则帖子生动地展示了这一点：克劳德代码在悄无声息间执行了 rm -rf ~/ 或 git checkout -- 等命令，瞬间清空了数小时的工作成果。这清楚地表明，仅仅依靠 CLAUDE.md 或 AGENTS.md 文件中的软性规则，无法替代硬性的技术限制措施。因此，当前的做法是利用专门的钩子程序来自动阻止代理运行破坏性命令。

为何不使用权限拒绝规则？

克劳德代码的 .claude/settings.json 支持带有通配符匹配的拒绝规则（例如 Bash(git reset --hard:*)）。而本插件与之相比有以下区别：

一目了然

	权限拒绝规则	安全网
设置	需手动配置	开箱即用
解析	通配符模式匹配	语义化命令分析
执行顺序	第二步执行	第一步执行（PreToolUse 钩子）
Shell 包装	不能自动处理（需匹配包装形式）	递归分析（最多 5 层）
解释器单行命令	不能自动处理（需匹配解释器形式）	能够检测并阻止

权限规则存在已知绕过途径

即便使用通配符匹配，Bash 的权限模式也存在诸多局限性，容易被多种方式绕过：

绕过方法	示例
选项置于值之前	curl -X GET http://evil.com 可绕过 Bash(curl http://evil.com:*)
Shell 变量	URL=http://evil.com && curl $URL 可绕过 URL 模式
标志位重新排序	rm -r -f / 可绕过 Bash(rm -rf:*)
多余空格	rm -rf /（双空格）可绕过模式
Shell 包装	sh -c "rm -rf /" 可完全绕过 Bash(rm:*)

安全网能处理模式无法应对的情况

场景	权限规则	安全网
git checkout -b feature（安全）	被 Bash(git checkout:*) 阻止	允许
git checkout -- file（危险）	被 Bash(git checkout:*) 阻止	阻止
rm -rf /tmp/cache（安全）	被 Bash(rm -rf:*) 阻止	允许
rm -r -f /（危险）	因标志位顺序获准执行	阻止
bash -c 'git reset --hard'	因使用包装获准执行	阻止
python -c 'os.system("rm -rf /")'	因使用解释器获准执行	阻止

多层防御

PreToolUse 钩子会在权限系统之前执行。这意味着安全网会优先检查每一条命令，无论你的权限配置如何。即使你误配置了拒绝规则，安全网仍能提供最后一道保护屏障。

建议两者结合使用：权限拒绝规则适合快速、用户可配置的拦截；而安全网则提供更强大、难以绕过的保护机制，且开箱即用。

沙箱又如何？

克劳德代码提供了原生的沙箱功能，可在操作系统层面实现文件系统和网络隔离。以下是它与安全网的对比：

不同层次的保护

	沙箱	安全网
执行方式	操作系统级别（Seatbelt/bubblewrap）	应用程序级别（PreToolUse 钩子）
方法	封闭式——限制文件系统和网络访问	命令分析——阻止破坏性操作
文件系统	默认限制写入（仅当前目录）；读取权限较宽	仅阻止破坏性操作
网络	域名级代理过滤	无
Git 意识	无	针对破坏性 Git 操作有明确规则
抗绕过能力	高——由操作系统强制边界	较低——仅分析命令字符串

为什么沙箱还不够

沙箱会限制文件系统和网络访问，但它并不了解在这些限制范围内哪些操作是具有破坏性的。以下命令不会被沙箱边界阻止：

[!NOTE] 这些命令是自动执行还是需要确认，取决于你的沙箱模式（自动允许 vs. 普通权限），而网络访问仍然取决于你允许的域名策略。Claude Code 还可以通过 dangerouslyDisableSandbox 在沙箱外重试命令（需用户授权）；这可以通过设置 allowUnsandboxedCommands: false 来禁用。

命令	沙箱限制	安全网
git reset --hard	允许（在当前工作目录内）	阻止
git checkout -- .	允许（在当前工作目录内）	阻止
git stash clear	允许（在当前工作目录内）	阻止
git push --force	允许（如果远程域名被允许）	阻止
rm -rf .	允许（在当前工作目录内）	阻止

沙箱会认为 git reset --hard 是一个安全的操作——它只修改当前目录内的文件。但这样一来，你所有未提交的工作就都丢失了。

何时应该使用沙箱

当你的主要关注点是以下情况时，使用沙箱更为合适：

• 提示注入攻击 — 通过限制出站域名来降低数据泄露风险（取决于你允许的域名策略）
• 恶意依赖 — 默认情况下限制文件系统写入和网络访问（受你的沙箱配置影响）
• 执行不受信任的代码 — 操作系统级别的隔离比模式匹配更强大
• 网络控制 — 安全网没有网络保护功能

推荐：同时使用两者

它们分别针对不同的威胁提供保护：

• 沙箱 可以控制破坏范围——即使出现问题，损害也仅限于当前工作目录和已批准的网络域名。
• 安全网 可以防止误操作——它可以捕获那些从沙箱角度看“安全”的 Git 特定错误。

同时运行两者可以提供纵深防御。沙箱处理未知威胁；安全网则处理沙箱允许的已知破坏性模式。

先决条件

• Node.js：运行此插件需要版本 18 或更高。

快速开始

Claude Code 的安装

/plugin marketplace add kenryu42/cc-marketplace
/plugin install safety-net@cc-marketplace
/reload-plugins

Claude Code 自动更新

1. 运行 /plugin → 选择 Marketplaces → 选择 cc-marketplace → 启用自动更新

---

OpenCode 的安装

选项 A：让 LLM 自动完成

将以下内容粘贴到任何 LLM 代理中（Claude Code、OpenCode、Cursor 等）：

按照 https://opencode.ai/config.json 中的模式，在 `~/.config/opencode/opencode.json`（或 `.jsonc`）中安装 cc-safety-net 插件。

选项 B：手动设置

1. 将插件添加到你的配置文件 ~/.config/opencode/opencode.json（或 .jsonc）：

{
  "plugin": ["cc-safety-net"]
}

---

Gemini CLI 的安装

gemini extensions install https://github.com/kenryu42/gemini-safety-net

---

GitHub Copilot CLI 的安装

/plugin install kenryu42/copilot-safety-net

[!NOTE] 安装插件后，你需要重启 Copilot CLI 才能使插件生效。

---

状态栏集成

安全网可以在 Claude Code 的状态栏中显示其状态，表明保护是否启用以及启用了哪些模式。

通过斜杠命令设置

配置状态栏最简单的方式是使用内置的斜杠命令：

/set-statusline

这个交互式命令会：

1. 询问你更倾向于使用 bunx 还是 npx
2. 检查现有的状态栏配置
3. 提供替换或与现有命令管道连接的选项
4. 将配置写入 ~/.claude/settings.json

手动设置

将以下内容添加到你的 ~/.claude/settings.json 中：

使用 Bun（推荐）：

{
  "statusLine": {
    "type": "command",
    "command": "bunx cc-safety-net --statusline"
  }
}

使用 Claude X：

{
  "statusLine": {
    "type": "command",
    "command": "BUN_BE_BUN=1 claude x cc-safety-net --statusline"
  }
}

[!NOTE] claude x 命令仅与原生版 Claude Code 兼容。如果你通过 npm 安装，请改用 npx 或 bunx。

使用 NPM：

{
  "statusLine": {
    "type": "command",
    "command": "npx -y cc-safety-net --statusline"
  }
}

与现有状态栏命令管道连接：

如果你已经有状态栏命令，可以在末尾加入安全网：

{
  "statusLine": {
    "type": "command",
    "command": "your-existing-command | bunx cc-safety-net --statusline"
  }
}

更改会立即生效——无需重启。

模式指示表情符号

状态栏会根据当前配置显示不同的表情符号：

状态	显示	含义
插件已禁用	🛡️ Safety Net ❌	安全网插件未启用
默认模式	🛡️ Safety Net ✅	使用默认设置进行保护
严格模式	🛡️ Safety Net 🔒	SAFETY_NET_STRICT=1 — 对无法解析的命令采取失败关闭
偏执模式	🛡️ Safety Net 👁️	SAFETY_NET_PARANOID=1 — 启用所有偏执检查
仅限 RM 的偏执模式	🛡️ Safety Net 🗑️	SAFETY_NET_PARANOID_RM=1 — 即使在当前工作目录内也会阻止 rm -rf
仅限解释器的偏执模式	🛡️ Safety Net 🐚	SAFETY_NET_PARANOID_INTERPRETERS=1 — 阻止解释器单行命令
严格 + 偏执模式	🛡️ Safety Net 🔒👁️	同时启用严格和偏执模式

当设置了多个环境变量时，模式表情符号会组合显示。

诊断

运行诊断命令以验证你的安装并排查问题：

npx cc-safety-net doctor
# 或使用 bun
bunx cc-safety-net doctor

诊断命令会检查：

检查	描述
钩子集成	验证插件是否为每个支持的平台正确配置
自我测试	运行示例命令以确认阻止功能正常工作
配置	验证用户和项目配置中的自定义规则
环境	显示模式标志的状态（SAFETY_NET_STRICT、SAFETY_NET_PARANOID 等）
最近活动	总结过去 7 天内被阻止的命令
系统信息	显示所有相关工具的版本
更新检查	检查是否有新版本可用

选项

标志	描述
--json	以 JSON 格式输出（便于在 bug 报告中分享）
--skip-update-check	跳过 npm 版本检查

解释（调试分析）

跟踪安全网如何逐步分析一条命令。这对于调试为什么某条命令会被阻止或允许，或者在开发自定义规则时非常有用。

npx cc-safety-net explain "git reset --hard"
# 或使用 bun
bunx cc-safety-net explain "git reset --hard"

选项

标志	描述
--json	将分析结果输出为 JSON
--cwd <path>	使用自定义工作目录进行分析

示例

npx cc-safety-net explain "rm -rf /"
npx cc-safety-net explain --json "git checkout -- file.txt"
npx cc-safety-net explain --cwd /tmp "git status"

被阻止的命令

命令模式	危险原因
git checkout -- files	永久丢弃未提交的更改
git checkout <ref> -- <path>	用引用版本覆盖工作区
git checkout <ref> <path>	当 Git 无法区分引用和路径规范时，可能会覆盖工作区
git restore files	丢弃未提交的更改
git restore --worktree	显式丢弃工作区更改
git reset --hard	销毁所有未提交的更改
git reset --merge	可能会丢失未提交的更改
git clean -f	永久删除未跟踪文件
git push --force / -f	破坏远程历史
git branch -D	强制删除分支，不检查是否已合并
git stash drop	永久删除暂存的更改
git stash clear	删除所有暂存的更改
git worktree remove --force	强制删除工作树，不检查是否有更改
rm -rf（当前目录外的路径）	递归删除当前目录外的文件
rm -rf / 或 ~ 或 $HOME	根目录/主目录的删除极其危险
find ... -delete	永久删除符合条件的文件
xargs rm -rf	动态输入使目标不可预测
xargs <shell> -c	可以执行任意命令
parallel rm -rf	动态输入使目标不可预测
parallel <shell> -c	可以执行任意命令

允许的命令

命令模式	安全原因
git checkout -b branch	创建新分支
git checkout --orphan	创建孤立分支
git restore --staged	仅取消暂存，不丢弃
git restore --help/--version	输出帮助信息或版本号
git branch -d	安全删除，会检查是否已合并
git clean -n / --dry-run	仅预览
git push --force-with-lease	安全强制推送
rm -rf /tmp/...	临时目录是短暂存在的
rm -rf /var/tmp/...	系统临时目录
rm -rf $TMPDIR/...	用户临时目录
rm -rf ./...（在当前目录内）	限制在当前工作目录内

被阻止时的行为

当检测到破坏性命令时，插件会阻止工具执行，并给出原因。

示例输出：

被安全网阻止

原因：git checkout -- 会永久丢弃未提交的更改。请先使用 'git stash'。

命令：git checkout -- src/main.py

如果确实需要执行此操作，请明确征得用户同意，并由用户手动运行该命令。

测试钩子

您可以通过尝试在 Claude Code 中运行被阻止的命令来手动测试钩子：

# 这应该会被阻止
git checkout -- README.md

# 这应该会被允许
git checkout -b test-branch

开发

有关如何参与本项目的详细信息，请参阅 CONTRIBUTING.md。

自定义规则（实验性）

除了内置保护之外，您还可以定义自己的阻止规则，以执行团队约定或项目特定的安全策略。

[!TIP] 使用 /set-custom-rules 可以通过自然语言交互方式创建自定义规则。

GitHub Copilot CLI 用户：由于 Copilot CLI 不支持自定义斜杠命令，请向您的代理发送以下提示：

运行 npx cc-safety-net --custom-rules-doc 并帮我设置自定义规则

快速示例

在项目根目录下创建 .safety-net.json 文件：

{
  "version": 1,
  "rules": [
    {
      "name": "block-git-add-all",
      "command": "git",
      "subcommand": "add",
      "block_args": ["-A", "--all", "."],
      "reason": "请使用 'git add <具体文件>'，而不是一次性添加所有文件。"
    }
  ]
}

现在，git add -A、git add --all 和 git add . 都将被阻止，并显示您的自定义消息。

配置文件位置

配置文件从两个作用域加载并合并：

1. 用户作用域：~/.cc-safety-net/config.json（如果存在则始终加载）
2. 项目作用域：当前工作目录中的 .safety-net.json（如果存在则加载）

合并行为：

• 来自两个作用域的规则会被合并
• 如果两个作用域中存在同名规则，则 项目作用域优先
• 规则名称比较不区分大小写（MyRule 和 myrule 被视为重复）

这使得您可以在用户作用域中定义个人默认规则，同时允许项目覆盖特定规则。

如果在任一位置都没有找到配置文件，则仅应用内置规则。

配置模式

字段	类型	必需	描述
version	整数	是	模式版本（必须为 1）
rules	数组	否	自定义阻止规则列表（默认为空）

规则模式

字段	类型	必需	描述
name	字符串	是	唯一标识符（字母、数字、连字符、下划线；最多 64 个字符）
command	字符串	是	要匹配的基础命令（例如 git、npm、docker）
subcommand	字符串	否	要匹配的子命令（例如 add、install）。如果省略，则匹配任何子命令。
block_args	数组	是	触发阻止的参数（至少需要一个）
reason	字符串	是	被阻止时显示的消息（最多 256 个字符）

匹配行为

• 命令会被规范化为基本名称（/usr/bin/git → git）
• 子命令是命令之后的第一个非选项参数
• 参数会逐字匹配（不使用正则表达式或通配符），短选项会被展开
• 如果 block_args 中的 任意一个 参数出现，命令就会被阻止
• 短选项会被展开：-Ap 会匹配 -A（捆绑的标志会被拆开）
• 长选项采用精确匹配：--all-files 不会匹配 --all
• 自定义规则只会增加限制——它们不能绕过内置保护。

已知局限性

• 短选项展开：-Cfoo 会被视为 -C -f -o -o，而不是 -C foo。阻止 -f 可能会导致对附加选项值的误判。

示例

阻止全局 npm 安装

{
  "version": 1,
  "rules": [
    {
      "name": "block-npm-global",
      "command": "npm",
      "subcommand": "install",
      "block_args": ["-g", "--global"],
      "reason": "全局 npm 安装可能导致版本冲突。请使用 npx 或本地安装。"
    }
  ]
}

阻止危险的 Docker 命令

{
  "version": 1,
  "rules": [
    {
      "name": "block-docker-system-prune",
      "command": "docker",
      "subcommand": "system",
      "block_args": ["prune"],
      "reason": "docker system prune 会移除所有未使用的数据。建议使用更精确的清理方式。"
    }
  ]
}

多条规则

{
  "version": 1,
  "rules": [
    {
      "name": "block-git-add-all",
      "command": "git",
      "subcommand": "add",
      "block_args": ["-A", "--all", ".", "-u", "--update"],
      "reason": "请使用 'git add <具体文件>'，而不是一次性添加所有文件。"
    },
    {
      "name": "block-npm-global",
      "command": "npm",
      "subcommand": "install",
      "block_args": ["-g", "--global"],
      "reason": "请使用 npx 或本地安装，而非全局安装。"
    }
  ]
}

错误处理

自定义规则采用静默回退的错误处理机制。如果您的配置文件无效，安全网将静默回退到仅使用内置规则：

场景	行为
未找到配置文件	静默 — 仅使用内置规则
空配置文件	静默 — 仅使用内置规则
JSON 语法无效	静默 — 仅使用内置规则
缺少必填字段	静默 — 仅使用内置规则
字段格式无效	静默 — 仅使用内置规则
规则名称重复	静默 — 仅使用内置规则

[!重要]
如果您手动添加或修改自定义规则，请务必使用 npx -y cc-safety-net --verify-config 或编码代理中的 /verify-custom-rules 斜杠命令对其进行验证。

阻断输出格式

当自定义规则阻止某个命令时，输出中会包含规则名称：

被安全网阻止

原因：[block-git-add-all] 请使用 'git add <具体文件>'，而不是一次性添加所有文件。

命令：git add -A

高级功能

严格模式

默认情况下，无法解析的命令会被允许通过。启用严格模式后，当钩子输入或 shell 命令无法被安全分析时（例如，JSON 格式无效、引号未闭合、bash -c 包装格式错误），系统将采取失败关闭策略：

export SAFETY_NET_STRICT=1

强硬模式

强硬模式会启用更为严格的安全检查，这可能会对正常工作流程造成干扰。您可以全局启用，也可以通过特定开关进行启用：

# 启用所有强硬检查
export SAFETY_NET_PARANOID=1

# 或者启用特定的强硬检查
export SAFETY_NET_PARANOID_RM=1
export SAFETY_NET_PARANOID_INTERPRETERS=1

强硬行为：

• rm：即使在当前工作目录内，也会阻止非临时性的 rm -rf 命令。
• 解释器：会阻止类似 python -c、node -e、ruby -e 和 perl -e 这样的解释器单行命令（这些命令可能隐藏破坏性操作）。

Shell 包装检测

该防护机制会递归分析被 shell 包装的命令：

bash -c 'git reset --hard'    # 被阻止
sh -lc 'rm -rf /'             # 被阻止

解释器单行命令检测

能够检测隐藏在 Python/Node/Ruby/Perl 单行命令中的破坏性操作：

python -c 'import os; os.system("rm -rf /")'  # 被阻止

敏感信息脱敏

阻断消息会自动脱敏敏感数据（如令牌、密码、API 密钥），以防止日志中泄露机密信息。

审计日志记录

所有被阻断的命令都会被记录到 ~/.cc-safety-net/logs/<session_id>.jsonl 文件中，用于审计目的：

{"ts": "2025-01-15T10:30:00Z", "command": "git reset --hard", "segment": "git reset --hard", "reason": "...", "cwd": "/path/to/project"}

日志条目中的敏感数据会被自动脱敏。

许可证

MIT

Claude Code Safety Net 快速上手指南

Claude Code Safety Net 是一个专为 Claude Code 及其他 AI 编程助手设计的安全插件。它作为一道“安全网”，在破坏性的 Git 命令或文件系统操作执行之前进行拦截，防止 AI 代理误删文件或丢失代码进度。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本需为 18 或更高。
• 支持的 CLI 工具:
  • Claude Code (主要支持)
  • OpenCode
  • Gemini CLI
  • GitHub Copilot CLI
• 包管理器 (可选但推荐): 推荐使用 bun 以获得最佳性能，同时也支持 npm/npx。

注意：国内用户若遇到网络连接问题，建议配置国内镜像源（如淘宝镜像）或使用代理加速 Node.js 包的下载。

安装步骤

根据您的使用场景，选择对应的安装方式：

1. Claude Code (官方推荐)

通过内置插件市场安装，支持自动更新：

/plugin marketplace add kenryu42/cc-marketplace
/plugin install safety-net@cc-marketplace
/reload-plugins

开启自动更新： 运行 /plugin -> 选择 Marketplaces -> 选择 cc-marketplace -> 启用 auto-update。

2. OpenCode

方式 A：让 LLM 自动配置 在任何 LLM 代理中输入以下指令：

Install the cc-safety-net plugin in `~/.config/opencode/opencode.json` (or `.jsonc`) according to the schema at: https://opencode.ai/config.json

方式 B：手动配置 编辑配置文件 ~/.config/opencode/opencode.json (或 .jsonc)，添加以下内容：

{
  "plugin": ["cc-safety-net"]
}

3. Gemini CLI

gemini extensions install https://github.com/kenryu42/gemini-safety-net

4. GitHub Copilot CLI

/plugin install kenryu42/copilot-safety-net

安装完成后，请重启 Copilot CLI 以使插件生效。

基本使用

安装完成后，插件默认立即生效，无需额外配置即可拦截高危命令（如 rm -rf、git reset --hard 等）。

查看保护状态（状态栏集成）

您可以在 Claude Code 的状态栏实时查看安全网的运行状态（是否激活、当前模式等）。

一键配置（推荐）： 在 Claude Code 中运行以下斜杠命令，按向导完成设置：

/set-statusline

手动配置： 如果您希望手动编辑，请将以下配置添加到 ~/.claude/settings.json 中。

使用 Bun (推荐):

{
  "statusLine": {
    "type": "command",
    "command": "bunx cc-safety-net --statusline"
  }
}

使用 NPM:

{
  "statusLine": {
    "type": "command",
    "command": "npx -y cc-safety-net --statusline"
  }
}

与现有状态栏命令共存:

{
  "statusLine": {
    "type": "command",
    "command": "your-existing-command | bunx cc-safety-net --statusline"
  }
}

状态指示器说明

配置成功后，状态栏将显示不同的图标代表当前保护级别：

状态	显示示例	含义
未启用	🛡️ Safety Net ❌	插件未运行
默认模式	🛡️ Safety Net ✅	正常保护，拦截已知破坏性命令
严格模式	🛡️ Safety Net 🔒	SAFETY_NET_STRICT=1，无法解析的命令将被阻止
偏执模式	🛡️ Safety Net 👁️	SAFETY_NET_PARANOID=1，启用所有高级检查

进阶模式切换（可选）

您可以通过设置环境变量来改变保护策略：

• 严格模式 (遇到无法解析的命令直接阻断):

  export SAFETY_NET_STRICT=1
  

• 偏执模式 (启用更广泛的检查，包括解释器单行命令检测等):

  export SAFETY_NET_PARANOID=1
  

现在，您可以放心地让 AI 助手编写代码，Safety Net 将在底层为您守护文件系统安全。