Install it, scope it, run it on a lab.

Pick a way to install.

All four give you the same pwner binary. Nothing phones home, and nothing leaves your machine until you point it at a model endpoint.

curl -fsSL https://pwner.example/install | sh

• PlatformsLinux (amd64, arm64) is the primary target. macOS and Windows build from the same source. The Docker image is Linux only.
• Check the installRun pwner version, then pwner doctor. Doctor checks your config, your model endpoint if you set one, and that audit logging can write.
• Verify the downloadRelease checksums and signatures are planned. Until the repository is public, treat every URL here as a stand-in.
• Network useNone at install time beyond the download itself. No telemetry, no update pings.

From install to your first report.

Five steps against a lab range. Every address below is fictional. Swap in a network you own or have written permission to test.

1. Create an engagement

   This writes a starter scope.yaml and playbook.yaml into a new folder. The starter scope allows nothing, so nothing can run until you fill it in.

   pwner init acme-demo

   copy

2. Write the scope, then check it

   Open scope.yaml, add your allowed ranges and the hosts to leave alone, and set the time window. The format is below. The check prints what the scope engine will allow and refuse.

   pwner scope check scope.yaml

   copy

3. Dry run the playbook

   A dry run prints every action the playbook would take and sends nothing. Read it once before the first live run.

   pwner run playbook.yaml --dry-run

   copy

   ~/engagements/acme-demosample output, fictional labreplay

   $ pwner run playbook.yaml --dry-run scope acme-demo-internal, window open scope allow 10.0.0.0/24, corp.acme-demo.example scope deny 10.0.0.1, 10.0.0.13 plan 6 steps, approval before each would discover 10.0.0.0/24, 252 addresses would enumerate, passive first refuse 10.0.0.13 is on the deny list, never touched audit dry run logged, 0 packets sent

   sample data, fictional lab. Output format is illustrative.

4. Run it with approvals on

   The default autonomy level asks before every action. Say yes or no at each prompt. Everything you approve or refuse goes to the audit log.

   pwner run playbook.yaml

   copy

5. Write the report

   Turn the run into a Markdown report or SARIF for your tracker. Each finding links back to the audit entries that support it.

   pwner report --format md

   copy

Want the agent to choose steps for you? See how the agent loop works and the three autonomy levels before you raise the setting.

Two files control every run.

A scope file says what you may touch. A playbook says what to do with it. Both are plain YAML and both belong in version control.

engagement: acme-demo-internal
roe_ref: LAB-0042
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
limits:
  rate_pps: 50
  active_checks: read-only
audit: ./pwner-audit.jsonl

name: internal-baseline
scope: ./scope.yaml
autonomy: approve-each-step
steps:
  - run: discover
  - run: enumerate
    with: { mode: passive-first }
  - run: hygiene
    with: { checks: [identity, ad] }
  - run: paths
    with: { to: "Domain Admins" }
  - run: validate
    with: { top: 3, safe: true }
  - run: report
    with: { format: [sarif, md] }

Browse what each step does on the modules page. For how the scope engine enforces the file, see architecture.

Command reference.

Every command reads the scope file and logs to the audit file. Run pwner help <command> for details.

placeholder Command and flag names are illustrative until the first tagged release.

Config reference.

Defaults are cautious. Settings live in ~/.config/pwner/config.yaml (placeholder path) and any of them can be overridden in a playbook or with a flag.

autonomy

How much the agent does without asking. The playbook can set it per run.

default: approve-each-step

planner

Which planner picks steps. deterministic ranks routes by hop count and works offline. model uses your endpoint.

default: deterministic

model.endpoint

URL of a local or hosted model you control. Leave empty and nothing is sent anywhere.

default: unset

budget.max_steps

Stop the agent after this many actions in one run.

default: 40

budget.max_tokens

Stop the agent when model usage reaches this total.

default: 200000

limits.rate_pps

Packets per second cap. A scope file can lower this value but never raise it above the default.

default: 100

audit.path

Where the append-only audit log is written. Every action and refusal is recorded.

default: ./pwner-audit.jsonl

audit.sign

Chain entries with hashes so pwner audit verify can detect edits.

default: true

report.formats

Formats written at the end of a run.

default: [md]

placeholder Keys and defaults are examples for a pre-release build.

Common questions.