pwn 0.5.617 → 0.5.620

data/documentation/Skills-Memory-Learning.md

@@ -1,44 +1,74 @@
-# Skills, Memory & Learning
+# Memory · Skills · Learning · Mistakes · 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, turns wins into permanent capability, and — critically —
+**learns from its own mistakes so it does not repeat them**.
 
-## Memory (`PWN::Memory`)
+![Memory / Skills detail](diagrams/memory-skills-detailed.svg)
 
-Persistent facts, preferences, lessons, and environment data stored in `~/.pwn/memory.json`.
+## The five 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 |
+| **Mistakes** | `mistakes.json` | `mistakes_record` · `mistakes_resolve` · *auto on failure* | `mistakes_list` | `KNOWN MISTAKES` + `KNOWN FIXES` blocks — do-NOT-repeat + do-THIS-instead |
+| **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)
+   ↳ tool FAILED?                 → Mistakes.record(tool, error)  (count++, cross-session)
+   ↳ same sig ≥3×?                → guard_repeated_failure + inline correction_hint
+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. Found a fix for a mistake       → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X — FIX: Y"
+6. Next launch: PromptBuilder injects all five blocks → the model already knows.
+```
 
-Reusable, versionable markdown procedures stored in `~/.pwn/skills/`.
+See **[Mistakes](Mistakes.md)** for the full negative-feedback mechanics
+(fingerprinting, `[REPEATING]`, `[REGRESSED]`, user-correction detection).
 
-- 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`.
+## Skill file format
 
-Example skills:
-- `deep_exploitation`
-- `vulnerability_research_fundamentals`
-- `xai_grok_oauth_device_flow`
+```markdown
+---
+references:
+  - CWE-89
+  - T1190
+  - https://portswigger.net/web-security/sql-injection
+---
+# sqli_union_enum
 
-## Learning Loop
+1. Confirm injection with `' AND 1=1 --`.
+2. Find column count with `ORDER BY n`.
+3. …
 
-- `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.
+## References
+- CWE-89
+- T1190
+```
 
-## Management Commands (REPL)
+`PWN::Config.parse_skill_references` reads both the YAML front-matter **and**
+the `## References` section, deduplicates, and exposes them via
+`skill_view(name)[:references]`.
 
-- `pwn-ai-memory`
-- `pwn-ai-sessions`
-- `pwn-ai-cron`
-- `skill_list`, `skill_view`, `skill_create`, `skill_add_reference`
+## Housekeeping
 
-This system turns one-off wins into institutional knowledge.
+| Tool | When |
+|---|---|
+| `learning_consolidate(max_entries: 200)` | MEMORY block getting long/noisy |
+| `learning_reset(confirm: true)` | dev-experiment noise polluted success_rate |
+| `mistakes_reset(confirm: true)` | new host/engagement — prior failure patterns no longer apply |
+| `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 |
 
-[[Diagrams]]
+**See also:** [Mistakes](Mistakes.md) — the negative-feedback half ·
+[Extrospection](Extrospection.md) — the outward-facing half ·
+[Sessions](Sessions.md) · [Persistence](Persistence.md)
+
+[← 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)