pentesting 0.2.2 → 0.2.4

package/README.md

@@ -1,130 +1,120 @@
-# Pentesting
-
-> 🎯 DEF CON-level Autonomous Penetration Testing AI Agent
-
-<p align="center">
-  <img src="assets/logo.png" alt="Pentesting Logo" width="200"/>
-</p>
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                                                               ║
+║   ██████╗ ███████╗███╗   ██╗████████╗███████╗███████╗████████╗║
+║   ██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝║
+║   ██████╔╝█████╗  ██╔██╗ ██║   ██║   █████╗  ███████╗   ██║   ║
+║   ██╔═══╝ ██╔══╝  ██║╚██╗██║   ██║   ██╔══╝  ╚════██║   ██║   ║
+║   ██║     ███████╗██║ ╚████║   ██║   ███████╗███████║   ██║   ║
+║   ╚═╝     ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚══════╝   ╚═╝   ║
+║                                                               ║
+║        🎯 DEF CON-level Autonomous Pentesting Agent           ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
 
 [![npm version](https://badge.fury.io/js/pentesting.svg)](https://www.npmjs.com/package/pentesting)
 [![Docker](https://img.shields.io/badge/Docker-pentesting--tools-blue)](https://hub.docker.com/r/agnusdei1207/pentesting-tools)
 
-## ✨ 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
+## 🚀 Quick Start
 
 ```bash
+# Install
 npm install -g pentesting
-```
-
-### Configure
 
-```bash
-# Required: API Key (either works)
+# Configure
 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
 ```
 
-### Run
+---
 
-```bash
-pentesting              # Interactive mode
-pentesting --yolo       # Auto-approve all tools (dangerous!)
-```
+## ✨ 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
+## 📖 CLI Commands
 
 ```bash
+# 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
-/web <url>          Web application testing
-/hash <hash>        Identify and crack hashes
 /attack <objective> Execute attack chain
+/hash <hash>        Identify and crack hashes
+
+# Reporting
 /report             Generate pentest report
-/sessions           List saved sessions
-/resume [id]        Resume a session
+/findings           Show findings
+
+# Control
 /yolo               Toggle auto-approve mode
 /approve /deny      Approve/deny tool execution
-/findings           Show findings
 /clear              Clear screen
 /exit               Exit
 ```
 
-## Built-in Agents
+---
+
+## 🤖 Built-in Agents
 
 | Agent | Specialty |
 |-------|-----------|
-| **target-explorer** | Network reconnaissance, service enumeration |
-| **exploit-researcher** | CVE research, exploit development |
-| **privesc-master** | Linux/Windows privilege escalation |
-| **web-hacker** | OWASP Top 10, SQLi, XSS, SSRF |
-| **crypto-solver** | Hash cracking, cipher analysis |
-| **forensics-analyst** | Memory forensics, file carving |
-| **reverse-engineer** | Binary analysis, exploit development |
-| **attack-architect** | Attack strategy planning |
-| **finding-reviewer** | Vulnerability validation |
-
-## Architecture
+| `target-explorer` | Network reconnaissance, service enumeration |
+| `exploit-researcher` | CVE research, exploit development |
+| `privesc-master` | Linux/Windows privilege escalation |
+| `web-hacker` | OWASP Top 10, SQLi, XSS, SSRF |
+| `crypto-solver` | Hash cracking, cipher analysis |
+| `forensics-analyst` | Memory forensics, file carving |
+| `reverse-engineer` | Binary analysis, exploit development |
+| `attack-architect` | Attack strategy planning |
+| `finding-reviewer` | Vulnerability validation |
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        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 │
-    └─────────┘     └─────────┘     └─────────┘
-```
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PENTEST_API_KEY` | LLM API key | Required |
+| `PENTEST_BASE_URL` | API endpoint URL | - |
+| `PENTEST_MODEL` | Model name | claude-sonnet-4-20250514 |
+| `PENTEST_MAX_TOKENS` | Max response tokens | 16384 |
+| `PENTESTING_DOCKER` | Force Docker execution | 0 |
+| `PENTESTING_CONTAINER` | Docker container name | pentesting-tools |
 
-## Programmatic Usage
+> **Note**: `ANTHROPIC_API_KEY` is also accepted as fallback for `PENTEST_API_KEY`.
+
+---
+
+## 💻 Programmatic Usage
 
 ```typescript
 import { PentestingAgent, PENTEST_EVENT } from 'pentesting';
@@ -158,7 +148,9 @@ const scanResult = await agent.chat('/scan 10.10.10.1');
 const exploitResult = await agent.chat('/exploit Apache 2.4.49');
 ```
 
-## Docker Environment
+---
+
+## 🐳 Docker Environment
 
 ```bash
 # Pull pre-built toolkit (50+ tools)
@@ -173,7 +165,9 @@ docker run -d --name pentesting-tools --network host \
 docker exec -it pentesting-tools nmap -sCV 10.0.0.1
 ```
 
-## MCP Integration
+---
+
+## 🔌 MCP Integration
 
 Extend with additional MCP servers:
 
@@ -191,32 +185,50 @@ await agent.addMCPServer('security-tools', 'docker', [
 ]);
 ```
 
-## Configuration
+---
 
-### Environment Variables
+## 🏗️ Architecture
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| PENTEST_API_KEY | API key (alternative: ANTHROPIC_API_KEY) | Required |
-| PENTEST_BASE_URL | API endpoint URL (for GLM, etc.) | - |
-| PENTEST_MODEL | Model name | claude-sonnet-4-20250514 |
-| PENTEST_MAX_TOKENS | Max response tokens | 16384 |
-| PENTESTING_DOCKER | Force Docker execution | 0 |
-| PENTESTING_CONTAINER | Docker container name | pentesting-tools |
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        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
+---
+
+## 📁 Project Structure
 
 ```
 src/
 ├── index.tsx              # CLI entry point
-├── cli/
-│   └── app.tsx            # TUI with streaming, approval, sessions
+├── 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
+│   ├── agent/             # Agent implementations
 │   ├── approval/          # Tool approval system
 │   ├── context/           # Conversation compaction
 │   ├── hooks/             # Event hooks
@@ -225,17 +237,16 @@ src/
 │   ├── 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
+├── agents/index.ts        # 9 built-in specialized agents
+├── commands/index.ts      # Built-in slash commands
+├── wire/                  # Agent-UI communication
 ├── mcp/                   # MCP client integration
-├── utils/                 # Retry logic, utilities
 └── config/                # Constants, theme
 ```
 
-## Development
+---
+
+## 🛠️ Development
 
 ```bash
 # Clone
@@ -252,12 +263,24 @@ npm run build
 npm run dev
 ```
 
-## Legal
+---
+
+## 📚 Documentation
+
+- [Architecture](docs/architecture.md) - System design and components
+- [API Reference](docs/api-reference.md) - Full API documentation
+- [Troubleshooting](docs/troubleshooting.md) - Common issues
 
-⚠️ **Only use on systems you own or have explicit permission to test.**
+---
+
+## ⚠️ 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
+---
+
+## 📄 License
 
 MIT

package/dist/index.js

@@ -1374,15 +1374,12 @@ const { chromium } = require('playwright');
 }
 
 // src/config/constants.ts
-var APP_VERSION = "0.2.2";
+var APP_VERSION = "0.2.4";
 var APP_DESCRIPTION = "Autonomous Penetration Testing AI Agent";
 var LLM_API_KEY = process.env.PENTEST_API_KEY || process.env.ANTHROPIC_API_KEY || "";
-var LLM_BASE_URL = process.env.PENTEST_BASE_URL || process.env.PENTEST_API_URL || void 0;
+var LLM_BASE_URL = process.env.PENTEST_BASE_URL || void 0;
 var LLM_MODEL = process.env.PENTEST_MODEL || "claude-sonnet-4-20250514";
 var LLM_MAX_TOKENS = parseInt(process.env.PENTEST_MAX_TOKENS || "16384", 10);
-var CLAUDE_MODEL = LLM_MODEL;
-var CLAUDE_MAX_TOKENS = LLM_MAX_TOKENS;
-var ANTHROPIC_BASE_URL = LLM_BASE_URL;
 var AGENT_CONFIG = {
   maxIterations: 200,
   maxToolCallsPerIteration: 10,
@@ -1889,8 +1886,8 @@ async function compactHistory(client, messages, keepRecent = 4) {
     return `[${msg.role.toUpperCase()}]: ${content}`;
   }).join("\n\n");
   const response = await client.messages.create({
-    model: CLAUDE_MODEL,
-    max_tokens: CLAUDE_MAX_TOKENS,
+    model: LLM_MODEL,
+    max_tokens: LLM_MAX_TOKENS,
     system: COMPACTION_PROMPT,
     messages: [{
       role: "user",
@@ -2983,8 +2980,8 @@ var AutonomousHackingAgent = class extends EventEmitter3 {
   constructor(apiKey, config) {
     super();
     this.client = new Anthropic({
-      apiKey: apiKey || LLM_API_KEY || process.env.ANTHROPIC_API_KEY,
-      baseURL: ANTHROPIC_BASE_URL
+      apiKey: apiKey || LLM_API_KEY || process.env.PENTEST_API_KEY,
+      baseURL: LLM_BASE_URL
     });
     this.config = { ...AGENT_CONFIG, ...config };
     this.tools = ALL_TOOLS;
@@ -3238,7 +3235,7 @@ Current situation:
 What went wrong and what different approach should be tried?
 `;
     const response = await this.client.messages.create({
-      model: CLAUDE_MODEL,
+      model: LLM_MODEL,
       max_tokens: 4096,
       messages: [{ role: "user", content: reflectionPrompt }]
     });
@@ -3386,8 +3383,8 @@ Goal: Deep penetration to obtain root/system privileges, extract internal data,
     }
     const response = await withRetry(
       () => this.client.messages.create({
-        model: CLAUDE_MODEL,
-        max_tokens: CLAUDE_MAX_TOKENS,
+        model: LLM_MODEL,
+        max_tokens: LLM_MAX_TOKENS,
         system: systemPrompt,
         tools: this.tools,
         messages
@@ -3674,8 +3671,8 @@ ${this.state.findings.filter((f) => f.severity !== "info").map((f) => `- Address
     try {
       const systemPrompt = this.buildContextualPrompt();
       const response = await this.client.messages.create({
-        model: CLAUDE_MODEL,
-        max_tokens: CLAUDE_MAX_TOKENS,
+        model: LLM_MODEL,
+        max_tokens: LLM_MAX_TOKENS,
         system: systemPrompt,
         messages: this.state.history,
         tools: this.tools
@@ -3707,8 +3704,8 @@ ${this.state.findings.filter((f) => f.severity !== "info").map((f) => `- Address
       }
       if (hasToolCalls && response.stop_reason === "tool_use") {
         const followUp = await this.client.messages.create({
-          model: CLAUDE_MODEL,
-          max_tokens: CLAUDE_MAX_TOKENS,
+          model: LLM_MODEL,
+          max_tokens: LLM_MAX_TOKENS,
           system: systemPrompt,
           messages: this.state.history,
           tools: this.tools
@@ -4765,7 +4762,7 @@ ${chalk.hex(THEME.status.warning)("Examples:")}
 
 ${chalk.hex(THEME.status.warning)("Environment:")}
 
-  ${chalk.hex(THEME.text.accent)("ANTHROPIC_API_KEY")}    Required - Anthropic API key
+  ${chalk.hex(THEME.text.accent)("PENTEST_API_KEY")}      Required - LLM API key
   ${chalk.hex(THEME.text.accent)("PENTEST_MODEL")}        Optional - Model override
 
 ${chalk.hex(THEME.text.muted)("For ethical hacking and authorized testing only.")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pentesting",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Autonomous Penetration Testing AI Agent",
   "type": "module",
   "main": "dist/index.js",