pwn 0.5.628 → 0.5.631

data/documentation/FFI.md

@@ -1,4 +1,4 @@
-# `PWN::FFI` — Native Calls for DSP & RF
+# `PWN::FFI` - Native Calls for DSP & RF Front-Ends
 
 Thin `ffi`-gem bindings to **already-installed** system shared objects. Nothing
 is compiled at `gem install` time, nothing shells out. If a `.so` is missing the
@@ -7,21 +7,34 @@ pure Ruby.
 
 ```ruby
 PWN::FFI.backends
-# => {FFTW: true, HackRF: true, Liquid: true, RTLSdr: true, SoapySDR: true, Volk: true}
+# => {AdalmPluto: true, FFTW: true, HackRF: true, Liquid: true,
+#     RTLSdr: true, SoapySDR: true, Volk: true}
 
 PWN::FFI.available?(mod: :Volk)  # => true/false
 ```
 
+## Install the shared objects
+
+```bash
+pwn setup --profile sdr   # rtl-sdr, hackrf, libiio/libad9361, SoapySDR,
+                          # libvolk, libliquid, libfftw3, libsndfile, libusb
+```
+
+`pwn setup` (the [doctor](Installation.md)) reports each `PWN::FFI` backend
+as `ok` / `MISSING` and knows the correct package name on `apt` / `dnf` /
+`pacman` / `brew` / `port`.
+
 ## Modules (`lib/pwn/ffi/*.rb`)
 
 | Module | Shared object | Role |
 |---|---|---|
-| **`Volk`** | `libvolk` | SIMD kernels: s16→f32 convert, accumulate, \|z\|², scale, dot-product. Backs `Decoder::DSP.unpack_s16le` / `rms_dbfs`. |
+| **`Volk`** | `libvolk` | SIMD kernels: s16 to f32 convert, accumulate, \|z\|^2, scale, dot-product. Backs `Decoder::DSP.unpack_s16le` / `rms_dbfs`. |
 | **`Liquid`** | `libliquid` | liquid-dsp: `freqdem` (FM demod), `msresamp_rrrf` (arbitrary resample), Kaiser FIR, DC blocker. Backs `Decoder::DSP.resample` / `dc_block`. |
 | **`FFTW`** | `libfftw3f` | Single-precision FFTW3: real & complex 1-D FFTs, magnitude / power-dB helpers for spectrum work. |
-| **`HackRF`** | `libhackrf` | Control plane (init/open/tune/rate/gains) + device info for Extrospection `probe_rf` and wideband I/Q capture. |
-| **`RTLSdr`** | `librtlsdr` | Device list, tune, gain, blocking `read_sync` of raw u8 I/Q. |
-| **`SoapySDR`** | `libSoapySDR` | Enumerate every Soapy-backed front-end (RTL-SDR, HackRF, Airspy, Pluto, UHD, …); API/ABI/lib version. |
+| **`RTLSdr`** | `librtlsdr` | Device list, open/tune/gain, blocking `read_sync` of raw cu8 I/Q. |
+| **`HackRF`** | `libhackrf` | Open/tune/rate/gains + **callback RX streaming** (`start_rx`/`read_sync`/`stop_rx`/`capture`) of raw cs8 I/Q. |
+| **`AdalmPluto`** | `libiio` (+ `libad9361`) | ADALM-Pluto (ad9361-phy). `open`/`configure`/`start_rx`/`read_sync`/`stop_rx`/`capture` of cs16 I/Q; USB or `ip:192.168.2.1`. |
+| **`SoapySDR`** | `libSoapySDR` | Enumerate every Soapy-backed front-end (RTL-SDR, HackRF, Airspy, Pluto, LimeSDR, UHD, ...) **and** stream cs16 I/Q from any of them (`open`/`configure`/`start_rx`/`read_sync`/`stop_rx`/`close`). |
 | `Stdio` | `libc` | Classic `puts` / `printf` / `scanf` for shellcode / format-string research. |
 
 ## Design rules
