hastikdan/swarmhawk-cli

## 什么是 SwarmHawk？ SwarmHawk 是一个**开源 CLI**，它将子域名枚举、漏洞扫描、CVE 富化以及 AI 驱动的报告生成串联成一个单一的自主 pipeline —— 这通常是高级渗透测试人员需要花费数天时间手动搭建的工作流程。 ``` Target domain ↓ Subdomain enumeration (subfinder) ↓ Live asset probing (httpx + IP enrichment) ↓ Vulnerability scanning (8,000+ Nuclei templates) ↓ 3-layer validation (syntactic → template quality → NVD/EPSS) ↓ AI synthesis (business impact + remediation via Claude/OpenAI) ↓ Professional HTML/PDF report ↓ Tamper-evident audit log (SHA-256 hash chain) ``` **没有安装工具？没有 API key？** 运行 `--mock` 即可在 10 秒内获得一个包含合成数据的完整演示。 ## 快速开始 ``` pip install swarmhawk # 演示 — 在任意机器上运行，无需工具 swarmhawk scan --target acme-corp.com --mock ``` 在浏览器中打开 `./reports/*.html`。就这么简单。 ## 演示输出 ``` ╔═══════════════════════════════════════════════════════╗ ║ ✦ S W A R M H A W K A I — MVP v1.0.0 ║ ╚═══════════════════════════════════════════════════════╝ ────────────────────────────────────────────────────── PHASE 1 ▸ RECONNAISSANCE ────────────────────────────────────────────────────── 09:14:01 ⬡ Enumerating subdomains... 09:14:03 ✓ 14 live assets discovered → acme-corp.com nginx/1.18 → api.acme-corp.com Apache/2.4.51 → admin.acme-corp.com PHP/8.1 → dev.acme-corp.com (no server header) → + 10 more... ────────────────────────────────────────────────────── PHASE 2 ▸ EXPLOIT DETECTION ────────────────────────────────────────────────────── 09:14:08 ◈ Running vulnerability templates... 09:14:22 ✓ 6 findings validated (2 critical, 2 high) [CRITICAL ] PHP CGI RCE (CVE-2024-4577) CVSS 9.8 [CRITICAL ] Apache Path Traversal RCE CVSS 9.8 [HIGH ] Web Server Misconfiguration CVSS 7.5 [HIGH ] Exposed Admin Panel CVSS 7.2 [MEDIUM ] Missing Security Headers CVSS 5.3 [LOW ] Server Version Disclosure CVSS 3.1 ────────────────────────────────────────────────────── PHASE 3 ▸ AI SYNTHESIS ────────────────────────────────────────────────────── 09:14:23 ✦ Enriching findings with business context... 09:14:31 ✓ Executive summary generated ────────────────────────────────────────────────────── PHASE 4 ▸ REPORT GENERATION ────────────────────────────────────────────────────── ══════════════════════════════════════════════════════ ✦ MISSION COMPLETE ══════════════════════════════════════════════════════ Target: acme-corp.com Assets scanned: 14 Duration: 0m 31s Findings: 2 critical 2 high 2 other Audit chain: ✓ VERIFIED Reports saved: → HTML reports/swarmhawk_acme-corp_com_20260319_091401.html → JSON reports/swarmhawk_acme-corp_com_20260319_091401_findings.json → Audit reports/swarmhawk_acme-corp_com_20260319_091401_audit.json ``` ## 安装 ### 通过 PyPI（推荐） ``` pip install swarmhawk ``` ### 从源码安装 ``` git clone https://github.com/hastikdan/swarmhawk-cli.git cd swarmhawk pip install -e . ``` ### 可选：真实扫描（实时模式） 安装 [ProjectDiscovery](https://projectdiscovery.io/) 工具以对真实目标进行实时扫描： ``` # macOS brew install subfinder httpx nuclei # Linux / 任何安装了 Go 的平台 go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest ``` 如果没有这些工具，SwarmHawk 会自动回退到 mock 模式 —— 适用于演示和 CI pipeline。 ### 可选：PDF 报告 ``` pip install "swarmhawk[pdf]" # weasyprint # 或：sudo apt install wkhtmltopdf ``` ### 可选：AI 综合 ``` export ANTHROPIC_API_KEY=sk-ant-... # Claude (recommended) export OPENAI_API_KEY=sk-... # OpenAI (fallback) ``` 如果没有 API key，SwarmHawk 会使用高质量的基于模板的综合方式。 ## 用法 ### 扫描目标 ``` # Mock 模式 — 使用合成数据进行演示，无需工具 swarmhawk scan --target acme-corp.com --mock # Live scan — 需要 subfinder, httpx, nuclei swarmhawk scan --target acme-corp.com # Full production scan — scope file + AI + NVD enrichment swarmhawk scan \ --target acme-corp.com \ --scope scopes/acme.json \ --nvd-key $NVD_API_KEY \ --output ./reports/acme-2026-q1 ``` ### Scope ledger（实时扫描必需） Scope ledger 是一个经过 SHA-256 签名的 JSON 文件，用于证明你拥有扫描目标的书面授权。这是你的法律保护。 ``` # 为新项目创建 scope swarmhawk scope new \ --customer "ACME Corp" \ --domain acme-corp.com \ --authorized-by "Jane Smith, CISO" \ --days 30 # 验证 scope ledger 的完整性 swarmhawk scope verify --file scopes/acme_corp.json ``` ### Audit log（审计日志） 每个操作都会记录在一个具有 SHA-256 哈希链的防篡改 SQLite 数据库中。对日志的任何修改都是可检测的。 ``` swarmhawk audit --file reports/audit_acme_corp_com.db ``` ## 输出文件 | File | Description | |------|-------------| | `*.html` | 完整安全报告 —— 浏览器可直接查看，可打印为 PDF | | `*_findings.json` | 机器可读的发现结果 —— 用于 SIEM/工单系统集成 | | `*_audit.json` | 防篡改审计日志导出 | | `*.pdf` | PDF 报告（需要 weasyprint 或 wkhtmltopdf） | ### Findings JSON schema ``` { "generated_at": "2026-03-19T09:14:31Z", "target": "acme-corp.com", "summary": { "total": 6, "by_severity": { "critical": 2, "high": 2, "medium": 1, "low": 1 } }, "findings": [ { "id": "SWH-0001", "title": "PHP CGI RCE", "severity": "critical", "cvss_score": 9.8, "cve_id": "CVE-2024-4577", "epss_score": 0.94, "asset": "https://api.acme-corp.com", "business_impact": "An unauthenticated attacker can execute arbitrary commands...", "remediation": "1. Update PHP to 8.1.29+\n2. Disable CGI handler...", "raw_evidence": "HTTP/1.1 200 OK\nX-Powered-By: PHP/8.1.0...", "validation_notes": ["✓ Syntactic check passed", "✓ NVD confirmed", "✓ EPSS 0.94"] } ] } ``` ## 架构 ``` swarmhawk/ ├── scope.py SHA-256 signed authorization ledger ├── audit.py Tamper-evident hash-chained audit log (SQLite) ├── recon.py RECON agent — subfinder + httpx + IP enrichment ├── exploit.py EXPLOIT agent — Nuclei + 3-layer validation + NVD/EPSS ├── synthesis.py SYNTHESIS agent — Claude/OpenAI business context ├── report.py Report generator — HTML + PDF └── cli.py CLI entry point ``` ### 3 层验证 Pipeline SwarmHawk 不仅仅是输出原始的 Nuclei 结果。每个发现都会经过： | Layer | What it checks | |-------|---------------| | **L1 语法层** | 证据字段已填充，匹配的 URL 存在，无空响应 | | **L2 模板质量** | 仅限 `confirmed` 或 `high-confidence` 模板，过滤噪声 | | **L3 NVD/EPSS** | 与 NIST NVD 数据库交叉引用，添加利用概率 (EPSS) | 置信度阈值：**Critical/High ≥ 0.70**，**Medium+ ≥ 0.50** ### 防篡改审计日志 每个 agent 操作都会写入带有 SHA-256 哈希链的 SQLite 数据库 —— 每个条目的哈希值依赖于之前所有的条目。任何事后修改都会破坏链条，`swarmhawk audit` 能立即检测到这一点。 ## 环境变量 | Variable | Required | Description | |----------|----------|-------------| | `ANTHROPIC_API_KEY` | No | Claude API —— 推荐用于最佳的 AI 综合 | | `OPENAI_API_KEY` | No | OpenAI 备选方案 | | `NVD_API_KEY` | No | 将 NVD 速率限制从 5/30s 提升至 50/30s | ## 运行测试 ``` pip install -e ".[dev]" pytest tests/ -v ``` 涵盖 Scope、Audit、Recon、Exploit、Synthesis 和 Integration 的 27 个测试。在零外部依赖的情况下全部通过（测试中使用 mock 模式）。 ``` # 带覆盖率 pytest tests/ -v --cov=swarmhawk --cov-report=term-missing ``` ## Docker ``` # 构建 docker build -t swarmhawk . # 运行 Mock scan docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -v $(pwd)/reports:/app/reports \ swarmhawk scan --target acme-corp.com --mock # 带 scope file 的 Real scan docker run \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -e NVD_API_KEY=$NVD_API_KEY \ -v $(pwd)/reports:/app/reports \ -v $(pwd)/scopes:/app/scopes \ swarmhawk scan --target acme-corp.com --scope /app/scopes/acme.json ``` ## GitHub Action 在每次 PR 时自动运行 SwarmHawk —— 发现结果将作为 PR 评论发布，若出现关键发现则 pipeline 失败： ``` # .github/workflows/security.yml name: Security Scan on: pull_request: branches: [main] schedule: - cron: '0 8 * * 1' # Every Monday 08:00 UTC permissions: contents: read pull-requests: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: hastikdan/swarmhawk-cli-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} fail_on_critical: 'true' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` ## 路线图 | Version | Features | |---------|----------| | **v1.0** ✓ | RECON + EXPLOIT + AI SYNTHESIS + HTML/PDF 报告 | | **v1.1** | 云 IAM 评估（通过 Stratus Red Team 支持 AWS/Azure/GCP） | | **v1.2** | 持续扫描模式 + 差异报告（“自上周以来的新内容”） | | **v1.3** | REST API + webhook 交付，用于 SIEM/工单系统集成 | | **v2.0** | 多 agent swarm（横向移动 + 内部威胁模拟） | 接受任何版本社区贡献。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 贡献 SwarmHawk 由社区驱动。最有影响力的贡献包括： - **新漏洞检查** —— 用自定义检测逻辑扩展 `exploit.py` - **Nuclei 模板集** —— 针对特定技术栈（WordPress、Laravel、SAP 等）的精选模板列表 - **侦察来源** —— 额外的子域名/资产发现方法 - **报告模板** —— 替代的 HTML 主题或输出格式 - **集成** —— Jira、Slack、PagerDuty、Splunk 输出目标 设置、约定和 PR 流程请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## ☁️ SwarmHawk Cloud CLI 是开源的。[云平台](https://swarmhawk.com)增加了： | Feature | CLI (OSS) | Cloud | |---------|-----------|-------| | 完整 pipeline | ✓ | ✓ | | HTML/PDF 报告 | ✓ | ✓ | | 持续监控 | — | ✓ | | 每周差异警报 | — | ✓ | | 团队访问 + SSO | — | ✓ | | 自动化外联 pipeline | — | ✓ | | SOC2/ISO27001 证据包 | — | ✓ | | 优先支持 | — | ✓ | [免费开始 →](https://swarmhawk.com) ## 法律声明 SwarmHawk 仅用于**授权的安全测试**。 - 切勿在未经明确书面授权的情况下对系统运行 - 在任何行动前始终创建已签名的 scope ledger —— 这是你的法律保护 - 防篡改审计日志会记录每一项操作，以确保合规性和问责制 - 使用此工具即表示你同意仅扫描你拥有或拥有书面测试许可的系统 ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。

标签：AI安全报告, ASM, CVE分析, EASM, GitHub, Google, LFI本地文件包含, Nuclei, Python, 外部攻击面评估, 威胁情报, 子域名枚举, 安全合规, 密码管理, 开发者工具, 开源安全工具, 插件系统, 无后门, 系统安全, 网络代理, 网络安全, 网络安全审计, 自动化渗透测试, 请求拦截, 运行时操纵, 逆向工具, 逆向工程平台, 隐私保护