hunt

Files (1)

• SKILL.md

SKILL.md (first lines)

# Hunt

Use the current Codex, Claude Code, OpenCode, or Pi session as the planner. ShakerScan is the only
executor and remains authoritative for target binding, approvals, credentials, budgets, evidence,
candidates, and proof. Do not start a second in-server reasoning loop.

## Start

1. Check ShakerScan health and resolve exactly one registered target ID.
2. Read `GET /hunts/contract` and use the running server's contract rather than copying policy,
   budget, capability, or methodology catalogs into the prompt.
3. Express the investigation: target, target kind, objective, budget profile, selected credential
   profile IDs/request collections when needed, and the permissions the operator actually requested.
   Prefer server defaults and an empty capability list unless there is a concrete reason to narrow
   execution. Do not manufacture restrictive allowlists. A Hunt may use the credentials attached
   to its target (its own and those shared to it by grant); selecting profiles narrows that list.
   `credential_not_attached` means the operator must attach or share the credential first.
4. Reuse standing target authorization. When the target already has valid standing authorization,
   let ShakerScan resolve the target-bound approval; do not ask the operator to repeat approval or
   make them find/copy a receipt ID. Never invent authority or a receipt.
5. Without standing authorization, obtain explicit target-specific operator authorization before
   requesting active authority. A clear authorization already given in this conversation counts;
   record it once through the target authorization workflow rather than asking again.
6. Start `POST /hunts`, then read the returned context pack and capability schemas. Starting with
   no `skill_ids` is normal. Methodologies guide investigation; they do not grant or reduce
   authority.

These public start examples are checked through standing-authorization resolution before the
internal contract is validated. Active examples assume the operator has already authorized the
registered target. Empty budgets use the server's profile defaults; policy automatically zeros
unrequested permissions. Profile and collection IDs select resources, not new authority.

```json
{"schema_version":"hunt-start/v2","target_id":"registered-target-id","target_kind":"web","goal":"Investigate the authorized web target.","budget_profile":"balanced","policy":{"active_testing":false,"allow_state_changing_http":false,"network_discovery":false,"allow_oob_interactions":false},"budgets":{},"credential_refs":{},"capabilities":[],"request_collection_ids":[],"skill_ids":[]}
```

```json
{"schema_version":"hunt-start/v2","target_id":"registered-api-target-id","target_kind":"api","goal":"Compare authorization between two approved principals.","budget_profile":"balanced","policy":{"active_testing":true,"allow_state_changing_http":false,"network_discovery":false,"allow_oob_interactions":false},"budgets":{},"credential_refs":{"primary_credential_profile_id":"primary-profile-id","secondary_credential_profile_id":"secondary-profile-id"},"capabilities":[],"request_collection_ids":[],"skill_ids":[]}
```

```json
{"schema_version":"hunt-start/v2","target_id":"registered-network-target-id","target_kind":"network","goal":"Investigate the authorized network target.","budget_profile":"balanced","policy":{"active_testing":true,"allow_state_changing_http":false,"network_discovery":true,"allow_oob_interactions":false},"budgets":{},"credential_refs":{},"capabilities":[],"request_collection_ids":[],"skill_ids":[]}
```

```json
{"schema_version":"hunt-start/v2","target_id":"registered-device-target-id","target_kind":"device","goal":"Investigate the authorized connected device.","budget_profile":"balanced","policy":{"active_testing":true,"allow_state_changing_http":false,"network_discovery":true,"allow_oob_interactions":false},"budgets":{},"credential_refs":{"ssh_credential_profile_id":"ssh-profile-id"},"capabilities":[],"request_collection_ids":["saved-device-selection-id"],"skill_ids":[]}
```

The exact `hunt-start/v2` fields come from `GET /hunts/contract`. A normal planner should not
pre-fill zero-valued ceilings merely to make a request look explicit: doing so can accidentally
turn a usable Hunt into a no-op. Supply a lower ceiling only when the operator actually asks for
one.

