pwn 0.5.621 → 0.5.626

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0708b22c22f49ec48a8263fe296b3dea6055d87259fe6bd6f63b484049432d6a'
-  data.tar.gz: 7b0dd573b0e169afd93e8ae228a40d02b4331fcf989a78df884cfdd5649fac8a
+  metadata.gz: 67a226a1a110698db44ee0378d3f9a5fd290d96d633487a3dd4a7e72c1ac09d9
+  data.tar.gz: 8acea5ce6ab68d30486aef426c176611f379a31acf3092cdea7ced91e8dbf8e9
 SHA512:
-  metadata.gz: 840dd2114e03a96ecc79fad15d9204f18d1ce5f444561fe230d0da5ca3e6a35f4d93a41c6c69cf3d87b37edf46e5bbd64ca0cbe4440b1a3ef9a268b5f918b39b
-  data.tar.gz: 0a18d690d4bc222a319500c7301c20f8a9629111e11498489ddf7516b6c2afe5ab6d6daf20354bea580688ad58bd7b85708f699cfe9c399dc8f1d23f65391bb1
+  metadata.gz: 48c6bca36c123d6419ee8fd12ff6813e2ab405b4fbd92fb31d1c64aea4ca3a2f75ee25e06e5db61d6db9d58775f8228b51783396c1c8e688dcf6afd224720025
+  data.tar.gz: 022c9adac00e0ccab76bbd4f6c86d603a32a55ce41e4e0b7d6093a59e52834b4692dbb700bb0e1c8ee2ba50bc0be1a5dd6db0fc80b76308d34188be1f623ce25

data/.rubocop.yml

@@ -16,9 +16,9 @@ Metrics/ClassLength:
 Metrics/CyclomaticComplexity:
   Max: 158
 Metrics/MethodLength:
-  Max: 733
+  Max: 800
 Metrics/ModuleLength:
-  Max: 1592
+  Max: 2900
 Metrics/PerceivedComplexity:
   Max: 157
 Style/HashEachMethods:

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

@@ -1,5 +1,11 @@
 ![PWN](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/PWN.png)
 
+<p align="center">
+  <img src="documentation/pwn_silent_help_learn_demo.gif" alt="PWN Silent Demo — Help Surfaces + Learning Feedback Loop" width="640">
+  <br>
+  <em>Silent walkthrough: <code>pwn</code> help surfaces → <code>pwn-ai</code> → recon → mistakes / learning / extrospection feedback loop</em>
+</p>
+
 ### **Table of Contents** ###
 
 - [Intro](#intro)
@@ -52,7 +58,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 + **Web** (extrospection) — plus browser-backed **`extro_verify`** self fact-checking — via `extro_correlate`, so the
+Snapshot + Drift + Intel + RF + **Web** (extrospection) — plus browser-backed **`extro_verify`** / **`extro_watch`** and RF **`extro_rf_tune`** sensing — 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/bin/pwn_gqrx_scanner

@@ -76,8 +76,8 @@ PWN::Driver::Parser.new do |options|
     opts[:fft_scan] = f
   end
 
-  options.on('--sample-rate=RATE', '<Optional --fft-scan - Visible span/sample_rate in Hz (default 1_000_000). NOTE: no short flag; -S is --strength-lock>') do |s|
-    opts[:sample_rate] = s
+  options.on('--input-rate=RATE', '<Optional --fft-scan - GQRX Input rate / visible span in Hz (default 1_000_000). NOTE: no short flag; -S is --strength-lock>') do |s|
+    opts[:input_rate] = s
   end
 
   options.on('-NINT', '--nfft=INT', '<Optional --fft-scan - FFT bin size (default 2048)>') do |n|
@@ -100,13 +100,21 @@ PWN::Driver::Parser.new do |options|
     opts[:strength_offset_db] = o
   end
 
-  options.on('--min-snr-db=FLOAT', '<Optional --fft-scan - Minimum SNR (dB above per-chunk noise floor) to report a signal (default 12.0)>') do |m|
+  options.on('--min-snr-db=FLOAT', '<Optional --fft-scan - Minimum SNR (dB above per-chunk noise floor) to report a signal (default 18.0)>') do |m|
     opts[:min_snr_db] = m
   end
 
-  options.on('--min-bw-ratio=FLOAT', '<Optional --fft-scan - Reject FFT peaks narrower than RATIO * band-plan bandwidth as spurs (default 0.30)>') do |r|
+  options.on('--min-bw-ratio=FLOAT', '<Optional --fft-scan - Reject FFT peaks narrower than RATIO * band-plan bandwidth as spurs (default 0.0 = off)>') do |r|
     opts[:min_bw_ratio] = r
   end
+
+  options.on('--no-refine', '<Optional --fft-scan - Skip the post-FFT iterative edge/peak refine pass that locks the exact channel frequency (default: refine ON)>') do
+    opts[:refine] = false
+  end
+
+  options.on('--refine-mode=MODE', '<Optional --fft-scan - Refine strategy: lock (default, fast S-meter raster hunt), fft (legacy local high-res FFT zoom), hybrid (both)>') do |m|
+    opts[:refine_mode] = m
+  end
 end.parse!
 
 begin
@@ -122,13 +130,55 @@ begin
   end
 
   profile = opts[:profile]
+
+  # Common user-facing aliases → canonical band_plans keys.
+  # (historical/typo names should not crash with Hash#merge! TypeError)
+  profile_aliases = {
+    'flex_pager' => 'pager_flex',
+    'flex' => 'pager_flex',
+    'pocsag_pager' => 'pager_pocsag',
+    'pocsag' => 'pager_pocsag',
+    'pager' => 'pager_all',
+    'pagers' => 'pager_all',
+    'adsb' => 'ads_b1090',
+    'adsb1090' => 'ads_b1090',
+    'adsb978' => 'ads_b978',
+    'fm' => 'fm_radio',
+    'noaa' => 'noaa_weather',
+    'wx' => 'noaa_weather',
+    'weather' => 'noaa_weather'
+  }.freeze
+
+  resolve_band_plan = lambda do |name|
+    return nil if name.nil?
+
+    key = name.to_s.strip.downcase.tr('-', '_').to_sym
+    key = profile_aliases[key.to_s].to_sym if profile_aliases.key?(key.to_s)
+    return key if band_plans.key?(key)
+
+    # fuzzy suggestions for helpful errors
+    cand = band_plans.keys.map(&:to_s)
+    suggestions = cand.select do |k|
+      k.include?(key.to_s) || key.to_s.include?(k) ||
+        k.split('_').intersect?(key.to_s.split('_'))
+    end
+    suggestions = cand.grep(/#{Regexp.escape(key.to_s.split('_').first)}/i) if suggestions.empty? && !key.to_s.empty?
+    msg = "ERROR: Unknown band plan profile: #{name.inspect}."
+    msg += " Did you mean: #{suggestions.sort.first(8).join(', ')}?" unless suggestions.empty?
+    msg += ' Use --list-band-plans to display supported profiles.'
+    raise msg
+  end
+
+  profile_key = resolve_band_plan.call(profile)
+  warn "[*] alias #{profile.inspect} → band plan #{profile_key}" if profile_key && profile.to_s.strip.downcase.tr('-', '_') != profile_key.to_s
+
   # Merge opts with profile values if profile provided
-  opts.merge!(band_plans[profile.to_sym]) unless profile.nil?
+  opts.merge!(band_plans[profile_key]) unless profile_key.nil?
 
   scan_ranges = opts[:scan_ranges]
-  raise 'ERROR: --assume-band-plan || --scan-ranges is required.' if scan_ranges.nil? && profile.nil?
+  raise 'ERROR: --assume-band-plan || --scan-ranges is required.' if scan_ranges.nil? && profile_key.nil?
 
-  ranges = band_plans[profile.to_sym][:ranges] unless profile.nil?
+  ranges = band_plans[profile_key][:ranges] unless profile_key.nil?
   if ranges.nil?
     # Convert comma-delimited string to array of hashes
     ranges = scan_ranges.split(',').map do |r|
@@ -179,11 +229,19 @@ begin
   location = opts[:location]
 
   # Merge opts one last time to ensure parameters passed to the driver are included
-  opts.merge!(band_plans[profile.to_sym]) unless profile.nil?
+  opts.merge!(band_plans[profile_key]) unless profile_key.nil?
 
   fft_scan = opts[:fft_scan]
-  sample_rate = opts[:sample_rate] || 1_000_000
+  # Prefer (1) explicit --input-rate, (2) band-plan :input_rate from
+  # FrequencyAllocation (merged above), (3) historic 1 Msps default.
+  # GQRX device Input rate is separate from this *assumption* — use
+  # PWN::SDR::GQRX.apply_band_plan_input_rate to push the plan rate into
+  # ~/.config/gqrx/*.conf for the connected SDR.
+  # Local var + fast_scan_range kwarg remain sample_rate for library parity.
+  sample_rate = opts[:input_rate] || 1_000_000
   sample_rate = sample_rate.to_i
+  puts "[*] input_rate (FFT/scan chunk / IQ span assumption): #{sample_rate} Hz" \
+       "#{" (band plan #{profile_key})" if profile_key}"
   nfft = opts[:nfft] || 2048
   nfft = nfft.to_i
   avgv = opts[:avg] || 8
@@ -200,6 +258,11 @@ begin
 
   if fft_scan
     puts '[*] --fft-scan requested: using fast FFT panoramic mode (#fast_scan_range)'
+    refine_flag = opts.fetch(:refine, true)
+    puts "[*] band-plan / session params: mode=#{demodulator_mode.inspect} bw=#{bandwidth.inspect} " \
+         "squelch=#{squelch.inspect} precision=#{precision} decoder=#{decoder.inspect} " \
+         "rf_gain=#{rf_gain.inspect} if_gain=#{intermediate_gain.inspect} bb_gain=#{baseband_gain.inspect} " \
+         "refine=#{refine_flag}"
     fast_resp = PWN::SDR::GQRX.fast_scan_range(
       gqrx_sock: gqrx_sock,
       ranges: ranges,
@@ -213,9 +276,15 @@ begin
       min_snr_db: min_snr_db,
       precision: precision,
       min_bw_ratio: min_bw_ratio,
+      refine: opts.fetch(:refine, true),
+      refine_mode: opts[:refine_mode] || :lock,
       demodulator_mode: demodulator_mode,
       bandwidth: bandwidth,
       squelch: squelch,
+      audio_gain_db: audio_gain_db,
+      rf_gain: rf_gain,
+      intermediate_gain: intermediate_gain,
+      baseband_gain: baseband_gain,
       decoder: decoder,
       location: location,
       scan_log: scan_log

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 · 54 tools)
+## Toolsets → Tools  (10 toolsets · 61 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_watch`** · **`extro_verify`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ `PWN::Plugins::TransparentBrowser`) → `~/.pwn/extrospection.json` |
+| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/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,320 @@
-# 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         # Optional ambient baseline (host/repo/env ONLY — never launches burpsuite/zaproxy/msf/gqrx). Sense tools (intel/verify/watch/rf_tune/observe) stay on-demand.
+    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).
+      rf:
+        host: 127.0.0.1            # GQRX remote-control host for extro_rf_tune.
+        port: 7356                 # GQRX remote-control port.
+        settle_secs: 8             # Seconds to sample RDS after tuning (max 30).
+        ttl: 300                   # Observation TTL for :rf (songs change — keep short).
+
+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.
+| `ai.agent.extrospection.rf.host` | String | `127.0.0.1` | `Extrospection.rf_tune` | GQRX remote-control host for the RF sense organ. |
+| `ai.agent.extrospection.rf.port` | Integer | `7356` | `Extrospection.rf_tune` | GQRX remote-control port. |
+| `ai.agent.extrospection.rf.settle_secs` | Integer | `8` | `Extrospection.rf_tune` | Seconds to sample RDS after tuning (capped at 30). |
+| `ai.agent.extrospection.rf.ttl` | Integer | `300` | `Extrospection.rf_tune` | TTL (seconds) for `:rf` observations written by `extro_rf_tune` (ephemeral radio content). |
 ```
 
+---
+
 ## 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` | 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.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,9 +37,11 @@ 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
-also updates Learning/Metrics/Extrospection — so tomorrow's interactive
-session already knows what changed overnight.
+`pwn-ai` turn. With `auto_introspect` on (and optional `auto_extrospect` for
+the cheap `AUTO_SECTIONS` baseline), the run updates Learning/Metrics — and,
+if enabled, host/repo/env posture — so tomorrow's interactive session already
+knows what changed overnight. Sense tools (`intel`/`verify`/`watch`) stay
+on-demand; cron is not expected to launch Burp/ZAP/msf/GQRX.
 
 ```ruby
 cron_create(

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 · 54 tools)
+### Agent Tool Registry (10 toolsets · 61 tools)
 [source](diagrams/dot/agent-tool-registry.dot) · doc: [Agent Tool Registry](Agent-Tool-Registry.md)
 ![agent-tool-registry](diagrams/agent-tool-registry.svg)