Codearia Academy

This Is More Than Just One Guide

12 courses and 29 free guides on AI automation for business — and beyond.

AI pentest · Shannon

Shannon: AI Hacks Your App Before a Hacker Does

A free, open-source AI pentester. It reads your code, attacks the running app and reports only the holes it actually got through. Here is how to run your first test without breaking anything.

FreeOpen sourceNo security background

Run the first test

What's inside

free, in full

1.What Shannon is 2.What you need first 3.The first test 4.Staying safe 5.Testing every release 6.Prompts for Claude Code

The idea

A hacker you hired yourself

AI writes code fast, but it leaves holes. They usually get found after the release, and not by you. Shannon flips the order: you hand it your app before it goes public, and it tries to break in.

It reads the source code, looks for weak spots, then attacks the running app through a browser and the command line. The main rule: no exploit, no report. If it cannot prove a hole with a real attack, the hole stays out of the report. That is why there are almost no false alarms.

false findings on Grok 4.6 and DeepSeek v4 Flash

$6.10

for the cheapest run, on DeepSeek v4 Flash

3 of 3

models found the critical SQL injection

Numbers from Keygraph's own comparison on the open-source app Photoview 2.4.0. In the same study the commercial Aikido and XBOW cost $4,000 per test each.

Diagram: source code and the running app go into Shannon, proven holes go to the report, unproven ones are dropped — Shannon reads the code first, then attacks the live app. Only what it managed to break goes into the report.

Shannon is made by Keygraph. The code is open, and the repository has about 50 thousand stars on GitHub.

Repository on GitHub

Preparation

What you need first

Four things. If one is missing, set it up before the run, or the test will fail halfway.

Docker

Shannon runs inside a container. It pulls the image and starts everything it needs by itself; you only need Docker installed and running.

Node.js 18 or newer

Needed for npx, which runs Shannon without a separate install.

A model key or subscription

Shannon runs on your model: Anthropic, OpenAI, xAI, AWS Bedrock, or a local one through Ollama. Instead of an API key you can use a ChatGPT Plus or Pro subscription or an xAI (Grok) subscription, signed in through Pi. A Claude Code subscription works only with the old version 1.9.0.

Windows only through WSL2

Shannon does not run natively on Windows or in Git Bash. Turn on WSL2, tick "Use the WSL 2 based engine" in Docker Desktop, and run the commands inside WSL.

PowerShell

wsl --install
wsl --set-default-version 2

Clear it with your model provider first

Anthropic and OpenAI watch cyber-security workloads. If their safeguard kicks in mid-run, the model refuses and the test stops halfway. Complete their verification for legitimate security testers, then check the model with the --validate-model flag.

Running it

The first test in five steps

We test a copy of your own app on your own computer. It is the safest option and needs no extra server.

01
Set up the key
The wizard asks for the provider, the key and the model. Run it again any time you want to switch models.
terminal
```
npx @keygraph/shannon@latest setup
```
02
Check the model
The --validate-model flag attacks nothing. It only checks the key and model access, then stops. If the provider declines, you find out now, not an hour later.
terminal
```
npx @keygraph/shannon@latest start \
  -u http://host.docker.internal:3000 \
  -r /path/to/your/repo \
  --validate-model
```
03
Start the test
-u is the address of the running app, -r is the folder with its code. The container cannot see your computer's localhost, so point at a local app through host.docker.internal. The code is mounted read-only.
terminal
```
npx @keygraph/shannon@latest start \
  -u http://host.docker.internal:3000 \
  -r /path/to/your/repo
```
04
Wait
A full test usually takes one to one and a half hours, longer on a big app. You see the progress right in the terminal. You pay only for your model's tokens.
05
If it stopped, resume
A test can be resumed: Shannon does not repeat what it already did. How to name the workspace and resume is in docs/workspaces.md in the repository.

If your app has a login

Without a login Shannon only sees public pages. To test the private part too, give it a test account and describe the login in plain words. Use a throwaway password.

terminal

npx @keygraph/shannon@latest start \
  -u http://host.docker.internal:3000 \
  -r /path/to/your/repo \
  -c ./config.yaml

config.yaml

# config.yaml: only needed when the app has a login
exploit: "true"

report:
  sarif: "true"

authentication:
  login_type: form
  login_url: "http://host.docker.internal:3000/login"
  credentials:
    username: "test-admin"
    password: "a-throwaway-password"
  login_flow:
    - "Go to http://host.docker.internal:3000/login"
    - "Type $username into the Username field"
    - "Type $password into the Password field"
    - "Click the Sign in button"

What you get

