Pentesting 🔓

Pentesting is a local-first Rust coding agent CLI for authorized security work, with audited reverse-shell and PTY session control: catch callbacks, verify upgrades, pivot across sessions, and reclaim them cleanly.

The runtime—not the model—owns routing, tool sandboxing, verification, completion adjudication, and PTY/session lifecycle management. PTYs are first-class runtime objects: upgrade state, resize authority, transcript capture, file-descriptor ownership, and close/revoke/gc reclamation are all tracked explicitly.

pentesting

Security-Focused Agent Runtime

✅ Capabilities

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

🚀 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.

🐳 Run with Docker

No local Rust toolchain needed:

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.

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: 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 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

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

The global frontier engine default stays off, but CTF-shaped engagement config auto-applies the CTF runtime profile: ctf-competition autonomy, runtime exploration, autonomous continuation, and a completion gate that requires verified flag_check evidence. A ready-to-copy profile lives at docs/config/ctf.toml:

[engagement]
kind = "ctf"
flag_format = "flag\\{[^}]+\\}"
require_flag_evidence = true

[exploration]
enabled = true
max_frontier_nodes = 256
max_breadth = 4

With the profile active, the runtime stores explore leads as EvidenceKind::Lead events, carries prior-run frontier/findings/verified flags forward, deduplicates leads, auto-pivots dead probes, enforces graph/cap limits, and injects a breadth/depth recommendation into mission control. The model still drives the work through explore and task; heavy independent leads such as crypto/rev/pwn ride the same parallel delegation batch rather than a detached background scheduler. Operators can inspect the current graph with /frontier, and the status row shows compact frontier progress during dispatch.

Malformed tool-call output is fail-loud: unparsed tool-shaped markup is retried instead of accepted as a final answer, the TUI suppresses raw control markup, and large no-newline streams are bounded so rendering cannot hang behind usage-only progress ticks.

The shipped contract is covered by cargo test -p builder_app orch_spec::exploration_e2e: it verifies the flag-off regression path plus breadth enumeration, depth descent, sibling breadth, dead-probe pivot, global reseed, seed digest, broad-clone overlay, and child result promotion.

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.
• 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