pwn

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.

Start Here	Entry Points	AI Subsystem	Capabilities
What is PWN	`pwn` REPL	AI / LLM Integration	Plugins (66)
Why PWN	`pwn-ai` Agent	Agent Tool Registry	SAST (48)
How PWN Works	CLI Drivers (53)	Memory · Skills · Learning	AWS (90)
Installation	Build a Driver	Mistakes (neg-feedback)	WWW (21)
General Usage		Extrospection	SDR / Radio
Configuration		Swarm (multi-agent)	Hardware
Configuration		Sessions · Cron	Reports
`~/.pwn/` Persistence			BurpSuite · NmapIt
All Diagrams			Metasploit · Fuzzing
Troubleshooting			Hardware · Blockchain
Contributing			Bounty · FFI · Banner

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.