pwn 0.5.615 → 0.5.617

data/documentation/Home.md

@@ -1,51 +1,78 @@
-# PWN Wiki
-
-Welcome to the PWN (pronounced /pōn/) Security Automation Framework Wiki.
-
-PWN is an open-source offensive cybersecurity automation framework and continuous security integration platform. It enables researchers, red teamers, penetration testers, and vulnerability researchers to discover zero-days, automate exploitation, perform web application testing, conduct SAST, orchestrate reconnaissance, and execute AI-augmented autonomous operations.
-
-## Visual Overview (Data Flow Diagrams)
-
-**Start here for visual understanding** — see [Diagrams.md](Diagrams.md) for 18+ SVG DFDs covering:
-
-- AI feedback learning loop & self-improvement
-- REPL prototyping + history → drivers
-- End-to-end penetration testing
-- Network / infrastructure testing
-- Web application testing (Burp preferred)
-- Code scanning / SAST
-- Fuzzing
-- Reverse engineering
-- Zero-day research flow
-- Overall architecture
-- Tool calling, plugins, memory/skills, reporting, etc.
-
-## Quick Navigation
-
-- [What is PWN](What-is-PWN.md)
-- [Why PWN](Why-PWN.md)
-- [How PWN Works](How-PWN-Works.md)
-- [Installation](Installation.md)
-- [General Usage](General-PWN-Usage.md)
-- [The pwn REPL](pwn-REPL.md)
-- [pwn-ai Autonomous Agent](pwn-ai-Agent.md)
-- [Plugins Overview](Plugins.md)
-- [AI & LLM Integration](AI-Integration.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
-- [SAST](SAST.md)
-- [Reporting](Reporting.md)
-- [Drivers & Custom Automation](Drivers.md)
-- [Diagrams (All SVGs)](Diagrams.md)
-- [Troubleshooting](Troubleshooting.md)
-- [Contributing](Contributing.md)
-
-## Core Commands
-
-Inside the `pwn` REPL:
-- `PWN.help`
-- `pwn-ai` — launch AI agent TUI
-- See full list via `pwn` command help.
-
-**Local Wiki Root:** This wiki lives in `/opt/pwn/documentation/`.
-
-For the latest upstream see the [GitHub Project](https://github.com/0dayInc/pwn) and [rubydoc.info](https://www.rubydoc.info/gems/pwn).
+# 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 · 52 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) | RVM, gem, `./install.sh`, first launch |
+| [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
+| [Configuration](Configuration.md) | `~/.pwn/config.yml` — engines, keys, agent options |
+| **[All Data-Flow Diagrams](Diagrams.md)** | **26 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) | 52 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) | 10 toolsets · 45+ LLM-callable tools |
+| [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection — the self-improvement loop |
+| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · correlate |
+| [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
+| [Sessions](Sessions.md) | Transcript persistence + reflection |
+| [Cron](Cron.md) | Scheduled autonomous jobs |
+
+## 🧩 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 |
+| [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 calls |
+| [Banner](Banner.md) | 15 startup banners |
+
+## 🛠️ Meta
+
+| | |
+|---|---|
+| [`~/.pwn/` Filesystem Map](Persistence.md) | Every file PWN writes and why |
+| [Troubleshooting](Troubleshooting.md) | Common errors and fixes |
+| [Contributing](Contributing.md) | Conventions, RuboCop, spec rules |
+
+---
+
+<sub>Generated by pwn-ai. Edit any `.md` directly; edit any diagram in
+`documentation/diagrams/dot/*.dot` then run `./build.sh`.</sub>

data/documentation/How-PWN-Works.md

@@ -1,60 +1,62 @@
 # How PWN Works
 
-PWN is structured as a Ruby gem with a rich `PWN::` namespace.
-
-## Visual Architecture Overview
-
-See the full set of **[Data Flow Diagrams](Diagrams.md)** (18+ SVGs) for detailed visualization of data flows, including:
-
-![Overall PWN Architecture](diagrams/overall-pwn-architecture.svg)
-
-- [PWN-AI Feedback Learning Loop](diagrams/pwn-ai-feedback-learning-loop.svg) — the core self-improving closed loop
-- [REPL Prototyping](diagrams/pwn-repl-prototyping.svg)
-- [History → Drivers & Skills](diagrams/history-to-drivers.svg)
-- [AI Tool Calling Integration](diagrams/ai-integration-tool-calling.svg)
-- [Plugin Ecosystem](diagrams/plugin-ecosystem.svg)
-- And many more specific workflows (Pen Testing, Web, Fuzzing, SAST, RE, etc.)
-
-## Namespace Overview
-
-| Namespace          | Description |
-|--------------------|-------------|
-| `PWN::Plugins::*`  | 67+ specialized modules (see [Plugins](Plugins.md)) |
-| `PWN::AI::*`       | Multi-provider LLM clients + autonomous `PWN::AI::Agent` |
-| `PWN::SAST`        | Static application security testing + test case generation |
-| `PWN::Reports`     | Automated reporting from scans, agents, findings |
-| `PWN::Memory`      | Persistent facts across sessions |
-| `PWN::Sessions`    | Record / replay conversations and workflows |
-| `PWN::Cron`        | Scheduled autonomous tasks |
-| `PWN::Skills`      | Reusable markdown procedures (distilled from successful runs) |
-| `PWN::Config`      | Environment + credential management |
-| `PWN::Driver`      | Framework for custom security automation packages |
-
-## Primary Interfaces
-
-1. **pwn REPL** — Pry-powered interactive shell (launched via `pwn` command). Full `PWN` namespace pre-loaded.
-2. **pwn-ai** — Autonomous AI agent TUI inside the REPL (highly recommended). Uses tool calling for `pwn_eval`, shell, skills, memory, etc.
-3. **Custom Drivers** — See `/opt/pwn/bin/` examples and [Drivers](Drivers.md).
-
-## LLM Tool Calling
-
-The agent can:
-- Execute any PWN plugin method directly
-- Run shell commands
-- Recall/remember facts
-- Distill new skills from successful workflows
-- Use multiple LLM providers (OpenAI, Anthropic, Gemini, Grok OAuth, Ollama, ...)
-
-Example:
-```
-pwn-ai
-> Use NmapIt to scan target.example.com, spider with TransparentBrowser, proxy via BurpSuite, run SAST if source available, then generate report.
-```
-
-See the Diagrams and:
-- [pwn REPL](pwn-REPL.md)
-- [pwn-ai Agent](pwn-ai-Agent.md)
-- [Plugins](Plugins.md)
-- [AI Integration](AI-Integration.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
+PWN is five layers, each visible in the source tree. Edges only ever go
+**down** one layer (or sideways within a layer), which is why the diagrams
+below have no criss-crossing lines.
 
+![Overall Architecture](diagrams/overall-pwn-architecture.svg)
+
+## L0 — Actors
+
+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/`)
+
+| 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::Cron` | `lib/pwn/cron.rb` | Scheduled jobs → any of the above |
+
+## L2 — AI agent core  (`lib/pwn/ai/agent/`)
+
+| Module | Role |
+|---|---|
+| `Loop` | plan → dispatch tool_calls → observe → repeat until final answer |
+| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** |
+| `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
+| `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / EXTROSPECTION blocks |
+| `Metrics` · `Learning` | **introspection** — how well am I doing? |
+| `Extrospection` | **extrospection** — what does the world look like? |
+| `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/*`)
+
+`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
+the REPL, from `pwn_eval`, or from a driver.
+
+## L4 — Persistence  (`~/.pwn/`)
+
+Everything the framework remembers between processes lives in one directory:
+
+![~/.pwn map](diagrams/persistence-filesystem.svg)
+
+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:
+
+![Self-improvement loop](diagrams/pwn-ai-feedback-learning-loop.svg)
+
+**Next:** [pwn REPL](pwn-REPL.md) · [pwn-ai Agent](pwn-ai-Agent.md)
+
+[← Home](Home.md)

data/documentation/Installation.md

@@ -1,50 +1,75 @@
 # Installation
 
-Tested primarily on Debian-based Linux (including Kali) and macOS using RVM-managed Ruby.
+PWN is tested on **Debian-based Linux** (Kali, Ubuntu) and **macOS**, using
+Ruby via **RVM**.
 
-## Quick Install (Recommended)
+## Quick install (recommended)
 
 ```bash
-$ cd /opt
-$ sudo git clone https://github.com/0dayInc/pwn
-$ cd /opt/pwn
-$ ./install.sh
-$ ./install.sh ruby-gem
-$ pwn
-pwn[v0.5.613]:001 >>> PWN.help
+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
 ```
 
-## Video Guide
-
-[![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
+```text
+pwn[v0.5.616]:001 >>> PWN.help
+```
 
-## Ruby Gem Updates
+## Gem-only install
 
 ```bash
-$ rvm use ruby-4.0.5@pwn
-$ gem uninstall --all --executables pwn
-$ gem install --verbose pwn
+rvm install ruby-4.0.5
+rvm use     ruby-4.0.5@pwn --create
+gem install --verbose pwn
+pwn
 ```
 
-For multi-user RVM use `rvmsudo` instead of `sudo` on gem commands.
+## Upgrading
 
-## Upgrade Path (Ruby + PWN)
+```bash
+rvm use ruby-4.0.5@pwn
+gem uninstall --all --executables pwn
+gem install --verbose pwn
+```
 
-Use the vagrant provisioner or:
+or from a checkout:
 
 ```bash
-$ /opt/pwn/vagrant/provisioners/pwn.sh
+cd /opt/pwn && git pull && rvmsudo rake install
 ```
 
-This rebuilds the gemset when `.ruby-version` advances.
+## 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).
 
-## Requirements
+## Optional external tools
 
-- Ruby (via RVM recommended)
-- Git
-- Build tools (for native extensions)
-- Optional: Burp Suite Pro, Metasploit, etc. for full plugin capability
+PWN wraps these when present on `$PATH`; none are hard requirements:
+
+| 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` |
+
+## 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
+```
 
-See the root [README.md](../README.md) and `install.sh` for latest details.
+**Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md)
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/What-is-PWN.md

@@ -1,34 +1,53 @@
 # What is PWN
 
-PWN (pronounced /pōn/ or "pone") is a powerful open-source **offensive cybersecurity automation framework** and **continuous security integration platform**.
-
-## Core Purpose
-
-- Rapidly discover zero-days
-- Automate exploitation and post-exploitation
-- Perform advanced web application penetration testing
-- Conduct source code analysis (SAST)
-- Orchestrate infrastructure reconnaissance at scale
-- Execute AI-augmented autonomous security operations
-
-## Architecture Highlights
-
-PWN provides over 60 production-grade plugins, full LLM integration with tool-calling agents, persistent memory, reusable skills, session/cron management, and a highly interactive REPL (Pry-powered) for prototyping and driving complex security workflows.
-
-All core automation primitives are open to promote trust, peer review, and collaborative innovation in adversarial security.
-
-## Key Components
-
-- `PWN::Plugins::*` — 66+ specialized modules
-- `PWN::AI::*` — Multi-LLM clients + autonomous agent
-- `PWN::SAST` — Static analysis & test case generation
-- `PWN::Reports` — Automated reporting
-- `PWN::Memory`, `Sessions`, `Cron`, `Skills`, `Config`
-- `PWN::Driver` — Custom automation packages
-
-See:
-- [How PWN Works](How-PWN-Works.md)
-- [Plugins](Plugins.md)
-- [pwn-ai Agent](pwn-ai-Agent.md)
-
-[[Diagrams]]
+**PWN** (pronounced /pōn/ — "pone") is an open-source **offensive-security
+automation framework** and **continuous-security-integration** platform,
+distributed as a Ruby gem.
+
+It gives security researchers, red teamers, bug-bounty hunters and DevSecOps
+engineers a single, scriptable 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 AI agent** on top of it.
+
+## In numbers
+
+| Namespace | Count | What it is |
+|---|---|---|
+| `PWN::Plugins::*` | **66** | Wrappers for external + native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, …) |
+| `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
+| `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
+| `PWN::WWW::*` | **21** | Site-specific browser automations (HackerOne, BugCrowd, Google, LinkedIn, …) |
+| `PWN::SDR::*` | **6** | GQRX, FlipperZero, RFIDler, SonMicro, decoders, band tables |
+| `PWN::AI::*` | **5** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama |
+| `bin/pwn_*` | **52** | Headless CLI drivers for CI/CD |
+| Agent toolsets | **10** | terminal · pwn · memory · skills · sessions · learning · metrics · extrospection · cron · swarm |
+
+## The three ways to use it
+
+1. **`pwn` REPL** — a Pry shell with the whole `PWN::` namespace pre-loaded.
+   Prototype an attack chain interactively, one method call at a time.
+2. **`pwn-ai`** — a natural-language TUI (or `pwn --ai "…"` one-shot) where an
+   LLM plans and executes those same method calls for you, records what
+   worked, and gets better at it.
+3. **`bin/pwn_*` drivers** — thin CLIs over the plugins, for cron and CI/CD.
+
+## What makes it different
+
+- **Everything is Ruby, everything is a method.** No YAML DSLs, no plugins-in-a-
+  black-box. If you can call it in the REPL, the AI agent can call it, a driver
+  can call it, and a cron job can call it.
+- **Closed self-improvement loop.** Metrics + Learning (introspection) and
+  Snapshot + Drift + Intel (extrospection) feed `extro_correlate`, which tells
+  the agent whether a failure was *its* fault or *the world* changed — and
+  writes the lesson back into the prompt for next time.
+- **Native multi-agent.** `PWN::AI::Agent::Swarm` runs personas (each a full
+  tool-calling agent, optionally on a *different* LLM engine) that debate,
+  broadcast and share an append-only bus — no IRC daemon, no external service.
+
+![Overall Architecture](diagrams/overall-pwn-architecture.svg)
+
+**Next:** [Why PWN](Why-PWN.md) · [How PWN Works](How-PWN-Works.md) ·
+[Installation](Installation.md)
+
+[← Home](Home.md)

data/documentation/Why-PWN.md

@@ -1,18 +1,48 @@
 # Why PWN
 
-In cybersecurity, proprietary black-box tools dominate. Threats evolve daily. An **open framework** for core security primitives, vulnerability research, exploitation techniques, and intelligent automation is essential.
+## The problem
 
-## Key Benefits
+Offensive security is a **toolchain problem**. A single engagement touches
+`nmap`, `burp`, `msfconsole`, a headless browser, `adb`, `gqrx`, three cloud
+consoles, a fuzzer, `radare2`, a spreadsheet of findings, and a bug-bounty
+submission form. Each tool has its own config, its own output format, and its
+own idea of what a "target" is. Gluing them together is 80 % of the job — and
+that glue is rewritten, badly, on every engagement.
 
-- **Transparency & Auditability**: Foundational modules remain open.
-- **Extensibility**: Seamless bridges to commercial tools (Burp Suite Professional [preferred], Metasploit, Nmap, Nessus, ZAP, etc.).
-- **Collaboration**: Accelerates zero-day discovery and reliable exploit development.
-- **Continuous Security**: Integrates into CI/CD pipelines.
-- **Reusable Intelligence**: AI skills, persistent memory, learning loops.
-- **Accessibility**: Advanced red team / vuln research capabilities available to all.
+Meanwhile, LLM agents are extraordinary at *planning* attack chains but have no
+reliable, auditable way to *execute* them against a real host.
 
-PWN stands on the shoulders of security giants while keeping the core open and auditable.
+## The design bet
 
-See [How PWN Works](How-PWN-Works.md) for architecture.
+PWN bets that the right abstraction is **plain Ruby methods with a uniform
+`opts = {}` signature**, exposed simultaneously to:
 
-[[Diagrams]]
+- a human in a REPL,
+- an LLM in a tool-calling loop,
+- a shell script in CI,
+- a cron job at 3 am.
+
+Because every capability is a method, the same line of code works in all four
+contexts. Because every method is open-source Ruby, it's auditable — critical
+when the caller is an autonomous agent.
+
+## Why open primitives matter
+
+| Closed / black-box | PWN |
+|---|---|
+| "Trust our scanner" | `cat lib/pwn/sast/sql.rb` — read the regex yourself |
+| Per-seat licence for the glue | MIT-licensed glue; bring your own Burp Pro / Nessus key |
+| Agent output is a PDF | Agent output is a `PWN::Reports` object *and* a distilled skill *and* a memory entry |
+| One vendor's model | Five interchangeable engines; swarm can pit them against each other |
+
+## Why the self-improvement loop matters
+
+A pentest framework that doesn't learn repeats the same dead-end scans forever.
+PWN records **per-tool success rate**, **per-task outcome**, **host drift**,
+and **external CVE intel**, then correlates them so tomorrow's run starts where
+today's finished. See [Skills, Memory & Learning](Skills-Memory-Learning.md)
+and [Extrospection](Extrospection.md).
+
+**Next:** [How PWN Works](How-PWN-Works.md)
+
+[← Home](Home.md)