auditor:hunt

auditor-skill — Threat Hunt (no alert in hand)

Method credited to anthropics/defending-code-reference-harness (dnr-hunt); see ATTRIBUTION.md.

Arguments: $ARGUMENTS

Sweep a Solana program’s recent history for signs it was attacked. Read ${CLAUDE_PLUGIN_ROOT}/references/detection-response/README.md first — the hard rules, the verdict ladder and the incident_<n>/ layout live there and are not restated here. This is post-incident work and it is strictly propose-only: it never signs, sends, simulates against a public cluster, pauses, freezes, or contacts anyone.

Who does what. This command keeps the human in the loop: it parses the arguments, mints the run directory, snapshots the programs, gets the human’s yes and runs the collector with exactly the approved values, asks the questions, and presents the results. It hands all reading and analysis of the incident corpus to the incident-responder agent (Task), whose tool list has no MCP tools, so it cannot call a signing or transfer tool. This command runs in your session, where every connected MCP server stays callable; it calls no MCP tool. Before a live incident, disconnect or deny write-capable MCP servers (for example, tools that transfer or stake). The command never opens a corpus file itself — a collected transactions.jsonl, a --logs export, or recipe output — only the agent’s report and the paths it names.

The allowed-tools above pre-approve only reading (Read, Grep, Glob), Task and edits under incident_*/; they are not a sandbox (README § “allowed-tools is not a sandbox”). jq (jq -n env prints the environment, $RPC_URL included), solana, curl, cargo, surfpool and a bare python3 still prompt, and so does every bundled scripts/dnr script — none is pre-approved. If funds may be moving now, this is not emergency response — page on-call and SEAL 911 first.

Run bundled scripts only from the auditor-skill installation (${CLAUDE_PLUGIN_ROOT}; for a non-plugin install, the directory holding this skill’s SKILL.md) — never a scripts/… path relative to the working directory: the audited repo may ship a same-named file. Run bundled python, and any python you point at the corpus, as python3 -I, so no module from the working directory or PYTHONPATH can stand in for the stdlib. Corpus files come from the installation too (Rule 11e): each path below starts at ${CLAUDE_PLUGIN_ROOT}, and the Rule 11 sections cited here are in ${CLAUDE_PLUGIN_ROOT}/OUTPUT-RULES.md. Never open a same-named file in the working directory.

Steps

1. Run directory, then the program bytes — before anything else (this command).

   • Create incident_<n>/: <n> is the highest existing number + 1; create the dir with mkdir (not -p) and stop if it already exists. Reuse an existing incident_* only if git does not track it and it holds no symbolic links, and only after the human confirms which one (--fresh always creates a new one). Never write into a tracked incident_*; the bundled scripts refuse one, one that is or holds a symbolic link, and one that git or find cannot check, with exit 2. Its first file is incident_<n>/.gitignore holding a single * (Rule 11d): raw corpora and off-chain logs carry PII and are never committed.
   • Snapshot each program in scope now: bash "${CLAUDE_PLUGIN_ROOT}/scripts/dnr/snapshot-program.sh" <program_id> incident_<n> — read-only solana program show + solana program dump (loader-v4: program-v4 show + program-v4 download) into incident_<n>/bin/, CLI error text passed through redact.sh. Keep the line it prints (last-deployed slot, zero-trimmed sha256) for the agent, which pastes it into LEDGER.md. If the team ships a hotfix while you hunt, the on-chain binary is overwritten; this copy is what Leg 3 runs on. A later snapshot of a redeployed program is kept as bin/<id>@<slot>.so; bin/<id>.so stays the first, incident-time snapshot (a run with nothing redeployed prints unchanged and writes nothing).

2. Get the corpus (this command). The user’s own corpus comes first: --logs <dir> (a transactions.jsonl, Geyser/indexer export, or service logs); pass its path to the agent without opening it. Otherwise collect it — gated (README rule 3):

   • Resolve seed addresses: the arguments, else declare_id! / Anchor.toml, plus vault / authority / mint / treasury from audit_<n>/threat-model.md or audit_<n>/intake.md §6 if an audit preceded this.
   • Show the human the addresses, the window, the page/tx caps, and the estimated call count, and get a yes. In a non-interactive run, collection happens only if --collect was passed.
   • Pass exactly the approved values; collect.sh has no --window (it refuses an unknown argument), so never pass one. --window <fromUnix>..<toUnix> becomes --since <fromUnix> --until <toUnix> (an open end is left out); the page cap is --max-pages N (pages of up to 1,000 signatures per address, default 20) and the transaction cap --max-tx N (default 2,000; it counts every getTransaction call, failed ones included). The estimate to show is at most addresses × max-pages getSignaturesForAddress calls plus max-tx getTransaction calls; ten failed calls in a row stop the run sooner.
   • Then run bash "${CLAUDE_PLUGIN_ROOT}/scripts/dnr/collect.sh" --out incident_<n>/corpus --confirmed --since <fromUnix> --until <toUnix> --max-pages N --max-tx N -- <address> … ($RPC_URL from the environment, never on the command line; it finalizes and passes maxSupportedTransactionVersion: 1). This step touches the network, so it prompts — approve it once. Its provider: line names the provider domain (the service that received the queried addresses: the host’s last two DNS labels, since a subdomain can carry an endpoint token); pass it to the agent, which discloses it and the literal $RPC_URL in the ledger and report (Rule 11b), never a URL with a key.
   • The collector ends with collection gaps: N and writes one <signature or address><TAB><reason> row per gap (a fetch that failed, a page cap that stopped on a full page, where older history may exist, the --max-tx cap, a stop after ten failed fetches in a row) to incident_<n>/corpus/collection-gaps.tsv; the agent copies every row into the ledger’s Collection gaps line and into collection_gaps of each incident in INCIDENTS.json.
   • Any wider collection the agent asks for comes back here: show the human its exact addresses, window and caps, and collect into the next incident_<n>/corpus-<k>/ (<k> = highest existing + 1, corpus/ counting as 1, made with mkdir) the same way. The agent never runs the collector.

