Table of Contents
- Intro
- Documentation
- Installation
- General Usage
- Call to Arms
- Module Documentation
- Keep Us Caffeinated
- 0x004D65726368
Intro
What is PWN
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
Why PWN
Offensive work is hard because the tools do not fit together. PWN's fix is
simple: every capability is a plain Ruby method with the same opts = {}
shape. 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
How PWN Works
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:
Full pages: How PWN Works · All data-flow diagrams
Documentation
The complete wiki lives in this repo at documentation/Home.md.
Rebuild every SVG from its Graphviz source:
cd documentation/diagrams && ./build.sh
Installation
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
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
Call to Arms
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.
Module Documentation
Primary: documentation/Home.md - the full local
wiki with 30+ pages and 26 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).
Keep Us Caffeinated
If this project helped you and you want to support the work, keep us caffeinated:
0x004D65726368
