swarmhack-cli

Neural swarm-based penetration testing framework.

What's New in v1.5.0

• 23 Exploit Agents: Full OWASP Top 10 coverage with 6 new agents (SessionFixation, DangerousMethods, DefaultCredentials, PrivilegeEscalation, MassAssignment, VulnerableComponents)
• Intelligence Bus: 7 typed intel categories shared across all 23 agents (TargetProfile, WafProfile, CredentialIntel, NetworkIntel, FileSystemIntel, AuthStateIntel, ExploitPathIntel)
• Runtime Vulnerability Chaining: Credentials/sessions from SQLi/AuthBypass automatically feed IDOR/PrivEsc/CSRF agents in a live chaining phase
• VulnerableComponents Agent (OWASP A06): 30 built-in CVE entries — fingerprints server versions from headers and matches against known vulnerabilities
• CVSS Score Fix: Severity scores now correctly computed (was always 0.0 due to case mismatch)
• Performance: SwarmHackConfig wrapped in Arc — eliminates deep clones on every agent spawn
• Agent Pool: Increased to 25 concurrent slots for 23 agent types
• Live Validated: 16 findings across 3 targets (demo.testfire.net, ginandjuice.shop, testasp.vulnweb.com) with 0 false positives

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:

| 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 (23)

| 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) | | session_fixation | CWE-384 | Session fixation and invalidation testing | | dangerous_methods | CWE-16 | Dangerous HTTP methods (TRACE/XST, PUT upload) | | default_credentials | CWE-798 | Default credential scanning (20 pairs) | | privilege_escalation | CWE-862 | Function-level access control testing | | mass_assignment | CWE-915 | Mass assignment / parameter injection | | vulnerable_components | CWE-1035 | Version fingerprinting + CVE lookup (30 CVEs) |

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