Documentation / SwarmHack

CLI Reference

CLI Reference

swarmhack [GLOBAL FLAGS] <subcommand> [SUBCOMMAND FLAGS]

Global flags

| Flag | Type | Default | Description |

| --- | --- | --- | --- |

| -c, --config <PATH> | path | config/swarmhack.yaml | Config file path. |

| -o, --format <FMT> | string | text | json, text, table, pretty. |

| -v, --verbose | bool | false | Verbose output. |

| -q, --quiet | bool | false | Suppress non-critical output. |

| --file-logging <BOOL> | bool | true | Enable file logging. |

| --no-file-logging | bool | false | Disable file logging. |

| --log-file <PATH> | path | auto | Custom log file path. |

| --log-level <LVL> | string | info | trace, debug, info, warn, error. |

| --log-dir <PATH> | path | ./logs | Log directory. |

| --log-max-size-mb <N> | u64 | 100 | Rotate at this size (MB). |

| --log-retention-days <N> | u64 | 30 | Compressed retention period. |

| --authz-doc <PATH> | path | unset | Authorization document (JSON or YAML). |

| --authz-skip | bool | false | Bypass authz check (requires env opt-in). |

| --strict-tls | bool | false | Refuse invalid TLS certificates. |

| --allow-public | bool | false | Required to scan any non-lab target. |

| --blast-radius <CLASS> | enum | exploit | recon, exploit, destructive. |

swarmhack spawn — run an autonomous mission

The primary entry point.

swarmhack spawn [GLOBAL FLAGS] --target <URL> [SPAWN FLAGS]

Mission flags

| Flag | Type | Default | Description |

| --- | --- | --- | --- |

| -t, --target <URL> | string | — | Single target URL, IP, or hostname. |

| --targets <FILE> | path | — | Multi-target YAML / JSON file. |

| --target-list <CSV> | string | — | Comma-separated; supports CIDR (10.0.0.0/24). |

| --agents <CSV> | string | all | Restrict to named agents (sqli,xss,csrf,...). |

| --role <TEXT> | string | "penetration testing" | Mission role description. |

| -m, --mode <MODE> | string | autonomous | autonomous, manual, semi-auto. |

| --exec-mode <MODE> | enum | hybrid | hybrid, kill-chain, ael-only. |

| --kill-chain <PHASES> | string | full | Phases to execute. |

| --phases <CSV> | string | — | Override phases list. |

| --capabilities <SPEC> | string | auto | Capability set. |

| -b, --budget <N> | u32 | 100 | Max agents to spawn. |

| --timeout <SECS> | u64 | 3600 | Max runtime. |

| --crown-jewels <CSV> | string | — | Target data types to extract. |

| -r, --report <CSV> | string | ocsf,html | Output formats. See Report Types. |

| -O, --output <PATH> | path | — | Output file path override. |

| --parallel <N> | u32 | — | Parallel target processing factor. |

| --from-memory <SESSION> | string | — | Resume from a memory session. |

| --depth <N> | u32 | — | Max crawl depth. |

| --scope <SPEC> | string | — | Scope pattern (*.example.com,!admin.example.com). |

| --auth <PATH> | path | — | Pre-flight credentials. |

| --header <H> | string | — | Append HTTP header (repeatable). |

| --recursive-depth <N> | u32 | 0 | Recursive swarm depth. |

| --dedup-mode <MODE> | enum | vector | vector, hash, none. |

| --proxy <URL> | string | — | HTTP proxy. |

| --rate-limit <RPS> | u32 | — | Override per-host request rate. |

| --stealth | bool | false | Slower, lower-noise probing. |

| --aggressive | bool | false | Push-harder mode. |

| --dry-run | bool | false | Simulate without execution. |

| --token <TOKEN> | string | — | Prancer Portal access token (32-char hex). |

| --customer <ID> | string | — | Prancer tenant slug (lowercase). |

| --portal-url <URL> | string | https://portal.prancer.io | Override portal endpoint. |

| --runtime <MODE> | enum | local | local or docker. |

| --docker-image <IMAGE> | string | from config | Container image. |

| --docker-container <NAME> | string | auto | Container name. |

| --docker-volume <SPEC> | string | — | /host:/container (repeatable). |

| --docker-env <K=V> | string | — | Container env var (repeatable). |

| --allow-legacy-tools | bool | false | Allow Tier-3 legacy tools. |

| --no-bruteforce-mode | bool | false | NHA challenge variant. |

| --no-vagrant-default | bool | false | DRACARYS challenge variant. |

| --allow-ntlm-relay | bool | false | Opt in to the NTLM relay primitive. |

| --pci-compliance | bool | false | Emit PCI DSS pci_summary. |

| --use-goap-planning | bool | false | Opt in to GOAP A* phase planning. |

Mission side-effects

