Share
## https://sploitus.com/exploit?id=D314F45D-3E1B-5A0C-8F91-985C5BA6CA30
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ โฆ S W A R M H A W K A I โ
โ Autonomous Offensive Security Platform โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Autonomous external attack surface assessment.**
Recon โ Exploit Detection โ AI Synthesis โ Report. One command.
[](https://github.com/hastikdan/swarmhawk-cli/actions)
[](https://pypi.org/project/swarmhawk/)
[](https://www.python.org/)
[](LICENSE)
[](CONTRIBUTING.md)
---
## What is SwarmHawk?
SwarmHawk is an **open-source CLI** that chains together subdomain enumeration, vulnerability scanning, CVE enrichment, and AI-powered report generation into a single autonomous pipeline โ the kind of thing a senior pentester would spend days setting up manually.
```
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)
```
**No tools installed? No API keys?** Run `--mock` for a full demo with synthetic data in 10 seconds.
---
## Quickstart
```bash
pip install swarmhawk
# Demo โ runs on any machine, no tools required
swarmhawk scan --target acme-corp.com --mock
```
Open `./reports/*.html` in your browser. That's it.
---
## Demo Output
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โฆ 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
```
---
## Installation
### From PyPI (recommended)
```bash
pip install swarmhawk
```
### From source
```bash
git clone https://github.com/hastikdan/swarmhawk-cli.git
cd swarmhawk
pip install -e .
```
### Optional: Real scanning (live mode)
Install [ProjectDiscovery](https://projectdiscovery.io/) tools for live scans against real targets:
```bash
# macOS
brew install subfinder httpx nuclei
# Linux / any platform with 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
```
Without these tools, SwarmHawk automatically falls back to mock mode โ useful for demos and CI pipelines.
### Optional: PDF reports
```bash
pip install "swarmhawk[pdf]" # weasyprint
# or: sudo apt install wkhtmltopdf
```
### Optional: AI synthesis
```bash
export ANTHROPIC_API_KEY=sk-ant-... # Claude (recommended)
export OPENAI_API_KEY=sk-... # OpenAI (fallback)
```
Without an API key, SwarmHawk uses high-quality template-based synthesis.
---
## Usage
### Scan a target
```bash
# Mock mode โ demo with synthetic data, no tools required
swarmhawk scan --target acme-corp.com --mock
# Live scan โ requires 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 (required for live scans)
The scope ledger is a SHA-256 signed JSON file that proves you have written authorization to scan a target. It's your legal protection.
```bash
# Create scope for a new engagement
swarmhawk scope new \
--customer "ACME Corp" \
--domain acme-corp.com \
--authorized-by "Jane Smith, CISO" \
--days 30
# Verify a scope ledger's integrity
swarmhawk scope verify --file scopes/acme_corp.json
```
### Audit log
Every action is recorded in a tamper-evident SQLite database with SHA-256 hash chaining. Any modification to the log is detectable.
```bash
swarmhawk audit --file reports/audit_acme_corp_com.db
```
---
## Output Files
| File | Description |
|------|-------------|
| `*.html` | Full security report โ browser-ready, print to PDF |
| `*_findings.json` | Machine-readable findings โ SIEM/ticketing integration |
| `*_audit.json` | Tamper-evident audit log export |
| `*.pdf` | PDF report (requires weasyprint or wkhtmltopdf) |
### Findings JSON schema
```json
{
"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"]
}
]
}
```
---
## Architecture
```
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-Layer Validation Pipeline
SwarmHawk doesn't just dump raw Nuclei output. Every finding goes through:
| Layer | What it checks |
|-------|---------------|
| **L1 Syntactic** | Evidence field populated, matched URL present, no empty responses |
| **L2 Template quality** | `confirmed` or `high-confidence` templates only, filters noise |
| **L3 NVD/EPSS** | Cross-references with NIST NVD database, adds exploitation probability (EPSS) |
Confidence thresholds: **Critical/High โฅ 0.70**, **Medium+ โฅ 0.50**
### Tamper-Evident Audit Log
Every agent action is written to a SQLite database with SHA-256 hash chaining โ each entry's hash depends on all previous entries. Any post-hoc modification breaks the chain, which `swarmhawk audit` detects instantly.
---
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | No | Claude API โ recommended for best AI synthesis |
| `OPENAI_API_KEY` | No | OpenAI fallback |
| `NVD_API_KEY` | No | Raises NVD rate limit from 5/30s โ 50/30s |
---
## Running Tests
```bash
pip install -e ".[dev]"
pytest tests/ -v
```
27 tests across Scope, Audit, Recon, Exploit, Synthesis, and Integration. All pass with zero external dependencies (mock mode used in tests).
```bash
# With coverage
pytest tests/ -v --cov=swarmhawk --cov-report=term-missing
```
---
## Docker
```bash
# Build
docker build -t swarmhawk .
# Run a mock scan
docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-v $(pwd)/reports:/app/reports \
swarmhawk scan --target acme-corp.com --mock
# Real scan with scope file
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
Run SwarmHawk automatically on every PR โ findings posted as PR comments, pipeline fails on critical findings:
```yaml
# .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 }}
```
---
## Roadmap
| Version | Features |
|---------|----------|
| **v1.0** โ | RECON + EXPLOIT + AI SYNTHESIS + HTML/PDF reports |
| **v1.1** | Cloud IAM assessment (AWS/Azure/GCP via Stratus Red Team) |
| **v1.2** | Continuous scan mode + diff reports ("new since last week") |
| **v1.3** | REST API + webhook delivery for SIEM/ticketing integration |
| **v2.0** | Multi-agent swarm (LATERAL movement + INSIDER simulation) |
Community contributions accepted at any version. See [CONTRIBUTING.md](CONTRIBUTING.md).
---
## Contributing
SwarmHawk is community-driven. The most impactful contributions:
- **New vulnerability checks** โ extend `exploit.py` with custom detection logic
- **Nuclei template sets** โ curated template lists for specific tech stacks (WordPress, Laravel, SAP, etc.)
- **Recon sources** โ additional subdomain / asset discovery methods
- **Report templates** โ alternative HTML themes or output formats
- **Integrations** โ Jira, Slack, PagerDuty, Splunk output targets
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and the PR process.
---
## โ๏ธ SwarmHawk Cloud
The CLI is open-source. The [cloud platform](https://swarmhawk.ai) adds:
| Feature | CLI (OSS) | Cloud |
|---------|-----------|-------|
| Full pipeline | โ | โ |
| HTML/PDF reports | โ | โ |
| Continuous monitoring | โ | โ |
| Weekly diff alerts | โ | โ |
| Team access + SSO | โ | โ |
| Automated outreach pipeline | โ | โ |
| SOC2/ISO27001 evidence packs | โ | โ |
| Priority support | โ | โ |
[Start free โ](https://swarmhawk.ai)
---
## Legal
SwarmHawk is for **authorized security testing only**.
- Never run against systems without explicit written authorization
- Always create a signed scope ledger before any engagement โ it's your legal protection
- The tamper-evident audit log records every action for compliance and accountability
- By using this tool you agree to only scan systems you own or have written permission to test
---
## License
MIT โ see [LICENSE](LICENSE).
---
**[swarmhawk.ai](https://swarmhawk.ai)** ยท [Docs](https://swarmhawk.ai/docs) ยท [Cloud Platform](https://swarmhawk.ai) ยท [Report a Bug](https://github.com/hastikdan/swarmhawk-cli/issues)
*Built with โฅ by the SwarmHawk AI team and contributors.*