A High-Efficiency Penetration-Testing Agent
Designed to achieve strong results with low-cost models. Powered by Rust.
[](LICENSE)
[](https://www.npmjs.com/package/pentesting)
---
## ๐ Quick Start
Install globally, or run once with a Node package runner (Node.js 18.18+):
```bash
npm install -g pentesting && pentesting # install
npx pentesting # or run once, no install
pnpm dlx pentesting
yarn dlx pentesting
```
### ๐ณ Run with Docker
No local toolchain needed. Published images are `linux/amd64` only.
```bash
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 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.
---
## โ
Capabilities
| Area | What it does |
| --- | --- |
| Verified agent loop | Streams actions and observations; a model Stop ends only the turn, evidence-backed verification closes the mission, and the full trajectory is persisted |
| Unified tool boundary | Built-in, delegated, and MCP calls share schema validation, provenance, permissions, policy, and resource limits |
| Context economy | Automatic micro-pruning and model-triggered summaries preserve useful context for low-cost models |
| Deterministic steering | Active-turn submissions are retained for the next safe transcript boundary; Esc stops the current turn and auto loop while the visible inputs resume in FIFO order |
| Reverse-shell & PTY lifecycle | One control plane manages authorized callbacks and local PTY/pipe sessions, from tagging, probing, and verified upgrades to transcripts, evidence, FD accounting, and deterministic reclamation |
| Bounded battlefield | A persistent Lead ledger produces a compact on-demand attention brief and read-only `/status` view; dispatch stays explicit and is capped at four branches |
| Adversarial pathfinding | A localized AlphaGo-inspired minimax technique models an opponent's best defensive move and improves the ability to find viable bypass paths |
| Dynamic fan-out / fan-in | The model sizes each specialist batch to the task, runs up to four delegated branches concurrently, then returns their results to the parent with bounded depth and recorded lineage |
| Extensible skills & tools | Discovers MCP tools dynamically and layers Markdown skills onto the same guarded runtime surface |
| Forgetting-aware memory | Ebbinghaus-style decaying notes combine with lexical, semantic, and graph retrieval |
---
## ๐งญ Philosophy
| Principle | What it means here |
| --- | --- |
| Simplicity is best | Prefer the smallest design that preserves the capability, makes ownership clear, and remains easy to verify |
| If it cannot be measured, it cannot be improved | Instrument outcomes, compare them under repeatable conditions, and let evidence drive the next change |
| The best design blueprint is the human being | Better systems begin with better self-observation: understand how we perceive, decide, learn, and recover, then make those loops observable |
| The agent is the bottleneck | As AI models advance, the agent framework and the surrounding system must evolve with them |
---
## Capability record
| Date | Result | Test setup | Note |
| --- | --- | --- | --- |
| 2026-04 | Project work began | Initial implementation and baseline work | โ |
| 2026-07-15 | ~40% higher pentesting score | Pentesting (MiniMax M3) vs. Claude Code v2.1.210 (Sonnet 5); same prompts, easy-to-hard CTFs, 60 minutes each | Time-bound internal test; both agents continue to evolve |
---
## โจ๏ธ Slash commands
| Command | Purpose |
| --- | --- |
| `/help` | Show commands |
| `/model [query]` | Switch provider, model, or custom endpoint |
| `/goal