PENTEST

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   ██████╗ ███████╗███╗   ██╗████████╗███████╗███████╗████████╗║
║   ██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝║
║   ██████╔╝█████╗  ██╔██╗ ██║   ██║   █████╗  ███████╗   ██║   ║
║   ██╔═══╝ ██╔══╝  ██║╚██╗██║   ██║   ██╔══╝  ╚════██║   ██║   ║
║   ██║     ███████╗██║ ╚████║   ██║   ███████╗███████║   ██║   ║
║   ╚═╝     ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚══════╝   ╚═╝   ║
║                                                               ║
║           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

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
• Ralph Loop: Autonomous iteration until objective is achieved
• Streaming Responses: Real-time LLM output display
• 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

v0.4+ New Features (kimi-cli inspired)

• Context Checkpoints: Save/restore conversation states with /checkpoint, /undo, /revert
• Flow Skills: Mermaid/D2 diagram-based workflow automation
• Session Replay: Review past sessions from wire recordings
• Auto-Update: Background version checking with update notifications
• Vision Analysis: Analyze images from clipboard with /paste
• Wire Logging: Detailed session recording in JSONL format
• Rich TUI: Premium ASCII banner, organized help, status reports

📖 CLI Commands

Core

/target <ip>        Set target IP/hostname
/start [objective]  Start autonomous pentest
/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)

🤖 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)                            │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│  │ WireLogger   │ │ContextMgr   │ │ SlashCommandRegistry     │ │
│  │ (Recording)  │ │(Checkpoints)│ │ (Command Handling)       │ │
│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
                             │ Events
┌────────────────────────────▼────────────────────────────────────┐
│              AutonomousHackingAgent (Core Engine)                │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐             │
│  │ HookExecutor │ │ MCPManager   │ │ApprovalMgr   │             │
│  │ (Lifecycle)  │ │ (Extensions) │ │(Tool Safety) │             │
│  └──────────────┘ └──────────────┘ └──────────────┘             │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │            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 │
     └─────────┘       └─────────┘       └─────────┘

Module Connectivity

Core Modules (src/core/):
├── agent/           AutonomousHackingAgent, PentestingAgent, AgentOrchestrator
├── approval/        ApprovalManager - tool execution safety
├── commands/        SlashCommandRegistry - command handling
├── context/         ContextManager (checkpoints) + Compaction (tokens)
├── display/         DisplayBlocks - rich output formatting
├── hooks/           HookExecutor - lifecycle events
├── loop/            RalphLoop - autonomous iteration
├── prompts/         System prompts for agents
├── replay/          SessionReplay - wire file parsing
├── session/         SessionManager - persistence
├── skill/           SkillManager + FlowExecutor - workflow automation
├── streaming/       StreamingAgent - real-time output
├── tools/           Tool definitions, executor, registry
└── update/          AutoUpdate - version management

Support Modules:
├── wire/            WireLogger (JSONL recording) + Wire Protocol
├── mcp/             MCPManager, MCPClient - extensions
├── utils/           Clipboard, Retry utilities
├── agents/          9 built-in specialized agents
├── commands/        Built-in slash commands
└── config/          Constants, Theme, Agent configuration

📁 Project Structure

src/
├── index.tsx              # CLI entry point
├── cli/
│   ├── app.tsx            # TUI with streaming, approval, sessions
│   └── components/        # Rich display components
├── 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

📚 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