Hunt in Enterprise

Hunt is ShakerScan's AI-assisted investigation workspace: an operator, or their agent, drives the engine through a target-scoped loop of skills and candidates while the engine keeps the authorization, budget and proof rules. In Enterprise it sits behind the same single sign-on, roles and audit as everything else.

Where the reasoning runs. The interactive Hunt, in the browser and over MCP, is driven by the operator or by their agent: the engine's skill suggestions and knowledge queries are deterministic, and the thinking is the person's or the agent's own model, not the engine's. The engine's own model credentials power three other things: AI verification of findings, AI classification of findings, and the autonomous Hunt, where the engine reasons and investigates on its own with the model you configure. Nothing about a Hunt leaves your network except the model API calls you configure yourself.

Who can use it

Roles come from the same identity system as the rest of Enterprise (local accounts or your identity provider). A Hunt is audited like a scan: every mutation is recorded under the acting identity, whether a person in the browser or a token used by an agent.

Turn it on (administrator, once)

Hunt is on for operators and administrators by default. An administrator can turn it off or back on under Settings → Scanning in the console; it applies immediately. (On the host, SHAKERSCAN_ENTERPRISE_HUNT=off in enterprise.env sets the starting value.)

Optionally give the engine model credentials. The interactive Hunt does not need them; they power AI verification and classification of findings and the autonomous Hunt. In the engine runtime's .env, before prepare or before the next re-render:

AI_URL=https://api.openai.com/v1        # or your provider's endpoint
AI_API_KEY=<your model API key>
AI_MODEL=<the model to use>

Then re-render and restart:

cd /srv/shakerscan-enterprise
self-hosted/upgrade.sh <current Enterprise image digest> /srv/shakerscan-public-release /srv/shakerscan-enterprise
docker compose -f compose.json up -d --wait

The Enterprise console's Deployment card then shows Hunt: enabled for operators, and the scanner workspace shows the Hunt navigation. Hunt takes no license slot; it runs regardless of the concurrent-scan count.

Ways to use it

The same gateway, the same token rules and the same audit sit in front of all of these. The first three drive the interactive Hunt (you or your agent reason); the fourth is the autonomous Hunt (the engine reasons with your model).

1. People, in the browser

Operators and administrators open the Hunt area of the scanner workspace and drive a Hunt against a target they are authorized for. Viewers can open Hunt history and read records.

2. An agent on your laptop

shakerscan agent claude (or Codex, OpenCode, Pi) gives the agent the ShakerScan workspace against your instance: its /deep-hunt command, the Hunt skill, and the Hunt tools over MCP, with the agent's own model doing the reasoning. Setup is two commands; see Work with an agent.

3. Scripts

The same client carries the Hunt command line, with the same token file:

shakerscan hunt list
shakerscan hunt start --help

Use it for scripted or CI-style Hunts; for interactive agent use, MCP is the better fit.

Whichever way an agent or script drives a Hunt, it works on a target a person authorized, within the policy and budget it started with. A step outside them that a person may allow (a budget raise, another target's saved credential, another host or port, a state-changing or active-testing step the Hunt's policy does not include) waits as a permission request. You decide it in your own terminal with shakerscan approve <id> or shakerscan deny <id> (--all-pending, --watch) and your authenticator code, security key or single sign-on, or allow it up front with shakerscan agent --allow; see Approve Hunt requests in your terminal. A target's authorization covers active testing: whoever holds the token can start a new Hunt whose policy includes active testing or state-changing requests on a target a person authorized, and that Hunt asks for neither.

4. The autonomous Hunt (the engine reasons with your model)

This is the only path that uses the engine's model credentials. An operator starts a single research episode and the engine runs its own reasoning loop against the target, up to a bounded step count, then reports:

curl -X POST https://scanner.example.com/research/episodes \
  -H "Authorization: Bearer <service token, operator role>" -H "Content-Type: application/json" \
  -d '{"target_id":"<target uuid>","objective":"Map the public surface and note anything worth a closer look.","execution_mode":"read_only","max_steps":5,"planner":{"mode":"configured_ai"},"autopilot":true}'

