17 Exploit Agents: SQLi, XSS, CMDI, CSRF, IDOR, AuthBypass, SSRF, LFI, SSTI, OpenRedirect, CORS, JWT, XXE, FileUpload, Deserialization, HTTPSmuggling + WebCrawler
Recursive Swarm (ADR-004): Generation-based re-scanning with 6 trigger types — automatically re-scans with discovered credentials
Pre-flight Authentication: 5 auth methods (FormBased, JWT, Cookie, JSON, Custom) via --auth config.json
Self-Learning Intelligence (ADR-005): SONA-backed payload learning, adaptive WAF evasion, rate limiting optimization
Semantic Deduplication: Two-level dedup (canonical key + HNSW vector similarity) catches near-duplicate findings
Crown Jewel ML Matching: Learns new crown jewel patterns beyond the 18 built-in regexes
Real HNSW Index: Replaced HashMap stub with actual approximate nearest neighbor search
Checkpoint-on-Detection: All 17 agents preserve findings before deep exploitation — no data loss on timeout
UTF-8 Safety: Fixed byte-slicing panics across 20 files (28 sites)
OCSF 1.1.0 Reports: Industry-standard vulnerability reports with generation lineage tracking

Installation

npm install -g swarmhack-cli

Or use npx:

npx swarmhack-cli --help

Configuration

SwarmHack includes a default configuration file (config/swarmhack.yaml) that is automatically used when running commands. You can override it by:

Using your own config file:

swarmhack spawn --config /path/to/your/config.yaml --target "http://example.com"

Creating a local config in your project: Place config/swarmhack.yaml in your project root - it will be automatically detected.
Customizing the bundled config: Copy the bundled config to your project and modify it:
```
cp $(npm root -g)/swarmhack-cli/config/swarmhack.yaml ./config/
```

CLI Usage

# Run SQL injection scan (local mode - default)
swarmhack spawn --agents sqli \
  --target "http://example.com" \
  --customer "your-customer" \
  --token "your-token"

# Run in Docker mode (isolated execution)
swarmhack spawn --agents sqli \
  --target "http://example.com" \
  --runtime docker \
  --docker-image "swarmhack/pentest:latest"

# Run multiple agents
swarmhack spawn --agents sqli,xss,csrf \
  --target "http://example.com" \
  --customer "your-customer" \
  --token "your-token"

# Run in Docker with custom image and volumes
swarmhack spawn --agents sqli \
  --target "http://example.com" \
  --runtime docker \
  --docker-image "myregistry/swarmhack:v1.0" \
  --docker-volume "/host/reports:/app/reports"

# List available agents
swarmhack agents list

# Check system health
swarmhack doctor

Runtime Modes

SwarmHack supports two runtime modes:

Mode	Description	Use Case
`local`	Run directly on host system	Development, CI/CD with pre-installed tools
`docker`	Run inside Docker containers	Production, isolated execution, portable

CLI Runtime Options

Option	Description
`--runtime`	Runtime mode: `local` (default) or `docker`
`--docker-image`	Docker image to use (overrides config)
`--docker-container`	Custom container name
`--docker-volume`	Additional volumes (can be repeated)
`--docker-env`	Environment variables (format: KEY=VALUE)

Config File Runtime Options

# In config/swarmhack.yaml
runtime:
  mode: docker  # or "local"
  docker_image: swarmhack/pentest:latest
  docker_auto_remove: true
  docker_volumes:
    - /host/reports:/app/reports
  docker_env:
    CUSTOM_VAR: value
  docker_network: bridge
  docker_resources:
    memory: 1g
    cpus: "1"

Node.js API

const swarmhack = require('swarmhack-cli');

// Run a scan
const results = await swarmhack.scan({
  target: 'http://example.com',
  agents: ['sqli', 'xss'],
  customer: 'your-customer',
  token: 'your-token',
});

console.log(results);

// Check version
const version = await swarmhack.version();
console.log(version);

// Run any command
const result = await swarmhack.run(['spawn', '--help']);
console.log(result.stdout);

Supported Platforms

Platform	Architecture
Linux	x64, arm64
macOS	x64, arm64
Windows	x64

Docker Alternative

If npm installation fails, use Docker:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/reports:/app/reports \
  prancer/swarmhack:0.1.0 \
  spawn --agents sqli --target "http://example.com" \
  --customer "your-customer" --token "your-token"

Available Agents (17)

Agent	CWE	Description
`crawler`	—	Web crawling, form discovery, WAF detection
`sqli`	CWE-89	SQL injection (UNION, boolean, error, time-based)
`xss`	CWE-79	Cross-site scripting (reflected, stored, DOM, blind)
`cmdi`	CWE-78	Command injection with marker-based detection
`csrf`	CWE-352	Cross-site request forgery
`idor`	CWE-639	Insecure direct object reference
`auth_bypass`	CWE-287	Authentication bypass
`ssrf`	CWE-918	Server-side request forgery (IMDS probes)
`lfi`	CWE-22	Local file inclusion / path traversal
`ssti`	CWE-1336	Server-side template injection
`open_redirect`	CWE-601	Open redirect
`cors`	CWE-942	CORS misconfiguration
`jwt`	CWE-345	JWT vulnerabilities (alg:none, confusion)
`xxe`	CWE-611	XML external entity injection
`file_upload`	CWE-434	File upload vulnerabilities
`deserialization`	CWE-502	Insecure deserialization
`http_smuggling`	CWE-444	HTTP request smuggling (CL.TE/TE.CL)

OCSF Reports

SwarmHack generates reports in OCSF 1.1.0 format, the industry standard for security findings:

{
  "scan_info": {
    "scanner": { "name": "SwarmHack", "vendor": "Prancer" },
    "customer": "your-customer",
    "target": "http://example.com",
    "duration_formatted": "3m 11s",
    "summary": { "findings_count": 5, "crown_jewels_count": 12 }
  },
  "class_name": "Vulnerability Finding",
  "class_uid": 6001,
  "findings": [...]
}

Authentication

SwarmHack requires Prancer Portal authentication:

swarmhack spawn \
  --target "http://example.com" \
  --agents sqli,xss \
  --customer "your-customer" \
  --token "your-32-char-token"

Get your token from Prancer Portal → Settings → Access Tokens.

Requirements

Node.js 16+
Prancer Portal account (for --token and --customer)

Changelog

v1.3.0

ADR-005: Self-learning intelligence layer (SONA, WAF evasion learning, adaptive rate limiting)
ADR-005: Semantic deduplication + crown jewel ML matching
ADR-005: Real HNSW vector index (replaced HashMap stub)
ADR-004: Recursive swarm architecture with 6 trigger types
Pre-flight authentication (5 methods via --auth)
Checkpoint-on-detection for all 17 agents
UTF-8 safety fix (28 byte-slicing sites)
147 new tests across intelligence layer

v1.2.0

ADR-004: Recursive swarm + auth config + tech debt remediation
CI hardening (test gates, pipefail)
Version bump and dependency cleanup

v1.1.0

ADR-003: 10 new exploit agents (SSRF, LFI, SSTI, CORS, JWT, XXE, FileUpload, Deserialization, HTTPSmuggling, OpenRedirect)
ADR-001: Parallel agent execution (4x speedup)
ADR-002: curl/nc deep exploitation