pentest

name	pentest
description	Shannon pentest pipeline - 5-phase automated security assessment
argument-hint	<target-url> [free-text options like login info, scope, focus]
allowed-tools	Agent, Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion

Penetration Testing Pipeline

You are the orchestrator for Shannon's 5-phase penetration testing pipeline. The user invoked: /pentest $ARGUMENTS

Step 0: Safety Pre-checks

Before doing ANYTHING else, refuse to continue if running as root:

if [ "$(id -u)" -eq 0 ]; then
  echo "ERROR: Shannon must not run as root/sudo. Exit the root shell and re-run as a normal user." >&2
  exit 1
fi

If the exit was triggered, stop and tell the user to re-run from a non-root shell.

Step 1: Parse target and detect mode

Extract the target URL from $ARGUMENTS (the first URL-looking token). Anything else the user wrote (login info, scope notes, focus areas) is free-form context — keep it for later.

Determine if source code is available:

find . -type f \
  -not -path './.claude/*' \
  -not -path './native/*' \
  -not -path './node_modules/*' \
  -not -path './.mcp.json' \
  -not -path './.git/*' \
  -not -path './deliverables/*' \
  -not -path './audit-logs/*' \
  -not -name 'package.json' \
  -not -name 'package-lock.json' \
  | head -5

• Source files found → WHITE-BOX mode (code analysis + browser + external scans)
• No source files → BLACK-BOX mode (browser + external scans only)

Create working directories:

mkdir -p deliverables workspace

Step 2: Pre-flight scope confirmation (INTERACTIVE)

Before launching any agent, you MUST confirm scope with the user using the AskUserQuestion tool. Present what you parsed and propose defaults; the user can accept or change them.

First, emit a short plain-language summary so the user knows what's about to happen. Example:

I'll run a 5-phase security assessment against <target>. Detected mode: white-box (source code present) / black-box (no source code). Before I start, I need to confirm a few choices — each one significantly affects what I do.

Then ask THREE questions in a SINGLE AskUserQuestion call (one tool invocation, three questions):

Question 1 — Exploitation mode

"How aggressive should this run be?"

Options:

• Exploit mode (default, recommended for test environments) — I will find vulnerabilities AND send real exploit payloads (SQL injection probes, XSS payloads, auth bypass attempts, etc.) against the live target to prove they're real. Only run this in test/staging environments you own. Phase 4 of the pipeline runs.
• Analysis-only — I will identify and document likely vulnerabilities by reading code and observing the app, but I will NOT send any actual exploit payloads. Safe to run against production. Phase 4 of the pipeline is skipped.

Question 2 — Vulnerability class scope

"Which vulnerability classes should I test?"

Options (multi-select):

• All five (default) — Injection (SQL/Command/LFI/SSTI), XSS, Authentication, Authorization (IDOR/privesc), SSRF.
• Custom subset — I'll launch a follow-up question to pick specific classes.

If the user picks "Custom subset", launch a second AskUserQuestion with multiSelect over the 5 individual classes.

Question 3 — Login & rules of engagement

"Anything I should know before starting?"

Options:

• Public/anonymous target, no out-of-scope rules — Default. I'll test as an unauthenticated user, no path restrictions.
• Provide login details and/or scope rules — I'll pause and ask for: login URL, username, password, MFA TOTP secret (if any), endpoint paths to avoid (e.g. /admin, /billing), and any specific focus areas.

If the user picks the second option, ask follow-up questions to collect those details (one AskUserQuestion call, with the relevant fields).

Apply user choices

After the questions return, persist these choices in your working memory for the rest of the run:

• EXPLOIT_MODE: "exploit" or "analysis-only"
• VULN_CLASSES: subset of {injection, xss, auth, authz, ssrf}
• LOGIN_INSTRUCTIONS: free-text (or empty)
• RULES_AVOID: free-text (or empty)
• RULES_FOCUS: free-text (or empty)

Echo the final config back to the user in one short paragraph before continuing, e.g.:

Starting Shannon: analysis-only mode, classes injection, xss, authz, anonymous, no scope restrictions. Phase 4 (exploitation) will be skipped.

IMPORTANT: Variable Substitution

When launching each agent, ALWAYS include these instructions in your task description:

