Install the package, then the scanners.
pwner is a Python CLI. Install the package, then the scanners it drives. nmap is the only hard requirement; everything else is optional and only matters when the tools that need it are used. Nothing phones home, and nothing leaves your machine until you point it at a model.
curl -fsSL pwner.si/install.sh | bash
The installer is the shortest route: one virtualenv under ~/.local/share/pwner, pwner on your PATH, nothing done to your system Python. It takes --with-tools, --no-path and --uninstall; read it at pwner.si/install.sh before you pipe it anywhere. The other routes are PyPI (pipx install pwner or uv tool install pwner, both isolated and both putting pwner on your PATH; a bare pip install only inside a virtualenv), the Homebrew tap, a clone, and the Dockerfile in the repository. nmap and the other scanners are separate system binaries.
- RequirementsPython 3.10+. Pip pulls
httpx,dnspython,richandtextual. nmap is the only hard requirement; the other scanners are optional../scripts/install-deps.shinstalls what your platform packages, andpwner doctorreports what is present, what is missing and how to get it. - Run it on KaliIf you get to choose the machine, choose Kali. A default install already ships 8 of the 11 external tools pwner drives — nmap, hydra, netexec, impacket, certipy, searchsploit, hashcat and snmpwalk.
sudo apt install nuclei bloodhound.pyadds two more, and only kerbrute has no Kali package. pwner detects Kali as its own ecosystem rather than as Debian, sopwner doctorgives you apt commands instead of the source builds a plain Debian box needs. The Dockerfile in the repository is built on Kali for the same reason. - First runType
pwner. A one-time wizard asks for your provider and key, saves them to~/.config/pwner/config.json, and opens the session. Re-run it any time withpwner setup. - PrivilegesHost discovery and OS detection use raw sockets. Run under
sudofor ICMP and ARP sweeps, which find more live hosts on a LAN. Unprivileged still works with TCP-SYN probes. - Network useNone at install beyond the download. No telemetry, no update pings. Nothing is sent to a model until you configure one.
From install to your first session.
Four steps against a lab range. Every address below is fictional. Swap in a network you own or have written permission to test.
Set your provider and key, once
The first bare
pwneropens a one-time wizard: pick a provider (openai, deepseek, anthropic, gemini, ollama or lemonade), paste a key, and it saves them to~/.config/pwner/config.json. Leave the key blank to run with no model at all.pwnerOpen a session on the lab range
Later runs skip the wizard and drop you into the full-screen session. Name a target up front, or set it in-session with
/target. Then just tell the agent what to do, in plain language.pwner chat 10.0.0.0/24~/engagements/acme-demosample session, fictional lab❯ find the live hosts, then the web box thinking… I'll sweep the /24, then fingerprint whatever answers. observe 2 hosts up (scope-locked sweep) scan 10.0.0.5 open 22, 80 detect 10.0.0.5:80 http nginx 1.18 (dated) finding [HIGH] exposed admin panel @ 10.0.0.5:80 ❯sample data, fictional lab. Output is illustrative.Steer it, approve or deny
Type while it works and your line steers the next step. When it wants to do something intrusive, like a brute-force, it pauses with
[y/N]and waits for you.EscorCtrl-Ccancels the current turn.focus on the web service, skip brute-forceNo model? Run the deterministic suite
With
--no-aithere is no LLM at all: discovery, port scan, service detection, vuln scripts and OS fingerprint run end to end, and findings print the same way. Add--jsonfor machine output.pwner scan 10.0.0.5 --no-ai
Want the agent to choose steps for you? See how the agent loop works and the consent gates before you raise autonomy with --auto-consent.
A full-screen session you talk to.
pwner and pwner chat open a full-screen terminal UI: a fixed input box at the bottom, a scrolling log above it, and a live status while the agent works. It is conversational, it remembers the whole session, and the target you name is the scope, enforced on every tool.
/scan [target] # deterministic suite, no model /target <t> # set or replace the authorized target /model [n|name] # list the models this provider serves, or switch /provider [name] # list providers, or switch to one /findings # findings so far, by severity /topology # the live network map /consent on|off # auto-approve intrusive actions /stop # cancel the running turn (Esc / Ctrl-C) /clear # reset the chat, keep target + findings /dump [path] # save the transcript (owner-only file) /doctor # external tool status /help /exit # help, and leave
talk to itType in plain language. It answers questions and only scans when you ask.steer liveType while it works and your line is injected as steering for the next step.consent inlineIntrusive actions pause with[y/N]. Answer right in the box, or pre-approve with--auto-consent.scope is the targetEvery host-targeting tool refuses an address outside the target you named./targetchanges it.
The consent model resolves in one order: --auto-consent approves automatically; an approval you already gave in this session approves too; an interactive terminal (-i) prompts y/N; a piped or scripted run auto-denies. Approval is session-wide, not per action — the first y covers every later intrusive action until you run /consent off, which retracts it. See the rules.
Command reference.
Run pwner <target> and it is treated as pwner scan <target>. The agentic commands need a model; --no-ai and the standalone scans do not.
| Command | What it does | Common flags |
|---|---|---|
| pwner | First run opens the setup wizard, then the interactive session. Later runs go straight into the session. | |
| pwner chat [target] | Open the interactive agent session, optionally on a target. Set or change it with /target. | --provider, --auto-consent, --instructions |
| pwner scan <target> | Run the agent, or the deterministic suite, against a host, CIDR or domain and print findings. | --no-ai, --ports, --max-steps, --concurrency |
| pwner ports <target> | Quick port scan only, no agent. | --ports |
| pwner vuln <target> | Vulnerability-script scan only, no agent. | --ports |
| pwner dns <domain> | DNS enumeration only. | --json |
| pwner pci <cde> | PCI DSS 11.4.5/11.4.6 segmentation test, no agent and no model. Run it from an out-of-scope segment: it tries to reach the CDE and reports whether the boundary held. Exits 0 isolated, 2 not isolated, 3 inconclusive. | --ports, --timeout, --json |
| pwner --pick | Choose a provider and model from a list, then open the session. The plain pwner launch stays instant and uses what is saved. | |
| pwner setup | Re-run the provider and API-key wizard. | |
| pwner doctor | Report which external tools are installed, what each one enables, and the install command for your platform. Exits non-zero only when nmap is missing. | --json |
Shared flags: --provider, --model, --api-key, --base-url, --ports, --no-ai, --max-steps, --concurrency, --range-cap, --timeout, --auto-consent, -i, --instructions, --nuclei-severity, --rate, --timing, --json.
Config reference.
Defaults are cautious. The provider and key live in ~/.config/pwner/config.json; everything else is a flag or an environment variable. Precedence: CLI flag, then env var, then saved config, then the provider preset.
- provider
- openai, deepseek, anthropic, gemini, ollama or lemonade. Sets the base URL and default model. A local endpoint (ollama, lemonade, or any
--base-urlon loopback or a private network) needs no API key. The model must support tool calling. - --provider · default: openai
- api_key
- Saved by the wizard. Or pass
--api-key, or setPWNER_API_KEY. Leave it empty to run the deterministic suite. - --api-key · env PWNER_API_KEY
- model / base_url
- Override the provider preset for a custom or local endpoint.
- --model / --base-url · env PWNER_MODEL / PWNER_BASE_URL
- --no-ai
- Skip the model and run the deterministic suite: discovery, port scan, service detection, vuln scripts, OS fingerprint.
- default: off
- --ports
top-1000(default),top-100,common,all, or a list like22,80,443or1-1024.- default: top-1000
- --max-steps
- Cap on the agent's tool-calling turns in one run.
- default: 0 (uncapped)
- --concurrency / --range-cap
- Parallel host scans for a range, and the largest CIDR it will expand before refusing.
- default: 20 / 4096
- --auto-consent / -i
- Approve intrusive actions automatically, or prompt
y/N. Authorized targets only. - default: prompt in a TTY, deny when piped
- --nuclei-severity
- Severity filter for the nuclei template run.
- default: low,medium,high,critical
Run pwner chat --help for the current flags; each provider preset's default model lives in pwner/llm.py.
Common questions.
Use and safety
What license is it?
GNU AGPL-3.0-or-later. It is strong copyleft: you can use, study, modify and redistribute it, but derivative works have to ship under the same license, and the network clause (§13) means that if you modify pwner and let others use it over a network, you owe them the modified source too. See the license section.
Is it safe to run?
Only with written authorization. Every tool is locked to the target you name, discovery and fingerprinting are read-only, and brute-force and anything intrusive are denied until you approve them. It is still a network testing tool, so try it on a lab range first.
Can the agent go out of scope?
Not through the model. Scope is checked in the tool layer, outside the model, on every host-targeting call, and any address outside your target is refused whatever the model or a prompt says. Pointing it at a network you do not own is still on you.
Does it need an LLM?
No. Bring a local or hosted model, or pass --no-ai to run the deterministic suite offline. Nothing is sent anywhere until you configure a model.
How it works
What makes it agentic?
pwner runs a tool-calling loop. The model reasons about what it sees, asks for a tool, reads the result and iterates, then reports the findings it confirms with severity, evidence and a fix. The tool layer decides whether each call is allowed. The agent page walks through it.
Which platforms are supported?
It is a Python 3.10+ package and runs on macOS and Linux, wherever Python and nmap run. There is no compiled binary. Kali is the best host: a default install already ships most of the external tools pwner drives, so there is almost nothing left to set up.
Compared with other tools
How is it different from Metasploit?
Metasploit is a large library of ready-made exploits you drive by hand. pwner is an agent: it reasons about a target, fingerprints it, detects known issues, and — with your consent — exploits them, runs commands, sprays credentials and dumps secrets, all scope-locked. It carries no exploit database of its own; it leans on nmap, nuclei, netexec, impacket and hydra and decides what to reach for.
How is it different from Sliver?
Sliver is a dedicated command-and-control framework for long-lived implants. pwner can catch a reverse shell (listener + shell_exec) and read blind-RCE output back over an exfil channel to prove impact during an engagement, but it ships no implant, no beaconing and no persistence — the post-exploitation is there to demonstrate access, not to maintain it.
How is it different from BloodHound?
BloodHound graphs Active Directory relationships into a database. pwner is not an AD grapher: it does its own network discovery and shows a live topology tree in the session, hosts to ports to services to findings. There is no graph database and no Neo4j export.