ShakerScan
Install ShakerScan
Pinned to v2.12.2Read as MarkdownView source on GitHub Report an issue

ShakerScan

Open-source security testing for web applications, APIs, AI systems, and network-connected devices.

ShakerScan runs locally in Docker and provides a web UI, REST API, CLI, one deterministic Scan, and an agent-driven Hunt. Every network action is bound to an authorized target, metered against a budget, and recorded as evidence; only deterministic proof marks a finding verified.

Responsible use. Test only systems you own or are explicitly authorized to assess. Unauthorized scanning may be illegal and can disrupt services. You are responsible for how you use this software; it is provided without warranty (see LICENSE).

Quick start

Requirements: Linux or macOS with Docker and Docker Compose v2 (the installer can install them), and at least 8 GB of RAM for the full engine.

Install and start ShakerScan:

curl -fsSL https://install.shakerscan.com | sh

The installer downloads a tagged release, verifies every file against the release manifest, and pulls digest-pinned images. To read it first: curl -fsSL https://install.shakerscan.com -o install.sh.

Targets groups root domains with expandable subdomains and keeps discovery on each domain. Use Web and IP / network filters to focus the inventory; an IP with a web service can appear in both views while retaining one target identity. Hunt can manage target metadata and instructions by default. Target detail includes Hunt permissions to disable these edits, approve specific shared inputs, and save SSH host trust once.

Then open:

Check the installation:

shakerscan status

Run a scan:

shakerscan scan https://app.example.test

For authorized active testing:

shakerscan scan https://app.example.test \
  --budget-profile thorough \
  --active-testing \
  --confirm-active

Use an AI agent

ShakerScan ships AGENTS.md and task skills for Codex, Claude Code, OpenCode, and Pi. Start the agent through ShakerScan so runtime URLs, planner identity, and agent-specific integration are applied:

shakerscan agent             # auto-detects codex, claude, opencode, then pi
shakerscan agent opencode    # or name one: codex, claude, opencode, or pi

The agent can drive Hunt, inspect findings, use saved credentials and request collections, and work through the same server-side authorization, scope, budget, evidence, and proof controls as the UI and CLI. Pi has no MCP client; the launcher passes the canonical ShakerScan skills and slash commands explicitly and Pi drives the instance through shakerscan api, scan, and hunt. The .claude/ directory contains the same commands and agents for Claude Code.

What to use

  • Scan — reproducible web/API assessment with fast, balanced, and thorough ceilings.
  • Hunt — adaptive investigation of an authorized web, API, network, or device target.
  • Connected Devices — inventory and assess network targets with dedicated scanning capacity started automatically. Use shakerscan devices stop to disable that capacity on smaller installations, and shakerscan devices start to re-enable it.

The Targets inventory groups root domains with their subdomains and keeps IP addresses and internal hosts independently selectable. Add a bare domain or IP with optional port hints, or an application URL. Domain grouping is navigation only; it does not share authorization or credentials across hosts.

  • AI Gate — test chat, RAG, agent, and MCP application surfaces.
  • Model Intake — inspect model artifacts before deployment.
  • ASM — maintain attack-surface inventory and coverage.

How it works

 Browser UI / CLI / MCP client / coding agent
                  |
                  v
        API (FastAPI, loopback by default)
        - target binding, scope and authorization
        - budgets, evidence, proof contracts
                  |
       +----------+-----------+
       |                      |
  PostgreSQL + Redis     Scan / Hunt workers
  (loopback, generated   - bounded capabilities from one registry
   passwords)            - nuclei, httpx, katana, sqlmap, testssl.sh, Nmap NSE, ...
                         - every request pinned to the authorized target and metered

Hunt is planned by the coding agent you run (Codex, Claude Code, OpenCode, or Pi); ShakerScan keeps target binding, scope, policy, approval, budget, execution, evidence, and proof on the server. Architecture details are in the documentation index.

Each target can store instructions, learned knowledge and named Saved Hunt actions. Actions compose canonical tool calls or a remote SSH command with typed parameters; saving one performs no testing. Hunt loads their index at startup and can read, create, update and delete them when target metadata edits are enabled. The Live SSH tab streams command output with the selected stored identity, supports cancellation and can save a useful command as an action.