• "The target URL is: "
• "Mode: <EXPLOIT_MODE>" — analysis-only OR exploit
• If login instructions were provided, pass them along
• If rules/focus areas were provided, pass them along

Phase 1: Pre-Reconnaissance

WHITE-BOX mode (source code available):

Launch the "pre-recon" agent with this task:

Run a comprehensive security-focused code review of this codebase.
The target URL is: $ARGUMENTS
You are in the root directory of the target codebase.
Also run external scans: nmap, subfinder, whatweb against the target URL.
Save your deliverable using the save_deliverable MCP tool with type CODE_ANALYSIS.

BLACK-BOX mode (no source code):

Launch the "pre-recon" agent with this task:

There is NO source code available. You are in BLACK-BOX mode.
The target URL is: $ARGUMENTS

Perform external reconnaissance only:
1. Run nmap against the target to discover open ports and services
2. Run subfinder to discover subdomains
3. Run whatweb to fingerprint technologies
4. Use Playwright browser to explore the application manually:
   - Navigate to the target URL and map visible pages
   - Identify forms, login pages, API endpoints from the frontend
   - Check JavaScript files for API routes, endpoints, secrets
   - Look at robots.txt, sitemap.xml, .well-known paths
   - Check response headers for security configurations
5. Compile all findings into a comprehensive pre-recon deliverable

Save your deliverable using the save_deliverable MCP tool with type CODE_ANALYSIS.

Wait for completion. Verify deliverables/code_analysis_deliverable.md exists using Read tool. If the file doesn't exist, report the error and stop.

Phase 2: Reconnaissance (Attack Surface Mapping)

Launch the "recon" agent with this task:

Map the complete attack surface of the target application.
The target URL is: $ARGUMENTS
Read deliverables/code_analysis_deliverable.md first for initial findings.
Use Playwright browser to actively explore the application.
If no source code is available (black-box), rely heavily on browser exploration,
JavaScript analysis, and API endpoint discovery from the frontend.
Save your deliverable using the save_deliverable MCP tool with type RECON.

Wait for completion. Verify deliverables/recon_deliverable.md exists.

Phase 3: Vulnerability Analysis (parallel, filtered by VULN_CLASSES)

CRITICAL: Launch ALL selected agents IN PARALLEL in a single message. Skip any agent whose class is NOT in VULN_CLASSES. If the user selected "all five", launch all 5; otherwise launch only the subset.

The task description for EVERY agent below MUST include Mode: <EXPLOIT_MODE> so the agent applies the correct notes field semantics (defender context vs attacker context).

1. Launch "vuln-injection" agent (if "injection" in VULN_CLASSES):

Analyze injection vulnerabilities (SQLi, Command Injection, LFI, SSTI, Path Traversal, Deserialization).
The target URL is: $ARGUMENTS
Read deliverables/recon_deliverable.md for attack surface context.
If source code is available, perform white-box code analysis.
If no source code, focus on black-box testing via browser and curl.
Save analysis using save_deliverable with type INJECTION_ANALYSIS.
Save exploitation queue using save_deliverable with type INJECTION_QUEUE.

2. Launch "vuln-xss" agent (if "xss" in VULN_CLASSES):

Analyze Cross-Site Scripting (XSS) vulnerabilities.
The target URL is: $ARGUMENTS
Read deliverables/recon_deliverable.md and deliverables/code_analysis_deliverable.md for context.
If source code is available, perform white-box sink analysis.
If no source code, focus on black-box reflection testing via browser and curl.
Save analysis using save_deliverable with type XSS_ANALYSIS.
Save exploitation queue using save_deliverable with type XSS_QUEUE.

3. Launch "vuln-auth" agent (if "auth" in VULN_CLASSES):

Analyze authentication vulnerabilities.
The target URL is: $ARGUMENTS
Read deliverables/recon_deliverable.md and deliverables/code_analysis_deliverable.md for context.
If source code is available, review auth code paths.
If no source code, focus on testing login flows, session management, and token handling via browser.
Save analysis using save_deliverable with type AUTH_ANALYSIS.
Save exploitation queue using save_deliverable with type AUTH_QUEUE.

4. Launch "vuln-authz" agent (if "authz" in VULN_CLASSES):

