Autonomous Pentest Framework — by Avi Twil

ATPTmaster

A modular, autonomous penetration-testing framework for Kali Linux. Drive it from the atpt command line, a web console, or a desktop window.

Set your scope, connect an LLM, and press Run. Findings and an attack-direction tree fill in as it works, and you download a PTES-compliant Markdown report at the end.

⚠️ Authorized testing only. Test systems you have permission to test. Every intrusive step is checked against your engagement scope, and in semi mode it pauses for your approval.

---

Contents

• Features
• Quick start
• Install
• Command line
• Launch the app
• Using the console — a TryHackMe box, end to end
• The ☰ menu
• The Director — the default engine
• Findings — clickable detail + screenshots
• PTES report — LLM-authored narrative, deterministic fallback
• Strategy Toolbox — the agent learns from its wins
• Under the hood
• Changelog
• License

---

Features

Command line or UI	atpt init / plan / run / status in a terminal, a browser console (atpt --u), or a native desktop app (atpt --app).
Zero-dependency core	Pure Python stdlib. The desktop window adds one optional package and falls back gracefully to a browser window without it.
Bring your own LLM	A hosted API key, an existing CLI login, or a local Ollama. Each operator uses their own keys; nothing proprietary is bundled.
An LLM Director by default	The model drives the scan/exploit loop one command at a time, writes up each finding in full, and learns reusable skills from its wins. The classic fixed pipeline is one click away.
Always scope-locked	A deterministic scope wall gates every intrusive command, in every mode.
PTES report out of the box	An LLM-authored narrative when a model is configured, a deterministic template when one isn't.

Quick start

# 1. Install (latest official release)
curl -fsSL https://raw.githubusercontent.com/avitwil/ATPTmasterv2/main/bootstrap.sh | bash

# 2. Launch
atpt --app     # native desktop window
atpt --u       # or open the console in your browser → http://127.0.0.1:8787

Then set your scope, add an LLM, pick a mode, and press Run. The console walkthrough is below. For a terminal lab that does not send packets, see Command line.

Install

Requires Python ≥ 3.10 — stdlib only. The one-liner installs the latest official release (stable vX.Y.Z tags only; betas are skipped):

curl -fsSL https://raw.githubusercontent.com/avitwil/ATPTmasterv2/main/bootstrap.sh | bash

Or clone it yourself (add --branch <vX.Y.Z> to pin a release):

git clone https://github.com/avitwil/ATPTmasterv2.git atpt && cd atpt && ./install.sh

The installer puts an atpt launcher on your PATH and adds an ATPTmaster desktop icon to your app grid.

• Optional scanners — add them any time with ./install.sh --with-tools.
• Updating is one click — ☰ → App settings → Update installs the latest stable release and keeps all your data (engagements, reports, learned skills). Beta / pre-release tags are never auto-installed.

Command line

After ./install.sh, the commands below are atpt .... From a source checkout they are the same with python3 -m atpt ....

These examples use a lab scope only: 203.0.113.10 (an RFC 5737 documentation address, not a host you can reach) and app.acme.example (a reserved .example name). --dry-run prints the plan and does not start scanners.

Help and version

atpt --help
atpt --version

--version prints atpt 2.1.0. --help lists init, modules, plan, run, status, approve, serve, and desktop.

Modules

atpt modules

Modules run in phase order: recon collects assets, map turns them into candidate findings, exploit is intrusive, validate checks findings, and report writes the PTES Markdown. In semi mode an INTRUSIVE module waits until you approve it.

Initialize a lab engagement

Save this as lab-scope.json:

{
  "engagement": "ACME-2026-Q3",
  "in_scope_domains": ["app.acme.example"],
  "in_scope_cidrs": ["203.0.113.10/32"],
  "out_of_scope": ["blog.acme.example"],
  "max_rate": 50,
  "notes": "Lab walkthrough only. RFC 5737 and the .example domain."
}

atpt init --scope lab-scope.json --engagement ACME-2026-Q3 --name "Acme lab" --mode semi
atpt plan --engagement ACME-2026-Q3

init creates the engagement. plan lists what can run next — here, five recon modules. agent_offensive is present and stays idle until you turn that engine on.

