pwn 0.5.617 → 0.5.620

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb16e051629252943b2df67c661ca49455cd5dfd4acfbde1620e75135f858c42
-  data.tar.gz: 036cb463b3cd848926f88c60be3f885e5e9b4f738534ac036918d118d18ec893
+  metadata.gz: d7b52a560de426b6b9c99fa2716b8e93a948e66088e0e1ae78d28f8633417cea
+  data.tar.gz: f94969b76a9ad4b856a9b5db25647f41d57f600f0c331ebde29c24b35ab59cd1
 SHA512:
-  metadata.gz: d76d992d344b3a2016819f772e7e304fc437d42df677b85b67f33418c988f6436385eefbb6509cbe1d1436c9df585a30f2f44189b00134792160f420af77e81c
-  data.tar.gz: 34cdfc754bd3801071a8967b672924764c5d8b894fb13a6bd74dc43f10d930aee94cb781e5c9812b6b00b14b83fbfa34cbcbbcf45d4c6c2332c800b8fe322fe5
+  metadata.gz: dcd6287345b8f7230aeeeddc8a5d8de97d4000ae6bddecd77b4b2957f8ddf480de5c9ba8ba6a96a9fcf77f64a30f0b3d9a41219ad15512deab556c5b7e60c360
+  data.tar.gz: 92b3f2b90679984a47ed9cff3e1440100803e4220fc6f78eac386bd5cd125f24acbdd7b44504c20f783ba653895726495a69b7ce5d9cd5fd883a98cb67a11ef9

data/Gemfile

@@ -50,7 +50,7 @@ gem 'libusb', '0.7.2'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
 gem 'mcp', '0.23.0'
-gem 'meshtastic', '0.0.167'
+gem 'meshtastic', '0.0.169'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.24.1'
 gem 'msfrpc-client', '1.1.2'
@@ -81,7 +81,7 @@ gem 'rmagick', '7.0.5'
 gem 'rqrcode', '3.2.0'
 gem 'rspec', '3.13.2'
 gem 'rtesseract', '3.1.4'
-gem 'rubocop', '1.88.1'
+gem 'rubocop', '1.88.2'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
 gem 'ruby-audio', '1.6.1'

data/README.md

