swarmhack-cli

Neural swarm-based penetration testing framework.

What's New in v2.0.0

v2.0.0 -- Major Release

• Confidence Calibration System -- Evidence-based confidence scoring (0.60-1.0) replacing fixed 1.0. Each finding's confidence reflects actual proof quality: heuristic detection (0.60), response pattern match (0.90), marker-based confirmation (0.99), synthesized from confirmed data (1.0).
• Full Kill Chain Automation -- Single command executes: external web scan -> credential extraction -> SSH lateral movement -> privilege escalation -> SSH tunnel -> internal target scanning. Zero human intervention.
• Credential Correlation -- 12 regex patterns extract credentials from HTML response bodies (SSH creds in admin pages, connection strings, API keys, Bearer tokens). Extracted creds automatically propagated via Intelligence Bus to SSH/auth agents.
• Privilege Escalation Chain Synthesis (ADR-009) -- Post-processing creates standalone "www-data -> root" findings from CMDI post-exploitation data (sudo NOPASSWD, SUID binaries, Docker socket).
• .env File Deep Extraction -- CMDI agent reads .env files via command injection, parses SSH/DB/API credentials with category classification (ssh_credential, database_credential, api_key, network_topology).
• Internal Tunnel Scanning (ADR-010) -- After SSH pivot discovers dual-homed hosts, automatically opens SSH tunnel via portable-pty and spawns new kill chain against internal targets.
• SSRF CVE Correlation -- 10-CVE payload map (CVE-2021-44224, ProxyLogon, Log4Shell, etc.). SSRF agent reads vulnerable_components findings and generates CVE-specific exploitation payloads.
• SQLi Time-Based Confirmation -- 3-step verification: retry payload, send SLEEP(0) control, confirm only if retry delayed AND control fast. Eliminates jitter false positives.
• XXE Confidence Grading -- Tiered confidence: heuristic-only (0.60), marker match (0.90), with deep exploitation output (1.0). OOB callback infrastructure ready (callback_url config).
• SONA Self-Learning (Phase 1) -- Optional --features self-learning wires ruvector-sona for payload trajectory recording and adaptive recommendations.
• 32 Exploit Agents -- Added session_fixation, dangerous_methods, pivot, plus enhanced all ADR-003 agents with memory deduplication and Intelligence Bus integration.
• Smart Pivot Optimization -- Port-scanned reachable hosts tried first, failed hosts skipped after timeout, SSH ConnectTimeout reduced to 3s for fast iteration.

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

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

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.0.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 (32)

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

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