@@ -29,11 +42,17 @@ PWN::FFI.available?(mod: :Volk)  # => true/false
 1. **Thin & optional.** Attach a minimal surface; prefer high-level Ruby wrappers
    (`Liquid.freq_demod`, `Volk.unpack_s16le`) over raw C pointers in call sites.
 2. **No install-time compile.** Use the system package (`libvolk-dev`,
-   `libliquid-dev`, `libfftw3-dev`, `libhackrf-dev`, …). On hosts without them
-   every `.available?` is `false` and pure-Ruby paths keep working.
+   `libliquid-dev`, `libfftw3-dev`, `libhackrf-dev`, `libiio-dev`, ...). Install
+   them all with **`pwn setup --profile sdr`** (see [Installation](Installation.md)).
+   On hosts without them every `.available?` is `false` and pure-Ruby paths
+   keep working.
 3. **Namespace hygiene.** `PubFFI = ::FFI` (defined once in `lib/pwn/ffi.rb`)
-   avoids the `PWN::FFI` ↔ `::FFI` collision when modules `extend PubFFI::Library`.
-4. **Fallbacks in DSP.** `PWN::SDR::Decoder::DSP` probes `PWN::FFI.available?`
+   avoids the `PWN::FFI` vs `::FFI` collision when modules `extend PubFFI::Library`.
+4. **Uniform front-end contract.** Every hardware binding exposes the same
+   verbs: `available?`, `open`, `configure`, `start_rx`, `read_sync`, `stop_rx`,
+   `close`, plus a one-shot `capture` where practical. `Decoder::Base.run_iq`
+   only depends on that contract, not on any specific radio.
+5. **Fallbacks in DSP.** `PWN::SDR::Decoder::DSP` probes `PWN::FFI.available?`
    and rescues into pure Ruby. Toggle globally with
    `PWN::SDR::Decoder::DSP.native = false`.
 
@@ -50,29 +69,47 @@ audio = PWN::FFI::Liquid.freq_demod(iq: interleaved_iq, kf: 0.5)
 # Real FFT power spectrum
 db = PWN::FFI::FFTW.rfft_power_db(samples: audio, n: 4096)
 
-# RF inventory
+# RF front-end inventory
 PWN::FFI::SoapySDR.list_devices
 PWN::FFI::HackRF.info
 PWN::FFI::RTLSdr.list_devices
+PWN::FFI::AdalmPluto.list_uris
+
+# Stream raw I/Q from ANY Soapy-backed device
+h = PWN::FFI::SoapySDR.open(args: 'driver=rtlsdr')
+PWN::FFI::SoapySDR.configure(handle: h, freq_hz: 929_612_500, rate_hz: 2_048_000)
+PWN::FFI::SoapySDR.start_rx(handle: h)
+data = PWN::FFI::SoapySDR.read_sync(handle: h)   # cs16le interleaved I/Q
+PWN::FFI::SoapySDR.close(handle: h)
+
+# One-shot HackRF capture
+iq = PWN::FFI::HackRF.capture(freq_hz: 1_090_000_000, rate_hz: 2_000_000, samples: 262_144)
 ```
 
-## How this accelerates `PWN::SDR::Decoder::*`
+## True-air decode: how this drives `PWN::SDR::Decoder::*`
 
-Audio-rate protocols (POCSAG, FLEX, Morse, RTTY, APT, …) stay on the GQRX
-48 kHz UDP tap and now automatically pick up VOLK/liquid for unpack + resample
-hot loops.
+Every decoder module now has a **true over-the-air I/Q path** via
+`PWN::SDR::Decoder::Base.run_iq`, which:
 
-Wideband protocols (ADS-B, GSM, LTE, LoRa, WiFi, …) still characterise bursts
-from the audio tap via `Base.run_detector`, but can graduate to true
-demodulation by:
+1. Calls `Base.resolve_iq_source(source: :auto)` to pick the first working
+   front-end in order `:file` -> `:rtlsdr` -> `:adalm_pluto` -> `:hackrf` ->
+   `:soapy` (or a forced `:source`).
+2. Streams raw I/Q via the uniform `read_sync` contract above.
+3. Unpacks (`cu8`/`cs8`/`cs16`) and either hands complex samples to
+   `demod#feed_iq(iq, rate:)` or FM-demodulates first and calls
+   `demod#feed(audio)` for narrowband protocols.
+4. Emits the same JSONL-logged Hash frames every decoder already produces.
+5. Falls back to `Base.run_detector` (energy characterizer) when no hardware
+   or capture file is present, so the operator still gets structured output.
 