Then read and steer it: GET /research/episodes/{id}, POST /research/episodes/{id}/observe, PUT /research/episodes/{id}/autopilot, POST /research/episodes/{id}/cancel.

Requirements:

1. The executor, an explicit opt-in. It is off by default, so an autonomous episode waits at awaiting_planner until you enable it: install or re-render with AUTONOMOUS_HUNT=1 (recorded in deployment.json, so upgrades keep it). GET /research/readiness shows execution_enabled and the configured model.
2. Engine 2.3.4 or later. Earlier engines could not run the autonomous planner.
3. A model that supports structured outputs and is reasonably fast. The planner requests strict JSON-schema output on every step. Small or slow models stall it; a current Claude, GPT or equivalent model that honours response_format: json_schema reasons in seconds.

Beta limits, enforced at the gateway with a named refusal: only read_only and shadow episodes (the engine reasons and investigates without touching the target); gated or active episodes and durable multi-episode campaigns are refused, because they need an approval receipt the self-hosted model does not mint yet.

Raising a Hunt's budget

Raising a Hunt's budget is a person's decision. When a limit runs out the Hunt raises a budget.raise permission request (a Hunt whose limit is spent stops at budget_exhausted until then). Approve it in your own terminal with shakerscan approve <request-id> (or decide every pending request with shakerscan approve --all-pending); the Hunt then continues. You can also allow raises up front for an agent's Hunts (shakerscan agent --allow budget.raise:2x, each limit up to twice its start value), raise it yourself with shakerscan hunt budget raise <hunt> --limit <name>=<N> (client 0.11.2), or raise it on the Hunt page in the browser.

By default a service token can also send POST /hunts/{id}/budget-amendments itself, so an agent that uses your token can raise its own budget, also its safety ceilings (state-changing requests, out-of-band interactions, ports, hosts). The gateway records each such raise in the audit log as made with a token, not proven by a person. That is an accepted risk; to close it, an administrator turns on Require a security-key touch for person decisions from terminals: the raise then needs your touch on a security key, in your own terminal, and the agent gets 403 person_decision_required with the command for you to run. The same holds for the other decisions only a person should make; see Decisions only a person should make.

With the switch on, the Hunts one agent session starts also share one safety budget: the one touch at shakerscan agent --allow approves it with the session's bounds (one balanced Hunt's state-changing requests, ports, hosts, out-of-band interactions and device fragility, raised as its budget.raise bounds raise one Hunt). A running Hunt holds what it may still spend and an ended one what it spent, so cancelling a Hunt and starting a new one with a fresh budget no longer resets anything, as it did up to the ceilings of the budget profile a token asked for before. A Hunt counts only the ceilings it can spend: a read-only Hunt (no state-changing requests, network discovery or out-of-band interactions) counts none, so it starts beside an active one with no touch. A start past what is left is your decision (the agent's line names that start as your command; your touch starts it), and a raise past it becomes the Hunt's own budget.raise request. A connection with no agent session has one balanced Hunt's safety ceilings per 12 hours. With the switch off a token can still start Hunts with a fresh budget, with any authority the target's authorization covers: authorize targets deliberately.

Token hygiene

• A service token is a bearer credential. Anyone holding it can drive Hunts and read the API at the token's role until it expires or is revoked.
• Issue one token per person, operator role only when Hunt is needed, short lifetime (tokens expire within 90 days). Name them so the audit trail is meaningful.
• Revoke a token in the console the moment the person no longer needs it or leaves. Disabling the service account revokes its tokens.
• Never put a token in a URL, a shared file, or a commit. Let shakerscan connect save it (a file only the user can read); the client never prints it and sends it only over HTTPS.

Not in this beta

• Hunt metering or per-Hunt licensing.
• Active or gated autonomous episodes and multi-episode campaigns (see above).
• Device-backed Hunt execution (connected-device fleets are not exposed).
• A hosted, vendor-run Hunt; this is self-hosted only.