vaporif/parry-guard

# Parry-guard [](https://github.com/vaporif/parry/actions/workflows/check.yml) [](https://github.com/hesreallyhim/awesome-claude-code) Claude Code hooks 的 Prompt 注入扫描器。扫描工具输入和输出，检测注入攻击、机密信息和数据窃取尝试。 ## 前置条件 ML 模型在 HuggingFace 上受限访问。安装前请先： 1. 在 [huggingface.co](https://huggingface.co) 创建账户 2. 接受 [DeBERTa v3 license](https://huggingface.co/ProtectAI/deberta-v3-small-prompt-injection-v2)（所有模式必需） 3. 对于 `full` 模式：还需接受 [Llama Prompt Guard 2 license](https://huggingface.co/meta-llama/Llama-Prompt-Guard-2-86M)（需要 Meta 审批） 4. 在 [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) 创建访问令牌 ## 使用方法 添加到 `~/.claude/settings.json`： **使用 [uvx](https://docs.astral.sh/uv/)：** ``` { "hooks": { "PreToolUse": [{ "command": "uvx parry-guard hook", "timeout": 1000 }], "PostToolUse": [{ "command": "uvx parry-guard hook", "timeout": 5000 }], "UserPromptSubmit": [{ "command": "uvx parry-guard hook", "timeout": 2000 }] } } ``` **使用 [rvx](https://github.com/vaporif/rvx)：** ``` { "hooks": { "PreToolUse": [{ "command": "rvx parry-guard hook", "timeout": 1000 }], "PostToolUse": [{ "command": "rvx parry-guard hook", "timeout": 5000 }], "UserPromptSubmit": [{ "command": "rvx parry-guard hook", "timeout": 2000 }] } } ``` **使用 PATH 中的 parry-guard**（通过 [Nix](#nix-home-manager)、cargo install 或 [release binary](https://github.com/vaporif/parry/releases)）： ``` { "hooks": { "PreToolUse": [{ "command": "parry-guard hook", "timeout": 1000 }], "PostToolUse": [{ "command": "parry-guard hook", "timeout": 5000 }], "UserPromptSubmit": [{ "command": "parry-guard hook", "timeout": 2000 }] } } ```

其他安装方法

**从源码构建：** ``` # 默认 (ONNX backend - 静态链接，比 Candle 快 5-6 倍) cargo install --path crates/cli # Candle backend (纯 Rust，无原生依赖，可移植) cargo install --path crates/cli --no-default-features --features candle ``` ### Nix (home-manager) ``` # flake.nix { inputs.parry.url = "github:vaporif/parry"; outputs = { parry, ... }: { # pass parry to your home-manager config via extraSpecialArgs, overlays, etc. }; } ``` ``` # home-manager module { inputs, pkgs, config, ... }: { imports = [ inputs.parry.homeManagerModules.default ]; programs.parry = { enable = true; package = inputs.parry.packages.${pkgs.system}.default; # onnx (default) # package = inputs.parry.packages.${pkgs.system}.candle; # candle (pure Rust, portable, ~5-6x slower) hfTokenFile = config.sops.secrets.hf-token.path; ignorePaths = [ "/home/user/repos/parry" ]; # claudeMdThreshold = 0.9; # ML threshold for CLAUDE.md scanning (default 0.9) # scanMode = "full"; # fast (default) | full | custom # Custom models (auto-sets scanMode to "custom") # models = [ # { repo = "ProtectAI/deberta-v3-small-prompt-injection-v2"; } # { repo = "meta-llama/Llama-Prompt-Guard-2-86M"; threshold = 0.5; } # ]; }; } ```