The checkout also includes recon/scope.example.json (203.0.113.0/24 and example.com) for the same kind of documentation engagement.

Dry-run, then status

atpt run --engagement ACME-2026-Q3 --dry-run
atpt status --engagement ACME-2026-Q3

You should see executed=[...], then assets=0 and findings=0. The newest event is a dry_run line: recon would call recon_runner.sh with --target app.acme.example and --target 203.0.113.10/32. No packet is sent.

How a run works

1. Scope is the allow-list. Hosts that are not in the scope file are refused before a scanner starts. semi and full both keep that wall.
2. plan is the queue. A module runs only when its inputs exist: a target first, then assets, then findings.
3. run walks the queue. step runs one module and stops. semi runs the non-intrusive ones and pauses before an intrusive module, printing atpt approve <module> --engagement <id>. full continues, still inside scope.
4. The Director is optional. With an LLM configured it can pick the next in-scope command. With no model, the fixed pipeline and the PTES report still run.

Approve an intrusive module only for a target you are allowed to test. The walkthrough above stops at --dry-run.

Launch the app

atpt --app     # native desktop window (the ATPTmaster icon does the same)
atpt --u       # or open the console in your browser → http://127.0.0.1:8787

The desktop app starts the console on a private local port and opens it in its own window — no terminal, no browser tab. It stores engagements, uploads, and reports under a per-user data folder:

OS	Data home
Linux	~/.local/share/ATPTmaster
macOS	~/Library/Application Support/ATPTmaster

To build a double-click installable bundle (Linux binary / macOS .app), see packaging/README.md.

Either way you get the same console:

The layout: ☰ menu (top-left) holds all settings, the logo and Run sit top-right, and the body is chat + status on the left, findings + attack-direction tree on the right.

Using the console — a TryHackMe box, end to end