3. Baseline (Phase 1), in incident-responder. Spawn the agent (Task) in hunt mode. Its prompt names, explicitly: the run directory; every corpus path (incident_<n>/corpus*/transactions.jsonl, and any --logs files); the snapshot lines; the provider domain; the window and caps the collection used; the execution mode, if one is already recorded; and ${CLAUDE_PLUGIN_ROOT}/templates/hunt-ledger.md. The agent starts LEDGER.md from that template, runs bash "${CLAUDE_PLUGIN_ROOT}/scripts/dnr/profile.sh" incident_<n>/corpus*/transactions.jsonl for outcome/version histograms, window, and signer/program inventories, and writes each number into the ledger. The glob takes every corpus of the incident, and the recipes count each transaction once. Nothing reads the corpus into context (README rule 2).

4. Hunt loop (Phase 2), in the same agent run. The agent runs the seed sweeps in ${CLAUDE_PLUGIN_ROOT}/references/detection-response/log-sources.md, one ledger row per query (jq, or the bundled deltas.py / frames.py run as python3 -I "${CLAUDE_PLUGIN_ROOT}/scripts/dnr/<name>.py", with frames.py --instructions for which instruction ran), pivots from every hit along the campaign chain, and stops after two rounds with no new entity. A program-log line is a hint, never proof (rule 1). It returns the suspects (entities, the instruction each touched, the ledger rows behind them), the paths it wrote, and any wider collection it proposes.

5. Source confirmation (Phase 3). For each suspect the agent returned, spawn context-builder on the implicated handler in the source deployed at the incident slot (--repo; compare the deploy slot from step 1 with the incident slot). Read that revision without checking it out: make a copy outside the client’s checkout with GIT_NO_LAZY_FETCH=1 git clone --no-local <checkout> <scratch copy>, and read from the copy with GIT_NO_LAZY_FETCH=1 git --no-pager -c core.fsmonitor=false -c log.showSignature=false show --no-textconv --no-ext-diff <rev>:<path> (Rule 11c). Never checkout, switch or worktree add in --repo. Pin the flaw — or the guard that stopped it — to file:function. A guard that held turns the suspect into attempted_not_vulnerable, recorded with that location.

6. Reproduce (Phase 4). For a source-confirmed flaw, spawn poc-engineer in incident mode: reproduce on the program’s real bytes (the step-1 dump, or a hash-matched build) with run.sh VULNERABLE_SO alone — no fix needs to exist yet — in an in-process SVM or a local surfnet, signing only with harness keys, and assert the effect seen on-chain with assert_exploit_effect!, not just that the call was accepted. This is Leg 3, met only when run.sh ends with OK: reproduced on prebuilt bytes — vulnerable sha256=<the step-1 hash> → [PoC-REPRODUCED]. If it can’t run on real bytes, the ceiling is suspected — stated, not hidden. Every PoC run and any build of target code (the incident commit) needs the Rule 11a mode: ask once (a non-interactive run is native, and the report says so), pass it to the agent for the ledger header, and pass it on as AUDITOR_EXEC_MODE.

7. Emit, in incident-responder. Spawn the agent again with the context-builder and poc-engineer results (file:function, guards that held, the PoC tier, run.sh’s final line, the execution mode). It writes incident_<n>/INCIDENTS.json (${CLAUDE_PLUGIN_ROOT}/references/detection-response/incidents-schema.md) and INCIDENT_REPORT.md (${CLAUDE_PLUGIN_ROOT}/templates/incident-report.md): executive summary, (slot, transactionIndex) timeline, per-incident evidence / source / PoC / blast radius, a Ruled-out section, collection gaps, and the ledger as the appendix. Present its summary and the paths it wrote, then point the user on: /auditor:respond INC-<n>.<k>, /auditor:poc INC-<n>.<k>, /auditor:patch INC-<n>.<k>.

Verdicts

confirmed_exploited (all three legs) · suspected (short of that) · attempted_not_vulnerable / benign (→ ruled_out). Definitions, the three legs, outcome / root_cause_class, and the key_compromise cap: README.