arjinexe/entropy-chaos

大多数 API 扫描器基于已知攻击模式的固定列表工作——例如 SQLi payload、常见的 HTTP headers、OWASP 词汇表。它们擅长发现它们已知的目标。但它们会遗漏那些特定于你 API 的东西：允许以负数总额结账的订单流程、对 GET 请求返回 401 但对 POST 请求不设防的 admin endpoint、在原型污染（prototype pollution）payload 下崩溃的 WebSocket handler。 Entropy 将你的 API schema 提供给 LLM，并要求其对你的特定 endpoints、数据模型和业务逻辑进行对抗性思考。LLM 生成针对其所见内容的攻击序列——然后 Entropy 执行这些序列，将响应与干净的基线进行对比，并仅报告那些看起来像实际 bug 的偏差。 它适用于 OpenAPI specs、GraphQL schemas，或者根本没有 spec 的情况（它会爬取目标并自行推断 endpoints）。 ## 安装 ``` pip install entropy-chaos ``` 需要 Python 3.10+。唯一必须的依赖是 PyYAML —— 其他所有依赖都是可选的。 ## 基本用法 ``` # 模拟攻击而不发送真实请求（可在任何地方安全运行） entropy run --spec openapi.yaml --target http://localhost:8000 # 实际发送请求 entropy run --spec openapi.yaml --target http://localhost:8000 --live # 无 spec 文件 — 让其自行发现端点 entropy run --target https://api.example.com --discover --live # 使用真实 LLM 以生成更好的攻击 entropy run --spec api.yaml --llm anthropic --live # ANTHROPIC_API_KEY 自动从环境中获取 ``` ## 工作原理 **攻击生成。** Entropy 解析你的 schema，构建 API 数据模型和认证结构的图景，然后提示 LLM 生成攻击序列。LLM 的输出不仅仅是 payload —— 而是多步骤场景（“以用户 A 身份认证，然后尝试使用步骤 1 中的会话 token 访问用户 B 的资源”）。 **角色 (Personas)。** 五种攻击者原型并行运行，每种都有不同的威胁模型： | 角色 | 测试内容 | |---------|---------------| | `malicious_insider` | 认证滥用 — IDOR、批量赋值 (mass assignment)、权限提升 | | `impatient_consumer` | 时序问题 — 竞态条件 (race conditions)、双花攻击 (double-spend)、重试循环 | | `bot_swarm` | 基于流量的问题 — 速率限制 (rate limiting)、资源耗尽 | | `confused_user` | 边缘情况 — 类型混淆、状态机绕过、意外输入 | | `penetration_tester` | 经典漏洞 — 注入、认证绕过、SSRF、XXE | **基线对比 (Baseline diffing)。** 在发送攻击 payload 之前，Entropy 会向同一个 endpoint 发送一个正常请求并记录响应。只有当攻击响应与基线有显著差异时——不同的状态码、body 中出现新字段、延迟显著增加——发现才会被标记。这消除了大部分来自已返回错误的 endpoint 的噪音。 **历史记录。** 每次运行都保存在 `~/.entropy/history.db`。在 CI 中，如果针对同一目标发现了比上次运行更多的新问题，Entropy 将以非零状态退出，这使其可用作回归检测门禁。 ## LLM 后端 Entropy 适用于大多数 LLM API。设置相关的 env var 并传递 `--llm `： | Backend | Env var | |---------|---------| | `anthropic` | `ANTHROPIC_API_KEY` | | `openai` | `OPENAI_API_KEY` | | `gemini` | `GEMINI_API_KEY` | | `mistral` | `MISTRAL_API_KEY` | | `groq` | `GROQ_API_KEY` | | `ollama` | *(无 key — 本地运行)* | | `huggingface` | `HF_API_KEY` | | `mock` | *(无 key — 确定性，用于 CI/测试)* | `mock` 后端无需任何 API 调用即可生成外观逼真的攻击场景。这是测试套件所使用的，它足以在接入真实 LLM 之前验证你的 pipeline 设置。 ## v0.3 功能 ### Endpoint 发现 如果你没有 spec 文件（或不想维护），传递 `--discover`： ``` entropy run --target https://api.example.com --discover --live ``` 它会检查 `robots.txt`，爬取链接的 JS 文件以查找 `fetch()`/`axios` 调用，探测 110 多个常见 API 路径，并在通常位置查找 OpenAPI/Swagger specs。其发现结果会像 spec 一样被输入到攻击生成 pipeline 中。 ``` # 仅发现，无 fuzzing entropy discover --target https://api.example.com ``` ### Rate limit 检测 ``` # 在扫描期间自动运行，或独立运行： entropy ratelimit --url https://api.example.com/login --max-probes 60 ``` 发送请求直到遇到 429（或耗尽探测预算），然后测试常见的绕过技术：`X-Forwarded-For` 轮换、`X-Real-IP`、带斜杠的路径变体。缺失的 rate limits 被报告为 HIGH；可绕过的被报告为 CRITICAL。 ### 差异测试 比较两个目标并找出它们的不同之处： ``` entropy compare \ --spec openapi.yaml \ --target-a https://api.example.com/v1 \ --target-b https://api.example.com/v2 ``` 标记状态码更改、移除的响应字段和显著的延迟回归。适用于在发布前捕获破坏性更改，或验证 staging 环境是否与 prod 匹配。 ### 自定义角色 内置角色涵盖一般威胁模型。如果你想模拟针对你的应用程序的特定情况： ``` entropy persona template > finance-insider.yaml # 编辑它 entropy persona validate finance-insider.yaml entropy run --spec api.yaml --custom-persona finance-insider.yaml --live ``` ``` name: finance-insider auth_level: read_write attack_focus: - privilege_escalation - idor endpoints_whitelist: - /api/reports - /api/export payload_overrides: role: admin is_admin: true ``` ### 仪表板 ``` entropy run --spec api.yaml --dashboard --live # http://localhost:8080 ``` 通过 Server-Sent Events 实时推送发现结果。无外部 JS 依赖。 ### WebSocket 模糊测试 ``` entropy run --spec api.yaml --ws wss://api.example.com/ws --live ``` 15 种 payload 涵盖注入、原型污染 (prototype pollution)、超大消息和类型混淆。使用标准库 `ssl`/`socket` —— 无需 `websockets` 包。 ### Proxy 集成 ``` # 通过 Burp Suite 路由 entropy run --spec api.yaml --proxy http://127.0.0.1:8080 --no-verify-ssl --live # Entropy 作为拦截代理（在传输中修改请求） entropy proxy --port 8888 ``` ### Watch 模式 ``` entropy run --spec api.yaml --watch --watch-interval 300 --live entropy run --spec api.yaml --watch --watch-file api.yaml --live # re-run on spec changes ``` ## 输出格式 ``` entropy run --spec api.yaml --live # Markdown + JSON + HTML (default) entropy run --spec api.yaml --sarif results.sarif --live # SARIF for GitHub Code Scanning ``` 所有运行都会生成 Markdown 摘要、机器可读的 JSON 报告以及包含严重性细分的 HTML 报告。JSON 输出版本间保持稳定。 ## 扫描配置 ``` entropy run --spec api.yaml --profile quick --live # ~2min, critical only entropy run --spec api.yaml --profile full --live # thorough, all personas ``` | Profile | Personas | 失败阈值 | Use case | |---------|----------|----------------|----------| | `quick` | 2 | critical | Pre-commit / 快速反馈 | | `standard` | 3 | high | PR gate (默认) | | `full` | 5 | high | 每日构建 / 预发布 | | `stealth` | 2 | critical | 低噪音 prod 测试 | | `ci` | 3 | high | CI pipelines | ## CI 集成 ### GitHub Actions ``` - name: Install entropy run: pip install entropy-chaos - name: Run scan run: | entropy run \ --spec openapi.yaml \ --target ${{ env.API_URL }} \ --llm anthropic \ --profile ci \ --sarif results.sarif \ --live env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - name: Upload to Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: results.sarif ``` ### GitLab CI ``` entropy: image: python:3.11 script: - pip install entropy-chaos - entropy run --spec openapi.yaml --target $API_URL --llm groq --profile ci --live artifacts: reports: junit: entropy-report/junit.xml ``` ## 配置文件 与其每次都传递 flags，不如在项目根目录下放置一个 `entropy.yml`： ``` entropy run # picks up entropy.yml automatically entropy run --config path/to/entropy.yml ``` ``` target: http://localhost:8000 spec: openapi.yaml llm: backend: anthropic scan: live: true profile: standard baseline_diff: true rate_limit_check: true output: dir: entropy-report sarif: results.sarif fail_on: high # alerts: # slack_webhook: https://hooks.slack.com/... ``` 生成一个带有完整注释的模板： ``` entropy report config-template > entropy.yml ``` ## 所有命令 ``` entropy run Run a scan entropy compare Compare two targets (v1 vs v2, prod vs staging) entropy discover Probe a target for endpoints without a spec entropy ratelimit Test rate limiting on a specific URL entropy history Browse previous runs (list / trend / compare) entropy persona Manage custom personas (template / validate) entropy shell Interactive REPL entropy proxy HTTP interception proxy entropy backends List available LLM backends entropy profiles List scan profiles entropy owasp List OWASP Top 10 scenarios ``` 完整 flag 参考：`entropy run --help` ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 ## 贡献 [CONTRIBUTING.md](CONTRIBUTING.md) ## 安全 请私下报告漏洞 — 详见 [SECURITY.md](SECURITY.md)。

标签：API安全测试, API网关安全, CISA项目, DevSecOps, DLL 劫持, GraphQL, IP 地址批量处理, LLM, OpenAPI, Python, SQL注入检测, Unmanaged PE, 上游代理, 人工智能安全, 合规性, 图数据库, 大语言模型, 密码管理, 攻击场景生成, 数据展示, 无后门, 混沌工程, 红队, 网络安全, 自动化安全审计, 逆向工具, 逻辑漏洞检测, 隐私保护