pwn 0.5.784 → 0.5.787

data/etc/default_skills/pwn/ai/agent/mission_namespace/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: pwn-ai-agent-mission-namespace
+description: Compiler-free Linux mission process ownership.
+preserve: true
+metadata:
+  bundled: true
+  module: PWN::AI::Agent::MissionNamespace
+  source: pwn/ai/agent/mission_namespace.rb
+---
+
+# PWN::AI::Agent::MissionNamespace
+
+Launch typed mission descriptors using util-linux `unshare`, Ruby stdlib
+Fiddle pidfds, and private inherited sockets. Install `pwn setup --profile ai`.
+Linux user/PID namespaces and pidfds must be enabled. Unsupported hosts fail
+closed; there is no process-group or uncontained fallback.
+
+The controller remains outside namespaces. Each request transfers its private
+configuration snapshot in memory, then owns a PID namespace. Cancellation kills
+namespace PID 1 and waits for the supervisor to reap it. Arbitrary Ruby closures
+are only supported inside an already-owned mission for protected tool workers.

data/etc/default_skills/pwn/ai/agent/tools/browser_act/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pwn-ai-agent-tools-browseract
+description: Drive PWN::Ai::Agent::Tools::BrowserAct from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Ai::Agent::Tools::BrowserAct
+  source: pwn/ai/agent/tools/browser_act.rb
+---
+
+# PWN::Ai::Agent::Tools::BrowserAct
+
+Public API for PWN::Ai::Agent::Tools::BrowserAct.
+
+## When to use
+
+Call `PWN::Ai::Agent::Tools::BrowserAct` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/ai/agent/tools/browser_act.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::Ai::Agent::Tools::BrowserAct.help
+PWN::Ai::Agent::Tools::BrowserAct.help(opts)
+```
+
+## Public methods
+
+- _(no public class methods parsed)_
+
+## Source
+
+`pwn/ai/agent/tools/browser_act.rb`
+
+## Verification
+
+`PWN::Ai::Agent::Tools::BrowserAct.respond_to?(:help)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/ai/agent/tools/loot_query/SKILL.md

@@ -1,45 +1,46 @@
 ---
 name: pwn-ai-agent-tools-lootquery
-description: Drive PWN::Ai::Agent::Tools::LootQuery from pwn_eval.
+description: Query and capture encrypted engagement loot.
 license: MIT
 allowed-tools: [pwn, pwn_eval]
 metadata:
   bundled: true
-  generated: true
-  module: PWN::Ai::Agent::Tools::LootQuery
+  generated: false
   source: pwn/ai/agent/tools/loot_query.rb
 ---
 
-# PWN::Ai::Agent::Tools::LootQuery
+# loot_query
 
-Public API for PWN::Ai::Agent::Tools::LootQuery.
-
-## When to use
-
-Call `PWN::Ai::Agent::Tools::LootQuery` from `pwn_eval` when the task needs this module.
-Do not reimplement it in shell.
-
-## Methodologies
-
-Generated from `pwn/ai/agent/tools/loot_query.rb`. Prefer the public class methods below.
-Class methods take `(opts = {})` and read `opts`.
+Use the registered `loot_query` tool to query, store, ingest, or offer engagement
+loot. This file registers a tool; it does not define a `Tools::LootQuery` module.
 
 ## How to call
 
-```ruby
-PWN::Ai::Agent::Tools::LootQuery.help
-PWN::Ai::Agent::Tools::LootQuery.help(opts)
-```
-
-## Public methods
+Select `op: query` (the default) with `engagement`, `host`, `service`, `kind`, or
+`finding_id` filters to obtain metadata without plaintext credentials. The Vault
+query handler does not decrypt or open a device. Dispatch's separate output
+redaction can require access to stored hardware secrets.
 
-- _(no public class methods parsed)_
+For `store` or `ingest`, pass `yubikey: {slot: 2, serial: "12345678", timeout: 30}`
+only when hardware protection is intended. The slot must already be provisioned
+for HMAC-SHA1. An empty selector chooses hardware defaults. The model-facing
+schema allows only `slot`, `serial`, and `timeout`; never put a PIN, PUK, key,
+password, or executable path in the selector. `offer` can use the same selector
+when decrypting matching hardware loot.
 