A PDF and Markdown report with evidence for every hole, plus JSON and SARIF. GitHub and other code tools read SARIF, so the findings can show up right in your repository.

Illustration: out of many suspicions, only the holes that were actually exploited pass into the report — No exploit, no report. Guesses are filtered out, holes with proof remain.

Safety

Staying safe

Shannon does not just scan, it really attacks. So the rules are simple and strict.

Do

Test apps that you own
Test someone else's app only with the owner's written permission
Run it on a local copy or staging with data you can afford to lose

Don't

Run it against production with live users
Attack sites and services you do not own. It is illegal
Feed it someone else's or suspicious code: an AI that reads code can be tricked by instructions hidden in it

What Shannon can do to a test app

Create new users
Change or delete data
Take over test accounts
Trigger side effects from injection attacks
Send unexpected outbound requests

A human still reads the report

Even proven findings are worth a second look: the AI can get details wrong in the report text. In the same comparison Claude Opus 5 took a normal admin feature for a hole.

Illustration: the test runs in an isolated copy of the app, production stays behind a wall — Shannon attacks a copy on test data. Real users and the real database stay out of it.

Automation

Testing every release in GitHub

Once the first test has passed, you can build it into GitHub Actions. Shannon will then attack staging before a release and stop it if it finds a serious hole.

.github/workflows/shannon.yml

name: Shannon Pentest

on:
  workflow_dispatch:

permissions:
  security-events: write

jobs:
  pentest:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Shannon
        uses: KeygraphHQ/shannon-action@v1
        with:
          url: https://staging.example.com
          api-key: ${{ secrets.SHANNON_AI_API_KEY }}
          fail-on-severity: high
          upload-sarif: true

What it needs

A private repository
A runner with Docker and Docker Compose v2
A running staging the runner can reach
A model key in GitHub Actions secrets

fail-on-severity: high stops the build only on proven high-severity holes. Guesses without an exploit never fail it. upload-sarif shows the findings in the repository's Security tab. GitLab has the same ready-made component.

Illustration: a release passes through the Shannon gate, and does not pass with a serious hole — Every release goes through a pentest first. A proven serious hole means the release waits for a fix.

Ready prompts

Let Claude Code do the routine

Three prompts for three stages: prepare a copy for the test, fix what was found, build the test into releases. Copy and paste them into Claude Code in your project folder.

Prepare a safe copy

Claude Code starts the app on test data and writes config.yaml with the login.

Help me prepare my app for a Shannon pentest. Start a local copy on test data, not production: a separate database with fake users, running on port 3000. Create a test admin with a throwaway password. Then write config.yaml for Shannon in the format from the README at https://github.com/KeygraphHQ/shannon: exploit true, sarif true, a form login with my real field names (find them in the code), URLs through host.docker.internal:3000. Do not touch production settings and do not commit .env.

Fix the findings from the report

One hole at a time, with a test that proves it is closed.

Here is the Shannon report: <path to the Markdown report>. For each finding, one at a time: explain in plain words what the hole is and where it is in the code; write a test that reproduces the attack and fails now; fix the code; run the test. Show me the diff before moving to the next finding. If a finding looks like an intended feature rather than a hole, say so and leave it alone.

Build the test into GitHub

A ready workflow and a hint on which secret to add.

Add the Shannon GitHub Action to this repository, following the example in the KeygraphHQ/shannon README: run it manually and before a release, url is my staging, the model key comes from the SHANNON_AI_API_KEY secret, fail-on-severity high, upload-sarif true. Tell me which secret to add in the repository settings and how to check that the runner can reach staging.

The prompts work in Cursor and Codex too. Look at the diff before you accept changes.

License and editions

The open-source Shannon is licensed under AGPL-3.0: free to use, you pay only for your model. Keygraph also sells cloud editions, Pro and Enterprise, but the open version is enough to test your own app.

What the guide leaves out

Finding a hole is not enough, you need to understand your app

Shannon shows you where the problem is. To fix it calmly, and avoid it next time, you need to understand how the thing you built with AI works. That is what the course "From Chat to App" teaches.

How to build your own app with Claude Code from zero, even with no experience
How the terminal, git and a project fit together, so you understand what the AI writes
How to fix and improve a working app step by step without breaking the rest
How to publish the app and keep it in shape after the release

Next step

The course "From Chat to App"

From your first chat request to your own published app. The terminal, Claude Code, building, fixing and publishing, step by step with assignments.

Go to the course

Shannon is updated fast: commands, models, subscriptions and prices can change. This guide was checked against the KeygraphHQ/shannon README on 28.10.2026. If something does not match, trust the current README.

All free guides

Free Guide

