mark-liu/webguard

# WebGuard 安全的 Web 获取 MCP 服务器，专为 LLM 智能体设计。在获取的内容进入 LLM 上下文窗口**之前**扫描提示注入攻击。恶意内容将被完全拦截 —— 零 Token 泄露。 ## 变更日志 (Go → Rust) - **二进制文件**：6MB vs 10MB - **无垃圾回收器** —— 稳定的亚毫秒级扫描延迟 - **BurntSushi 的 aho-corasick** —— ripgrep 级别的模式匹配 - **流式 Body 读取** —— 在下载过程中强制执行大小限制，而非下载后 - **逐跳重定向 SSRF 验证** —— 每次重定向都根据黑名单重新检查 - 同样的 38 个内置模式，同样的两阶段级联，同样的 SSRF 防护 ## 安装 ``` # Homebrew (macOS/Linux) brew install mark-liu/tap/webguard # Cargo (来自 crates.io) cargo install webguard # 从源代码构建 git clone https://github.com/mark-liu/webguard cd webguard cargo build --release # 位于 target/release/webguard 的 Binary ``` ## 使用方法 ``` # 添加到 Claude Code claude mcp add webguard -s user -- /path/to/webguard # 然后在 Claude Code 中使用 webguard_fetch 检索任意 URL ``` ## 架构 ``` Claude Code → webguard_fetch(url) │ ┌───────────┴───────────┐ │ 1. URL Validation │ SSRF prevention, scheme check │ 2. DNS Pinning │ Resolve + validate all IPs │ 3. HTTP Fetch │ HTTPS, streaming body, retry │ 4. Redirect Recheck │ Re-validate SSRF on every hop │ 5. Content Extraction │ HTML → markdown, strip scripts │ 6. Preprocessing │ Comment extraction, entity decode, │ │ base64/URL/hex decode, NFC normalize, │ │ zero-width strip │ 7. Stage 1: Patterns │ Aho-Corasick + regex (~0.3ms) │ ↳ Category filter │ Suppress per-domain categories │ ↳ Doc-path hints │ Auto-suppress for /docs/, /api/ │ 8. Stage 2: Heuristic │ Density, clustering, proximity │ 9. Decision │ PASS/WARN/BLOCK based on mode │ 10. Audit Log │ JSONL with pattern IDs + timing └───────────────────────┘ ``` ## 工具 ### `webguard_fetch` 获取 URL，带有 SSRF 防护和提示注入扫描。 | 参数 | 类型 | 必填 | 描述 | |-----------|------|----------|-------------| | `url` | string | yes | 要获取的 URL (http/https) | | `headers` | object | no | 自定义 HTTP 头 | | `raw` | boolean | no | 返回原始 HTML 而非 markdown | | `max_chars` | number | no | 将响应截断至 N 个字符 (0 = 不限) | **通过 (PASS)**：返回提取的 markdown 内容 + 元数据。 **警告 (WARN)** (mode=warn)：返回带有警告横幅的内容 + 元数据。 **拦截 (BLOCK)** (mode=block, 默认)：返回 `[BLOCKED: prompt injection detected]` + 元数据。零页面内容泄露。 ### `webguard_status` 返回服务器健康状况：版本、模式数量、模式、灵敏度、配置。 ### `webguard_report` 返回基于 JSONL 审计日志汇总的审计报告。 | 参数 | 类型 | 必填 | 描述 | |-----------|------|----------|-------------| | `days` | number | no | 包含的天数 (默认: 7) | ## 测试页面 用于验证检测的实时测试页面：https://mark-liu.github.io/webguard/test/ | 页面 | 预期结果 | 类别 | |------|----------|----------| | [clean.html](https://mark-liu.github.io/webguard/test/clean.html) | pass | — | | [inject.html](https://mark-liu.github.io/webguard/test/inject.html) | block | instruction-override (HTML 注释) | | [exfil.html](https://mark-liu.github.io/webguard/test/exfil.html) | block | exfil-instruction | | [encoded.html](https://mark-liu.github.io/webguard/test/encoded.html) | block | instruction-override (base64) | | [authority.html](https://mark-liu.github.io/webguard/test/authority.html) | block | authority-claim | ## 分类器 两阶段级联 —— 快速模式匹配，仅在需要时进行启发式评分。 ### 阶段 1：模式匹配 通过混合 Aho-Corasick (字面量，单次 O(N) 扫描) + 正则表达式 (结构化模式) 跨 8 个类别的 38 个内置模式。可从外部 YAML 文件加载额外模式。 | 类别 | 模式数 | 描述 | |----------|----------|-------------| | instruction-override | 7 | 试图覆盖或重置先前的指令 | | prompt-marker | 6 | 伪造的系统/指令分隔符和聊天标记 | | authority-claim | 6 | 虚假声称开发者、管理员或高级权限 | | exfil-instruction | 5 | 通过 URL 或隐藏元素进行数据渗出 | | output-manipulation | 4 | 试图约束或重定向模型输出 | | unicode-obfuscation | 4 | 零宽字符、RTL 重写、私用区 | | encoded-injection | 3 | Base64/eval/charcode 混淆载荷 | | delimiter-injection | 3 | 伪造的提示边界和角色注入 | 请参阅 [PATTERNS.md](PATTERNS.md) 获取包含示例和正则定义的完整模式列表。 ### 类别抑制 针对特定域名抑制特定模式类别，以消除误报： ``` domains: "*.linkedin.com": suppress: ["authority-claim"] "interactivebrokers.com": suppress: ["encoded-injection"] ``` 文档 URL (`/docs/`, `/api/`, `/reference/`, `/sdk/` 等) 自动抑制 `exfil-instruction` 和 `encoded-injection`。 ### 阶段 2：启发式评分 仅在阶段 1 发现非关键匹配时运行。因素： - **密度**：每 1000 字符的匹配数 (>2.0 = 1.2x 乘数) - **聚类**：200 字符内的匹配 (1.5x) - **邻近度**：authority-claim + instruction-override 临近 (1.5x) - **编码惩罚**：解码内容匹配 (1.3x) ### 灵敏度级别 | 级别 | 阈值 | 用例 | |-------|-----------|----------| | `low` | 2.0 | 文档、受信任来源 | | `medium` | 1.0 | 通用浏览 (默认) | | `high` | 0.5 | 不受信任来源 | ## SSRF 防护 在任何 TCP 连接之前进行所有检查： - 私有 IP 范围 (RFC 1918, loopback, link-local, 运营商级 NAT) - 云元数据 (AWS, GCP, Azure, Alibaba, Oracle, ECS) - 八进制 IP 检测 (`0177.0.0.01`) - URL 编码的主名拒绝 - URL authority 中的 `@` 拒绝 - DNS 固定 (解析一次，连接到解析后的 IP) - **在每次重定向跳转时重新验证** (最多 5 次) —— 防止 DNS 重绑定和重定向到内部网络绕过 ## 配置 `~/.config/webguard-mcp/config.yaml` —— 支持零配置运行 (合理的默认值)： ``` sensitivity: medium mode: block max_body_size: 5242880 request_timeout: 15s patterns_dir: "" domains: "docs.python.org": sensitivity: low timeout: 30s "*.github.com": sensitivity: low "*.linkedin.com": suppress: - authority-claim allowlist: [] blocklist: ["*.evil.com"] audit: enabled: true path: "" # default: ~/.local/share/webguard-mcp/audit.jsonl ``` ## 外部模式 通过将 YAML 文件放入 `patterns_dir` 目录来添加自定义检测模式： ``` # patterns.d/custom.yaml patterns: - id: custom-001 category: instruction-override severity: high type: literal value: "override all safety measures" ``` ## 开发 ``` cargo build # Build debug binary cargo test # Run all 77 tests cargo build --release # Build optimised binary cargo clippy # Lint cargo fmt --check # Format check ``` ## 项目结构 ``` webguard/ ├── src/ │ ├── main.rs # CLI entry, signal handling, MCP boot │ ├── server.rs # MCP tool handlers (fetch/status/report) │ ├── config.rs # YAML config, domain overrides │ ├── audit.rs # JSONL audit logger + reader │ ├── fetch/ │ │ ├── ssrf.rs # URL + IP validation, DNS pinning │ │ ├── client.rs # HTTP fetch, redirect recheck, retry │ │ └── extract.rs # HTML → markdown │ └── classify/ │ ├── engine.rs # Two-stage orchestrator │ ├── preprocess.rs # 8-step content preprocessing │ ├── stage1.rs # Aho-Corasick + regex scanner │ ├── stage2.rs # Heuristic scoring │ ├── patterns.rs # 38 built-in patterns │ ├── external.rs # External pattern YAML loader │ ├── encoding.rs # Base64/URL/hex/ROT13 decode │ └── result.rs # Result types ├── docs/test/ # GitHub Pages test pages ├── testdata/ # Test fixtures (14 JSON files) └── patterns.d/ # External pattern directory ``` ## 相关项目 - **[webguard-mcp](https://github.com/mark-liu/webguard-mcp)** —— 原始 Go 实现 (被本仓库取代) - **[mcpguard](https://github.com/mark-liu/mcpguard)** —— MCP stdio 代理，扫描来自任何 MCP 服务器 (Discord, Telegram 等) 的工具结果以检测提示注入 - **[snap](https://github.com/mark-liu/snap)** —— 用于 Playwright 快照的 MCP stdio 压缩代理 ## 许可证 MIT

标签：Aho-Corasick, AI Agent 安全, Claude Code 插件, DNS 反向解析, JSONLines, LLM 安全, MCP 服务器, Redis利用, Rust, SSRF 防护, WAF, Web 安全, 上下文窗口保护, 可视化界面, 恶意内容检测, 提示词注入防护, 时序数据库, 模式匹配, 流式处理, 红队防御, 网络安全, 网络抓取, 网络流量审计, 自动化资产收集, 通知系统, 隐私保护, 零信任, 零日漏洞检测, 静态二进制