pentesting 0.92.8 → 0.100.0

package/ARCHITECTURE.md

@@ -28,7 +28,8 @@ stays intentionally short and usage-focused.
 - **Intelligent Queuing** — Queued inputs are deduplicated and prioritized live;
   obsolete tasks are preempted, not FIFO-replayed.
 - **Lab Session Multiplexing** — `shell-listener` runs multiple authorized TCP
-  sessions with per-session routing and PTY upgrades.
+  sessions with per-session routing, identity tags, verified PTY upgrade state,
+  transcripts, command ledgers, replay, and orphaned evidence recovery.
 - **Dynamic Agent Profiles** — No fixed persona: the runtime *derives* a profile
   per request from the prompt and can overlay a named autonomy profile, driving
   tool scope, phase, and memory weighting.
@@ -405,5 +406,18 @@ pentesting shell-listener --bind 127.0.0.1 --port 4444
 ```
 
 Manages multiple accepted TCP sessions with per-session routing, buffered
-output, raw byte logging, and PTY-upgrade helpers. Bound to loopback by default;
-`--allow-remote` is an explicit opt-in gate.
+output, raw byte logging, full-duplex transcripts, command history, attach /
+detach events, replay, and evidence manifests. `pty-upgrade` sends the helper
+only; `upgrade` runs the helper plus a probe and records `pty_state` as verified
+or failed. The upgrade helper is drawn from a named technique catalog
+(`python3`, `python`, `python2`, `script`, `expect`) selectable per request —
+there is no default, so the request is rejected unless the caller picks a
+technique or supplies a full custom command, forcing the agent to recon the
+target and match what it actually has instead of assuming one interpreter; a
+missing tool is recorded as `pty_state=failed` with reason `<technique> helper
+unavailable`. Raw logs and transcripts are capped per session and closed sessions
+are archived automatically so a noisy peer cannot grow memory or disk without
+bound. Secret redaction is applied before new raw/transcript/display records are
+written; it is not retroactive for output that arrived before the secret value
+was registered. Bound to loopback by default; `--allow-remote` is an explicit
+opt-in gate.

package/README.md

@@ -1,6 +1,6 @@
 # Pentesting 🔓
 
-> **Pentesting** is a local-first, zero-panic Rust coding agent CLI for authorized security assessments. The runtime—not the model—owns routing, tool sandboxing, verification, and completion adjudication.
+> **Pentesting** is a local-first, zero-panic Rust coding agent CLI for authorized security assessments and educational security research. The runtime—not the model—owns routing, tool sandboxing, verification, and completion adjudication.
 
 <div align="center">
   <img src="https://api.iconify.design/hugeicons:bash.svg" alt="pentesting bash icon" width="120" />
@@ -24,31 +24,44 @@ Agent-loop essentials at parity with leading coding agents, plus a security-focu
 | Permissions | Allow / Deny / Confirm, with once/always decisions persisted |
 | Context compaction | Automatic micro-pruning + model-triggered summarization, pre/post hooks |
 | Interrupt & steering | ESC to interrupt mid-turn, queue follow-ups while it works |
+| 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 |
 | Subagents | Parallel delegated tasks, budget-capped, role-specific personas |
 | MCP & skills | Dynamic MCP tool discovery, layered markdown skills |
 | Memory | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval |
 
-**Beyond the baseline:** evidence-gated completion adjudication (Complete / Replan / Blocked), full PTY session control, and CTF-grade verification tools (flag check, best-of-N verify, findings ledger).
+**Beyond the baseline:** evidence-gated completion adjudication (Complete / Replan / Blocked), a CTF-oriented reverse-shell/PTY control plane (multi-session tracking, helper-only `pty_upgrade` plus verified `upgrade`, transcript/history/replay, lifecycle/FD management), and CTF-grade verification tools (flag check, best-of-N verify, findings ledger).
 
 ---
 
 ## 🚀 Quick Start
 
+Install globally, or run without installing via your package manager of choice:
+
 ```bash
-npm install -g pentesting
-pentesting
+npm install -g pentesting && pentesting   # install
+npx pentesting                            # or run once, no install
+pnpm dlx pentesting
+yarn dlx pentesting
+bunx pentesting
+deno run npm:pentesting
 ```
 
-Or run it with Docker:
+### 🐳 Run with Docker
+
+No local Rust toolchain or native binary needed — the image ships the full
+runtime plus the offensive testing toolchain:
 
 ```bash
-docker run -it --rm -v "$(pwd):/workspace" -w /workspace agnusdei1207/pentesting:latest
+docker run -it --rm \
+  -v "$(pwd):/workspace" -w /workspace \
+  -e ANTHROPIC_API_KEY \
+  agnusdei1207/pentesting:latest
 ```
 
 Or via Docker Compose:
 
 ```bash
-PENTESTING_PROJECT_DIR=/path/to/project docker compose run pentesting
+PENTESTING_PROJECT_DIR=/path/to/project ANTHROPIC_API_KEY=sk-ant-... docker compose run pentesting
 ```
 
 ### Common commands
@@ -56,12 +69,34 @@ PENTESTING_PROJECT_DIR=/path/to/project docker compose run pentesting
 ```bash
 pentesting                                                # Interactive TUI
 pentesting --prompt "Enumerate the target and summarize next actions."
-pentesting shell-listener --bind 127.0.0.1 --port 4444   # Authorized lab listener
+pentesting shell-listener --bind 127.0.0.1 --port 4444   # Authorized reverse-shell listener
 pentesting --version
 ```
 
+Use `shell-listener` in authorized CTF/lab work to accept multiple callbacks, label/tag sessions, probe remote identity, run sentinel-tracked commands, verify dumb-shell PTY upgrades, attach/detach without closing, and retain raw logs, transcripts, command history, replay data, and evidence manifests.
+
+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`.
+
 Inside a session, `/help` lists every command and `/update` pulls the latest release for supported native targets.
 
