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. It will not run without a scope file, it refuses targets that are not on your allowlist, and it records what it does. That makes engagements easier to defend and misuse harder. It does not make misuse impossible: nothing stops a person from writing an allowlist that covers a network 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.
What pwner refuses to do.
Every action, including each one the agent asks for, passes the scope engine before anything touches the network. The checks run in ordinary code outside the planner, so a model cannot talk its way past them.
engagement: acme-demo-internal roe_ref: LAB-0042 # signed rules of engagement window: start: 2026-10-06T09:00Z end: 2026-10-13T17:00Z allow: - 10.0.0.0/24 - corp.acme-demo.example deny: - 10.0.0.1 # gateway, not ours - 10.0.0.13 # dc02, not ours
- Scope file requiredNo scope file, no run. It names the engagement, a reference to the signed rules of engagement and a time window.
- Allowlist, deny by defaultA target must match an allow rule. Anything else is denied, and deny rules win over allow rules.
- Read-only validationValidation confirms that a weakness exists. It does not exploit it, change data or leave anything behind.
- Approval gates onAutonomy starts at approve-each-step. Gates are defined in the playbook, and the agent cannot edit them, widen its scope, add tools or raise its budget.
- Audit log always onEvery action is written down with the rule that allowed it. There is no flag to turn it off.
Details of the agent loop and its autonomy levels are on the Agent page. The config format is in the Docs.
Gates are on until you turn them off.
Out of the box the agent proposes a step and waits. You can loosen that per playbook, one level at a time, and the setting is written to the audit log at the start of each run.
suggestThe agent explains its plan and runs no tools. You run each step yourself.approve-each-step defaultEvery action waits for an operator to confirm it.autonomous-within-scopeThe agent runs its plan inside scope and budget. Out-of-scope requests are still refused, and every step is still logged.A record of what the tool did and why it was allowed.
One line per action, appended as it happens. Each entry names the scope rule that permitted it, or the rule that refused it.
# sample entries, fictional lab {"step":2,"action":"discover","target":"10.0.0.0/24","decision":"allow","rule":"allow[0]","by":"scope-engine"} {"step":3,"action":"discover","target":"10.0.0.13","decision":"deny","rule":"deny[1]","by":"scope-engine"} {"step":6,"action":"validate","target":"files01","decision":"approve","rule":"approve-each-step","by":"operator"} {"step":7,"action":"validate","target":"files01","decision":"allow","rule":"allow[0]","by":"scope-engine"}
The log is append-only by design, and chaining entries by hash so that edits show up is planned. It is a record for you and your client. It is not a guarantee against a determined operator with local file access.
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. Reports about conduct go to the contact in the security policy below until a dedicated address exists. (Placeholder.)
Using pwner
Get written permission before you test, and keep it with the scope file in version control.
Stay inside the window. Check that the scope file matches what the owner signed, not what is convenient.
Tell the owner what you found, and handle reports and logs 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 lets a run reach targets outside the allowlist, bypass deny rules or the time window, or make the agent widen its own scope.
- Audit-hiding
- Anything that skips, edits, truncates or disables audit entries, or that makes the log say something different from what happened.
- Gate bypass
- Anything that lets the planner change approval rules, autonomy level or budget, or that confirms a gate without an operator.
- 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.
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 the contact in the file on this page. 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.contact: security@example.invalid # placeholder pgp: (published at launch) acknowledge: 3 working days # target disclosure: coordinated, 90 days # default supported: latest release only in_scope: - scope engine bypass - audit log tampering - approval gate bypass - unsafe handling of untrusted target data out_of_scope: - misuse by an operator on systems they do not own
The address, key and timelines above are placeholders. The real policy will ship with the repository.
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.
Planned license: Apache-2.0 (placeholder, not final). This page is not legal advice. Talk to a lawyer about your own engagements.