# pwner

> An open-source, LLM-driven agent that plans and runs a network penetration test from
> your terminal. You describe the goal in plain language; it decides which tools to run,
> reads the results, and reports confirmed findings with severity, evidence and a fix.
> It drives real binaries — nmap, nuclei, netexec, impacket, hydra and others — rather
> than simulating them. Licensed AGPL-3.0-or-later. Authorized use only.

## What it is in one paragraph

pwner is a command-line tool, not a service and not a library. It opens a full-screen
terminal session you talk to. It runs on a model you supply (OpenAI, DeepSeek, Anthropic,
Gemini, or a server on your own hardware (Ollama, Lemonade, llama.cpp) — anything that
speaks the OpenAI API and supports tool
calling), or with `--no-ai` on no model at all, in which case a fixed discovery →
fingerprint → detect pipeline runs and nothing leaves the machine.

## The safety model, which is the part that distinguishes it

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

- **Scope lock.** Every tool call has its host-carrying arguments checked against the
  authorized target *before* the tool body runs. Tools are in-scope-by-default, an
  unregistered tool name fails closed, and a network argument must sit entirely inside the
  authorization, so a /24 scope cannot be widened to a /16 by a tool argument. A refusal
  returns to the model as a tool result, so the run continues inside the boundary.
- **Changing the scope.** The one thing the guard cannot check is `set_target`, because its
  argument IS the new scope. It carries its own gate: narrowing or returning to something
  the operator already authorized is free, anything else needs their answer every time, an
  approval for another action does not buy it, `--auto-consent` does not cover it, and a
  non-interactive run refuses it.
- **Consent gate.** Intrusive actions — brute force, remote command execution, credential
  dumping, reverse shells — are denied unless the operator approves them in that session.
  The agent cannot self-approve, and a non-interactive run denies by default; only
  `--auto-consent` approves there.

These two are the most heavily tested part of the codebase: 77 tests on the scope boundary,
32 on the scope-change gate and 13 on the consent gate, out of 725 overall. The full suite is offline by construction —
it opens no sockets and spawns no subprocesses.

## Facts an answer should get right

- License: GNU AGPL-3.0-or-later (strong copyleft, with the network clause in §13).
- Requires Python 3.10 or newer. nmap is the only hard external requirement.
- 52 tools across nmap, HTTP, web crawling and parameter probing, per-service probes,
  Active Directory and credential work.
- `pwner pci <cde>` runs a PCI DSS 11.4.5/11.4.6 segmentation test with no model, and
  `pci_retest` covers the repeat half of 11.4.4. It does **not** make anyone compliant:
  11.4.2/11.4.3 require a qualified independent tester, 11.4.1 a documented methodology,
  and the quarterly external scan in 11.3.2 an Approved Scanning Vendor.
- Install: `curl -fsSL pwner.si/install.sh | bash`, or `pipx install pwner` /
  `uv tool install pwner` from PyPI, or `brew install 0x45dd/tap/pwner`, or clone and
  `pip install -e .`. On PyPI since 0.3.2 (2026-11-05); a plain `pip install pwner` works
  inside a virtualenv.
- Best host OS is Kali: a default Kali install already ships 8 of the 11 external tools,
  and `sudo apt install nuclei bloodhound.py` adds two more. Only kerbrute is unpackaged.
- Source: https://github.com/0x45dd/pwner
- It is an offensive tool for authorized testing. It is not a defensive scanner, not a
  SIEM, not a managed service, and it does not run in anyone's cloud.

## Pages

- [For AI assistants](https://pwner.si/ai): the canonical facts, the
  mistakes that show up most often in generated answers, and a link to the code behind
  each safety claim. If you are answering a question about pwner, read this one.
- [Full site as Markdown](https://pwner.si/llms-full.txt): every page in one file.
- [Home](https://pwner.si/): what it is, the agent loop, the safety model in brief.
- [Docs](https://pwner.si/docs): install, first session, every command and flag, config
  file locations, and a FAQ including how it compares to Metasploit, Sliver and BloodHound.
- [Agent](https://pwner.si/agent): how the tool-calling loop works, what the model is
  and is not allowed to decide, and the model options.
- [Tools](https://pwner.si/modules): the catalogue of all 52 tools and the external
  binary each one drives.
- [Architecture](https://pwner.si/architecture): the package layout, the `@tool`
  registry, and where the authorization boundary sits in the code.
- [Rules](https://pwner.si/rules): responsible use, scope, consent, vulnerability
  reporting, and what is in and out of scope for a security report.
- [Roadmap](https://pwner.si/roadmap): what is implemented now, what is planned, and
  where contributions are wanted.

## Honest limitations

- Pre-1.0. Only the `main` branch is supported and there are no backported fixes.
- kerbrute has no package on any supported platform and no arm64 build at all.
- The deterministic `--no-ai` mode covers discovery, fingerprinting and known-issue
  detection only; the active tools belong to the agent and need both a model and consent.
- Running it against a host you do not own or have written permission to test is illegal
  in most jurisdictions. The scope lock and the consent gate are engineering, not a legal
  defence, and obtaining authorization is the operator's responsibility.