JSPM

   ██████╗ ███████╗███╗   ██╗████████╗███████╗███████╗████████╗██╗███╗   ██╗ ██████╗ 
   ██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██║████╗  ██║██╔════╝ 
   ██████╔╝█████╗  ██╔██╗ ██║   ██║   █████╗  ███████╗   ██║   ██║██╔██╗ ██║██║  ███╗
   ██╔═══╝ ██╔══╝  ██║╚██╗██║   ██║   ██╔══╝  ╚════██║   ██║   ██║██║╚██╗██║██║   ██║
   ██║     ███████╗██║ ╚████║   ██║   ███████╗███████║   ██║   ██║██║ ╚████║╚██████╔╝
   ╚═╝     ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚═╝╚═╝  ╚═══╝ ╚═════╝ 

Autonomous AI Penetration Testing 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

Core Capabilities

• 10-Phase Attack Workflow: Recon → Scan → Enum → Vuln Analysis → Exploitation → PrivEsc → Pivot → Persist → Exfil → Report
• 9 Specialized Agents: Built-in domain experts for security testing
• Multi-Target Attack: Register multiple targets and attack them sequentially
• Auto-Target Detection: Automatically sets targets from user input
• Streaming Responses: Real-time LLM output display
• Session Persistence: Save/resume pentesting sessions
• ESC Interrupt: Stop execution anytime with ESC key
• MCP Integration: Extend with Model Context Protocol tools
• Docker Toolkit: 50+ pre-installed pentesting tools
• Provider Agnostic: Works with any OpenAI-compatible API

v0.7+ New Features

• Multi-Target Management: /target add, /target list, /target clear
• Batch Attack: /start all to attack all registered targets
• set_target Tool: Agent can set targets directly via tool call
• Enhanced ESC: Properly interrupts even during tool execution
• UI State Sync: Real-time status bar updates for findings/creds/targets

📖 CLI Commands

Target Management

/target <domain|ip>     Set primary target
/target add <t>         Add target to list
/target list            Show all targets (★ = primary)
/target rm <t>          Remove target from list
/target set <t>         Set as primary target
/target clear           Remove ALL targets

Attack Execution

/start [objective]      Start pentest on primary target
/start all              Attack ALL registered targets sequentially
/stop                   Stop current operation
/status                 Show status report

Session Management

/checkpoint [desc]      Create checkpoint with optional description
/checkpoints            List all checkpoints
/undo                   Undo to last checkpoint
/revert <id>            Revert to specific checkpoint
/compact                Compact context (keep last 3 messages)
/sessions               List saved sessions
/resume [id]            Resume a session
/replay                 Show session recordings

Skills & Extras

/skills                 List available skills
/update                 Check for updates
/update now             Install update

Findings & Reports

/findings               Show discovered findings
/report                 Generate pentest report

Utility

/paste                  Paste from clipboard (text or image)
/yolo                   Toggle auto-approve mode
/clear                  Clear screen
/exit                   Exit
/y /n /ya               Approve/Deny/Always approve (for pending tools)

🎯 Multi-Target Workflow

# Start pentesting CLI
pentesting

# Register multiple targets
/target add example1.com
/target add example2.com
/target add 192.168.1.1
/target add internal.corp

# View registered targets
/target list
🎯 Targets (4):
  1. ★ example1.com
  2.   example2.com
  3.   192.168.1.1
  4.   internal.corp

# Attack all targets sequentially
/start all

🚀 Starting multi-target attack on 4 targets

━━━ [1/4] example1.com ━━━
📁 Session: session-1707325423
... reconnaissance & exploitation ...

━━━ [2/4] example2.com ━━━
...

# Press ESC to stop between targets
⏸ Stopped at target 2/4

✓ Multi-target attack complete

🤖 Built-in Agents

⚙️ Configuration

Environment Variables

Note: ANTHROPIC_API_KEY is also accepted as fallback for PENTEST_API_KEY.

💻 Programmatic Usage

import { AutonomousHackingAgent, AGENT_EVENT } from 'pentesting';

const agent = new AutonomousHackingAgent(undefined, {
    autoApprove: false,       // Require approval for dangerous tools
    maxIterations: 100,       // Max loop iterations
});

// Multi-target setup
agent.addTarget('example1.com');
agent.addTarget('example2.com');
agent.setTarget('example1.com');

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

