pentesting 0.1.12 → 0.2.1
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 +177 -80
- package/dist/index.js +1969 -331
- 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
|
|
@@ -29,15 +31,132 @@ npm install -g pentesting
|
|
|
29
31
|
### Configure
|
|
30
32
|
|
|
31
33
|
```bash
|
|
34
|
+
# Anthropic API
|
|
35
|
+
export ANTHROPIC_API_KEY=your_api_key
|
|
36
|
+
|
|
37
|
+
# OpenAI-compatible APIs (GLM, etc.)
|
|
32
38
|
export ANTHROPIC_API_KEY=your_api_key
|
|
39
|
+
export ANTHROPIC_BASE_URL=https://your-api-endpoint.com/v1
|
|
40
|
+
|
|
41
|
+
# Optional
|
|
42
|
+
export PENTEST_MODEL=claude-sonnet-4-20250514 # or your model
|
|
43
|
+
export PENTEST_MAX_TOKENS=16384
|
|
33
44
|
```
|
|
34
45
|
|
|
35
46
|
### Run
|
|
36
47
|
|
|
37
48
|
```bash
|
|
38
|
-
pentesting
|
|
39
|
-
#
|
|
40
|
-
|
|
49
|
+
pentesting # Interactive mode
|
|
50
|
+
pentesting --yolo # Auto-approve all tools (dangerous!)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## CLI Commands
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
/target <ip> Set target
|
|
57
|
+
/start [objective] Start autonomous pentest
|
|
58
|
+
/scan <target> Quick enumeration
|
|
59
|
+
/exploit <service> Search for exploits
|
|
60
|
+
/privesc [os] Check privilege escalation vectors
|
|
61
|
+
/web <url> Web application testing
|
|
62
|
+
/hash <hash> Identify and crack hashes
|
|
63
|
+
/attack <objective> Execute attack chain
|
|
64
|
+
/report Generate pentest report
|
|
65
|
+
/sessions List saved sessions
|
|
66
|
+
/resume [id] Resume a session
|
|
67
|
+
/yolo Toggle auto-approve mode
|
|
68
|
+
/approve /deny Approve/deny tool execution
|
|
69
|
+
/findings Show findings
|
|
70
|
+
/clear Clear screen
|
|
71
|
+
/exit Exit
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Built-in Agents
|
|
75
|
+
|
|
76
|
+
| Agent | Specialty |
|
|
77
|
+
|-------|-----------|
|
|
78
|
+
| **target-explorer** | Network reconnaissance, service enumeration |
|
|
79
|
+
| **exploit-researcher** | CVE research, exploit development |
|
|
80
|
+
| **privesc-master** | Linux/Windows privilege escalation |
|
|
81
|
+
| **web-hacker** | OWASP Top 10, SQLi, XSS, SSRF |
|
|
82
|
+
| **crypto-solver** | Hash cracking, cipher analysis |
|
|
83
|
+
| **forensics-analyst** | Memory forensics, file carving |
|
|
84
|
+
| **reverse-engineer** | Binary analysis, exploit development |
|
|
85
|
+
| **attack-architect** | Attack strategy planning |
|
|
86
|
+
| **finding-reviewer** | Vulnerability validation |
|
|
87
|
+
|
|
88
|
+
## Architecture
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
92
|
+
│ TUI (app.tsx) │
|
|
93
|
+
│ - Streaming text display │
|
|
94
|
+
│ - Tool approval prompts │
|
|
95
|
+
│ - Session management │
|
|
96
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
97
|
+
│ Wire Protocol
|
|
98
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
99
|
+
│ PentestingAgent (Unified) │
|
|
100
|
+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
101
|
+
│ │ RalphLoop │ │ Streaming │ │ Session │ │
|
|
102
|
+
│ │ (Auto-iter) │ │ Handler │ │ Manager │ │
|
|
103
|
+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
104
|
+
│ │
|
|
105
|
+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
106
|
+
│ │ Context │ │ Retry │ │ Approval │ │
|
|
107
|
+
│ │ Compaction │ │ Handler │ │ Manager │ │
|
|
108
|
+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
109
|
+
│ │
|
|
110
|
+
│ ┌──────────────────────────────────────────────────┐ │
|
|
111
|
+
│ │ AutonomousHackingAgent (Core) │ │
|
|
112
|
+
│ │ ┌──────────────────────────────────────────┐ │ │
|
|
113
|
+
│ │ │ 9 Built-in Specialized Agents │ │ │
|
|
114
|
+
│ │ │ (No plugins needed) │ │ │
|
|
115
|
+
│ │ └──────────────────────────────────────────┘ │ │
|
|
116
|
+
│ │ - Hook System │ │
|
|
117
|
+
│ │ - MCP Client for Extended Tools │ │
|
|
118
|
+
│ └──────────────────────────────────────────────────┘ │
|
|
119
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
120
|
+
│
|
|
121
|
+
┌────────────────┼────────────────┐
|
|
122
|
+
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
|
|
123
|
+
│ Tool │ │ Bash │ │ MCP │
|
|
124
|
+
│Executor │ │ Commands│ │ Servers │
|
|
125
|
+
└─────────┘ └─────────┘ └─────────┘
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Programmatic Usage
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
import { PentestingAgent, PENTEST_EVENT } from 'pentesting';
|
|
132
|
+
|
|
133
|
+
const agent = new PentestingAgent({
|
|
134
|
+
yoloMode: false, // Require approval for dangerous tools
|
|
135
|
+
useStreaming: true, // Enable streaming responses
|
|
136
|
+
maxIterations: 100, // Max Ralph loop iterations
|
|
137
|
+
autoSave: true, // Auto-save session state
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
// Listen for events
|
|
141
|
+
agent.on(PENTEST_EVENT.FINDING, (finding) => {
|
|
142
|
+
console.log(`Found: ${finding.title} (${finding.severity})`);
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
agent.on(PENTEST_EVENT.APPROVAL_NEEDED, (request) => {
|
|
146
|
+
console.log(`Approval needed for: ${request.toolName}`);
|
|
147
|
+
agent.approveToolCall(request.id, 'approve');
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
agent.on(PENTEST_EVENT.TEXT_DELTA, (text) => {
|
|
151
|
+
process.stdout.write(text);
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
// Start pentesting
|
|
155
|
+
await agent.start('Get root access', '192.168.1.100');
|
|
156
|
+
|
|
157
|
+
// Or use individual commands
|
|
158
|
+
const scanResult = await agent.chat('/scan 10.10.10.1');
|
|
159
|
+
const exploitResult = await agent.chat('/exploit Apache 2.4.49');
|
|
41
160
|
```
|
|
42
161
|
|
|
43
162
|
## Docker Environment
|
|
@@ -55,89 +174,67 @@ docker run -d --name pentesting-tools --network host \
|
|
|
55
174
|
docker exec -it pentesting-tools nmap -sCV 10.0.0.1
|
|
56
175
|
```
|
|
57
176
|
|
|
58
|
-
##
|
|
177
|
+
## MCP Integration
|
|
59
178
|
|
|
60
|
-
|
|
179
|
+
Extend with additional MCP servers:
|
|
61
180
|
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
├── agents/ # 9 specialized AI agents
|
|
65
|
-
├── commands/ # 5 slash commands
|
|
66
|
-
├── hooks/ # Event handlers
|
|
67
|
-
└── skills/ # 9 domain skills
|
|
68
|
-
```
|
|
181
|
+
```typescript
|
|
182
|
+
const agent = new PentestingAgent();
|
|
69
183
|
|
|
70
|
-
|
|
184
|
+
// Add filesystem access
|
|
185
|
+
await agent.addMCPServer('filesystem', 'npx', [
|
|
186
|
+
'-y', '@modelcontextprotocol/server-filesystem', '/'
|
|
187
|
+
]);
|
|
71
188
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
/pentest-loop <target> <objective> # Autonomous attack loop
|
|
88
|
-
/scan <target> # Quick enumeration
|
|
89
|
-
/exploit <query> # Search/run exploits
|
|
90
|
-
/vuln-review # Review findings
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
## Architecture
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
┌──────────────────────────────────────────────────────────────┐
|
|
97
|
-
│ AutonomousHackingAgent │
|
|
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
|
-
└──────────────────────────────────────────────────────────────┘
|
|
189
|
+
// Add custom security tools
|
|
190
|
+
await agent.addMCPServer('security-tools', 'docker', [
|
|
191
|
+
'exec', '-i', 'pentesting-tools', '/bin/bash'
|
|
192
|
+
]);
|
|
111
193
|
```
|
|
112
194
|
|
|
113
195
|
## Configuration
|
|
114
196
|
|
|
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
197
|
### Environment Variables
|
|
135
198
|
|
|
136
199
|
| Variable | Description | Default |
|
|
137
200
|
|----------|-------------|---------|
|
|
138
201
|
| ANTHROPIC_API_KEY | Claude API key | Required |
|
|
202
|
+
| ANTHROPIC_BASE_URL | API endpoint URL (for GLM, etc.) | - |
|
|
139
203
|
| PENTEST_MODEL | Claude model | claude-sonnet-4-20250514 |
|
|
140
|
-
| PENTEST_MAX_TOKENS | Max response tokens |
|
|
204
|
+
| PENTEST_MAX_TOKENS | Max response tokens | 16384 |
|
|
205
|
+
| PENTESTING_DOCKER | Force Docker execution | 0 |
|
|
206
|
+
| PENTESTING_CONTAINER | Docker container name | pentesting-tools |
|
|
207
|
+
|
|
208
|
+
## Project Structure
|
|
209
|
+
|
|
210
|
+
```
|
|
211
|
+
src/
|
|
212
|
+
├── index.tsx # CLI entry point
|
|
213
|
+
├── cli/
|
|
214
|
+
│ └── app.tsx # TUI with streaming, approval, sessions
|
|
215
|
+
├── core/
|
|
216
|
+
│ ├── index.ts # All core exports
|
|
217
|
+
│ ├── agent/
|
|
218
|
+
│ │ ├── pentesting-agent.ts # Unified agent
|
|
219
|
+
│ │ ├── autonomous-agent.ts # Core agent logic
|
|
220
|
+
│ │ └── agent-orchestrator.ts # Parallel agent execution
|
|
221
|
+
│ ├── approval/ # Tool approval system
|
|
222
|
+
│ ├── context/ # Conversation compaction
|
|
223
|
+
│ ├── hooks/ # Event hooks
|
|
224
|
+
│ ├── loop/ # Ralph autonomous loop
|
|
225
|
+
│ ├── session/ # Session persistence
|
|
226
|
+
│ ├── streaming/ # Real-time streaming
|
|
227
|
+
│ ├── prompts/ # System prompts
|
|
228
|
+
│ └── tools/ # Tool definitions & executor
|
|
229
|
+
├── agents/
|
|
230
|
+
│ └── index.ts # 9 built-in specialized agents
|
|
231
|
+
├── commands/
|
|
232
|
+
│ └── index.ts # Built-in slash commands
|
|
233
|
+
├── wire/ # Agent-UI communication protocol
|
|
234
|
+
├── mcp/ # MCP client integration
|
|
235
|
+
├── utils/ # Retry logic, utilities
|
|
236
|
+
└── config/ # Constants, theme
|
|
237
|
+
```
|
|
141
238
|
|
|
142
239
|
## Development
|
|
143
240
|
|
|
@@ -160,7 +257,7 @@ npm run dev
|
|
|
160
257
|
|
|
161
258
|
⚠️ **Only use on systems you own or have explicit permission to test.**
|
|
162
259
|
|
|
163
|
-
This tool is for authorized penetration testing and CTF competitions only.
|
|
260
|
+
This tool is for authorized penetration testing and CTF competitions only. Unauthorized access to computer systems is illegal.
|
|
164
261
|
|
|
165
262
|
## License
|
|
166
263
|
|