-## Source
+## Pitfalls
 
-`pwn/ai/agent/tools/loot_query.rb`
+- Missing hardware or failed touch raises; do not retry with software protection.
+- Replacing an existing hardware label without a selector retains that backend.
+- Treat `offer` results as secrets. Dispatch redacts array results before returning
+  them; direct Ruby callers must not print or persist plaintext credentials.
+- `VAULT_EXPANSION_FAILED` means Dispatch did not execute the handler.
+  `VAULT_REDACTION_FAILED` with `handler_executed: true` means it already ran;
+  reconcile effects before retrying.
 
 ## Verification
 
-`PWN::Ai::Agent::Tools::LootQuery.respond_to?(:help)` after the
-module is loaded. Read the source for parameter names.
+Use `PWN::AI::Agent::Registry.lookup(name: 'loot_query')` to inspect its schema
+and handler after discovery. Offline tests stub only the device HMAC boundary,
+use an isolated home, verify encrypted loot has no disk master key, and reject
+selector executable overrides through Dispatch before any vault access.

data/etc/default_skills/pwn/ai/agent/tools/recon_run/SKILL.md

@@ -1,39 +1,48 @@
 ---
 name: pwn-ai-agent-tools-reconrun
-description: Drive PWN::Ai::Agent::Tools::ReconRun from pwn_eval.
+description: Run recon pipelines with optional hardware-protected loot.
 license: MIT
 allowed-tools: [pwn, pwn_eval]
 metadata:
   bundled: true
-  generated: true
+  preserve: true
   module: PWN::Ai::Agent::Tools::ReconRun
   source: pwn/ai/agent/tools/recon_run.rb
 ---
 
-# PWN::Ai::Agent::Tools::ReconRun
+# recon_run registry tool
 
-Public API for PWN::Ai::Agent::Tools::ReconRun.
+Use the registered `recon_run` tool or `PWN::Plugins::Recon.run`; this file
+registers a tool, not a Ruby class named `PWN::Ai::Agent::Tools::ReconRun`.
 
 ## When to use
 
-Call `PWN::Ai::Agent::Tools::ReconRun` from `pwn_eval` when the task needs this module.
-Do not reimplement it in shell.
+Run selected recon modules against a single authorized target and persist their
+asset/evidence model. Scanner observations are not proven findings.
 
 ## Methodologies
 
-Generated from `pwn/ai/agent/tools/recon_run.rb`. Prefer the public class methods below.
-Class methods take `(opts = {})` and read `opts`.
+Supply `target` and a nonempty `modules` array from `nmap`, `banner`, `tls`,
+`subfinder`, `nuclei`. Optional `ports`, `engagement_id`, positive `timeout` up to
+300 seconds and `ingest` control the pipeline; tool ingestion defaults to true.
 
 ## How to call
 
