swarmhack-cli

Neural swarm-based penetration testing framework.

What's New in v2.5.0

v2.5.0 -- Multi-Target Campaign + Network Intelligence + Host Recon

• Multi-target campaigns -- --target-list accepts comma-separated IPs, URLs, hostnames, and CIDR ranges. Scan entire networks in one command.
• CIDR expansion -- --target-list 10.0.0.0/24 expands to 254 hosts automatically.
• Campaign intelligence graph -- Credentials found on Host A are automatically seeded to Host B (petgraph + DashMap property graph).
• Unified OCSF report -- Single mission-*.json with all targets' findings combined. Per-target reports moved to reports/per-target/.
• Network attack path visualization -- D3.js HTML showing all hosts as topology with device types, findings grouped per host, detail panel on click, intel flow bottom panel.
• Host recon -- Reverse DNS + HTTP banner + MAC vendor lookup. Device type classification: Router, Printer, NAS, IP Camera, Web Server.
• Graceful unreachable skip -- Offline hosts skipped with one-line message instead of verbose error. Prior scan data included in campaign report.
• Default credential fallback -- SMB/WinRM agents try vagrant:vagrant and other defaults when campaign creds fail on non-domain hosts.
• Network agent findings fix -- AD agent findings now included in OCSF report and CLI display (was silently dropped).
• Quiet campaign mode -- Per-target "MISSION COMPLETE" banners suppressed; single campaign summary shown.
• 49 regression tests (was 37) across 15 categories.
• GOAD assessment -- Comprehensive mapping of 38 GOAD attack paths vs SwarmHack capabilities.
• 46 agents total (23 web + 23 AD/network).

v2.4.0 -- AD Data Quality + Mandatory Auth + External Tool Documentation

• Mandatory Prancer Portal authentication (offline mode removed)
• AD finding categorization (CWE-307/521/522 → "authentication")
• Dynamic resource type from URL scheme
• Compliance mappings for AD CWEs
• LDIF base64 parsing, password policy guard, trust direction decoding
• Crown jewel dedup across merged findings
• External tool documentation (38 binaries)

v2.1.0 -- Quality, OCSF Compliance & Service-Driven Discovery Foundation

• Agent Plugin Registry (ADR-011) -- Scalable plugin system: adding a new agent is one file + one registry line. 26 plugins registered (23 legacy web agents + nmap scanner + FTP probe + SSH probe). Foundation for 100+ agents.
• Nmap-First Port Discovery -- Every mission starts with nmap port/service discovery (canonical entry point). Discovered services route to the correct agents automatically via ServiceRouter. Falls back to URL-based inference when nmap is unavailable.
• FTP & SSH Probe Agents -- New non-HTTP agents: FTP anonymous login + default credential testing, SSH banner analysis + weak version CVE detection. First protocol-aware agents beyond HTTP.
• OCSF 1.1.0 Full Compliance -- type_uid corrected to 600105, severity_id added at finding level, crown jewel deduplication by (category, value), findings sorted by generation ascending + risk_score descending.
• Crown Jewel Sanitization -- 5-rule system: short values always full, api_key never truncated, credential summaries up to 200 chars, session tokens format-preserving (PHPSESSID=abcd...wxyz), fallback 500-char cap.
• False Positive Elimination -- LFI agent filters PHP payloads on ASP.NET/IIS targets, IDOR agent no longer fabricates synthetic parameters, Default Credentials uses discovered form field names, CVE-2021-31166 version rule narrowed.
• Risk Score Calibration -- Info=1.0, Low=3.0, Medium=5.0, High=7.5, Critical=10.0 base scores. robots.txt now scores ~0.2 (was 0.9), SQLi auth bypass scores ~9.0 (was 5.63).
• Security Fixes -- Shell injection in askpass helper patched, TLS verification restored in file_upload/xxe agents, PII redaction in OCSF reports.
• CI Pipeline -- cargo test + cargo clippy now run on every push/PR (was build-only).
• Version Banner -- Uses CARGO_PKG_VERSION (no more hardcoded v1.0.0).
• 83 new regression tests -- 46 for v2.1.0 quality fixes + 37 for ADR-011 Phase 1.

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:

1. Using your own config file:

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

2. Creating a local config in your project: Place config/swarmhack.yaml in your project root - it will be automatically detected.

3. 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

Single Target

# Full kill chain scan
swarmhack spawn \
  --target "http://example.com" \
  --customer "your-customer" \
  --token "your-token"

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

# AD domain controller scan
swarmhack spawn \
  --target 192.168.56.10 \
  --customer "your-customer" \
  --token "your-token"

Multi-Target Campaign (NEW in v2.5.0)

# Scan multiple targets — credentials from Host A are shared with Host B
swarmhack spawn \
  --target-list "192.168.56.10,192.168.56.11,10.0.0.1" \
  --customer "your-customer" \
  --token "your-token"

