---

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

pentesting
`

---

Architecture

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

$3

| 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

- 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 | Set target |
| /start [objective] | Start autonomous pentest |
| /agent | Switch to specialist agent |
| /plan | Show current attack plan |
| /memory | Show shared memory state |
| /findings | Show findings |
| /status | Status |
| /yolo | Toggle auto-approve |
| /help | Help |

---

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 - System architecture details
- API Reference - Programming interface
- Troubleshooting - 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

---

License

MIT

⚠️ For authorized security testing only.