pwn 0.5.615 → 0.5.618

data/documentation/Sessions.md

@@ -0,0 +1,39 @@
+# Sessions — Transcript Persistence
+
+Every `pwn-ai` conversation (top-level *and* per-persona in a Swarm) is
+appended as JSON-per-line to `~/.pwn/sessions/<id>.jsonl`.
+
+![Sessions ↔ Cron ↔ Swarm](diagrams/sessions-cron-automation.svg)
+
+## Why keep transcripts?
+
+- `learning_reflect(session_id:)` mines them for durable lessons → Memory.
+- `learning_distill_skill(name:, session_id:)` turns a winning run into a
+  reusable Skill.
+- `sessions_view` lets you (or a later agent) re-read exactly what happened.
+- Swarm maps each persona to its own session so its private context survives
+  across `agent_ask` calls.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `sessions_current` | The id *this* conversation is being written to |
+| `sessions_list(limit:)` | Newest-first index (id · size · mtime · lines) |
+| `sessions_view(session_id:, truncate:)` | Read entries |
+| `sessions_delete(session_id:)` | Prune noisy/dev transcripts so `reflect` corpus stays clean |
+| `sessions_stats` | totals across the whole directory |
+
+## File format
+
+```json
+{"role":"system","ts":"2026-07-07T22:08:02Z","content":"…"}
+{"role":"user","ts":"…","content":"…"}
+{"role":"assistant","ts":"…","content":"…","tool_calls":[…]}
+{"role":"tool","ts":"…","name":"shell","content":"…"}
+```
+
+**See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[Swarm](Swarm.md) · [Persistence](Persistence.md)
+
+[← Home](Home.md)

data/documentation/Skills-Memory-Learning.md

@@ -1,44 +1,64 @@
-# Skills, Memory & Learning
+# Memory · Skills · Learning · Metrics — Introspection
 
-One of PWN's most powerful features is its self-improving closed loop.
+The **inward-facing** half of the pwn-ai feedback loop: how the agent measures
+its own performance and turns wins into permanent capability.
 
-## Memory (`PWN::Memory`)
+![Memory / Skills detail](diagrams/memory-skills-detailed.svg)
 
-Persistent facts, preferences, lessons, and environment data stored in `~/.pwn/memory.json`.
+## The four stores
 
-Use from REPL / agent:
-- `PWN::Memory.remember(key, value, category: :fact)`
-- `PWN::Memory.recall(query)`
+| Store | File | Write tool | Read tool | Injected as |
+|---|---|---|---|---|
+| **Memory** | `memory.json` | `memory_remember` | `memory_recall` | `MEMORY` block — durable facts / prefs / lessons / env |
+| **Skills** | `skills/*.md` | `skill_create` · `learning_distill_skill` | `skill_list` · `skill_view` | `SKILLS` list — reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST/URL) |
+| **Learning** | `learning.jsonl` | `learning_note_outcome` · `learning_reflect` | `learning_outcomes` · `learning_stats` | `LEARNING` block — recent outcomes + success_rate |
+| **Metrics** | `metrics.json` | *automatic* (every Dispatch) | `metrics_summary` | `TOOL EFFECTIVENESS` block — steer tool choice |
 
-Injected into every future `pwn-ai` session.
+## The lifecycle of a lesson
 
-## Skills
+```text
+1. Dispatch runs a tool           → Metrics.record(tool, ok?, ms)
+2. Final answer produced          → Learning.auto_reflect(session_id)
+3. Reflect finds a durable insight → Memory.remember(lesson_xxxx, …)
+4. A whole workflow succeeded      → Learning.distill_skill(name, session_id, references:)
+5. Next launch: PromptBuilder injects all four blocks → the model already knows.
+```
 
-Reusable, versionable markdown procedures stored in `~/.pwn/skills/`.
+## Skill file format
 