-1. Opening a front-end via `PWN::FFI::RTLSdr` / `HackRF` / `SoapySDR`
-2. Reading raw I/Q
-3. Running native DSP (`Liquid.freq_demod`, `FFTW.rfft`, VOLK magnitude)
-4. Emitting the same Hash frames decoders already JSONL-log
+| Decoder | Air path | I/Q entry point |
+|---|---|---|
+| ADSB, Bluetooth, DECT, GPS, GSM, Iridium, LoRa, LTE, P25, RFID, RTL433, WiFi, ZigBee | `run_iq` (wideband) | `#feed_iq(iq, rate:)` |
+| APT, FLEX, Morse, Pager, POCSAG, RTTY | `run_iq(fm_demod: true)` or `run_native` (GQRX 48 kHz UDP) | `#feed(audio)` |
+| RDS | GQRX built-in RDS decoder (`RDS.sample`) | n/a |
 
 No decoder shells out; Ruby remains the orchestrator.
 
-**See also:** [SDR](SDR.md) · [Hardware](Hardware.md)
+**See also:** [SDR](SDR.md) - [Hardware](Hardware.md)
 
-[← Home](Home.md)
+[<- Home](Home.md)

data/documentation/Fuzzing.md

@@ -1,7 +1,10 @@
-# Fuzzing — `PWN::Plugins::Fuzz` · `Sock` · `Packet`
+# Fuzzing - `PWN::Plugins::Fuzz` · `Sock` · `Packet`
 
 ![Fuzzing workflow](diagrams/fuzzing-workflow.svg)
 
+> **Install:** `pwn setup --profile net` - pcaprub headers · tshark ·
+> tcpdump. See [Installation](Installation.md).
+
 ## Generate
 
 ```ruby

data/documentation/General-PWN-Usage.md

@@ -1,4 +1,4 @@
-# General Usage — Day-One Cheat Sheet
+# General Usage - Day-One Cheat Sheet
 
 ## Launch
 
@@ -8,12 +8,23 @@ $ pwn --ai "scan 10.0.0.0/24 with NmapIt and summarise open services"
 $ pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/   # headless driver
 ```
 
