swarmhack-cli

Neural swarm-based penetration testing framework.

What's New in v0.2.0

- Runtime Modes: Choose between local (direct execution) or docker (containerized) mode
- OCSF 1.1.0 Reports: Industry-standard vulnerability reports with optimized JSON structure
- Prancer Portal Integration: Secure authentication with Prancer Portal
- Bundled Configuration: Default config file included - no manual setup required
- Multi-Platform Support: Linux, macOS, and Windows binaries

Installation

``bash
npm install -g swarmhack-cli
`

Or use npx:

`bash
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:
`bash
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:
`bash
cp $(npm root -g)/swarmhack-cli/config/swarmhack.yaml ./config/
`

CLI Usage

`bash


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 |

$3

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

$3

`yaml


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

`javascript
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:

`bash
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

| Agent | Description |
|-------|-------------|
| crawler | Web crawling and discovery |
| sqli | SQL injection detection |
| xss | Cross-site scripting |
| csrf | CSRF vulnerabilities |
| idor | Insecure direct object reference |
| auth_bypass | Authentication bypass |
| cmdi | Command injection |

OCSF Reports

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

`json
{
"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:

`bash
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

$3

- Added runtime mode selection (local/docker)
- Added OCSF 1.1.0 report generation
- Added Prancer Portal authentication
- Bundled default configuration file
- Multi-platform binary support

$3

- Initial release

License

MIT