claude-pentest

---

For authorized security testing only. Always obtain written permission before testing any system you do not own.

---

What this is

claude-pentest is a Claude Code plugin that gives Claude structured penetration testing capabilities. It is not a script or scanner, it is an agent coordination framework: the /pentest:pentest command coordinates the engagement from the main session — it runs reconnaissance, asks a planner agent for a deployment plan, then deploys specialized executor agents (each following a strict 4-phase workflow) in parallel, spending the time budget on escalation, and requiring operator approval before any active exploitation begins. Every finding ships with a working PoC, captured HTTP evidence, and a Playwright screenshot.

Key principles:

• Human-in-the-loop at every escalation point — Claude cannot proceed to exploitation without your confirmation
• Evidence-first — no theoretical findings, only verified PoCs with poc.py and poc_output.txt
• Structured outputs — every engagement writes machine-readable JSON + markdown analysis to outputs/{engagement}/
• Breadth — 11 attack domains, 63 sub-categories, 25+ security tools referenced

---

Install

First Add Marketplace

# Add marketplace from inside claude code
/plugin marketplace add Stickman230/claude-pentest

Then Install plugin

# Install plugin from inside claude code
/plugin install pentest@claude-pentest

The plugin installs into your project's .claude/ directory. Once installed, all agents, skills, and slash commands are available in any Claude Code session.

Optional: Kali Server (MKS)

For server-side testing (nmap, sqlmap, gobuster, Metasploit, etc.), the plugin can connect to a remote Kali Linux REST API. Without it, agents fall back to whatever tools are available locally via Bash.

Setup: Deploy MCP-Kali-Server on a Kali Linux host reachable from your machine, then run /pentest:pentest-kali in Claude Code to connect and save the configuration. The server URL and tool availability are written to .pentest-mks.json and picked up automatically at engagement launch.

---

Quick Start

The recommended way to start an engagement is via the guided slash command:

/pentest:pentest

This walks you through scope collection, attack profile selection, optional Kali server configuration, then runs the engagement itself (pre-flight → recon → planning → executor deployment → time-budget loop → report). See Slash Commands below for the full command reference.

---

Slash Commands

Five slash commands are included for guided session management. They are auto-discovered by Claude Code and invoked by name.

/pentest:pentest

Purpose: Guided engagement launcher and orchestrator — collects scope, attack profile, and Kali server configuration, then runs the engagement from the main session (the command owns dispatch because the harness allows only one level of subagent nesting).

Flow:

1. Displays ASCII art banner
2. Asks whether to isolate the session to the pentest plugin (recommended — prevents other plugins interfering with the engagement)
3. Checks for a saved scope (.pentest-scope.json) — if found, offers to reuse it or enter new scope. Collects the scope fields if entering new scope: target, engagement name, out-of-scope restrictions, time budget (the quota the engagement spends), authentication credentials, thoroughness level (Light / Medium / Deep / Full), and deliverable formats. Target, scope, auth, and time budget are free-text prompts; thoroughness and deliverable formats are multiple choice
4. Checks for a saved attack profile (.pentest-attacks.json) — if found, offers to use it or run the full suite. If no profile is found, offers inline mode selection (Full / Web app / API & cloud / Custom)
5. Checks for a configured Kali server (.pentest-mks.json) — if active, displays tool availability and asks whether to use MKS endpoints; if none is configured, offers to connect one inline (URL prompt + /health check) so you don't have to run a separate command and relaunch
6. Outputs an engagement summary for review
7. Runs the engagement from the main session: pre-flight reachability check → dispatches recon agents → invokes the pentester-orchestrator planner for a deployment plan → presents the plan for approval → deploys the specialized executor agents in parallel → time-budget quota loop (escalation) → aggregates → writes pentest-report.json + report.md

Isolation note: If isolation is selected in step 2, Claude constrains itself to pentest plugin agents and skills for the duration of the session. This constraint is lifted when /pentest:pentest-exit runs or /clear resets the context.

---

/pentest:pentest-scope

Purpose: Define or update engagement scope without launching a pentest. Useful for preparing scope ahead of time or updating scope mid-engagement.

Flow:

1. Reads any existing .pentest-scope.json and displays current scope if found
2. If an existing scope is found: offers update or cancel; detects drastic vs minor target changes when an engagement is active (drastic change = different domain or IP subnet triggers a warning with options)
3. Collects the scope fields in sequence (free-text for target/scope/auth/time budget; multiple choice for thoroughness and deliverable formats)
4. Writes .pentest-scope.json with status: pending
5. Displays a confirmation block with next steps

---

/pentest:pentest-attacks

Purpose: Define which attack categories the engagement should cover, without launching a pentest. Saves the profile for reuse across sessions.

Flow:

1. Reads any existing .pentest-attacks.json and displays it if found; offers update or keep
2. Mode selection: Full suite / Web application profile / API & cloud profile / Custom
3. Custom mode: three multi-select questions covering all 12 attack categories — each selection maps to the correct skill coordinator and executor agent(s)
4. Writes .pentest-attacks.json
5. Displays a confirmation block

Presets:

• Web app — injection, client-side, server-side, authentication, API security, business logic
• API & cloud — API security, cloud & containers, IP infrastructure, CVE testing, domain recon

---

/pentest:pentest-kali

Purpose: Connect a remote Metasploit-Kali Server (MKS) REST API (see Kali MCP) and configure agents to prefer its endpoints over local Bash equivalents.

Flow:

1. Asks for the MKS server URL (e.g., http://192.168.1.10:5000)
2. Verifies connectivity via /health endpoint
3. Parses and displays tool availability: nmap, gobuster, dirb, nikto (verified), sqlmap, hydra, john, metasploit (assumed)
4. Writes .pentest-mks.json with status: active
5. Displays the active MKS session block with curl usage examples for each tool

When MKS is active, the time-budget loop runs post-exploitation if a CVE or RCE finding is confirmed — deploying Metasploit via the MKS endpoint. It never runs speculatively.

---

/pentest:pentest-exit

Purpose: Structured session close — reads findings, flushes unsaved notes, outputs a severity-bucketed summary, resets session state, and lifts the isolation constraint.

Flow:

1. Asks for the engagement name (used as the outputs/{name}/ folder)
2. Reads findings from outputs/{name}/findings/ (Schema A) or outputs/{name}/processed/findings/ (Schema B) — whichever the engagement used
3. Flushes any unsaved in-progress notes or findings to disk
4. Outputs severity-bucketed session summary (Critical / High / Medium / Low / Info counts + top 3 findings)
5. Outputs an isolation lift instruction block
6. Resets both .pentest-scope.json and .pentest-attacks.json to status: pending — a subsequent /pentest:pentest will offer to reuse them rather than assuming they are still active
7. Prompts to run /clear to fully reset the context window before the next engagement

Note: Engagement outputs remain in outputs/{name}/ after /clear.

---

Session State Files

Three JSON files persist session configuration at the project root. They decouple preparation from launch — you can define scope, attack profile, and Kali server connection independently, then launch when ready.

File	Written by	Purpose
.pentest-scope.json	/pentest:pentest-scope, /pentest:pentest	Target, engagement name, out-of-scope, auth, timing (time budget/quota), thoroughness, output_formats, and status: pending|active
.pentest-attacks.json	/pentest:pentest-attacks, /pentest:pentest	Attack mode and selected categories with skill/executor mapping, and status: pending|active
.pentest-mks.json	/pentest:pentest-kali	Kali server URL, essential tool availability flags, and status: active

Lifecycle

/pentest:pentest-scope   → writes .pentest-scope.json   (status: pending)
/pentest:pentest-attacks → writes .pentest-attacks.json (status: pending)
/pentest:pentest-kali    → writes .pentest-mks.json     (status: active)
        ↓
/pentest:pentest reads all three files at launch:
  • scope found   → offers reuse or new scope; sets status: active on confirm
  • attacks found → offers reuse or full suite
  • MKS found     → offers MKS tools or skip; carries mks_active into the engagement
        ↓
The command runs the engagement: pre-flight → recon → planner → approval →
executor deployment → time-budget loop → report. Scope and MKS are already resolved.
        ↓
/pentest:pentest-exit resets scope and attacks to status: pending.
.pentest-mks.json is left active (server connection persists across engagements).

Typical workflows

Prepare ahead, launch when ready:

/pentest:pentest-scope    # define scope
/pentest:pentest-attacks  # define attack profile
/pentest:pentest-kali     # connect Kali server (optional)
/pentest:pentest          # launch — all three are detected and offered for reuse

Quick launch (no pre-configuration):