{"id":"beb9e5df-d7f8-4385-a6fc-2701f31b952f","slug":"shannon-on-claude-code","kind":"mcp","name":"shannon-on-claude-code","summary":"Shannon's 5-phase pentest pipeline running natively in Claude Code — no Docker, no Temporal, just /pentest https://github.com/KeygraphHQ/shannon","owner":"us","repoUrl":"https://github.com/us/shannon-on-claude-code","license":"AGPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":17,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-05T09:50:36.000Z","addedAt":"2026-10-14T05:47:18.777Z","logoUrl":"https://avatars.githubusercontent.com/u/22618852?u=026c3f07167d8b2cf7620ac37818fee0512f296e&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","data-analytics"],"tags":["agpl-3","ai-agents","claude","claude-code","cybersecurity","multi-agent","penetration-testing","pentest"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T07:30:18.182Z","sample":false,"url":"https://conduits.dev/tools/shannon-on-claude-code","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Shannon — Claude Code Native\n<!-- Copyright (C) 2025 Keygraph, Inc. (original Shannon) -->\n<!-- This project is a derivative of Shannon (https://github.com/KeygraphHQ/shannon) -->\n<!-- Licensed under GNU Affero General Public License v3.0 -->\n\nShannon's penetration testing pipeline (5 phases + 3 conditional sub-phases) running natively in Claude Code.\nNo Temporal, no Docker, no worker processes. Just open `claude` and run `/pentest <url>`.\n\n## Quick Start\n\n```bash\ncd /Users/us/coding/shannon-on-claude-code   # or wherever you cloned this repo\nclaude\n/pentest https://target.com\n```\n\n## OpenCode usage (tested 2026-09-19)\n\nThe repo also runs under opencode (`opencode run`), verified end-to-end on a\nlocal fixture (pre-recon + recon + vuln-xss + vuln-misc, analysis-only,\nblack-box: all `save_deliverable` calls returned `success`/`validated true`):\n\n```bash\ncd /path/to/this/repo\nopencode\n/pentest https://target.com\n```\n\nHeadless:\n\n```bash\nopencode run --dir . --command pentest -m <provider/model> \"https://target.com\"\n```\n\nOpencode-specific files (all committed with the repo):\n\n- `opencode.json` — MCP servers (`shannon-tools`). Opencode does not read\n  `.mcp.json`, so this file is required.\n- `.opencode/agents/*.md` — the 18 subagents. Opencode does not read\n  `.claude/agents/`, so these generated copies are required. Regenerate after\n  editing any Claude agent:\n  ```bash\n  python3 - <<'EOF'\n  import re, pathlib\n  dst = pathlib.Path('.opencode/agents'); dst.mkdir(parents=True, exist_ok=True)\n  for f in sorted(pathlib.Path('.claude/agents').glob('*.md')):\n      m = re.match(r'^---\\n(.*?)\\n---\\n(.*)$', f.read_text(), re.S)\n      desc = re.search(r'^description:\\s*(.*)$', m.group(1), re.M).group(1).strip()\n      (dst / f.name).write_text(f\"---\\ndescription: {desc}\\nmode: subagent\\nsteps: 100\\n---\\n\" + m.group(2))\n  EOF\n  ```\n- `.opencode/commands/pentest.md` — the `/pentest` slash command (loads the skill).\n- `.claude/skills/pentest/SKILL.md` is auto-discovered by opencode (no copy needed).\n\nCaveats:\n\n- Run `cd native && npm install`. Do NOT symlink `node_modules` into\n  `native/`: opencode's directory scan follows the symlink and hangs startup.\n- Agent models are unpinned in `.opencode/agents/` (opencode subagents inherit\n  the primary session model); the skill's scope questions use opencode's\n  `question` tool, or pass fixed scope to skip them in `opencode run`.\n- `models.dev` is unreachable from some networks; pass `-m` explicitly.\n\nWith source code (white-box):\n```bash\n# Clone or symlink the target repo here\ngit clone https://github.com/org/repo.git .\n# or\nln -s /path/to/repo/* .\n\nclaude\n/pentest https://target.com\n```\n\n---\n\n## Requirements\n\n### Required\n\n| Tool | Install | Purpose |\n|------|---------|---------|\n| `claude` (Claude Code) | [claude.ai/code](https://claude.ai/code) | Run the pipeline |\n| `node` ≥ 18 | `apt install nodejs` | MCP server |\n| `npm` | `apt install npm` | MCP dependencies |\n| `curl` | Usually pre-installed | HTTP testing |\n\n### MCP Dependencies\n\n```bash\ncd native && npm install\n```\n\n### Optional (used if available)\n\n| Tool | Install | Purpose |\n|------|---------|---------|\n| `nmap` | `apt install nmap` | Port scanning |\n| `subfinder` | [github.com/projectdiscovery/subfinder](https://github.com/projectdiscovery/subfinder/releases) | Subdomain discovery |\n| `whatweb` | `apt install whatweb` | Technology fingerprinting |\n| `sqlmap` | `apt install sqlmap` | SQL injection automation |\n| `oathtool` | `apt install oathtool` | TOTP code generation (for MFA) |\n| Playwright | `npx playwright install chromium` | Browser automation (MCP installs automatically) |\n\n> If optional tools are missing, the pipeline continues and skips those steps.\n\n---\n\n## Pipeline — 5 phases + 3 conditional sub-phases (synced with upstream Shannon 3.0)\n\n```\nPhase 1:  Pre-Recon   → pre_recon_deliverable.md\n            ↓\nPhase 1b: SAST-lite (white-box only, parallel with Recon)\n          → sast_deliverable.md + sast_findings.json\n            ↓\nPhase 2:  Recon       → recon_deliverable.md\n            ↓\nPhase 0b: Validate-auth (conditional, login scans only, runs before Phase 1)\n          → auth_validation.json\n            ↓\nPhase 3:  Vuln (×6 parallel)\n  ├─ injection  → injection_analysis_deliverable.md + injection_exploitation_queue.json\n  ├─ xss        → xss_analysis_deliverable.md + xss_exploitation_queue.json\n  ├─ auth       → auth_analysis_deliverable.md + auth_exploitation_queue.json\n  ├─ authz      → authz_analysis_deliverable.md + authz_exploitation_queue.json\n  ├─ ssrf       → ssrf_analysis_deliverable.md + ssrf_exploitation_queue.json\n  └─ misc       → miscellaneous_analysis_deliverable.md + miscellaneous_exploitation_queue.json\n            ↓\nPhase 3b: Reconcile (merge + dedupe, split-over-merge)\n          → reconciled_exploitation_queue.json\n            ↓\nPhase 4:  Exploit (conditional, ×6 parallel)\n  └─ Only runs for non-empty queues with externally exploitable findings\n  └─ Prefers the reconciled queue, falls back to per-class queues\n            ↓\nPhase 5:  Report      → comprehensive_security_assessment_report.md\n                       + security_assessment_report.json + security_assessment_report.sarif\n```\n\nResume: re-run the same `/pentest <target>`; phases with valid deliverables are\nskipped (URL-bound via `scan_meta.json`). `--fresh` forces a clean rerun.\n\n**Model assignments:**\n- Pre-recon/SAST: `claude-opus-4` (deep code analysis)\n- Recon/Vuln/Exploit/Reconcile/Validate-auth: `claude-sonnet-4` (15 agents: 6 vuln + 6 exploit lanes, recon, reconcile, validate-auth)\n- Report: `claude-haiku-4` (executive summary writing)\n\n**Conventions:**\n- Scope rules are typed: `url_path`, `subdomain`, `domain`, `method`, `header`, `parameter`, `code_path` (`code_path` values are repo-relative file paths or globs).\n- Findings use stable report IDs `[TYPE]-[NUMBER]` (e.g. INJ-01, AUTH-03, MISC-01), each in its own class namespace.\n- Every finding maps to an OWASP Top 10 2025 category.\n\n---\n\n## Modes\n\n### Black-Box (URL only)\nNo source code, just a URL. Uses:\n- nmap, subfinder, whatweb (external scanning)\n- Playwright browser (frontend exploration, JS analysis)\n- curl (API endpoint testing)\n\n### White-Box (URL + Source Code)\nProject files present in this directory. Additionally:\n- Source code analysis (taint analysis, code review)\n- Route/controller mapping\n- Auth/authz guard analysis\n\n---\n\n## Output Files\n\nAll files are saved under `deliverables/`:\n\n```\ndeliverables/\n├── scan_meta.json                        # Scan binding (target URL, resume guard)\n├── pre_recon_deliverable.md           # Pre-recon findings\n├── sast_deliverable.md + sast_findings.json  # SAST-lite (white-box only)\n├── recon_deliverable.md                  # Attack surface map\n├── auth_validation.json                  # Credential check (login scans only)\n├── *_analysis_deliverable.md × 6        # Vulnerability analysis reports\n├── *_exploitation_queue.json × 6        # Exploit target lists\n├── reconciled_exploitation_queue.json    # Merged + deduped queue\n├── *_exploitation_evidence.md × 6       # Exploitation evidence\n├── comprehensive_security_assessment_report.md  # Final report\n├── security_assessment_report.json       # Machine-readable findings\n└── security_assessment_report.sarif      # SARIF 2.1.0\n```\n\nAudit log:\n```\naudit-logs/session.jsonl                  # Record of every tool call\n```\n\n---\n\n## MCP Tools\n\n### shannon-tools (`native/mcp-stdio-wrapper.mjs`)\n\n| Tool | Description |\n|------|-------------|\n| `save_deliverable` | Saves a deliverable file to `deliverables/` with validation |\n| `generate_totp` | Generates a TOTP code from a Base32 secret (for MFA-protected sites) |\n\nThe `SHANNON_TARGET_DIR` env var sets the target directory (default: `.`).\n\n### playwright\nHeadless Chromium browser for browser interactions, form filling, and JS execution.\n\n---\n\n## Configuration\n\n### Sites Requiring Login\n\nPass login details directly to the `/pentest` skill:\n\n```\n/pentest https://target.com\nLogin URL: https://target.com/login\nUsername: testuser@example.com\nPassword: testpass123\nLogin type: form\n```\n\nWith MFA/TOTP:\n```\nTOTP Secret: JBSWY3DPEHPK3PXP\n```\n\n### Scope Restrictions\n\n```\n/pentest https://target.com\nRules to Avoid: /admin, /billing, payment endpoints\nFocus: authentication, authorization\n```\n\nFile-based equivalent: copy `shannon-config.example.yaml` to `shannon-config.yaml` (typed `rules:`, `authentication:`, `rules_of_engagement:`) and pass it with the command.\n\n---\n\n## File Structure\n\n```\nshannon-on-claude-code/\n├── README.md\n├── shannon-config.example.yaml        # Config file template (auth, rules, report)\n├── docs/\n│   ├── configuration.md               # Config, providers, resume, report formats\n│   ├── safety.md                      # Authorized use, non-prod, limitations\n│   └── coverage-roadmap.md            # Coverage, out-of-scope, roadmap\n├── plans/\n│   └── 2026-09-19-shannon-3.0-sync.md # This sync's plan + review record\n├── .mcp.json                        # Playwright + Shannon MCP configuration\n├── .claude/\n│   ├── settings.json                # Tool permissions + audit hook\n│   ├── shared/                      # Shared prompt partials (ported upstream)\n│   │   ├── severity-reasoning.md\n│   │   ├── reporting-standards.md\n│   │   ├── exploit-scope.md\n│   │   └── credentials-hygiene.md\n│   ├── agents/                      # 18 agent definitions\n│   │   ├── pre-recon.md    (opus)\n│   │   ├── sast.md         (opus, white-box only)\n│   │   ├── recon.md        (sonnet)\n│   │   ├── validate-auth.md (sonnet, conditional)\n│   │   ├── vuln-auth.md    (sonnet)\n│   │   ├── vuln-authz.md   (sonnet)\n│   │   ├── vuln-injection.md (sonnet)\n│   │   ├── vuln-xss.md     (sonnet)\n│   │   ├── vuln-ssrf.md    (sonnet)\n│   │   ├── vuln-misc.md    (sonnet, native extension)\n│   │   ├── reconcile.md    (sonnet)\n│   │   ├── exploit-auth.md (sonnet)\n│   │   ├── exploit-authz.md (sonnet)\n│   │   ├── exploit-injection.md (sonnet)\n│   │   ├── exploit-xss.md  (sonnet)\n│   │   ├── exploit-ssrf.md (sonnet)\n│   │   ├── exploit-misc.md (sonnet)\n│   │   └── report.md       (haiku)\n│   ├── skills/\n│   │   └── pentest/SKILL.md         # /pentest orchestrator skill\n│   └── hooks/\n│       └── audit-logger.sh          # Tool call audit logging\n└── native/\n    ├── mcp-stdio-wrapper.mjs        # MCP server (save_deliverable, generate_totp)\n    ├── package.json\n    └── node_modules/\n```\n\n---\n\n## Differences from Shannon (Original)\n\n| Feature | Shannon (Temporal) | Claude Code Native |\n|---------|-------------------|-------------------|\n| Orchestration | Temporal workflow | Skill prompt |\n| Parallel agents | `Promise.allSettled` | Agent tool parallel calls |\n| Crash recovery | Temporal durable execution | Resume from deliverables |\n| Resume/workspace | Git checkpoint + session | `scan_meta.json` URL-bound skip + `--fresh` |\n| Retry | Temporal retry policy (3x) | None (re-run resumes) |\n| Finding reconciliation | Task-formation + dedupe | `reconcile` agent (split-over-merge) |\n| Static analysis | 10-stage Capella SAST | SAST-lite agent (white-box only) |\n| Auth validation | validate-authentication | `validate-auth` agent (conditional) |\n| Vuln classes | 5 fixed | 6 (adds native `misc` lane) |\n| Reports | PDF + Markdown + SARIF | Markdown + JSON + SARIF 2.1.0 (no PDF) |\n| Playwright | 5 isolated instances | Single shared instance |\n| Setup | Docker + npm build | npm install only |\n\n---\n\n## Troubleshooting\n\n**`claude` command not found:**\n```bash\nwhich claude || echo \"Claude Code is not installed\"\n```\n\n**MCP server won't start:**\n```bash\ncd native && node mcp-stdio-wrapper.mjs\n# If errors: npm install\n```\n\n**Playwright not working:**\n```bash\nnpx playwright install chromium\n```\n\n**Pipeline stopped mid-run:**\n```bash\n# Resume where it left off (deliverables are checkpoints)\nclaude\n/pentest https://target.com\n# Or force a clean rerun\n/pentest https://target.com --fresh\n```\n\n**nmap/subfinder not found:**\nThe pipeline still runs — those scans are simply skipped. All external tools are optional.\n\n---\n\n## License\n\nThis project is a derivative of [Shannon](https://github.com/KeygraphHQ/shannon) and is licensed under the **GNU Affero General Public License v3.0** — see [LICENSE](./LICENSE) for the full text.\n\n**Original copyright:** Copyright (C) 2025 Keygraph, Inc.\n\n**Modifications made in this derivative:**\n- Removed Temporal workflow orchestration layer\n- Removed Docker and worker process infrastructure\n- Adapted all 13 agent prompts to Claude Code native agent format (`.claude/agents/`), now 18 with the 3.0 sync additions\n- Added `/pentest` skill orchestrator replacing `pentestPipelineWorkflow`\n- Replaced in-process MCP server with stdio-compatible wrapper (`native/mcp-stdio-wrapper.mjs`)\n- Added black-box mode detection for URL-only operation without source code\n- Synced with upstream Shannon 3.0 (Sep 2026): 6th `misc` lane (native extension,\n  upstream feeds it from SAST), `reconcile` agent (task-formation + dedupe),\n  SAST-lite agent, `validate-auth` preflight, SARIF 2.1.0 + JSON reports,\n  typed scope rules, `scan_meta.json` resume, `shannon-config.example.yaml`,\n  shared severity/reporting/scope partials, OWASP Top 10 2025 mapping\n\n## Acknowledgements\n\nAll penetration testing methodology, prompt engineering, vulnerability analysis frameworks, and agent definitions originate from [Shannon](https://github.com/KeygraphHQ/shannon) by Keygraph, Inc.\n"}