shakerscan

Files (3)

• SKILL.md
• openai.yaml · agents/
• model-intake.md · references/

SKILL.md (first lines)

# ShakerScan

Use ShakerScan through its local REST API and operational wrapper. ShakerScan owns execution,
target binding, approvals, budgets, evidence, and finding proof.

## Establish Context

1. Run from the ShakerScan runtime or source checkout.
2. Use `http://localhost:8080` for a loopback-bound install. If `./scanner.sh status` reports a
   Tailscale or other host-published API URL, use that URL even for commands executed on the host;
   remote mode may not publish the API on `127.0.0.1`.
3. Set `UI_BASE` to the UI URL printed by `./scanner.sh status` and use it for user-facing links. Do
   not hardcode localhost links for a remote VPS.
   Set `API_BASE` to the API URL from the same status output.
4. Check health before an operation:

   ```bash
   shakerscan api GET /health
   ```

5. If the scanner is stopped, offer `./scanner.sh start`; use `./scanner.sh start --remote` only when
   the user needs remote access over Tailscale.

## Choose The Workflow

| User intent | ShakerScan surface |
|---|---|
| “Scan this target” | `POST /scans` with budget and policy; no scan type |
| Legacy quick/standard/deep/full/aggressive/smart request | Map to Scan V2 and surface the deprecation warning |
| Hunt, autonomous investigation, web or device security hunt | Use the `hunt` skill and `/hunts/*` |
| Explain, compare, or triage a connected device without traffic | Use the `device-triage` skill |
| Multiple targets | `POST /scans/batch` |
| Authenticated or two-user testing | `POST /scans` with auth options |
| Targets and subdomains | `/targets`, `/domains`, `/discovery` |
| Continuous endpoint coverage | `/targets/{id}/asm/*` |
| Connected-device inventory, policy, credentials, and posture | `/devices*`, `/device-policies*` |
| Findings, cleanup, triage, or retest | `/findings*`, `/retests*` |
| Archive or permanently delete a target | `/delete-target`: `POST /targets/{id}/archive` (reversible), or preview → dangerous approval → `POST /data-deletion/execute`, only on the user's explicit request |
| Finding exceptions and deployment policies | `/finding-exceptions*`, `/policy-profiles*` |
| AI chat, RAG, agent, MCP, or widget testing | `/ai/targets*` |
| Model artifact intake | `/model-intake/*` |
| Schedules and safe automation defaults | `/schedules*`, `/settings/automation` |
| Evidence export or retention | `/evidence/*` |
| Mission timeline and read-only campaign ledger | `/timeline`, `/arsenal/campaigns*` |
| Natural-language operation preview | `/ai/ops/route` |
| Interactive browser or BOLA/IDOR workflow | Use the `ai-security-session` skill (Interactive Testing) |
| JS or frontend attack-surface analysis | Use the `js-analyze` skill |
| Content-discovery seeds | Use the `content-discovery` skill |
| Health, queue, and workers | `/health`, `/queue/stats`, `/workers` |
| Multi-node fleet setup or operations | Check `/workers.fleet`, then use `shakerscan fleet *`, `shakerscan join`, and `/fleet/*` only when supported/enabled |
| Exhaustive operation or schema lookup | Read `AGENTS.md` and the live `/openapi.json` (open-source engine; an Enterprise gateway refuses it, use `/hunts/contract`, `/scan/contracts` and the MCP tool schemas) |

Web Scan and Hunt use one durable target per host. Different HTTP(S) schemes and ports share
findings, inventory, credentials, and history, while each scan or hunt keeps its exact concrete
origin. Model Intake artifacts remain exact-subject targets.

## Apply Safety Gates

- Never scan a target without ownership or explicit authorization.
- Active Scan policy and active Hunt capabilities require explicit target authorization. A larger
  budget changes ceilings only; it does not grant active permission. A person raises a Hunt's
  budget (approving its `budget.raise` request, or on the Hunt page); an agent never calls
  `POST /hunts/{id}/budget-amendments` or sends `operator_confirmed`.
- Hunt is one target-kind-aware workflow. Confirm authorization for the exact web or device target;
  keep immutable scope, worker-only credentials, device fragility/circuit-breaker controls, and
  separately confirmed SSH plans intact.
- Treat credentials, auth headers, cookies, API keys, and approval receipts as secrets. Do not echo
  them in reports.
- Production AI Gate scans require their production confirmation.
- Auth checks require a primary auth context. BOLA/IDOR requires a provably distinct second
  principal plus the applicable deep-intent and approval gates.
- Do not bypass a rejected scope, approval, risk, or budget decision.
- Do not call a finding verified from a title, status code, reflection, or model judgment alone.
  Use ShakerScan proof and retest records.
- Keep Model Intake preflight and admission structurally distinct. `POST /model-intake/scan` is always
  non-deployable technical preflight. When the user asks whether a model may enter a corporate supply
  chain, use the controlled `/model-intake/submissions/*` workflow and read
  `skills/shakerscan/references/model-intake.md` before acting.
- Never replace unavailable Firecracker/KVM execution with the semantic container sandbox, QEMU, Docker,
  or an agent claim. Report `NOT_READY`/`INCOMPLETE`. The optional Model Intake coding-agent loop is
  advisory only and cannot approve, freeze evidence, change policy, sign, promote, or suppress a non-pass.
- Connected-device scans are a separate namespace. Require exact-device authorization; never guess
  credentials, discover a whole LAN, or route Device findings through Web DAST replay. Use encrypted
  device credential profiles only with `authenticated_active`; the planner never receives secrets.

## Execute

For a normal scan:

```bash
shakerscan api POST /scans '{"target":"https://app.example.test","budget_profile":"balanced","policy":{"active_testing":false}}'
```

After any action queues a scan, ASM job, AI Gate run, Model Intake run, or finding retest:

1. Report the returned ID and accepted/queued state.
2. Report the UI link `${UI_BASE}/scans/{scan_id}` when a scan ID exists.
3. Stop. Do not poll unless the user explicitly asks later.

For batch submissions, report `queued_count`, `failed_count`, and per-target errors. Never report the
requested count as successfully queued when the response is partial.

### Model Intake routing

- “Inspect/scan this model” means provider-neutral technical preflight unless the user explicitly asks for
  corporate admission or deployment approval.
- For the ordinary one-link request, call `/model-intake/resolve` with the pasted reference, take the
  server-returned `scan_payload`, and queue it with complete artifact acquisition, complete repository
  snapshot, generated scanners, and dynamic sandbox enabled. Do not ask the user to choose an artifact file
  when the resolver already selected one. Report unavailable runtime/signing/evaluation controls as gaps.
- “Can we use/admit/approve/deploy this model?” means the authenticated controlled workflow: submission,
  completed static scan binding, exact-subject Firecracker evidence, frozen evidence, separated human
  approvals, deterministic policy, and isolated signer promotion.
- For a complete review, inspect the License BOM and Third-Party Notices draft as well as the SBOM/AIBOM.
  Trivy is the sole external license scanner. Unknown, custom, reciprocal, dataset-related, conflicting, or
  use-case-dependent terms remain `LEGAL REVIEW REQUIRED` until a distinct legal reviewer approves the latest
  frozen evidence; never translate `NO LEGAL BLOCKER DETECTED` into legal approval.
- Inspect `/model-intake/scanners/readiness` and `/model-intake/runners/readiness` before promising coverage.
  Missing required tools or physical KVM is a non-pass, not a reason to omit the control.

From andriyze/shakerscan, AGPL-3.0.

More from andriyze/shakerscan