-- Created automatically via distillation of successful agent runs.
-- Manually via `skill_create` or editing YAML+markdown files.
-- Contain front-matter `references:` (CWE, CVE, ATT&CK, NIST, URLs).
-- Exposed to the agent and listed via `skill_list` / `skill_view`.
+```markdown
+---
+references:
+  - CWE-89
+  - T1190
+  - https://portswigger.net/web-security/sql-injection
+---
+# sqli_union_enum
 
-Example skills:
-- `deep_exploitation`
-- `vulnerability_research_fundamentals`
-- `xai_grok_oauth_device_flow`
+1. Confirm injection with `' AND 1=1 --`.
+2. Find column count with `ORDER BY n`.
+3. …
 
-## Learning Loop
+## References
+- CWE-89
+- T1190
+```
 
-- `PWN::AI::Agent::Metrics` — per-tool success rate + duration (`~/.pwn/metrics.json`)
-- `PWN::AI::Agent::Learning` — outcomes, reflections, skill distillation (`~/.pwn/learning.jsonl`)
-- Successful workflows become durable skills available to all future sessions.
+`PWN::Config.parse_skill_references` reads both the YAML front-matter **and**
+the `## References` section, deduplicates, and exposes them via
+`skill_view(name)[:references]`.
 
-## Management Commands (REPL)
+## Housekeeping
 
-- `pwn-ai-memory`
-- `pwn-ai-sessions`
-- `pwn-ai-cron`
-- `skill_list`, `skill_view`, `skill_create`, `skill_add_reference`
+| Tool | When |
+|---|---|
+| `learning_consolidate(max_entries: 200)` | MEMORY block getting long/noisy |
+| `learning_reset(confirm: true)` | dev-experiment noise polluted success_rate |
+| `metrics_reset(confirm: true)` | fixed a broken tool; stale 0 % is misleading |
+| `skill_delete(name)` | auto-distilled skill turned out low-quality |
+| `learning_auto_reflect_toggle(enabled: false)` | during noisy fuzz loops |
 
-This system turns one-off wins into institutional knowledge.
+**See also:** [Extrospection](Extrospection.md) — the outward-facing half ·
+[Sessions](Sessions.md) · [Persistence](Persistence.md)
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/Swarm.md

@@ -0,0 +1,71 @@
+# Swarm — Native Multi-Agent Orchestration
+
+`PWN::AI::Agent::Swarm` replaces the legacy `pwn-irc` (inspircd + weechat +
+PRIVMSG) transport with **first-class sub-agents** built directly on
+`PWN::AI::Agent::Loop`. Each persona is a *full* tool-calling agent — Memory,
+Skills, Learning, Metrics and Extrospection all apply — so the
+self-improvement loop covers the whole swarm.
+
+![Swarm](diagrams/swarm-multi-agent.svg)
+
+## Files
+
+| Path | Contains |
+|---|---|
+| `~/.pwn/agents.yml` | Persona registry (name → role/engine/toolsets/max_iters) |
+| `~/.pwn/swarm/<id>/bus.jsonl` | Append-only chat every persona reads/writes |
+| `~/.pwn/swarm/<id>/personas.json` | persona name → `PWN::Sessions` id |
+
+No daemon. Cross-session / cross-process communication == another `pwn-ai` (or
+a `PWN::Cron` job) calling `Swarm.ask` with the same `swarm_id`.
+
+## Define personas
+
+```ruby
+agent_spawn(name: 'red_team',
+            role: 'Offensive operator. Propose the most aggressive next step.',
+            engine: 'grok',
+            toolsets: %w[terminal pwn memory skills extrospection])
+
+agent_spawn(name: 'blue_team',
+            role: 'Defender. Critique red_team, flag detection risk & OPSEC.',
+            engine: 'anthropic',
+            toolsets: %w[pwn memory extrospection])
+```
+
+> Omit `swarm` from a persona's toolsets to stop it recursively spawning
+> further sub-agents. Recursion is also hard-capped by
+> `PWN::Env[:ai][:agent][:max_depth]` (default 3).
+
+## Verbs
+
+| Tool | Use for |
+|---|---|
+| `agent_list` | See who's defined |
+| `agent_spawn` | Define / overwrite a persona |
+| `agent_ask(name, request)` | One turn of one persona → reply comes back to *you* |
+| `agent_debate(names, topic, rounds:)` | Round-robin critique — each sees the bus tail |
+| `agent_broadcast(request)` | Fan-out; returns `{name => reply}` for voting |
+| `swarm_bus(swarm_id)` | Tail a bus to inspect a prior/concurrent conversation |
+| `swarm_list` | Find a `swarm_id` to resume |
+
+## Example: adversarial exploit review
+
+```ruby
+tx = agent_debate(
+  names:  %w[red_team blue_team exploit_dev],
+  topic:  'Target runs Jenkins 2.426.2 on :8080 — plan initial access.',
+  rounds: 3
+)
+# later, in a different pwn-ai process:
+agent_ask(name: 'red_team', swarm_id: tx[:swarm_id],
+          request: 'blue_team raised WAF concerns — revise the payload.')
+```
+
+Because each persona can pin a **different engine**, the debate is real model
+diversity, not one model role-playing.
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
+[Agent Tool Registry](Agent-Tool-Registry.md) · [Sessions](Sessions.md)
+
+[← Home](Home.md)