# Scan entire subnet (CIDR)
swarmhack spawn \
  --target-list "10.0.0.0/24" \
  --customer "your-customer" \
  --token "your-token"

# Mixed targets: IPs + URLs + hostnames + CIDR
swarmhack spawn \
  --target-list "192.168.56.10,https://app.corp.local,10.0.0.0/24" \
  --customer "your-customer" \
  --token "your-token"

Campaign output:

• Unified mission-*.json with all findings across all targets
• mission-*-attack-path.html showing network topology with all hosts
• Per-target reports in reports/per-target/
• Unreachable hosts gracefully skipped

Docker Mode

# 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:

CLI Runtime Options

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

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:2.5.0 \
  spawn --agents sqli --target "http://example.com" \
  --customer "your-customer" --token "your-token"

Authenticated Scanning

SwarmHack supports authenticated scanning using custom HTTP headers. This enables testing of post-authentication attack surfaces that are invisible to unauthenticated scans.

Using Session Cookies

swarmhack spawn \
  --target "https://your-app.com" \
  --header "Cookie: session=abc123def456" \
  --token "$PRANCER_TOKEN" \
  --customer "$PRANCER_CUSTOMER"

Using Bearer Tokens

swarmhack spawn \
  --target "https://api.your-app.com" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --token "$PRANCER_TOKEN" \
  --customer "$PRANCER_CUSTOMER"

Using Multiple Headers

swarmhack spawn \
  --target "https://your-app.com" \
  --header "Cookie: session=abc123" \
  --header "X-API-Key: your-api-key-here" \
  --header "X-Tenant-ID: customer-123" \
  --token "$PRANCER_TOKEN" \
  --customer "$PRANCER_CUSTOMER"

Using Basic Auth

swarmhack spawn \
  --target "https://your-app.com" \
  --header "Authorization: Basic YWRtaW46cGFzc3dvcmQ=" \
  --token "$PRANCER_TOKEN" \
  --customer "$PRANCER_CUSTOMER"

Tips for Authenticated Scanning

• Get a fresh session token before scanning -- expired sessions produce false negatives
• Use a test account with appropriate permissions -- avoid scanning with admin credentials unless testing privilege escalation
• Set appropriate timeout -- authenticated scans discover more endpoints, so allow more time: --timeout 1200
• Monitor session validity -- some apps invalidate sessions after unusual activity patterns
• The --header flag is repeatable -- add as many custom headers as needed
• All agents (SQLi, XSS, CSRF, etc.) automatically include your custom headers in every request

Available Agents (46)

OCSF Reports

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

Single target:

{
  "scan_info": {
    "scanner": { "name": "SwarmHack", "vendor": "Prancer" },
    "customer": "your-customer",
    "target": "http://example.com",
    "summary": { "findings_count": 9, "crown_jewels_count": 23 }
  },
  "compliance_summary": { "frameworks_covered": ["PCI-DSS 4.0", "OWASP Top 10", "NIST CSF 2.0", ...] },
  "findings": [...]
}

Multi-target campaign:

{
  "scan_info": {
    "mission_type": "multi-target",
    "targets_scanned": 4,
    "targets_total": 5,
    "summary": { "findings_count": 20, "crown_jewels_count": 28 },
    "per_target": [
      { "target": "http://192.168.56.10/", "findings_count": 6, "crown_jewels_count": 4 },
      { "target": "https://demo.testfire.net/", "findings_count": 7, "crown_jewels_count": 22 }
    ]
  },
  "findings": [/* all findings from all targets combined */]
}

Each finding includes:

• Severity + risk score + confidence
• CWE classification + MITRE ATT&CK mapping
• Compliance mappings (PCI-DSS, OWASP, NIST, SOC2, HIPAA, ISO 27001, DORA, NIS2)
• Crown jewels (extracted credentials, hashes, sensitive data)
• Device type identification (Router, Printer, NAS, etc.)

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

v2.5.0

• Multi-target campaigns: --target-list with comma-separated IPs, URLs, hostnames, CIDR ranges
• CIDR expansion: 10.0.0.0/24 → 254 hosts, up to /16 supported
• Campaign intelligence graph: credentials from Host A seed Host B (petgraph + DashMap)
• Unified OCSF report: single mission-*.json with all targets combined
• Network attack path visualization: D3.js HTML with host topology, device types, detail panel, intel flow
• Host recon: reverse DNS + HTTP banner + MAC vendor → device type classification
• Graceful unreachable skip: offline hosts skipped cleanly, prior scan data included
• Default credential fallback: SMB/WinRM try vagrant:vagrant when null session/campaign creds fail
• Network agent findings fix: AD findings now in report + CLI display (was silently dropped)
• Quiet campaign mode: per-target banners suppressed, single summary shown
• 49 regression tests across 15 categories
• GOAD lab assessment: 38 attack paths mapped vs SwarmHack capabilities
• Validated: 5-target campaign = 20 findings, 28 crown jewels

v2.4.0