-```ruby
-PWN::Ai::Agent::Tools::ReconRun.help
-PWN::Ai::Agent::Tools::ReconRun.help(opts)
+```json
+{"target":"app.example.test","modules":["banner"],"ports":[443],"ingest":false,"yubikey":{"slot":2}}
 ```
 
-## Public methods
+## Hardware protection
 
-- _(no public class methods parsed)_
+The optional `yubikey` selector accepts only integer `slot` 1/2, decimal String
+`serial`, and positive `timeout` seconds. An empty object chooses hardware
+defaults. It forwards into Vault ingestion without provisioning or software
+fallback. Device access errors remain failures. PINs, seeds, arbitrary executable
+paths and secret selector fields are forbidden by the tool schema.
+
+Only harvested loot is hardware encrypted. Raw scanner evidence and the asset
+model remain ordinary files; protect those separately. Do not claim a completed
+scan when harvesting failed, or replay an expensive scan blindly after device loss.
 
 ## Source
 
@@ -41,5 +50,6 @@ PWN::Ai::Agent::Tools::ReconRun.help(opts)
 
 ## Verification
 
-`PWN::Ai::Agent::Tools::ReconRun.respond_to?(:help)` after the
-module is loaded. Read the source for parameter names.
+Run `spec/lib/pwn/ai/agent/tools/recon_run_spec.rb` and
+`spec/lib/pwn/ai/agent/tools/recon_run_yubikey_spec.rb`. The latter exercises the
+real handler/Recon/Vault path with fake socket/device boundaries and no live scan.

data/etc/default_skills/pwn/ai/agent/tools/workspace_tool/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pwn-ai-agent-tools-workspacetool
+description: Drive PWN::Ai::Agent::Tools::WorkspaceTool from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Ai::Agent::Tools::WorkspaceTool
+  source: pwn/ai/agent/tools/workspace_tool.rb
+---
+
+# PWN::Ai::Agent::Tools::WorkspaceTool
+
+Public API for PWN::Ai::Agent::Tools::WorkspaceTool.
+
+## When to use
+
+Call `workspace_tool` when the task needs a provider-hosted tool. Ask Jev is
+an Open WebUI workspace tool. Do not reimplement it in shell.
+
+## Source
+
+`pwn/ai/agent/tools/workspace_tool.rb`

data/etc/default_skills/pwn/ai/server_tools/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: pwn-ai-servertools
+description: Use provider-hosted tools without replacing Registry client tools.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::AI::ServerTools
+  source: pwn/ai/server_tools.rb
+---
+
+# PWN::AI::ServerTools
+
+Open WebUI is the only engine with a user-installed tool workspace. Ask Jev
+runs there through `workspace_tool` or `chat(server_tools:)`. Do not send a
+client `tools` array on that same Open WebUI request.
+
+Anthropic, Gemini, and OpenAI Responses can carry their fixed hosted tools
+beside Registry tools. xAI hosted tools use the Responses API, not
+chat/completions. Ollama has no server-side tool workspace.
+
+## Source
+
+`pwn/ai/server_tools.rb`

data/etc/default_skills/pwn/backups/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: pwn-backups
+description: Drive PWN::Backups from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Backups
+  source: pwn/backups.rb
+---
+
+# PWN::Backups
+
+All first-party recovery copies share one serialized seven-generation store. Evidence artifacts are not recovery copies and must not enter this store.
+
+## When to use
+
+Call `PWN::Backups` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/backups.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::Backups.help
+PWN::Backups.active(opts)
+```
+
+## Public methods
+
+- `active`
+- `transaction`
+- `directory`
+- `capture`
+- `configure`
+- `reconcile`
+- `relocate_legacy`
+- `authors`
+- `help`
+- `active?`
+
+## Source
+
+`pwn/backups.rb`
+
+## Verification
+
+`PWN::Backups.respond_to?(:active)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/plugins/recon/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [pwn, pwn_eval]
 metadata:
   bundled: true
   generated: true
+  preserve: true
   module: PWN::Plugins::Recon
   source: pwn/plugins/recon.rb
 ---
@@ -26,9 +27,19 @@ Class methods take `(opts = {})` and read `opts`.
 
 ## How to call
 
+Pass an explicit `yubikey: {slot: 2, serial: '12345678', timeout: 30}` to `run`
+or `harvest_loot` to encrypt harvested credentials with an already provisioned
+HMAC-SHA1 OTP slot. Both entry points preserve the selector through Vault.ingest.
+Device failure raises without falling back to a software master key. Raw scan
+evidence remains governed by the existing recon persistence contract; selecting
+hardware loot protection does not encrypt the entire asset/evidence directory.
+
+Verify offline with a fake banner and a stubbed 20-byte challenge-response; assert
+the saved loot envelope has the hardware KDF and no `.pwn-vault.key` is created.
+
 ```ruby
 PWN::Plugins::Recon.help
