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.
Sample flow, fictional lab range. Select a step or let it cycle.
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
service_detect 10.0.0.21inside target 10.0.0.0/24rundns_enum corp.acme-demo.exampleresolves in scoperunport_scan 203.0.113.50outside the targetrefuserun_nmap --script bruteintrusive NSE categoryrefusehydra_brute 10.0.0.30:22consent-gated actionaskIllustrative 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.
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.
- One entry point
pwner = pwner.cli:main. From there it is the interactive session, a one-shotscan, or a quickports/vuln/dns. - core.py is the boundary
build_dispatchwraps every tool with the scope check, so a tool is guarded by being registered — not by remembering. Every other module imports fromcoreand from nothing else. The model calls tools; it cannot edit the guard. - Short deps
httpx,dnspython,rich,textual. Plus nmap as the one required system binary; the rest are optional. - Offline by defaultWith
--no-aithere is no model and no network use beyond your in-scope targets.
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.
@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 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.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.jsonholds just your provider and API key, written once by the setup wizard. Nothing else is saved.
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.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.