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. Hunt is a preview in this beta.

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 AI verification and AI classification of findings, and are what the autonomous Hunt (the engine reasoning on its own with your model) will use; the autonomous Hunt does not work yet in this beta (see below). 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 or off (administrator)

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 and is audited. (On the host, SHAKERSCAN_ENTERPRISE_HUNT=off in enterprise.env, or install.sh --hunt off, 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. 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. All three drive the interactive Hunt: you or your agent do the reasoning.

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) 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.

The autonomous Hunt: not working yet in this beta

The autonomous Hunt is the path where the engine runs its own reasoning loop against a target with the model credentials you configure, as a single bounded research episode. The gateway exposes the research-episode routes (/research/episodes, /research/readiness) and, even with the engine's executor enabled (AUTONOMOUS_HUNT=1), an episode is created but does not advance past awaiting_planner in the Enterprise deployment. Do not plan a pilot around it; use the browser, an agent over MCP, or the CLI instead. This page will describe how to run it once it works end to end.

When it ships, the beta limits enforced at the gateway stay the same: 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 with a named refusal, because they need an approval receipt the self-hosted model does not mint yet.

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.
• A working autonomous Hunt (episodes stall at awaiting_planner), and, once it works, 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.