pwn 0.5.627 → 0.5.629

data/documentation/Configuration.md

@@ -16,6 +16,11 @@ writes a fully-commented template with every key below (values set to
 `'optional - …'` / `'required - …'` placeholder strings), encrypts it, and
 generates the decryptor.
 
+> **Before configuring**, run `pwn setup` — the
+> [doctor](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
+> reports whether `~/.pwn/`, `pwn.yaml`, its decryptor, and an AI-engine key
+> are present, and exits non-zero for CI if any are missing.
+
 ---
 
 ## Full annotated example
@@ -30,7 +35,7 @@ ai:
   grok:
     base_uri: https://api.x.ai/v1  # xAI API base URL. Override for a self-hosted proxy / private endpoint.
     key: xai-…                     # xAI API key. If blank AND no oauth.* below, PWN prompts interactively at load.
-    model: grok-4.5                # Model id sent on every chat / tool-loop request.
+    model: <model-id>              # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking xAI Grok agent.'   # Base system prompt (MEMORY/SKILLS/LEARNING/EXTROSPECTION blocks are appended to this).
     temp: 1.0                      # Sampling temperature passed to the chat endpoint.
     max_prompt_length: 256000      # Soft input-context ceiling (chars) used for prompt truncation / chunking.
@@ -46,7 +51,7 @@ ai:
   openai:
     base_uri: https://api.openai.com/v1   # OpenAI API base URL. Override for Azure OpenAI / VPC gateway / local proxy.
     key: sk-…                             # OpenAI API key (`sk-…`). Prompted interactively if blank.
-    model: gpt-4o                         # Model id sent on every chat / tool-loop request.
+    model: <model-id>                     # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking OpenAI agent.'   # Base system prompt for this engine.
     temp: 1.0                             # Sampling temperature.
     max_prompt_length: 128000             # Soft input-context ceiling (chars) for truncation / chunking.
@@ -55,7 +60,7 @@ ai:
   anthropic:
     base_uri: https://api.anthropic.com/v1   # Anthropic API base URL. Override for Bedrock / private gateway.
     key: sk-ant-…                            # Anthropic API key (`sk-ant-…`). Prompted interactively if blank.
-    model: claude-3-5-sonnet-20240620        # Model id sent on every chat / tool-loop request.
+    model: <model-id>                        # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking Anthropic agent.'   # Base system prompt for this engine.
     temp: 1.0                                # Sampling temperature.
     max_tokens: 8192                         # Max OUTPUT tokens per response. Raise if tool-call JSON truncates.
@@ -64,7 +69,7 @@ ai:
   gemini:
     base_uri: https://generativelanguage.googleapis.com/v1beta   # Google Generative Language API base URL.
     key: AIza…                               # Google AI Studio API key (`AIza…`). Prompted interactively if blank.
-    model: gemini-2.5-pro                    # Model id sent on every chat / tool-loop request.
+    model: <model-id>                        # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking Gemini agent.'   # Base system prompt for this engine.
     temp: 1.0                                # Sampling temperature.
     max_prompt_length: 1000000               # Soft input-context ceiling (chars) — Gemini supports very large contexts.
@@ -72,17 +77,31 @@ ai:
   ollama:
     base_uri: https://ollama.local           # REQUIRED for ollama — Open WebUI / ollama-serve base URL (no vendor default).
     key: eyJ…                                # Open WebUI JWT (Settings → Account → API Key). Prompted if blank.
-    model: llama3.1:70b                      # Local model tag as `ollama list` shows it.
+    model: <local-model-tag>                 # Local model tag exactly as `ollama list` shows it.
+    embed_model: <embed-model-tag>           # Embedding model for PWN::MemoryIndex (relevance-ranked MEMORY). Must be pulled locally.
     system_role_content: 'You are an ethically hacking Ollama agent.'   # Base system prompt for this engine.
-    temp: 1.0                                # Sampling temperature.
+    temp: 1.0                                # Sampling temperature (used on the FINAL text-only turn — tool-bearing turns are pinned low for deterministic routing).
+    num_ctx: 32768                           # Context window passed to /api/chat options.num_ctx. Ollama's default (2048) is too small for the pwn-ai system prompt.
+    keep_alive: 30m                          # How long ollama keeps the model resident between iterations (avoids reload latency mid-turn).
+    prompt_budget:                           # Per-block caps applied by PromptBuilder.budget so a small model spends attention on the request, not the harness.
+      memory: 6                              # Max MEMORY entries injected (relevance-ranked via PWN::MemoryIndex when available).
+      metrics: 3                             # Max TOOL EFFECTIVENESS rows.
+      mistakes: 3                            # Max KNOWN MISTAKES / FIXES rows.
+      learning: 2                            # Max recent LEARNING outcomes shown.
+      extro: false                           # Gate the (heaviest) EXTROSPECTION block entirely for local models.
     max_prompt_length: 32000                 # Soft input-context ceiling (chars) — tune per local model's real context window.
 
+  reflect_engine: ~                # Teacher-student reflection: EXECUTE on ai.active, but write durable lessons via THIS engine (nil = same as active). Lets a local model act while a frontier model authors the Memory :lesson entries it reads back.
+
   agent:
     native_tools: true             # Use provider-native tool_calls / function-calling. false → legacy text-parsed tool protocol.
     max_iters: 25                  # Hard cap on tool-call rounds per user turn before a forced final answer.
     max_depth: 3                   # Recursion guard: how many levels deep agent_ask/agent_debate sub-agents may spawn sub-agents.
     auto_introspect: true          # Run Learning.auto_introspect (outcome logging + lesson mining) after every final answer.
     auto_extrospect: false         # Optional ambient baseline (host/repo/env ONLY — never launches burpsuite/zaproxy/msf/gqrx). Sense tools (intel/verify/watch/rf_tune/observe) stay on-demand.
+    plan_first: ~                  # Plan-then-act pre-pass: force the model to externalise a numbered tool plan BEFORE its first dispatch. nil = auto (true when ai.active == ollama).
+    tool_router: false             # Dynamic tool-set slimming: ship only Registry::CORE_TOOLS + top-K keyword-relevant schemas per turn (helps small models route correctly).
+    escalation_persona: ~          # Swarm persona name to ask for a 3-line corrective hint once a local model burns ≥ Loop::ESCALATE_AFTER_FAILS in-turn failures. nil = disabled.
     toolsets: ~                    # Allow-list of toolsets exposed to the agent. nil = all. Valid: cron, extrospection, learning, memory, metrics, pwn, sessions, skills, swarm, terminal.
     extrospection:
       web:
@@ -193,12 +212,17 @@ PWN::Config.refresh_env
 | `ai.module_reflection` | Boolean | `false` | `PWN::AI::Agent::Reflect`, `PWN::SAST::*`, `PWN::Plugins::BurpSuite` | Master gate for LLM-driven self-analysis (SAST triage, Burp finding enrichment, `Learning.llm_reflect`). |
 | `ai.<engine>.base_uri` | String | provider default | `PWN::AI::<Engine>.rest_call` | Override the API base URL (self-hosted proxy, private endpoint, Azure/VPC gateway). **Required** for `ollama`. |
 | `ai.<engine>.key` | String | — | `PWN::AI::<Engine>` | API key / bearer token. If blank AND no OAuth is configured, PWN prompts interactively at load. |
-| `ai.<engine>.model` | String | provider default | `PWN::AI::<Engine>.chat` / `.chat_tool_loop` | Model id sent on every request (e.g. `grok-4.5`, `gpt-4o`, `claude-3-5-sonnet-20240620`, `gemini-2.5-pro`, `llama3.1:70b`). |
+| `ai.<engine>.model` | String | provider default | `PWN::AI::<Engine>.chat` / `.chat_tool_loop` | Model id sent on every request. Use whatever id the provider / `ollama list` currently exposes — PWN never hard-codes a specific model. |
 | `ai.<engine>.system_role_content` | String | ethical-hacker persona | `PWN::AI::Agent::PromptBuilder`, `PWN::Plugins::REPL` | Base system prompt prepended to MEMORY / SKILLS / LEARNING / EXTROSPECTION blocks. |
 | `ai.<engine>.temp` | Float | `1.0` | `PWN::AI::<Engine>.chat` | Sampling temperature. |
 | `ai.<engine>.max_prompt_length` | Integer | per-engine | `PWN::AI::<Engine>`, `PWN::Plugins::REPL` | Soft input-context ceiling used for prompt truncation / chunking. |
 | `ai.anthropic.max_tokens` | Integer | `8192` | `PWN::AI::Anthropic.chat_tool_loop` | Max **output** tokens per response. Raise if tool-call JSON truncates. |
 | `ai.openai.max_tokens` | Integer | `16384` | `PWN::AI::OpenAI.chat` | Max **output** tokens per response. Mapped to OpenAI's wire param `max_completion_tokens` (legacy env key `max_completion_tokens` still accepted). |
+| `ai.ollama.embed_model` | String | provider default | `PWN::MemoryIndex` | Local embedding model tag used to build `~/.pwn/memory.idx` for **relevance-ranked** MEMORY injection. Falls back to substring recall when unset / unreachable. |
+| `ai.ollama.num_ctx` | Integer | `32768` | `PWN::AI::Ollama.chat_with_tools` | Context window sent as `options.num_ctx` on the native `/api/chat` call. Ollama's own default (2048) truncates the pwn-ai system prompt. |
+| `ai.ollama.keep_alive` | String | `30m` | `PWN::AI::Ollama.chat_with_tools` | How long the model stays resident in ollama between iterations of a single turn. |
+| `ai.ollama.prompt_budget` | Hash | `{memory:6, metrics:3, mistakes:3, learning:2, extro:false}` | `PWN::AI::Agent::PromptBuilder.budget` | Per-block caps on injected context so a small local model spends its attention on the request, not the harness. Any engine may set this. |
+| `ai.reflect_engine` | Symbol \| `nil` | `nil` (= `ai.active`) | `PWN::AI::Agent::Reflect.on`, `Learning.reflect` | **Teacher-student** override: run the task on `ai.active`, but generate durable lessons via *this* engine. Lets a local model execute while a frontier model writes the Memory it reads back. |
 | `ai.grok.oauth.refresh_token` | String | — | `PWN::AI::Grok.resolve_auth` | Durable OAuth refresh token (from `PWN::AI::Grok.obtain_oauth_bearer_token` device flow). Enables silent re-auth without an API key. |
 | `ai.grok.oauth.bearer_token` | String | — | `PWN::AI::Grok.resolve_auth` | Short-lived OAuth access JWT. Auto-refreshed each run when `refresh_token` is present; live-cached back into this hash. |
 | `ai.grok.oauth.client_id` | String | Grok-CLI public id | `PWN::AI::Grok` | Override the public OAuth client id used for device-flow / refresh. |
@@ -217,6 +241,9 @@ PWN::Config.refresh_env
 | `ai.agent.auto_introspect` | Boolean | `true` | `PWN::AI::Agent::Learning.auto_introspect` | Run outcome logging + lesson mining after every final answer. Toggle live via `learning_auto_introspect_toggle`. |
 | `ai.agent.auto_extrospect` | Boolean | `false` | `PWN::AI::Agent::Extrospection.auto_extrospect` | Optional ambient baseline after every final answer (`AUTO_SECTIONS` = host/repo/env only; never spawns GUI/JVM tools). Prefer on-demand sense tools (`intel`/`verify`/`watch`/`rf_tune`/`observe`). Toggle live via `extro_auto_toggle`. |
 | `ai.agent.toolsets` | Array\<String\> \| `nil` | `nil` (all) | `bin/pwn`, `PWN::Plugins::REPL`, `PWN::AI::Agent::Registry` | Allow-list of toolsets exposed to the agent. Valid: `cron`, `extrospection`, `learning`, `memory`, `metrics`, `pwn`, `sessions`, `skills`, `swarm`, `terminal`. |
+| `ai.agent.plan_first` | Boolean \| `nil` | `nil` (auto: `true` when `ai.active == ollama`) | `PWN::AI::Agent::Loop.plan_first` | Plan-then-act pre-pass: the model must emit a numbered tool plan (as an assistant message) *before* it may dispatch anything. Cheap chain-of-thought scaffolding for local models. |
+| `ai.agent.tool_router` | Boolean | `false` | `PWN::AI::Agent::Registry.definitions` | Dynamic tool-set slimming: expose only `Registry::CORE_TOOLS` + the top-K keyword-relevant schemas for *this* request. Ties break on historical `Metrics` success rate so the router itself is a learned component. |
+| `ai.agent.escalation_persona` | String \| `nil` | `nil` | `PWN::AI::Agent::Loop.escalate` → `Swarm.ask` | Circuit-breaker: once a local model accumulates ≥ `Loop::ESCALATE_AFTER_FAILS` in-turn failures, ask this Swarm persona for a 3-line corrective hint (injected as a synthetic tool result). The local model still authors the final answer so Learning/Metrics stay attributed. |
 | `ai.agent.extrospection.web.anchors` | Array\<String\> | `DEFAULT_WEB_ANCHORS` | `PWN::AI::Agent::Extrospection.probe_web` | URLs the headless browser fingerprints on `extro_snapshot(sections:[:web])`. Alias: `web_anchors`. |
 | `ai.agent.extrospection.web.proxy` | String | — | `Extrospection.probe_web` / `.verify` / `.watch` | Upstream proxy for `PWN::Plugins::TransparentBrowser` (e.g. `tor`, `http://127.0.0.1:8080`). |
 | `ai.agent.extrospection.web.max_anchors` | Integer | `8` | `Extrospection.probe_web` | Cap on anchors rendered per snapshot. |
@@ -309,9 +336,9 @@ agent system prompt.
 
 `pwn.yaml` is the only file you edit; everything else is machine-written
 state. See **[Persistence](Persistence.md)** for the full map
-(`memory.json`, `learning.jsonl`, `mistakes.json`, `metrics.json`,
-`extrospection.json`, `sessions/`, `skills/`, `cron/`, `agents.yml`,
-`swarm/`).
+(`memory.json`, `memory.idx`, `learning.jsonl`, `mistakes.json`,
+`metrics.json`, `extrospection.json`, `sessions/`, `skills/`,
+`finetune/`, `cron/`, `agents.yml`, `swarm/`).
 
 Multi-agent personas are **not** configured here — they live in
 `~/.pwn/agents.yml` and are managed with `agent_spawn` / `agent_list`

data/documentation/Contributing.md

@@ -4,10 +4,11 @@
 
 ```text
 lib/pwn/                # all namespaces
+lib/pwn/setup.rb        # PWN::Setup — doctor/provisioner data tables
 lib/pwn/plugins/        # 66 plugin modules
 lib/pwn/ai/agent/       # agent core
 lib/pwn/ai/agent/tools/ # LLM tool registrations
-bin/                    # 52 pwn_* drivers
+bin/                    # 53 pwn_* drivers (incl. pwn_setup)
 spec/                   # RSpec (incl. conventions_spec)
 documentation/          # this wiki + diagrams
 ```
@@ -23,9 +24,11 @@ documentation/          # this wiki + diagrams
 ## Quality gates
 
 ```bash
-rvmsudo rake            # rubocop + rspec — must be zero offenses
+rake            # rubocop + rspec — must be zero offenses
 ```
 
+(`rvmsudo rake` on multi-user RVM installs.)
+
 ## Adding a plugin
 
 1. `lib/pwn/plugins/my_thing.rb` following the conventions above.
@@ -34,7 +37,14 @@ rvmsudo rake            # rubocop + rspec — must be zero offenses
 4. Optional `bin/pwn_my_thing` driver (see [Drivers](Drivers.md)).
 5. Optional agent tool in `lib/pwn/ai/agent/tools/` (see
    [Agent Tool Registry](Agent-Tool-Registry.md)).
-6. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
+6. **If it needs a native gem or external binary**, add **one row** to
+   `PWN::Setup::NATIVE_GEMS` or `PWN::Setup::TOOLCHAIN` in
+   `lib/pwn/setup.rb` (with `apt:`/`dnf:`/`pacman:`/`brew:`/`port:` package
+   names + the `plugins:` it unlocks) and, if it belongs in a capability
+   set, reference it from `PWN::Setup::PROFILES`. That single edit makes
+   `pwn setup` install it on every OS and every install path (gem, git,
+   Docker, Packer, Vagrant, CI). **Do not** add a new bash provisioner.
+7. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
    relevant `.dot` in `documentation/diagrams/dot/` → `./build.sh`.
 
 ## Commit / release

data/documentation/Extrospection.md

@@ -442,142 +442,152 @@ extro_correlate                        # why did it break?
 
 ## Example questions that trigger Extrospection
 
-Natural-language prompts that should fire **outward** sensing (grouped by sense organ).
-Location-specific details use **Chicago** as the canonical city so the catalog stays
-portable across deployments.
-
-### RF sense organ (`extro_rf_tune` + RF observations)
-
-- “What’s playing on 101.1 right now?”
-- “What’s on Q101 / 101.1 FM in Chicago?”
-- “Is NOAA weather radio for the Chicago area broadcasting an alert?”
-- “Tune 433.92 MHz and report signal strength.”
-- “Any ADS-B traffic near Chicago O’Hare (ORD) right now?”
-- “Sample RDS on 93.1 for 15 seconds — station name and radiotext?”
-- “Is the local Chicago 2 m repeater on 146.x active?”
-
-### Web sense organ (`extro_watch`, `extro_verify`, `snapshot(sections: [:web])`)
-
-- “Did the vendor status page change since last check?”
-- “Watch https://status.example.com for DOM changes.”
-- “Has the bug-bounty scope page been updated?”
-- “What’s the weather in Chicago today?” *(live external page)*
-- “Fingerprint that login portal’s generator / title / tech stack.”
-- “Screenshot + hash https://target/app/version for drift tracking.”
+Natural-language prompts that should route to **outward** sensing rather than
+introspection. These are phrased the way an offensive security researcher
+actually asks them mid-engagement — attack-surface discovery, zero-day
+hunting, hardware/RF poking, and disclosure prep. Location-specific examples
+use **Chicago** so the catalogue stays portable.
+
+### RF / SDR sense organ (`extro_rf_tune` + `:rf` observations)
+
+- “Tune 433.92 MHz — is the target’s garage/gate remote fixed-code or rolling?”
+- “Sweep the 900 MHz ISM band near the badge reader and log anything > −40 dBFS.”
+- “What’s broadcasting on 101.1 FM right now — grab RDS PI/PS so we can prove SDR is live.”
+- “Sample 868.3 MHz for 15 s — does the smart-meter mesh look like Wireless M-Bus?”
+- “Any ADS-B traffic squawking over the client’s campus (near ORD)?”
+- “Listen on the pager band (929.x MHz) — are unencrypted POCSAG pages leaking PHI?”
+- “Is the site’s DMR/TETRA handheld traffic on 462.x actually encrypted?”
+- “Park on 315 MHz and tell me if the target’s TPMS / key-fob replays cleanly.”
+
+### Web / browser sense organ (`extro_watch`, `extro_verify`, `snapshot(sections: [:web])`)
+
+- “Watch the target’s `/api/version` endpoint — alert me the moment the build string changes.”
+- “Has the vendor silently patched? Diff today’s changelog DOM against our last hash.”
+- “Did the bug-bounty scope page add or drop assets since we baselined it?”
+- “Fingerprint the login portal’s JS bundle — framework, version, source-map leakage.”
+- “Screenshot + DOM-hash the admin panel so we can prove pre-auth state for the report.”
+- “Render the CSP/`.well-known/security.txt` and tell me who to disclose to.”
+- “Has the target’s TLS cert or issuer rotated since the last watch?”
 
 ### OSINT sense organ (`extro_osint`)
 
-- “Reverse lookup +1 312 555 1212.”
-- “Who is the registrant for example.com?”
-- “What device is FCC ID 2ABIP-ESP32?”
-- “Find patents related to software-defined radio receivers.”
-- “Pivot on username @octocat across GitHub/GitLab/Reddit.”
-- “Is Jane Doe listed on OpenSanctions / Wikipedia?”
-- “CT certs for target.acme via crt.sh.”
-- “ASN / BGP neighbours for 1.1.1.1.”
-- “Any Wayback snapshots of https://target.acme/login?”
+- “Enumerate every subdomain for `*.target.tld` via CT logs (crt.sh + CertSpotter).”
+- “Who owns AS-XXXXX and what netblocks does it announce — expand our in-scope ranges.”
+- “Pull EPSS + CISA KEV for CVE-2024-3094 — is this worth weaponising first?”
+- “What’s Shodan / GreyNoise saying about `203.0.113.10` — already mass-exploited?”
+- “Decode this VIN off the fleet vehicle — what telematics head-unit ships in that trim?”
+- “FCC ID `2ABIP-…` on the IoT doorbell — pull the internal photos and RF test report.”
+- “MAC OUI `AC:DE:48` on the rogue AP — which vendor, and do they have default creds?”
+- “Any prior litigation or SEC 8-K breach filings for `Target Corp` before we disclose?”
+- “Wayback the old `/admin` path — did an earlier deploy expose a debug console?”
+- “Pivot `@lead-dev` across GitHub/GitLab — hardcoded secrets in personal repos?”
 
-### Serial sense organ (`extro_serial`)
+### Serial / hardware sense organ (`extro_serial`)
 
-- “What USB serial devices are attached?”
-- “Send ATI to the modem on /dev/ttyUSB0 and show the banner.”
-- “Talk to the Flipper / RFID reader on ttyACM and dump response hex.”
-- “Probe the Arduino console at 115200 8N1.”
+- “What just enumerated on `/dev/ttyUSB*` when I plugged in the router’s UART header?”
+- “Send `AT+GMR` to the ESP32 on `/dev/ttyUSB0` — firmware version and SDK build?”
+- “Dump the boot banner at 115200 8N1 — does it drop to an unauthenticated U-Boot shell?”
+- “Probe the Flipper on `ttyACM0` and pull the last captured Sub-GHz raw.”
+- “Talk to the smart-lock’s BLE-UART bridge and echo back whatever it volunteers.”
 
-### Telecomm sense organ (`extro_telecomm`)
+### Telecomm / VoIP sense organ (`extro_telecomm`)
 
-- “Is BareSIP running and what is its status?”
-- “List SIP ports listening on this host.”
-- “Dial sip:echo@example.com via BareSIP.” *(OPSEC: real call)*
-- “Hang up the active VoIP call.”
+- “Is BareSIP registered to the client’s PBX, and what codecs did it negotiate?”
+- “Enumerate SIP `OPTIONS` against the exposed SBC — does it leak `User-Agent`/version?”
+- “Dial the IVR at `sip:ivr@target` and record the prompt tree for the social-eng playbook.” *(OPSEC: real call)*
+- “Hang up and note whether the PBX exposed internal extension ranges in the `BYE`.”
 
 ### Packet sense organ (`extro_packet`)
 
-- “Inventory capture-capable interfaces and tshark/tcpdump.”
-- “Capture 20 packets on eth0 for tcp/443 and summarise.”
-- “Summarise this pcap: /tmp/eng.pcap.”
-- “What IP conversations dominate that capture?”
+- “Capture 30 s on `eth0` while I trigger the IoT hub — what does it phone home to?”
+- “Summarise `/tmp/eng.pcap` — top talkers, cleartext creds, weird ports.”
+- “BPF `udp port 5353` — is mDNS leaking hostnames and service records on the guest VLAN?”
+- “Grab 50 packets of the OT segment — Modbus/TCP or something proprietary?”
+- “Do we see the camera’s RTSP creds in the clear during that capture?”
 
 ### Vision / OCR sense organ (`extro_vision`)
 
-- “OCR this screenshot of the login page.”
-- “Decode the QR code on /tmp/badge.png.”
-- “What languages does tesseract have installed?”
+- “OCR the photo of the switch label — model, firmware, and default-cred sticker.”
+- “Decode the QR on the badge printer — is that a provisioning URL with an embedded token?”
+- “OCR the BIOS/BMC screenshot and pull the exact firmware build for CVE matching.”
+- “Read the barcode on the HSM — serial + part number for supply-chain lookup.”
 
 ### Voice sense organ (`extro_voice`)
 
-- “Speak ‘engagement complete’ via TTS.”
-- “Transcribe /tmp/voicemail.wav.”
-- “What TTS/STT engines are available on this host?”
+- “Transcribe `/tmp/voicemail.wav` — did the helpdesk leak the temp-password format?”
+- “STT the recorded IVR tree so we can grep it for extension numbers.”
+- “TTS this vishing pretext to a `.wav` for the approved social-engineering call.”
+- “Which STT/TTS engines are installed — can we run whisper offline on the drop box?”
 
 ### Fact-check / claim verification (`extro_verify`)
 
-- “Is CVE-2024-3094 still rated Critical on NVD?”
-- “Confirm the latest `pwn` gem on RubyGems is 0.5.x.”
-- “Is it true that OpenSSH 9.8p1 is the current stable?”
-- “Verify this claim from the advisory against the official page.”
-- “Does that docs page actually say what we quoted?”
+- “Before I file this: does CVE-2024-3094 actually list our target’s distro package as affected?”
+- “Confirm the latest upstream OpenSSH is 9.x — is the target’s 8.2p1 genuinely EOL?”
+- “Verify the vendor advisory URL really says ‘remote unauthenticated’ — quote it back.”
+- “Is `pwn` on RubyGems still at the version we ship in the report appendix?”
+- “Fact-check my claim that this library has no maintained fork — search says otherwise?”
 
 ### Threat intel (`extro_intel` ± `record:true`)
 
-- “Any known exploits for Apache 2.4.58?”
-- “Look up CVE-2025-XXXX across NVD / CIRCL / Exploit-DB.”
-- “What CVEs hit `libssl` in the last year?”
-- “Is there a public PoC for that JetBrains CVE?”
-- “Correlate installed nmap version against known CVEs.”
+- “Any public PoC or Exploit-DB entry for the exact `nginx 1.25.3` build we bannered?”
+- “Pull NVD + CIRCL for `libwebp` since 2023 — which are pre-auth RCE vs local?”
+- “Cross-ref this router’s firmware components against known-exploited (KEV).”
+- “What’s the newest CVE touching `Fortinet FortiOS` and is there an exploit module yet?”
+- “Record everything for `Apache Struts` so `extro_correlate` can match our target stack.”
 
 ### Host / env / toolchain drift (`extro_snapshot`, `extro_drift`, `extro_stats`)
 
-- “Did the environment change under us since last session?”
-- “Take a full extrospection snapshot and show drift.”
-- “Is nmap / gqrx / SoapySDR still the version we expect?”
-- “What’s listening on this host right now?”
-- “Show toolchain + repo HEAD fingerprint.”
-- “Why did that tool start failing — world drift or operator error?” → pairs with `extro_correlate`
+- “Snapshot the drop box before we start — I want a defensible ‘this is what we brought’ baseline.”
+- “Did anything on this attack host change overnight (kernel, nmap, listening ports)?”
+- “Which offensive bins are actually present in PATH on this jump host?”
+- “Is the SDR / HackRF still attached, or did the USB hub flake again?”
+- “Show repo HEAD + dirty state so the finding is reproducible from a commit hash.”
 
 ### Recon memory / observations (`extro_observe`, `extro_observations`)
 
-- “Remember that target X bannered as nginx/1.25.3 on 443.”
-- “What recon findings do we have for 10.0.0.5?”
-- “List RF observations from today.”
-- “Any :web watches that changed this week?”
-- “Show intel hits we recorded against this product.”
+- “Remember: `10.0.0.5:8443` self-signed CN leaks internal AD domain — tag `recon,pivot`.”
+- “Log the RF finding: 433.92 MHz fixed-code, 24-bit, replayable — tag `rf,physical`.”
+- “What have we already observed about `*.target.tld` this engagement?”
+- “List every `:intel` observation still fresh so I don’t re-run the same CVE queries.”
+- “Which `:web` watches flipped `changed:true` this week — silent patch candidates?”
 
-### Correlation / “am I wrong or did the world move?” (`extro_correlate`)
+### Correlation — “am I wrong or did the world move?” (`extro_correlate`)
 
-- “Cross-check recent tool failures against host/toolchain drift.”
-- “Did any of our recorded CVEs match installed package versions?”
-- “Is that failed shell call explained by missing binaries?”
-- “Any refuted claims that should invalidate old memory facts?”
+- “My exploit stopped landing — did the target’s DOM/TLS drift or did I break the payload?”
+- “Cross recorded CVE intel against the versions we actually bannered on scope hosts.”
+- “Are any of my `PWN::Memory` facts about this target now refuted by fresh `extro_verify` runs?”
+- “Do the `nmap`/`msf` failures line up with a toolchain upgrade rather than operator error?”
+- “Which watched anchors went unreachable — down-weight intel sourced from them.”
 
 ### Operational / lifecycle
 
-- “Enable ambient auto-extrospect after every answer.”
-- “Reset extrospection for a new engagement.” *(destructive)*
-- “How stale is the current world snapshot?”
-- “Toggle auto-extrospect off while we fuzz.”
+- “New engagement, new client — wipe extrospection so old recon doesn’t bleed into this report.” *(destructive)*
+- “Turn ambient auto-extrospect **off** while I fuzz — I don’t want baseline noise per turn.”
+- “How stale is our world snapshot — is it still from the pre-patch window?”
+- “Re-enable auto-extrospect for the wrap-up so drift is captured in the final deliverable.”
 
-### Short “trigger” patterns the agent should recognize
+### Short trigger patterns the agent should recognise
 
 | Pattern | Likely tools |
-|--------|----------------|
-| “What’s on … MHz / FM / station” | `extro_rf_tune` |
-| “Reverse phone / FCC ID / patent / whois / person” | `extro_osint` |
-| “Serial / AT modem / ttyUSB / Flipper console” | `extro_serial` |
-| “SIP / VoIP / BareSIP / dial” | `extro_telecomm` |
-| “Capture packets / summarise pcap” | `extro_packet` |
-| “OCR / barcode / QR this image” | `extro_vision` |
-| “Speak this / transcribe that audio” | `extro_voice` |
-| “Did … page change / watch URL” | `extro_watch` |
-| “Is it true that… / confirm CVE / latest version” | `extro_verify` |
-| “Known vulns / CVE / exploit for…” | `extro_intel` |
-| “What changed on this host / drift” | `extro_snapshot` + `extro_drift` |
-| “Remember this finding about…” | `extro_observe` |
-| “Why did X start failing?” | `extro_correlate` + metrics/mistakes |
-| “Weather in Chicago / public page content” | `extro_watch` / TransparentBrowser |
+|---|---|
+| “tune / MHz / FM / RDS / ISM / key-fob / pager / ADS-B” | `extro_rf_tune` |
+| “subdomain / CT log / ASN / whois / FCC ID / VIN / MAC OUI / EPSS / KEV / Wayback / pivot @user” | `extro_osint` |
+| “UART / ttyUSB / U-Boot / AT command / Flipper / JTAG banner” | `extro_serial` |
+| “SIP / PBX / IVR / BareSIP / dial / hangup” | `extro_telecomm` |
+| “capture on iface / summarise pcap / mDNS / Modbus / RTSP creds” | `extro_packet` |
+| “OCR sticker / decode QR / read badge / BIOS screenshot” | `extro_vision` |
+| “transcribe wav / TTS pretext / whisper offline” | `extro_voice` |
+| “watch URL / did the page change / silent patch / scope updated / TLS rotated” | `extro_watch` |
+| “is it true that / confirm CVE / verify advisory / latest version of” | `extro_verify` |
+| “known exploits for / any PoC / CVEs affecting / KEV for” | `extro_intel` |
+| “what changed on this host / baseline the box / SDR still attached” | `extro_snapshot` + `extro_drift` |
+| “remember this finding / what did we observe about / tag it recon” | `extro_observe` / `extro_observations` |
+| “why did X stop working / my fault or theirs / down-weight that source” | `extro_correlate` |
+| “new engagement clean slate / stop baselining while I fuzz” | `extro_reset` / `extro_auto_toggle` |
 
 The **inward** half of the loop (Memory · Skills · Learning · Mistakes · Metrics)
-has a matching example catalog in [Skills, Memory & Learning](Skills-Memory-Learning.md#example-questions-that-trigger-introspection).
+has a matching example catalogue in
+[Skills, Memory & Learning](Skills-Memory-Learning.md#example-questions-that-trigger-introspection).
 
 **See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
 [Mistakes](Mistakes.md) · [SDR](SDR.md) · [Transparent Browser](Transparent-Browser.md) · [Cron](Cron.md) · [pwn-ai Agent](pwn-ai-Agent.md)

data/documentation/FFI.md

@@ -12,6 +12,16 @@ PWN::FFI.backends
 PWN::FFI.available?(mod: :Volk)  # => true/false
 ```
 
+## Install the shared objects
+
+```bash
+pwn setup --profile sdr   # rtl-sdr · hackrf · SoapySDR · libsndfile · libusb · ffi headers
+```
+
+`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 |
@@ -29,8 +39,10 @@ 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`, …). 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?`

data/documentation/Fuzzing.md

@@ -2,6 +2,9 @@
 
 ![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

@@ -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,6 +3,10 @@
 ![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 |

data/documentation/Home.md

@@ -2,7 +2,7 @@
 
 > **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/` ·
@@ -17,9 +17,9 @@
 | [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 |
+| [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`)

data/documentation/How-PWN-Works.md

@@ -19,7 +19,8 @@ hardware).
 | `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/`)