## 设置 ### 1. 配置 HuggingFace token 以下方式之一（优先级按顺序递减）： ``` export HF_TOKEN="hf_..." # direct value export HF_TOKEN_PATH="/path/to/token" # file path # 或将 token 放置于 /run/secrets/hf-token-scan-injection ``` 守护进程会在首次扫描时自动启动，首次运行时下载模型，并在空闲 30 分钟后自动退出。 ### 各 Hook 功能 - **PreToolUse**：5 层安全检测 — 污点强制执行、CLAUDE.md 扫描、数据窃取拦截、敏感路径拦截、输入内容注入扫描（Write/Edit/Bash/MCP 工具） - **PostToolUse**：扫描工具输出中的注入/机密信息，检测到时自动标记项目污点 - **UserPromptSubmit**：审计 `.claude/` 目录中的危险权限、注入命令、hook 脚本 ### 守护进程与缓存 守护进程将 ML 模型保存在内存中，可使用 `parry-guard serve --idle-timeout 1800` 独立运行。Hook 调用会自动启动守护进程（若未运行）。 扫描结果缓存在 `~/.parry-guard/scan-cache.redb`（30 天 TTL，缓存命中约 8ms vs 推理约 70ms+）。缓存在各项目间共享，每小时清理一次。 ## 检测层 多阶段，故障闭环（若不确定，则视为不安全）： 1. **Unicode** — 不可见字符（PUA、未分配码位）、同形异义字、RTL 覆盖 2. **Substring** — 使用 Aho-Corasick 算法匹配已知注入短语 3. **Secrets** — 40+ 正则表达式模式匹配凭证（AWS、GitHub/GitLab、云服务商、数据库 URI、私钥等） 4. **ML Classification** — DeBERTa v3 transformer，支持文本分块（256 字符，25 字符重叠）及针对长文本的 head+tail 策略。可配置阈值（默认 0.7）。 5. **Bash Exfiltration** — 使用 tree-sitter AST 分析数据窃取：网络接收端、命令替换、混淆（base64、hex、ROT13）、DNS 隧道、云存储、60+ 敏感路径、40+ 窃取域名 6. **Script Exfiltration** — 对 16 种语言的脚本文件执行相同的源→接收端分析 ### 扫描模式 | 模式 | 模型 | 延迟/块 | 后端 | |------|--------|---------------|---------| | `fast` (默认) | DeBERTa v3 | ~50-70ms | 任意 | | `full` | DeBERTa v3 + Llama Prompt Guard 2 | ~1.5s | 仅 candle | | `custom` | 用户自定义 (`~/.config/parry-guard/models.toml`) | 不定 | 任意 | 交互式工作流推荐使用 `fast`；高安全场景或批量扫描（`parry-guard diff --full`）推荐使用 `full`。两个模型覆盖不同的盲区 —— DeBERTa v3 捕获常见注入模式，而 Llama Prompt Guard 2 更擅长检测隐蔽的、依赖上下文的攻击（角色扮演越狱、间接注入）。两者以 OR 集成方式运行，以约 20 倍的每块延迟代价减少漏报。 ## 配置 ### 全局标志 | 标志 | 环境变量 | 默认值 | 描述 | |------|-----|---------|-------------| | `--threshold` | `PARRY_THRESHOLD` | 0.7 | ML 检测阈值 (0.0–1.0) | | `--claude-md-threshold` | `PARRY_CLAUDE_MD_THRESHOLD` | 0.9 | CLAUDE.md 扫描的 ML 阈值 (0.0–1.0) | | `--scan-mode` | `PARRY_SCAN_MODE` | fast | ML 扫描模式: `fast`, `full`, `custom` | | `--hf-token` | `HF_TOKEN` | — | HuggingFace token（直接值） | | `--hf-token-path` | `HF_TOKEN_PATH` | `/run/secrets/hf-token-scan-injection` | HuggingFace token 文件 | | `--ignore-path` | `PARRY_IGNORE_PATHS` | — | 跳过扫描的路径（逗号分隔 / 可重复） | ### 子命令标志 | 标志 | 环境变量 | 默认值 | 描述 | |------|-----|---------|-------------| | `serve --idle-timeout` | `PARRY_IDLE_TIMEOUT` | 1800 | 守护进程空闲超时（秒） | | `diff --full` | — | false | 使用 ML 扫描而非仅快速扫描 | | `diff -e, --extensions` | — | — | 按文件扩展名过滤（逗号分隔） | ### 仅环境变量 | 环境变量 | 默认值 | 描述 | |-----|---------|-------------| | `PARRY_LOG` | warn | Tracing 过滤器 (`trace`, `debug`, `info`, `warn`, `error`) | | `PARRY_LOG_FILE` | `~/.parry-guard/parry-guard.log` | 覆盖日志文件路径 | 自定义模式：`~/.config/parry-guard/patterns.toml`（添加/移除敏感路径、窃取域名、机密模式）。 自定义模型：`~/.config/parry-guard/models.toml`（配合 `--scan-mode custom` 使用，参见 `examples/models.toml`）。 ## ML 后端 始终需要且仅启用一个后端（编译时强制）。Nix 默认为 ONNX（x86_64-linux, aarch64-linux, aarch64-darwin）。其他平台请使用 `candle` 包。 | 特性 | 描述 | |---------|-------------| | `onnx-fetch` | ONNX，静态链接（构建时下载 ORT）。默认。 | | `candle` | 纯 Rust ML。可移植，无原生依赖。慢约 5-6 倍。 | | `onnx` | ONNX，需自行提供 `ORT_DYLIB_PATH`。 | | `onnx-coreml` | (实验性) Apple Silicon 上的 ONNX with CoreML。 | ``` # 使用 Candle 而非 ONNX 构建 cargo build --no-default-features --features candle ``` ## 性能 Apple Silicon，release 构建，`fast` 模式（仅 DeBERTa v3）。Candle 比 ONNX（默认）**慢 5-6 倍**。运行 `just bench-candle` / `just bench-onnx` 复现（需要 `HF_TOKEN`）。 | 场景 | ONNX (默认) | Candle | |---|---|---| | 短文本 (1 块) | ~10ms | ~61ms | | 中等文本 (2 块) | ~32ms | ~160ms | | 长文本 (6 块) | ~136ms | ~683ms | | 冷启动 (守护进程 + 模型加载) | ~580ms | ~1s | | 快速扫描短路 | ~7ms | ~7ms | | 缓存结果 | ~8ms | ~8ms | ## 致谢 - **ML model**: [ProtectAI/deberta-v3-small-prompt-injection-v2](https://huggingface.co/ProtectAI/deberta-v3-small-prompt-injection-v2) - 同款模型被 [LLM Guard](https://github.com/protectai/llm-guard) 使用 - **窃取模式**: 灵感来自 [GuardDog](https://github.com/DataDog/guarddog)（Datadog 的恶意软件包扫描器） - **全量扫描模式**可选使用 Meta 的 [Llama Prompt Guard 2 86M](https://huggingface.co/meta-llama/Llama-Prompt-Guard-2-86M)，根据 [Llama 4 Community License](https://github.com/meta-llama/llama-models/blob/main/models/llama4/LICENSE) 授权。Built with Llama. ## 许可证 MIT Llama Prompt Guard 2（用于 `full` 扫描模式）根据 Llama 4 Community License 单独授权。参见 [LICENSE-LLAMA](LICENSE-LLAMA)。

标签：Candle, CI/CD安全, Claude Code 插件, CNCF毕业项目, DeBERTa, DNS 反向解析, Hook 机制, Llama, LLM 防火墙, meg, ONNX, Rust, 信息安全, 可视化界面, 大模型安全, 对抗攻击, 提示注入防御, 敏感信息检测, 本地推理, 机器学习推理, 源代码安全, 网络安全, 网络流量审计, 通知系统, 隐私保护