pwn 0.5.620 → 0.5.622

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b52a560de426b6b9c99fa2716b8e93a948e66088e0e1ae78d28f8633417cea
-  data.tar.gz: f94969b76a9ad4b856a9b5db25647f41d57f600f0c331ebde29c24b35ab59cd1
+  metadata.gz: f4aeb484ae013e0feb9648009d60cfc493bbd4ec98ba42193745af669ed70bcc
+  data.tar.gz: 2dcffdf992ee24a9c8a10ae7b83c743ad5b6b1aed83e70063da56e8cf6e9ea85
 SHA512:
-  metadata.gz: dcd6287345b8f7230aeeeddc8a5d8de97d4000ae6bddecd77b4b2957f8ddf480de5c9ba8ba6a96a9fcf77f64a30f0b3d9a41219ad15512deab556c5b7e60c360
-  data.tar.gz: 92b3f2b90679984a47ed9cff3e1440100803e4220fc6f78eac386bd5cd125f24acbdd7b44504c20f783ba653895726495a69b7ce5d9cd5fd883a98cb67a11ef9
+  metadata.gz: 2468ec9291d44be94de1f3877441380e60cde34e24953f6ac677bd39f0679c82ab6f82f6554b7fcacf1348b0c751c63bf8d8a23a369ac665023b5a9e74cc3a01
+  data.tar.gz: 722765fd660ca9da266a170da45f65eb061886b7629557143436a0765412dc89d3de3e56ac8f5bd8e9b32e5f25831d3644ac3568d851f6ac5f7629531b9e7768

data/Gemfile

@@ -50,7 +50,7 @@ gem 'libusb', '0.7.2'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
 gem 'mcp', '0.23.0'
-gem 'meshtastic', '0.0.169'
+gem 'meshtastic', '0.0.171'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.24.1'
 gem 'msfrpc-client', '1.1.2'

data/README.md

@@ -52,7 +52,7 @@ Five layers, edges only ever go down:
 
 The AI layer closes a **self-improvement loop** on every turn — Metrics +
 Learning + **Mistakes** (introspection / negative feedback) joined with
-Snapshot + Drift + Intel + RF (extrospection) via `extro_correlate`, so the
+Snapshot + Drift + Intel + RF + **Web** (extrospection) — plus browser-backed **`extro_verify`** self fact-checking — via `extro_correlate`, so the
 agent knows whether a failure was *its* fault or *the world* changed —
 **and does not repeat the same mistake twice**:
 

data/documentation/Agent-Tool-Registry.md

@@ -6,7 +6,7 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 
 ![Tool registry](diagrams/agent-tool-registry.svg)
 
-## Toolsets → Tools  (10 toolsets · 52 tools)
+## Toolsets → Tools  (10 toolsets · 54 tools)
 
 | Toolset | Tools | Backed by |
 |---|---|---|
@@ -15,9 +15,9 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
 | `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` | `~/.pwn/skills/*.md` |
 | `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
-| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_reflect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** | `PWN::AI::Agent::Learning` + `PWN::AI::Agent::Mistakes` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** | `PWN::AI::Agent::Learning` + `PWN::AI::Agent::Mistakes` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` |
 | `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
-| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` → `~/.pwn/extrospection.json` |
+| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ `PWN::Plugins::TransparentBrowser`) → `~/.pwn/extrospection.json` |
 | `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
 | `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
 

data/documentation/Configuration.md

@@ -1,66 +1,311 @@
-# Configuration — `~/.pwn/config.yml`
+# Configuration — `~/.pwn/pwn.yaml`
 
-Everything configurable lives in one YAML file, loaded by `PWN::Config` at
-startup and available in-process as `PWN::Env`.
+Everything configurable in PWN lives in **one encrypted YAML file**, loaded by
+`PWN::Config.refresh_env` at driver startup and exposed in-process as the
+frozen constant **`PWN::Env`** (a redacted copy is available as
+`PWN::EnvRedacted`).
 
-## Minimal example
+The file is **AES-encrypted at rest** by `PWN::Plugins::Vault`. Its key/IV
+live in a sibling **`~/.pwn/pwn.yaml.decryptor`** file (or in
+`PWN_DECRYPTOR_KEY` / `PWN_DECRYPTOR_IV` env vars). Never edit `pwn.yaml`
+by hand — use the **`pwn-vault`** REPL command, which decrypts → opens
+`$EDITOR` → re-encrypts → reloads `PWN::Env`.
+
+If `~/.pwn/pwn.yaml` does not exist on first run, `PWN::Config.default_env`
+writes a fully-commented template with every key below (values set to
+`'optional - …'` / `'required - …'` placeholder strings), encrypts it, and
+generates the decryptor.
+
+---
+
+## Full annotated example
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml  (shown DECRYPTED — file is AES-encrypted on disk)
+
 ai:
-  engine: anthropic          # openai | anthropic | grok | gemini | ollama
-  anthropic:
-    key: sk-ant-…
-  openai:
-    key: sk-…
+  active: grok                     # Which engine backs `pwn-ai`. One of: openai | anthropic | grok | gemini | ollama.
+  module_reflection: false         # Master gate for LLM self-analysis (SAST triage, Burp enrichment, Learning.llm_reflect).
+
   grok:
-    oauth: true              # RFC-8628 device flow, no client_secret
+    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.
+    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.
+    oauth:                         # RFC-8628 device-flow (SuperGrok subscription) — public client, no client_secret.
+      refresh_token: ~             # Durable OAuth refresh token; enables silent re-auth without an API key.
+      bearer_token: ~              # Short-lived OAuth access JWT; auto-refreshed each run when refresh_token is set.
+      client_id: b1a00492-073a-47ea-816f-4c329264a828   # xAI's PUBLIC OAuth client id for the "Grok CLI" application (not sensitive).
+      client_secret: ~             # Only for confidential-client OAuth flows; unused by the public Grok-CLI client.
+      scope: 'openid profile email offline_access grok-cli:access api:access'   # OAuth scope string requested during device-flow enrollment.
+      token_uri: https://auth.x.ai/oauth2/token          # OAuth token endpoint (override for enterprise IdP).
+      enroll: false                # true → force RFC-8628 device-flow enrollment on load even when `key:` is set.
+
+  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.
+    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.
+    max_tokens: 16384                     # Max OUTPUT tokens per response. Mapped to OpenAI wire param `max_completion_tokens`.
+
+  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.
+    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.
+    max_prompt_length: 200000                # Soft input-context ceiling (chars) for truncation / chunking.
+
+  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.
+    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.
+
   ollama:
-    base_url: http://localhost:11434
-    model: llama3.1:70b
+    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.
+    system_role_content: 'You are an ethically hacking Ollama agent.'   # Base system prompt for this engine.
+    temp: 1.0                                # Sampling temperature.
+    max_prompt_length: 32000                 # Soft input-context ceiling (chars) — tune per local model's real context window.
+
   agent:
