pentesting 0.100.13 โ 0.100.14
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 +84 -245
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,148 +1,73 @@
|
|
|
1
|
-
# Pentesting ๐
|
|
2
|
-
|
|
3
|
-
<div align="center">
|
|
4
|
-
<img src="https://api.iconify.design/hugeicons:bash.svg" alt="pentesting bash icon" width="120" />
|
|
5
|
-
<h1>pentesting</h1>
|
|
6
|
-
<p>Security-Focused Agent Runtime</p>
|
|
7
|
-
|
|
8
|
-
[](LICENSE)
|
|
9
|
-
[](https://www.npmjs.com/package/pentesting)
|
|
10
|
-
</div>
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## โ
Capabilities
|
|
15
|
-
|
|
16
|
-
Agent-loop essentials plus a security-focused runtime layer.
|
|
17
|
-
|
|
18
|
-
| Area | What it does |
|
|
19
|
-
| --- | --- |
|
|
20
|
-
| Model-driven loop | Streaming action/observation loop; model Stop ends a turn, while verified artifacts close a mission and the full turn trajectory is persisted with the outcome |
|
|
21
|
-
| Tool guardrails | Read-before-edit enforcement, repeat-call guard, policy-gated file/shell/network |
|
|
22
|
-
| Permissions | Allow / Deny / Confirm, with once/always decisions persisted |
|
|
23
|
-
| Context compaction | Automatic micro-pruning + model-triggered summarization, pre/post hooks |
|
|
24
|
-
| Interrupt & steering | ESC stops the current turn and auto loop; queued input uses revisioned FIFO amend/replace semantics and deterministic PTY Enter ownership |
|
|
25
|
-
| Reverse-shell control plane | Accept and track multiple authorized callbacks, tag/probe sessions, send/observe/run commands, verify PTY upgrades, and keep transcript/ledger/evidence records |
|
|
26
|
-
| PTY session control | One actor owns each socket/PTY/pipe, command queue, transcript, and child lifecycle, with resize gating, FD accounting, and deterministic close/revoke/gc reclamation |
|
|
27
|
-
| Frontier-guided exploration | Persistent lead ledger with explicit dispatch; breadth defaults to one and is hard-capped at four |
|
|
28
|
-
| Subagents | Explicit delegation to built-in specialists, including `crypto`, `rev`, and `pwn`; one selected agent can run up to four tasks concurrently |
|
|
29
|
-
| MCP & skills | Dynamic MCP tool discovery, layered markdown skills |
|
|
30
|
-
| Memory | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval |
|
|
31
|
-
|
|
32
|
-
---
|
|
33
|
-
|
|
34
|
-
Delegation is explicit. One `task` call selects one agent and may run its tasks
|
|
35
|
-
concurrently; separate top-level calls are sequenced. `explore dispatch` instead
|
|
36
|
-
uses `builder` clones with category overlays and waits for the batch. Both paths
|
|
37
|
-
share permissions, budgets, lineage, and evidence checks.
|
|
1
|
+
# Pentesting ๐
|
|
38
2
|
|
|
39
|
-
|
|
3
|
+
<div align="center">
|
|
4
|
+
<img src="https://api.iconify.design/hugeicons:bash.svg" alt="pentesting bash icon" width="120" />
|
|
5
|
+
<h1>pentesting</h1>
|
|
6
|
+
<p>Security-Focused Agent Runtime</p>
|
|
40
7
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
| Knowledge | BM25 + 768-D cosine search + BFS over adjacency maps/visited sets, fused by RRF; fixed 20-round PageRank at index build | Query `O(M + N(Q + D + log N) + V log V + E)` time and `O(N + V + D)` working space; index storage `O(M + ND + V + E)` |
|
|
45
|
-
| Runtime control | FIFO queues plus semaphore-bounded `join_all` fan-out | `O(T)` scheduling/result state, at most four active children per batch |
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](https://www.npmjs.com/package/pentesting)
|
|
10
|
+
</div>
|
|
46
11
|
|
|
47
|
-
|
|
48
|
-
terms, `D = 768`, and `V/E` graph nodes/links. Memory decay is constant-time per
|
|
49
|
-
note. Kruskal, Prim, and a generic divide-and-conquer engine are not runtime
|
|
50
|
-
components; agents may apply them to a target when useful.
|
|
51
|
-
|
|
52
|
-
---
|
|
53
|
-
|
|
54
|
-
## ๐ Quick Start
|
|
55
|
-
|
|
56
|
-
Install globally, or run once with a Node package runner:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
npm install -g pentesting && pentesting # install
|
|
60
|
-
npx pentesting # or run once, no install
|
|
61
|
-
pnpm dlx pentesting
|
|
62
|
-
yarn dlx pentesting
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
Requires Node.js 18.18+. Use npm/npx/pnpm/yarn; Bun and Deno runners are not supported.
|
|
66
|
-
|
|
67
|
-
### Docker-only development builds
|
|
68
|
-
|
|
69
|
-
Repository builds and Rust tests must always use the resource-capped Docker
|
|
70
|
-
wrappers. Host Cargo compilation is fail-closed; free disk or RAM does not make
|
|
71
|
-
it an approved path.
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
scripts/dbuild.sh check --workspace --all-targets
|
|
75
|
-
scripts/dbuild.sh test -p builder_domain
|
|
76
|
-
scripts/dverify.sh focused
|
|
77
|
-
scripts/dverify.sh full
|
|
78
|
-
scripts/dbuild-image.sh validation # once per fresh Docker cache
|
|
79
|
-
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dbuild.ps1 test -p builder_domain # Windows
|
|
80
|
-
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/nverify.ps1 # Windows npm verify
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
The wrappers cap memory, CPU, PIDs, jobs, test threads, and time; verify storage
|
|
84
|
-
before launch; serialize resource-intensive work; and leave a redacted resource
|
|
85
|
-
report. Automated CI/CD is disabled. Full policy: [Docker-only build safety](https://github.com/agnusdei1207/pentesting/blob/main/docs/BUILD_SAFETY.md).
|
|
12
|
+
---
|
|
86
13
|
|
|
87
|
-
|
|
88
|
-
that same AMD64 artifact for GitHub and Docker publication.
|
|
89
|
-
|
|
90
|
-
### ๐ณ Run with Docker
|
|
91
|
-
|
|
92
|
-
No local Rust toolchain needed:
|
|
93
|
-
|
|
94
|
-
Published images support `linux/amd64` only. Docker is the recommended runtime
|
|
95
|
-
on Windows and macOS; Apple Silicon Macs run the amd64 image through Docker
|
|
96
|
-
Desktop emulation. Native ARM64 images and binaries are not supported.
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
export OPENAI_API_KEY="sk-..." # provider API key or gateway token
|
|
100
|
-
export OPENAI_BASE_URL="https://api.openai.com/v1"
|
|
101
|
-
export OPENAI_MODEL="gpt-4o"
|
|
102
|
-
export OPENAI_MAX_TOKENS="4096"
|
|
103
|
-
|
|
104
|
-
docker run -it --rm \
|
|
105
|
-
-v "$(pwd):/workspace" \
|
|
106
|
-
-v pentesting-config:/root/.pentesting \
|
|
107
|
-
-w /workspace \
|
|
108
|
-
-e OPENAI_API_KEY \
|
|
109
|
-
-e OPENAI_BASE_URL \
|
|
110
|
-
-e OPENAI_MODEL \
|
|
111
|
-
-e OPENAI_MAX_TOKENS \
|
|
112
|
-
agnusdei1207/pentesting:latest
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
Provider environment variables are optional for startup. If they are omitted,
|
|
116
|
-
the interactive TUI still launches and lets you configure/login inside the
|
|
117
|
-
persistent `pentesting-config` volume.
|
|
118
|
-
|
|
119
|
-
Or via Docker Compose:
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
PENTESTING_PROJECT_DIR=/path/to/project \
|
|
123
|
-
OPENAI_API_KEY=sk-... \
|
|
124
|
-
OPENAI_BASE_URL=https://api.openai.com/v1 \
|
|
125
|
-
OPENAI_MODEL=gpt-4o \
|
|
126
|
-
OPENAI_MAX_TOKENS=4096 \
|
|
127
|
-
docker compose run --rm pentesting
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
### Common commands
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
pentesting # Interactive TUI
|
|
134
|
-
pentesting --prompt "Enumerate the target and summarize next actions."
|
|
135
|
-
pentesting shell-listener --bind 127.0.0.1 --port 4444 # Authorized reverse-shell listener
|
|
136
|
-
pentesting --version
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
Use `shell-listener` in authorized CTF/lab work to accept callbacks, tag sessions, run sentinel-tracked commands, verify PTY upgrades, and retain transcripts/evidence.
|
|
140
|
-
|
|
141
|
-
Short version: the agent can catch a dumb reverse shell, upgrade it to a verified PTY, pivot to a second callback, and reclaim both sessions cleanly with `close` / `revoke` / `gc`.
|
|
142
|
-
|
|
143
|
-
### Interactive commands
|
|
14
|
+
## ๐ Quick Start
|
|
144
15
|
|
|
145
|
-
|
|
16
|
+
Install globally, or run once with a Node package runner (Node.js 18.18+):
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g pentesting && pentesting # install
|
|
20
|
+
npx pentesting # or run once, no install
|
|
21
|
+
pnpm dlx pentesting
|
|
22
|
+
yarn dlx pentesting
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### ๐ณ Run with Docker
|
|
26
|
+
|
|
27
|
+
No local toolchain needed. Published images are `linux/amd64` only.
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
export OPENAI_API_KEY="sk-..." # provider API key or gateway token
|
|
31
|
+
export OPENAI_BASE_URL="https://api.openai.com/v1"
|
|
32
|
+
export OPENAI_MODEL="gpt-4o"
|
|
33
|
+
export OPENAI_MAX_TOKENS="4096"
|
|
34
|
+
|
|
35
|
+
docker run -it --rm \
|
|
36
|
+
-v "$(pwd):/workspace" \
|
|
37
|
+
-v pentesting-config:/root/.pentesting \
|
|
38
|
+
-w /workspace \
|
|
39
|
+
-e OPENAI_API_KEY \
|
|
40
|
+
-e OPENAI_BASE_URL \
|
|
41
|
+
-e OPENAI_MODEL \
|
|
42
|
+
-e OPENAI_MAX_TOKENS \
|
|
43
|
+
agnusdei1207/pentesting:latest
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Provider variables are optional โ the TUI launches without them and lets you log in inside the persistent `pentesting-config` volume. The TUI pre-fills output max tokens from the model; `OPENAI_MAX_TOKENS` overrides it.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## โ
Capabilities
|
|
51
|
+
|
|
52
|
+
| Area | What it does |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| Model-driven loop | Streaming action/observation loop; a model Stop ends a turn, verified artifacts close a mission, and the full turn trajectory is persisted |
|
|
55
|
+
| Tool guardrails | Read-before-edit enforcement, repeat-call guard, policy-gated file/shell/network |
|
|
56
|
+
| Permissions | Allow / Deny / Confirm, with once/always decisions persisted |
|
|
57
|
+
| Context compaction | Automatic micro-pruning + model-triggered summarization |
|
|
58
|
+
| Interrupt & steering | Esc stops the current turn and auto loop; queued input uses revisioned FIFO amend/replace semantics |
|
|
59
|
+
| Reverse-shell control plane | Accept and track authorized callbacks, tag/probe sessions, verify PTY upgrades, keep transcript/evidence records |
|
|
60
|
+
| PTY session control | One actor owns each socket/PTY/pipe, command queue, transcript, and child lifecycle, with FD accounting and deterministic reclamation |
|
|
61
|
+
| Frontier-guided exploration | Persistent lead ledger with explicit dispatch; breadth defaults to one and is hard-capped at four |
|
|
62
|
+
| Subagents | Explicit delegation to built-in specialists (`crypto`, `rev`, `pwn`); one selected agent can run up to four tasks concurrently |
|
|
63
|
+
| MCP & skills | Dynamic MCP tool discovery, layered markdown skills |
|
|
64
|
+
| Memory | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## โจ๏ธ Interactive commands
|
|
69
|
+
|
|
70
|
+
Sessions start with auto mode off. Esc stops both the current turn and autonomous continuation. Queued input replays in FIFO order.
|
|
146
71
|
|
|
147
72
|
| Command | Purpose |
|
|
148
73
|
| --- | --- |
|
|
@@ -156,109 +81,23 @@ Sessions start with auto mode off. Esc stops both the current turn and autonomou
|
|
|
156
81
|
| `/config` ยท `/tools` ยท `/skill` | Configure the runtime and inspect capabilities |
|
|
157
82
|
| `/workflow report` | Export the active run as Markdown |
|
|
158
83
|
| `/update` ยท `/exit` | Update the native release or quit |
|
|
159
|
-
|
|
160
|
-
On native Windows Git Bash, the repository smoke path builds the capped Docker
|
|
161
|
-
image and then opens this interactive TUI without WSL:
|
|
162
|
-
|
|
163
|
-
```bash
|
|
164
|
-
npm run check
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
### ๐ Reverse-shell & PTY sessions
|
|
168
|
-
|
|
169
|
-
Catch and manage authorized shell callbacks: one listener, many targets, audited cleanup.
|
|
170
|
-
|
|
171
|
-
```bash
|
|
172
|
-
pentesting shell-listener --port 4444 # 1. Catch callbacks (tracks many at once)
|
|
173
|
-
pentesting shell-session list # 2. See every live session + FD ownership
|
|
174
|
-
pentesting shell-session run -- id # 3. Run sentinel-bounded commands, capture output
|
|
175
|
-
pentesting shell-session upgrade --technique auto # 4. Recon, select, retry, and verify a real PTY
|
|
176
|
-
pentesting shell-session revoke --session 1 # 5. Hard-close: reclaim FDs + archive evidence
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
- **Track** โ each callback is accepted, numbered, and tagged; one session actor exclusively owns its live descriptors, transcript, and child lifecycle. `list` / `info` / `fdstat` / `lifecycle` show state and byte counts without cloned reader/writer descriptors.
|
|
180
|
-
- **Drive** โ `run` wraps commands in a sentinel to capture exactly their output; `send` / `raw` / `signal` / `resize` give interactive control.
|
|
181
|
-
- **Upgrade** โ `upgrade --technique auto` explicitly runs a bounded `recon โ select โ helper โ probe` controller, choosing an allowlisted shell and retrying only evidence-backed failures across `python3`, `python`, `python2`, `script`, and `expect`. Omission is still rejected: use a concrete technique for one exact CLI attempt; unusual custom `text` commands are available through the `session_control`/JSONL API. CLI `pty-upgrade` sends one concrete catalog helper and never starts adaptive fallback.
|
|
182
|
-
- **Record** โ per-session raw log, full-duplex transcript, command ledger, replay, and evidence manifest โ with secret redaction for registered values.
|
|
183
|
-
- **Reclaim** โ `close` (graceful) and `revoke` (hard) release file descriptors immediately and archive the session; `gc` prunes closed sessions. Reclamation is tracked end-to-end, so FDs never leak.
|
|
184
|
-
- **Guard** โ the JSONL control plane is a workspace-internal Unix socket only (absolute paths, symlink escapes, and non-socket files are rejected). Every request carries a protocol version and a correlating `request_id`, is bounded to 1 MiB in / 4 MiB out, and `timeout_ms` is capped at 5 minutes and rejected before any bytes reach the session. A small fixed worker pool multiplexes the socket so a long adaptive `upgrade` never blocks `health` / `observe` / `close`, and injected secrets are redacted from responses and sensitive audit records. `probe` / recon fields are the target's own self-report, not a security attestation.
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## โ๏ธ Configuration
|
|
189
|
-
|
|
190
|
-
Pentesting uses local storage by default. For normal use, configure only the model endpoint:
|
|
191
|
-
|
|
192
|
-
### Example `.env` / shell setup
|
|
193
|
-
|
|
194
|
-
```bash
|
|
195
|
-
# OpenAI-compatible provider or gateway
|
|
196
|
-
export OPENAI_API_KEY="sk-..."
|
|
197
|
-
export OPENAI_BASE_URL="https://api.openai.com/v1"
|
|
198
|
-
export OPENAI_MODEL="gpt-4o"
|
|
199
|
-
export OPENAI_MAX_TOKENS="4096"
|
|
200
|
-
|
|
201
|
-
# Runtime overrides (optional)
|
|
202
|
-
export PENTESTING_CONFIG="$HOME/.config/pentesting" # move the global config dir
|
|
203
|
-
export PENTESTING_SKIP_DOWNLOAD=1 # skip postinstall binary download (CI)
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
The TUI pre-fills output max tokens from known model names/provider metadata. `OPENAI_MAX_TOKENS` and the TUI field are explicit overrides for custom/self-hosted models.
|
|
207
|
-
|
|
208
|
-
### Frontier-guided CTF exploration
|
|
209
84
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
Those variables only pre-fill provider settings. Leaving them unset must not
|
|
230
|
-
block the container from launching the TUI; configure the provider interactively
|
|
231
|
-
inside the container instead.
|
|
232
|
-
|
|
233
|
-
> **Note:** The command you run is always **`pentesting`**. The internal engine is **`builder`** โ `pentesting` downloads and runs it under the hood; the engine name never surfaces in normal use.
|
|
234
|
-
|
|
235
|
-
---
|
|
236
|
-
|
|
237
|
-
## ๐ Documentation
|
|
238
|
-
|
|
239
|
-
- [`ARCHITECTURE.md`](ARCHITECTURE.md) โ Runtime flow, agent team, memory model, crate map, tool surface, and supported targets.
|
|
240
|
-
- [Documentation map](https://github.com/agnusdei1207/pentesting/blob/main/docs/README.md) โ Current authoritative documents versus historical plans and research notes.
|
|
241
|
-
- [Integrated runtime design](https://github.com/agnusdei1207/pentesting/blob/main/docs/BUILDER-CONSOLIDATED-DEEP-DIVE.md) โ Top-down explanation from the one-loop model to prompt, subagents, persistence, and PTY ownership.
|
|
242
|
-
- [Minimal Core implementation](https://github.com/agnusdei1207/pentesting/blob/main/docs/plans/2026/07/10/minimal-core/README.md) โ Implemented simplification record for the single turn/tool/security surface.
|
|
243
|
-
- [Next-generation clean-break convergence](https://github.com/agnusdei1207/pentesting/blob/main/docs/plans/2026/07/10/next-generation-convergence/README.md) โ Canonical contracts, deleted compatibility paths, and the phase-by-phase migration boundary.
|
|
244
|
-
- Internal layout: service traits are split under `builder_app/src/services/*`; OpenAI request conversion is isolated under `dto/openai/request/*`.
|
|
245
|
-
- [Public site](https://agnusdei1207.github.io/pentesting-public/) โ Landing page and public runtime entry surface.
|
|
246
|
-
- [`compose.yaml`](https://github.com/agnusdei1207/pentesting-public) โ Docker Compose facade for pentesting sessions.
|
|
247
|
-
|
|
248
|
-
---
|
|
249
|
-
|
|
250
|
-
## ๐น From the Developer
|
|
251
|
-
|
|
252
|
-
<div align="center">
|
|
253
|
-
<img src="https://github.com/user-attachments/assets/abe73474-f27b-4536-b358-fedef1e461f0" alt="Chopin Ballade No.4" width="600" />
|
|
254
|
-
</div>
|
|
255
|
-
|
|
256
|
-
<br/>
|
|
257
|
-
|
|
258
|
-
> "I believe playing the piano is also a form of orchestration."
|
|
259
|
-
>
|
|
260
|
-
> The harmony of polyphony โ multiple voices โ and homophony โ a single melodic line.
|
|
261
|
-
>
|
|
262
|
-
> Each voice sings its most beautiful song from its own place, yet when combined, they create one grand, beautiful melody. I believe this structure is no different from AI agents.
|
|
263
|
-
>
|
|
264
|
-
> โ *agnusdei1207*
|
|
85
|
+
> The command you run is always **`pentesting`**. The internal engine is **`builder`** โ `pentesting` runs it under the hood; the engine name never surfaces in normal use.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## ๐น From the Developer
|
|
90
|
+
|
|
91
|
+
<div align="center">
|
|
92
|
+
<img src="https://github.com/user-attachments/assets/abe73474-f27b-4536-b358-fedef1e461f0" alt="Chopin Ballade No.4" width="600" />
|
|
93
|
+
</div>
|
|
94
|
+
|
|
95
|
+
<br/>
|
|
96
|
+
|
|
97
|
+
> "I believe playing the piano is also a form of orchestration."
|
|
98
|
+
>
|
|
99
|
+
> The harmony of polyphony โ multiple voices โ and homophony โ a single melodic line.
|
|
100
|
+
>
|
|
101
|
+
> Each voice sings its most beautiful song from its own place, yet when combined, they create one grand, beautiful melody. I believe this structure is no different from AI agents.
|
|
102
|
+
>
|
|
103
|
+
> โ *agnusdei1207*
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pentesting",
|
|
3
|
-
"version": "0.100.
|
|
4
|
-
"builderReleaseTag": "v0.100.
|
|
3
|
+
"version": "0.100.14",
|
|
4
|
+
"builderReleaseTag": "v0.100.14",
|
|
5
5
|
"description": "pentesting โ coding agent runtime with audited reverse-shell capture, verified PTY session upgrades, pivot control, evidence transcripts, and safe session reclamation.",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "agnusdei1207",
|