ARCHITECTUREone process, your machine

Small on purpose.

A handful of Python modules: a terminal UI you talk to, an agentic tool-calling loop on your own model, and a scope-and-consent layer that lives in the tool code, outside the model's reach. This page follows one request from your message to the target and back, then shows where each piece lives.

agent loop (your model)scope + consent, in codetools: nmap, nuclei, probesthe target you named asks onlyallow, deny or askactive steps gatedin scope only
One request, top to bottom.
DATA FLOWone request, end to end

Nothing reaches a target without passing the tool layer.

You talk to the Textual UI. The agent loop asks the model for the next tool call. Before any call runs, the tool code checks it against the scope lock and the consent gate, both outside the model, then shells out to nmap or nuclei on an in-scope target and feeds the result back into the next step.

pwner data flow You type into the Textual UI. The session passes your message to the agent loop running your model. The model asks for a tool call. The tool layer checks scope and consent, outside the model, and either refuses it or runs nmap or nuclei on an in-scope target. Results flow into findings and the live topology, and back into the next step. you ↔ TUIapp.py, Textual agent loopllm.py, your model scope + consenttools/core.py, outside model toolsnmap · nuclei · probes target 10.0.0.0/24in-scope, lab findings+ live topology refusedout of scope / denied results feed the next step (the loop) pwner data flow, stacked Top to bottom: the Textual UI, the agent loop on your model, the scope-and-consent layer outside the model which refuses out-of-scope or denied calls, the tools acting on the target, and the findings and topology that feed the next step. you ↔ TUIapp.py agent loopyour model scope + consentoutside the model refused toolsnmap · nuclei findings+ topology

Sample flow, fictional lab range. Select a step or let it cycle.

POLICY LAYERtools/core.py

The model asks. The tool code answers.

Scope is the target you name on the command line, a host or a CIDR, held in ScanContext. Every host-targeting tool calls in_scope() before it acts and refuses anything outside it. Intrusive calls pass through a consent check. The model never sees a handle to either, so a confused or manipulated model cannot widen its own reach.

Authorized testing only. Run it against systems you own or have written permission to test. Read the rules

tool callwhy it decidedverdict
service_detect 10.0.0.21inside target 10.0.0.0/24run
dns_enum corp.acme-demo.exampleresolves in scoperun
port_scan 203.0.113.50outside the targetrefuse
run_nmap --script bruteintrusive NSE categoryrefuse
hydra_brute 10.0.0.30:22consent-gated actionask

Illustrative decisions on a fictional lab. Default is deny: anything outside the named target, or an intrusive category, is refused before a packet leaves. Brute-force asks first.

PACKAGINGa small Python package

You can read the whole data path in an afternoon.

A pip-installable Python package with a short dependency list. One entry point, a module per concern, and nothing hidden. nmap and nuclei are ordinary system binaries it shells out to.

pwner/ # pip install -e . ├─ cli.py # argparse entry point, pwner = pwner.cli:main ├─ app.py # full-screen Textual TUI ├─ repl.py # interactive session logic + plain fallback ├─ llm.py # OpenAI-compatible client + run_tools loop ├─ tools/ # the tool layer: core + 7 domain modules │ ├─ core.py # scope guard, consent gate, @tool registry │ ├─ nmap.py # port/service/vuln/OS scans, discovery, nuclei │ ├─ web.py # scheme probing, discovery, raw HTTP │ ├─ net.py # DNS, banners, raw TCP, SNMP, FTP │ ├─ ad.py # Active Directory + credentialed execution │ ├─ session.py # listener, exfil channel, shell_exec │ ├─ target.py # operator phrase to authorized scope │ └─ report.py # findings, ledger, dependency status ├─ agent.py # orchestration, deterministic fallback, output ├─ prompts.py # the system prompt └─ config.py # ~/.config/pwner/config.json system binaries (not pip): nmap (required), nuclei, netexec, impacket, …
  • One entry pointpwner = pwner.cli:main. From there it is the interactive session, a one-shot scan, or a quick ports/vuln/dns.
  • core.py is the boundarybuild_dispatch wraps every tool with the scope check, so a tool is guarded by being registered — not by remembering. Every other module imports from core and from nothing else. The model calls tools; it cannot edit the guard.
  • Short depshttpx, dnspython, rich, textual. Plus nmap as the one required system binary; the rest are optional.
  • Offline by defaultWith --no-ai there is no model and no network use beyond your in-scope targets.
EXTENSION POINTStools and models

Two places to plug in.

Both are narrow on purpose. A tool adds an action. A model chooses actions. Neither can change the scope lock or the consent gate.

A tool is a function plus a schema.

Decorate an async function with @tool and it is registered, advertised to the model, dispatchable and scope-guarded by that fact alone. You do not call the guard yourself — build_dispatch applies it to every tool, so a tool that forgets cannot slip through. so the model can call it. The scope and consent checks apply the same way to every tool.

pwner/tools/ad.pysketch, not the full API
@tool("List SMB shares on a host.",
      {"host": {"type": "string"}},
      ["host"])
async def smb_shares(ctx, args):
    # host is already scope-checked by the dispatch wrapper
    # read-only enumeration here
    return {"shares": [...]}

The model is yours, or none at all.

Point pwner at any OpenAI-compatible endpoint, a local runtime, or run with no model. It ships no model and no key; it reasons with whatever you configure and must support tool calling.

provider presetsexample
--provider openai     # or deepseek, anthropic, gemini
--provider ollama     # local runtime
--base-url ...        # any OpenAI-compatible endpoint
--no-ai               # deterministic, no model
deterministicNo model, no model-endpoint traffic. --no-ai.
local modelAn endpoint on your own machine, such as Ollama.
hosted modelOnly if you configure one. Receives the scan context you allow.
STATEin process, local-first

State lives in the run, not a database.

There is no server, no account and no embedded graph database. The run's state is an in-process ScanContext; the findings print to the terminal and export as JSON. The only thing that persists between runs is your provider and key in one config file.

  • ScanContextHolds the authorized target, the findings, the notes and the consent decisions for this run. It is ordinary memory, gone when the process exits.
  • Live topologyThe Textual UI renders a tree of hosts, open ports, service and version, and findings as the agent goes. Call it up with /topology. It is a view, not a stored graph.
  • Config~/.config/pwner/config.json holds just your provider and API key, written once by the setup wizard. Nothing else is saved.
outputexample, fictional lab
findings      # severity + evidence + remediation, in the terminal
--json        # the same findings + summary as JSON
/topology     # the live host → port → service → finding tree

# no SARIF, no graph.db, no audit log, no telemetry

No telemetry, and the egress list is short.

your targetsOnly hosts inside the target you named.
a model endpointOnly if you configure one. None with --no-ai.
everything elseNothing. No analytics, no update ping, no crash reports.
DESIGN PRINCIPLESwhat we keep choosing

Rules we hold the design to.

Policy outside the modelThe scope lock and consent gate are enforced in code the model cannot reach.
Deny by defaultAnything outside the named target, or an intrusive category, does not run.
Read-only firstDiscovery, fingerprinting and detection by default. Brute-force asks.
Untrusted tool outputBanners and web bodies are data, never instructions. They cannot move the guard.
Narrow extension pointsTools and models get a small surface and the same checks as everything else.
Small enough to auditIf a piece cannot be reviewed in an afternoon, it is too big.