DCGDestructive Command Guard实战指南为 Claude Code 构建亚毫秒级的破坏性命令拦截钩子【免费下载链接】destructive_command_guardThe Destructive Command Guard (dcg) is for blocking dangerous git and shell commands from being executed by agents.项目地址: https://gitcode.com/GitHub_Trending/de/destructive_command_guard本指南以项目 SKILL.md 为核心展开系统讲解 Destructive Command Guarddcg——一个用 Rust 编写、面向 Claude Code 的高性能PreToolUse钩子它在命令执行之前拦截git reset --hard、rm -rf等破坏性操作并用清晰的解释和安全替代方案阻止 Agent 误删未提交的工作。读完本文你将掌握 dcg 的三大设计原则白名单优先、默认允许、零漏报、完整的拦截/放行规则表、模块化 pack 系统与配置方法、Claude Code 接入步骤、内部四阶段处理管线的源码级原理以及边界情况、性能优化、退出码契约与故障排查方法。为什么需要这样一个钩子AI 编程 Agent 能力强大但会犯错它们可能在一次对话中执行灾难性命令毁掉数小时未提交的工作。SKILL.md 给出了四类典型事故场景Agent 的意图实际执行后果让我清理构建产物rm -rf ./src拼写错误删除整个源码目录我要回退到上一个提交git reset --hard销毁所有未提交更改我来解决合并冲突git checkout -- .丢弃全部本地修改我来清理未跟踪文件git clean -fd永久删除未跟踪文件dcg 的核心承诺就是在这些命令真正执行之前将其拦截给出明确说明为你留下git stash抢救数据的机会。三大关键设计原则1. 白名单优先Whitelist-First Architecture安全模式先于破坏模式被检查确保显式安全的命令永远不会被误伤git checkout -b feature → 匹配 SAFE checkout-new-branch → ALLOW git checkout -- file.txt → 无安全匹配命中 DESTRUCTIVE → DENY这一顺序在评估器src/evaluator.rs中被固化为固定步骤先检查安全模式命中即短路放行再检查破坏模式命中即拒绝最后无匹配默认放行。2. 失败安全默认值Fail-Safe Defaults / Default-Allow未识别的命令默认放行。这保证了钩子永远不会破坏合法工作流只有已知的危险模式会被拦截新出现的 git 命令在明确归类前可以正常使用。3. 零漏报哲学Zero False Negatives Philosophy模式集优先保证绝不放行危险命令而不是优先规避误报。多几次人工确认提示是可接受的代价丢失工作不可接受。拦截清单dcg 阻止什么销毁未提交工作的 Git 命令命令原因git reset --hard销毁未提交更改git reset --merge销毁未提交更改git checkout -- file丢弃文件修改git restore file不带--staged丢弃未提交更改git clean -f永久删除未跟踪文件销毁远程历史的 Git 命令命令原因git push --force/-f覆盖远程提交git branch -d、--delete、-D、-f、-M、-C删除或强制覆盖用户拥有的分支引用销毁 Stash 的 Git 命令命令原因git stash drop永久删除一个 stashgit stash clear永久删除全部 stash文件系统命令命令原因rm -rf位于/tmp、/var/tmp、$TMPDIR之外递归删除极其危险注意rm -rf的拦截范围是临时目录之外——临时目录设计上就是易失的这一取舍在 FAQ 中有详细论证。放行清单dcg 允许什么永远安全的 Git 操作git status、git log、git diff、git add、git commit、git push、git pull、git fetch、只读分支列举、git stash、git stash pop、git stash list全部静默放行。显式安全模式模式为什么安全git checkout -b branch创建新分支git checkout --orphan branch创建孤儿分支git restore --staged file仅取消暂存不触碰工作区git restore -S file--staged的短标志git clean -n/--dry-run预览模式不实际删除rm -rf /tmp/*临时目录本质上是易失的rm -rf $TMPDIR/*Shell 变量形式安全替代--force-with-leasegit push --force-with-lease # ALLOWED - 若远程存在未见过的提交则拒绝推送 git push --force # BLOCKED - 可能覆盖他人的工作模块化 Pack 系统dcg 使用模块化的 pack 系统按类别组织危险命令模式。每个 pack 在源码中都有对应实现目录如 src/packs/database、src/packs/containers、src/packs/kubernetes 等完整的包 ID 索引见 docs/packs/README.md。核心包始终启用Pack说明core.git破坏性 git 命令core.filesystem临时目录之外的危险rm -rf数据库包Pack说明database.postgresqlPostgreSQL 中的 DROP/TRUNCATEdatabase.mysqlMySQL/MariaDB 中的 DROP/TRUNCATEdatabase.mongodbdropDatabase、drop()database.redisFLUSHALL/FLUSHDBdatabase.sqliteSQLite 中的 DROP容器包Pack说明containers.dockerdocker system prune、docker rm -fcontainers.composedocker-compose down --volumescontainers.podmanpodman system pruneKubernetes 包Pack说明kubernetes.kubectlkubectl delete namespacekubernetes.helmhelm uninstallkubernetes.kustomizekustomize delete 模式云厂商包Pack说明cloud.aws破坏性 AWS CLI 命令cloud.gcp破坏性 gcloud 命令cloud.azure破坏性 az 命令基础设施包Pack说明infrastructure.terraformterraform destroyinfrastructure.ansible危险 ansible 模式infrastructure.pulumipulumi destroy系统包Pack说明system.diskdd、mkfs、fdisk 操作system.permissions危险的 chmod/chown 模式system.servicessystemctl stop/disable 模式其他包Pack说明strict_git额外的偏执 git 保护package_managersnpm unpublish、cargo yank配置 Pack# ~/.config/dcg/config.toml [packs] enabled [ database.postgresql, containers.docker, kubernetes, # 启用所有 kubernetes 子包 ]分类 ID 会展开为其全部子包enabled [database]会激活database.postgresql、database.mysql及其余该分类下的包仍可用disabled [database.redis]单独关闭某个子包。规范说明与模式计数可用dcg packs --verbose查看。所有包注册在 src/packs/mod.rs 的REGISTRY: LazyLockPackRegistry中通过LazyLock惰性一次性初始化。环境变量变量说明DCG_PACKScontainers.docker,kubernetes启用包逗号分隔DCG_DISABLEkubernetes.helm禁用包/子包DCG_VERBOSE1详细输出DCG_COLORauto\|always\|never颜色模式DCG_BYPASS1完全绕过 dcg逃生舱环境变量在配置层级中优先级最高高于显式配置文件、用户配置、系统配置与编译默认值。其他常用变量还包括DCG_FAIL_CLOSED1hook 输入无法解析时拒绝而非放行、DCG_UNVERIFIED_DECISIONdeny无法验证的命令直接拒绝适合无人值守会话、DCG_HOOK_TIMEOUT_MShook 评估超时默认 1000ms、DCG_HEREDOC_ENABLED系列heredoc 扫描开关与超时等完整清单见 README.md。安装快速安装推荐仓库根目录提供 install.shUnix/Linux/macOS/WSL与 install.ps1原生 Windows两个安装脚本。安装脚本自动检测平台、下载对应二进制、校验 SHA256 校验和并配置检测到的 Agent 钩子Claude Code、Codex CLI、Gemini CLI、GitHub Copilot CLI、Cursor IDE、Hermes Agent、Posit Assistant 等# 易用模式自动更新 PATH curl -fsSL 仓库 install.sh 地址?$(date %s) | bash -s -- --easy-mode # 系统级安装需要 sudo curl -fsSL 仓库 install.sh 地址?$(date %s) | sudo bash -s -- --system原生 Windows 使用 PowerShell 安装器支持-EasyMode加入用户 PATH与-Verify自检并默认启用windows.filesystem与windows.system两个包开箱即拦截del /s、rd /s、Remove-Item -Recurse、format、vssadmin delete shadows等操作。从源码编译需要 Rust Nightlycargo nightly install --git 仓库地址仓库使用rust-toolchain.toml固定工具链版本预编译二进制覆盖 Linux x86_64、Linux ARM64、macOS Intel、macOS Apple Silicon 与 Windows。Claude Code 配置在~/.claude/settings.json中添加{ hooks: { PreToolUse: [ { matcher: Bash|PowerShell, hooks: [ { type: command, command: /absolute/path/to/dcg } ] } ] } }请将/absolute/path/to/dcg替换为解析后的绝对路径不要使用裸dcg非交互式 hook shell 可能不会继承交互式PATH。在原生 Windows 上使用install.ps1让 hook 获得 PowerShell 安全的绝对命令和显式 shell 选择。重要添加 hook 后必须重启 Claude Code。底层协议支持在 src/hook.rs 中实现HookInput结构兼容 Claude Code、Codex CLI、Copilot CLI、Gemini CLI、VS Code Copilot ChattoolCalls数组、Antigravity CLItoolCall嵌套等多种投递格式并通过turn_id字段识别 Codex 载荷为其输出最小化的hookSpecificOutput拒绝 JSON。工作原理四阶段处理管线SKILL.md 给出了完整的处理流程┌─────────────────────────────────────────────────────────────────┐ │ Claude Code │ │ Agent executes rm -rf ./build │ └─────────────────────┬───────────────────────────────────────────┘ │ ▼ PreToolUse hook (stdin: JSON) ┌─────────────────────────────────────────────────────────────────┐ │ dcg │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Parse │───▶│ Normalize │───▶│ Quick Reject │ │ │ │ JSON │ │ Command │ │ Filter │ │ │ └──────────────┘ └──────────────┘ └──────┬───────┘ │ │ │ │ │ ┌───────────────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Pattern Matching │ │ │ │ 1. Check SAFE_PATTERNS (whitelist) ──▶ Allow if match │ │ │ │ 2. Check DESTRUCTIVE_PATTERNS ──────▶ Deny if match │ │ │ │ 3. No match ────────────────────────▶ Allow (default) │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────┬───────────────────────────────────────────┘ │ ▼ stdout: JSON (deny) or empty (allow)阶段一JSON 解析从 stdin 读取 hook 输入校验 Claude Code 的PreToolUse格式非 Bash 工具立即放行。实际实现在 src/hook.rs 中支持多种 Agent 协议并对toolCalls等字段采用容错反序列化——字段形状不符时不会让整个载荷解析失败而静默放行。阶段二命令规范化剥离绝对路径/usr/bin/git status→git status同时保留参数路径。更深层的规范化由 src/normalize.rs 完成迭代剥离常见包装前缀sudo、env、前导反斜杠\git、command包装器等最大迭代 32 层防止恶意构造的命令造成 DoS且只在不产生歧义时剥离、绝不改变非包装命令的语义。阶段三快速拒绝过滤器使用 SIMD 加速的子串搜索查找 git 或 rm不含这些关键字的命令直接绕过正则这类命令占 99% 以上。源码中预编译了GIT_FINDER与RM_FINDER基于memchrcrate 的memmem::Finder见 src/packs/mod.rs并在 src/packs/mod.rs 明确以 SIMD 加速子串搜索作为快速预过滤器再在可执行片段内做基于上下文的令牌感知检查避免子串误触发。阶段四模式匹配安全模式先检查命中即短路放行破坏模式其次命中即拒绝无匹配默认放行。评价结果模型评估器的统一入口evaluate_command同时服务于 hook 模式与 CLIdcg test保证行为一致src/evaluator.rs。其决策枚举EvaluationDecision有三种取值Allow、Deny、Indeterminate——后者表示安全性评估未完成如评估超时或命令超过max_command_bytes此时不得放行执行。这与默认允许策略互补放行只针对已知安全或未识别的命令不针对来不及检查的命令。退出码契约SKILL.md 的 hook 语境下代码含义0命令安全继续执行2命令被拦截不执行更完整的契约在 src/exit_codes.rs 中定义hook 模式无子命令的裁决由 stdout 上的 JSON 承载且进程退出 0——除非无法写入阻断裁决如 stdout 管道断裂EPIPE此时退出EXIT_HOOK_BLOCK2防止exit 0 但无 JSON被宿主误解为放行。CLI/robot 模式下则有独立的稳定退出码0成功/允许、1命令被拒、2警告、3配置错误、4解析错误、5IO 错误、141输出读取方消失broken pipe。CLI 用法手动测试命令# 显示带构建元数据的版本 dcg --version # 测试一条命令 echo {tool_name:Bash,tool_input:{command:git reset --hard}} | dcg拦截消息示例与上下文建议════════════════════════════════════════════════════════════════════════ BLOCKED dcg ──────────────────────────────────────────────────────────────────────── Reason: git reset --hard destroys uncommitted changes. Use git stash first. Command: git reset --hard HEAD~1 Tip: If you need to run this command, execute it manually in a terminal. Consider using git stash first to save your changes. ════════════════════════════════════════════════════════════════════════上下文建议Contextual Suggestions命令类型建议git reset、git checkout --考虑先用 git stash 保存更改git clean先用 git clean -n 预览git push --force考虑使用 --force-with-leaserm -rf手动执行前仔细核对路径建议机制由PatternMatch.suggestions字段承载src/evaluator.rs各 pack 模式可声明对应的安全替代命令。已处理的边界情况路径规范化/usr/bin/git reset --hard # 被拦截 /usr/local/bin/git checkout -- . # 被拦截 /bin/rm -rf /home/user # 被拦截标志顺序变体rm -rf /path # 组合标志 rm -fr /path # 反序 rm -r -f /path # 分离标志 rm --recursive --force /path # 长标志所有变体都会被处理。Shell 变量展开rm -rf $TMPDIR/build # 放行临时目录 rm -rf ${TMPDIR}/build # 放行 rm -rf $TMPDIR/build # 放行 rm -rf ${TMPDIR:-/tmp}/build # 放行暂存区与工作区恢复的区分git restore --staged file.txt # 放行仅取消暂存 git restore -S file.txt # 放行短标志 git restore file.txt # 拦截丢弃更改 git restore --worktree file.txt # 拦截显式工作区 git restore -S -W file.txt # 拦截包含工作区性能优化dcg 以零感知延迟为设计目标优化技术Lazy Static通过LazyLock一次性编译正则模式SIMD 快速拒绝使用memchrcrate 的 CPU 向量指令提前退出安全匹配立即返回零拷贝 JSONserde_json直接在输入缓冲区上操作零分配路径规范化使用Cowstr发布配置opt-levelz、LTO、单一 codegen unit结果典型命令亚毫秒级执行。LazyLockPackRegistrysrc/packs/mod.rs与LazyLockmemmem::Finder正是正则只编译一次与SIMD 预过滤器两项优化在源码层面的落点。模式数量类型数量安全模式白名单34破坏模式黑名单16注这是核心 git/文件系统规则的基准计数启用更多 pack 后规则总数会随包扩展。安全考虑dcg 防护的对象git checkout --/git reset --hard导致的意外数据丢失强制推送导致的远程历史销毁git stash drop/clear导致的 stash 丢失临时目录之外rm -rf导致的文件系统事故dcg 不防护的对象恶意攻击者可以绕过 hook非 Bash 命令Python/JavaScript 文件写入、API 调用已提交但未推送的工作脚本内部的命令./deploy.sh的内容不会被检查威胁模型dcg 假设 AI Agent意图良好但会犯错。它拦截的是诚实错误而非对抗性攻击。故障排查Hook 不拦截命令确认~/.claude/settings.json包含 hook 配置重启 Claude Code手动测试echo {tool_name:Bash,tool_input:{command:git reset --hard}} | dcgHook 拦截了安全命令检查是否有未覆盖的边界情况向项目提交 issue临时绕过DCG_BYPASS1或手动运行命令FAQQ为什么git branch -d和git branch -D都要拦截小写-d虽然会检查合并状态但依然会删除分支名、上游跟踪配置和便利的 reflog 引用。这些都属于用户拥有的状态因此每种删除形式都需要显式批准。先用git branch -vv、git branch --merged和git branch --no-merged复核。Q为什么git push --force-with-lease被放行--force-with-lease在远程包含你未见过的提交时会拒绝推送从而防止意外覆盖。Q为什么拦截临时目录之外的所有rm -rf递归强制删除极其危险一个拼写错误或错误变量就可能删除关键文件而临时目录设计上就是易失的。Q如果确实需要运行被拦截的命令怎么办dcg 会指示 Agent 请求许可。请在确认后于单独终端手动运行该命令。其他集成工具集成方式Claude Code原生 PreToolUse hookAgent MailAgent 可向协调器报告被拦截的命令BV标记反复触发 dcg 的任务CASS跨会话搜索 dcg 拦截模式RUdcg 保护 agent-sweep 免受破坏性提交影响此外仓库还提供了dcg explain解释某条命令为何被拦截、dcg simulate、dcg scanCI 扫描、dcg allowlist白名单管理、dcg allow-once一次性放行码以及命令历史dcg history/dcg stats/dcg suggest-allowlist基于 SQLite需在配置中显式开启等丰富的运维子命令。更多细节可查阅 README.md、docs 目录下的专项文档以及针对各 Agent 的集成指南如 docs/codex-integration.md、docs/crush-integration.md、docs/opencode-integration.md。【免费下载链接】destructive_command_guardThe Destructive Command Guard (dcg) is for blocking dangerous git and shell commands from being executed by agents.项目地址: https://gitcode.com/GitHub_Trending/de/destructive_command_guard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考