@@ -6,7 +6,7 @@
   * [What is PWN](#what-is-pwn)
   * [Why PWN](#why-pwn)
   * [How PWN Works](#how-pwn-works)
-- [[Local PWN Wiki](documentation/Home.md)
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [General Usage](#general-usage)
 - [Call to Arms](#call-to-arms)
@@ -14,79 +14,92 @@
 - [Keep Us Caffeinated](#keep-us-caffeinated)
 - [0x004D65726368](#0x004d65726368)
 
+---
+
 ### **Intro** ###
 
 #### **What is PWN** ####
 
-PWN (Pronounced /pōn/ or pone), is a powerful open-source offensive cybersecurity automation framework and continuous security integration platform. It enables security researchers, red teamers, penetration testers, and vulnerability researchers to rapidly discover zero-days, automate exploitation, perform advanced web application testing, conduct source code analysis (SAST), orchestrate infrastructure reconnaissance, and execute AI-augmented autonomous security operations.
+PWN (pronounced /pōn/ — *pone*) is an open-source **offensive-security
+automation framework** and **continuous-security-integration** platform.
+It gives security researchers, red teamers, penetration testers and
+vulnerability researchers a single, scriptable Ruby surface over the entire
+offensive toolchain — from OSINT and network discovery, through web / cloud /
+hardware / radio exploitation, to reporting and disclosure — and puts a
+**self-improving, tool-calling, multi-agent AI** on top of it.
 
-PWN stands on the shoulders of security giants, providing over **66** production-grade plugins, full LLM integration with tool-calling agents, persistent memory, reusable skills, session/cron management, and a highly interactive REPL for prototyping and driving complex security workflows. All core automation primitives are open to promote trust, peer review, and collaborative innovation in adversarial security.
+**In numbers:** 66 `PWN::Plugins` · 48 `PWN::SAST` rules · 90 `PWN::AWS`
+service wrappers · 21 `PWN::WWW` site drivers · 52 `bin/pwn_*` CLI drivers ·
+5 LLM engines · 10 agent toolsets · 45+ LLM-callable tools.
 
-**See the full [PWN Wiki](documentation/Home.md) for detailed guides.**
+Full page: [What is PWN](documentation/What-is-PWN.md)
 
 #### **Why PWN** ####
 
-In cybersecurity, where proprietary black-box tools dominate and threats evolve daily, an open framework for core security primitives, vulnerability research, exploitation techniques, and intelligent automation is essential. PWN ensures foundational modules remain transparent and auditable while providing seamless bridges to commercial and open security tools (e.g. Burp Suite Professional, Metasploit, Nmap, Nessus, and multiple LLMs).
-
-Broad collaboration accelerates zero-day discovery, reliable exploit development, continuous vulnerability management in CI/CD pipelines, and the creation of reusable AI-driven security skills. PWN makes advanced red team and vuln research capabilities accessible and extensible to all.
+Offensive security is a *toolchain problem*. PWN's bet is that the right
+abstraction is **plain Ruby methods with a uniform `opts = {}` signature**,
+exposed simultaneously to a human in a REPL, an LLM in a tool-calling loop, a
+shell script in CI, and a cron job at 3 am — all open-source and auditable,
+which matters when the caller is autonomous.
 
-See [Why PWN](documentation/Why-PWN.md) in the wiki.
+Full page: [Why PWN](documentation/Why-PWN.md)
 
 #### **How PWN Works** ####
 
-#### **PWN AI Feedback Learning Loop (Self-Improving Agent)**
-
-The core of pwn-ai is a closed feedback loop for autonomous improvement:
+Five layers, edges only ever go down:
 
-![PWN AI Feedback Learning Loop](documentation/diagrams/pwn-ai-feedback-learning-loop.svg)
+![PWN Overall Architecture](documentation/diagrams/overall-pwn-architecture.svg)
 
-See full details in [Skills, Memory & Learning](documentation/Skills-Memory-Learning.md) and the [Diagrams](documentation/Diagrams.md) wiki page.
+The AI layer closes a **self-improvement loop** on every turn — Metrics +
+Learning + **Mistakes** (introspection / negative feedback) joined with
+Snapshot + Drift + Intel + RF (extrospection) via `extro_correlate`, so the
+agent knows whether a failure was *its* fault or *the world* changed —
+**and does not repeat the same mistake twice**:
 
+![pwn-ai Feedback Learning Loop](documentation/diagrams/pwn-ai-feedback-learning-loop.svg)
 
-PWN is structured as a Ruby gem with a rich namespace:
+Failures are fingerprinted cross-session (`~/.pwn/mistakes.json`), tagged
+`[REPEATING]` / `[REGRESSED]`, and their **fix** is handed straight back inline
+on the next recurrence:
 
-- `PWN::Plugins::*` — **66+** specialized modules ([BurpSuite](documentation/BurpSuite.md) [preferred for web proxying/scanning], [Zaproxy](documentation/Plugins.md) [fallback], [Metasploit](documentation/Plugins.md), [NmapIt](documentation/NmapIt.md), [TransparentBrowser](documentation/Transparent-Browser.md), Shodan, NessusCloud, NexposeVulnScan, Fuzz, SAST engines, Android analysis, SDR/GQRX, Blockchain, Bounty platforms like HackerOne, hardware interfaces, OCR, packet crafting, etc.).
-- `PWN::AI::*` — Multi-provider LLM clients (OpenAI, Anthropic, Gemini, [Grok OAuth device flow](documentation/AI-Integration.md), Ollama) and autonomous `PWN::AI::Agent` with tool-calling harness (`pwn_eval` for full PWN namespace, shell execution, skills, memory recall/remember, learning loops).
-- `PWN::SAST` — Static application security testing and test case generation. See [SAST Wiki](documentation/SAST.md).
-- `PWN::Reports` — Automated reporting from scans, agents, and findings. See [Reporting](documentation/Reporting.md).
-- `PWN::Memory / Sessions / Cron / Skills / Config` — Persistent facts, conversation sessions, scheduled autonomous tasks, reusable markdown skills (distillable from successful workflows), and environment management. See [Skills, Memory & Learning](documentation/Skills-Memory-Learning.md).
-- `PWN::Driver` — Framework for building custom security automation packages ("drivers"). See [Drivers](documentation/Drivers.md).
+![Mistakes Negative-Feedback Loop](documentation/diagrams/mistakes-negative-feedback.svg)
 
-The **pwn REPL** (launched via the `pwn` command) is the primary interface: a Pry-powered interactive shell with the entire `PWN` namespace pre-loaded. It supports rapid prototyping, direct execution of any plugin method, and custom commands.
+And **Swarm** runs multiple personas — each a full tool-calling agent,
+optionally on a *different* LLM engine — over a shared append-only bus:
 
-**Particularly powerful is the `pwn-ai` command** inside the REPL:
-- Activates an autonomous AI agent TUI with multi-line input support (use SHIFT+ENTER to insert newlines; ENTER submits the full prompt).
-- Full awareness of PWN plugins, skills (`~/.pwn/skills`), memory, sessions, and cron.
-- Leverages LLM tool-calling to execute PWN methods (e.g., `PWN::Plugins::BurpSuite`, `PWN::Plugins::NmapIt`, `PWN::Plugins::TransparentBrowser`, `PWN::SAST`, `PWN::Reports`), shell commands, and orchestrate end-to-end tasks.
-- Supports self-improvement via `PWN::AI::Agent::Learning` / Metrics (records per-tool success/duration, distills skills from outcomes).
-- Example instruction: "Use NmapIt to scan target.example.com for open ports, then TransparentBrowser to spider the web app, run SAST analysis if source is available, proxy via BurpSuite, and generate a vulnerability report with PWN::Reports."
-- Additional REPL commands: `pwn-asm` (assembly prototyping with multiline), `pwn-ai-memory`, `pwn-ai-sessions`, `pwn-ai-cron`, `pwn-ai-delegate`, `welcome-banner`, etc.
-- Easily prototype and roll out custom "drivers" (see `/opt/pwn/bin/` examples).
+![Swarm Multi-Agent](documentation/diagrams/swarm-multi-agent.svg)
 
-Mix and match plugins, invoke via the REPL or `pwn-ai` agent, record/replay sessions, schedule autonomous jobs, and generate reports. PWN is designed for both interactive red teaming and headless/CI automation.
+Full pages: [How PWN Works](documentation/How-PWN-Works.md) ·
+[All 27 Data-Flow Diagrams](documentation/Diagrams.md)
 
-Here are some [example drivers](https://github.com/0dayInc/pwn/tree/master/bin) distributed with PWN.
+---
 
-#### **Local PWN Wiki** ####
+### **Documentation** ###
 
-A full local wiki has been generated in this checkout:
+The complete wiki lives in this repo at **[`documentation/Home.md`](documentation/Home.md)**.
 
-**`/opt/pwn/documentation/Home.md`**
+| Start Here | Entry Points | AI Subsystem | Capabilities |
+|---|---|---|---|
+| [What is PWN](documentation/What-is-PWN.md) | [`pwn` REPL](documentation/pwn-REPL.md) | [AI / LLM Integration](documentation/AI-Integration.md) | [Plugins (66)](documentation/Plugins.md) |
+| [Why PWN](documentation/Why-PWN.md) | [`pwn-ai` Agent](documentation/pwn-ai-Agent.md) | [Agent Tool Registry](documentation/Agent-Tool-Registry.md) | [SAST (48)](documentation/SAST.md) |
+| [How PWN Works](documentation/How-PWN-Works.md) | [CLI Drivers (52)](documentation/CLI-Drivers.md) | [Memory · Skills · Learning](documentation/Skills-Memory-Learning.md) | [AWS (90)](documentation/AWS.md) |
+| [Installation](documentation/Installation.md) | [Build a Driver](documentation/Drivers.md) | [Mistakes (neg-feedback)](documentation/Mistakes.md) | [WWW (21)](documentation/WWW.md) |
+| [General Usage](documentation/General-PWN-Usage.md) | | [Extrospection](documentation/Extrospection.md) | [SDR / Radio](documentation/SDR.md) |
+| [Configuration](documentation/Configuration.md) | | [Swarm (multi-agent)](documentation/Swarm.md) | [Hardware](documentation/Hardware.md) |
+| [Configuration](documentation/Configuration.md) | | [Sessions](documentation/Sessions.md) · [Cron](documentation/Cron.md) | [Reports](documentation/Reporting.md) |
+| [`~/.pwn/` Persistence](documentation/Persistence.md) | | | [BurpSuite](documentation/BurpSuite.md) · [NmapIt](documentation/NmapIt.md) |
+| **[All Diagrams](documentation/Diagrams.md)** | | | [Metasploit](documentation/Metasploit.md) · [Fuzzing](documentation/Fuzzing.md) |
+| [Troubleshooting](documentation/Troubleshooting.md) | | | [Hardware](documentation/Hardware.md) · [Blockchain](documentation/Blockchain.md) |
+| [Contributing](documentation/Contributing.md) | | | [Bounty](documentation/Bounty.md) · [FFI](documentation/FFI.md) · [Banner](documentation/Banner.md) |
 
-- [Home](documentation/Home.md)
-- [What is PWN](documentation/What-is-PWN.md)
-- [Installation](documentation/Installation.md)
-- [pwn-ai Agent](documentation/pwn-ai-Agent.md)
-- [Plugins](documentation/Plugins.md)
-- [AI Integration](documentation/AI-Integration.md)
-- [Troubleshooting](documentation/Troubleshooting.md)
-- ...and many more
+Rebuild every SVG from its Graphviz source:
+`cd documentation/diagrams && ./build.sh`
 
-Run `cat /opt/pwn/documentation/Home.md` or open in your editor for the complete local documentation.
+---
 
 ### **Installation** ###
 
-Tested on Debian-Based Linux Distros & OSX leveraging Ruby via RVM.
+Tested on Debian-based Linux & macOS, Ruby via RVM.
 
 ```
 $ cd /opt
@@ -95,20 +108,23 @@ $ cd /opt/pwn
 $ ./install.sh
 $ ./install.sh ruby-gem
 $ pwn
-pwn[v0.5.617]:001 >>> PWN.help
+pwn[v0.5.616]:001 >>> PWN.help
 ```
 
 [![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
 
-See the dedicated [Installation Wiki](documentation/Installation.md) for more options.
+Full page: [Installation](documentation/Installation.md) ·
+[Configuration](documentation/Configuration.md)
 
-### **General Usage** ###
+---
 
-[General Usage Quick-Start](https://github.com/0dayinc/pwn/wiki/General-PWN-Usage)
+### **General Usage** ###
 
-Detailed local guide: [General PWN Usage](documentation/General-PWN-Usage.md)
+[General Usage Quick-Start](https://github.com/0dayinc/pwn/wiki/General-PWN-Usage) ·
+local: [General PWN Usage](documentation/General-PWN-Usage.md)
 
-It is strongly recommended to update PWN frequently as new capabilities (plugins, AI agents, skills, zero-day tooling) are released regularly:
+Update PWN frequently — new plugins, agent tools, skills and zero-day tooling
+land regularly:
 
 ```
 $ rvm list gemsets
@@ -116,70 +132,72 @@ $ rvm use ruby-4.0.5@pwn
 $ gem uninstall --all --executables pwn
 $ gem install --verbose pwn
 $ pwn
-pwn[v0.5.617]:001 >>> PWN.help
+pwn[v0.5.616]:001 >>> PWN.help
 ```
 
-If using a multi-user install of RVM:
+If using a multi-user RVM install:
 
 ```
-$ rvm list gemsets
 $ rvm use ruby-4.0.5@pwn
 $ rvmsudo gem uninstall --all --executables pwn
 $ rvmsudo gem install --verbose pwn
-$ pwn
-pwn[v0.5.617]:001 >>> PWN.help
 ```
 
-**Inside the pwn REPL (the heart of PWN):**
-- Full access to every PWN class and plugin.
-- `PWN.help` — list all top-level modules.
-- `pwn-ai` — launch the autonomous AI agent (highly recommended for complex tasks). Once active you can issue natural language instructions that leverage PWN's full power.
-- Example flow:
-  ``` 
-  pwn[v0.5.617]:001 >>> pwn-ai
-  [*] pwn-ai agent TUI activated...
-  > Perform active scan of https://target.example.com using preferred tooling, then analyze findings with PWN modules and produce a report.
-  ```
-- Other REPL helpers: `pwn-asm`, memory/session/cron management commands, etc.
-- Exit AI mode with `back`; use full Ruby/PWN expressions at any time.
-
-**Headless / CI-CD one-shot (`pwn --ai`):**
-Skip the TUI entirely and submit a single pwn-ai request from the shell — ideal for quick lookups, scripting, or CI/CD pipelines. The final answer is written to STDOUT (pipeable); live tool-call activity streams to STDERR.
+**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 summarise HIGH findings' > findings.txt
 ```
 
-PWN periodically upgrades to the latest version of Ruby (reflected in `/opt/pwn/.ruby-version`). The easiest way to upgrade Ruby + pwn from a previous installation:
+PWN periodically upgrades to the latest Ruby (`/opt/pwn/.ruby-version`).
+Easiest upgrade of Ruby + pwn from a previous install:
 
 ```
 $ /opt/pwn/vagrant/provisioners/pwn.sh
 ```
 
-This updates Ruby, recreates the pwn gemset, etc. Note that older Ruby versions can only use pwn gems compatible with that Ruby.
+---
 
 ### **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](mailto:support@0dayinc.com). This accelerates interoperability and zero-day research tooling. See our [How to Contribute](https://github.com/0dayInc/pwn/blob/master/CONTRIBUTING.md) and the growing skills system for ways to extend the AI agent.
+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](mailto:support@0dayinc.com). See
+[CONTRIBUTING.md](https://github.com/0dayInc/pwn/blob/master/CONTRIBUTING.md)
+and the local [Contributing](documentation/Contributing.md) page.
 
-See also the wiki page on [Contributing](documentation/Contributing.md).
+---
 
 ### **Module Documentation** ###
 
-**Primary Documentation:** Browse the embedded local wiki — start at [/opt/pwn/documentation/Home.md](documentation/Home.md).
+**Primary:** [`documentation/Home.md`](documentation/Home.md) — the full local
+wiki with 30+ pages and 26 SVG data-flow diagrams.
 
-Additional documentation on using PWN can be found on [RubyGems.org](https://www.rubydoc.info/gems/pwn). Explore the source under `lib/pwn/plugins/`, `lib/pwn/ai/`, and `PWN::` constants directly in the REPL.
+**API reference:** [rubydoc.info/gems/pwn](https://www.rubydoc.info/gems/pwn),
+or in-REPL: `PWN::Plugins::BurpSuite.help`, `show-source`, `ls`.
 
-Key wiki pages:
-- [Plugins](documentation/Plugins.md)
-- [Burp Suite](documentation/BurpSuite.md)
-- [pwn-ai Agent](documentation/pwn-ai-Agent.md)
-- [SAST](documentation/SAST.md)
-- [AI Integration](documentation/AI-Integration.md)
+Highlights:
+[Plugins](documentation/Plugins.md) ·
+[BurpSuite](documentation/BurpSuite.md) ·
+[Transparent-Browser](documentation/Transparent-Browser.md) ·
+[pwn-ai Agent](documentation/pwn-ai-Agent.md) ·
+[Swarm](documentation/Swarm.md) ·
+[Extrospection](documentation/Extrospection.md) ·
+[SAST](documentation/SAST.md) ·
+[AI Integration](documentation/AI-Integration.md)
 
-I hope you enjoy PWN and remember... ensure you always have permission prior to carrying out any sort of security testing or hacktivities. Now — go pwn all the things (responsibly)!
+I hope you enjoy PWN — and remember: **always have permission** before any
+security testing. Now go pwn all the things (responsibly)!
 
+---
 
 ### **Keep Us Caffeinated** ###
 If you've found this project useful and you're interested in supporting our efforts, we invite you to take a brief moment to keep us caffeinated:

data/bin/pwn_gqrx_scanner

@@ -76,7 +76,7 @@ PWN::Driver::Parser.new do |options|
     opts[:fft_scan] = f
   end
 
-  options.on('-SRATE', '--sample-rate=RATE', '<Optional --fft-scan - Visible span/sample_rate in Hz (default 1_000_000)>') do |s|
+  options.on('--sample-rate=RATE', '<Optional --fft-scan - Visible span/sample_rate in Hz (default 1_000_000). NOTE: no short flag; -S is --strength-lock>') do |s|
     opts[:sample_rate] = s
   end
 
@@ -84,11 +84,11 @@ PWN::Driver::Parser.new do |options|
     opts[:nfft] = n
   end
 
-  options.on('-AINT', '--avg=INT', '<Optional --fft-scan - FFT averages (default 2)>') do |a|
+  options.on('--avg=INT', '<Optional --fft-scan - FFT averages (default 8). NOTE: no short flag; -A is --audio-gain>') do |a|
     opts[:avg] = a
   end
 
-  options.on('-CSEC', '--capture-secs=SEC', '<Optional --fft-scan - Capture seconds per chunk (default 0.03)>') do |c|
+  options.on('-CSEC', '--capture-secs=SEC', '<Optional --fft-scan - Capture seconds per chunk (default 0.10)>') do |c|
     opts[:capture_secs] = c
   end
 
@@ -99,6 +99,14 @@ PWN::Driver::Parser.new do |options|
   options.on('-ODB', '--strength-offset-db=FLOAT', '<Optional - Power offset in dB (default 0.0)>') do |o|
     opts[:strength_offset_db] = o
   end
+
+  options.on('--min-snr-db=FLOAT', '<Optional --fft-scan - Minimum SNR (dB above per-chunk noise floor) to report a signal (default 12.0)>') do |m|
+    opts[:min_snr_db] = m
+  end
+
+  options.on('--min-bw-ratio=FLOAT', '<Optional --fft-scan - Reject FFT peaks narrower than RATIO * band-plan bandwidth as spurs (default 0.30)>') do |r|
+    opts[:min_bw_ratio] = r
+  end
 end.parse!
 
 begin
@@ -178,13 +186,17 @@ begin
   sample_rate = sample_rate.to_i
   nfft = opts[:nfft] || 2048
   nfft = nfft.to_i
-  avgv = opts[:avg] || 2
+  avgv = opts[:avg] || 8
   avgv = avgv.to_i
-  capture_secs = opts[:capture_secs] || 0.03
+  capture_secs = opts[:capture_secs] || 0.10
   capture_secs = capture_secs.to_f
   keep_spectrum = opts[:keep_spectrum] ? true : false
   strength_offset_db = opts[:strength_offset_db]
   strength_offset_db = strength_offset_db.to_f unless strength_offset_db.nil?
+  min_snr_db = opts[:min_snr_db]
+  min_snr_db = min_snr_db.to_f unless min_snr_db.nil?
+  min_bw_ratio = opts[:min_bw_ratio]
+  min_bw_ratio = min_bw_ratio.to_f unless min_bw_ratio.nil?
 
   if fft_scan
     puts '[*] --fft-scan requested: using fast FFT panoramic mode (#fast_scan_range)'
@@ -198,6 +210,14 @@ begin
       strength_lock: strength_lock,
       keep_spectrum: keep_spectrum,
       strength_offset_db: strength_offset_db,
+      min_snr_db: min_snr_db,
+      precision: precision,
+      min_bw_ratio: min_bw_ratio,
+      demodulator_mode: demodulator_mode,
+      bandwidth: bandwidth,
+      squelch: squelch,
+      decoder: decoder,
+      location: location,
       scan_log: scan_log
     )
     puts "FFT Scan complete: #{fast_resp[:total]} signals found."

data/documentation/AI-Integration.md

@@ -1,36 +1,52 @@
-# AI & LLM Integration
+# AI / LLM Integration — `PWN::AI`
 
-PWN integrates deeply with multiple LLMs for both interactive and autonomous operation.
+One agent loop, five interchangeable engines. Swap providers by changing one
+line in `~/.pwn/config.yml`; the tool-calling contract is normalised so the
+agent code never cares which model is behind it.
 
-## Supported Providers
+![Multi-provider integration](diagrams/ai-integration-tool-calling.svg)
 
-- OpenAI
-- Anthropic
-- Google Gemini
-- xAI Grok (full OAuth device flow support, public client)
-- Ollama (local)
-- Others via extensible client design
+## Supported engines
 
-## Primary Entry Points
+| Engine | Client | Auth | Notes |
+|---|---|---|---|
+| `openai` | `PWN::AI::OpenAI` | `key:` | function-calling native |
+| `anthropic` | `PWN::AI::Anthropic` | `key:` | tool-use native |
+| `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) — see skill `xai_grok_oauth_device_flow` |
+| `gemini` | `PWN::AI::Gemini` | `key:` | function-calling native |
+| `ollama` | `PWN::AI::Ollama` | none | local, `base_url:` + `model:` |
 
-- `PWN::AI::*` (OpenAI, Anthropic, Grok, etc.)
-- `PWN::AI::Agent` — the autonomous tool-calling harness
-- `pwn-ai` command inside REPL launches the TUI
+## Selecting an engine
 
-## Tool Calling
+```yaml
+# ~/.pwn/config.yml
+ai:
+  engine: grok
+  grok:
+    oauth: true   # first run opens https://accounts.x.ai/… device page
+```
 
-The agent can call:
-- `pwn_eval` (full PWN namespace + Ruby)
-- `shell`
-- skills
-- memory (recall/remember)
-- learning & metrics
+```ruby
+# at runtime
+PWN::Env[:ai][:engine] = :ollama
+```
 
-OAuth for Grok is configured via `PWN::Config` and follows modern device-code flows (no client secrets).
+## Direct client use (no agent)
 
-See:
-- [pwn-ai Agent](pwn-ai-Agent.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
-- `lib/pwn/ai/` in source
+```ruby
+resp = PWN::AI::Anthropic.chat(
+  messages: [{ role: 'user', content: 'Explain CVE-2024-1234 in one line' }]
+)
+puts resp[:content]
+```
 
-[[Diagrams]]
+## Model diversity in Swarm
+
+Because each persona in [`agents.yml`](Swarm.md) can override `engine:`, an
+`agent_debate` can literally pit Claude against Grok against a local Llama —
+real antagonism, not one model role-playing three voices.
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
+[Agent Tool Registry](Agent-Tool-Registry.md) · [Swarm](Swarm.md)
+
+[← Home](Home.md)

data/documentation/AWS.md

@@ -0,0 +1,57 @@
+# `PWN::AWS` — Cloud Security (90 service wrappers)
+
+One thin module per AWS service, each wrapping the official `aws-sdk-*` gem
+with the PWN `opts = {}` convention so they compose in the REPL and in
+`pwn_eval`.
+
+![AWS cloud security](diagrams/aws-cloud-security.svg)
+
+## Credentials
+
+Standard AWS SDK chain: `~/.aws/credentials` profile, env vars
+(`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`), or
+instance profile. Optionally pin in `~/.pwn/config.yml` under `aws:`.
+
+## Quick enumeration
+
+```ruby
+PWN::AWS::STS.get_caller_identity
+PWN::AWS::IAM.list_users
+PWN::AWS::EC2.describe_instances(region: 'us-east-1')
+PWN::AWS::S3.list_buckets
+PWN::AWS::Lambda.list_functions
+```
+
+CLI: `pwn_aws_describe_resources -r us-east-1 -o out/`
+
+## Service groups
+
+| Group | Modules |
+|---|---|
+| Identity | `IAM` `STS` `CognitoIdentity` `CognitoIdentityProvider` `CognitoSync` `DirectoryService` |
+| Compute | `EC2` `ECS` `ECR` `Lambda` `LambdaPreview` `Batch` `Lightsail` `ElasticBeanstalk` `AutoScaling` `ApplicationAutoScaling` `AppStream` |
+| Storage | `S3` `Glacier` `EFS` `StorageGateway` `Snowball` |
+| Data | `DynamoDB` `DynamoDBStreams` `RDS` `Redshift` `ElastiCache` `SimpleDB` `ElasticsearchService` |
+| Network | `Route53` `Route53Domains` `ElasticLoadBalancing` `ElasticLoadBalancingV2` `APIGateway` `CloudFront` `DirectConnect` `WAF` `WAFRegional` `Shield` |
+| Crypto | `KMS` `CloudHSM` `ACM` |
+| Ops / Logs | `CloudTrail` `CloudWatch` `CloudWatchLogs` `CloudWatchEvents` `ConfigService` `SSM` `Health` `Inspector` `XRay` |
+| Dev | `CodeBuild` `CodeCommit` `CodeDeploy` `CodePipeline` |
+| Messaging | `SNS` `SQS` `SES` `Pinpoint` `Kinesis` `KinesisAnalytics` `Firehose` |
+| ML / Media | `Rekognition` `Polly` `MachineLearning` `Lex` `ElasticTranscoder` |
+| Infra | `CloudFormation` `CloudSearch` `CloudSearchDomain` `OpsWorks` `OpsWorksCM` `ServiceCatalog` `DataPipleline` `EMR` `SWF` `States` |
+| IoT / Other | `IoT` `IoTDataPlane` `DeviceFarm` `GameLift` `Workspaces` `Support` `Budgets` `ImportExport` `SMS` `DatabaseMigrationService` `ApplicationDiscoveryService` `MarketplaceCommerceAnalytics` `MarketplaceMetering` |
+
+## Offensive patterns
+
+- **Enumerate** → `IAM` policies, `EC2` userdata, `Lambda` env vars, `S3`
+  bucket ACLs, `SSM` parameters.
+- **Misconfig** → public `S3`, wildcard `IAM` actions, unencrypted `RDS`,
+  missing `CloudTrail`.
+- **Escalate** → `iam:PassRole` + `lambda:Invoke`, `ssm:SendCommand`,
+  `ec2:RunInstances` with instance profile.
+- **Persist** → new access key, Lambda backdoor, EC2 userdata.
+
+Record everything with `extro_observe(source: 'aws', …)` so
+[Extrospection](Extrospection.md) can correlate later.
+
+[← Home](Home.md)

data/documentation/Agent-Tool-Registry.md

@@ -0,0 +1,56 @@
+# Agent Tool Registry
+
+`PWN::AI::Agent::Registry` (`lib/pwn/ai/agent/registry.rb`) collects every
+LLM-callable function into named **toolsets**. A persona is granted a subset of
+toolsets; the JSON-Schema for each tool is what the model actually sees.
+
+![Tool registry](diagrams/agent-tool-registry.svg)
+
+## Toolsets → Tools  (10 toolsets · 52 tools)
+
+| Toolset | Tools | Backed by |
+|---|---|---|
+| `terminal` | `shell` | `Open3.capture3` on the host |
+| `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
+| `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
+| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` | `~/.pwn/skills/*.md` |
+| `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_reflect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** | `PWN::AI::Agent::Learning` + `PWN::AI::Agent::Mistakes` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` |
+| `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
+| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` → `~/.pwn/extrospection.json` |
+| `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
+| `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
+
+## Adding a tool
+
+```ruby
+# lib/pwn/ai/agent/tools/my_thing.rb
+PWN::AI::Agent::Registry.register(
+  name: 'my_thing_do',
+  toolset: 'my_thing',
+  description: 'One-line summary the LLM will read.',
+  parameters: {
+    type: 'object',
+    properties: { target: { type: 'string' } },
+    required: ['target']
+  }
+) do |args|
+  PWN::Plugins::MyThing.do(target: args['target'])
+end
+```
+
+Drop the file in `lib/pwn/ai/agent/tools/`, it's auto-loaded on next launch.
+
+## Restricting a persona
+
+```yaml
+# ~/.pwn/agents.yml
+recon:
+  role: "Passive OSINT only. Never touch the target directly."
+  toolsets: [terminal, pwn, memory, extrospection]   # no swarm, no cron
+  engine: ollama
+```
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Mistakes](Mistakes.md) · [Swarm](Swarm.md)
+
+[← Home](Home.md)

data/documentation/Banner.md

@@ -0,0 +1,17 @@
+# `PWN::Banner` — Startup Art
+
+15 ANSI banners; one is picked at random every time the REPL starts. Purely
+cosmetic, entirely necessary.
+
+`Anon · Bubble · Cheshire · CodeCave · DontPanic · ForkBomb · FSociety ·
+JmpEsp · Matrix · Ninja · OffTheAir · Pirate · Radare2 · Radare2AI ·
+WhiteRabbit`
+
+```ruby
+puts PWN::Banner::Matrix.get
+welcome-banner          # REPL command: redraw a random one
+```
+
+Add your own: drop a module in `lib/pwn/banner/` implementing `self.get`.
+
+[← Home](Home.md)

data/documentation/Blockchain.md

@@ -0,0 +1,18 @@
+# `PWN::Blockchain` — BTC · ETH
+
+Lightweight helpers for on-chain recon and wallet interaction.
+Source: `lib/pwn/blockchain/*.rb`.
+
+| Module | Purpose |
+|---|---|
+| `PWN::Blockchain::BTC` | Address balance/UTXO lookup, tx broadcast, key helpers |
+| `PWN::Blockchain::ETH` | Address balance, contract call, event log query |
+
+Also exposed to the agent via `PWN::AI::Agent::BTC` for wallet-aware prompts.
+
+```ruby
+PWN::Blockchain::BTC.balance(address: 'bc1q…')
+PWN::Blockchain::ETH.call(contract: '0x…', method: 'owner()')
+```
+
+[← Home](Home.md)

data/documentation/Bounty.md

@@ -0,0 +1,21 @@
+# `PWN::Bounty` — Bug-Bounty Lifecycle Tooling
+
+| Module | Purpose |
+|---|---|
+| `PWN::Bounty::LifecycleAuthzReplay` | Record an authenticated browser session, then replay every request under a *different* principal to surface horizontal/vertical authz bugs |
+
+Pairs naturally with:
+
+- [`PWN::WWW::HackerOne`](WWW.md) / `BugCrowd` / `Synack` — programme navigation
+- `PWN::Plugins::HackerOne` — submissions API
+- [`PWN::Plugins::BurpSuite`](BurpSuite.md) — capture the session to replay
+
+```ruby
+PWN::Bounty::LifecycleAuthzReplay.start(
+  har_path: 'admin_session.har',
+  replay_as: { cookie: 'session=LOW_PRIV_TOKEN' },
+  proxy: 'http://127.0.0.1:8080'
+)
+```
+
+[← Home](Home.md) · [WWW](WWW.md)