pentesting 0.8.40 → 0.8.42

package/README.md

@@ -18,13 +18,24 @@
 
 ---
 
+## Philosophy
+
+> **Think → Plan → Collaborate → Execute → Reflect → Adapt**
+
+Pentesting is not just a tool execution agent. It aims for **AGI-level autonomous thinking**:
+
+- 🧠 **Autonomous Decision** - Decide and act without asking the user
+- 🎯 **BFS First** - Breadth over depth, map the attack surface first
+- 🤝 **Agent Collaboration** - 9 specialist agents share knowledge and collaborate
+- 🔄 **Continuous Reflection** - Learn from failures and adjust strategy
+- 💾 **Shared Memory** - All agents share discoveries
+
+---
+
 ## Quick Start
 
 ```bash
-# Docker required for security tools (nmap, rustscan, etc.)
-# Install: https://docs.docker.com/get-docker/
-open -a Docker  # macOS - start Docker Desktop
-
+# Docker required for security tools
 npm install -g pentesting
 
 # Set API key
@@ -39,33 +50,72 @@ pentesting
 
 ---
 
-## Environment Variables
+## Architecture
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `PENTEST_API_KEY` | ✅ | - | API key (`ANTHROPIC_API_KEY` also works) |
-| `PENTEST_BASE_URL` | | - | Custom API endpoint URL |
-| `PENTEST_MODEL` | | `claude-sonnet-4-20250514` | LLM model name |
-| `PENTEST_MAX_TOKENS` | | `16384` | Max response tokens |
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SUPERVISOR AGENT                          │
+│              (Task Planning & Coordination)                  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     SHARED MEMORY                            │
+│     Short-Term │ Long-Term │ Episodic │ Attack Surface      │
+└─────────────────────────────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        ▼                   ▼                   ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│target-explorer│   │exploit-research│   │ privesc-master │
+│   web-hacker  │   │ crypto-solver │   │forensics-analyst│
+│reverse-engineer│  │attack-architect│  │finding-reviewer│
+└───────────────┘   └───────────────┘   └───────────────┘
+```
+
+### Core Components
+
+| Component | Role |
+|-----------|------|
+| **Supervisor Agent** | Task planning, agent selection, strategy adjustment |
+| **Shared Memory** | Cross-agent context sharing, failure recording |
+| **9 Specialists** | Domain expert agents |
+| **Orchestrator** | Parallel execution, result consolidation |
 
 ---
 
 ## Features
 
-- **Soul Architecture** - ReAct pattern: Think → Act → Observe → Reflect
-- **9 Specialized Agents** - Recon, Exploit, PrivEsc, Web, Crypto...
-- **80%+ Confidence Filter** - Only high-confidence findings
-- **D-Mail Time Travel** - Auto-recovery from dead ends
+- **Multi-Agent Orchestration** - 9 specialist agents collaborate
+- **Shared Memory System** - Cross-agent knowledge sharing
+- **Strategic Planning** - BFS-based attack surface mapping
+- **Self-Reflection** - Auto strategy change when stuck
+- **Handoff Protocol** - Context transfer between agents
+- **80%+ Confidence Filter** - Report only high-confidence findings
 - **50+ Security Tools** - nmap, sqlmap, gobuster, hydra...
 
 ---
 
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PENTEST_API_KEY` | ✅ | - | API key |
+| `PENTEST_BASE_URL` | | - | Custom API endpoint |
+| `PENTEST_MODEL` | | `claude-sonnet-4-20250514` | LLM model |
+| `PENTEST_MAX_TOKENS` | | `16384` | Max response tokens |
+
+---
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `/target <ip>` | Set target |
 | `/start [objective]` | Start autonomous pentest |
+| `/agent <name>` | Switch to specialist agent |
+| `/plan` | Show current attack plan |
+| `/memory` | Show shared memory state |
 | `/findings` | Show findings |
 | `/status` | Status |
 | `/yolo` | Toggle auto-approve |
@@ -73,11 +123,58 @@ pentesting
 
 ---
 
+## Specialized Agents
+
+| Agent | Specialty |
+|-------|-----------|
+| `target-explorer` | Recon, OSINT, Enumeration |
+| `exploit-researcher` | CVE, Exploit Development |
+| `privesc-master` | Linux/Windows Privilege Escalation |
+| `web-hacker` | Web Vulnerabilities, Injection |
+| `crypto-solver` | Hash Cracking, Cryptography |
+| `forensics-analyst` | Memory/File Analysis |
+| `reverse-engineer` | Binary Analysis, PWN |
+| `attack-architect` | Strategy, Attack Chains |
+| `finding-reviewer` | Validation, Confidence Scoring |
+
+---
+
+## Programmatic Usage
+
+```typescript
+import { 
+    getSupervisor, 
+    getAgentMemory, 
+    AutonomousHackingAgent 
+} from 'pentesting';
+
+// High-level: Supervisor orchestration
+const supervisor = getSupervisor();
+const plan = await supervisor.createPlan('Get root access', '10.10.10.5');
+const findings = await supervisor.executePlan();
+
+// Direct agent usage
+const agent = new AutonomousHackingAgent();
+await agent.start('Enumerate web application', 'http://target.com');
+```
+
+---
+
 ## Documentation
 
-- [Architecture](docs/architecture.md)
-- [API Reference](docs/api-reference.md)
-- [Troubleshooting](docs/troubleshooting.md)
+- [Architecture](docs/architecture.md) - System architecture details
+- [API Reference](docs/api-reference.md) - Programming interface
+- [Troubleshooting](docs/troubleshooting.md) - Problem solving
+
+---
+
+## Design Principles
+
+1. **BFS Over DFS** - Map attack surface completely first
+2. **Fail Fast, Pivot Quick** - Switch to alternative after 3 attempts
+3. **Shared Context** - All agents share discoveries
+4. **Confidence-Based** - Prioritize high-confidence findings
+5. **AGI-like Autonomy** - Decide without asking
 
 ---