# swarmhack-cli

Neural swarm-based penetration testing framework.

## What's New in v2.1.0

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

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

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

```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:2.1.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

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

### Using Bearer Tokens

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

### Using Multiple Headers

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

```bash
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 (35)

| 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) |
| `pivot` | — | SSH lateral movement, tunnel scanning, credential reuse |
| `idor` (enhanced) | CWE-639 | Object reference enumeration with credential correlation |
| `nmap_scanner` | — | Port discovery, service detection, NSE vulnerability scanning |
| `ftp_probe` | CWE-287 | FTP anonymous login, default credentials, banner analysis |
| `ssh_probe` | CWE-327 | SSH banner analysis, weak version CVE detection |

## OCSF Reports

SwarmHack generates reports in [OCSF 1.1.0](https://schema.ocsf.io/) 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](https://portal.prancer.io) → Settings → Access Tokens.

## Requirements

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

## Changelog

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