• ./reports/mission-{YYYYMMDD-HHMMSS}-{shortid}.json — OCSF report (always).
• ./reports/mission-…-attack-path.html — D3.js attack-path visualisation.
• ./reports/mission-…-attack-path.dot — Graphviz attack graph.
• ./reports/mission-….sse.md — SSE upsell Markdown (when --report sse).
• ./reports/per-target/… — per-target copies for multi-target campaigns.
• ./logs/{session-uuid}.jsonl — structured logs (rotated, gzipped).

swarmhack scorecard — before / after delta

swarmhack scorecard --before <BEFORE.json> --after <AFTER.json> [FLAGS]

| Flag | Default | Description |

| --- | --- | --- |

| --before <PATH> | — | Earlier mission OCSF JSON. |

| --after <PATH> | — | Later mission OCSF JSON. |

| --report <FMT> | sse-delta | Only sse-delta is implemented. |

| -o, --output <PATH> | auto | Output Markdown path. |

| --capability-map <PATH> | config/sse_capability_map.yaml | SSE capability map override. |

| --allow-schema-mismatch | false | Bypass schema-major check. |

| --features-toggled <TEXT> | — | Free-form note rendered into the delta MD (no PII). |

No network calls, no agent spawning — pure file diff.

swarmhack lab — GOAD lab harness

Drives vagrant up / snapshot / restore / status / destroy against the upstream GOAD repo under ~/.swarmhack/goad/.

| Subcommand | Description |

| --- | --- |

| lab list | List supported GOAD variants + hardware budget. |

| lab setup-host | One-time host setup (Vagrant + libvirt + Ansible). |

| lab clone-goad [--ref <SHA>] | Clone upstream GOAD repo. |

| lab build <VARIANT> | vagrant up; first build is 30–90 min. |

| lab snapshot <VARIANT> [--name <T>] | vagrant snapshot save. |

| lab restore <VARIANT> [--name <T>] | vagrant snapshot restore. |

| lab status <VARIANT> [--json] | Per-VM running/halted/IP state. |

| lab destroy <VARIANT> | vagrant destroy -f. |

| lab dc-ip <VARIANT> | Prints discovered DC IP. |

| lab validate <VARIANT> --report <PATH> | Validate an OCSF report against expected-crowns manifest. |

swarmhack tools — toolchain inventory

| Subcommand | Description |

| --- | --- |

| tools doctor [--json] [--allow-legacy-tools] | Reports Tier-1, Tier-2, Tier-3 toolchain state. |

swarmhack lint — OCSF report linter

| Flag | Description |

| --- | --- |

| --pentest-mode | Enforce: every finding must carry ≥1 crown jewel AND severity_id >= 3. Non-compliant reports exit 1. |

| --json | Single machine-readable JSON line. |

| <REPORT> | OCSF JSON to lint. |

swarmhack bh-query — BloodHound / Neo4j driver

| Flag | Default | Description |

| --- | --- | --- |

| --bolt <URL> | bolt://localhost:7687 | Neo4j endpoint. |

| --user <U> | neo4j | Neo4j user. |

| --password <P> | — | Required. |

| <CYPHER> | — | Raw Cypher (mutually exclusive with --preset). |

| --preset <NAME> | — | shortest-path-to-da, kerberoastable-admins, unconstrained-delegation. |

| --from <PRINCIPAL> | — | Source principal for shortest-path-to-da. |

| --json | — | JSON output. |

swarmhack relay — standalone NTLM relay

| Flag | Default | Description |

| --- | --- | --- |

| --listener <URL> | — | http://<bind> or smb://<bind>. |

| --target <URL> | — | ldaps://<dc> or https://<host>/certsrv/. |

| --escalate-user <DN> | — | Add to Domain Admins post-relay. |

| --delegate-access <DN> | — | Set RBCD on the named computer. |

| --add-computer <NAME> | — | Add new computer account. |

| --write-dacl <DN> | — | Append attacker-SID Allow ACE. |

| --attacker-host <HOST> | 127.0.0.1 | Advertised by WPAD payload. |

| --capture-timeout <SECS> | 180 | Listener timeout. |

Other subcommands

| Subcommand | Purpose |

| --- | --- |

| swarmhack init <NAME> | Initialise a project skeleton. |

| swarmhack start | Start the Queen orchestrator (interactive TUI). |

| swarmhack monitor [MISSION_ID] | Real-time mission monitor. |

| swarmhack stop <MISSION_ID> [--all] | Stop a mission. |

| swarmhack resume <MISSION_ID> | Resume from checkpoint. |

| swarmhack agents <...> | Agent management. |

| swarmhack memory <...> | Memory system. |

| swarmhack report <...> | Report generation off a stored mission. |

| swarmhack config <...> | Config management. |

| swarmhack learn <...> | ReasoningBank learning. |

| swarmhack campaign <...> | Multi-target campaign. |

| swarmhack skills <...> | Skill management. |

| swarmhack data | Pre-training data pipeline. |

| swarmhack model <status\ | verify> | Air-gapped model cache. |

| swarmhack logs <TARGET> [--follow] | Tail mission or agent logs. |

| swarmhack doctor | System health check. |

| swarmhack version | Print version + component banner. |