Run Your First SwarmHack Scan

This walkthrough takes you from a fresh machine to your first exploit-validated SwarmHack mission, then shows you where to find the OCSF report, attack-path HTML, and SSE upsell Markdown.

Looking for the full reference (every flag, every agent, every config file)? See the SwarmHack documentation.

Prerequisites

Before you start, make sure you have:

A Prancer Portal account — your 32-character hex access token (Settings → Access Tokens) and your lowercase tenant slug (e.g. xforia, not XFORIA).
A signed engagement letter or asset-ownership document for the target you intend to scan.
Node.js ≥ 16 on the operator host.
A target you are authorised to test. For your first run, use a loopback or RFC1918 lab target so you don't need --allow-public.

Step 1 — Install the CLI

SwarmHack ships as an npm package:

npm install -g swarmhack-cli

The installer drops a Node shim and resolves a platform-native binary for linux, darwin, or win32 on x64 / arm64.

Step 2 — Verify the install

swarmhack --version         # SwarmHack v2.6.0 + component banner
swarmhack doctor            # component-level health check
swarmhack tools doctor      # Tier-1 / Tier-2 / Tier-3 toolchain inventory

If doctor reports a missing component, address it before running a real mission.

Step 3 — Write your authorization document

Every spawn requires a per-engagement authorization document. Save the following as lab.authz.json and edit it for your engagement:

{
  "client": "Acme Corp",
  "targets": ["127.0.0.1", "10.0.0.0/24"],
  "expires_at": "2026-05-27T08:00:00Z",
  "scope": ["full_pentest"],
  "tester": "[email protected]",
  "document_id": "AUTHZ-LAB-FIRSTRUN-001",
  "notes": "First-run lab validation."
}

Rules to remember:

targets is label-strict — *.acme.com does not match dev.acme.com.evil.com.
expires_at is RFC 3339 UTC and is capped at ≤ 24 h in the future.
Do not paste credentials or PII into notes — it is rendered into customer reports.

[!IMPORTANT]

Running spawn without --authz-doc exits immediately with status 2. Running with a target that is not in targets[] exits with status 3. This is by design.

Step 4 — Export your portal credentials

export PRANCER_TOKEN="0123456789abcdef0123456789abcdef"
export PRANCER_CUSTOMER="your-tenant-slug"
export SWARMHACK_AUTHZ_DOC="$PWD/lab.authz.json"

Never commit these to source control.

Step 5 — Preview with a dry run (optional)

A dry run validates the authz contract, parses your flags, and prints the agent plan without spawning agents:

swarmhack spawn \
  --target http://127.0.0.1:9999 \
  --agents sqli,xss,csrf \
  --dry-run \
  --token "$PRANCER_TOKEN" \
  --customer "$PRANCER_CUSTOMER"

Step 6 — Run your first real scan

Point the swarm at a vulnerable lab target — for example a local Docker app on port 9999:

swarmhack spawn \
  --target http://127.0.0.1:9999 \
  --agents crawler,sqli,xss,cmdi,csrf \
  --report ocsf,html,sse \
  --token "$PRANCER_TOKEN" \
  --customer "$PRANCER_CUSTOMER"

What the flags do:

| Flag | Effect |

| --- | --- |

| --target | Single URL, IP, or hostname. |

| --agents | Restrict the swarm to the named agents (omit to enable all). |

| --report ocsf,html,sse | Emit the OCSF JSON, the D3 attack-path HTML, and the 8-section SSE Markdown. |

| --token / --customer | Prancer Portal identity. |

The mission runs autonomously (default --mode autonomous, default --budget 100 agents, default --timeout 3600s).

Step 7 — Read your results

Default destination: ./reports/. Mission id format: mission-{YYYYMMDD}-{HHMMSS}-{shortid}.

| File | What it contains |

| --- | --- |

| mission-….json | OCSF 1.1.0 Vulnerability Finding report (class_uid=2001). Severity, CWE, MITRE ATT&CK, compliance mappings (PCI-DSS, OWASP, NIST CSF 2.0, SOC2, HIPAA, ISO 27001, DORA, NIS2), and the crown_jewels[] array. |

| mission-…-attack-path.html | Self-contained D3.js attack-path graph — open in a browser. |

| mission-…-attack-path.dot | Same graph in Graphviz DOT. |

| mission-….sse.md | 8-section upsell-validated SSE Markdown (executive summary, successful paths, blocked paths, missing controls, SKU mapping, evidence appendix, upsell plan, authz footer). |

| ./logs/{session-uuid}.jsonl | Structured rotated logs. |

Validate that every Critical / High finding carries deep-exploitation evidence:

swarmhack lint --pentest-mode reports/mission-*.json

The linter exits 1 if any finding has no crown_jewels[] or severity_id < 3.

Step 8 — Compare two runs (optional)

After remediation work, you can produce a before / after delta report — pure file diff, no network, no agent spawning:

swarmhack scorecard \
  --before reports/mission-2026-05-25-pre.json \
  --after  reports/mission-2026-05-26-post.json \
  --report sse-delta \
  --output reports/customer-delta.md \
  --features-toggled "Enabled Duo step-up on /admin; enabled DLP inline on /upload."

Safety reminders

Public targets require --allow-public and an authz-doc whose targets[] lists the host.
NTLM relay requires --allow-ntlm-relay and explicit authorisation in the engagement letter.
Destructive payloads require --blast-radius destructive and an authz-doc that explicitly authorises them. Pair only with a lab target you own.
TLS is on by default. Only relax with SWARMHACK_INSECURE_PREFLIGHT_TLS=1 / SWARMHACK_INSECURE_BANNER_TLS=1 against self-signed lab certs. Never in production.

You're done — that's a complete autonomous, exploit-validated SwarmHack mission. For full flag coverage, agent details, and operational tuning, head to the SwarmHack docs.