shannon-pentest

name	shannon-pentest
description	AI-driven white-box penetration testing methodology adapted from Shannon (Keygraph). Follows a 5-phase pipeline (Pre-Recon, Recon, Vulnerability Analysis, Exploitation, Reporting) with structured deliverables. Use when the user asks for security audit, penetration testing, vulnerability assessment, or exploit validation of web applications, APIs, or source code.

Shannon Pentest Methodology

Principle: No Exploit, No Report. Only report vulnerabilities that have been practically exploited or validated.

Methodology derived from Shannon (AGPL-3.0, Keygraph), adapted for Kimi CLI.

5-Phase Pipeline

Execute phases sequentially. Each phase saves a deliverable to .shannon/deliverables/. Do not skip phases unless the user explicitly requests a subset.

Pre-Recon → Recon → Vulnerability Analysis → Exploitation → Reporting

Phase 1: Pre-Reconnaissance

Goal: External footprinting + initial source-code mapping.

1. Read references/pre-recon.md.
2. If target is a live web app/API:
   • Run nmap, subfinder, whatweb via Bash.
   • Capture open ports, subdomains, tech stack fingerprints.
3. If source code is available:
   • Grep for hardcoded secrets (API_KEY, SECRET, password, token).
   • Identify entry points (controllers, routes, handlers).
4. Save deliverable: python .claw/skills/shannon-pentest/scripts/save-deliverable.py --type PRE_RECON --content "..."

Phase 2: Reconnaissance

Goal: Browser automation + attack-surface mapping.

1. Read references/recon.md.
2. Use Playwright (via Bash or configured MCP) to:
   • Navigate the application, authenticate if credentials/TOTP are provided.
   • Map all forms, links, API endpoints, and URL parameters.
   • Capture screenshots of critical flows.
3. Correlate dynamic findings with static code analysis.
4. Save deliverable: --type RECON

Phase 3: Vulnerability Analysis

Goal: Identify concrete vulnerability hypotheses.

1. Read references/vuln-analysis.md and references/schemas.md.
2. Launch up to 5 parallel Agent subtasks (one per vulnerability class):
   • injection-vuln (SQLi, Command Injection, SSTI, etc.)
   • xss-vuln (Stored/Reflected/DOM XSS)
   • auth-vuln (Broken Authentication, Session Management)
   • ssrf-vuln (Server-Side Request Forgery)
   • authz-vuln (Broken Access Control, IDOR)
3. Each agent must output a structured JSON queue matching the schema in references/schemas.md.
4. Save deliverables: injection_analysis_deliverable.md, xss_analysis_deliverable.md, etc. (use --type INJECTION_ANALYSIS, XSS_ANALYSIS, etc.)

Phase 4: Exploitation

Goal: Validate hypotheses from Phase 3.

1. Read references/exploitation.md.
2. For each non-empty vulnerability queue from Phase 3, launch a focused Agent subtask to attempt practical exploitation.
   • Use Bash to run exploit payloads (curl, playwright scripts, custom Python).
   • Capture evidence: HTTP responses, screenshots, source-code diffs.
3. If a hypothesis cannot be exploited after reasonable effort, mark it unconfirmed and drop it from the report.
4. Save deliverables: *_exploitation_queue.json and exploitation_evidence/ folder.

Phase 5: Reporting

Goal: Compile only validated findings into a professional report.

1. Read references/reporting.md.
2. Aggregate all exploitation evidence from .shannon/deliverables/.
3. Generate a markdown report with:
   • Executive Summary
   • Risk ratings (CVSS or Critical/High/Medium/Low)
   • Step-by-step reproduction instructions
   • Impact analysis
   • Remediation guidance
4. Save deliverable: --type REPORT (saved as report.md).

Helper Scripts

TOTP Generation

For 2FA/MFA login flows:

python .claw/skills/shannon-pentest/scripts/generate-totp.py --secret BASE32SECRET

Save Deliverable

Always use the provided script to persist phase outputs:

python .claw/skills/shannon-pentest/scripts/save-deliverable.py --type <TYPE> --content "..."
# Or from file:
python .claw/skills/shannon-pentest/scripts/save-deliverable.py --type <TYPE> --file-path /path/to/content.md

Valid types: PRE_RECON, RECON, INJECTION_ANALYSIS, XSS_ANALYSIS, AUTH_ANALYSIS, SSRF_ANALYSIS, AUTHZ_ANALYSIS, EXPLOITATION_EVIDENCE, REPORT

Workspace Conventions

• All deliverables live in ./.shannon/deliverables/ (created automatically).
• Use git init inside .shannon/deliverables/ if you want checkpoint/rollback support.
• Maintain a scratchpad directory .shannon/scratchpad/ for temporary files, screenshots, and raw tool output.

Error Handling

• If a tool (nmap, playwright, etc.) is not installed, attempt to install it or ask the user.
• If an Agent subtask fails, retry once with a more focused prompt. If it still fails, note the failure in the deliverable and continue.
• Never halt the entire pipeline because one vulnerability-class agent failed.