Pentesting

🎯 DEF CON-level Autonomous Penetration Testing AI Agent

✨ Features

• 7-Phase Attack Workflow: Recon → Scan → Enum → Vuln Analysis → Exploitation → PrivEsc → Reporting
• 9 Specialized Agents: Built-in experts for each security domain
• Ralph Loop: Autonomous iteration until objective is achieved
• Streaming Responses: Real-time output from Claude
• 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

Quick Start

Install

npm install -g pentesting

Configure

# Required: API Key (either works)
export PENTEST_API_KEY=your_api_key
# or
export ANTHROPIC_API_KEY=your_api_key

# For other providers (GLM, OpenRouter, etc.)
export PENTEST_BASE_URL=https://your-api-endpoint.com/v1
export PENTEST_MODEL=your-model-name
export PENTEST_MAX_TOKENS=16384

Run

pentesting              # Interactive mode
pentesting --yolo       # Auto-approve all tools (dangerous!)

CLI Commands

/target <ip>        Set target
/start [objective]  Start autonomous pentest
/scan <target>      Quick enumeration
/exploit <service>  Search for exploits
/privesc [os]       Check privilege escalation vectors
/web <url>          Web application testing
/hash <hash>        Identify and crack hashes
/attack <objective> Execute attack chain
/report             Generate pentest report
/sessions           List saved sessions
/resume [id]        Resume a session
/yolo               Toggle auto-approve mode
/approve /deny      Approve/deny tool execution
/findings           Show findings
/clear              Clear screen
/exit               Exit

Built-in Agents

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        TUI (app.tsx)                         │
│  - Streaming text display                                    │
│  - Tool approval prompts                                     │
│  - Session management                                        │
└──────────────────────────┬──────────────────────────────────┘
                          │ Wire Protocol
┌──────────────────────────▼──────────────────────────────────┐
│                 PentestingAgent (Unified)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ RalphLoop    │  │ Streaming    │  │ Session      │       │
│  │ (Auto-iter)  │  │ Handler      │  │ Manager      │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Context      │  │ Retry        │  │ Approval     │       │
│  │ Compaction   │  │ Handler      │  │ Manager      │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │         AutonomousHackingAgent (Core)             │       │
│  │  ┌──────────────────────────────────────────┐    │       │
│  │  │ 9 Built-in Specialized Agents            │    │       │
│  │  │ (No plugins needed)                       │    │       │
│  │  └──────────────────────────────────────────┘    │       │
│  │  - Hook System                                    │       │
│  │  - MCP Client for Extended Tools                  │       │
│  └──────────────────────────────────────────────────┘       │
└──────────────────────────┬──────────────────────────────────┘
                          │
         ┌────────────────┼────────────────┐
    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐
    │ Tool    │     │  Bash   │     │   MCP   │
    │Executor │     │ Commands│     │ Servers │
    └─────────┘     └─────────┘     └─────────┘

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'
]);

Configuration

Environment Variables

Project Structure

src/
├── index.tsx              # CLI entry point
├── cli/
│   └── app.tsx            # TUI with streaming, approval, sessions
├── core/
│   ├── index.ts           # All core exports
│   ├── agent/
│   │   ├── pentesting-agent.ts   # Unified agent
│   │   ├── autonomous-agent.ts   # Core agent logic
│   │   └── agent-orchestrator.ts # Parallel agent execution
│   ├── 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 protocol
├── mcp/                   # MCP client integration
├── utils/                 # Retry logic, utilities
└── 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

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