-PWN::Plugins::Recon.required_bins(opts)
+PWN::Plugins::Recon.required_bins
 ```
 
 ## Public methods

data/etc/default_skills/pwn/plugins/yubikey/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: pwn-plugins-yubikey
+description: Manage YubiKeys with explicit mutation guards.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey
+  source: pwn/plugins/yubikey.rb
+---
+
+# PWN::Plugins::YubiKey
+
+Use the native Ruby wrapper around the official `ykman` executable. Never
+provision, overwrite, repair or reset a slot as part of routine inventory,
+authentication or vault access. See `documentation/YubiKey.md` for the device
+contract and `documentation/YubiKey-Vaults.md` for storage/recovery integration.
+
+## When to use
+
+- Inventory and application status, or explicit YubiKey management requests.
+- Binary HMAC-SHA1 challenge-response from an **already provisioned** OTP slot.
+- OATH account listing and retrieval with consent for authentication, remembered-key
+  cleanup, counter and credential-repair effects.
+- Do not use device management as a substitute for browser WebAuthn ceremonies.
+
+## Prerequisites
+
+Install the official `yubikey-manager` separately. `required_bins` returns
+`['ykman']`; `available?` probes `--version` without opening a device. Use a trusted
+explicit `ykman:` path when PATH selection is unsuitable. The reviewed management
+grammar is 5.9.1; automatic provisioning intentionally accepts only that version.
+Use decimal String serials, integer slots 1 or 2, and a finite positive timeout.
+
+## How to call
+
+```ruby
+PWN::Plugins::YubiKey.help
+PWN::Plugins::YubiKey.available?
+PWN::Plugins::YubiKey.devices
+PWN::Plugins::YubiKey.info(serial: '12345678')
+PWN::Plugins::YubiKey.otp(args: ['info'], serial: '12345678')
+PWN::Plugins::YubiKey.cli_help(path: %w[piv keys generate])
+```
+
+Serials above are placeholders. Family methods take an `args:` argv Array after
+the family name; omission returns official help. Use long options as separate
+array elements, not a shell string or `--option=value`. `command` takes the full
+management argv. All return raw output without logging it; successful output can
+still contain secrets and must not be echoed into a transcript.
+
+## Public methods
+
+- `required_bins`, `available?`, `devices`, `info`, `cli_help`, `help`, `authors`
+- `command`, `interact`, `config`, `otp`, `oath`, `fido`, `piv`, `openpgp`, `hsmauth`,
+  `security_domain` (official **sd** family), `apdu`
+- `challenge_response`, `provision_challenge_response`, `oath_code`
+
+## Procedure
+
+1. Identify the intended device and application with read-only inventory. Pin a
+   serial when selecting a device; never choose the first key automatically.
+2. Read the specific command's help. The wrapper guards the complete reviewed
+   management tree, but model/firmware/interface support still belongs to ykman.
+3. Obtain explicit `confirm: true` for every non-allowlisted operation, including
+   resets, provisioning, authentication attempts, exports, OATH listing/calculation and
+   all raw APDUs. Unknown commands stay rejected even after consent. Do not add
+   `--force` merely to make a command succeed.
+4. Keep credentials out of argv, environment variables, history and logs. Generic
+   calls close stdin. Use `interact(args: ..., confirm: true)` only in a private
+   operator terminal outside curses/recorded tool sessions. It bridges a native
+   PTY, returns only `:completed`, restores terminal mode and descriptor status flags,
+   and bounds total traffic and elapsed time, including human input. Its terminal
+   must be readable and writable, including the Ruby wrapper mode; validation
+   consumes no input and never closes caller-owned IO. Some upstream secret prompts
+   are not masked. Never guess a PIN. Key imports and SCP11 use protected existing files;
+   custom SCP03 import KIDs are refused before filename checks, even when the
+   inline key string names an existing file. SCP11 file-import KIDs accept unsigned
+   decimal, `0x` hex or `SCP11a`/`SCP11b`/`SCP11c` names, without coercion.
+5. Read the exact result or device state after a mutation. A timeout is uncertain
+   device state, not proof that nothing changed. Do not automatically retry.
+
+### Existing HMAC slot
+
+```ruby
+challenge = SecureRandom.random_bytes(32)
+response = PWN::Plugins::YubiKey.challenge_response(
+  challenge: challenge, slot: 2, serial: '12345678', timeout: 30
+); nil
+```
+
+Pass **raw 1–64 bytes**, not pre-encoded hex. The wrapper sends `otp calculate
+SLOT HEX_CHALLENGE` and returns exactly **20 binary bytes**. Slot 2 is only a
+selector default, never implicit provisioning. Touch the device if required;
+the wrapper suppresses the CLI's stderr prompt. The challenge is public in argv;
+never use a password as the challenge. Keep the response out of transcripts.
+
+### Explicit provisioning
+
+Only after inspecting the slot and obtaining consent, use
+`provision_challenge_response(key: key_bytes, serial: serial, slot: 2,
+confirm: true)`. `key_bytes` must be exactly 20 raw bytes acquired in local memory,
+not a literal pasted into a console. The method checks ykman 5.9.1, supplies a
+validated key/consent sequence through stdin without `--force`, enables touch,
+and verifies a fresh random challenge with Ruby OpenSSL before returning
+`:verified`. It overwrites the slot. Plan and test independent recovery before
+discarding the key. Protected slots and other CLI versions require the separately
+reviewed private-terminal workflow described in `documentation/YubiKey.md`.
+No Ruby zeroization guarantee is made.
+
+### Exact OATH
+
+`oath_code(account: exact_identifier, serial: serial, confirm: true)` returns
+6–8 digits, retaining leading zeros, or raises. It verifies a unique full
+inventory identifier and the returned account label; substring-only, ambiguous,
+changed-identity and nonnumeric output is refused. Official 5.9.1 has **no
+--exact** option; `--single` alone is not exact matching. Confirmation is mandatory
+for listing too: upstream may authenticate using a remembered key and delete/persist
+that key if authentication fails, even without `--remember`. HOTP advances counters
+and upstream code can delete corrupted credentials automatically. Do not treat
+this as a read-only operation or use it for SMS/passkey
+challenges. Password-protected OATH may require the private terminal workflow.
+
+## Pitfalls
+
+- Missing executable, unsupported device capability or malformed output is an
+  error, not permission to reset, provision or fall back to a software key.
+- `ykman script`, debug/traffic logging, secret argv fields, arbitrary stdin and
+  unreviewed future commands are intentionally unavailable.
+- Raw APDU bytes are visible in argv. Never put credentials in arbitrary payloads;
+  the wrapper cannot infer their confidentiality.
+- Noninteractive mutations needing prompts can abort/time out. Confirmation in
+  Ruby does not bypass the CLI's own confirmation except the fixed provisioning
+  stdin flow; no force flag is inserted.
+- `timeout` defaults to 30 seconds and combined output to 1 MiB. Timeout/output
+  failures kill the Unix child process group and reap the direct child. This is
+  not a sandbox against a malicious executable escaping its process group.
+- FIDO credential/PIN/fingerprint management is not website authentication.
+  Browser and relying party must perform genuine security-key ceremonies.
+
+## Verification
+
+Run the paired offline suites:
+
+```text
+bundle exec rspec spec/lib/pwn/plugins/yubikey_spec.rb spec/lib/pwn/plugins/yubikey_security_spec.rb spec/lib/pwn/plugins/yubikey_terminal_spec.rb
+bundle exec rubocop lib/pwn/plugins/yubikey.rb spec/lib/pwn/plugins/yubikey_spec.rb spec/lib/pwn/plugins/yubikey_security_spec.rb spec/lib/pwn/plugins/yubikey_terminal_spec.rb
+```
+
+Specs exercise real child processes with fake device executables, argument guards,
+binary HMAC vectors, exact OATH parsing, validated provisioning, private PTY
+prompts, descriptor/terminal restoration on success and failure, pre-spawn duplex
+validation without consuming input, and cleanup. The
+real 5.9.1 CLI's management help tree and Click stdin contract were separately
+checked offline. None of this proves USB/NFC hardware, physical touches, PIN
+protection, every firmware variant, or live website login. Report those boundaries.