1. ☰ → Scope → Target & scope. Give the engagement an id and name, put the box IP in Target (IP or CIDR), and tick the domains in play (Infra for the IP, Web if there's a site). Each domain takes in-scope and out-of-scope lists, and the scope oracle enforces both before any intrusive tool touches a host.

   Pick the Engine for this engagement — Director (LLM drives it, default) or Classic pipeline (the original fixed scan chain).

   Rather than fill the fields yourself, you can describe your scope in plain language to the scope agent; it restates or completes it and writes it only after you approve. The deterministic scope wall and startup confirmation still gate every scan either way.

   

2. ☰ → Scope → CTF / engagement. Set the goals (injected into the LLM's prompts), pick your .ovpn with the file picker (no path typing), then Connect VPN (background) to bring the tunnel up. Optionally add an attack-box.

   

3. ☰ → AI settings. Add a provider (API key, subscription CLI, or Ollama). Then use ☰ → App settings → Model ladder to order the models to try, each with an effort level (fetched live in the Models panel).

   

4. ☰ → App settings → Mode, then press Run (top-right). It runs in the background — the button becomes ⏸ Pause / ⏹ Stop. Findings and the attack tree fill in on the right; grab the report from App settings → Report (customize per-finding notes and screenshots first).

While it runs:

Control	What it does
Run	Executes in the background.
⏸ Pause / ⏹ Stop	Halt gracefully at the next module boundary (a running scanner finishes first).
Intrusive steps	Still gate on approval in semi mode.

• Chat control — run / plan / status / approve <module> / report.
• Findings table — click a row for its full write-up (what it is, how it was proven, impact, remediation, confidence) plus any attached screenshots, alongside an attack-direction tree grouped by domain and ranked by severity.

The ☰ menu

Everything is configured in the menu — no JSON editing. Provider / model / user / sudo settings are global; scope, CTF, and report settings attach to the selected engagement.

Section	What's inside
User	Name (appears on the report), company, phone, email.
AI settings	API providers, subscription CLI, local LLM (Ollama), and live-fetched models.
Scope	Target & scope (domain-typed, with the scope agent) and CTF / engagement (VPN, goals, attack-box).
App settings	Mode, Appearance, Model ladder, Report, and Toolbox.

Full ☰ menu breakdown

• User — name (appears on the report), company, phone, email.
• AI settings
  • API providers — paste a key (stored redacted) or name an env var read at call time.
  • Subscription CLI — Claude / Gemini / Codex, or a custom one, with one-click auto-install.
  • Local LLM — Ollama.
  • Models — live-fetched per provider; a curated list for the subscription CLIs.
• Scope
  • Target & scope — domain-typed (Infra / Web / API / AI / Cloud / Mobile / Wireless), each with in/out-of-scope lists. Or chat with the scope agent, which restates or elicits a scope and writes it only after you approve.
  • CTF / engagement — VPN config, goals, attack-box.
• App settings
  • Mode — step / semi / full.
  • Appearance — light / dark / system, plus Allow sudo (password held in memory only).
  • Model ladder — one global ladder of ordered models, each with an effort level, plus optional per-role overrides (director / OSINT / active recon / skill / scope / map / exploit / report). Any configured provider can serve any role; nothing is pinned to a specific model.
  • Report — include/exclude findings, add notes and screenshots, then Download.
  • Toolbox — the offensive agent's learned skills; view service tags and what worked, or delete one.

The Director — the default engine

New engagements default to the Director: instead of a fixed scan chain, the LLM drives the engagement itself — proposing one command at a time, reading the output, and deciding what's next, adapting to what it finds. Switch to Classic pipeline on the Engine toggle (☰ → Scope → Target & scope, at creation) to fall back to the original fixed scan chain. Both engines share the same tool library and the same scope wall.

New in v2.1 — an opt-in parallel engine. Set config.offensive_agent.parallel = true and a coordinator runs a persistent enumeration agent alongside bounded parallel exploitation workers over a shared facts store. The sequential Director loop remains the default — leave the flag unset and there's no change in behavior. Design in docs/superpowers/specs/2026-09-19-parallel-director-and-privesc-efficiency-design.md.

Recon runs in two phases. A passive OSINT expert reasons only over context you provide for the engagement — for a TryHackMe/HackTheBox box that's the challenge-page text, since there's no public footprint to research — before active recon enumerates in-scope hosts. Paste that context in ☰ → Scope → CTF / engagement → OSINT context / challenge page; leave it empty and the OSINT phase stays a no-op.

Findings are authored, not just harvested. When the Director concludes something is a real issue, it writes a first-class finding — title, severity, what it is, how it was proven, impact, remediation, and confidence — instead of a bare "asset found". That write-up feeds both the findings detail view and the downloaded report. Automatic flag/asset harvesting stays on as a safety net alongside it.

It is supervised so it can never leave scope:

• Startup confirmation — before it acts, in every mode, it shows you the exact in-scope targets and waits for your OK, so a typo in the target can't turn into scanning the wrong host.
• Deterministic scope wall — every command it proposes is parsed for its target and must pass the scope oracle, in semi and full. full means no per-step human — never "no scope wall". An out-of-scope command is blocked, fed back as an observation, and the agent proposes a different in-scope action.
• Read-only by default — allowed tools default to enumeration (nmap, curl, gobuster, nuclei, …); exploit tools (sqlmap, hydra, …) are opt-in per engagement. Write/egress flags are denied regardless.
• Bounded + stoppable — a step budget limits the run; Stop halts it and disconnects the VPN.

Discovered services and issues flow into the same map → validate → PTES report pipeline, and every win is distilled into a reusable skill (see the Strategy Toolbox). Full design in docs/superpowers/specs/2026-09-18-llm-driven-offensive-agent-design.md and docs/superpowers/specs/2026-09-19-llm-director-and-rich-findings-design.md.

Findings — clickable detail + screenshots

Every row in the findings table opens a detail panel with that finding's full write-up — description, how it was proven, impact, remediation, confidence, severity, status, OWASP/CVSS — plus an "Add screenshot" control.

Screenshots are operator-attached (there's no auto-capture of target pages). The in-console panel lists the attached file(s) — inline image display over http://127.0.0.1 is a known limitation — while the same screenshots render inline in the downloaded PTES report, since both draw from the one shared screenshot slot in App settings → Report.

PTES report — LLM-authored narrative, deterministic fallback

The downloaded report's Executive Summary and Methodology are written by an LLM from the engagement's real run transcript — a narrative of what was actually done on this target, not boilerplate. Each finding's description, reproduction, impact, and remediation come straight from the Director's write-up.

With no model configured, or if the ladder is exhausted, the report falls back to the original deterministic template. A PTES report is produced either way.

Strategy Toolbox — the agent learns from its wins

The offensive agent keeps a toolbox of skills. When a run succeeds — it captures a flag or confirms a finding — the winning steps are distilled into a reusable skill: a short, tool-generic recipe tagged with the goal and the services it applies to. On a later target the agent searches the toolbox and injects the best-matching skills into its prompt as a learned playbook, reaching for a proven technique instead of rediscovering it.

• Where they live — one JSON file per skill under your data home. In the desktop app that's ~/.local/share/ATPTmaster/toolbox/*.json; on a source checkout (e.g. atpt --u / serve, including the install.sh path, which pins ATPT_HOME to the checkout) it's <project home>/toolbox/. Files are hand-editable and portable — share a skill by dropping its file in, and the agent indexes it on the next run.
• Operator-visible — ☰ → App settings → Toolbox lists every skill with its service tags and what worked, each with a Delete control. A skill records its name, applies_to (goal / service tags), steps (argv templated with placeholders like {TARGET}), a one-line success_note, and its provenance.
• Suggestions, never authority — a skill only suggests commands. Every command the agent runs, learned or not, still passes the deterministic scope wall and the tool allowlist at execution time. A shared or hand-edited skill can never widen your scope or unlock a new tool; at worst a bad suggestion is blocked.

Nothing to configure: the toolbox fills itself as you run the agent, and grows more useful the more engagements you run.

Under the hood

The engine, module contract, the 11 shipped capability modules (recon → map → exploit → validate → report), the scope oracle, and the LLM provider ladder are documented in docs/CORE.md. Design specs and implementation plans live under docs/superpowers/.

🔒 The console binds to 127.0.0.1 and has no authentication — it's an operator tool. Don't expose it.

Changelog

Newest first.

v2.1.0 — Parallel Director Engine · 2026-09-20

Reasoning runs in parallel; command execution stays serial behind the scope wall.

• Opt-in parallel engine (config.offensive_agent.parallel = true): a coordinator runs a persistent enumeration agent alongside bounded parallel exploitation workers over a thread-safe shared facts store, grounded by a fast deterministic seed scan.
• Reasoning-ladder resilience — transient errors (timeouts, network blips, HTTP 429/5xx) are retried with backoff; model refusals are never retried and simply advance the ladder.
• Thread-safe event store so the engine's worker/enumerator threads can record events and findings safely.
• Per-worker reverse-shell footholds — each exploitation worker holds its own session (no shared-shell contention).
• Engagement-configurable flag format, sourced from a Toolbox skill.
• Per-role model tiering.
• The sequential Director loop remains the default — leave the flag unset and behavior is unchanged.

v2.0.0 — The LLM Director · 2026-09-19

The LLM drives the loop and authors the findings.

• The Director is the default engine — the LLM drives the scan/exploit loop one command at a time, adapting to what it finds (Director / Classic-pipeline toggle at engagement creation).
• Authored findings — the agent writes first-class findings (what it is, how it was proven, impact, remediation, confidence), shown in a clickable detail panel with operator-attached screenshots.
• LLM-authored PTES report — the Executive Summary and Methodology are narrated from the engagement's real run transcript, with a deterministic template fallback when no model is configured.
• Two-phase recon — a passive OSINT phase (reasons over the context you provide) runs before active recon.
• Conversational scope agent — define or confirm scope in plain language; the deterministic scope wall is unchanged.
• Per-role model ladders — a global model ladder plus optional per-role overrides.

v1.0.0 — Initial release · 2026-09-19

The framework foundation.

• The classic scan → map → exploit → validate → report pipeline, driven from a web console or a native desktop app.
• A deterministic scope oracle gating every intrusive command, an LLM provider ladder (subscription CLI / hosted API / local Ollama), the Strategy Toolbox of learned skills, a one-click, data-safe self-updater, and a PTES-compliant Markdown report.

License

Licensed under the Apache License 2.0 — see LICENSE. © 2026 Avi Twil. Bundled third-party tools under tools/ retain their own upstream licenses.