pwner

pwner is an LLM-driven agent that plans and runs a network penetration test from your terminal. It discovers hosts, fingerprints services, checks them against known issues, and — when the target warrants it and you approve — exploits them to prove impact. It drives real tools (nmap, nuclei, netexec, impacket, hydra and others) rather than simulating them, and it reports confirmed findings with severity, evidence and a fix.

It runs on your own model, or on no model at all.

• You talk to it. Not a flag soup: say "scan it, focus on the database" and it decides what to run, shows you its reasoning as it goes, and you can redirect it mid-run.
• Scope is enforced in code. Every tool call is checked against the target you named before it runs — not asked of the model in a prompt. See Safety model.
• Intrusive actions are denied by default. Brute-force, remote command execution, credential dumping and reverse shells need your explicit approval.
• Your model, your machine. OpenAI, Anthropic, Google, DeepSeek, or a server on your own hardware — Ollama, Lemonade, llama.cpp, anything OpenAI-compatible. A local endpoint needs no API key. Nothing is sent anywhere until you configure one.
• Works with no model. --no-ai runs the full discovery → fingerprint → detect pipeline deterministically, with no API key and nothing leaving the machine.
• 52 tools across nmap, HTTP, web crawling and parameter probing, per-service probes, Active Directory and credential work, each a thin wrapper over the standard binary rather than a reimplementation.

Safety model

Two mechanisms, both in the tool layer, both outside the model's reach. The model can ask for anything; it cannot widen its own authorization.

flowchart LR
    OP(["operator"]) -->|"plain language"| AG["agent loop"]
    AG -->|"tool call"| SG{"scope guard"}
    SG -->|"host outside<br>the target"| R1["refused"]
    SG -->|"in scope"| CG{"consent gate"}
    CG -->|"intrusive,<br>not approved"| R2["skipped"]
    CG -->|"approved, or<br>not intrusive"| RUN["runs against<br>the target"]
    classDef guard fill:#ffb000,stroke:#8a5f00,color:#140d00,stroke-width:2px
    classDef stop fill:none,stroke:#8b949e,stroke-dasharray:4 4
    class SG,CG guard
    class R1,R2 stop

A refusal is not an error that stops the run: it goes back to the model as a tool result, so the agent learns it overstepped and carries on inside the boundary.

Scope lock. build_dispatch wraps every tool so each host-carrying argument is checked against your target before the tool body runs. Tools are in-scope-by-default: one that forgets its own check is still guarded, and an unregistered tool name fails closed. A network argument has to sit entirely inside the authorization, so a /24 scope cannot be widened to a /16 by a tool argument.

Changing the scope. The one thing the guard cannot check is set_target, because its argument is the new scope, so there is nothing to check it against. It carries its own gate instead: narrowing, or returning to something you already authorized, is free, and moving anywhere else needs your answer every time. An earlier approval for some other action does not buy it, --auto-consent does not cover it, and a non-interactive run refuses it outright.

Consent gate. Anything active is denied unless you approve it in that session. The agent cannot self-approve — consent is resolved outside the model, and in a non-interactive run the answer is always no.

These two are the part of the codebase under the most test: 77 tests on the scope boundary in tests/test_scope.py and 13 on the consent gate in tests/test_consent.py, out of 725 overall. If you are going to read one thing before pointing this at a network, read those.

Intended use:

• Authorized penetration tests, with written permission and an agreed scope
• Bug-bounty work, inside the program's stated rules
• Your own lab, your own hardware, CTFs
• Security research on systems you own

Not this tool's purpose, and not defensible:

• Anything on a host you do not own and have no written permission to test
• "Just checking" a network you happen to be on
• Anything where you cannot name who authorized it

Install

Python 3.10+. nmap is the only hard requirement — everything else enables more tools and is optional.

curl -fsSL https://raw.githubusercontent.com/0x45dd/pwner/main/install.sh | bash

That builds an isolated virtualenv under ~/.local/share/pwner, leaves your system Python alone, and puts pwner on your PATH so it works from any directory. Add --with-tools to install nmap and the optional scanners too, and --uninstall to take it all back out. On macOS there is also a tap:

brew install 0x45dd/tap/pwner

That brings nmap with it. From source instead:

git clone https://github.com/0x45dd/pwner.git
cd pwner
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Then the external tools, and a check:

./scripts/install-deps.sh   # brew/apt/kali/pacman/dnf
pwner doctor               # what's missing

install-deps.sh installs only what is missing and skips anything your distro does not package instead of failing. pwner doctor reports every external tool, what each one enables, and the install command for the system you are on; it exits non-zero only when nmap is missing, so it works as a setup check in a script.

On Kali there is almost nothing to install. A default Kali image already ships 8 of the 11 external tools pwner drives — nmap, hydra, netexec, impacket, certipy, searchsploit, hashcat and snmpwalk. sudo apt install nuclei bloodhound.py adds two more, and only kerbrute is unpackaged. pwner detects Kali as its own ecosystem rather than as Debian, so pwner doctor hands you apt commands instead of the source builds a plain Debian box needs. If you are choosing where to run this, run it there.

uv venv && uv pip install -e .
pipx install -e .

The whole toolchain in one image, nothing installed on your host. The base is Kali, so every tool but kerbrute comes from apt:

docker build -t pwner .
docker run --rm -it --net=host \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  -v pwner-config:/root/.config/pwner \
  -v pwner-sessions:/root/.local/share/pwner \
  pwner

--net=host and the two capabilities are what let nmap do SYN scans and ICMP/ARP discovery; without them it quietly falls back to slower connect scans and finds fewer hosts. The volumes persist your key and your saved transcripts.

The image is ~2.7 GB and carries 10 of the 11 external tools plus nuclei's 14k templates, baked in so the first scan does not stall on a download. kerbrute is the one omission: it has no Kali package and no arm64 release. Built and run on arm64; the package set resolves on amd64 too.

First run

pwner

The first run asks for a provider and an API key once and saves them to ~/.config/pwner/config.json (owner-only). Every run after that drops you straight into a session. Change it later with pwner --pick for a provider/model menu, pwner setup for the full prompts, or /model and /provider from inside a running session.

pwner chat 10.0.0.5          # session, target set
pwner 10.0.0.0/24 --no-ai    # sweep, no model
pwner doctor                 # tool status
pwner --pick                 # choose a provider/model, then open a session

In a session you talk to the agent and steer it while it works; /help lists the commands, /findings and /topology show what it has built so far, and /dump writes the transcript to ~/.local/share/pwner/sessions/ (owner-only — it contains every credential the engagement turned up, in cleartext).

Your model

Point it at a provider and give it a key. Presets cover OpenAI, Anthropic, Google and DeepSeek; anything else that speaks the OpenAI API works via --base-url.

export PWNER_A