+### 🔌 Reverse-shell & PTY sessions
+
+Catch and manage authorized shell callbacks like a session manager — **one listener, many targets, full audit trail, no leaked file descriptors.**
+
+```bash
+pentesting shell-listener --port 4444             # 1. Catch callbacks (tracks many at once)
+pentesting shell-session list                     # 2. See every live session + FD ownership
+pentesting shell-session run -- id                # 3. Run sentinel-bounded commands, capture output
+pentesting shell-session pty-upgrade              # 4. Inject the PTY helper; `upgrade` then verifies it
+pentesting shell-session revoke --session 1       # 5. Hard-close: reclaim FDs + archive evidence
+```
+
+- **Track** — each callback is accepted, numbered, and tagged; `list` / `info` / `fdstat` / `lifecycle` show live state, byte counts, and FD ownership.
+- **Drive** — `run` wraps commands in a sentinel to capture exactly their output; `send` / `raw` / `signal` / `resize` give interactive control.
+- **Upgrade** — `pty-upgrade` sends the built-in helper and `upgrade` verifies a real PTY before remote resize is allowed; the agent must pick the method with `--technique` (`python3`, `python`, `python2`, `script`, `expect` — no default) after reconning what the target actually has, or send a fully custom command instead.
+- **Record** — per-session raw log, full-duplex transcript, command ledger, replay, and evidence manifest — with secret redaction for registered values.
+- **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.
+
 ---
 
 ## ⚙️ Configuration
@@ -75,6 +110,30 @@ backend = "local"   # Local md/fs runtime state
 
 Environment variables use the `PENTESTING_` prefix (`__` for nested keys, e.g. `PENTESTING_SESSION__MODEL_ID=...`). Full variable list and the legacy `BUILDER_*` aliases are documented in [`ARCHITECTURE.md`](ARCHITECTURE.md#configuration).
 
+### Example `.env` / shell setup
+
+```bash
+# Model provider credentials — set whichever provider(s) you use
+export ANTHROPIC_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+export OPENROUTER_API_KEY="sk-or-..."
+
+# Runtime overrides (optional)
+export PENTESTING_SESSION__MODEL_ID="claude-sonnet-5"   # default model for new sessions
+export PENTESTING_CONFIG="$HOME/.config/pentesting"      # move the global config dir
+export PENTESTING_SKIP_DOWNLOAD=1                        # skip postinstall binary download (CI)
+```
+
+With Docker, pass the same variables through with `-e`:
+
+```bash
+docker run -it --rm \
+  -v "$(pwd):/workspace" -w /workspace \
+  -e ANTHROPIC_API_KEY \
+  -e PENTESTING_SESSION__MODEL_ID="claude-sonnet-5" \
+  agnusdei1207/pentesting:latest
+```
+
 > **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.
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pentesting",
-  "version": "0.92.8",
-  "builderReleaseTag": "v0.92.8",
+  "version": "0.100.0",
+  "builderReleaseTag": "v0.100.0",
   "description": "pentesting — security-focused agent runtime (internal engine: builder). Thin npm facade that downloads the managed Builder binary and forwards arguments.",
   "license": "MIT",
   "author": "agnusdei1207",
@@ -53,6 +53,7 @@
     "test": "node --test tests/*.test.mjs",
     "preflight:local": "bash scripts/preflight-local.sh",
     "verify": "npm run consistency && npm run test",
+    "check": "npm run verify",
     "pentesting:help": "bash scripts/pentesting-release-help.sh",
     "pentesting:status": "bash scripts/pentesting-release-status.sh",
     "pentesting:test": "npm run test",
@@ -70,7 +71,7 @@
     "public:sync": "bash scripts/sync-public-repo.sh",
     "public:mirror-release": "bash scripts/mirror-public-release.sh",
     "release:backfill": "bash scripts/backfill-release-local.sh",
-    "check": "sh -c 'npm run docker:build && docker run -it --rm -v builder-workspace:/workspace -e ANTHROPIC_BASE_URL -e ANTHROPIC_AUTH_TOKEN -e ANTHROPIC_MODEL -e ANTHROPIC_API_KEY -e MINIMAX_API_KEY -e OPENAI_API_KEY -e OPENAI_BASE_URL -e GEMINI_API_KEY -e DEEPSEEK_API_KEY agnusdei1207/pentesting:latest'",
+    "check:docker": "sh -c 'npm run docker:build && docker run -it --rm -v builder-workspace:/workspace -e ANTHROPIC_BASE_URL -e ANTHROPIC_AUTH_TOKEN -e ANTHROPIC_MODEL -e ANTHROPIC_API_KEY -e MINIMAX_API_KEY -e OPENAI_API_KEY -e OPENAI_BASE_URL -e GEMINI_API_KEY -e DEEPSEEK_API_KEY agnusdei1207/pentesting:latest'",
     "docker:build": "(docker image inspect agnusdei1207/pentesting-build-base:1.96 >/dev/null 2>&1 && docker image inspect agnusdei1207/pentesting-runtime-base:26.04 >/dev/null 2>&1 || npm run docker:base:build) && docker build --build-arg APP_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo dev) -t agnusdei1207/pentesting:latest .",
     "docker:base:build": "docker build -t agnusdei1207/pentesting-build-base:1.96 -f docker/build-base.Dockerfile . && docker build -t agnusdei1207/pentesting-runtime-base:26.04 -f docker/runtime-base.Dockerfile .",
     "release:patch": "./scripts/release-all.sh patch",