DOCSv0.3.3

Install it, point it at a lab, talk to it.

Everything you need for a first engagement: install the Python package and the scanners, set a model key once, open the interactive session against a lab range, and the command and config reference. Start on a network you own.

  1. 1Installbrew install 0x45dd/tap/pwner
  2. 2Set a key oncepwner
  3. 3Open a sessionpwner chat
  4. 4Or no modelpwner scan --no-ai
The first four commands, in order.
INSTALLpython package

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, rich and textual. nmap is the only hard requirement; the other scanners are optional. ./scripts/install-deps.sh installs what your platform packages, and pwner doctor reports 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.py adds two more, and only kerbrute has no Kali package. pwner detects Kali as its own ecosystem rather than as Debian, so pwner doctor gives 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 with pwner setup.
  • PrivilegesHost discovery and OS detection use raw sockets. Run under sudo for 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.
QUICKSTARTa few minutes

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.

  1. Set your provider and key, once

    The first bare pwner opens 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.

    pwner
  2. Open 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
    sample data, fictional lab. Output is illustrative.
  3. 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. Esc or Ctrl-C cancels the current turn.

    focus on the web service, skip brute-force
  4. No model? Run the deterministic suite

    With --no-ai there 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 --json for 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.

SESSIONthe interactive TUI

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.

slash commandsin-session
/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. /target changes 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.

CLIcommands and flags

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.

CommandWhat it doesCommon flags
pwnerFirst 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 --pickChoose a provider and model from a list, then open the session. The plain pwner launch stays instant and uses what is saved. 
pwner setupRe-run the provider and API-key wizard. 
pwner doctorReport 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.

CONFIGconfig.json + flags

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-url on 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 set PWNER_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 like 22,80,443 or 1-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.

FAQhonest short answers

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.