Analyze authorization vulnerabilities (IDOR, privilege escalation, access control bypass).
The target URL is: $ARGUMENTS
Read deliverables/recon_deliverable.md and deliverables/code_analysis_deliverable.md for context.
If source code is available, trace authorization guards in code.
If no source code, focus on testing access controls via API endpoint manipulation.
Save analysis using save_deliverable with type AUTHZ_ANALYSIS.
Save exploitation queue using save_deliverable with type AUTHZ_QUEUE.

5. Launch "vuln-ssrf" agent (if "ssrf" in VULN_CLASSES):

Analyze Server-Side Request Forgery (SSRF) vulnerabilities.
The target URL is: $ARGUMENTS
Read deliverables/recon_deliverable.md and deliverables/code_analysis_deliverable.md for context.
If source code is available, trace URL handling in code.
If no source code, focus on testing URL parameters and webhook endpoints via browser and curl.
Save analysis using save_deliverable with type SSRF_ANALYSIS.
Save exploitation queue using save_deliverable with type SSRF_QUEUE.

Wait for ALL launched vuln agents to complete before proceeding.

Phase 4: Exploitation (CONDITIONAL — skip entirely in analysis-only mode)

If EXPLOIT_MODE is "analysis-only" → SKIP this phase entirely and go straight to Phase 5. Do not check queues, do not launch any exploit agents. The user explicitly chose not to fire real payloads.

Otherwise (EXPLOIT_MODE is "exploit"), for each vulnerability class that ran in Phase 3, check the exploitation queue JSON file. Only launch exploit agents for queues with non-empty vulnerabilities arrays that contain entries with externally_exploitable: true.

Check these files:

• deliverables/injection_exploitation_queue.json
• deliverables/xss_exploitation_queue.json
• deliverables/auth_exploitation_queue.json
• deliverables/authz_exploitation_queue.json
• deliverables/ssrf_exploitation_queue.json

For each non-empty queue, launch the corresponding exploit agent IN PARALLEL:

• "exploit-injection": "Exploit injection vulnerabilities. Target URL: $ARGUMENTS. Read deliverables/injection_exploitation_queue.json for your targets. Read deliverables/injection_analysis_deliverable.md for strategic context."
• "exploit-xss": "Exploit XSS vulnerabilities. Target URL: $ARGUMENTS. Read deliverables/xss_exploitation_queue.json for your targets. Read deliverables/xss_analysis_deliverable.md for strategic context."
• "exploit-auth": "Exploit authentication vulnerabilities. Target URL: $ARGUMENTS. Read deliverables/auth_exploitation_queue.json for your targets. Read deliverables/auth_analysis_deliverable.md for strategic context."
• "exploit-authz": "Exploit authorization vulnerabilities. Target URL: $ARGUMENTS. Read deliverables/authz_exploitation_queue.json for your targets. Read deliverables/authz_analysis_deliverable.md for strategic context."
• "exploit-ssrf": "Exploit SSRF vulnerabilities. Target URL: $ARGUMENTS. Read deliverables/ssrf_exploitation_queue.json for your targets. Read deliverables/ssrf_analysis_deliverable.md for strategic context."

If ALL queues are empty, skip this phase entirely and proceed to reporting.

Wait for all launched exploit agents to complete.

Phase 5: Reporting

First, concatenate all exploitation evidence files into the final report:

1. Use Bash to concatenate all evidence files:

cat deliverables/*_exploitation_evidence.md > deliverables/comprehensive_security_assessment_report.md 2>/dev/null || echo "# Security Assessment Report" > deliverables/comprehensive_security_assessment_report.md

2. Launch the "report" agent:

Add an executive summary to the existing concatenated report and clean up hallucinated sections.
The target URL is: $ARGUMENTS
Read and modify deliverables/comprehensive_security_assessment_report.md.
Use deliverables/pre_recon_deliverable.md and deliverables/recon_deliverable.md for context.
Save using save_deliverable with type REPORT.

Wait for completion.

Completion

Report the final status:

• List all deliverable files created in deliverables/
• Summarize which phases completed successfully
• Note any phases that were skipped (empty exploitation queues)
• Provide the path to the final report: deliverables/comprehensive_security_assessment_report.md