https://github.com/pitimon/shannon-pentest
Claude Code plugin to orchestrate Shannon autonomous pentester — configure, launch, monitor, and analyze security assessments with bilingual Thai+English output
https://github.com/pitimon/shannon-pentest
autonomous-security bug-bounty claude-code-plugin owasp penetration-testing pentest security-audit shannon vulnerability-scanner web-security
Last synced: about 1 month ago
JSON representation
Claude Code plugin to orchestrate Shannon autonomous pentester — configure, launch, monitor, and analyze security assessments with bilingual Thai+English output
- Host: GitHub
- URL: https://github.com/pitimon/shannon-pentest
- Owner: pitimon
- License: mit
- Created: 2026-02-27T13:10:41.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-11T22:00:47.000Z (about 1 month ago)
- Last Synced: 2026-05-12T00:00:15.224Z (about 1 month ago)
- Topics: autonomous-security, bug-bounty, claude-code-plugin, owasp, penetration-testing, pentest, security-audit, shannon, vulnerability-scanner, web-security
- Language: Shell
- Homepage: https://github.com/KeygraphHQ/shannon
- Size: 305 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Shannon Pentest — Claude Code Plugin
[](CHANGELOG.md)
[](https://github.com/pitimon/shannon-pentest/actions/workflows/validate.yml)
[](LICENSE)
[](https://github.com/pitimon/shannon-pentest)
**Orchestrate autonomous penetration testing from Claude Code** — describe your target in plain language, and Shannon handles the rest: configuration, launch, monitoring, and findings analysis with bilingual Thai+English output.
### Why Shannon?
| Problem | Shannon's Solution |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| Manual pentest setup takes hours of config | **Natural language** — just say "pentest my staging app" |
| Missed vulnerability classes from narrow scopes | **9 parallel agents** — XSS, SQLi, SSRF, auth bypass, and more |
| Reports require security expertise to interpret | **Auto-analysis** with CVSS v4.0, OWASP Top 10, MITRE ATT&CK mapping |
| Tool context-switching slows you down | **Stays in Claude Code** — configure, launch, monitor, analyze in one place |
| Repeated scans waste API budget | **v1.2.0 optimizations** — 17.7% cheaper with smarter pre-recon |
---
## Proven Results
> Real metrics from QA testing on a live WordPress target (v1.2.0):
| Metric | Value |
| ------------------ | --------------------------------------------------- |
| Total duration | **81.4 minutes** |
| Total cost | **$18.71** |
| Pre-recon savings | **76% cheaper** vs previous version |
| Config validation | **First-try success** (3-step pre-validation) |
| Findings | **6 confirmed vulnerabilities** across 3 categories |
| Agent success rate | **9/9 agents** completed |
---
## Quick Start
```bash
# 1. Install the plugin
claude plugin marketplace add pitimon/shannon-pentest
claude plugin install shannon-pentest@pitimon-shannon
# 2. Launch a pentest (just describe your target)
```
Then in Claude Code:
```
"pentest my web app at https://staging.example.com"
```
Shannon walks you through target configuration, launches the scan, monitors progress automatically, and delivers a structured findings report — all within your Claude Code session.
---
## How It Works
```
Phase 0 Phase 1 Phase 2 Phase 3 Phase 4 Phase 4.5 Phase 5
Setup → Configure → Launch → Monitor → Analyze → Inline → Handoff
Docker Target URL Config Auto-poll Parallel Defense Defensive
Shannon Auth type validation every 2-5min Read calls IR checklist docs prompt
API key YAML config Pre-flight Stall detect CVSS/OWASP Remediation Clipboard
(auto) Web-only Safety confirm Auto-transition PDF/SARIF/HTML Compliance copy
detection ./shannon start → Phase 4 Finding tags quick-map → cyber-pro
```
| Phase | What happens |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| **0. Setup** | Verify Docker & Shannon, auto-configure API key from your Claude Code session |
| **1. Configure** | You provide a target URL and auth type → plugin generates YAML config with smart target-type detection |
| **2. Launch** | Config pre-validation (YAML/schema/types) → pre-flight checks → safety confirmation → `./shannon start` |
| **3. Monitor** | Auto-poll every 2-5 min, stall detection at 10 min, auto-transition when scan completes |
| **4. Analyze** | Parallel read → severity summary, CVSS v4.0, OWASP Top 10, PDF/SARIF/HTML export, finding lifecycle tags |
| **4.5. Defense** | Inline IR checklist, per-finding remediation skeleton, OWASP/NIST compliance quick-map (no plugin needed) |
| **5. Handoff** | Pre-generate cybersecurity-pro prompt, clipboard copy, structured manifest for full defensive documentation |
---
## Usage Examples
### Natural Language
Type `/shannon-pentest` or ask naturally:
```
"pentest my web app at https://staging.example.com"
"run Shannon against the staging environment"
"security audit my application"
"ทดสอบเจาะระบบ staging"
"find vulnerabilities in my app"
```
### Direct Routing
Skip to a specific phase or reference:
```
"analyze Shannon report" → Phase 4 (report analysis)
"export Shannon report as PDF" → Multi-format export (PDF/SARIF/HTML)
"generate SARIF from findings" → SARIF export for GitHub Security tab
"tag finding as false positive" → Finding lifecycle (status tagging)
"show remediation status" → Remediation status report
"list Shannon workspaces" → CLI workspace manager
"inline defense from findings" → Phase 4.5 (IR checklist + remediation)
"create tickets from findings" → Issue template generation (GitHub/Jira)
"export SARIF report" → SARIF export for GitHub Security tab
"integrate Shannon with CI/CD" → CI/CD pipeline templates
"verify fix for stored XSS" → Remediation verification (retest)
"save this scan config" → Scan templates (save/load profiles)
"suppress this finding" → Finding suppression (whitelist)
"correlate findings by root cause" → Finding correlation (grouping)
"calculate risk scores" → Risk scoring (CVSS+Exploit+BizImpact)
"scan multiple targets" → Multi-target campaign (sequential)
"generate SOC 2 compliance report" → Compliance frameworks (7 standards)
"show security metrics dashboard" → Security metrics (MTTR/density/cost)
"assign owner to finding" → Team remediation (ownership/SLA)
"SLA gating for deployment" → CI/CD gating strategies (advanced)
"show risk posture score" → Executive reporting (risk posture + trends)
"import Burp findings" → External tool import (Burp/ZAP/Nuclei/SARIF)
"set up Slack notifications" → Notification hub (webhooks + SLA alerts)
"schedule weekly pentest" → Scheduled scanning (cron/Actions/systemd)
"benchmark this target" → Historical benchmarking (trends + forecasting)
"generate HTML dashboard" → Standalone dashboard (self-contained HTML)
"Shannon config for OAuth" → Config templates
"validate my Shannon config" → Config pre-validation
"Docker error in Shannon" → Troubleshooting guide
"check Shannon status" → Monitoring with auto-poll
"handoff to cybersecurity-pro" → Phase 5 (defensive docs prompt)
"compare Shannon runs" → Session comparison (diff table)
"Shannon stats" → Session analytics (cost/duration trends)
"set up engagement context" → Engagement setup (client/project info)
```
---
## Configuration
Shannon config uses **3 root keys only** (`additionalProperties: false` at root):
| Root Key | Required | Purpose |
| ---------------- | -------- | ------------------------------------------ |
| `authentication` | anyOf | Login credentials, flow, success condition |
| `rules` | anyOf | Focus/avoid paths for scoping |
| `pipeline` | optional | Retry preset, concurrency limits |
> `authentication` or `rules` (or both) must be present. Keys like `target:`, `auth:`, `scope:` will cause errors.
### Quick Config (No Auth)
```yaml
rules:
focus:
- description: "Focus on main application"
type: path
url_path: "/"
pipeline:
retry_preset: "subscription"
max_concurrent_pipelines: "3"
```
### Auth Scenarios
| Auth Type | Config Key | Template |
| -------------------- | ------------------------------------ | ------------------------------ |
| No Auth (public) | `rules` only | `config-templates-basic.md` |
| Form-based login | `authentication` (login_type: form) | `config-templates-basic.md` |
| TOTP / 2FA | `authentication` (+ totp_secret) | `config-templates-basic.md` |
| SSO (SAML/OIDC) | `authentication` (login_type: sso) | `config-templates-advanced.md` |
| API Key / Basic Auth | `authentication` (login_type: api) | `config-templates-advanced.md` |
| Scoped testing | `rules` (focus + avoid arrays) | `config-templates-advanced.md` |
| Local development | `rules` + `host.docker.internal` URL | `config-templates-advanced.md` |
### Pre-Validation (v1.2.0)
Before launch, the plugin runs 3-step validation:
1. **YAML syntax** — `yaml.safe_load()` check
2. **Root key validation** — only `authentication`, `rules`, `pipeline` allowed
3. **Value type check** — e.g., `max_concurrent_pipelines` must be string `"3"` not integer `3`
---
## CLI Quick Reference
```bash
# Start pentest
./shannon start URL= REPO=
./shannon start URL= REPO= CONFIG= WORKSPACE=
# Monitor
./shannon logs # Real-time logs
./shannon query ID= # Query specific workflow
./shannon workspaces # List all workspaces
# Stop
./shannon stop # Graceful stop
./shannon stop CLEAN=true # Stop + cleanup
./shannon stop WORKSPACE= CLEAN=true
```
**Temporal UI:** `http://localhost:8233` (accessible after launch)
---
## Performance Optimizations
v1.2.0 optimizations based on empirical testing:
| Optimization | Before | After | Impact |
| ------------------------ | --------------------------------- | ---------------------------- | ---------------------- |
| Smart target detection | 165+ LLM turns for web-only repos | ~5-10 turns | ~3-5 min saved |
| Config template split | ~2,500 tokens loaded always | ~900 tokens for common cases | 64% token reduction |
| Config pre-validation | Trial-and-error (2-3 attempts) | Validate before launch | Zero failed launches |
| Active monitoring | Manual status checks | Auto-poll every 2-5 min | 2-3 fewer interactions |
| Stall detection | User discovers after 20+ min | Auto-warn at 10 min | Faster recovery |
| Parallel report analysis | Sequential file reads | Concurrent Read calls | Faster Phase 4 |
---
## Setup Guide
Prerequisites
| Tool | Version | Purpose | Install |
| ------------------ | ----------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Docker Desktop** | 24.0+ | Runs Shannon containers (Temporal, workers, browser agents) | [docker.com/get-docker](https://docs.docker.com/get-docker/) |
| **Docker Compose** | v2 (plugin) | Orchestrates multi-container Shannon stack | Included with Docker Desktop |
| **Git** | 2.30+ | Repository management for target source code | `brew install git` / `apt install git` |
| **Python 3** | 3.8+ | Config validation, OAuth token extraction | Pre-installed on macOS/Linux |
| **Claude Code** | Latest | Plugin host environment | [claude.ai/claude-code](https://claude.ai/claude-code) |
| **Shannon** | Latest | Autonomous pentesting engine | [github.com/KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon) |
### Shannon Installation
```bash
git clone https://github.com/KeygraphHQ/shannon.git ~/shannon-tool
cd ~/shannon-tool
cp .env.example .env
chmod +x ./shannon
```
### API Key Configuration
The plugin **auto-configures** the API key from your active Claude Code session — no manual setup needed.
```
Claude Code session → OAuth token → Shannon .env (automatic)
```
If auto-detection fails, set an Anthropic API key manually:
```bash
echo 'ANTHROPIC_API_KEY=sk-ant-...' > ~/shannon-tool/.env
```
Pre-flight Checklist
Run these checks before your first pentest:
```bash
# 1. Docker running?
docker info > /dev/null 2>&1 && echo "✓ Docker running" || echo "✗ Docker not found"
# 2. Shannon installed?
SHANNON_DIR="${SHANNON_DIR:-$HOME/shannon-tool}"
ls "$SHANNON_DIR/shannon" 2>/dev/null && echo "✓ Shannon found" || echo "✗ Not found at $SHANNON_DIR"
# 3. .env configured?
ls "$SHANNON_DIR/.env" 2>/dev/null && echo "✓ .env exists" || echo "✗ .env missing"
# 4. Docker Compose v2?
docker compose version > /dev/null 2>&1 && echo "✓ Compose v2" || echo "✗ Compose not found"
# 5. Target reachable?
curl -s -o /dev/null -w "✓ Target responded: %{http_code}" "https://your-staging.example.com"
```
### Platform Notes
| Platform | Notes |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **macOS (Apple Silicon)** | Docker Desktop supports ARM64 natively. `host.docker.internal` works out of the box. |
| **Linux** | Add user to docker group: `sudo usermod -aG docker $USER`. May need `--add-host=host.docker.internal:host-gateway` for local targets. |
| **Windows (WSL2)** | Use WSL2 only. Clone Shannon inside WSL2 filesystem (`/home/user/`), not `/mnt/c/`. |
---
## Troubleshooting
Common issues and quick fixes
| Issue | Cause | Fix |
| --------------------------- | ------------------------------ | ------------------------------------------------------------------- |
| `docker: command not found` | Docker not installed | Install Docker Desktop |
| `Not a git repository` | Repo directory missing `.git/` | `cd repos/ && git init && git commit --allow-empty -m "init"` |
| Workspace resume fails | Cached failure state | Use a new workspace name |
| Config schema error | Invalid root keys | Use only `authentication`, `rules`, `pipeline` |
| Can't reach localhost | Docker network isolation | Use `host.docker.internal` instead of `localhost` |
| Workflow stall (20+ min) | Temporal/resource/rate limit | See `troubleshooting.md` — Workflow stalling section |
| API rate limit / 429 | Too many concurrent pipelines | Set `max_concurrent_pipelines: "2"` |
> Full troubleshooting: `references/troubleshooting.md` (infra) + `references/troubleshooting-shannon.md` (app)
---
## Related Plugins
| Plugin | Description | Install |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **[cybersecurity-pro](https://github.com/pitimon/claude-cybersecurity-skill)** | 18-domain defensive security knowledge — IR playbooks, compliance, vulnerability management, API security, threat modeling | `claude plugin install cybersecurity-pro@pitimon-cybersecurity` |
> **Complementary workflow:** Shannon finds vulnerabilities (offensive) → cybersecurity-pro creates remediation plans, IR playbooks, compliance mapping (defensive)
| Shannon Finding Type | cybersecurity-pro Domain | Use Case |
| -------------------------- | ----------------------------- | -------------------------------------- |
| Auth/AuthZ vulnerabilities | Domain 13: API Security | JWT, OAuth, BOLA remediation |
| XSS/SQLi/Injection | Domain 6: Code Security | Semgrep/CodeQL rules, variant analysis |
| OWASP Top 10 mapping | Domain 8: Threat Modeling | STRIDE/PASTA risk assessment |
| Vulnerability inventory | Domain 14: Vulnerability Mgmt | CVSS+EPSS+KEV prioritization |
| Infrastructure findings | Domain 10: Cloud Security | CIS Benchmarks, CSPM remediation |
---
## Project Structure
```
shannon-pentest/
├── .claude-plugin/
│ ├── marketplace.json # Marketplace registry entry
│ └── plugin.json # Plugin manifest (name, version, skills)
├── skills/
│ └── shannon-pentest/
│ ├── SKILL.md # Core skill (~566 lines) — phases, safety, decision tree
│ └── references/
│ ├── ci-cd-gating-strategies.md # CI/CD advanced gating: risk score, campaign, SLA, cost
│ ├── ci-cd-integration.md # CI/CD severity gating policy (basic)
│ ├── companion-tools-fingerprint.md # WhatWeb CMS detection + scanner routing (v3.4.0)
│ ├── companion-tools-orchestration.md # Phase 1.5/3/4 workflow + parallel monitoring (v3.4.0)
│ ├── companion-tools-overview.md # Kali tool catalog + concurrency + safety (v3.4.0)
│ ├── companion-tools-parsers.md # WPScan/ffuf/testssl parsers → Shannon schema (v3.4.0)
│ ├── companion-tools-ncsa.md # NCSA compliance mapping + VTS bulk scan (v3.5.0)
│ ├── companion-tools-safety.md # Rate limiting + scope enforcement (v3.4.0)
│ ├── companion-tools-scanners.md # Docker commands for all companion tools (v3.6.0)
│ ├── ci-cd-templates.md # GitHub Actions + GitLab CI YAML templates
│ ├── compliance-framework-reports.md # Compliance reports (OWASP/NIST/ISO/SOC2/PCI-DSS/HIPAA/GDPR)
│ ├── config-templates-basic.md # No Auth, Form, TOTP (~900 tokens)
│ ├── config-templates-advanced.md # SSO, API, Scoped, Pipeline, WordPress
│ ├── config-validation.md # Phase 2 validation scripts + common fixes
│ ├── docker-runtime-detection.md # Phase 0: Colima vs Docker Desktop detection (v3.7.0)
│ ├── defensive-handoff.md # Phase 5 handoff manifest + prompt generation
│ ├── engagement-context.md # Engagement context: client, project, scope
│ ├── evidence-packaging.md # Evidence archive + manifest schema
│ ├── external-findings-comparison.md # Compare Shannon vs external findings.json (v3.7.0)
│ ├── external-tool-import.md # Import Burp/ZAP/Nuclei/SARIF findings (v3.3.0)
│ ├── finding-comparison.md # Finding comparison diff between sessions
│ ├── finding-correlation.md # Root cause grouping, OWASP + endpoint correlation
│ ├── finding-lifecycle.md # Finding status tags, transitions, tracking
│ ├── finding-suppression.md # Cross-session finding whitelist management
│ ├── historical-benchmarking.md # Date-range queries, trends, forecasting (v3.3.0)
│ ├── inline-defense.md # IR checklist, remediation, compliance map
│ ├── issue-templates.md # Finding → GitHub/Jira issue template generation
│ ├── monitoring-guide.md # Phase 3 polling scripts + stall detection
│ ├── multi-format-export.md # PDF/HTML export pipeline
│ ├── multi-target-campaign.md # Campaign orchestration: multi-target + aggregate
│ ├── notification-hub.md # Slack/Discord/webhook/email notifications (v3.3.0)
│ ├── preflight-checks.md # 5-step pre-flight validation (v3.3.0)
│ ├── remediation-verification.md # Targeted retest, before/after evidence, verification report
│ ├── report-interpretation.md # CVSS v4.0, OWASP, MITRE ATT&CK mapping
│ ├── report-templates.md # 3 report templates (executive/technical/compliance)
│ ├── risk-scoring.md # Custom risk scoring (CVSS+Exploit+BizImpact)
│ ├── sarif-export.md # SARIF v2.1.0 export + GitHub Security tab upload
│ ├── scan-templates.md # Save/load reusable scan profiles
│ ├── scheduled-scanning.md # Automated recurring scans + regression (v3.3.0)
│ ├── security-metrics-dashboard.md # Security KPIs: MTTR, density, cost, risk posture, trends
│ ├── session-analytics.md # Session analytics: cost estimation + basic stats
│ ├── session-management.md # Session registry, auto-append logic
│ ├── setup-automation.md # Phase 0 OAuth token extraction + .env config
│ ├── standalone-dashboard.md # Self-contained HTML security dashboard (v3.3.0)
│ ├── target-detection.md # Web-only vs source-available detection (v3.3.0)
│ ├── team-remediation-dashboard.md # Enterprise workflow: ownership, SLA, audit trail
│ ├── troubleshooting.md # Docker, Temporal, Network, Platform issues
│ └── troubleshooting-shannon.md # Shannon app, config, API, workspace issues
├── hooks/
│ ├── hooks.json # Pre-validation hook config (PreToolUse)
│ └── pre-shannon-start.sh # Config YAML validation before ./shannon start
├── tests/
│ ├── smoke-test-prompts.md # 172 test cases for 42 decision tree routes
│ └── validate-plugin.sh # Structure + size + content validation (auto-counted checks)
├── .github/
│ └── workflows/
│ └── validate.yml # CI/CD: automated validation on push/PR
├── CHANGELOG.md # Version history (v1.0.0 → v3.7.0)
├── CLAUDE.md # Project instructions for Claude Code
├── LICENSE # MIT License
└── README.md # This file
```
---
## Man-Day Cost Estimation (v2.4.0)
Traditional vs AI-assisted development cost analysis
### Plugin Scope
| Metric | Value |
| --------------- | -------------------------------- |
| Total files | 30 |
| Total lines | 5,140 |
| Reference files | 46 (domain-specific content) |
| SKILL.md | ~566 lines (8 phases, 40 routes) |
| Validator | auto-counted checks, 7 sections |
| Smoke tests | 172 cases |
| Releases | 24 (v1.0.0 → v3.7.0) |
### Traditional Estimate (Senior Security Engineer)
| Category | Scope | Man-Days |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| Architecture & Design | Plugin architecture, 8-phase workflow, decision tree (20 routes), safety framework, bilingual policy | 2.5 |
| Core SKILL.md | Phase 0-5 logic, config generation, CLI workspace manager, inline defense trigger | 3.5 |
| Reference Files (19) | session-management (split), troubleshooting (split), report-templates, config-templates, finding-lifecycle, multi-format-export, sarif-export, issue-templates, etc. | 9.5 |
| Testing & Validation | validate-plugin.sh (auto-counted checks), smoke-test-prompts.md (64 tests), live QA run | 3.5 |
| CI/CD & Hooks | GitHub Actions workflow, PreToolUse hook, YAML fallback | 1.0 |
| Documentation | README, CHANGELOG (12 versions), CLAUDE.md, PR/release management | 2.5 |
| Iteration & Fixes | Config schema fix, perf optimization, quality polish, CI fix across 12 releases | 2.5 |
| **Total** | | **25 man-days** |
### Cost Comparison
| Metric | Traditional | AI-Assisted (Claude Code) |
| -------------------- | ---------------------- | ------------------------- |
| Elapsed time | 25 man-days (~5 weeks) | ~3-4 hours |
| Cost (Thailand rate) | 125,000-200,000 THB | API cost ~$50-80 |
| Quality assurance | Manual review | auto-counted checks + CI |
| Iteration speed | Days per version | Minutes per version |
| **Time savings** | — | **~98%** |
| **Cost savings** | — | **~99%** |
---
## Safety & License
This plugin enforces mandatory safety rules: **never run on production** (staging/test only), **written authorization required** before launch, **target URL confirmed** before every scan, **no credential storage** outside Shannon config, and **strict scope boundaries** (no expansion beyond specified target).
MIT License — see [LICENSE](LICENSE) for details.