# PWN Documentation

> **PWN** (/pōn/) - an open-source offensive-security automation framework and
> continuous-security-integration platform written in Ruby.
> 66 plugins · 48 SAST rules · 90 AWS wrappers · 21 WWW drivers · 53 CLI
> drivers · 5 LLM engines · a self-improving multi-agent AI · one REPL.

**Repo root:** `/opt/pwn` · **This wiki:** `/opt/pwn/documentation/` ·
**Rebuild diagrams:** `documentation/diagrams/build.sh`

---

## 🗺️ Start Here

| | |
|---|---|
| [What is PWN](What-is-PWN.md) | One-paragraph elevator pitch |
| [Why PWN](Why-PWN.md) | Design philosophy - why another framework |
| [How PWN Works](How-PWN-Works.md) | The five layers, with the architecture diagram |
| [Installation](Installation.md) | `gem install pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
| [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
| [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
| **[All Data-Flow Diagrams](Diagrams.md)** | **28 SVGs** in one scrollable page |

## 🚪 Entry Points

| | |
|---|---|
| [The `pwn` REPL](pwn-REPL.md) | Pry shell with the whole `PWN::` namespace pre-loaded |
| [`pwn-ai` Autonomous Agent](pwn-ai-Agent.md) | Natural-language TUI + `pwn --ai PROMPT` one-shot |
| [CLI Drivers `bin/pwn_*`](CLI-Drivers.md) | 53 headless executables for CI/CD |
| [Drivers (build your own)](Drivers.md) | Turn a REPL session into a shipped binary |

## 🤖 AI Subsystem  (`PWN::AI`)

| | |
|---|---|
| [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama |
| [Agent Tool Registry](Agent-Tool-Registry.md) | 12 toolsets · **78** LLM-callable tools |
| [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection - the self-improvement loop |
| [Mistakes](Mistakes.md) | **Negative feedback** - fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
| [Reinforcement Learning](Reinforcement-Learning.md) | **`Reward` + `Curriculum`** - ORM/PRM · P9/P14 trajectory DPO · P15 scrub · P16 warm · P17 budget skill · P18 PRM→rank · P19 diet gate · export-ready LoRA |
| [Extrospection](Extrospection.md) | World-awareness - snapshot · drift · intel · **watch** · **verify** · **rf_tune** · **osint** · serial · telecomm · packet · vision · voice · correlate |
| [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
| [Sessions](Sessions.md) | Transcript persistence + reflection |
| [Cron](Cron.md) | Scheduled autonomous jobs (nightly self-play + weekly weight-loop seeded by default) |

## 🧩 Capability Namespaces  (`lib/pwn/*`)

| | |
|---|---|
| [Plugins (66)](Plugins.md) | Every `PWN::Plugins::*` module by category |
|   ↳ [BurpSuite](BurpSuite.md) ⭐ | Preferred web proxy / scanner |
|   ↳ [TransparentBrowser](Transparent-Browser.md) | Headless / visible browser automation |
|   ↳ [NmapIt](NmapIt.md) | Network discovery |
|   ↳ [Metasploit](Metasploit.md) | RPC exploitation |
|   ↳ [Fuzzing](Fuzzing.md) | `Fuzz` · `Sock` · `Packet` |
|   ↳ [Hardware](Hardware.md) | Serial · BusPirate · MSR206 · Android · BareSIP |
| [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
| [WWW (21 drivers)](WWW.md) | Browser automations for real sites |
| [AWS (90 services)](AWS.md) | Cloud-security enumeration |
| [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro · **Decoder::* (20)** · FFI-accelerated DSP |
| [Blockchain](Blockchain.md) | BTC · ETH helpers |
| [Bounty](Bounty.md) | Lifecycle / auth-replay tooling |
| [Reports](Reporting.md) | HTML/JSON output + DefectDojo/Jira |
| [FFI](FFI.md) | Native DSP/RF backends (Volk · Liquid · FFTW · HackRF · RTL-SDR · **AdalmPluto** · SoapySDR · Stdio) |
| [Banner](Banner.md) | 15 startup banners |

## 🛠️ Meta

| | |
|---|---|
| [`~/.pwn/` Filesystem Map](Persistence.md) | Every file PWN writes and why · `PWN::Migrate` state doctor |
| [Troubleshooting](Troubleshooting.md) | Common errors and fixes |
| [Contributing](Contributing.md) | Conventions, RuboCop, spec rules |

---

<sub>Edit any `.md` directly. Edit diagrams in `documentation/diagrams/dot/*.dot`, then run `./build.sh`.</sub>