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.
| 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 |
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 |
# 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.
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 |
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"
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)
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 |
authenticationorrules(or both) must be present. Keys liketarget:,auth:,scope:will cause errors.
rules:
focus:
- description: "Focus on main application"
type: path
url_path: "/"
pipeline:
retry_preset: "subscription"
max_concurrent_pipelines: "3"| 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 |
Before launch, the plugin runs 3-step validation:
- YAML syntax —
yaml.safe_load()check - Root key validation — only
authentication,rules,pipelineallowed - Value type check — e.g.,
max_concurrent_pipelinesmust be string"3"not integer3
# Start pentest
./shannon start URL=<url> REPO=<repo>
./shannon start URL=<url> REPO=<repo> CONFIG=<path> WORKSPACE=<name>
# Monitor
./shannon logs # Real-time logs
./shannon query ID=<workflow-id> # Query specific workflow
./shannon workspaces # List all workspaces
# Stop
./shannon stop # Graceful stop
./shannon stop CLEAN=true # Stop + cleanup
./shannon stop WORKSPACE=<name> CLEAN=trueTemporal UI: http://localhost:8233 (accessible after launch)
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 |
Prerequisites
| Tool | Version | Purpose | Install |
|---|---|---|---|
| Docker Desktop | 24.0+ | Runs Shannon containers (Temporal, workers, browser agents) | 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 |
| Shannon | Latest | Autonomous pentesting engine | github.com/KeygraphHQ/shannon |
git clone https://github.com/KeygraphHQ/shannon.git ~/shannon-tool
cd ~/shannon-tool
cp .env.example .env
chmod +x ./shannonThe 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:
echo 'ANTHROPIC_API_KEY=sk-ant-...' > ~/shannon-tool/.envPre-flight Checklist
Run these checks before your first pentest:
# 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 |
|---|---|
| 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/. |
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/<name> && 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)
| Plugin | Description | Install |
|---|---|---|
| cybersecurity-pro | 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 |
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)
│ ├── 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
│ ├── 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-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 # 127 test cases for 36 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.3.0)
├── CLAUDE.md # Project instructions for Claude Code
├── LICENSE # MIT License
└── README.md # This file
Traditional vs AI-assisted development cost analysis
| Metric | Value |
|---|---|
| Total files | 30 |
| Total lines | 5,140 |
| Reference files | 39 (domain-specific content) |
| SKILL.md | ~566 lines (8 phases, 36 routes) |
| Validator | auto-counted checks, 7 sections |
| Smoke tests | 127 cases |
| Releases | 20 (v1.0.0 → v3.3.0) |
| 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 |
| 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% |
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 for details.