-    max_iters:      40       # tool-loop cap per turn
-    max_depth:      3        # swarm recursion cap
-    auto_reflect:   true     # Learning.auto_reflect after every final answer
-    auto_extrospect: true    # Extrospection.auto_extrospect likewise
-
-burp:
-  jar: /opt/burpsuite_pro/burpsuite_pro.jar
-  api_key: …
-
-metasploit:
-  host: 127.0.0.1
-  port: 55553
-  user: msf
-  pass: …
+    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         # Also run Extrospection.auto_extrospect (host/toolchain/net/repo drift capture) after every final answer.
+    toolsets: ~                    # Allow-list of toolsets exposed to the agent. nil = all. Valid: cron, extrospection, learning, memory, metrics, pwn, sessions, skills, swarm, terminal.
+    extrospection:
+      web:
+        anchors:                   # URLs the headless browser fingerprints on extro_snapshot(sections:[:web]). Alias: web_anchors.
+          - https://nvd.nist.gov
+          - https://www.exploit-db.com
+        proxy: ~                   # Upstream proxy for TransparentBrowser during probe_web/verify/watch (e.g. 'tor', http://127.0.0.1:8080).
+        max_anchors: 8             # Cap on how many anchors are rendered per snapshot (protects run time).
+        per_page_timeout: 15       # Seconds before a single page render is abandoned and recorded as unreachable.
+        screenshot: false          # Persist a PNG per anchor to ~/.pwn/extrospection/web/ (disk-heavy; off by default).
+        allow_targets: false       # true → also merge top-level `targets:` into anchors (opt-in — off so in-scope hosts aren't touched unprompted).
+
+plugins:
+  asm:
+    arch: x86_64                   # Target architecture for `pwn-asm` inline assembler/disassembler. Default: PWN::Plugins::DetectOS.arch.
+    endian: little                 # Endianness for `pwn-asm` (little | big). Default: PWN::Plugins::DetectOS.endian.
+  blockchain:
+    bitcoin:
+      rpc_host: localhost          # bitcoind JSON-RPC host for PWN::Blockchain::BTC.
+      rpc_port: 8332               # bitcoind JSON-RPC port.
+      rpc_user: …                  # bitcoind RPC username (rpcauth / rpcuser in bitcoin.conf).
+      rpc_pass: …                  # bitcoind RPC password. Redacted in PWN::EnvRedacted.
+  hunter:
+    api_key: …                     # hunter.how API key — passed as api_key: to PWN::Plugins::Hunter.search.
+  jira_data_center:
+    base_uri: https://jira.company.com/rest/api/latest   # Jira Data Center REST base URL.
+    token: …                       # Jira Personal Access Token for PWN::Plugins::JiraDataCenter. Redacted.
+  meshtastic:
+    admin_key: …                   # Public key authorised to send admin messages to mesh nodes via `pwn-mesh`.
+    serial:
+      port: /dev/ttyUSB0           # Serial device path for a locally-attached Meshtastic node.
+      baud: 115200                 # Serial baud rate.
+      bits: 8                      # Serial data bits.
+      stop: 1                      # Serial stop bits.
+      parity: none                 # Serial parity (none | even | odd).
+    mqtt:
+      host: mqtt.meshtastic.org    # MQTT broker hostname for Meshtastic-over-MQTT.
+      port: 1883                   # MQTT broker port (8883 for TLS).
+      tls: false                   # Use TLS to the MQTT broker.
+      user: meshdev                # MQTT username (public Meshtastic broker default shown).
+      pass: large4cats             # MQTT password (public Meshtastic broker default shown). Redacted.
+    channel:
+      active: LongFast             # Which named channel block below `pwn-mesh` uses for TX/RX.
+      LongFast:                    # Channel definition — name is arbitrary, referenced by `active:` above.
+        psk: 'AQ=='                # Channel pre-shared key (base64). 'AQ==' = Meshtastic default public key. Redacted.
+        region: US/UT              # LoRa region tag (regulatory band).
+        topic: 2/e/#               # MQTT topic filter to subscribe/publish for this channel.
+        channel_num: 8             # Meshtastic channel index (slot number on the device).
+        from: '!deadbeef'          # Sender node id used on outbound packets. Optional — defaults to !<mqtt client_id>.
+      PWN:                         # Example second (private) channel definition.
+        psk: …                     # Private channel pre-shared key (base64). Redacted.
+        region: US/UT              # LoRa region tag for this channel.
+        topic: 2/e/PWN/#           # MQTT topic filter for this channel.
+        channel_num: 99            # Meshtastic channel index for this channel.
+  shodan:
+    api_key: …                     # Shodan API key — passed as api_key: to PWN::Plugins::Shodan.*. Redacted.
+
+memory:
+  enabled: true                    # Reserve — persistent-memory subsystem on/off (currently always active; future gate).
+  provider: file                   # Storage backend for PWN::Memory: file (~/.pwn/memory.json). `sqlite` reserved.
+
+sessions:
+  enabled: true                    # Reserve — transcript recording on/off (currently always active; future gate).
+  provider: jsonl                  # Transcript format under ~/.pwn/sessions/ (one .jsonl per session).
+
+cron:
+  enabled: true                    # Reserve — scheduled-job subsystem on/off (currently always active; future gate).
+  provider: yaml                   # Job store format for PWN::Cron (~/.pwn/cron/jobs.yml).
+
+targets:                           # Optional — engagement-scope URLs/hosts. Merged into :web snapshot anchors
+  - https://target.example.com     #   ONLY when ai.agent.extrospection.web.allow_targets: true.
 ```
 
+---
+
 ## Reading / writing at runtime
 
 ```ruby
-PWN::Env[:ai][:engine]                 # => :anthropic
-PWN::Env[:ai][:agent][:auto_reflect]   # => true
-PWN::Config.reload!
+PWN::Env[:ai][:active]                          # => :grok
+PWN::Env.dig(:ai, :agent, :max_iters)           # => 25
+PWN::EnvRedacted[:ai][:grok][:key]              # => ">>> REDACTED >>> …"
+
+# Edit + re-encrypt + reload without leaving the REPL:
+pwn-vault
+
+# Force a reload from disk (e.g. after pwn-vault in another shell):
+PWN::Config.refresh_env
 ```
 
-## Sections PWN looks for
+---
+
+## Exhaustive key reference
+
+### `ai` — AI engines & agent loop
+
+| Key path | Type | Default | Consumed by | Purpose |
+|---|---|---|---|---|
+| `ai.active` | String | `grok` | `PWN::Config.refresh_env`, `PWN::AI::Agent::Loop`, `PWN::Plugins::REPL`, `PWN::Cron` | Which AI engine backs `pwn-ai`. One of `openai` · `anthropic` · `grok` · `gemini` · `ollama`. |
+| `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>.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.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. |
+| `ai.grok.oauth.client_secret` | String | — | `PWN::Config.refresh_env`, `PWN::AI::Grok` | Only for confidential-client OAuth flows. Unused by the default public Grok-CLI client. |
+| `ai.grok.oauth.scope` | String | see example | `PWN::AI::Grok` | OAuth scope string requested during device-flow enrollment. |
+| `ai.grok.oauth.token_uri` | String | `https://auth.x.ai/oauth2/token` | `PWN::AI::Grok` | OAuth token endpoint (override for enterprise IdP). |
+| `ai.grok.oauth.enroll` | Boolean | `false` | `PWN::AI::Grok` | `true` → always run RFC-8628 device-flow enrollment on load, even when `ai.grok.key` is set. |
+
+### `ai.agent` — pwn-ai autonomous loop
+
+| Key path | Type | Default | Consumed by | Purpose |
+|---|---|---|---|---|
+| `ai.agent.native_tools` | Boolean | `true` | `PWN::Plugins::REPL` (`pwn-ai` cmd) | Use provider-native `tool_calls` / function-calling. `false` falls back to the legacy text-parsed tool protocol. |
+| `ai.agent.max_iters` | Integer | `25` | `PWN::AI::Agent::Loop.run`, `PWN::AI::Agent::Swarm` | Hard cap on tool-call rounds per user turn before a forced final answer. |
+| `ai.agent.max_depth` | Integer | `3` | `PWN::AI::Agent::Swarm` | Recursion guard for `agent_ask` / `agent_debate` sub-agents spawning sub-agents. |
+| `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` | Also capture host/toolchain/net/repo drift after every final answer. 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.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. |
+| `ai.agent.extrospection.web.per_page_timeout` | Integer | `15` | `Extrospection` (headless browser) | Seconds before a page render is abandoned. |
+| `ai.agent.extrospection.web.screenshot` | Boolean | `false` | `Extrospection.probe_web` / `.watch` | Persist a PNG per anchor to `~/.pwn/extrospection/web/`. |
+| `ai.agent.extrospection.web.allow_targets` | Boolean | `false` | `Extrospection.web_anchors` | Merge top-level `targets:` into the anchor list (opt-in — off by default to avoid touching in-scope hosts unprompted). |
+
+### `plugins` — module credentials & wiring
+
+| Key path | Type | Default | Consumed by | Purpose |
+|---|---|---|---|---|
+| `plugins.asm.arch` | String | `DetectOS.arch` | `PWN::Plugins::REPL` (`pwn-asm`) | Target architecture for the inline assembler / disassembler prompt (`x86_64`, `arm64`, …). |
+| `plugins.asm.endian` | String | `DetectOS.endian` | `PWN::Plugins::REPL` (`pwn-asm`) | Endianness for the inline assembler (`little` / `big`). |
+| `plugins.blockchain.bitcoin.rpc_host` | String | `localhost` | `PWN::Blockchain::BTC` | bitcoind JSON-RPC host. |
+| `plugins.blockchain.bitcoin.rpc_port` | Integer | `8332` | `PWN::Blockchain::BTC` | bitcoind JSON-RPC port. |
+| `plugins.blockchain.bitcoin.rpc_user` | String | — | `PWN::Blockchain::BTC` | bitcoind RPC username. |
+| `plugins.blockchain.bitcoin.rpc_pass` | String | — | `PWN::Blockchain::BTC` | bitcoind RPC password. |
+| `plugins.hunter.api_key` | String | — | `PWN::Plugins::Hunter` | hunter.how API key (passed as `api_key:` to `Hunter.search`). |
+| `plugins.jira_data_center.base_uri` | String | — | `PWN::Plugins::JiraDataCenter` | Jira DC REST base (e.g. `https://jira.company.com/rest/api/latest`). |
+| `plugins.jira_data_center.token` | String | — | `PWN::Plugins::JiraDataCenter` | Jira Personal Access Token. |
+| `plugins.meshtastic.admin_key` | String | — | `PWN::Plugins::REPL` (`pwn-mesh`) | Public key authorised to send admin messages to mesh nodes. |
+| `plugins.meshtastic.serial.port` | String | `/dev/ttyUSB0` | `pwn-mesh` (serial) | Serial device path for a locally-attached Meshtastic node. |
+| `plugins.meshtastic.serial.baud` | Integer | `115200` | `pwn-mesh` (serial) | Serial baud rate. |
+| `plugins.meshtastic.serial.bits` | Integer | `8` | `pwn-mesh` (serial) | Serial data bits. |
+| `plugins.meshtastic.serial.stop` | Integer | `1` | `pwn-mesh` (serial) | Serial stop bits. |
+| `plugins.meshtastic.serial.parity` | Symbol | `:none` | `pwn-mesh` (serial) | Serial parity. |
+| `plugins.meshtastic.mqtt.host` | String | `mqtt.meshtastic.org` | `pwn-mesh` → `Meshtastic::MQTT.connect` | MQTT broker hostname. |
+| `plugins.meshtastic.mqtt.port` | Integer | `1883` | `pwn-mesh` | MQTT broker port. |
+| `plugins.meshtastic.mqtt.tls` | Boolean | `false` | `pwn-mesh` | Use TLS to the MQTT broker. |
+| `plugins.meshtastic.mqtt.user` | String | `meshdev` | `pwn-mesh` | MQTT username. |
+| `plugins.meshtastic.mqtt.pass` | String | `large4cats` | `pwn-mesh` | MQTT password. |
+| `plugins.meshtastic.channel.active` | String | `LongFast` | `pwn-mesh` | Which named channel block below is used for TX/RX. |
+| `plugins.meshtastic.channel.<NAME>.psk` | String (b64) | `AQ==` | `pwn-mesh` | Channel pre-shared key. |
+| `plugins.meshtastic.channel.<NAME>.region` | String | — | `pwn-mesh` | LoRa region tag (e.g. `US/UT`). |
+| `plugins.meshtastic.channel.<NAME>.topic` | String | — | `pwn-mesh` | MQTT topic filter to subscribe/publish (e.g. `2/e/#`). |
+| `plugins.meshtastic.channel.<NAME>.channel_num` | Integer | — | `pwn-mesh` | Meshtastic channel index. |
+| `plugins.meshtastic.channel.<NAME>.from` | String | `!<mqtt client_id>` | `pwn-mesh` | Sender node id used on outbound packets. |
+| `plugins.shodan.api_key` | String | — | `PWN::Plugins::Shodan` | Shodan API key (passed as `api_key:` to `Shodan.*`). |
+
+### `memory` / `sessions` / `cron`
+
+| Key path | Type | Default | Consumed by | Purpose |
+|---|---|---|---|---|
+| `memory.enabled` | Boolean | `true` | `PWN::Memory` | Reserve — persistent memory on/off (currently always active; future gate). |
+| `memory.provider` | String | `file` | `PWN::Memory` | Storage backend: `file` (`~/.pwn/memory.json`). `sqlite` reserved. |
+| `sessions.enabled` | Boolean | `true` | `PWN::Sessions` | Reserve — transcript recording on/off (currently always active; future gate). |
+| `sessions.provider` | String | `jsonl` | `PWN::Sessions` | Transcript format under `~/.pwn/sessions/`. |
+| `cron.enabled` | Boolean | `true` | `PWN::Cron` | Reserve — scheduled-job subsystem on/off (currently always active; future gate). |
+| `cron.provider` | String | `yaml` | `PWN::Cron` | Job store format (`~/.pwn/cron/jobs.yml`). |
+
+### Top-level / miscellaneous
+
+| Key path | Type | Default | Consumed by | Purpose |
+|---|---|---|---|---|
+| `targets` | Array\<String\> | — | `PWN::AI::Agent::Extrospection.web_anchors` | Engagement-scope URLs/hosts. Merged into `:web` snapshot anchors when `ai.agent.extrospection.web.allow_targets: true`. |
+
+---
+
+## Runtime-only keys on `PWN::Env` (NOT stored in `pwn.yaml`)
+
+These are injected by `PWN::Config.refresh_env` / `PWN::AI::Agent::Loop` after
+the YAML is decrypted. They will appear on `PWN::Env` in-process but are
+**overwritten on every load**, so putting them in `pwn.yaml` has no effect.
+
+| Key path | Set by | Purpose |
+|---|---|---|
+| `driver_opts.pwn_env_path` | `PWN::Config.refresh_env` / `PWN::Driver::Parser` | Resolved path to the active `pwn.yaml` (from `--pwn_env` or default). |
+| `driver_opts.pwn_dec_path` | `PWN::Config.refresh_env` / `PWN::Driver::Parser` | Resolved path to the decryptor YAML (from `--pwn_dec` or default). |
+| `pwn_skills_path` | `PWN::Config.refresh_env` | Absolute path to `~/.pwn/skills/`. |
+| `pwn_memory_path` | `PWN::Config.refresh_env` | Absolute path to `~/.pwn/memory.json`. |
+| `pwn_sessions_path` | `PWN::Config.refresh_env` | Absolute path to `~/.pwn/sessions/`. |
+| `pwn_cron_path` | `PWN::Config.refresh_env` | Absolute path to `~/.pwn/cron/`. |
+| `ai.<engine>.response_history` | `PWN::Config.refresh_env` | Rolling chat history for the active engine (reset on every reload). |
+| `ai.session_id` | `PWN::AI::Agent::Loop.run` | Active `PWN::Sessions` id for the current turn (read by `sessions_current`, `mistakes_record`). |
+
+---
+
+## Redaction
+
+`PWN::Config.redact_sensitive_artifacts` (and therefore `PWN::EnvRedacted`)
+masks any key named: `admin_key`, `api_key`, `auth_client_secret`,
+`bearer_token`, `client_secret`, `consumer_key`, `key`, `pass`, `password`,
+`psk`, `refresh_token`, `secret_key`, `token`. Use those key names for any
+custom secrets you add so they never leak into logs, transcripts, or the
+agent system prompt.
+
+---
 
-| Key path | Consumed by |
-|---|---|
-| `ai.engine` | `PWN::AI::Agent::Loop` — which client to instantiate |
-| `ai.<engine>.key` / `.oauth` | `PWN::AI::OpenAI` / `Anthropic` / `Grok` / `Gemini` / `Ollama` |
-| `ai.agent.max_iters` | hard stop on tool-call rounds |
-| `ai.agent.max_depth` | `Swarm` recursion guard |
-| `ai.agent.auto_reflect` | toggle `Learning.auto_reflect` |
-| `ai.agent.auto_extrospect` | toggle `Extrospection.auto_extrospect` |
-| `burp.*` | `PWN::Plugins::BurpSuite` |
-| `metasploit.*` | `PWN::Plugins::Metasploit` |
-| `zap.*` | `PWN::Plugins::Zaproxy` |
-| `shodan.key` / `hunter.key` / … | respective OSINT plugins |
-| `aws.*` | `PWN::AWS::*` (falls back to standard AWS SDK env/instance-profile) |
+## Related files under `~/.pwn/`
 
-## Other files under `~/.pwn/`
+`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/`).
 
-See [Persistence](Persistence.md) for the full map.
+Multi-agent personas are **not** configured here — they live in
+`~/.pwn/agents.yml` and are managed with `agent_spawn` / `agent_list`
+(see **[Swarm](Swarm.md)**).
 
-[← Home](Home.md)
+[← Home](Home.md) · [Persistence](Persistence.md) · [pwn-ai Agent](pwn-ai-Agent.md) · [Extrospection](Extrospection.md)

data/documentation/Cron.md

@@ -37,10 +37,23 @@ cron_create(
 ```
 
 At 02:00 the system cron fires `PWN::Cron.run`, which spins up a headless
-`pwn-ai` turn. Because `auto_reflect` and `auto_extrospect` are on, the run
+`pwn-ai` turn. Because `auto_introspect` and `auto_extrospect` are on, the run
 also updates Learning/Metrics/Extrospection — so tomorrow's interactive
 session already knows what changed overnight.
 
+```ruby
+cron_create(
+  name: 'memory_revalidate',
+  schedule: '0 4 * * 0',
+  ruby: 'PWN::AI::Agent::Extrospection.revalidate_memory'
+)
+```
+
+Weekly, headless-browser fact-check of every `PWN::Memory` `:fact` containing
+a CVE / version string / URL. Refuted entries get prefixed `[UNVERIFIED
+yyyy-mm-dd]` so the injected MEMORY block stops calcifying into
+confidently-wrong priors — see [Extrospection § revalidate_memory](Extrospection.md).
+
 **See also:** [Sessions](Sessions.md) · [Extrospection](Extrospection.md) ·
 [CLI Drivers](CLI-Drivers.md)
 

data/documentation/Diagrams.md

@@ -59,7 +59,7 @@ groups) so lines never criss-cross.
 [source](diagrams/dot/ai-integration-tool-calling.dot) · doc: [AI Integration](AI-Integration.md)
 ![ai-integration-tool-calling](diagrams/ai-integration-tool-calling.svg)
 
-### Agent Tool Registry (10 toolsets · 52 tools)
+### Agent Tool Registry (10 toolsets · 54 tools)
 [source](diagrams/dot/agent-tool-registry.dot) · doc: [Agent Tool Registry](Agent-Tool-Registry.md)
 ![agent-tool-registry](diagrams/agent-tool-registry.svg)
 

data/documentation/Extrospection.md

@@ -17,22 +17,31 @@ like right now, and has it changed under me?"*
 | `:repo` | `probe_repo` | HEAD · branch · dirty · origin |
 | `:env` | `probe_env` | ruby / gem / bundler / PWN version |
 | **`:rf`** | **`probe_rf`** | **RTL-SDR / HackRF presence · SoapySDR devices · GQRX socket (127.0.0.1:7356) · Flipper serial · `/dev/tty{USB,ACM}*` · band-plan count** |
+| **`:web`** *(opt-in)* | **`probe_web`** | **Renders `web_anchors` via `PWN::Plugins::TransparentBrowser` (`:headless`) — HTTP status · final URL · `<title>` · meta[generator] · `Server` · SHA-256 of *rendered* DOM text · TLS cert fp / notAfter · optional screenshot → `~/.pwn/extrospection/web/<host>.png`** |
 
 `RF_BINS = %w[rtl_sdr rtl_test rtl_433 hackrf_info gqrx dump1090 multimon-ng SoapySDRUtil]`
 — these are also merged into `PROBE_BINS` so RF-toolchain drift shows up under
 `toolchain.*` diff keys.
 
+`DEFAULT_WEB_ANCHORS` = NVD CVE 2.0 API, Exploit-DB, upstream `pwn/version.rb`.
+Override / extend via `PWN::Env[:ai][:agent][:extrospection][:web][:anchors]`; set
+`allow_targets: true` to also fingerprint `PWN::Env[:targets]`. **`:web` is never
+run by `auto_extrospect`** — a headless browser is ~1–3 s cold vs ~50 ms for
+`probe_host`, so it's opt-in (`extro_snapshot(sections: %i[web])`).
+
 ## Verbs
 
 | Tool | Does | Persists to |
 |---|---|---|
-| `extro_snapshot` | Fingerprint host/net/toolchain/repo/env/**rf** → hash | `extrospection.json` (`snapshot` + rotates `previous`) |
+| `extro_snapshot` | Fingerprint host/net/toolchain/repo/env/**rf**/*web* → hash | `extrospection.json` (`snapshot` + rotates `previous`) |
 | `extro_drift` | Diff live-vs-stored (or stored-vs-previous) | — returns `{changed, added, removed}` with dotted keys |
-| `extro_observe` | Record a fact — `category:` one of `recon vuln intel target network env` **`rf`** `misc` | `observations[]` |
+| `extro_observe` | Record a fact — `category:` one of `recon vuln intel target network env` **`rf` `web`** `misc` | `observations[]` |
 | `extro_observations` | Query recorded facts by source/category/target/tag | — |
 | `extro_intel` | Query NVD / CIRCL / Exploit-DB for keyword or CVE | optional `record: true` → `:intel` observations |
+| **`extro_watch`** | **Render a URL headless, hash the *rendered* DOM, screenshot, diff vs prior** | `observations[]` (`category: :web`) |
+| **`extro_verify`** | **Browser-backed self fact-check of a claim (`:cve` `:version` `:doc` `:generic`) → `:confirmed`/`:refuted`/`:unknown`** | `Mistakes.record` / `observe(:intel)` / `Learning.note_outcome` |
 | `extro_correlate` | **Join** introspection ↔ extrospection | — actionable findings |
-| `extro_stats` | snapshot age · observation count · drift counts · **rf_devices** | — |
+| `extro_stats` | snapshot age · observation count · drift counts · **rf_devices** · **web_anchors** | — |
 | `extro_reset` | Wipe snapshot + observations (new engagement) | — |
 | `extro_auto_toggle` | Enable/disable auto-snapshot after every final answer | `PWN::Env[:ai][:agent][:auto_extrospect]` |
 
@@ -43,6 +52,9 @@ like right now, and has it changed under me?"*
 (b) Learning failures on day X         ×  host/net/repo drift on day X
 (c) recorded :intel observations       ×  installed component versions
 (d) recorded :rf observations          ×  missing SDR hardware / RF_BINS
+(e) recorded :web DOM drift on target  ×  Learning failures citing that host
+(f) extro_verify :refuted claims       ×  stale PWN::Memory :fact entries
+(g) :intel obs whose feed anchor is    ×  probe_web-unreachable → downgrade weight
 ```
 
 Output tells the agent whether a failure was **its own fault** ("I called the
@@ -51,23 +63,77 @@ API wrong" → belongs in [Mistakes](Mistakes.md)) or **the world changed**
 that distinction is written back into MEMORY so the next run doesn't waste
 iterations rediscovering it.
 
+## `extro_verify` — proactive fact-checking (the browser as a sense organ)
+
+`probe_rf` gave Extrospection **ears**; `PWN::Plugins::TransparentBrowser` gives
+it **eyes**. `extro_verify(claim:)` renders a canonical source *with JavaScript
+executed* and returns a verdict:
+
+| `kind:` | Canonical source (rendered headless) | Verdict logic |
+|---|---|---|
+| `:cve` | `nvd.nist.gov/vuln/detail/<id>` + `cve.org/CVERecord?id=` | CVE exists? affected-product string overlaps claimed product/version? |
+| `:version` | rubygems.org / PyPI / GitHub search | claimed "latest is X" vs scraped latest |
+| `:doc` | the URL the model cited | 200? title/body contains ≥ 40 % of the quoted-snippet tokens (fuzzy)? |
+| `:generic` | DuckDuckGo HTML (proxy-able, no API key) | ≥ 50 % token overlap in top result snippets |
+
+```text
+                  ┌── :refuted  → Mistakes.record(tool:'assumption', …)  → KNOWN MISTAKES block ∀ future runs
+extro_verify ─────┼── :confirmed→ observe(category::intel, ttl:30d)      → EXTROSPECTION block, freshness-bound
+                  └── :unknown  → Learning.note_outcome(tags:[needs_human])
+```
+
+This adds a **proactive** trigger to the negative-feedback loop: today
+`Mistakes.record` fires only *reactively* (a tool blew up, or a human said
+"that's wrong"). `extro_verify` lets the agent catch itself being wrong about
+the world **before** a human does. `commit: false` returns the verdict without
+side-effects.
+
+### `revalidate_memory` — the browser as GC for `PWN::Memory`
+
+`learning_consolidate` only dedupes/truncates; it never asks *"is this still
+true?"*. `PWN::AI::Agent::Extrospection.revalidate_memory` walks every
+`PWN::Memory` `:fact` containing a CVE / version string / URL, runs `verify()`
+on it, and prefixes stale ones with `[UNVERIFIED yyyy-mm-dd]` so the injected
+MEMORY block stops calcifying into confidently-wrong priors. Schedule it:
+
+```ruby
+cron_create(name: 'memory_revalidate', schedule: '0 4 * * 0',
+            ruby: 'PWN::AI::Agent::Extrospection.revalidate_memory')
+```
+
+### Configuration
+
+```ruby
+PWN::Env[:ai][:agent][:extrospection][:web] = {
+  anchors:          ['https://target.acme/api/version', …],  # else DEFAULT_WEB_ANCHORS
+  proxy:            'tor',      # or 'http://127.0.0.1:8080' (Burp) — honoured by verify/watch/probe_web
+  max_anchors:      8,
+  per_page_timeout: 15,
+  screenshot:       false,      # → ~/.pwn/extrospection/web/<host>.png
+  allow_targets:    false       # OPSEC: also fingerprint PWN::Env[:targets] (active recon!)
+}
+```
+
+
 ## Typical engagement flow
 
 ```ruby
 extro_reset(confirm: true)             # clean slate for new scope
-extro_snapshot                         # baseline (all six sections)
+extro_snapshot                         # baseline (six local sections; add sections:%i[web] for anchors)
 # … recon …
 extro_observe(source: 'nmap', target: '10.0.0.5',
               category: 'recon', data: 'OpenSSH 8.2p1 Ubuntu')
 extro_observe(source: 'gqrx', target: '433.920MHz',
               category: 'rf', data: 'peak -34.2 dBFS bw=200k FSK — likely garage remote')
 extro_intel(query: 'OpenSSH 8.2p1', record: true)
+extro_watch(url: 'https://target.acme/api/version')       # DOM-hash + screenshot; changed:true on next run
+extro_verify(claim: 'CVE-2026-12345 affects OpenSSL 3.2.1')  # → Mistakes/Memory/observe on verdict
 # … days later, something breaks …
 extro_drift                            # what moved?
 extro_correlate                        # why did it break?
 ```
 
 **See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
-[Mistakes](Mistakes.md) · [SDR](SDR.md) · [pwn-ai Agent](pwn-ai-Agent.md)
+[Mistakes](Mistakes.md) · [SDR](SDR.md) · [Transparent Browser](Transparent-Browser.md) · [Cron](Cron.md) · [pwn-ai Agent](pwn-ai-Agent.md)
 
 [← Home](Home.md)

data/documentation/Home.md

@@ -36,10 +36,10 @@
 | | |
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama |
-| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 52 LLM-callable tools |
+| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 54 LLM-callable tools |
 | [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection — the self-improvement loop |
 | [Mistakes](Mistakes.md) | **Negative feedback** — fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
-| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · correlate · **rf** |
+| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · **watch** · **verify** · correlate · **rf** · **web** |
 | [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
 | [Sessions](Sessions.md) | Transcript persistence + reflection |
 | [Cron](Cron.md) | Scheduled autonomous jobs |

data/documentation/How-PWN-Works.md

@@ -27,7 +27,7 @@ hardware).
 | Module | Role |
 |---|---|
 | `Loop` | plan → dispatch tool_calls → observe → repeat until final answer |
-| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · 52 tools |
+| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · 54 tools |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / EXTROSPECTION blocks |
 | `Metrics` · `Learning` | **introspection** — how well am I doing? |

data/documentation/Mistakes.md

@@ -42,7 +42,7 @@ PromptBuilder <-------------------- Mistakes.to_context     (KNOWN MISTAKES + KN
 model --(tool call)---------------> mistakes_record / mistakes_resolve
 ```
 
-## Four ingest paths — nothing slips through
+## Five ingest paths — nothing slips through
 
 | Source | Trigger | What is recorded |
 |---|---|---|
@@ -50,6 +50,7 @@ model --(tool call)---------------> mistakes_record / mistakes_resolve
 | `:loop` | iteration budget exhausted with no final answer | *automatic* — `Loop.run` epilogue |
 | `:user_correction` | next user message matches `CORRECTION_RX` (*"no that's wrong"*, *"still broken"*, *"try again"*, …) | `check_user_correction` — also flips the previous `Learning` outcome to `success:false` |
 | `:model` | the model itself calls `mistakes_record` | wrong assumption, wrong file, hallucinated API — failures that are **not** dispatch errors |
+| **`:model` (proactive)** | **`extro_verify(claim:)` returns `:refuted`** | **`Mistakes.record(tool:'assumption', error:'REFUTED …: <claim>')` — the browser caught the model being wrong about the world *before* a human did** |
 
 ## Tools