JSPM

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   ██████╗ ███████╗███╗   ██╗████████╗███████╗███████╗████████╗║
║   ██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝║
║   ██████╔╝█████╗  ██╔██╗ ██║   ██║   █████╗  ███████╗   ██║   ║
║   ██╔═══╝ ██╔══╝  ██║╚██╗██║   ██║   ██╔══╝  ╚════██║   ██║   ║
║   ██║     ███████╗██║ ╚████║   ██║   ███████╗███████║   ██║   ║
║   ╚═╝     ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚══════╝   ╚═╝   ║
║                                                               ║
║        🎯 DEF CON-level Autonomous Pentesting Agent           ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

🚀 Quick Start

# Install
npm install -g pentesting

# Configure
export PENTEST_API_KEY=your_api_key
export PENTEST_BASE_URL=https://your-api-endpoint.com/v1
export PENTEST_MODEL=your-model-name

# Run
pentesting

✨ Features

• 10-Phase Attack Workflow: Recon → Scan → Enum → Vuln Analysis → Exploitation → PrivEsc → Pivot → Persist → Exfil → Report
• 9 Specialized Agents: Built-in experts for each security domain
• Ralph Loop: Autonomous iteration until objective is achieved
• Streaming Responses: Real-time LLM output
• Session Persistence: Save/resume pentesting sessions
• Tool Approval: Manual confirmation for dangerous commands
• MCP Integration: Extend with Model Context Protocol tools
• Docker Toolkit: 50+ pre-installed pentesting tools
• Provider Agnostic: Works with any OpenAI-compatible API

📖 CLI Commands

# Target & Session
/target <ip>        Set target
/start [objective]  Start autonomous pentest
/sessions           List saved sessions
/resume [id]        Resume a session

# Scanning & Enumeration
/scan <target>      Quick enumeration
/web <url>          Web application testing

# Exploitation
/exploit <service>  Search for exploits
/privesc [os]       Check privilege escalation vectors
/attack <objective> Execute attack chain
/hash <hash>        Identify and crack hashes

# Reporting
/report             Generate pentest report
/findings           Show findings

# Control
/yolo               Toggle auto-approve mode
/approve /deny      Approve/deny tool execution
/clear              Clear screen
/exit               Exit

🤖 Built-in Agents

⚙️ Configuration

Environment Variables

Note: ANTHROPIC_API_KEY is also accepted as fallback for PENTEST_API_KEY.

💻 Programmatic Usage

import { PentestingAgent, PENTEST_EVENT } from 'pentesting';

const agent = new PentestingAgent({
    yoloMode: false,          // Require approval for dangerous tools
    useStreaming: true,       // Enable streaming responses
    maxIterations: 100,       // Max Ralph loop iterations
    autoSave: true,           // Auto-save session state
});

// Listen for events
agent.on(PENTEST_EVENT.FINDING, (finding) => {
    console.log(`Found: ${finding.title} (${finding.severity})`);
});

agent.on(PENTEST_EVENT.APPROVAL_NEEDED, (request) => {
    console.log(`Approval needed for: ${request.toolName}`);
    agent.approveToolCall(request.id, 'approve');
});

agent.on(PENTEST_EVENT.TEXT_DELTA, (text) => {
    process.stdout.write(text);
});

// Start pentesting
await agent.start('Get root access', '192.168.1.100');

// Or use individual commands
const scanResult = await agent.chat('/scan 10.10.10.1');
const exploitResult = await agent.chat('/exploit Apache 2.4.49');

🐳 Docker Environment

# Pull pre-built toolkit (50+ tools)
docker pull agnusdei1207/pentesting-tools:latest

# Run with host network (required for target access)
docker run -d --name pentesting-tools --network host \
  -v $(pwd)/workspace:/pentest \
  agnusdei1207/pentesting-tools:latest

# Execute tools
docker exec -it pentesting-tools nmap -sCV 10.0.0.1

🔌 MCP Integration

Extend with additional MCP servers:

const agent = new PentestingAgent();

// Add filesystem access
await agent.addMCPServer('filesystem', 'npx', [
    '-y', '@modelcontextprotocol/server-filesystem', '/'
]);

// Add custom security tools
await agent.addMCPServer('security-tools', 'docker', [
    'exec', '-i', 'pentesting-tools', '/bin/bash'
]);

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        TUI (app.tsx)                         │
│  - Streaming text display                                    │
│  - Tool approval prompts                                     │
│  - Session management                                        │
└──────────────────────────┬──────────────────────────────────┘
                          │ Wire Protocol
┌──────────────────────────▼──────────────────────────────────┐
│                 PentestingAgent (Unified)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ RalphLoop    │  │ Streaming    │  │ Session      │       │
│  │ (Auto-iter)  │  │ Handler      │  │ Manager      │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │         AutonomousHackingAgent (Core)             │       │
│  │  ┌──────────────────────────────────────────┐    │       │
│  │  │ 9 Built-in Specialized Agents            │    │       │
│  │  └──────────────────────────────────────────┘    │       │
│  └──────────────────────────────────────────────────┘       │
└──────────────────────────┬──────────────────────────────────┘
                          │
         ┌────────────────┼────────────────┐
    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐
    │ Tool    │     │  Bash   │     │   MCP   │
    │Executor │     │ Commands│     │ Servers │
    └─────────┘     └─────────┘     └─────────┘

📁 Project Structure

src/
├── index.tsx              # CLI entry point
├── cli/app.tsx            # TUI with streaming, approval, sessions
├── core/
│   ├── agent/             # Agent implementations
│   ├── approval/          # Tool approval system
│   ├── context/           # Conversation compaction
│   ├── hooks/             # Event hooks
│   ├── loop/              # Ralph autonomous loop
│   ├── session/           # Session persistence
│   ├── streaming/         # Real-time streaming
│   ├── prompts/           # System prompts
│   └── tools/             # Tool definitions & executor
├── agents/index.ts        # 9 built-in specialized agents
├── commands/index.ts      # Built-in slash commands
├── wire/                  # Agent-UI communication
├── mcp/                   # MCP client integration
└── config/                # Constants, theme

🛠️ Development

# Clone
git clone https://github.com/agnusdei1207/pentesting.git
cd pentesting

# Install
npm install

# Build
npm run build

# Dev mode
npm run dev

📚 Documentation

• Architecture - System design and components
• API Reference - Full API documentation
• Troubleshooting - Common issues

⚠️ Legal

Only use on systems you own or have explicit permission to test.

This tool is for authorized penetration testing and CTF competitions only. Unauthorized access to computer systems is illegal.

📄 License

MIT