JSPM

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

🚀 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

🧠 Philosophy: Think Like a Hacker

Pentesting is not a brute-force tool. It's an intelligent agent that thinks strategically.

Strategic Decision Framework

Every action is evaluated using:

Value = (Probability × CVSS Impact) / Time Cost

The agent only executes actions with confidence >50%. Below that, it finds a better approach.

Self-Reflection Before Every Action

Before running any tool, the agent asks:

• "What exactly am I trying to learn?"
• "Is this the FASTEST way to get that information?"
• "Have I already tried this? What happened?"
• "Is there a simpler approach?"

Mandatory Fallback Strategy

When a tool fails, the agent immediately tries alternatives:

🔥 Why Pentesting?

✨ Core Capabilities

• 10-Phase Attack Workflow: Recon → Scan → Enum → Vuln Analysis → Exploitation → PrivEsc → Pivot → Persist → Exfil → Report
• Auto Docker Management: Pulls and starts tool container automatically
• Multi-Target Attack: Attack multiple targets sequentially
• Real-time Feedback: See thinking process, tool calls, results live
• Session Persistence: Save/resume attack sessions
• Context Compaction: Automatic history summarization

📖 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 (primary)
  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

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 │
     └─────────┘       └─────────┘       └─────────┘

🛠️ Development

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

# Install
npm install

# Build
npm run build

# Dev mode
npm run dev

📄 License

Documentation

• Architecture - System design and components
• Docker Image - Pre-built security tools

�📄 License

MIT