Pentesting 🔓

✅ Capabilities

Agent-loop essentials plus a security-focused runtime layer.

| Area | What it does | | --- | --- | | 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 | | Tool guardrails | Read-before-edit enforcement, repeat-call guard, policy-gated file/shell/network | | Permissions | Allow / Deny / Confirm, with once/always decisions persisted | | Context compaction | Automatic micro-pruning + model-triggered summarization, pre/post hooks | | Interrupt & steering | ESC stops the current turn and auto loop; queued input uses revisioned FIFO amend/replace semantics and deterministic PTY Enter ownership | | 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 | | 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 | | Frontier-guided exploration | Persistent lead ledger with explicit dispatch; breadth defaults to one and is hard-capped at four | | Subagents | Explicit delegation to built-in specialists, including crypto, rev, and pwn; one selected agent can run up to four tasks concurrently | | MCP & skills | Dynamic MCP tool discovery, layered markdown skills | | Memory | Ebbinghaus-style decaying notes + hybrid lexical/semantic/graph retrieval |

Delegation is explicit. One task call selects one agent and may run its tasks concurrently; separate top-level calls are sequenced. explore dispatch instead uses builder clones with category overlays and waits for the batch. Both paths share permissions, budgets, lineage, and evidence checks.

Core algorithms

| Area | Implementation | Time / space | | --- | --- | --- | | Exploration | Score-ranked BFS/DFS guidance, parent backtracking, global reseeding; append-only leads folded into a HashMap | Snapshot/advice O(R + L log L) time, O(L) working and O(R) stored space | | 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) | | Runtime control | FIFO queues plus semaphore-bounded join_all fan-out | O(T) scheduling/result state, at most four active children per batch |

R is lead records, L live leads, M searchable text, N notes, Q query terms, D = 768, and V/E graph nodes/links. Memory decay is constant-time per note. Kruskal, Prim, and a generic divide-and-conquer engine are not runtime components; agents may apply them to a target when useful.

🚀 Quick Start

Install globally, or run once with a Node package runner:

npm install -g pentesting && pentesting   # install
npx pentesting                            # or run once, no install
pnpm dlx pentesting
yarn dlx pentesting

Requires Node.js 18.18+. Use npm/npx/pnpm/yarn; Bun and Deno runners are not supported.

Docker-only development builds

Repository builds and Rust tests must always use the resource-capped Docker wrappers. Host Cargo compilation is fail-closed; free disk or RAM does not make it an approved path.

scripts/dbuild.sh check --workspace --all-targets
scripts/dbuild.sh test -p builder_domain
scripts/dverify.sh focused
scripts/dverify.sh full
scripts/dbuild-image.sh validation                                                # once per fresh Docker cache
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/dbuild.ps1 test -p builder_domain  # Windows
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/nverify.ps1                  # Windows npm verify

The wrappers cap memory, CPU, PIDs, jobs, test threads, and time; verify storage before launch; serialize resource-intensive work; and leave a redacted resource report. Automated CI/CD is disabled. Full policy: Docker-only build safety.

Patch releases compile once, verify the binary version and SHA-256, and reuse that same AMD64 artifact for GitHub and Docker publication.

🐳 Run with Docker

No local Rust toolchain needed:

Published images support linux/amd64 only. Docker is the recommended runtime on Windows and macOS; Apple Silicon Macs run the amd64 image through Docker Desktop emulation. Native ARM64 images and binaries are not supported.

export OPENAI_API_KEY="sk-..."                 # provider API key or gateway token
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="gpt-4o"
export OPENAI_MAX_TOKENS="4096"

docker run -it --rm \
  -v "$(pwd):/workspace" \
  -v pentesting-config:/root/.pentesting \
  -w /workspace \
  -e OPENAI_API_KEY \
  -e OPENAI_BASE_URL \
  -e OPENAI_MODEL \
  -e OPENAI_MAX_TOKENS \
  agnusdei1207/pentesting:latest

Provider environment variables are optional for startup. If they are omitted, the interactive TUI still launches and lets you configure/login inside the persistent pentesting-config volume.

Or via Docker Compose:

PENTESTING_PROJECT_DIR=/path/to/project \
OPENAI_API_KEY=sk-... \
OPENAI_BASE_URL=https://api.openai.com/v1 \
OPENAI_MODEL=gpt-4o \
OPENAI_MAX_TOKENS=4096 \
docker compose run --rm pentesting

Common commands

pentesting                                                # Interactive TUI
pentesting --prompt "Enumerate the target and summarize next actions."
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 callbacks, tag sessions, run sentinel-tracked commands, verify PTY upgrades, and retain transcripts/evidence.

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.

Interactive commands

Sessions start with auto mode off. Esc stops both the current turn and autonomous continuation. Queued input is replayed in FIFO order.

| Command | Purpose | | --- | --- | | /help | List every command | | /model [query] | Choose a provider/model or custom endpoint | | /goal <objective> · /auto | Record a goal, then toggle autonomous continuation; Esc stops it | | /status · /usage | Inspect run state, gates, budgets, tokens, and requests | | /context · /memory | Inspect context-budget snapshots and stored memories | | /agent · /builder · /planner · /researcher | Select the active agent | | /new · /retry · /compact | Start fresh, retry the last turn, or compact context | | /config · /tools · /skill | Configure the runtime and inspect capabilities | | /workflow report | Export the active run as Markdown | | /update · /exit | Update the native release or quit |

On native Windows Git Bash, the repository smoke path builds the capped Docker image and then opens this interactive TUI without WSL:

npm run check

🔌 Reverse-shell & PTY sessions

Catch and manage authorized shell callbacks: one listener, many targets, audited cleanup.

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 upgrade --technique auto # 4. Recon, select, retry, and verify a real PTY
pentesting shell-session revoke --session 1       # 5. Hard-close: reclaim FDs + archive evidence

• 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.
• Drive — run wraps commands in a sentinel to capture exactly their output; send / raw / signal / resize give interactive control.
• 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.
• 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.
• 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.

⚙️ Configuration

Pentesting uses local storage by default. For normal use, configure only the model endpoint:

Example .env / shell setup

# OpenAI-compatible provider or gateway
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="gpt-4o"
export OPENAI_MAX_TOKENS="4096"

# Runtime overrides (optional)
export PENTESTING_CONFIG="$HOME/.config/pentesting"      # move the global config dir
export PENTESTING_SKIP_DOWNLOAD=1                        # skip postinstall binary download (CI)

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.

Frontier-guided CTF exploration

explore is always available. Use /config to set the engagement kind, flag verification, and frontier limits; settings persist in the installed runtime's user config. Breadth defaults to one and is capped at four. Leads are persistent, deduplicated, and dispatched explicitly.

With Docker, mount both your project and the persistent runtime config volume, then pass the same variables through with -e:

docker run -it --rm \
  -v "$(pwd):/workspace" \
  -v pentesting-config:/root/.pentesting \
  -w /workspace \
  -e OPENAI_API_KEY \
  -e OPENAI_BASE_URL \
  -e OPENAI_MODEL \
  -e OPENAI_MAX_TOKENS \
  agnusdei1207/pentesting:latest

Those variables only pre-fill provider settings. Leaving them unset must not block the container from launching the TUI; configure the provider interactively inside the container instead.

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.

📖 Documentation

• ARCHITECTURE.md — Runtime flow, agent team, memory model, crate map, tool surface, and supported targets.
• Documentation map — Current authoritative documents versus historical plans and research notes.
• Integrated runtime design — Top-down explanation from the one-loop model to prompt, subagents, persistence, and PTY ownership.
• Minimal Core implementation — Implemented simplification record for the single turn/tool/security surface.
• Next-generation clean-break convergence — Canonical contracts, deleted compatibility paths, and the phase-by-phase migration boundary.
• Internal layout: service traits are split under builder_app/src/services/*; OpenAI request conversion is isolated under dto/openai/request/*.
• Public site — Landing page and public runtime entry surface.
• compose.yaml — Docker Compose facade for pentesting sessions.

🎹 From the Developer

"I believe playing the piano is also a form of orchestration."

The harmony of polyphony — multiple voices — and homophony — a single melodic line.

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.

— agnusdei1207