Run the Shannon AI pentester on a disposable VM

Install#

Deploy installs Shannon, starts Juice Shop as a practice target, and checks that Shannon can log in to it. It doesn't start a scan: that's yours to start. To do it yourself:

ssh exe.dev new --name=my-shannon
ssh my-shannon.exe.xyz

sudo systemctl enable --now docker.service
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g @keygraph/shannon@3
shannon version
docker pull keygraph/shannon:$(shannon version | awk '{print $2}')

mkdir -p ~/.shannon
install -m 600 /dev/null ~/.shannon/config.toml
cat > ~/.shannon/config.toml <<'EOF'
[core]
model = "anthropic:claude-sonnet-5"
base_url = "https://llm.int.exe.xyz"

[anthropic]
api_key = "exe-llm-integration"
EOF

docker run -d --name juice-shop --restart unless-stopped -p 3000:3000 bkimminich/juice-shop:v20.3.0
git clone --depth 1 --branch v20.3.0 https://github.com/juice-shop/juice-shop.git ~/juice-shop
sleep 15
curl -s -X POST localhost:3000/rest/user/login -H 'Content-Type: application/json' \
  -d '{"email":"jim@juice-sh.op","password":"ncc-1701"}' | head -c 40; echo

mkdir -p ~/scans
cat > ~/scans/juice-shop.yaml <<'EOF'
description: "OWASP Juice Shop v20.3.0, a deliberately vulnerable training app, in Docker on this disposable exe.dev VM. Test data only."
rules_of_engagement: |
  - The only target is http://host.docker.internal:3000. Send no requests to any other host.
  - Never target exe.dev infrastructure: no requests to *.exe.xyz, *.int.exe.xyz, *.exe.dev or 169.254.169.254.
  - For SSRF, prove impact against the target itself, not against third-party hosts.
authentication:
  login_type: form
  login_url: "http://host.docker.internal:3000/#/login"
  credentials:
    username: "jim@juice-sh.op"
    password: "ncc-1701"
  login_flow:
    - "If a 'Welcome to OWASP Juice Shop' dialog is shown, click 'Dismiss'"
    - "If a cookie banner is shown, click 'Me want it!'"
    - "Type $username into the Email field"
    - "Type $password into the Password field"
    - "Click the 'Log in' button"
  success_condition:
    type: url_contains
    value: "/search"
EOF
chmod 600 ~/scans/juice-shop.yaml

shannon start -u http://host.docker.internal:3000 -r ~/juice-shop \
  -c ~/scans/juice-shop.yaml -w login-check --validate-auth

Before you scan#

A scan is a real attack, so decide what it may touch:

• The target is yours. Juice Shop on this VM is built to be attacked. For your own app, see Scan your own app.

• Nothing else is in reach. Shannon follows the rules of engagement in the config, but it's an agent, so also limit what the VM can reach. With the egress policy set to integrations, the VM can reach exe.dev's integrations — the LLM one, and a target reached through a VM-to-VM integration — and nothing on the internet. On your computer:

  ssh exe.dev egress my-shannon integrations
  

  Traffic that never leaves the VM, like the practice target on host.docker.internal, is unaffected. Run the login check from "Check the setup" again after changing the policy to confirm. Set it back with ssh exe.dev egress my-shannon all when you need to install or update something.

• The model will cooperate. Anthropic and OpenAI apply safeguards to security work. Shannon checks before every scan and stops early if the provider declines, but a refusal can still end a scan partway.

Run your first scan#

On the VM:

shannon start -u http://host.docker.internal:3000 -r ~/juice-shop \
  -c ~/scans/juice-shop.yaml -w juice-1

Shannon runs its checks, starts the scan in a container of its own, and returns you to the prompt. The scan takes an hour or more and carries on when you log out. From any SSH session:

shannon status juice-1   # phases and agents, done and pending
shannon logs juice-1     # the live log; Ctrl-C stops following, not the scan
shannon scans            # every scan on this VM
shannon stop juice-1     # stop it

For more detail, open Temporal's web UI. It listens only on the VM's localhost, so tunnel to it from your computer and open http://localhost:8233/:

ssh -L 8233:localhost:8233 my-shannon.exe.xyz

If a scan is interrupted, run the same shannon start command with the same -w name: Shannon resumes it and skips the agents that finished.

Read the report#

Each scan leaves a workspace in ~/.shannon/workspaces/<name>/, with the report at the top:

• Security-Assessment-Report.pdf and Security-Assessment-Report.md: each finding with the proof that it was exploited.
• report.sarif: the same findings for GitHub code scanning or any other SARIF reader.
• .shannon/: logs, prompts, screenshots, and each agent's notes.

On your computer, copy the workspace off the VM:

scp -r my-shannon.exe.xyz:.shannon/workspaces/juice-1 ./shannon-juice-1

The report contains working exploits for your app. Keep it like any other secret. And review it: Keygraph says a model can still get details wrong.

Scan your own app#

Shannon needs your app's source and a running copy with test data. The copy should be disposable: a staging or review deployment, or a throwaway run on a VM. Two ways to place it:

On this VM, next to Shannon — the simplest, and the attack never leaves the VM:

1. Clone your repository into ~/myapp, for example through the GitHub integration, so no token lands on the VM. Shannon mounts it read-only.
2. Start the app on the VM the way you run it locally, such as docker compose up -d, with test data and test accounts only.

On another VM of yours — the natural home for a staging app, like the test and prod VMs in Dev, Test, Prod. Don't open it to the internet for this: a VM-to-VM integration gives the Shannon VM a private HTTPS address for it, with a generated key injected at exe.dev's edge so neither VM holds a credential. Serve the app on the target VM's port 8000, the web port, then on your computer:

ssh exe.dev integrations add http-proxy --name myapp --target https://my-shannon-target.exe.xyz/ --peer --attach vm:my-shannon

my-shannon-target stands for the target VM's own name. From the Shannon VM, the app is now at https://myapp.int.exe.xyz/, and that address keeps working with the egress policy set to integrations. (This page's own end-to-end test ran the same shape — Shannon on one VM attacking Juice Shop on a second over its HTTPS address — and got 29 proven findings, including SQL injection with a forged admin session, in about an hour and a half with claude-sonnet-5.)

Then, either way:

3. Copy ~/scans/juice-shop.yaml to ~/scans/myapp.yaml and chmod 600 it, since it will hold a test account's password. Change description, the target in rules_of_engagement — http://host.docker.internal:<port> or https://myapp.int.exe.xyz, and that host only — and the login. Keygraph's configuration guide covers TOTP, magic links, and rules to avoid or focus on paths.

4. Check the login, then scan:

   shannon start -u https://myapp.int.exe.xyz -r ~/myapp -c ~/scans/myapp.yaml -w myapp-check --validate-auth
   shannon start -u https://myapp.int.exe.xyz -r ~/myapp -c ~/scans/myapp.yaml -w myapp-1
   

One VM per scan#

For regular scans, keep this VM as a template and scan in copies. A copy has Shannon, the worker image, and the config already, and keeps the template's egress policy. On your computer:

ssh exe.dev cp my-shannon my-shannon-scan1
ssh my-shannon-scan1.exe.xyz

Run the scan in the copy, copy the workspace off it as in Read the report, and delete it:

ssh exe.dev rm my-shannon-scan1

To script that, the same commands are in exe.dev's HTTPS API, the Python SDK, and the MCP server, so an agent can make the VM, run the scan, and fetch the report for you.

Use your own model key#

The LLM integration bills model use to your exe.dev account, and the provider's safeguards see exe.dev's account. To use your own Anthropic or OpenAI organization, one that has done the provider's security verification, add a separate LLM integration with your key, attached only to this VM. The VM can use the key but never read it. On your computer:

printf '%s' "$ANTHROPIC_API_KEY" | ssh exe.dev integrations add llm --name shannon-llm --anthropic=byok --anthropic-key=- --openai=disabled --fireworks=disabled --attach vm:my-shannon

On the VM, point Shannon at it by changing one line in ~/.shannon/config.toml:

base_url = "https://shannon-llm.int.exe.xyz"

To use OpenAI instead, set model = "openai:gpt-5.6-sol", move the placeholder key to an [openai] section, and end base_url in /v1. Keygraph's AI providers guide lists the models Shannon knows.

Update#

On the VM:

sudo npm install -g @keygraph/shannon@3
docker pull keygraph/shannon:$(shannon version | awk '{print $2}')

Shannon removes older worker images itself. Check the releases first: they sometimes change the config.

Clean up#

When you're done, keep the reports and delete the VM. On your computer:

ssh exe.dev rm my-shannon

To keep the VM but clear out old scans, shannon stop --all stops any that are running, and shannon reset wipes Temporal's history. Workspaces are plain directories in ~/.shannon/workspaces/. To reset Juice Shop's data, restart it: docker restart juice-shop. When the target was a whole VM of its own, delete that too: ssh exe.dev rm my-shannon-target.

Troubleshooting#

• Your config file is readable by other users: run chmod 600 ~/.shannon/config.toml.
• Preflight fails on the model: check the integration from the VM with curl -s https://llm.int.exe.xyz/v1/messages -H 'content-type: application/json' -H 'anthropic-version: 2023-06-01' -d '{"model":"claude-sonnet-5","max_tokens":20,"messages":[{"role":"user","content":"hi"}]}'. A plain reply means the gateway is fine. Shannon checks model names against its own catalogue, so a name the integration knows may still be refused; use one from Keygraph's list.
• The provider declined the security workload: the scan stops with a link to the provider's verification program. Complete it, or use your own key as above.
• The target can't be reached: from inside a container, localhost is the container. Use http://host.docker.internal:<port> for apps on the VM, and make sure the app's port is published (docker ps, ss -ltn). For an app on another VM, check the integration address from the VM first: curl -s https://myapp.int.exe.xyz/.
• The login check fails: write login_flow the way you'd log in by hand in a private window, with the exact labels and button texts. Juice Shop's welcome dialog and cookie banner are the usual culprits.
• A scan stalls or fails: shannon logs <name> shows the combined log, shannon logs <name> --list-agents the per-agent logs, and Temporal's UI each step's error. Running the same start again resumes.
• After a reboot: Docker comes back with Juice Shop; Shannon starts Temporal again with the next shannon start.