This guide is 100% free

All the commands and prompts are free. If you want to go deeper, we have 12 courses on AI, content and automation. Full access for $44.90.

View courses

Codearia Academy

This Is More Than Just One Guide

12 courses and 29 free guides on AI automation for business — and beyond.

Browse guides Browse courses

AI pentest · Shannon

Shannon: AI Hacks Your App Before a Hacker Does

A free, open-source AI pentester. It reads your code, attacks the running app and reports only the holes it actually got through. Here is how to run your first test without breaking anything.

FreeOpen sourceNo security background

Run the first test

What's inside

free, in full

1.What Shannon is 2.What you need first 3.The first test 4.Staying safe 5.Testing every release 6.Prompts for Claude Code

The idea

A hacker you hired yourself

AI writes code fast, but it leaves holes. They usually get found after the release, and not by you. Shannon flips the order: you hand it your app before it goes public, and it tries to break in.

false findings on Grok 4.6 and DeepSeek v4 Flash

$6.10

for the cheapest run, on DeepSeek v4 Flash

3 of 3

models found the critical SQL injection

Numbers from Keygraph's own comparison on the open-source app Photoview 2.4.0. In the same study the commercial Aikido and XBOW cost $4,000 per test each.

Shannon is made by Keygraph. The code is open, and the repository has about 50 thousand stars on GitHub.

Repository on GitHub

Preparation

What you need first

Four things. If one is missing, set it up before the run, or the test will fail halfway.

Docker

Shannon runs inside a container. It pulls the image and starts everything it needs by itself; you only need Docker installed and running.

Node.js 18 or newer

Needed for npx, which runs Shannon without a separate install.

A model key or subscription

Windows only through WSL2

Shannon does not run natively on Windows or in Git Bash. Turn on WSL2, tick "Use the WSL 2 based engine" in Docker Desktop, and run the commands inside WSL.

PowerShell

wsl --install
wsl --set-default-version 2

Clear it with your model provider first

Running it

The first test in five steps

We test a copy of your own app on your own computer. It is the safest option and needs no extra server.

01
Set up the key
The wizard asks for the provider, the key and the model. Run it again any time you want to switch models.
terminal
```
npx @keygraph/shannon@latest setup
```
02
Check the model
The --validate-model flag attacks nothing. It only checks the key and model access, then stops. If the provider declines, you find out now, not an hour later.
terminal
```
npx @keygraph/shannon@latest start \
  -u http://host.docker.internal:3000 \
  -r /path/to/your/repo \
  --validate-model
```
03
Start the test
-u is the address of the running app, -r is the folder with its code. The container cannot see your computer's localhost, so point at a local app through host.docker.internal. The code is mounted read-only.
terminal
```
npx @keygraph/shannon@latest start \
  -u http://host.docker.internal:3000 \
  -r /path/to/your/repo
```
04
Wait
A full test usually takes one to one and a half hours, longer on a big app. You see the progress right in the terminal. You pay only for your model's tokens.
05
If it stopped, resume
A test can be resumed: Shannon does not repeat what it already did. How to name the workspace and resume is in docs/workspaces.md in the repository.

If your app has a login

Without a login Shannon only sees public pages. To test the private part too, give it a test account and describe the login in plain words. Use a throwaway password.

terminal

npx @keygraph/shannon@latest start \
  -u http://host.docker.internal:3000 \
  -r /path/to/your/repo \
  -c ./config.yaml

config.yaml

# config.yaml: only needed when the app has a login
exploit: "true"

report:
  sarif: "true"

authentication:
  login_type: form
  login_url: "http://host.docker.internal:3000/login"
  credentials:
    username: "test-admin"
    password: "a-throwaway-password"
  login_flow:
    - "Go to http://host.docker.internal:3000/login"
    - "Type $username into the Username field"
    - "Type $password into the Password field"
    - "Click the Sign in button"

What you get

A PDF and Markdown report with evidence for every hole, plus JSON and SARIF. GitHub and other code tools read SARIF, so the findings can show up right in your repository.

Safety

Staying safe

Shannon does not just scan, it really attacks. So the rules are simple and strict.

Do

Test apps that you own
Test someone else's app only with the owner's written permission
Run it on a local copy or staging with data you can afford to lose

Don't

Run it against production with live users
Attack sites and services you do not own. It is illegal
Feed it someone else's or suspicious code: an AI that reads code can be tricked by instructions hidden in it

What Shannon can do to a test app

Create new users
Change or delete data
Take over test accounts
Trigger side effects from injection attacks
Send unexpected outbound requests

A human still reads the report

