AGENTmodel optional, scope required

You talk. The agent acts. Scope decides.

pwner's agent is a conversational tool-calling loop. You chat with it in a terminal; it reasons about the target, calls a tool, reads the result and keeps going. The model only ever writes a request. Whether that request runs is decided in code, outside the model, by the scope lock and the consent gates.

modelscope +consenttool requestalloweddeniedrefused in code
Fictional flow. The model asks, the tool layer decides.
THE LOOPobserve, reason, act, report

One loop, and you watch it think in real time.

The planner is your own model, or a deterministic fallback with no model at all. It proposes a tool call; the scope lock and consent gate check it before it runs; then it reads the result and goes again, streaming its reasoning as it works. When a scan turns up new hosts, the loop starts again at observe.

The pwner agent loop Observe, plan, a scope and consent gate, act, validate, report. Validate can loop back to observe when new hosts appear. The scope lock and consent gate check every action in code outside the model. agent proposes (your model, or the deterministic fallback) scope + consent, checked outside the model steer it, or stop it, at any time consentscope + read-only observereasonactconfirmreport read hosts + resultsreason, proposecall a toolread-only checkfindings + summary new hosts re-enter at observe, if still in scope
The pwner agent loop, stacked Observe, reason, a scope and consent gate, act, confirm, report, top to bottom. A dashed line returns from confirm to observe when new hosts appear. The scope lock and consent gate check every action in code outside the model. agent proposesscope + consent consentscope check new hosts re-enter at observe observereasonactconfirmreport read hosts + resultsreason, proposecall a toolread-only checkfindings + summary steer or stop it at any time

The agent proposes, the scope lock and consent gate check it, then it runs. Its reasoning streams as it goes, and new hosts re-enter at observe, if still in scope. You can type to steer it mid-run, or cancel the turn.

observeRead the live hosts, open ports and tool results gathered so far.
reasonThink about what the target actually shows and propose the next tool. The output is a request, never an action.
actCall an allowed tool. The scope lock checks the host first; intrusive actions wait for your consent.
confirmValidate a weakness with a read-only signature: a version, an nmap script, a nuclei template match.
reportSurface confirmed findings with severity, evidence and a fix, then an executive summary.
A RUNsample data, fictional lab
~/engagements/acme-demointeractive session
Sample session, fictional lab. Output is stylized.

Read it as a series of decisions.

  1. reasonYou ask in plain language; the agent says what it is about to do and why before it touches anything.
  2. observeDiscovery runs only inside the target you named. Hosts outside 10.0.0.0/24 are never probed.
  3. searchWith an exact version in hand, it looks up known CVEs instead of reaching for brute-force.
  4. consentBrute-force is denied by default. The agent asks; you answer. Here the operator says no.
  5. refuseA request for a host out of scope is dropped in code, not by the prompt, and the run continues.
  6. findingOnly confirmed issues are reported, each with evidence and a fix.
CONSENTyou decide, the model cannot

Intrusive actions are denied until you allow them.

Discovery, fingerprinting and detection are always read-only. Brute-force and anything active are consent-gated. How a gate resolves depends on how you launched pwner and on whether you have already approved something this session — never on what the model says. The first y you give covers every later intrusive action until /consent off retracts it.

interactivedefault in a TTY --auto-consent non-TTYpiped / scripted
Intrusive actionPauses and prompts you.Runs without a prompt.Auto-denied.
You answery or N, inline.Once, ahead of time, on the command line.Nobody is there, so the answer is no.
Use it forMost sessions.A lab range you own and are cleared to test.CI and scripted runs that must stay safe.

Read-only discovery and detection always run. No setting lets the agent widen the scope, unlock a new target or approve its own intrusive action. set_target is the only tool that can move the scope, and it asks you whenever the new target is outside what you have already authorized; --auto-consent does not cover that, and a non-interactive run refuses it. The model writes a request; the tool layer decides.

CONSENT GATESanswered inline, from the box
consent requiredhigh-impact action
Sample prompt. Wording is stylized.

