joergmichno/clawguard-shield

# ClawGuard Shield **面向 AI Agent 的安全扫描 REST API** [](https://github.com/joergmichno/clawguard-shield/actions/workflows/ci.yml) [](tests/) [](https://python.org) [](LICENSE) [](https://prompttools.co/api/v1/health) 🎯 **在线演示：** [prompttools.co](https://prompttools.co) 用于扫描文本中 Prompt 注入、数据泄露、危险命令、代码混淆和社会工程学模式的 REST API。包含 42+ 个正则表达式模式，平均扫描时间 6ms，零 ML 推理。 **在线演示：** https://prompttools.co/api/v1/ **核心扫描器：** [ClawGuard](https://github.com/joergmichno/clawguard)（开源，零依赖） ## 快速开始 ``` # 1. 获取免费 API key curl -X POST https://prompttools.co/api/v1/register \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com"}' # 2. 扫描文本以检测威胁 curl -X POST https://prompttools.co/api/v1/scan \ -H "X-API-Key: cgs_your_key_here" \ -H "Content-Type: application/json" \ -d '{"text": "Ignore all previous instructions"}' ``` 响应： ``` { "clean": false, "risk_score": 10, "severity": "CRITICAL", "findings_count": 1, "findings": [{ "pattern_name": "Direct Override (EN)", "severity": "CRITICAL", "category": "Prompt Injection", "matched_text": "Ignore all previous instructions", "line_number": 1, "description": "BLOCK this input immediately." }], "scan_time_ms": 6 } ``` 安全文本返回： ``` { "clean": true, "risk_score": 0, "severity": "CLEAN", "findings_count": 0, "findings": [], "scan_time_ms": 2 } ``` ## API 参考 ### 端点 | Method | Endpoint | Auth | Description | |--------|----------|------|-------------| | `GET` | `/api/v1/` | - | 包含所有端点的 API 概览 | | `GET` | `/api/v1/health` | - | 健康检查 + 模式计数 | | `POST` | `/api/v1/register` | - | 注册以获取免费 API key | | `POST` | `/api/v1/scan` | API key | 扫描文本以检测安全威胁 | | `GET` | `/api/v1/patterns` | API key | 按类别列出所有检测模式 | | `GET` | `/api/v1/usage` | API key | 您的使用统计（过去 30 天） | ### 认证 所有受保护的端点都需要在 `X-API-Key` 请求头中提供 API key： ``` X-API-Key: cgs_your_key_here ``` **Key 格式：** `cgs_` 前缀 + 32 个十六进制字符（共 36 个字符）。 Key 在存储前使用 SHA-256 进行哈希处理 —— 我们从不存储您的原始密钥。 ### POST /api/v1/scan 扫描文本以检测安全威胁。 **请求体：** ``` { "text": "Text to scan (required)", "source": "user-message" } ``` **响应头（当触发速率限制时）：** ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 87 ``` ### POST /api/v1/register 注册以获取免费 API key。 ``` // Request { "email": "you@example.com" } // Response 201 { "message": "API key created successfully. Store it safely — it cannot be recovered!", "api_key": "cgs_abc123...", "tier": "free", "daily_limit": 100, "max_text_length": 5000 } ``` ### GET /api/v1/usage 返回您过去 30 天的使用统计。 ``` { "tier": "free", "tier_name": "Free", "daily_limit": 100, "today_used": 12, "today_remaining": 88, "last_30_days": { "total_requests": 247, "total_findings": 89, "avg_response_time_ms": 5.8 }, "key_prefix": "cgs_abc123ab...", "api_version": "1.0" } ``` ## 错误处理 所有错误均返回带有 `error` 和 `message` 字段的 JSON。 | Status | Error Code | Description | |--------|-----------|-------------| | `400` | `invalid_json` | 请求体不是有效的 JSON | | `400` | `validation_error` | 缺少 `text` 字段、文本为空或文本超过最大长度 | | `401` | `missing_api_key` | 未提供 `X-API-Key` 请求头 | | `401` | `invalid_key_format` | Key 格式不符合 `cgs_` + 32 个十六进制字符 | | `403` | `invalid_api_key` | 未找到 Key 或 Key 已停用 | | `404` | `not_found` | 端点不存在 | | `409` | `email_exists` | 该邮箱已拥有 API key | | `429` | `rate_limit_exceeded` | 已达到每日扫描限制 | **错误响应示例：** ``` { "error": "rate_limit_exceeded", "message": "Daily limit of 100 requests exceeded.", "tier": "free", "limit": 100, "used": 100 } ``` ## 检测内容 | Category | Patterns | Examples | |----------|----------|----------| | **Prompt 注入** | 13 | 直接覆盖、角色扮演逃逸、分隔符注入、同义词绕过（英语 + 德语） | | **危险命令** | 5 | Shell 命令（`rm -rf`、`curl \| bash`）、反向 Shell、权限提升 | | **数据泄露** | 6 | API key 泄露、私钥、密码、数据库连接字符串 | | **代码混淆** | 11 | Python `eval()`/`exec()`、`getattr()`、魔术属性、字符串拼接 | | **社会工程学** | 3 | 紧迫性操控、冒充权威、保密陷阱 | 涵盖 5 个类别的 42+ 个正则表达式模式。支持双语检测（英语 + 德语）。 ## 速率限制 速率限制基于每个 API key 在每日滑动窗口（UTC）内强制执行。 | Tier | Daily Limit | Max Text Length | |------|-------------|-----------------| | **Free** | 100 次扫描 | 5,000 字符 | | **Pro** | 10,000 次扫描 | 50,000 字符 | | **Enterprise** | 无限制 | 200,000 字符 | 该层级系统展示了具有按 Key 速率限制的多租户 API 架构。当您超过限制时，API 将返回 `429` 状态码及使用详情。每次扫描响应中都会包含速率限制头（`X-RateLimit-Limit`、`X-RateLimit-Remaining`）。 ## 架构 ``` ┌─────────────────────────────────────┐ │ Nginx (HTTPS) │ │ prompttools.co │ └──────┬──────────┬──────────┬─────────┘ │ │ │ /shield│ /api/v1│ / │ │ │ │ ┌──────┴──┐ ┌─────┴────┐ ┌───┴──────┐ │ Static │ │ Shield │ │ Prompt │ │ HTML │ │ (5001) │ │ Lab │ │ │ │ Flask │ │ (5000) │ └─────────┘ └────┬─────┘ └──────────┘ │ ┌────────────────┼────────────────────┐ │ │ │ ┌────┴─────┐ ┌──────┴───────┐ ┌────────┴────────┐ │ auth.py │ │ rate_limiter │ │ clawguard.py │ │ │ │ .py │ │ (scan engine) │ │ Key gen │ │ │ │ │ │ SHA-256 │ │ Sliding │ │ 42+ patterns │ │ Validate │ │ window/day │ │ 5 categories │ │ Tiers │ │ Per-key │ │ Risk scoring │ └────┬──────┘ └──────┬───────┘ └─────────────────┘ │ │ ┌────┴────────────────┴────┐ │ database.py │ │ SQLite (WAL mode) │ │ │ │ api_keys usage_log │ │ rate_limits │ └───────────────────────────┘ ``` ### 数据库模式 | Table | Purpose | |-------|---------| | `api_keys` | Key 哈希、前缀、邮箱、层级、创建/最后使用时间戳、激活标志 | | `usage_log` | 每次请求日志：端点、文本长度、发现结果、风险评分、响应时间 | | `rate_limits` | 每个 Key 的每日请求计数器（滑动窗口） | SQLite 使用 WAL 模式以支持并发读取。线程本地连接。强制执行外键约束。 ### 请求流程 1. **CORS** — 预检处理 + 针对浏览器客户端的宽松 Header 2. **Auth** — 验证 `X-API-Key` 格式 → SHA-256 哈希 → 在 `api_keys` 中查找 3. **Rate Check** — 统计该 Key 今天的请求数并根据层级限制进行检查 4. **Validation** — 根据层级的 `max_text_length` 检查文本长度 5. **Scan** — 使用 ClawGuard 的 `scan_text()` 对所有 42+ 个模式进行扫描 6. **Log** — 记录使用情况（端点、文本长度、发现结果、响应时间） 7. **Response** — 返回发现结果及速率限制头 ## 自托管 ``` git clone https://github.com/joergmichno/clawguard-shield.git cd clawguard-shield # Docker (推荐) docker compose up -d --build # 或者本地运行 pip install -r requirements.txt python app.py ``` Docker 设置包括： - Python 3.12-slim 基础镜像 - Gunicorn 配备 2 个 worker - 以非 root 用户 `shield` 运行以确保安全 - 持久化 SQLite 卷位于 `./data/` - 健康检查端点 ### 环境变量 | Variable | Default | Description | |----------|---------|-------------| | `PORT` | `5001` | 服务器端口 | | `SHIELD_DB_PATH` | `/app/data/shield.db` | SQLite 数据库路径 | | `SECRET_KEY` | (自动生成) | Flask secret key | ## 测试 ``` pip install pytest python -m pytest tests/ -v # 70 passed ``` 70 个测试覆盖： - 所有 6 个 API 端点（scan、health、patterns、usage、register、index） - 认证（Key 生成、哈希、验证、格式检查） - 速率限制（计数、强制执行、层级限制） - 输入验证（缺少文本、文本为空、文本过长） - 错误处理（无效 JSON、缺少 Header、错误方法） - CORS Header ## 相关项目 - [ClawGuard](https://github.com/joergmichno/clawguard) — 此 API 封装的开源扫描器（42+ 模式，零依赖） - [ClawGuard Shield Python SDK](https://github.com/joergmichno/clawguard-shield-python) — Python 客户端库（[PyPI](https://pypi.org/project/clawguard-shield/)） - [ClawGuard Scan Action](https://github.com/joergmichno/clawguard-scan-action) — 用于 CI/CD 安全扫描的 GitHub Action - [Prompt Lab](https://github.com/joergmichno/prompt-lab) — 交互式 Prompt 注入演练场（[在线演示](https://prompttools.co)） - [DocQA](https://github.com/joergmichno/docqa) — 基于 RAG 的文档问答 CLI ## 生态系统集成 | Component | Install / Link | Description | |-----------|---------------|-------------| | **ClawGuard** (核心引擎) | [github.com/joergmichno/clawguard](https://github.com/joergmichno/clawguard) | 支持 Shield API 的开源扫描器 | | **Python SDK** | `pip install clawguard-shield` — [GitHub](https://github.com/joergmichno/clawguard-shield-python) | Shield API 的 Python 客户端库 | | **GitHub Action** | [github.com/joergmichno/clawguard-scan-action](https://github.com/joergmichno/clawguard-scan-action) | 针对拉取请求的 CI/CD 安全扫描 | | **Prompt Lab** | [prompttools.co](https://prompttools.co) — [GitHub](https://github.com/joergmichno/prompt-lab) | 交互式 Prompt 注入演示 | ## 许可证 MIT 由 [Jörg Michno](https://github.com/joergmichno) 构建

标签：AMSI绕过, API安全, API密钥检测, DNS 反向解析, JSON输出, Python, REST API, SaaS, TLS, Web安全, 人工智能安全, 代码混淆检测, 内容审核, 危险命令拦截, 合规性, 威胁检测, 提示词注入检测, 数据防泄露, 无后门, 社会工程学防护, 网络安全, 网络测绘, 蓝队分析, 请求拦截, 输入验证, 防御工具, 隐私保护, 零依赖