Even proven findings are worth a second look: the AI can get details wrong in the report text. In the same comparison Claude Opus 5 took a normal admin feature for a hole.

Automation

Testing every release in GitHub

Once the first test has passed, you can build it into GitHub Actions. Shannon will then attack staging before a release and stop it if it finds a serious hole.

.github/workflows/shannon.yml

name: Shannon Pentest

on:
  workflow_dispatch:

permissions:
  security-events: write

jobs:
  pentest:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Shannon
        uses: KeygraphHQ/shannon-action@v1
        with:
          url: https://staging.example.com
          api-key: ${{ secrets.SHANNON_AI_API_KEY }}
          fail-on-severity: high
          upload-sarif: true

What it needs

A private repository
A runner with Docker and Docker Compose v2
A running staging the runner can reach
A model key in GitHub Actions secrets

Ready prompts

Let Claude Code do the routine

Three prompts for three stages: prepare a copy for the test, fix what was found, build the test into releases. Copy and paste them into Claude Code in your project folder.

Prepare a safe copy

Claude Code starts the app on test data and writes config.yaml with the login.

Help me prepare my app for a Shannon pentest. Start a local copy on test data, not production: a separate database with fake users, running on port 3000. Create a test admin with a throwaway password. Then write config.yaml for Shannon in the format from the README at https://github.com/KeygraphHQ/shannon: exploit true, sarif true, a form login with my real field names (find them in the code), URLs through host.docker.internal:3000. Do not touch production settings and do not commit .env.

Fix the findings from the report

One hole at a time, with a test that proves it is closed.

Here is the Shannon report: <path to the Markdown report>. For each finding, one at a time: explain in plain words what the hole is and where it is in the code; write a test that reproduces the attack and fails now; fix the code; run the test. Show me the diff before moving to the next finding. If a finding looks like an intended feature rather than a hole, say so and leave it alone.

Build the test into GitHub

A ready workflow and a hint on which secret to add.

Add the Shannon GitHub Action to this repository, following the example in the KeygraphHQ/shannon README: run it manually and before a release, url is my staging, the model key comes from the SHANNON_AI_API_KEY secret, fail-on-severity high, upload-sarif true. Tell me which secret to add in the repository settings and how to check that the runner can reach staging.

The prompts work in Cursor and Codex too. Look at the diff before you accept changes.

License and editions

What the guide leaves out

Finding a hole is not enough, you need to understand your app

Shannon shows you where the problem is. To fix it calmly, and avoid it next time, you need to understand how the thing you built with AI works. That is what the course "From Chat to App" teaches.

How to build your own app with Claude Code from zero, even with no experience
How the terminal, git and a project fit together, so you understand what the AI writes
How to fix and improve a working app step by step without breaking the rest
How to publish the app and keep it in shape after the release

Next step

The course "From Chat to App"

From your first chat request to your own published app. The terminal, Claude Code, building, fixing and publishing, step by step with assignments.

Go to the course

All free guides

Free Guide

This guide is 100% free

All the commands and prompts are free. If you want to go deeper, we have 12 courses on AI, content and automation. Full access for $44.90.

View courses

Guide text

This Is More Than Just One Guide

Shannon: AI Hacks Your App Before a Hacker Does

What's inside

A hacker you hired yourself

What you need first

Docker

Node.js 18 or newer

A model key or subscription

Windows only through WSL2

Clear it with your model provider first

The first test in five steps

Set up the key

Check the model

Start the test

Wait

If it stopped, resume

If your app has a login

What you get

Staying safe

Do

Don't

What Shannon can do to a test app

A human still reads the report

Testing every release in GitHub

What it needs

Let Claude Code do the routine

Prepare a safe copy

Fix the findings from the report

Build the test into GitHub

License and editions

Finding a hole is not enough, you need to understand your app

The course "From Chat to App"

This guide is 100% free

From Chat to App: 3 Ways to Put AI to Work

More guides on this topic

Read next

Comments

This Is More Than Just One Guide

Shannon: AI Hacks Your App Before a Hacker Does

What's inside

A hacker you hired yourself

What you need first

Docker

Node.js 18 or newer

A model key or subscription

Windows only through WSL2

Clear it with your model provider first

The first test in five steps

Set up the key

Check the model

Start the test

Wait

If it stopped, resume

If your app has a login

What you get

Staying safe

Do

Don't

What Shannon can do to a test app

A human still reads the report

Testing every release in GitHub

What it needs

Let Claude Code do the routine

Prepare a safe copy

Fix the findings from the report

Build the test into GitHub

License and editions

Finding a hole is not enough, you need to understand your app

The course "From Chat to App"

This guide is 100% free