data/documentation/Transparent-Browser.md

@@ -1,32 +1,36 @@
-# Transparent Browser
+# `PWN::Plugins::TransparentBrowser`
 
-`PWN::Plugins::TransparentBrowser` — powerful browser automation (headless + visible) built on top of Selenium / Watir / Ferrum / similar.
+Watir + Selenium wrapper that gives you a real Chrome/Firefox — headless or
+visible — with proxy support, DevTools protocol access, and cookie/console
+capture. It's the traffic source for [BurpSuite](BurpSuite.md), the engine
+under every [`PWN::WWW`](WWW.md) driver, and the agent's go-to for anything
+JS-heavy.
 
-## Primary Uses
-
-- Web spidering / crawling
-- JavaScript-heavy application interaction
-- Automated form submission, auth flows
-- Screenshotting, DOM inspection
-- Proxied browsing (pairs excellently with BurpSuite)
-
-## Example Calls
+## Open
 
 ```ruby
-browser = PWN::Plugins::TransparentBrowser.open_browser(
-  browser_type: :chrome,
-  proxy: 'http://127.0.0.1:8080'   # Burp
+b = PWN::Plugins::TransparentBrowser.open(
+  browser_type: :headless,           # :chrome | :firefox | :headless | :rest
+  proxy:        'http://127.0.0.1:8080',
+  with_devtools: true
 )
-browser.goto 'https://target.example.com'
-# ... interact ...
-browser.close
+b[:browser].goto 'https://target'
+b[:browser].text_field(name: 'q').set 'pwn'
 ```
 
-Agent-friendly.
+## Useful bits
+
+```ruby
+b[:browser].cookies.to_a
+b[:browser].execute_script('return document.title')
+b[:devtools].send_cmd('Network.enable')
+PWN::Plugins::TransparentBrowser.dump_links(browser_obj: b)
+PWN::Plugins::TransparentBrowser.close(browser_obj: b)
+```
 
-## See Also
+## `:rest` mode
 
-- [Burp Suite](BurpSuite.md)
-- [Plugins](Plugins.md)
+`browser_type: :rest` returns a `RestClient`-backed object with the same proxy
+plumbing — for APIs where a full browser is overkill.
 
-[[Diagrams]]
+[← Home](Home.md) · [BurpSuite](BurpSuite.md) · [WWW](WWW.md)

data/documentation/Troubleshooting.md

@@ -1,38 +1,57 @@
 # Troubleshooting
 
-## Common Issues
+## SHIFT+ENTER submits instead of newline
 
-### Burp / ZAP Proxy Problems
-- Prefer `PWN::Plugins::BurpSuite`
-- 502 errors usually mean upstream proxy not listening or crashed. Check with `ps`, `ss -tlnp`, restart via plugin methods.
+`pwn-ai` / `pwn-asm` need the terminal to send a *distinct* code for
+Shift-Enter. Under **tmux** both sides must be configured:
 
-### Ruby / Gemset Issues
-- Use RVM and the gemset defined in `.ruby-version` / `.ruby-gemset`.
-- Re-run `./install.sh ruby-gem` or the vagrant provisioner after Ruby upgrades.
-
-### AI / LLM Authentication
-- Grok uses OAuth device flow (public client) — see `xai_grok_oauth_device_flow` skill.
-- Store credentials via `PWN::Config` or environment as documented.
+```tmux
+# ~/.tmux.conf
+set -s  extended-keys on
+set -as terminal-features 'xterm*:extkeys'   # replace xterm* with your $TERM
+```
 