agent.on(AGENT_EVENT.TARGET_SET, (target) => {
    console.log(`Target set: ${target}`);
});

agent.on(AGENT_EVENT.TOOL_CALL, ({ name, input }) => {
    console.log(`Tool: ${name}`);
});

// Start pentesting
await agent.runAutonomous('Get root access');

// Control execution
agent.pause();    // Pause (ESC key equivalent)
agent.resume();   // Resume
agent.abort();    // Complete stop

🐳 Docker Toolkit (Auto-Managed)

Pentesting automatically manages a Docker container with 50+ pre-installed tools.

Automatic Setup

No manual Docker setup required! When you run a command that needs tools like nmap or rustscan:

1. Pentesting checks if tool exists locally
2. If not, it automatically pulls agnusdei1207/pentesting-tools:latest
3. Starts container pentesting-tools with host network
4. Executes command via docker exec

Manual Docker Control

# Force all commands through Docker
export PENTESTING_DOCKER=1

# Use custom container name
export PENTESTING_CONTAINER=my-pentest-container

# Manual pull (optional - auto-pulled on first use)
docker pull agnusdei1207/pentesting-tools:latest

Included Tools (50+)

🔌 MCP Integration

Extend with additional MCP servers:

const agent = new AutonomousHackingAgent();

// 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)                            │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│  │ WireLogger   │ │ContextMgr   │ │ Multi-Target Handler     │ │
│  │ (Recording)  │ │(Checkpoints)│ │ (add/list/rm/clear/all)  │ │
│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│  │ KeyboardLstn │ │ ForceUpdate  │ │ SlashCommandRegistry     │ │
│  │ (ESC/Ctrl+C) │ │ (UI Refresh) │ │ (Command Handling)       │ │
│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
                             │ Events
┌────────────────────────────▼────────────────────────────────────┐
│              AutonomousHackingAgent (Core Engine)                │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐             │
│  │ HookExecutor │ │ MCPManager   │ │ApprovalMgr   │             │
│  │ (Lifecycle)  │ │ (Extensions) │ │(Tool Safety) │             │
│  └──────────────┘ └──────────────┘ └──────────────┘             │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐             │
│  │ TargetMgr    │ │ PauseMgr     │ │ContextMgr    │             │
│  │ (Multi-Tgt)  │ │ (ESC/Abort)  │ │ (Compaction) │             │
│  └──────────────┘ └──────────────┘ └──────────────┘             │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │            9 Built-in Specialized Agents                   │ │
│  │  target-explorer • exploit-researcher • privesc-master     │ │
│  │  web-hacker • crypto-solver • forensics-analyst            │ │
│  │  reverse-engineer • attack-architect • finding-reviewer    │ │
│  └────────────────────────────────────────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
     ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
     │  Tool   │       │  Bash   │       │   MCP   │
     │Executor │       │Commands │       │ Servers │
     └─────────┘       └─────────┘       └─────────┘

📁 Project Structure

src/
├── index.tsx              # CLI entry point
├── cli/
│   ├── app.tsx            # TUI with streaming, multi-target, approval
│   ├── components/        # Rich display components
│   └── utils/             # Keyboard listener
├── core/
│   ├── agent/             # Agent implementations
│   ├── approval/          # Tool approval system
│   ├── commands/          # Slash command registry
│   ├── context/           # Checkpoint + compaction
│   ├── display/           # Rich output blocks
│   ├── hooks/             # Event hooks
│   ├── loop/              # Ralph autonomous loop
│   ├── replay/            # Session replay
│   ├── session/           # Session persistence
│   ├── skill/             # Flow skills (Mermaid/D2)
│   ├── streaming/         # Real-time streaming
│   ├── update/            # Auto-update system
│   ├── prompts/           # System prompts
│   └── tools/             # Tool definitions & executor
├── agents/                # 9 built-in specialized agents
├── commands/              # Built-in slash commands
├── wire/                  # JSONL logging + Wire protocol
├── mcp/                   # MCP client integration
├── utils/                 # Clipboard, retry 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

📚 Changelog

v0.7.7

• Multi-target management (/target add/list/rm/clear)
• Batch attack (/start all)
• set_target tool for agent

v0.7.6

• ESC interrupt improvements
• UI state sync for findings/creds/phase

v0.7.5

• set_target tool integration
• forceUpdate mechanism for React state

v0.7.4

• Removed all legal/permission prompts
• Auto-target detection from user input

📄 License

MIT