The agent can ask. It cannot answer for you.

Before a high-impact action, the loop pauses. The prompt says what will run, against what, and the risk. Answer it right from the input box. If nobody answers, the answer is no.

  • yApprove this action once.
  • NRefuse it. The refusal is recorded and the agent tries something else.
  • escCancel the whole turn and go back to the prompt.
  • typeAnything else you type is sent to the agent as live steering.

Keys are for the example TUI; brute-force is the agent's last resort, never its default.

CONFIGflags and config.json

Every limit is a flag you can read.

There is no run file to maintain. The provider and key you set on first run are saved to a small JSON file; everything else is a command-line flag. The model can never add a tool or raise a limit, however it asks.

~/.config/pwner/config.jsonexample
{
  "provider": "deepseek",
  "api_key": "sk-… (saved on first run)"
}
  • --provideropenai, deepseek, anthropic, gemini, ollama or lemonade. Sets the base URL and a default model. A local endpoint needs no API key, and when no model is set pwner asks the server's /models and uses what it finds.
  • --model / --api-keyOverride the model or key. Env vars PWNER_MODEL, PWNER_API_KEY, PWNER_BASE_URL also work.
  • --no-aiSkip the model entirely and run the deterministic suite.
  • --max-stepsCap on tool-calling steps per turn. Default 0, meaning uncapped.
  • --auto-consent / -iAuto-approve gates, or force the interactive [y/N] prompt.
  • --instructionsOperator steering folded into the brief, for example "focus on the database".
40max steps per turn, default
5model providers, plus none
18tools the agent can call
1of them consent-gated

Example values, not recommendations. The model and key are yours; pwner ships neither.

BRING YOUR OWN MODELlocal, hosted or none

Use the model you trust with the data.

pwner ships no model and no key. Point it at something you run, something you pay for, or nothing at all. The model must support function/tool calling.

ollama / lemonadelocal
A model on your own machine. Nothing about the network leaves the host. The right choice for a client who says the data cannot travel.
--provider ollama | lemonade  ·  no API key needed
openai / deepseek / anthropic / geminihosted
A hosted model through an API key you supply. The agent sends the conversation and tool results to the endpoint you chose, and nowhere else.
--provider openai | deepseek | anthropic | gemini
--no-aifallback
No model at all. A fixed suite runs discovery, fingerprinting and detection, so the same input gives the same output. It is the mode to use when a run must be repeatable or fully offline.
deterministic

Whichever model you pick, it sits on the same side of the line. It writes proposals, and everything after that is code you can read.

STAYING IN SCOPEenforced outside the model

The model cannot talk its way past the scope lock.

Scope is not part of the prompt. It is a check in the tool layer that every host-targeting call passes through, and it runs the same way for a local model, a hosted one, or the deterministic fallback.

Where scope is enforced The model, local or hosted or the fallback, sends a request to the scope and consent layer. Inside the tool-layer boundary, it allows a request through to the tool runner and then to targets in scope, or refuses it. tool layer: not controlled by the model modelscope + consenttool runnertargetsrefused request yours or fallbackin scope? gated?active steps gatedin scope onlydropped in code, run continues requestrefused Where scope is enforced, stacked The model sends a request down to the scope and consent layer inside the tool-layer boundary. Allowed requests continue to the tool runner and then to targets in scope. Refused requests stop there. tool layer: not controlled by the model modelscope + consenttool runnertargetsrefused yours or fallbackin scope? gated?read-onlyin scope onlydropped in code requestrefused
  • Scope-lockedEvery host-targeting tool refuses any address outside the single host or CIDR you named.
  • Code, not promptA banner or a web page can try to steer the model. It cannot change the scope lock or the consent gate.
  • No self editThe agent can read its config. It cannot unlock a new target, add a tool or approve its own brute-force.
  • Refusals are dataA refused request is fed back to the model, which reasons and tries something else.

Authorized testing only. Anyone can point pwner at a network they do not own, and no software can stop that. Read responsible use before you run it.