**Budgets: do not starve the Hunt.** Leave `budgets` empty: the profile defaults are sized so that
calls, approval-gated calls, verifications, browser actions and HTTP requests cannot run out before
the profile's duration, so never ask for more of them in advance. Only the duration ends a Hunt.
A used-up safety ceiling (TCP ports, state-changing requests, hosts, UDP ports, out-of-band
interactions, device fragility) refuses only the actions that need it, and the Hunt keeps running. Never lower `max_http_requests` below what discovery needs: one
`web.crawl` and one `web.content_discover` reserve about 370 requests together, and an agent that
set 300, then 180, skipped content discovery and missed every exposed `/.env`, `/.git` and backup
file. The start response's `budget_warnings` names each capability the limits leave unable to run
even once. At a profile's defaults the usual web work (log in, crawl, discover content, verify,
record) draws none; a default warning names a safety ceiling such as TCP ports or state-changing
requests. If you lowered a limit and the warning says `restart_fixes_it: true`, start again without
lowering it. Call the capability a warning names only when your plan needs it (for example
`ports.discover` on `fast`): its refusal raises a `budget.raise` request for the person to approve;
otherwise carry on. A warning with `restart_fixes_it: false` is above even the profile's start
maximum: only a budget raise the person approves can let that capability run. Map first, then narrow.

**Keep answers small.** Hunt tools answer in a compact view by default; leave `view` out. Use
`capability=<name>` on `shakerscan_hunt_get` for one capability's contract, and `limit`/`cursor` on
queries. `view: full` returns a 70-150 KB record in 32 KB pages and wastes context: do not use it.

**Verification families.** `verification.verifiable_families` in the start response (and in
`GET /hunts/contract` under `candidates.verification`) lists the only families `candidate.verify`
can prove. Record any other family (prompt injection, excessive agency, RAG isolation...) as an
unverified candidate with its evidence, and do not spend a verification call on it.

For authenticated or multi-principal work, pass saved profile IDs only. For imported traffic, pass
saved request-collection IDs only. Secret values stay in ShakerScan. For network/device work, request
the network authority and resource profile the operator authorized; nonstandard ports, HTTP,
self-signed HTTPS, and alternate services on the same admitted asset are normal scanner inputs, not
reasons to abandon the Hunt.

If the server says additional authority is genuinely absent, explain the missing permission once.
Do not repeatedly prompt for authority already represented by standing authorization, and do not
convert a recoverable capability/budget shortage into failure of the whole investigation.

## Authorized HTTP workflows

`http.request` supports GET/HEAD/OPTIONS and authorized POST/PUT/PATCH/DELETE with
one `json_body` or `form_body`. Read the running server's schema; do not declare
PUT or pairing unavailable from an older read-only description. The same capability
and saved principal references apply across web, API, network and device Hunts.

For an operator-requested workflow such as TV pairing, request
`allow_state_changing_http: true` when creating the Hunt and reuse the target's
standing authorization. Do not ask again for each HTTP verb, port, or pairing step.
An already-admitted passive Hunt has not gained write authority; start an appropriately
configured Hunt using the existing target authorization rather than inventing a receipt.

Keep inline bodies non-secret. `request_bindings` inserts worker-resolved values from a saved
principal, an explicitly selected same-target profile ID/version, or an earlier action's capture.
Use `capture` with an exact JSON pointer or response-header name for a pairing challenge or issued
token. The result exposes only `source_action_id` and `capture_name`; pass these references to a
later body/header binding. A `prefix` such as `Bearer ` can format an authorization header without
exposing the token. Do not infer a secret field's name: use the protocol or retained evidence.

A newly supplied PIN goes through the existing encrypted credential-profile workflow, not the
Hunt input, log or shell history. Bind that profile's returned ID/version without restarting the
Hunt or re-asking permission already granted. Captures stay on this Hunt's action, expire after
one hour, and are cleared on finish/cancel; they are not permanent credentials for another Hunt.
A returned reference proves capture, not accepted application identity. Follow the protocol's
pairing confirmation with a relevant authenticated request before reporting pairing complete.

### Secrets the target leaks: use them by reference

Credentials found in target responses (a `.env`, a SQL dump, `web.config`, a phpinfo table, a
JSON `api_key`, a JWT in a bundle) are withheld from your view, not lost. `artifact.inspect`,

From andriyze/shakerscan, AGPL-3.0.

More from andriyze/shakerscan