+## Check / provision this host
+
+```bash
+$ pwn setup                   # doctor: which PWN:: capabilities are usable here?
+$ pwn setup --profile web     # install what TransparentBrowser / Burp / ZAP need
+$ pwn setup --list-profiles   # core · ai · web · net · db · sdr · vision · voice · exploit · hardware · full
+```
+
+See [Installation](Installation.md) for every flag and the `PWN::Setup` API.
+
 ## Inside the REPL
 
 ```ruby
 PWN.help                            # top-level help
 PWN::Plugins.constants.sort         # list all 66 plugins
 PWN::Plugins::NmapIt.help           # per-plugin usage
+PWN::Setup.check                    # capability doctor from inside the REPL
 ls PWN::Plugins::BurpSuite          # Pry: list methods
 show-source PWN::SAST::SQL.scan     # Pry: read the code
 history                             # what you've typed → copy into a driver
@@ -25,6 +36,7 @@ history                             # what you've typed → copy into a driver
 |---|---|
 | `pwn-ai` | Enter the agent TUI (SHIFT+ENTER = newline, ENTER = submit) |
 | `pwn-asm` | Multi-line assembly ↔ opcode workbench |
+| `pwn-vault` | Decrypt → edit `~/.pwn/pwn.yaml` in `$EDITOR` → re-encrypt |
 | `pwn-ai-memory` | Inspect / edit `~/.pwn/memory.json` |
 | `pwn-ai-sessions` | List / view / delete transcripts |
 | `pwn-ai-cron` | List / run scheduled jobs |

data/documentation/Hardware.md

@@ -3,11 +3,15 @@
 ![Hardware hacking](diagrams/hardware-hacking.svg)
 ![Reverse engineering](diagrams/reverse-engineering-flow.svg)
 
+> **Install:** `pwn setup --profile hardware` - libusb · adb · baresip
+> (Serial · BusPirate · Android · BareSIP · `extro_serial` ·
+> `extro_telecomm`). See [Installation](Installation.md).
+
 ## Serial / Bus
 
 | Module | Use |
 |---|---|
-| `PWN::Plugins::Serial` | Generic UART (`/dev/ttyUSB*`) — read/write, baud detect |
+| `PWN::Plugins::Serial` | Generic UART (`/dev/ttyUSB*`) - read/write, baud detect |
 | `PWN::Plugins::BusPirate` | SPI/I²C/1-Wire via Bus Pirate |
 | `PWN::Plugins::MSR206` | ISO magstripe read/write (tracks 1-3) |
 
@@ -16,7 +20,7 @@ CLI: `pwn_serial_msr206`, `pwn_serial_qualcomm_commands`,
 
 ## Mobile
 
-`PWN::Plugins::Android` — `adb_net_connect`, `adb_sh`, `adb_push/pull`,
+`PWN::Plugins::Android` - `adb_net_connect`, `adb_sh`, `adb_push/pull`,
 `take_screenshot`, `screen_record`, `list_installed_apps`, `dumpsys`,
 `open_app`, `find_hidden_codes`, `swipe`, `input`, `input_special`,
 `invoke_event_listener`. CLI war-dialer: `pwn_android_war_dialer`.
@@ -28,13 +32,13 @@ CLI: `pwn_phone`.
 
 ## Radio
 
-See [SDR](SDR.md) — GQRX, FlipperZero, RFIDler, SonMicro.
+See [SDR](SDR.md) - GQRX, FlipperZero, RFIDler, SonMicro.
 
 ## Binary / RE
 
-- `PWN::Plugins::XXD` — hex dump / patch
-- `PWN::Plugins::Assembly` + `pwn-asm` REPL — opcodes ↔ asm, multi-arch
-- `PWN::Plugins::BlackDuckBinaryAnalysis` — SBOM + CVE match on firmware
-- [`PWN::FFI`](FFI.md) — call libc from Ruby
+- `PWN::Plugins::XXD` - hex dump / patch
+- `PWN::Plugins::Assembly` + `pwn-asm` REPL - opcodes ↔ asm, multi-arch
+- `PWN::Plugins::BlackDuckBinaryAnalysis` - SBOM + CVE match on firmware
+- [`PWN::FFI`](FFI.md) - call libc from Ruby
 
 [← Home](Home.md) · [SDR](SDR.md) · [FFI](FFI.md)

data/documentation/Home.md

@@ -1,8 +1,8 @@
 # PWN Documentation
 
-> **PWN** (/pōn/) — an open-source offensive-security automation framework and
+> **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 · 52 CLI
+> 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/` ·
@@ -15,11 +15,11 @@
 | | |
 |---|---|
 | [What is PWN](What-is-PWN.md) | One-paragraph elevator pitch |