• BREAKING: Mandatory Prancer Portal authentication — offline mode removed
• AD finding category mapping: CWE-307/521/522 → "authentication", CWE-200 → "reconnaissance"
• Dynamic affected_resource.type from URL scheme (Directory Service, Kerberos KDC, SMB File Share)
• Compliance mappings for AD CWEs (OWASP A07:2021, PCI-DSS 8.3.6, NIST PR.AA-01)
• LDIF base64 attribute parsing, empty password policy guard, trust direction decoding
• Crown jewel dedup across merged findings, masked value filtering
• 37 quality regression tests (was 25)
• External tool documentation: 38 binaries fully documented with install instructions

v2.3.0

• Full AD exploitation pipeline: 23 new network/AD agents (LDAP, Kerberos, SMB, MSSQL, DCSync, WinRM, NTLM, ACL, ADCS, delegation, LAPS, shadow creds, GPO, trust)
• 6-pass AD kill chain: Discovery → Spray → Kerberoast → Exploit → Lateral → Dominate
• Credential chaining via shared memory (spray → Kerberoast → lateral movement)
• Blackbox DC discovery: rootDSE + DNS reverse + NetBIOS
• OCSF compliance mapping for 8 frameworks (ADR-012)
• D3.js attack path visualization (ADR-013)
• GOAD lab validated: hodor:hodor credential + tyron.lannister TGS hash extracted
• Agent plugin registry with define_plugin! macro (46 plugins total)
• Bare IP/hostname target support (auto-prepend http://)
• TCP connectivity fallback for non-HTTP targets

v2.1.0

• Agent plugin registry (ADR-011): scalable plugin system for 100+ agents (one file + one registry line per agent)
• Nmap-first port discovery: canonical entry point, automatic service-to-agent routing
• FTP probe agent: anonymous login, default credential testing, banner analysis
• SSH probe agent: banner analysis, weak version CVE detection
• OCSF 1.1.0 compliance: type_uid=600105, severity_id at finding level, crown jewel dedup, finding sort order
• Crown jewel sanitization: 5-rule system (api_key never truncated, format-preserving session tokens)
• False positive elimination: LFI tech-stack filter, IDOR no synthetic params, default creds uses discovered form fields, CVE-2021-31166 narrowed
• Risk score calibration: Info=1.0, Low=3.0, Medium=5.0, High=7.5, Critical=10.0
• Security fixes: shell injection in askpass, TLS verification restored, PII redaction in reports
• CI pipeline: cargo test + cargo clippy (was build-only)
• 83 new regression tests (46 quality fixes + 37 ADR-011 Phase 1)
• 35 exploit agents (was 32): added nmap_scanner, ftp_probe, ssh_probe

v2.0.0

• Confidence calibration system: evidence-based scoring (0.60-1.0) replacing fixed 1.0
• Full kill chain automation: web scan -> credential extraction -> SSH pivot -> privilege escalation -> internal scanning
• Credential correlation: 12 regex patterns, auto-propagation via Intelligence Bus
• Privilege escalation chain synthesis (ADR-009): standalone www-data -> root findings
• .env file deep extraction: SSH/DB/API credential parsing from command injection
• Internal tunnel scanning (ADR-010): SSH tunnel via portable-pty for internal targets
• SSRF CVE correlation: 10-CVE payload map (ProxyLogon, Log4Shell, etc.)
• SQLi time-based confirmation: 3-step verification eliminates jitter false positives
• XXE confidence grading: tiered 0.60/0.90/1.0 with OOB callback ready
• SONA self-learning (Phase 1): ruvector-sona payload trajectory recording
• 32 exploit agents (was 23): added pivot, enhanced all ADR-003 agents
• Smart pivot optimization: port-scan prioritization, 3s SSH ConnectTimeout
• Authenticated scanning: --header flag for session cookies, Bearer tokens, API keys

v1.5.0

• ADR-006: OWASP Top 10 full coverage -- 6 new agents (SessionFixation, DangerousMethods, DefaultCredentials, PrivilegeEscalation, MassAssignment, VulnerableComponents)
• Intelligence Bus: 7 typed intel categories shared across all 23 agents
• Runtime vulnerability chaining: credentials/sessions feed consumer agents live
• VulnerableComponents agent (OWASP A06): 30 built-in CVE entries
• CVSS score fix (was always 0.0), GOAP precondition key unification
• SwarmHackConfig wrapped in Arc (performance), agent pool 20->25
• Live validated: 16 findings, 67 crown jewels, 0 false positives across 3 targets

v1.4.0

• Hybrid execution mode (Kill Chain + AEL amplification)
• SPA false positive elimination
• Auth crawling and OCSF auth tracking
• Common endpoint discovery (107 paths)
• Version bump and CI adjustments

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

v0.2.0

• Runtime mode selection (local/docker)
• OCSF 1.1.0 report generation
• Prancer Portal authentication

v0.1.0

• Initial release

License

MIT