Hunt can watch SSH logs while checking the same asset's web services. Its agent worker runs bounded concurrent jobs; device Hunts allow one SSH command alongside one external traffic action while preserving device health pauses and all budgets. Browser workflows can submit authorized forms and clean up test objects. authz.verify supports object comparisons and repeated function-access matrices; role intent is never inferred from a successful response. Camera/router methodologies include RTSP OPTIONS, SSH algorithm/key inspection and bounded SNMPv3 engine discovery.

LAN server

To run the engine on one trusted machine and control it from another:

# engine machine
shakerscan start --lan

# laptop/client
pipx install shakerscan
shakerscan connect http://192.168.1.50:8080

LAN mode does not add authentication or encryption. Fresh OSS installs remain localhost-only. See the LAN access guide.

Security model

  • The open-source API has no login; it binds to 127.0.0.1 by default. Anyone who can reach it can operate the engine, and the API can use the Docker socket, so keep it on loopback or a trusted network.
  • Targets need explicit authorization before active testing; scope, budgets, and approvals are enforced server-side, not by the UI or the agent.
  • Stored credentials, including secret headers in an AI target's header template, and the raw headers and bodies recorded in the HTTP archive are encrypted at rest. Normal API and planner responses redact secrets; explicit raw HAR exports include captured credentials. Verbatim HAR export is on by default only for a loopback install.
  • Remote commands over SSH (Hunt ssh.exec, the live console, saved actions) need an explicit grant on the SSH credential and a pinned host key, saved by the operator or pinned on first contact when that is authorized. Device scans run fixed read-only review commands and only operator-confirmed shell plans over the device's SSH credential.
  • Release images are digest-pinned, scanned, and published with SBOMs and build attestations.

Read SECURITY.md for the full trust boundaries and how to report a vulnerability.

Your data

  • Delete targets, domains, credentials, request collections, scans, Hunts, AI targets and Model Intake submissions from the UI or API. Deletion previews what it removes, asks for confirmation, and removes the stored secrets with the records.
  • Back up with shakerscan backup, list with shakerscan backup list, and remove with shakerscan backup delete <name|all>. The newest five backups are kept (SHAKERSCAN_BACKUP_KEEP). The encryption key is left out unless you pass --include-key, so keep results/.credential_enc.key safely elsewhere: without it a restored backup cannot decrypt stored secrets. A backup still holds .env (generated passwords and tokens) and all evidence; store it as carefully as the host.

Troubleshooting

shakerscan status          # engine and worker health
shakerscan doctor          # connectivity and configuration checks
./scanner.sh logs -f       # follow service logs (from ~/.shakerscan)

A scan that fails is best diagnosed from shakerscan api GET /scans/<id>/actions and the worker logs. If start reports that storage preparation (api-storage-init) failed, the credential encryption key results/.credential_enc.key is unreadable, empty or damaged: restore it from your safe copy. Removing it starts the engine with a new key, and stored credentials can no longer be decrypted. Open an issue if you are stuck.

Documentation

Start with shakerscan --help, the UI, or the live API contracts:

shakerscan api GET /openapi.json
shakerscan api GET /scan/contracts
shakerscan api GET /hunts/contract

Engineering and architecture documentation is in the docs directory. For agent behavior and product invariants, see AGENTS.md. Release notes are listed in CHANGELOG.md.

Acknowledgements

ShakerScan is built on outstanding open-source security work, including ProjectDiscovery's nuclei, httpx, katana, subfinder, naabu and tlsx; sqlmap by Bernardo Damele A. G. and Miroslav Stampar; Nmap by Gordon Lyon and the Nmap Project; testssl.sh by Dirk Wetter; dalfox by hahwul; ffuf by Joona Hoikkala; meg by Tom Hudson; gungnir by g0lden; SecLists by Daniel Miessler and contributors; Retire.js; Playwright; Trivy; and many more. The full list of components, authors and licences is in THIRD_PARTY_NOTICES.md.

Contributing

Bug reports, false-positive/false-negative reports, and feature requests are very welcome. The project does not accept outside code contributions; see CONTRIBUTING.md.

License

Copyright (C) 2026 Andriy (@andriyze).

ShakerScan is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). Bundled third-party components keep their own licences; see NOTICE and THIRD_PARTY_NOTICES.md. "ShakerScan" is a trademark of its author; see TRADEMARKS.md.

This page is rendered from README.md in the open-source repository at v2.12.2. When documentation and implementation disagree, the code, database schema, and tests at that tag are authoritative.