-| [Why PWN](Why-PWN.md) | Design philosophy — why another framework |
+| [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) | RVM, gem, `./install.sh`, first launch |
+| [Installation](Installation.md) | `gem install pwn` → `pwn setup` doctor/provisioner · capability profiles |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
-| [Configuration](Configuration.md) | `~/.pwn/config.yml` — engines, keys, agent options |
+| [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
 | **[All Data-Flow Diagrams](Diagrams.md)** | **27 SVGs** in one scrollable page |
 
 ## 🚪 Entry Points
@@ -28,7 +28,7 @@
 |---|---|
 | [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) | 52 headless executables for CI/CD |
+| [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`)
@@ -37,9 +37,9 @@
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama |
 | [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 61 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 |
-| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · **watch** · **verify** · **rf_tune** · correlate · **rf** · **web** |
+| [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 |
+| [Extrospection](Extrospection.md) | World-awareness - snapshot · drift · intel · **watch** · **verify** · **rf_tune** · correlate · **rf** · **web** |
 | [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
 | [Sessions](Sessions.md) | Transcript persistence + reflection |
 | [Cron](Cron.md) | Scheduled autonomous jobs |

data/documentation/How-PWN-Works.md

@@ -6,23 +6,24 @@ below have no criss-crossing lines.
 
 ![Overall Architecture](diagrams/overall-pwn-architecture.svg)
 
-## L0 — Actors
+## L0 - Actors
 
-Humans (`pwn` REPL, `pwn-ai` TUI), CI runners (`pwn --ai "…"`, `bin/pwn_*`),
+Humans (`pwn` REPL, `pwn-ai` TUI), CI runners (`pwn --ai "..."`, `bin/pwn_*`),
 LLM providers (over HTTPS), and targets (hosts, web apps, clouds, radios,
 hardware).
 
-## L1 — Entry points  (`bin/`)
+## L1 - Entry points  (`bin/`)
 
 | Entry | File | Purpose |
 |---|---|---|
 | `pwn` REPL | `lib/pwn/plugins/repl.rb` | Pry with `PWN::` pre-loaded + custom commands |
 | `pwn-ai` | `lib/pwn/ai/agent/loop.rb` | Agent TUI inside the REPL |
 | `pwn --ai PROMPT` | `bin/pwn` | Headless one-shot agent (CI-friendly) |
-| `bin/pwn_*` | 52 files | Thin OptionParser wrappers over one plugin each |
+| `pwn setup` | `lib/pwn/setup.rb` · `bin/pwn_setup` | Post-install doctor + capability provisioner (also `pwn --setup[=PROFILE]`) |
+| `bin/pwn_*` | 53 files | Thin OptionParser wrappers over one plugin each |
 | `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs → any of the above |
 
-## L2 — AI agent core  (`lib/pwn/ai/agent/`)
+## L2 - AI agent core  (`lib/pwn/ai/agent/`)
 
 | Module | Role |
 |---|---|
@@ -30,21 +31,21 @@ hardware).
 | `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · 61 tools |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / EXTROSPECTION blocks |
-| `Metrics` · `Learning` | **introspection** — how well am I doing? |
-| `Mistakes` | **negative feedback** — fingerprint failures, do NOT repeat, `[REPEATING]`/`[REGRESSED]`, inline `correction_hint` |
-| `Extrospection` | **extrospection** — on-demand world sensing (`intel` · **`verify`** · **`watch`** · **`rf_tune`**) + ambient baseline (host · net · toolchain · repo · env · **rf** · **web**) joined to introspection via `correlate` |
+| `Metrics` · `Learning` | **introspection** - how well am I doing? |
+| `Mistakes` | **negative feedback** - fingerprint failures, do NOT repeat, `[REPEATING]`/`[REGRESSED]`, inline `correction_hint` |
+| `Extrospection` | **extrospection** - on-demand world sensing (`intel` · **`verify`** · **`watch`** · **`rf_tune`**) + ambient baseline (host · net · toolchain · repo · env · **rf** · **web**) joined to introspection via `correlate` |
 | `Swarm` | multi-agent personas over a shared JSONL bus |
 
 See [Agent Tool Registry](Agent-Tool-Registry.md) for every tool the LLM can call.
 
-## L3 — Capability namespaces  (`lib/pwn/*`)
+## L3 - Capability namespaces  (`lib/pwn/*`)
 
 `Plugins` (66) · `SAST` (48) · `WWW` (21) · `AWS` (90) · `SDR` · `Blockchain` ·
 `Bounty` · `Reports` · `FFI` · `Banner`. Each is a plain module of
-`public_class_method def self.x(opts = {})` methods — callable identically from
+`public_class_method def self.x(opts = {})` methods - callable identically from
 the REPL, from `pwn_eval`, or from a driver.
 
-## L4 — Persistence  (`~/.pwn/`)
+## L4 - Persistence  (`~/.pwn/`)
 
 Everything the framework remembers between processes lives in one directory:
 
@@ -54,7 +55,7 @@ See [Persistence](Persistence.md) for the byte-level layout of each file.
 
 ## The feedback loop
 
-The reason L2 exists is to close this loop on every turn — successes
+The reason L2 exists is to close this loop on every turn - successes
 become skills/lessons, **failures become fingerprinted mistakes with fixes**,
 **world-state is sensed on demand** (`extro_verify` / `extro_watch` /
 `extro_rf_tune` / `extro_osint` / `extro_serial` / `extro_telecomm` / `extro_packet` / `extro_vision` / `extro_voice` / `extro_intel`) and correlated against those failures, and

data/documentation/Installation.md

@@ -1,73 +1,237 @@
 # Installation
 
-PWN is tested on **Debian-based Linux** (Kali, Ubuntu) and **macOS**, using
-Ruby via **RVM**.
+PWN ships as a **single Ruby gem** whose runtime is 100 % `autoload`ed -
+a plugin whose native extension or OS binary is missing costs nothing until
+you actually touch that constant. That means the install is **two steps**:
+
+```bash
+gem install pwn      # 1. get the gem (pure-Ruby core always works)
+pwn setup            # 2. doctor + provision this host's capabilities
+```
+
+`pwn setup` is the built-in **doctor / provisioner** (`PWN::Setup`). It
+detects your OS package manager (`apt` · `dnf` · `pacman` · `brew` · `port`),
+reports which `PWN::` capabilities are usable on *this* host, and - when
+asked - installs exactly the OS headers, external tools, and native gems
+needed to unlock the ones you want. No `/opt/pwn` checkout, no `rvmsudo`
+chain, no bash provisioners required.
+
+Tested on **Kali / Debian / Ubuntu**, **Fedora**, **Arch**, and **macOS**
+(Homebrew or MacPorts). Ruby ≥ 3.4 (RVM, rbenv, asdf, or system Ruby).
+
+---
 
 ## Quick install (recommended)
 
 ```bash
-cd /opt
-sudo git clone https://github.com/0dayinc/pwn
-cd /opt/pwn
-./install.sh          # system deps (nmap, chromium, graphviz, …)
-./install.sh ruby-gem # rvm gemset + bundle install + rake install
-pwn                   # launch the REPL
+gem install pwn
+pwn setup                      # read-only doctor: what's usable, what's missing
+pwn setup --profile full --yes # install everything for every PWN:: namespace
+pwn                            # launch the REPL
+```
+
+```text
+pwn[v0.5.628]:001 >>> PWN.help
+```
+
+If you only need a subset (e.g. web testing on a CI runner, SDR on a lab
+box), install just that **capability profile** - see below.
+
+---
+
+## `pwn setup` - the post-install doctor & provisioner
+
+Three equivalent spellings ship with the gem:
+
+| Invocation | Same as |
+|---|---|
+| `pwn setup [opts]` | bare-word subcommand of `bin/pwn` |
+| `pwn_setup [opts]` | standalone driver (`bin/pwn_setup`) |
+| `pwn --setup[=PROFILE]` | flag form; no `PROFILE` = check, `PROFILE` = deps |
+
+### Read-only doctor (default)
+
+```bash
+$ pwn setup            # or: pwn setup --check   / pwn --setup / pwn_setup
+```
+
+Prints a per-capability report and **exits non-zero if anything is degraded**
+(so you can gate CI on it):
+
+```text
+PWN v0.5.628 · ruby 4.0.5 · linux x86_64 · pkg-manager: apt
+
+~/.pwn/                    ok   (11 entries)
+~/.pwn/pwn.yaml            ok   (encrypted, decryptor present)
+AI engine                  ok   anthropic (key set)
+
+Ruby extensions
+  pg             MISSING  (needs: postgresql-server-dev-all)  → PWN::Plugins::DAOPostgres
+  pcaprub        ok                                            → PWN::Plugins::Packet, extro_packet
+  nokogiri       ok                                            → PWN::Plugins::TransparentBrowser, PWN::WWW
+  ...
+
+External toolchain                              used by
+  nmap           ok    /usr/bin/nmap            PWN::Plugins::NmapIt
+  gqrx           MISSING                        PWN::SDR, extro_rf_tune
+  ...
+
+31 / 36 capabilities usable · 5 degraded
+
+Run `pwn setup --deps` to install missing OS headers/tools, or
+    `pwn setup --profile <name>` for a subset. See `pwn setup --list-profiles`.
+```
+
+### Install dependencies
+
+```bash
+pwn setup --deps                     # profile :full - everything
+pwn setup --profile web              # just TransparentBrowser · Burp · ZAP · Tor
+pwn setup --profile sdr --yes        # non-interactive (CI / packer / docker)
+pwn setup --profile net --dry-run    # print the apt/dnf/brew/... commands only
+pwn setup --list-profiles
 ```
 
+`--deps` / `--profile` will:
+
+1. Resolve the profile → set of native gems + external binaries.
+2. Map those to OS packages for **your** package manager (data lives in
+   `PWN::Setup::NATIVE_GEMS` / `::TOOLCHAIN` - versioned with the gem, so
+   `gem install pwn`, git checkout, Docker, Packer and Vagrant all read the
+   same table).
+3. Show the exact commands, prompt (unless `--yes`), run them, then
+   `gem pristine` / `gem install` any native extension that still fails to
+   load, and re-run the doctor.
+
+### Capability profiles
+
+`pwn setup --list-profiles` (source of truth: `PWN::Setup::PROFILES`)
+
+| Profile | Unlocks |
+|---|---|
+| `core` | `~/.pwn` bootstrap · vault · REPL - always applied |
+| `ai` | verify at least one AI engine key/oauth in `~/.pwn/pwn.yaml` |
+| `web` | `TransparentBrowser` · `BurpSuite` · `Zaproxy` · `extro_verify` · `extro_watch` · `sqlmap` · `tor` |
+| `net` | `NmapIt` · `Packet` · `extro_packet` · `extro_osint` · `tshark`/`tcpdump` |
+| `db` | `DAOPostgres` · `DAOSqlite3` · `DAOMongo` |
+| `sdr` | `PWN::SDR` · GQRX · `PWN::FFI` DSP backends · `extro_rf_tune` · rtl-sdr / hackrf / SoapySDR |
+| `vision` | `OCR` · `ScannableCodes` · `Reports` · `extro_vision` · tesseract / zbar / graphviz |
+| `voice` | `PWN::Plugins::Voice` · `extro_voice` · espeak-ng / sox |
+| `exploit` | `Metasploit` · `sqlmap` |
+| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `extro_serial` · `extro_telecomm` |
+| `full` | everything above |
+
+### All flags
+
 ```text
-pwn[v0.5.616]:001 >>> PWN.help
+pwn setup [--check] [--deps] [--profile NAME] [--list-profiles]
+          [--yes] [--dry-run]
 ```
 
-## Gem-only install
+| Flag | Meaning |
+|---|---|
+| *(none)* / `-c`, `--check` | Read-only doctor. Exit 1 if any capability degraded. |
+| `-d`, `--deps` | Install OS packages + rebuild native gems for `--profile` (default `full`). |
+| `-p`, `--profile NAME` | One of the profiles above. Implies `--deps`. |
+| `-l`, `--list-profiles` | Print profile table and exit. |
+| `-y`, `--yes` | Assume yes; non-interactive (CI / Docker / Packer). |
+| `-n`, `--dry-run` | Print the commands that *would* run, do nothing. |
+
+---
+
+## From a git checkout (contributors)
 
 ```bash
-rvm install ruby-4.0.5
-rvm use     ruby-4.0.5@pwn --create
-gem install --verbose pwn
-pwn
+git clone https://github.com/0dayinc/pwn /opt/pwn
+cd /opt/pwn
+bundle install
+rake install                         # or: rvmsudo rake install (multi-user RVM)
+pwn setup --profile full --yes       # same provisioner, same data tables
 ```
 
+The legacy `./install.sh` / `packer/provisioners/pwn.sh` bash paths still
+work, but they now simply delegate to `pwn setup` - the `case $os` package
+lists have been consolidated into `PWN::Setup::NATIVE_GEMS` / `::TOOLCHAIN`.
+
+---
+
+## Docker / Packer / Vagrant / CI
+
+`pwn setup` is the single provisioning entry point for every image builder:
+
+```dockerfile
+FROM kalilinux/kali-rolling
+RUN gem install pwn && pwn setup --profile full --yes
+```
+
+```yaml
+# .gitlab-ci.yml - fail the job if the runner is missing a capability
+before_script:
+  - pwn setup --profile web --yes
+  - pwn setup --check
+```
+
+```bash
+# packer / vagrant provisioner
+pwn setup --profile ${PWN_PROFILE:-full} --yes
+```
+
+---
+
 ## Upgrading
 
 ```bash
-rvm use ruby-4.0.5@pwn
-gem uninstall --all --executables pwn
-gem install --verbose pwn
+gem update pwn         # or: gem uninstall --all --executables pwn && gem install pwn
+pwn setup              # re-doctor - new versions may add capabilities
 ```
 
-or from a checkout:
+From a checkout:
 
 ```bash
-cd /opt/pwn && git pull && rvmsudo rake install
+cd /opt/pwn && git pull && rake install && pwn setup
 ```
 
+---
+
 ## First-run configuration
 
-`pwn` creates `~/.pwn/` on first launch. Add at least one LLM engine to
-`~/.pwn/config.yml` to enable `pwn-ai` — see [Configuration](Configuration.md).
+The first `pwn` launch creates `~/.pwn/` and an **encrypted**
+`~/.pwn/pwn.yaml` template. Add at least one LLM engine key with the
+`pwn-vault` REPL command to enable `pwn-ai` - see
+[Configuration](Configuration.md). `pwn setup` will report the AI-engine
+row as `MISSING` until a key is set.
 
-## Optional external tools
+---
 
-PWN wraps these when present on `$PATH`; none are hard requirements:
+## Programmatic API - `PWN::Setup`
 
-| Tool | Used by |
-|---|---|
-| `nmap` | `PWN::Plugins::NmapIt` |
-| Burp Suite Pro (+ REST API) | `PWN::Plugins::BurpSuite` |
-| `msfconsole` / msfrpcd | `PWN::Plugins::Metasploit` |
-| `chromium` / `google-chrome` | `PWN::Plugins::TransparentBrowser` |
-| `zaproxy` | `PWN::Plugins::Zaproxy` (fallback) |
-| `gqrx` | `PWN::SDR::GQRX` |
-| `adb` | `PWN::Plugins::Android` |
-| `graphviz` (`dot`) | rebuilding these diagrams |
-| `tor` | `PWN::Plugins::Tor` |
+Everything above is a thin CLI over one autoloaded module:
+
+```ruby
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, pkg_manager:, os:, arch: }
+PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
+PWN::Setup.list_profiles
+PWN::Setup.pkg_manager                    # → { key: :apt, install: 'sudo apt-get install -y', sudo: true }
+
+# The data tables - single source of truth, versioned with the gem:
+PWN::Setup::NATIVE_GEMS   # native ext  → { apt:, dnf:, pacman:, brew:, port:, plugins: }
+PWN::Setup::TOOLCHAIN     # external bin → { apt:, dnf:, pacman:, brew:, port:, plugins: }
+PWN::Setup::PROFILES      # profile      → { desc:, gems:, bins: }
+```
+
+Adding a new native dependency or wrapped binary? Add **one row** to the
+appropriate constant in `lib/pwn/setup.rb` - every install path (gem, git,
+Docker, Packer, Vagrant, CI) picks it up automatically.
+
+---
 
 ## Verify
 
 ```ruby
-pwn[v0.5.616]:001 >>> PWN::Plugins.constants.count   # => 66
-pwn[v0.5.616]:002 >>> PWN::SAST.constants.count      # => 48
-pwn[v0.5.616]:003 >>> pwn-ai                         # launches agent TUI
+pwn[v0.5.628]:001 >>> PWN::Setup.check[:ok]          # => true
+pwn[v0.5.628]:002 >>> PWN::Plugins.constants.count   # => 66
+pwn[v0.5.628]:003 >>> PWN::SAST.constants.count      # => 48
+pwn[v0.5.628]:004 >>> pwn-ai                         # launches agent TUI
 ```
 
 **Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md)

data/documentation/Metasploit.md

@@ -1,20 +1,23 @@
 # `PWN::Plugins::Metasploit`
 
-RPC client for `msfrpcd` — search modules, set options, run exploits, interact
+RPC client for `msfrpcd` - search modules, set options, run exploits, interact
 with sessions, all from Ruby.
 
+> **Install:** `pwn setup --profile exploit` - metasploit-framework ·
+> sqlmap. See [Installation](Installation.md).
+
 ## Configure
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml  (edit via `pwn-vault`)
 metasploit:
   host: 127.0.0.1
   port: 55553
   user: msf
-  pass: …
+  pass: ...
 ```
 
-Start the daemon: `msfrpcd -U msf -P … -a 127.0.0.1 -p 55553 -S`
+Start the daemon: `msfrpcd -U msf -P ... -a 127.0.0.1 -p 55553 -S`
 
 ## Use