pentesting 0.1.12 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +166 -79
- package/dist/index.js +1965 -329
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -9,13 +9,15 @@
|
|
|
9
9
|
[](https://www.npmjs.com/package/pentesting)
|
|
10
10
|
[](https://hub.docker.com/r/agnusdei1207/pentesting-tools)
|
|
11
11
|
|
|
12
|
-
## Features
|
|
13
|
-
|
|
14
|
-
- **7-Phase Workflow**: Recon → Enum → Vuln Analysis → Exploitation → PrivEsc →
|
|
15
|
-
- **
|
|
16
|
-
- **Ralph
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
12
|
+
## ✨ Features
|
|
13
|
+
|
|
14
|
+
- **7-Phase Attack Workflow**: Recon → Scan → Enum → Vuln Analysis → Exploitation → PrivEsc → Reporting
|
|
15
|
+
- **9 Specialized Agents**: Built-in experts for each security domain
|
|
16
|
+
- **Ralph Loop**: Autonomous iteration until objective is achieved
|
|
17
|
+
- **Streaming Responses**: Real-time output from Claude
|
|
18
|
+
- **Session Persistence**: Save/resume pentesting sessions
|
|
19
|
+
- **Tool Approval**: Manual confirmation for dangerous commands
|
|
20
|
+
- **MCP Integration**: Extend with Model Context Protocol tools
|
|
19
21
|
- **Docker Toolkit**: 50+ pre-installed pentesting tools
|
|
20
22
|
|
|
21
23
|
## Quick Start
|
|
@@ -35,9 +37,117 @@ export ANTHROPIC_API_KEY=your_api_key
|
|
|
35
37
|
### Run
|
|
36
38
|
|
|
37
39
|
```bash
|
|
38
|
-
pentesting
|
|
39
|
-
#
|
|
40
|
-
|
|
40
|
+
pentesting # Interactive mode
|
|
41
|
+
pentesting --yolo # Auto-approve all tools (dangerous!)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## CLI Commands
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
/target <ip> Set target
|
|
48
|
+
/start [objective] Start autonomous pentest
|
|
49
|
+
/scan <target> Quick enumeration
|
|
50
|
+
/exploit <service> Search for exploits
|
|
51
|
+
/privesc [os] Check privilege escalation vectors
|
|
52
|
+
/web <url> Web application testing
|
|
53
|
+
/hash <hash> Identify and crack hashes
|
|
54
|
+
/attack <objective> Execute attack chain
|
|
55
|
+
/report Generate pentest report
|
|
56
|
+
/sessions List saved sessions
|
|
57
|
+
/resume [id] Resume a session
|
|
58
|
+
/yolo Toggle auto-approve mode
|
|
59
|
+
/approve /deny Approve/deny tool execution
|
|
60
|
+
/findings Show findings
|
|
61
|
+
/clear Clear screen
|
|
62
|
+
/exit Exit
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Built-in Agents
|
|
66
|
+
|
|
67
|
+
| Agent | Specialty |
|
|
68
|
+
|-------|-----------|
|
|
69
|
+
| **target-explorer** | Network reconnaissance, service enumeration |
|
|
70
|
+
| **exploit-researcher** | CVE research, exploit development |
|
|
71
|
+
| **privesc-master** | Linux/Windows privilege escalation |
|
|
72
|
+
| **web-hacker** | OWASP Top 10, SQLi, XSS, SSRF |
|
|
73
|
+
| **crypto-solver** | Hash cracking, cipher analysis |
|
|
74
|
+
| **forensics-analyst** | Memory forensics, file carving |
|
|
75
|
+
| **reverse-engineer** | Binary analysis, exploit development |
|
|
76
|
+
| **attack-architect** | Attack strategy planning |
|
|
77
|
+
| **finding-reviewer** | Vulnerability validation |
|
|
78
|
+
|
|
79
|
+
## Architecture
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
83
|
+
│ TUI (app.tsx) │
|
|
84
|
+
│ - Streaming text display │
|
|
85
|
+
│ - Tool approval prompts │
|
|
86
|
+
│ - Session management │
|
|
87
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
88
|
+
│ Wire Protocol
|
|
89
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
90
|
+
│ PentestingAgent (Unified) │
|
|
91
|
+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
92
|
+
│ │ RalphLoop │ │ Streaming │ │ Session │ │
|
|
93
|
+
│ │ (Auto-iter) │ │ Handler │ │ Manager │ │
|
|
94
|
+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
95
|
+
│ │
|
|
96
|
+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
97
|
+
│ │ Context │ │ Retry │ │ Approval │ │
|
|
98
|
+
│ │ Compaction │ │ Handler │ │ Manager │ │
|
|
99
|
+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
100
|
+
│ │
|
|
101
|
+
│ ┌──────────────────────────────────────────────────┐ │
|
|
102
|
+
│ │ AutonomousHackingAgent (Core) │ │
|
|
103
|
+
│ │ ┌──────────────────────────────────────────┐ │ │
|
|
104
|
+
│ │ │ 9 Built-in Specialized Agents │ │ │
|
|
105
|
+
│ │ │ (No plugins needed) │ │ │
|
|
106
|
+
│ │ └──────────────────────────────────────────┘ │ │
|
|
107
|
+
│ │ - Hook System │ │
|
|
108
|
+
│ │ - MCP Client for Extended Tools │ │
|
|
109
|
+
│ └──────────────────────────────────────────────────┘ │
|
|
110
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
111
|
+
│
|
|
112
|
+
┌────────────────┼────────────────┐
|
|
113
|
+
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
|
|
114
|
+
│ Tool │ │ Bash │ │ MCP │
|
|
115
|
+
│Executor │ │ Commands│ │ Servers │
|
|
116
|
+
└─────────┘ └─────────┘ └─────────┘
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Programmatic Usage
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
import { PentestingAgent, PENTEST_EVENT } from 'pentesting';
|
|
123
|
+
|
|
124
|
+
const agent = new PentestingAgent({
|
|
125
|
+
yoloMode: false, // Require approval for dangerous tools
|
|
126
|
+
useStreaming: true, // Enable streaming responses
|
|
127
|
+
maxIterations: 100, // Max Ralph loop iterations
|
|
128
|
+
autoSave: true, // Auto-save session state
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
// Listen for events
|
|
132
|
+
agent.on(PENTEST_EVENT.FINDING, (finding) => {
|
|
133
|
+
console.log(`Found: ${finding.title} (${finding.severity})`);
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
agent.on(PENTEST_EVENT.APPROVAL_NEEDED, (request) => {
|
|
137
|
+
console.log(`Approval needed for: ${request.toolName}`);
|
|
138
|
+
agent.approveToolCall(request.id, 'approve');
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
agent.on(PENTEST_EVENT.TEXT_DELTA, (text) => {
|
|
142
|
+
process.stdout.write(text);
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
// Start pentesting
|
|
146
|
+
await agent.start('Get root access', '192.168.1.100');
|
|
147
|
+
|
|
148
|
+
// Or use individual commands
|
|
149
|
+
const scanResult = await agent.chat('/scan 10.10.10.1');
|
|
150
|
+
const exploitResult = await agent.chat('/exploit Apache 2.4.49');
|
|
41
151
|
```
|
|
42
152
|
|
|
43
153
|
## Docker Environment
|
|
@@ -55,82 +165,26 @@ docker run -d --name pentesting-tools --network host \
|
|
|
55
165
|
docker exec -it pentesting-tools nmap -sCV 10.0.0.1
|
|
56
166
|
```
|
|
57
167
|
|
|
58
|
-
##
|
|
59
|
-
|
|
60
|
-
Based on Claude-Code plugin architecture:
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
plugins/pentesting-core/
|
|
64
|
-
├── agents/ # 9 specialized AI agents
|
|
65
|
-
├── commands/ # 5 slash commands
|
|
66
|
-
├── hooks/ # Event handlers
|
|
67
|
-
└── skills/ # 9 domain skills
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
### Agents
|
|
168
|
+
## MCP Integration
|
|
71
169
|
|
|
72
|
-
|
|
73
|
-
|-------|-----------|
|
|
74
|
-
| target-explorer | Reconnaissance |
|
|
75
|
-
| exploit-researcher | CVE/Exploit research |
|
|
76
|
-
| privesc-master | Privilege escalation |
|
|
77
|
-
| web-hacker | OWASP Top 10 |
|
|
78
|
-
| crypto-solver | Cryptography |
|
|
79
|
-
| forensics-analyst | Digital forensics |
|
|
80
|
-
| reverse-engineer | Binary analysis |
|
|
81
|
-
| attack-architect | Strategy planning |
|
|
82
|
-
| finding-reviewer | Validation |
|
|
83
|
-
|
|
84
|
-
### Commands
|
|
170
|
+
Extend with additional MCP servers:
|
|
85
171
|
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
/scan <target> # Quick enumeration
|
|
89
|
-
/exploit <query> # Search/run exploits
|
|
90
|
-
/vuln-review # Review findings
|
|
91
|
-
```
|
|
172
|
+
```typescript
|
|
173
|
+
const agent = new PentestingAgent();
|
|
92
174
|
|
|
93
|
-
|
|
175
|
+
// Add filesystem access
|
|
176
|
+
await agent.addMCPServer('filesystem', 'npx', [
|
|
177
|
+
'-y', '@modelcontextprotocol/server-filesystem', '/'
|
|
178
|
+
]);
|
|
94
179
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
100
|
-
│ │ Claude │ │ Plugin │ │ MCP │ │
|
|
101
|
-
│ │ API │ │ System │ │ Client │ │
|
|
102
|
-
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
103
|
-
│ │ │ │ │
|
|
104
|
-
│ ┌──────┴────────────────┴────────────────┴───────┐ │
|
|
105
|
-
│ │ Tool Executor │ │
|
|
106
|
-
│ │ (bash, nmap, sqlmap, msfconsole, etc.) │ │
|
|
107
|
-
│ └─────────────────────────────────────────────────┘ │
|
|
108
|
-
├──────────────────────────────────────────────────────────────┤
|
|
109
|
-
│ Hook System │ Command Parser │ Web Search │ Agents │
|
|
110
|
-
└──────────────────────────────────────────────────────────────┘
|
|
180
|
+
// Add custom security tools
|
|
181
|
+
await agent.addMCPServer('security-tools', 'docker', [
|
|
182
|
+
'exec', '-i', 'pentesting-tools', '/bin/bash'
|
|
183
|
+
]);
|
|
111
184
|
```
|
|
112
185
|
|
|
113
186
|
## Configuration
|
|
114
187
|
|
|
115
|
-
### MCP Servers
|
|
116
|
-
|
|
117
|
-
Create `.pentest/mcp.json`:
|
|
118
|
-
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"mcpServers": {
|
|
122
|
-
"filesystem": {
|
|
123
|
-
"command": "npx",
|
|
124
|
-
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/"]
|
|
125
|
-
},
|
|
126
|
-
"pentesting-tools": {
|
|
127
|
-
"command": "docker",
|
|
128
|
-
"args": ["exec", "-i", "pentesting-tools", "/bin/bash"]
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
}
|
|
132
|
-
```
|
|
133
|
-
|
|
134
188
|
### Environment Variables
|
|
135
189
|
|
|
136
190
|
| Variable | Description | Default |
|
|
@@ -138,6 +192,39 @@ Create `.pentest/mcp.json`:
|
|
|
138
192
|
| ANTHROPIC_API_KEY | Claude API key | Required |
|
|
139
193
|
| PENTEST_MODEL | Claude model | claude-sonnet-4-20250514 |
|
|
140
194
|
| PENTEST_MAX_TOKENS | Max response tokens | 8192 |
|
|
195
|
+
| PENTESTING_DOCKER | Force Docker execution | 0 |
|
|
196
|
+
| PENTESTING_CONTAINER | Docker container name | pentesting-tools |
|
|
197
|
+
|
|
198
|
+
## Project Structure
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
src/
|
|
202
|
+
├── index.tsx # CLI entry point
|
|
203
|
+
├── cli/
|
|
204
|
+
│ └── app.tsx # TUI with streaming, approval, sessions
|
|
205
|
+
├── core/
|
|
206
|
+
│ ├── index.ts # All core exports
|
|
207
|
+
│ ├── agent/
|
|
208
|
+
│ │ ├── pentesting-agent.ts # Unified agent
|
|
209
|
+
│ │ ├── autonomous-agent.ts # Core agent logic
|
|
210
|
+
│ │ └── agent-orchestrator.ts # Parallel agent execution
|
|
211
|
+
│ ├── approval/ # Tool approval system
|
|
212
|
+
│ ├── context/ # Conversation compaction
|
|
213
|
+
│ ├── hooks/ # Event hooks
|
|
214
|
+
│ ├── loop/ # Ralph autonomous loop
|
|
215
|
+
│ ├── session/ # Session persistence
|
|
216
|
+
│ ├── streaming/ # Real-time streaming
|
|
217
|
+
│ ├── prompts/ # System prompts
|
|
218
|
+
│ └── tools/ # Tool definitions & executor
|
|
219
|
+
├── agents/
|
|
220
|
+
│ └── index.ts # 9 built-in specialized agents
|
|
221
|
+
├── commands/
|
|
222
|
+
│ └── index.ts # Built-in slash commands
|
|
223
|
+
├── wire/ # Agent-UI communication protocol
|
|
224
|
+
├── mcp/ # MCP client integration
|
|
225
|
+
├── utils/ # Retry logic, utilities
|
|
226
|
+
└── config/ # Constants, theme
|
|
227
|
+
```
|
|
141
228
|
|
|
142
229
|
## Development
|
|
143
230
|
|
|
@@ -160,7 +247,7 @@ npm run dev
|
|
|
160
247
|
|
|
161
248
|
⚠️ **Only use on systems you own or have explicit permission to test.**
|
|
162
249
|
|
|
163
|
-
This tool is for authorized penetration testing and CTF competitions only.
|
|
250
|
+
This tool is for authorized penetration testing and CTF competitions only. Unauthorized access to computer systems is illegal.
|
|
164
251
|
|
|
165
252
|
## License
|
|
166
253
|
|