- Intro
- Documentation
- Installation
- General Usage
- Call to Arms
- Module Documentation
- Keep Us Caffeinated
- 0x004D65726368
PWN (pronounced pone, like "own" with a p) is an open-source Ruby toolkit for offensive security automation. One workspace ties together the tools you already use: OSINT, network scanning, web and cloud testing, hardware and radio, reporting, and disclosure. A tool-calling AI agent sits on top and can run those same methods for you.
Red teamers, pentesters, and vulnerability researchers get one place to script and automate instead of gluing together a pile of separate CLIs.
In numbers: 66 PWN::Plugins · 48 PWN::SAST rules · 90 PWN::AWS
service wrappers · 21 PWN::WWW site drivers · 53 bin/pwn_* CLI drivers ·
5 LLM engines · 12 agent toolsets · 78 LLM-callable tools.
Full page: What is PWN
Here's what grok-4.5 has to say about pwn (more specifically pwn-ai):
pwn.ai:grok/grok-4.5/0:500K[CURRENT_VERSION]:002 >>> Briefly describe your take on the reinforced learning feedback loop implemented within `pwn-ai` in clear, concise English so that a human understands your response.
[ <TIMESTAMP> → pwn-ai → task ] Goal: Briefly describe your take on the reinforced learning feedback loop implemented within `pwn-ai` in clear, concise English so that a human understands your response.
Tangible tasks (6) — each task may leverage one or more tools to complete its objective(s):
task 1/6: Review available knowledge of pwn-ai architecture and any reinforced learning elements
task 2/6: Identify the key stages of the feedback loop used for reinforcement
task 3/6: Summarize how actions, rewards, and model updates connect in that loop
task 4/6: Draft a brief plain-English explanation of the overall take on the loop
task 5/6: Refine the draft for clarity and conciseness suitable for a human reader
task 6/6: Present the final short description
... performs tasks ...
**My take, in plain English:**
pwn-ai’s reinforcement loop is mostly **learning in context**, not only weight training.
On every turn the agent acts with tools. Each result is scored in a few ways: quick “did this tool call really fail?” checks, longer-term tool success stats, and—when a final answer lands—a judge that scores whether the *goal* was actually met, plus per-step credit for which tool calls helped or hurt. Failures become fingerprints (mistakes) with fixes; wins become outcomes, exemplars, memory lessons, and sometimes skills. All of that is written back into the next prompt as “what worked,” “what not to repeat,” and “which tools pay off,” so behavior improves on the following run without waiting for a model train.
Around that core sit self-checks: a sentinel that distrusts inflated success rates when the judge disagrees, night jobs that practice the worst repeating mistakes, and optional export of preference pairs for a gated LoRA update when a trainer and GPU exist. So the loop is: **act → measure honestly → remember (and fix) → bias the next act**—with real weight updates as an optional outer ring, not the main daily path.
Offensive work is hard because the tools do not fit together. PWN's fix is simple: every capability is a ruby module that can be used with other modules to produce a diverse set of security "drivers". That one idea means the same code runs:
- live in the REPL
- from an LLM agent in a tool loop
- in a shell script or CI job
- on a cron schedule while you sleep
The whole stack is open source and easy to read. That matters when software is driving security decisions without you watching every click.
Full page: Why PWN
PWN is five layers. Dependencies only point downward, so each level stays small and easy to swap:
On every turn the AI layer runs a feedback loop. It checks inward
(Metrics, Learning, and Mistakes: what failed last time) and outward
(Snapshot, Drift, Intel, RF, and Web: did the host or network change?).
Live checks use browser-backed extro_verify / extro_watch and RF
extro_rf_tune. extro_correlate joins those views so the agent can tell
"I messed up" from "the world moved", and does not repeat the same
mistake:
Failures are fingerprinted across sessions (~/.pwn/mistakes.json), tagged
[REPEATING] / [REGRESSED], and when the same slip shows up again the saved
fix is dropped straight back into the prompt:
Swarm runs several personas at once. Each is a full tool-calling agent, optionally on a different LLM engine, talking over a shared append-only message bus:
Long-running turns also show executive task briefs (not raw commands) via
TaskSummarizer: one full plan on submit (emit_plan!), then per-batch
about_to lines keyed by tool_counts_phrase + intent_phrase with
last_brief_fp duplicate suppression. When recent turns keep hitting the iteration ceiling, the Loop tightens the remaining runway (lower max_iters on local engines, text-only tail, no counterfactual fork) so the agent still finishes instead of thrashing.
Full pages: How PWN Works · All data-flow diagrams
The complete wiki lives in this repo at documentation/Home.md.
Rebuild every SVG from its Graphviz source:
cd documentation/diagrams && ./build.sh
PWN is a single gem with a built-in post-install doctor/provisioner -
pwn setup - that detects your package manager (apt · dnf · pacman ·
brew · port) and installs the OS headers and external tools each
PWN:: capability needs. Tested on Kali/Debian/Ubuntu, Fedora, Arch, macOS.
$ gem install pwn
$ pwn setup # read-only doctor: which capabilities are usable?
$ pwn setup --profile full --yes # provision everything (or: web | net | sdr | vision | ...)
$ pwn
pwn[CURRENT_VERSION]:001 >>> PWN.help
Only need a subset?
$ pwn setup --list-profiles
$ pwn setup --profile web # TransparentBrowser · Burp · ZAP · Tor · sqlmap
$ pwn setup --profile sdr --yes # GQRX · rtl-sdr · hackrf · SoapySDR · FFI DSP
$ pwn setup --profile net --dry-run
Also available as pwn_setup (standalone driver) and pwn --setup[=PROFILE].
The doctor exits non-zero when capabilities are degraded, so CI can gate on it.
Full page: Installation · Configuration
General Usage Quick-Start · local: General PWN Usage
Update PWN frequently - new plugins, agent tools, skills and zero-day tooling land regularly:
$ gem update pwn
$ pwn setup # re-doctor - new versions may add capabilities
$ pwn
pwn[CURRENT_VERSION]:001 >>> PWN.help
From a git checkout:
$ cd /opt/pwn && git pull && rake install && pwn setup
Inside the pwn REPL:
- Full access to every
PWN::module. pwn-ai- launch the autonomous agent TUI (SHIFT+ENTER newline, ENTER submit).pwn-asm,pwn-ai-memory,pwn-ai-sessions,pwn-ai-cron,pwn-ai-delegate.
Headless / CI one-shot (pwn --ai):
$ pwn --ai 'What ports are listening on this host?'
$ echo "$LONG_PROMPT" | pwn --ai -
$ pwn -Y ./ci/pwn.yaml --ai 'Run pwn_sast against ./src and summarize HIGH findings' > findings.txt
Provision a CI runner / Docker image:
$ pwn setup --profile web --yes && pwn setup --check # exits 1 if degraded
Contributions that expand PWN's offensive capabilities are welcome. If you can provide access to additional commercial LLMs, security scanners, or bounty platforms - or wish to contribute plugins, AI skills, or exploit modules - please email us. See CONTRIBUTING.md and the local Contributing page.
Primary: documentation/Home.md - the full local
wiki with 30+ pages and 29 SVG data-flow diagrams.
API reference: rubydoc.info/gems/pwn,
or in-REPL: PWN::Plugins::BurpSuite.help, show-source, ls.
Highlights: Plugins · BurpSuite · Transparent-Browser · pwn-ai Agent · Swarm · Extrospection · SAST · AI Integration
Remember: always have permission before any security testing. Then go pwn all the things (responsibly).
If this project helped you and you want to support the work, keep us caffeinated:
