pwn 0.5.784 → 0.5.785

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b180063b404ae6511a5df181eb969dcf2970b1ac128225369d6ec69afb30cc
-  data.tar.gz: 7936dc0f2c4552327650e74f3f0af790da4fbd353ca5d48cb651542d3f550acd
+  metadata.gz: fef74967cd315acf1e070378d8e12000d552604b8d0f273d42638014d0a13a8c
+  data.tar.gz: 3d68aa5c28678b95a4b20acbe878a36c6d0cd8c04357ee3d18c768a7e0435c75
 SHA512:
-  metadata.gz: 1184f82a572f136b6421f04059b5e05e79642e7f68337f376392c816aeb023b0bd0d74c15f0916c84078ad7188d255f0776ac04d2a87cbb31e9ee8fa59e6dc16
-  data.tar.gz: 851035353589425ab5ff5fdefb04c9c2a1f2c91fce7cb5d1e02067bd0eebb16905284bbf6cd7cde6373fa2ea9b7b1f6dbf531089ee9319988bd62ec7e83cdeb1
+  metadata.gz: '0871b196e754cfe2134ba0372f4108b24113d9a1f7b0355257b31a032833c4b91bd1e52f53ff467a4e9e817375b9138b5691c15ef621c6026a34d32672f77d2b'
+  data.tar.gz: 2fef6064addee1ba16706d641f19af7a8bbf99432dfb1a13426fbd1d534d01b89d4a7f4dced9db9ad934d30db94dfcf908e88c993cb779424b706a0296db1cd2

data/.ruby-version

@@ -1 +1 @@
-4.0.6
+4.0.9

data/Gemfile

@@ -49,8 +49,8 @@ gem 'jwt', '3.3.0'
 gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
-gem 'mcp', '1.8.2'
-gem 'meshtastic', '0.0.189'
+gem 'mcp', '1.9.0'
+gem 'meshtastic', '0.0.192'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.26.0'
 gem 'msfrpc-client', '1.1.2'
@@ -59,7 +59,7 @@ gem 'net-ldap', '0.21.0'
 gem 'net-openvpn', '0.8.7'
 gem 'net-smtp', '0.5.2'
 gem 'nexpose', '7.3.0'
-gem 'nokogiri', '1.19.4'
+gem 'nokogiri', '1.19.7'
 gem 'nokogiri-diff', '0.3.0'
 gem 'oily_png', '1.2.1'
 gem 'open3', '0.3.0'
@@ -81,7 +81,7 @@ gem 'rmagick', '7.2.0'
 gem 'rqrcode', '3.2.0'
 gem 'rspec', '3.13.2'
 gem 'rtesseract', '3.1.4'
-gem 'rubocop', '1.92.1'
+gem 'rubocop', '1.92.2'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
 gem 'ruby-audio', '1.6.1'
@@ -89,8 +89,8 @@ gem 'ruby-nmap', '1.0.3'
 gem 'ruby-saml', '1.18.1'
 gem 'rvm', '1.11.3.9'
 gem 'savon', '2.17.5'
-gem 'selenium-devtools', '0.155.0'
-gem 'selenium-webdriver', '4.51.0'
+gem 'selenium-devtools', '0.156.0'
+gem 'selenium-webdriver', '4.52.0'
 gem 'slack-ruby-client', '3.3.0'
 gem 'socksify', '1.8.1'
 gem 'spreadsheet', '1.3.5'

data/README.md

@@ -9,6 +9,7 @@
 - [Intro](#intro)
   * [What is PWN](#what-is-pwn)
   * [Why PWN](#why-pwn)
+    * [Vault and Sandboxing](#vault-and-sandboxing)
   * [How PWN Works](#how-pwn-works)
 - [Documentation](#documentation)
 - [Installation](#installation)
@@ -88,6 +89,42 @@ is driving security decisions without you watching every click.
 
 Full page: [Why PWN](documentation/Why-PWN.md)
 
+##### **Vault and Sandboxing** #####
+
+Agentic security research, bug bounty hunting and penetration testing put
+credentials, client evidence and untrusted target content in the same tool loop.
+Vault and sandboxing reduce accidental secret persistence and limit local damage
+from untrusted PoCs or target-supplied prompt injection:
+
+- **Keep secrets separate from the conversation.** [Vault](lib/pwn/plugins/vault.rb)
+  encrypts configuration and captured credential values at rest. Use
+  `{{vault:label}}` references: [Dispatch](lib/pwn/ai/agent/dispatch.rb) resolves
+  them at the tool boundary and redacts known stored secrets from returned results.
+  Together with transcript/log redaction, this reduces copying raw secrets into
+  prompts, logs and reusable context. Store/query loot under explicit engagement
+  IDs with host/service/finding provenance. Use unique labels: reference expansion
+  can search across engagements, so these IDs are not credential access controls.
+- **Contain tool effects, not just model instructions.** The
+  [mandatory runtime boundary](documentation/Runtime-Source-Protection.md) uses
+  Linux workers to separate tool writes from protected source and controller state;
+  [mission containment](documentation/Mission-Cancellation.md) owns their descendants.
+  Unnamed writes default to `~/.pwn/workspaces/runtime`. Other destinations must
+  come from the original operator request, not tool output; naming a file can
+  grant its parent directory. Protected source stays read-only even if named.
+  Missing required Landlock/seccomp or namespace support makes execution fail closed.
+  Optional `strict`/`permissive`/`off` profiles do not disable that mandatory boundary.
+
+**Know the limits.** Encryption at rest does not protect secrets from an active
+process that has unlocked them or promise LLM-provider privacy. Vault is not
+whole-filesystem or evidence/artifact encryption, and redaction can miss secrets.
+Sandboxing is not authorization, complete network isolation, a perfect container,
+or a guarantee against bugs or prompt injection. Operators still need target
+authorization and scope, least-privilege credentials, and separate evidence access,
+retention and encryption controls.
+
+Details: [Configuration](documentation/Configuration.md) ·
+[Optional hardware-backed vaults and recovery](documentation/YubiKey-Vaults.md)
+
 #### **How PWN Works** ####
 
 PWN is five layers. Dependencies only point downward, so each level stays

data/bin/pwn

@@ -81,7 +81,8 @@ begin
       warn result.to_s[0, 700]
     end
 
-    final = PWN::AI::Agent::Loop.run(
+    require 'pwn/plugins/repl/ai'
+    final = PWN::Plugins::REPL.pwn_ai_run_steerable(
       request: prompt,
       session_id: sess[:id],
       enabled_toolsets: PWN::Env.dig(:ai, :agent, :toolsets),

data/bin/pwn_web_cache_deception

@@ -33,6 +33,18 @@ PWN::Driver::Parser.new do |options|
     opts[:mfa] = f
   end
 
+  options.on('--yubikey-account=NAME', '<Optional - Exact OATH account; supports GitHub, Synack, Twitter, BugCrowd, CoinbasePro, AppCobaltIO; Paypal SMS adapter unsupported; requires --yubikey-confirm; enables MFA even with --no-mfa; never an OTP slot>') do |name|
+    opts[:yubikey_account] = name
+  end
+
+  options.on('--yubikey-confirm', '<Required with --yubikey-account - Explicit OATH consent: HOTP advances counters; ykman may authenticate/delete remembered keys and delete corrupted OATH credentials>') do |confirm|
+    opts[:yubikey_confirm] = confirm
+  end
+
+  options.on('--yubikey-serial=SERIAL', '<Optional - Decimal YubiKey serial; requires --yubikey-account>') do |serial|
+    opts[:yubikey_serial] = serial
+  end
+
   options.on('-pPROXY', '--proxy=PROXY', '<Optional - HTTP or Socks Proxy || tor>') do |p|
     opts[:proxy] = p
   end
@@ -60,6 +72,24 @@ pwn_www_mod_str = opts[:pwn_www_mod_str].to_s.scrub.strip.chomp
 
 username = opts[:username].to_s.scrub.strip.chomp
 
+yubikey = nil
+raise ArgumentError, 'YubiKey serial requires --yubikey-account with an exact OATH account name' if opts[:yubikey_account].nil? && !opts[:yubikey_serial].nil?
+raise ArgumentError, '--yubikey-confirm requires --yubikey-account with an exact OATH account name' if opts[:yubikey_account].nil? && !opts[:yubikey_confirm].nil?
+
+unless opts[:yubikey_account].nil?
+  supported_oath_modules = %w[GitHub Synack Twitter BugCrowd CoinbasePro AppCobaltIO]
+  raise ArgumentError, "YubiKey OATH is supported only with --pwn-www-mod=#{supported_oath_modules.join('|')}; the Paypal adapter is SMS-only" unless supported_oath_modules.include?(pwn_www_mod_str)
+
+  yubikey = { account: opts[:yubikey_account], confirm: opts[:yubikey_confirm] }
+  unless opts[:yubikey_serial].nil?
+    serial = opts[:yubikey_serial]
+    raise ArgumentError, 'YubiKey serial must be a decimal string without whitespace' unless serial.is_a?(String) && serial.match?(/\A[0-9]+\z/)
+
+    yubikey[:serial] = serial
+  end
+  PWN::Plugins::AuthenticationHelper.validate_mfa_options(yubikey: yubikey, mfa: opts[:mfa], mfa_token: opts[:mfa_token])
+end
+
 password = opts[:password] # Don't cast to string to detect if PWN::Plugins::AuthenticationHelper is necessary
 if password.nil?
   password = PWN::Plugins::AuthenticationHelper.mask_password
@@ -67,11 +97,7 @@ else
   password = opts[:password].to_s.scrub.strip.chomp
 end
 
-if opts[:mfa]
-  mfa = true
-else
-  mfa = false
-end
+mfa = opts[:mfa] || false
 
 proxy = opts[:proxy].to_s.scrub.strip.chomp unless opts[:proxy].nil?
 
@@ -151,12 +177,14 @@ begin
       browser_obj = pwn_www_mod.open(browser_type: :chrome)
     end
     # Now AuthN via PWN::WWW::<MODULE>
-    browser_obj = pwn_www_mod.login(
+    login_opts = {
       browser_obj: browser_obj,
       username: username,
       password: password,
       mfa: mfa
-    )
+    }
+    login_opts[:yubikey] = yubikey unless yubikey.nil?
+    browser_obj = pwn_www_mod.login(login_opts)
     puts "#{@green}complete.#{@end_of_color}\n\n\n"
   elsif pwn_www_mod_str == '' && proxy
     browser_obj = PWN::Plugins::TransparentBrowser.open(

data/documentation/AI-Integration.md

@@ -15,7 +15,7 @@ agent code never cares which model is behind it.
 | `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) - see skill `xai_grok_oauth_device_flow` |
 | `gemini` | `PWN::AI::Gemini` | `key:` | function-calling native |
 | `ollama` | `PWN::AI::Ollama` | none (stock) | Direct Ollama server (default `http://127.0.0.1:11434`). Native `/api/chat` (`num_ctx`, `num_predict`, `keep_alive`, low `tool_temp`) and `/api/embed` for `PWN::MemoryIndex`. No prefix-cache field. |
-| `openwebui` | `PWN::AI::OpenWebUI` | `key:` (JWT / API token) + `base_uri:` | Open WebUI gateway - OpenAI-compatible `/api/v1/chat/completions` plus proxied Ollama `/ollama/api/*` (including embed) |
+| `openwebui` | `PWN::AI::OpenWebUI` | `key:` (JWT / API token) + `base_uri:` | Open WebUI gateway - OpenAI-compatible `/api/v1/chat/completions` plus proxied Ollama `/ollama/api/*`. Workspace tools such as Ask Jev run server-side through `tool_ids` on `chat` / `workspace_tool`. A client `tools` array on that same request disables them. |
 
 > PWN is **model-agnostic**. `ai.<engine>.model` is passed straight through to
 choose a provider-supported model ID (or a tag from `ollama list`).
@@ -56,12 +56,14 @@ The trailing `nil` prevents the console from echoing the returned bearer.
 Successful enrollment updates the live environment and calls the private
 `persist_oauth_to_vault` helper, as token refresh does. It uses the configured
 `driver_opts.pwn_env_path` and `pwn_dec_path`, defaulting to
-`~/.pwn/pwn.yaml` and its `.decryptor` file. Existing decryption artifacts are
-required; missing artifacts leave tokens in the session only and produce a
+`~/.pwn/pwn.yaml` and its legacy `.decryptor` file. A [YubiKey vault](YubiKey-Vaults.md)
+uses its hardware selector instead and does not need a software sidecar.
+Unavailable credentials or hardware leave tokens in the session only and produce a
 notice. Tokens are not printed by the enrollment success message.
 
-Persistence retains unrelated settings and the existing key/IV, encrypts a
-private temporary file, and replaces the vault only after encryption succeeds.
+Persistence retains unrelated settings and the encryption backend, decrypts and
+merges in memory, writes only ciphertext to a private temporary file, and
+replaces the vault only after encryption succeeds.
 The resulting vault has mode `0600`. The original vault remains unchanged on
 a persistence failure; the helper does not create or rotate decryptor secrets.
 

data/documentation/Agent-Tool-Registry.md

@@ -6,13 +6,13 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 
 ![Tool registry](diagrams/agent-tool-registry.svg)
 
-## Toolsets to tools  (16 toolsets · 150 tools)
+## Toolsets to tools  (16 toolsets · 152 tools)
 
 | Toolset | Tools | Backed by |
 |---|---|---|
 | `http` | `http_proxy_start` · `http_proxy_stop` · `http_proxy_entries` · `http_proxy_rules` · `http_replay` | `PWN::Plugins::MitmProxy`: native HTTP HAR capture/replay; opaque CONNECT tunnels |
 | `terminal` | `pty_expect` · `job_run` · `job_status` · `job_result` · `job_tail` · `job_kill` · `pty_open` · `pty_send` · `pty_read` · `pty_close` · `pty_session` · `shell` | Foreground host commands plus `PWN::Plugins::Jobs` durable supervisors |
-| `pwn` | `binary_triage` · `browser_goto` · `capabilities` · `debug_session` · `gdb_run_to_crash` · `binary_diff` · `crash_triage` · `emulate` · `detonate` · `decompile` · `exploitdev` · `finding_record` · `finding_report` · `chain_score` · `fuzz_campaign` · `intel_lookup` · `loot_query` · `nmap_scan` · `nuclei_scan` · `r2_functions` · `r2_disasm` · `recon_run` · `pwn_eval` · `sandbox_run` · `sandbox_fuzz` · `sbom_scan` · `swarm_map` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard`; SBOM engines via `PWN::Plugins::SBOM` store CVE leads as recon observations, not findings; r2pipe JSON via `PWN::Plugins::Radare2`; gdb MI3 crash reports via `PWN::Plugins::GDBMI`; nmap XML ingest/diff via `PWN::Plugins::NmapIt`, which skips a known port unless `refresh: true`; nuclei/httpx JSONL via `PWN::Plugins::Nuclei` writes a recon observation (a template match is not a finding) and accepts a `Recon.handoff` record; TransparentBrowser navigation captures screenshot/DOM/HAR via `browser_goto`; engagement loot via `PWN::Plugins::Vault` |
+| `pwn` | `binary_triage` · `browser_goto` · `browser_act` · `workspace_tool` · `capabilities` · `debug_session` · `gdb_run_to_crash` · `binary_diff` · `crash_triage` · `emulate` · `detonate` · `decompile` · `exploitdev` · `finding_record` · `finding_report` · `chain_score` · `fuzz_campaign` · `intel_lookup` · `loot_query` · `nmap_scan` · `nuclei_scan` · `r2_functions` · `r2_disasm` · `recon_run` · `pwn_eval` · `sandbox_run` · `sandbox_fuzz` · `sbom_scan` · `swarm_map` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard`; SBOM engines via `PWN::Plugins::SBOM` store CVE leads as recon observations, not findings; r2pipe JSON via `PWN::Plugins::Radare2`; gdb MI3 crash reports via `PWN::Plugins::GDBMI`; nmap XML ingest/diff via `PWN::Plugins::NmapIt`, which skips a known port unless `refresh: true`; nuclei/httpx JSONL via `PWN::Plugins::Nuclei` writes a recon observation (a template match is not a finding) and accepts a `Recon.handoff` record; TransparentBrowser navigation captures screenshot/DOM/HAR via `browser_goto`; engagement loot via `PWN::Plugins::Vault` |
 | `mcp` | `mcp` | `PWN::AI::MCP` session broker → any `PWN::AI::MCP::*` stdio client |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` · `memory_lean` | `PWN::Memory` → `~/.pwn/memory.json` |
 | `skills` | `skills_recall` · `skills_update` · `skill_list` · `skill_view` · `skill_create` · `skills_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` · `skills_consolidate` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |

data/documentation/Backup-Retention.md

@@ -1,27 +1,82 @@
-# Historical migration backup retention
+# Shared recovery backup retention
 
-## Explicit legacy diagnostic and generated-copy expiry
+All PWN-owned recovery producers use `PWN::Backups` and the single
+`~/.pwn/backup` store. The limit is **seven total generation folders**, not seven
+per producer. Producer payloads and recovery receipts are grouped inside their
+transaction's generation. No new adjacent learning, preference, skill or
+Terminator `.bak` / `.pwnbak` files are produced.
 
-`PWN::SessionCleanup.expire_legacy` is a separate, explicit maintenance entry point, defaulting to a preview. Apply requires `dry_run: false` and a **new external** `manifest:` path for one compressed metadata ledger; it does not archive payloads back into the managed home or run session/swarm retirement.
+## Producers
 
-Only recognized expired closed request logs, the exact `learning.jsonl.bak-lean-YYYYMMDD` and `preferences.jsonl.bak-p15-YYYYMMDDhhmmss` recovery families, and verified duplicate BinaryParser triage caches qualify. Root recovery retains at least the latest three nonempty parseable copies per family, all literal reference pins, and copies younger than thirty days. Cache expiry requires byte-identical retained ArtifactRegistry evidence; absent inputs are not claimed reproducible. Decompiler stdout caches are not adopted by this policy.
+| Producer | Contents |
+| --- | --- |
+| Migrate | Exact registry-owned state paths, encrypted configuration and decryptor; verified snapshot manifest; no recursive logs/cache/backup copies |
+| Learning | Learning rewrites and original evidence-migration index |
+| Reward | Preference rewrite recovery |
+| SkillReview / SkillConsolidation | Original skill bytes |
+| PolicyEvaluation | Pinned routing-policy rollback snapshot |
+| Setup | Original Terminator configuration |
+| SessionCleanup | Session/layout recovery, dependency removal, continuation retirement and disposable quarantine payloads with their recovery receipts |
 
-The operation holds the canonical maintenance lock, rejects unsafe path/inode identities, checks retained references without exposing content, and checks process descriptors before classification and unlink. Existing producer leases must be available. Retained recovery/evidence proofs and candidate hashes are rechecked before unlink. An unreadable process inventory fails closed; do not bypass it when an older client is active. Coordinate any legacy writers before applying, and keep the learning producer lock during root recovery expiry. The external ledger records prepared versus completed state; it is not an undo archive. Existing immutable workers require a separately verified matched release before this entry point is deployed; it is not automatically enabled by importing the source.
+Immutable learning evidence, artifacts, evaluation inputs and user-requested
+exports are not disposable backup generations. Device read/write backup commands,
+GitHub gist exports and Jenkins-to-S3 transfer operate on operator-selected data,
+not PWN's internal recovery state.
 
-## Migration generations
+## Admission, locking and failures
 
-Migration backups are recovery generations, not an indefinite archive of every distinct historical byte. `PWN::Migrate.prune_backups` stays duplicate-only until an operator explicitly authorizes historical expiry. Its optional `expire_history: true` argument or private `~/.pwn/backup/.retention-policy.json` enables generation retention:
+The permanent `.retention.lock` serializes cooperating producers. Maintenance
+acquires its maintenance lock, then the Learning writer lock, then the backup
+lock. Ordinary backup producers acquire Learning before backups and never acquire
+maintenance. Learning reentrancy is bound to the owning PID and thread; an
+attempt to acquire Learning underneath an unowned backup transaction is rejected.
+Maintenance still defers when the Learning writer is busy.
 
-```json
-{"version":1,"expire_history":true,"keep":3,"pins":[]}
-```
+Before a new folder is admitted, oldest completed, unpinned generations may be
+expired to make room. Prepared/interrupted generations, explicit pins and current
+literal evidence references remain protected. Malformed reference data fails
+closed when expiry would be needed. Pins count **inside** the seven-folder limit:
+if they occupy capacity, the next producer fails before modifying its source.
+Unknown legacy folders count toward capacity but are not silently certified or
+expired. A pre-existing over-limit store can therefore block admission until an
+explicit offline remediation is performed; importing this source does not fix a
+live store or grant permission to prune it.
 
-`keep` cannot be less than three. `pins` contains exact timestamp generation directory names. Current structured evidence paths and prepared/interrupted or explicitly pinned maintenance records also retain their referenced generations. Quoted directory inventories and historical prose are not evidence dependencies. No logs, metrics, or historical learning versions are copied aside merely because their bytes are unique.
+Transactions publish `prepared` before payload/source changes and `complete`
+only after successful return. Exceptions, interrupted/blocked results and failed
+receipts leave prepared recovery. Copies are hash-verified and fsynced. Keep the
+transaction open through source mutation and receipt publication. Restoring one
+store does not undo all children of a maintenance operation.
 
-Before expiry, the newest retained point must cover every existing current migration-owned input path, and current encrypted configuration and decryptor bytes must match retained recovery copies. Every retained and expiring payload is hashed, current inputs and references are rechecked, symlinks are rejected, and deletion shares the snapshot producer's permanent `.retention.lock`. The ordinary maintenance transaction supplies its own maintenance lock and cooperative work admission. Manual backup-only calls must also coordinate live writers before apply. Default automatic batches consider at most ten older generations; exhausted admission defers expiry rather than weakening protection.
+Use the owning store's recovery API (`SessionCleanup.recover`,
+`Learning.rollback_evidence`, skill review rollback or policy rollback) first.
+`Backups.reconcile` only acknowledges recovery: it requires the exact generation,
+its inspected manifest SHA-256 and explicit confirmation. It retains a pin by
+default; `pinned: false` permits normal retention but does not override live
+references. It does not restore payloads or declare a failed operation successful.
+Never edit shared/hardlinked historical payloads in place; restore by copying.
 
-The single mode-0600 `.retention-manifest.json.gz` contains prepared/committed inventories and expiry names, not a second payload tree. Older unpinned versions are permanently expired: that manifest is an audit record, not an undo payload. Incomplete historical snapshots are never retrospectively certified complete. Their extant payloads can be verified for bounded recovery; the newly produced complete snapshot establishes current coverage. Restore by **copying only migration-owned paths**, not overlaying an entire old home, and never edit hardlinked backup bytes in place. Keep explicit pins for any recovery boundary needed during an active migration.
+## Upgrade and legacy relocation
 
-Scheduled retention is called by the managed v10 `SessionCleanup.maintain` helper through PWN's internal cron worker. No native scheduler or systemd installation is needed. Use `PWN::Migrate.prune_backups(dry_run: true)` for a strictly backup-only preview; do not invoke full session maintenance to test backup expiry. When no generation can expire, this preview avoids scanning evidence bodies and reports `evidence_scan: not_needed_no_expiry`; it is not a fresh payload-integrity audit.
+Schema 12 changes the existing retention policy from three to seven, preserving
+pins and other policy fields. A second migration is byte-stable. The old
+`Migrate.prune_backups` entry point is a compatibility report only; it cannot run
+an independent three-generation pruning policy. Retention happens at producer
+admission, not via another scheduler.
 
-An isolated maintenance release may coexist with older interactive clients: run the worker from the release's immutable `lib` load path, verify source/release/live-helper SHA-256 equality, and leave the active gem and clients untouched. The cron helper does not retrofit methods into those clients. A later normal application upgrade is separate from this scoped maintenance deployment.
+`Backups.relocate_legacy(paths: ..., dry_run: true)` previews exact recognized
+legacy paths. Applying requires `dry_run: false, writers_stopped: true`, owned
+non-symlink sources, unchanged verified copies and no references to their old
+paths. The shared generation contains an origin mapping before originals are
+removed. Unknown, referenced or over-capacity inputs must be resolved explicitly,
+not bypassed. Existing cleanup recovery readers remain available for legacy
+ledgers. Legacy diagnostic/cache expiry is a separate explicit operation and is
+not a new backup producer.
+
+## Deployment boundary
+
+Source changes do not upgrade installed gems, existing clients or immutable cron
+releases. Deploy a matched release and restart only explicitly authorized
+processes separately. Use only PWN's existing internal cron worker; no systemd,
+native scheduler, live provider calls or live backup pruning is required for
+fixture verification. Tests must use an isolated HOME and scratch storage.

data/documentation/Configuration.md

@@ -5,18 +5,22 @@ Provider and plugin configuration lives in **one encrypted YAML file**, loaded b
 constant **`PWN::Env`** (whose nested settings are mutable) (a redacted copy is available as
 `PWN::EnvRedacted`).
 
-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, and reloads `PWN::Env`. If `PWN::Config` rejects the
+The file is **AES-encrypted at rest** by `PWN::Plugins::Vault`. Legacy CBC key/IV
+values live in a sibling **`~/.pwn/pwn.yaml.decryptor`** file (or in
+`PWN_DECRYPTOR_KEY` / `PWN_DECRYPTOR_IV` env vars). Explicitly selected
+[YubiKey vaults](YubiKey-Vaults.md) instead use an authenticated hardware-derived
+AES-GCM envelope and need no software decryptor. Never edit ciphertext by hand;
+use the **`pwn-vault`** REPL command, which edits a private temporary copy,
+re-encrypts before replacing the original, and reloads `PWN::Env`. If `PWN::Config` rejects the
 edited file, the editor reopens until the vault loads cleanly, so you do not
 leave the REPL stuck on a decrypt / re-edit / encrypt loop.
 
 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.
+generates the legacy decryptor. `default_env(yubikey: { slot: 2 })` explicitly
+selects hardware protection for a new vault and omits that sidecar; it does not
+provision the device slot or silently convert an existing file.
 
 > **Before configuring**, run `pwn setup` - the
 > [doctor](Installation.md#pwn-setup--the-post-install-doctor--provisioner)

data/documentation/Contributing.md

@@ -6,7 +6,7 @@
 lib/pwn/                # all namespaces
 lib/pwn/setup.rb        # PWN::Setup - doctor/provisioner data tables
 lib/pwn/migrate.rb      # PWN::Migrate - ~/.pwn state doctor / auto-migrator
-lib/pwn/plugins/        # 107 top-level plugin autoloads
+lib/pwn/plugins/        # 108 top-level plugin autoloads
 lib/pwn/ai/agent/       # agent core
 lib/pwn/ai/agent/tools/ # LLM tool registrations
 bin/                    # 56 executables: 53 pwn_* drivers + pwn / pwn-ai / pwn-capd (incl. pwn_setup)

data/documentation/Cron.md

@@ -9,8 +9,8 @@ jobs require that worker, while manual commands do not. `--no-cron` disables
 the internal worker without changing host services.
 
 **Housekeeping must never use systemd or another native scheduler.**
-The three enabled housekeeping defaults below use only this existing worker
-or manual commands. `install_native_job` and each platform-specific job
+The one enabled housekeeping default, `session_cleanup`, uses only this existing
+worker or a manual command. `install_native_job` and each platform-specific job
 installer explicitly skip housekeeping (`housekeeping_internal_only`),
 including recognizable cleanup payloads under another name. Native worker
 contexts exclude housekeeping from ticks and direct job execution.

data/documentation/Diagrams.md

@@ -24,7 +24,7 @@ a dependency guarantee. External services/radios require separate live verificat
 [source](diagrams/dot/persistence-filesystem.dot) · doc: [Persistence](Persistence.md)
 ![persistence-filesystem](diagrams/persistence-filesystem.svg)
 
-### Plugin Ecosystem (107 modules)
+### Plugin Ecosystem (108 modules)
 [source](diagrams/dot/plugin-ecosystem.dot) · doc: [Plugins](Plugins.md)
 ![plugin-ecosystem](diagrams/plugin-ecosystem.svg)
 
@@ -69,7 +69,7 @@ a dependency guarantee. External services/radios require separate live verificat
 [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 (16 toolsets · 150 tools)
+### Agent Tool Registry (16 toolsets · 152 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/General-PWN-Usage.md

@@ -18,13 +18,14 @@ $ pwn setup --migrate --fix   # after `gem update pwn`: verify + autofix ~/.pwn
 ```
 
 See [Installation](Installation.md) for every flag and the
-`PWN::Setup` / `PWN::Migrate` API.
+`PWN::Setup` / `PWN::Migrate` API. Unspecified `pwn-ai` writes use
+`~/.pwn/workspaces/runtime`; see [Operability](Operability.md).
 
 ## Inside the REPL
 
 ```ruby
 PWN.help                            # top-level help
-PWN::Plugins.constants.sort         # list all 107 plugins
+PWN::Plugins.constants.sort         # list all 108 plugins
 PWN::Plugins::NmapIt.help           # per-plugin usage
 PWN::Setup.check                    # capability doctor from inside the REPL
 PWN::Migrate.status                 # ~/.pwn state-file compatibility rows
@@ -40,7 +41,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-mesh` | Meshtastic serial / bluetooth / TCP / MQTT client (Ruby ≥ 4.0) |
-| `pwn-vault` | Decrypt → edit `~/.pwn/pwn.yaml` in `$EDITOR` → re-encrypt |
+| `pwn-vault` | Edit a private temporary copy, then replace `~/.pwn/pwn.yaml` only after encryption succeeds (legacy or YubiKey) |
 | `pwn-ai-memory` | Inspect / edit `~/.pwn/memory.json` |
 | `pwn-ai-sessions` | List / view / delete transcripts |
 | `pwn-ai-cron` | List / run scheduled jobs |

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.
-> 107 plugins · 48 SAST modules · 90 AWS wrappers · 22 WWW drivers · 56 CLI
+> 108 plugins · 48 SAST modules · 90 AWS wrappers · 22 WWW drivers · 56 CLI
 > executables · 6 LLM engines · a self-improving multi-agent AI · one REPL.
 
 **Repo root:** `/opt/pwn` · **This wiki:** `/opt/pwn/documentation/` ·
@@ -19,7 +19,7 @@
 | [How PWN Works](How-PWN-Works.md) | The five layers, with the architecture diagram |
 | [Installation](Installation.md) | `gem install --verbose pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
-| [Operability and Evidence](Operability.md) | Completion, regressions, frozen evaluation, mesh and deployment boundaries |
+| [Operability and Evidence](Operability.md) | Runtime writes, backups, cron, completion and deployment boundaries |
 | [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
 | **[All Data-Flow Diagrams](Diagrams.md)** | **29 SVGs** in one scrollable page |
 
@@ -37,7 +37,7 @@
 | | |
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama · Open WebUI |
-| [Agent Tool Registry](Agent-Tool-Registry.md) | 16 toolsets · **150** LLM-callable tools |
+| [Agent Tool Registry](Agent-Tool-Registry.md) | 16 toolsets · **152** LLM-callable tools |
 | [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection, reviewed skill updates and bundled SOP/module skills on first launch |
 | [Mistakes](Mistakes.md) | **Negative feedback** - fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
 | [Reinforcement Learning](Reinforcement-Learning.md) | **`Reward` + `Curriculum` + `Policy`** - outcome/process judges · preference ledger · self-play practice · live Q / REINFORCE (advisory) · export-ready LoRA gate |
@@ -45,19 +45,20 @@
 | [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
 | [Sessions](Sessions.md) | Transcript persistence + reflection |
 | [Session Workflow](Session-Workflow.md) | Keywords: `continue` / last session / write-then-read |
-| [Cron](Cron.md) | Scheduled jobs. Hygiene seeds on; curriculum practice/judge/train ship off |
+| [Cron](Cron.md) | Scheduled jobs. Fresh install seeds one `session_cleanup` coordinator; curriculum is not seeded |
 
 ## 🧩 Capability Namespaces  (`lib/pwn/*`)
 
 | | |
 |---|---|
-| [Plugins (107)](Plugins.md) | Every `PWN::Plugins::*` module by category |
+| [Plugins (108)](Plugins.md) | Every `PWN::Plugins::*` module by category |
 |   ↳ [BurpSuite](BurpSuite.md) ⭐ | Preferred web proxy / scanner |
 |   ↳ [TransparentBrowser](Transparent-Browser.md) | Headless / visible browser automation |
 |   ↳ [NmapIt](NmapIt.md) | Network discovery |
 |   ↳ [Metasploit](Metasploit.md) | RPC exploitation |
 |   ↳ [Fuzzing](Fuzzing.md) | `Fuzz` · `Sock` · `Packet` |
 |   ↳ [Hardware](Hardware.md) | Serial · BusPirate · MSR206 · Android · BareSIP |
+|   ↳ [YubiKey](YubiKey.md) | Device management, hardware vaults and OATH MFA |
 | [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
 | [WWW (22 drivers)](WWW.md) | Browser automations for real sites |
 | [AWS (90 services)](AWS.md) | Cloud-security enumeration |

data/documentation/How-PWN-Works.md

@@ -28,7 +28,7 @@ hardware).
 |---|---|
 | `Loop` | plan → **TaskSummarizer** briefs → dispatch tool_calls → observe → repeat until `may_finalize?`. No iteration-budget abort |
 | **`TaskSummarizer`** | Executive UX: every request gets an English task compass (`emit_plan!` · `about_to` as `task k/n`) - no statement/question/goal type |
-| `Registry` | JSON-Schema function definitions grouped into 16 **toolsets** · **150 tools** · `CORE_TOOLS` = `DEFAULT_PREFERENCE` (`memory_recall` · `session_recall` · `skills_recall` · `pwn_eval` · `shell` · `mistakes_record` · `mistakes_resolve` · `learning_note_outcome` · `memory_remember` · `skills_update` · `artifact_read` · `artifact_grep` · `job_run` · `job_status` · `job_tail` · `job_result` · `job_kill`) |
+| `Registry` | JSON-Schema function definitions grouped into 16 **toolsets** · **152 tools** · `CORE_TOOLS` = `DEFAULT_PREFERENCE` (`memory_recall` · `session_recall` · `skills_recall` · `pwn_eval` · `shell` · `mistakes_record` · `mistakes_resolve` · `learning_note_outcome` · `memory_remember` · `skills_update` · `artifact_read` · `artifact_grep` · `job_run` · `job_status` · `job_tail` · `job_result` · `job_kill`) |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / **POLICY** / EXTROSPECTION / RECENT TURNS |
 | `Metrics` · `Learning` · `Reflect` · **`Policy`** | **introspection** - how well am I doing? (Policy is live Q / REINFORCE, advisory rank only) |
@@ -44,7 +44,7 @@ call, and [Reinforcement Learning](Reinforcement-Learning.md) for how
 
 ## L3 - Capability namespaces (`lib/pwn/*`)
 
-`Plugins` (107) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
+`Plugins` (108) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
 `Bounty` · `Reports` · `FFI` · `Banner` · **`Setup`** · **`Migrate`**. First launch also seeds bundled skills from `etc/default_skills/`. Each is
 a plain module of `public_class_method def self.x(opts = {})` methods -
 callable the same way from the REPL, from `pwn_eval`, or from a driver.
@@ -74,9 +74,10 @@ Q / REINFORCE only for eligible resolved outcomes with independently attributed
 (MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS ·
 POLICY · EXTROSPECTION · RECENT TURNS) are re-injected into the next system
 prompt.
-Nightly hygiene cron trims `~/.pwn` stores. Curriculum practice, offline
-judge, and weekly LoRA train ship seeded but disabled; turn them on with
-`cron_enable` when you want that loop.
+Nightly hygiene is the one seeded `session_cleanup` coordinator. It is not three
+separate enabled jobs, and it does not use systemd. Curriculum practice, offline
+judge, and weekly LoRA train are optional templates; they are not seeded, and
+deleting them does not cause the next launch to recreate them.
 
 `Metrics.esr` is `verified_exploit_tools / vulnerable_tools`. `Metrics.asr` is `successful_attacks / total_attack_attempts`. `Learning.rsi_tick` compares ESR with the previous snapshot and writes a lesson when it falls. A file hash, a nuclei template match, or a CVE id does not move ESR. Only a reproduced exploit does.
 

data/documentation/Installation.md

@@ -34,7 +34,7 @@ anchors:
 | state | `swarm/`, `cron/`, `agents.yml`, `jobs/`, `missions/`, `runs/`, metrics | Preserve continuation associations and active work |
 | logs | `logs/` | Only explicitly registered disposable closed logs are eligible; unknown logs remain |
 | cache | `cache/` | Only producer-registered, checksum-verified, inactive disposable files |
-| tmp | `tmp/` | Same registration contract; never glob-delete arbitrary temp files |
+| tmp | `workspaces/runtime/` | Same registration contract; never glob-delete arbitrary temp files |
 | maintenance | `maintenance/`, legacy `session_cleanup_archive/` | Policy, permanent locks, metadata ledgers and recoverable quarantine |
 
 `maintenance/policy.json` is non-secret JSON, version 1. `batch_size` defaults to
@@ -42,7 +42,7 @@ anchors:
 `work_seconds: 30` and `work_bytes: 67108864` for dependency and maintenance
 payload reads, plus reserved disposable backup writes. Existing policy
 files acquire these defaults in memory, without rewriting operator values.
-`maintenance/layout.json` upgrades recognized inventory v1 to v2 separately from
+`maintenance/layout.json` upgrades recognized inventory v1 or v2 to v3 separately from
 policy; unknown inventory versions are refused. `retention_days` defaults to sessions 0, logs 30,
 cache 7, tmp 1, maintenance 90. Null disables that category's expiry. Session
 age is an additional floor, never an override of leases, provenance or evidence.
@@ -149,7 +149,7 @@ deployment or provider run is implied.
 
 The audit covers `Dir.tmpdir`, `Tempfile`, `mktmpdir` and atomic replacement
 call sites, not a filesystem filename sweep:
-- Festival speech input now uses `SessionCleanup.temporary` in `~/.pwn/tmp`, with
+- Festival speech input now uses `SessionCleanup.temporary` in `~/.pwn/workspaces/runtime`, with
   a lifetime lease and exact registration. Concurrent calls have unique names;
   normal completion unlinks the input and a crashed consumer leaves registered bytes.
 - Ghidra/BinaryParser canonical cache publication and managed temporary inputs
@@ -315,7 +315,7 @@ pwn setup --list-profiles
 | `vision` | `OCR` · `ScannableCodes` · `Reports` · `extro_vision` · tesseract / zbar / graphviz |
 | `voice` | `PWN::Plugins::Voice` · `extro_voice` · espeak-ng / sox |
 | `exploit` | `Metasploit` · `sqlmap` |
-| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `extro_serial` · `extro_telecomm` |
+| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `YubiKey` (`ykman`) · `extro_serial` · `extro_telecomm` |
 | `re` | `Radare2` · `GDB` · `ExploitDev` · `Frida` · Android RE (`apktool`/`jadx`) · `pwndbg` · `ropper` · `rizin` |
 | `full` | everything above |
 
@@ -365,7 +365,8 @@ What `--migrate` does:
    (`PWN::Migrate::STATE_FILES` - no re-implemented parsers). If the raw
    file has bytes but the owner returned its empty-fallback, the file is
    flagged incompatible.
-3. **Autofix** (with `--fix`): timestamped backup under `~/.pwn/backup/<ts>/`
+3. **Autofix** (with `--fix`): one shared recovery generation under
+   `~/.pwn/backup/` (seven folders total; see [Backup Retention](Backup-Retention.md))
    → ordered schema migrations → per-file repair (quarantine corrupt to
    `~/.pwn/quarantine/`, re-seed missing dirs, strip unparsable JSONL lines,
    convert legacy flat skills to the [agentskills.io](https://agentskills.io)
@@ -410,8 +411,10 @@ and schedule-only deletion. Already-running old binaries must be upgraded before
 their startup/config-refresh hooks can be relied on to honor the new defaults.
 
 **Housekeeping never uses systemd or any other native scheduler.**
-`session_cleanup`, `learning_consolidate_nightly`, and `pwn_stores_lean_nightly`
-run only through PWN's built-in cron worker or manual commands. Native job
+`session_cleanup` is the only seeded housekeeping job. It runs only through
+PWN's built-in cron worker or a manual command. Older split names
+(`learning_consolidate_nightly`, `pwn_stores_lean_nightly`) are not seeded and
+are not removed automatically. Native job
 installers explicitly skip them with `housekeeping_internal_only`; this also
 covers renamed payloads that invoke `SessionCleanup` or `session_cleanup.rb`.
 Generic scheduler APIs remain available for unrelated custom jobs. Native
@@ -680,7 +683,7 @@ row as `MISSING` until a key is set.
 Everything above is a thin CLI over two autoloaded modules:
 
 ```ruby
-PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch: }
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch:, native_libraries_missing: }
 PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
 PWN::Setup.list_profiles
 PWN::Setup.migrate(fix: true)             # thin wrapper → PWN::Migrate.run
@@ -715,7 +718,7 @@ Vagrant, CI) picks it up automatically.
 ```ruby
 pwn[CURRENT_VERSION]:001 >>> PWN::Setup.check[:ok]          # => true
 pwn[CURRENT_VERSION]:002 >>> PWN::Migrate.needed?           # => false
-pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 107
+pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 108
 pwn[CURRENT_VERSION]:004 >>> PWN::SAST.constants.count      # => 48
 pwn[CURRENT_VERSION]:005 >>> pwn-ai                         # launches agent TUI
 ```