-### SHIFT+ENTER Not Working in pwn-ai
-- Requires tmux `extended-keys on` on **both** inner and outer sides.
-- See recent lessons in memory for exact tmux config.
+Then fully **detach and re-attach** (a `source-file` isn't enough for
+`terminal-features`). Verify with `tmux display -p '#{client_termfeatures}'`
+— it must include `extkeys`.
 
-### Git / Permissions
-- Run `sudo chown -R $USER:$USER /opt/pwn` if permission issues after install.
+## `502 Bad Gateway` from a proxy plugin
 
-## Diagnostics
+The upstream (Burp/ZAP) isn't listening. Check:
 
 ```bash
-pwn
-PWN.help
-# Inside REPL:
-PWN::Config
-PWN::Plugins::PWNLogger
+ps aux | grep -E 'burp|zap'
+ss -tlnp | grep -E ':8080|:1337'
 ```
 
-Check `~/.pwn/` for logs, metrics, learning files.
+Restart via `PWN::Plugins::BurpSuite.start` / `PWN::Plugins::Zaproxy.start` or
+fix the port in `~/.pwn/config.yml`.
+
+## `Psych::DisallowedClass` on cron/agents YAML
+
+Fixed in current `PWN::Cron` / `Swarm` — both loaders now pass
+`permitted_classes: [Symbol]`. If you see it, `git pull && rake install`.
+
+## Agent stops early ("max iterations")
+
+Raise `ai.agent.max_iters` in `~/.pwn/config.yml`, or split the request.
+
+## A tool is stuck at 0 % success
+
+If you've since fixed the tool, wipe the stale telemetry so it stops steering
+the agent away: `metrics_reset(confirm: true)`.
+
+## LLM auth
+
+| Engine | Fix |
+|---|---|
+| grok `oauth: true` | first run prints a `https://accounts.x.ai/…` URL — open it, approve, token is cached |
+| ollama | ensure `ollama serve` is running and `base_url:` matches |
+| others | check `key:` under `ai.<engine>` in `~/.pwn/config.yml` |
+
+## Diagrams won't rebuild
 
-Report bugs via GitHub issues with full reproduction + `pwn` version.
+`sudo apt install graphviz` (need `dot` on `$PATH`), then
+`cd documentation/diagrams && ./build.sh`.
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/WWW.md

@@ -0,0 +1,32 @@
+# `PWN::WWW` — Site-Specific Browser Automations
+
+21 modules, each a scripted [`TransparentBrowser`](Transparent-Browser.md)
+session against a real site: log in, navigate, scrape, submit.
+Source: `lib/pwn/www/*.rb`.
+
+## Modules
+
+| Category | Modules |
+|---|---|
+| **Bug bounty** | `HackerOne` · `BugCrowd` · `Synack` · `AppCobaltIO` |
+| **Search / OSINT** | `Google` · `Bing` · `DuckDuckGo` · `Torch` · `WaybackMachine` · `Pastebin` · `Checkip` |
+| **Social** | `Twitter` · `Facebook` · `LinkedIn` · `Youtube` · `Pandora` |
+| **Finance / Work** | `CoinbasePro` · `Paypal` · `TradingView` · `Uber` · `Upwork` |
+
+## Pattern
+
+```ruby
+b = PWN::WWW::HackerOne.open(browser_type: :headless,
+                             proxy: 'http://127.0.0.1:8080')
+PWN::WWW::HackerOne.login(browser_obj: b, username: '…', mfa: '…')
+# ... scripted navigation ...
+PWN::WWW::HackerOne.logout(browser_obj: b)
+PWN::Plugins::TransparentBrowser.close(browser_obj: b)
+```
+
+Because traffic goes through TransparentBrowser, you can point `proxy:` at
+[BurpSuite](BurpSuite.md) and passively capture every request the automation
+makes.
+
+[← Home](Home.md) · [Transparent-Browser](Transparent-Browser.md) ·
+[Bounty](Bounty.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)