RULESresponsible use, conduct, disclosure

Test only what you are allowed to test.

pwner is a tool for authorized security testing. This page says what that means in practice, what the tool enforces in code, what we expect from people who use and contribute to it, and how to report a flaw in pwner itself.

AUTHORIZATIONthe one rule
If you do not have written permission to test a network, do not point pwner at it.

Written permission means the owner of the systems, or someone with the authority to speak for them, has agreed in writing to the targets, the dates and the kinds of testing. Your own lab counts. A network you happen to have access to does not.

The tool is built around that rule. Every tool is locked to the target you name, read-only discovery runs freely, and everything active — brute-force, exploitation, remote command execution, reverse shells, credential dumping — is denied until you approve it. That makes engagements easier to run cleanly and misuse harder. It does not make misuse impossible: pwner can break into a system you point it at and consent to, and nothing stops a person from naming a target they do not own. That responsibility is yours.

Unauthorized access is illegal in most jurisdictions, and a tool that automates testing makes it faster, not safer.

GUARDRAILSenforced by the tool, not the model

What pwner refuses to do.

Scope is the target you name on the command line, a host, IP, CIDR or domain. Every host-targeting tool checks it before a packet leaves. The check runs in ordinary code at the tool layer, outside the model, so a planner cannot talk its way past it, and neither can text it reads from a banner or a web page.

set the scopeexample
# scope is the target you name, nothing runs outside it
pwner chat 10.0.0.0/24      # a CIDR
pwner scan 10.0.0.5         # a single host
pwner dns  corp.acme-demo.example

# or set it inside the session:
❯ /target 10.0.0.0/24
~/engagements/acme-demoscope lock
sample session, fictional lab. Messages are illustrative.
  • Scope lockEvery host-targeting tool refuses any address outside the target you named. Enforced in code at the tool layer, not by the prompt.
  • Read-only firstDiscovery, fingerprinting and detection are read-only and run freely — they confirm a weakness by evidence before anything touches it. The deterministic --no-ai suite stops there.
  • Consent-gated intrusionEverything active — brute-force, password spraying, exploitation, remote command execution, reverse shells and credential dumping — is denied by default and needs your y/N. The agent cannot approve itself.
  • Guarded escape hatchThe raw run_nmap passthrough blocks intrusive NSE categories, brute, dos and exploit.
  • No telemetryOnly the model endpoint you choose ever receives data. Nothing else leaves your machine.

The agent loop and how it decides what to call are on the Agent page. The tools and what each one reads are in Modules.

CONSENTdefaults

The agent can ask. It cannot answer for you.

Read-only discovery, fingerprinting and detection always run. The moment the agent wants something intrusive — brute-force, password spraying, remote command execution, a reverse shell, dumping credentials — it stops and asks. How that gate resolves depends only on how you launched pwner, never on the model.

interactive default on a TTYThe agent pauses and prints approve? [y/N]. You answer inline, right in the session. Deny and it moves on. Approval is session-wide: the first y covers every later intrusive action until /consent off retracts it.
--auto-consentIntrusive actions proceed without a prompt. For targets you are authorized to test, when you want an unattended run.
non-interactive piped / scriptedWith no terminal to ask at, every intrusive action is auto-denied. The safe default.

Brute-force is the agent's last resort, never its default. It exhausts cheaper, non-intrusive checks, an anonymous-access check, known-CVE lookups for the exact observed version, default or weak credentials, first, and reaches the gate only when the target genuinely warrants it.

OUTPUT AND PRIVACYwhat you get, what leaves

A report you can act on, and nothing phoned home.

A run ends in confirmed findings, each with a severity, the evidence that proves it and a remediation, plus a short executive summary. Read them in the terminal, or emit the whole run as JSON. There is no hidden log and no analytics.

a findingexample, --json
// sample finding, fictional lab
{
  "host": "10.0.0.5", "port": 80,
  "severity": "high",
  "title": "exposed admin panel",
  "confidence": "confirmed",
  "evidence": "nginx 1.18, /admin returns 200",
  "remediation": "restrict /admin, update nginx"
}

The live network map the agent builds, hosts to ports to service and version to findings, lives only in the session and is shown with /topology. It is not written to disk. The only data that ever leaves your machine goes to the model endpoint you chose; run a local model and nothing leaves at all.

CONDUCTusers and contributors

How we expect people to behave.

Code of conduct

Be direct and be kind. Critique code and ideas, not people. Harassment, discrimination and personal attacks get a warning once, then a ban.

Discussions about techniques stay at the level of defense and authorized testing. Do not post other people's data, credentials or unreleased vulnerabilities in issues, pull requests or chat.

Maintainers can remove content and block accounts. Report conduct privately through GitHub’s private reporting rather than a public issue; there is no separate address yet.

Using pwner

Get written permission before you test, and keep it with your engagement notes in version control.

Point it only at the target you agreed on, not at whatever you happen to have access to.

Tell the owner what you found, and handle reports and findings as confidential client data.

Do not run pwner against systems you do not have permission to test, including to see whether it works.

Contributions we will not accept.

Most contributions are welcome. These are closed, and pull requests that do any of them are declined without review.

Scope evasion
Anything that weakens the scope lock, lets a tool reach a host outside the named target, or lets the agent widen its own scope.
Gate bypass
Anything that lets the model approve its own consent gates, or run an intrusive action without an operator's go-ahead.
Weaponization
Bundling real exploits, payloads or implants, or turning the read-only default into active exploitation by default.
Covert operation
Telemetry, hidden callbacks, persistence on target systems, or features meant to avoid detection by the owner of the network under test.

Contributing guide: coming soon. See the Roadmap for what is open for help.

SECURITY POLICYreporting a flaw in pwner

Found a vulnerability in pwner?

Tell us privately first. We would rather fix it before it is public, and we will credit you if you want to be named.

Send a private reportUse GitHub private vulnerability reporting — the Report a vulnerability button on the Security tab. Do not open a public issue.
Include enough to reproduceVersion, a short description and the steps, run against your own lab.
We reply, fix, then discloseTarget is an acknowledgement within 3 working days and a coordinated date you agree to.
SECURITY.mdin the repository
channel:      GitHub private advisories  # no email needed
acknowledge:  3 working days       # target
disclosure:   coordinated, date agreed with you
supported:    main branch          # pre-1.0, no backports
in_scope:
  - scope lock bypass
  - consent gate bypass
  - operator key or transcript leaking
  - RCE on the operator from a scanned host or a model reply
out_of_scope:
  - misuse by an operator on systems they do not own
  - prompt injection the guard correctly refuses
  - bugs in nmap, nuclei, netexec, impacket (report upstream)

The full policy, including what counts as a vulnerability in an offensive tool, is SECURITY.md in the repository.

LEGALdisclaimer and license

No warranty, and the responsibility is yours.

pwner is provided as is, without warranty of any kind. The authors and contributors are not liable for damage, data loss, downtime or legal consequences that result from using it. You are solely responsible for making sure your use is lawful and authorized.

Testing can disrupt systems even when it is read-only. Agree on a window and a contact with the system owner, and have a way to stop a run.

License: GNU AGPL-3.0-or-later. This page is not legal advice. Talk to a lawyer about your own engagements.

license AGPL-3.0-or-latertelemetry none