pwn 0.5.784 → 0.5.787

data/documentation/What-is-PWN.md

@@ -12,7 +12,7 @@ with a **tool-calling AI agent** on top that can run the same methods.
 
 | Namespace | Count | What it is |
 |---|---|---|
-| `PWN::Plugins::*` | **107** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
+| `PWN::Plugins::*` | **108** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, YubiKey, ...) |
 | `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
 | `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
 | `PWN::WWW::*` | **22** | Site-specific browser automations (HackerOne, BugCrowd, GitHub, Google, LinkedIn, ...) |
@@ -20,7 +20,7 @@ with a **tool-calling AI agent** on top that can run the same methods.
 | `PWN::FFI::*` | **11** | Native bindings (including DSPNative, Capstone and Keystone): Volk · Liquid · FFTW · RTLSdr · HackRF · AdalmPluto · SoapySDR · Stdio |
 | `PWN::AI::*` | **6** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama, Open WebUI |
 | `bin/` (including `pwn-ai` and `pwn-capd`) | **56** | Headless CLI executables for CI/CD |
-| Agent toolsets | **16** · **150 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · policy · extrospection · cron · swarm · reward · curriculum · http · mcp · manifest |
+| Agent toolsets | **16** · **152 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · policy · extrospection · cron · swarm · reward · curriculum · http · mcp · manifest |
 
 ## Three ways to use it
 

data/documentation/YubiKey-Vaults.md

@@ -0,0 +1,185 @@
+# YubiKey-backed vaults and authentication
+
+See [YubiKey device operations](YubiKey.md) for native HID/PC/SC operations,
+provisioning safeguards and the firmware boundary. No `ykman` process is used.
+
+## Encryption model
+
+This is **hardware-derived key encryption**, not bulk encryption inside the
+YubiKey. An already provisioned OTP HMAC-SHA1 slot answers a fresh random
+32-byte challenge. Ruby derives a 32-byte encryption key using HKDF-SHA256 with
+a fresh 16-byte salt and a domain-specific context, then uses AES-256-GCM with
+a fresh nonce and a full 16-byte tag. The HMAC response and derived key exist
+transiently in the Ruby process; the slot secret is not exported. Ruby does not
+promise zeroization of copied strings.
+
+The versioned `PWN-YUBIKEY-VAULT:1` envelope authenticates its metadata as AAD.
+The public challenge, salt, slot and optional serial are stored with ciphertext,
+not in a secret sidecar. Executable paths and timeout overrides are supplied
+by the caller, never loaded from ciphertext. PINs, OTP codes and serial numbers
+are not encryption keys. HMAC-SHA1 is used as the device PRF, not as an
+unauthenticated document hash; it provides at most the slot/response security,
+not 256 bits of entropy merely because AES-256 is used.
+
+Existing Base64 AES-256-CBC files and software loot remain readable. New
+hardware protection is opt-in; no existing configuration is migrated merely by
+loading PWN. A hardware envelope never falls back to a software master key,
+passphrase or unauthenticated plaintext when a device is missing or a tag fails.
+Do not combine a software key/IV or passphrase/keyring with hardware selection.
+
+## Use an existing HMAC slot
+
+Use a key model supporting OTP HMAC challenge-response. FIDO-only Security Keys
+do not support this vault backend. Set up the slot explicitly using the device
+management interface; prefer its physical-touch policy. PWN never provisions,
+replaces, unlocks by guessing, or resets a slot in order to open a vault.
+
+```ruby
+# The named file must already contain the plaintext you intend to encrypt.
+PWN::Plugins::Vault.create(file: '/path/to/private.yaml', yubikey: { slot: 2 })
+
+# With multiple devices, explicitly select the intended device serial.
+# Serial is a placeholder; replace locally, never paste secrets into a transcript.
+selector = { slot: 2, serial: '12345678' }
+PWN::Plugins::Vault.encrypt(file: '/path/to/another.yaml', yubikey: selector)
+
+# Read-only: decrypted data exists in memory, not an intermediate file.
+config = PWN::Plugins::Vault.dump(file: '/path/to/private.yaml'); nil
+
+# Mutate YAML in memory and atomically publish ciphertext, preserving the backend.
+PWN::Plugins::Vault.update(file: '/path/to/private.yaml') do |document|
+  document[:setting] = 'replacement'
+end
+```
+
+`yubikey` is a Hash accepting `slot` (integer 1 or 2; default 2), optional
+exact decimal `serial`, optional `reader` or `device_path`, and bounded
+`timeout` seconds. An executable path such as `ykman` is rejected. The
+envelope stores slot and serial only; it never stores a backend path.
+`dump`, `decrypt`, `open_credentials` and hardware loot retrieval otherwise use
+the slot/serial stored in their envelope. Selecting another serial permits an
+explicitly provisioned recovery key with the same slot secret; the authentication
+tag still has to verify. A different slot requires explicit rewrapping.
+
+`encrypt_data` / `decrypt_data` are in-memory String APIs, including arbitrary
+binary data and empty plaintext. `seal_credentials` / `open_credentials` work
+on JSON-compatible credential values. Neither API opens the live configuration
+or writes keys. `file_encrypted?` / `hardware_encrypted?` inspect format only;
+they do not prove the device is present or that a ciphertext authenticates.
+
+`decrypt(file:)` explicitly replaces ciphertext with plaintext. Use `dump`
+instead when plaintext-on-disk is unnecessary. `edit` explicitly gives a private
+0600 temporary copy to the chosen editor under `~/.pwn/workspaces/runtime`, then
+removes its private working directory. The original stays encrypted until a
+successful re-encryption and atomic replacement. Editors are trusted programs:
+their external backups, OS swap, crash dumps and an abruptly killed process are
+not a secure-erasure guarantee. The curses `/vault edit` editor works in memory
+and writes only ciphertext. Built-in file writers share its parent-directory
+advisory lock across the final baseline check and atomic rename. A stale edit
+raises rather than overwriting a newer publication. This is not a filesystem
+compare-and-swap guarantee against external writers that ignore the lock.
+
+## Conversion and recovery
+
+Before converting a legacy vault, retain its verified encrypted backup and
+legacy decryptor somewhere secure. Conversion is explicit:
+
+```ruby
+PWN::Plugins::Vault.refresh_encryption_secrets(
+  file: '/path/to/legacy.yaml',
+  key: legacy_key, iv: legacy_iv,
+  new_yubikey: { slot: 2 }
+)
+```
+
+No temporary plaintext is published during conversion. On an existing hardware
+vault, `refresh_encryption_secrets(file:)` rewraps with fresh challenge/salt/nonce;
+it does **not** change the device secret. Supply `new_yubikey:` to move to another
+already provisioned slot/device while the old one is available. An explicit
+`new_yubikey:` must be a valid selector Hash; values such as `false` are rejected
+before opening the source vault, not treated as a request for software rotation.
+Hardware access or encryption failure leaves the original ciphertext intact. Old software
+sidecars and backups are not silently deleted; retire them deliberately after
+verifying recovery.
+
+Losing or reprogramming the only usable slot loses access. A ciphertext backup
+alone is not an independent recovery key. Establish and test an appropriate
+recovery device/secret before relying on hardware-only storage. Removing a
+YubiKey does not erase an already unlocked `PWN::Env` or revoke remote tokens;
+the application retains its in-memory configuration until exit/refresh.
+
+## Integration coverage
+
+| Entry point | Hardware behavior |
+|---|---|
+| `Vault.create/encrypt/decrypt/dump/edit/refresh_encryption_secrets` | Explicit creation/conversion, automatic envelope detection on read, backend-preserving edits |
+| `Vault.seal_credentials/open_credentials` | Authenticated in-memory hardware envelopes alongside existing passphrase/keyring formats |
+| `Vault.store/fetch/offer/ingest/expand/redact` | Optional hardware-protected engagement records; metadata-only `query` does not touch hardware |
+| `BasicAuth.encode(host:)` | Resolves matching protected loot through Vault, not a separate crypto implementation |
+| `Redaction.capture` and `Recon` loot ingestion | Explicit hardware selector for new captures; locked-store failure never creates a software-key fallback |
+| `Config.default_env/refresh_env` | Explicit hardware creation; hardware loading without a legacy decryptor sidecar |
+| `Migrate.vault_drift/backfill_vault` | Read/merge through Vault, preserving hardware format and user settings |
+| `pwn-vault`, `/vault edit`, `/model`, `/system-role`, mesh settings | Backend-aware encrypted persistence; no duplicate CBC-only write path |
+| OpenAI, Anthropic, Grok and Google Workspace OAuth persistence | In-memory configuration merge, ciphertext-only atomic save; hardware unavailability reports persistence failure |
+| `AuthenticationHelper.mfa` and supported WWW login methods | Explicit exact-account OATH code lookup, separate from ordinary manual MFA |
+
+Hardware-protected loot reads may require a touch, including explicit expansion
+and secret-value redaction. Do not enable it for unattended workflows expecting
+unbounded automatic access. Background metadata discovery and help do not unlock
+hardware. Existing unrelated records are not implicitly re-encrypted. Missing
+loot stores are empty; an existing unreadable store, malformed JSON, or invalid
+record/envelope shape raises `IOError` on reads and writes, including metadata
+queries. PWN does not infer a software backend from corrupt records, generate a
+replacement master key, or overwrite the damaged store. Restore a verified backup
+before retrying.
+
+## Explicit OATH authentication
+
+Select an exact account and authorize its effects explicitly:
+
+```ruby
+code = PWN::Plugins::AuthenticationHelper.mfa(
+  yubikey: { account: 'Example:alice', serial: '12345678', confirm: true }
+); nil
+```
+
+The same `yubikey:` Hash is accepted by GitHub, Synack, Twitter, BugCrowd,
+CoinbasePro and AppCobaltIO login methods. Lookup occurs at the authenticator
+form, not during option validation. Missing/nonliteral consent is rejected before
+password prompts or navigation. Device errors do not fall back to manual MFA;
+explicit manual tokens cannot be combined with the hardware selector. PayPal's
+current SMS-only adapter rejects OATH even with consent, and GitHub's SMS-only
+challenge does not accept an authenticator code.
+
+For `pwn_web_cache_deception`, add `--yubikey-account='Example:alice'`, optionally
+`--yubikey-serial=12345678`, and the required `--yubikey-confirm` to the normal
+arguments for a compatible login module. The flag authorizes native OATH
+authentication and HOTP counter advancement. It does not authorize deleting or
+repairing a corrupted credential. It is required for TOTP too; PWN never
+silently supplies consent.
+Confirmation/serial flags without an account are rejected before login.
+
+## Scope boundaries
+
+YubiKey FIDO management is not a WebAuthn relying-party implementation. Website
+passkey login still requires the browser's genuine security-key ceremony and
+site enrollment; a generated OATH code must never be submitted to an SMS-only
+challenge. PIV/OpenPGP key management does not export non-exportable keys or
+magically replace TLS, SSH-agent or GPG-provider integrations.
+
+Radio protocol keys, packet AES-CCM, TLS inspection certificates, OAuth PKCE,
+artifact hashes, cloud KMS/HSM API clients and Jenkins private-key uploads are
+not rewritten to use hardware-derived bytes. Their stored credentials can be
+protected through Vault where appropriate.
+
+Hardware-backed loot does not encrypt Recon's raw evidence/asset files, generic
+tool-result artifacts, exports, or the filesystem as a whole. Those retain their
+existing evidence-storage behavior and need separate access/at-rest protection.
+`recon_run` advertises the same nonsecret hardware selector as `loot_query` for
+harvested loot; metadata-only Vault queries do not unlock a device, but Dispatch's
+separate output-redaction step can still require access to protected secrets.
+
+Verification uses synthetic native connections and HMAC responses. Tests
+exercise real Ruby encryption, authentication failures, selector validation
+and persistence entry points. They are not evidence of a physical YubiKey,
+live website authentication or every firmware variant.

data/documentation/YubiKey.md

@@ -0,0 +1,218 @@
+# YubiKey device operations
+
+`PWN::Plugins::YubiKey` implements YubiKey application protocols in Ruby. It
+talks to the device through HIDAPI and PC/SC (`::FFI` bindings to those host
+libraries). It does not start `ykman`, another device CLI, a Python helper, or
+any subprocess. It is not a WebAuthn relying party.
+
+Hardware capability and firmware still decide which operations succeed. Fixture
+tests are not physical-key interoperability, and this page does not claim every
+model or firmware revision.
+
+For encrypted configuration, credential storage, conversion and recovery, see
+[YubiKey-backed vaults and authentication](YubiKey-Vaults.md).
+
+## Dependency and discovery
+
+`required_bins` is empty. Core setup does not install hardware packages. The
+`hardware` profile maps optional host libraries (`hidapi`, `pcsc`), not an
+executable. Loading the module does not open a device. `available?` only probes
+those libraries. A missing library, a missing device, a permission failure and
+an unsupported application are different conditions. Preflight reports
+`FIDO native transport` and `PC/SC native transport` without discovering
+hardware. See [Plugin Degradation](Plugin-Degradation.md#pwn-plugins-yubikey).
+
+```ruby
+require 'pwn'
+yk = PWN::Plugins::YubiKey
+yk.required_bins                       # => []
+yk.available?(backend: 'hid')          # library probe; no device open
+yk.devices                             # explicit listing; may be []
+yk.info(serial: '12345678')            # example serial; replace locally
+yk.otp(args: ['info'], serial: '12345678')
+yk.help                                # public methods and option descriptions
+yk.cli_help                            # local native help metadata, not a CLI process
+yk.cli_help(path: %w[piv keys generate])
+```
+
+There is no `ykman:` path option. Executable paths, stdin, log files and inline
+credential argv are rejected. Serial values must be decimal Strings; they are
+not trimmed or coerced. Omit the serial only when selection is unambiguous.
+PWN never chooses the first of several devices. `reader:` and `device_path:`
+are mutually exclusive with each other and with `serial:` when more than one
+is set. A caller-owned `connection:` stays open; PWN closes only handles it
+opened.
+
+## Native application coverage
+
+Family methods take `args:` as an argv Array **after the family name**. With
+no `args`, they return that family's local help metadata. `command(args:)`
+takes the complete nonsecret argv, including the family name, and dispatches
+to the matching Ruby application. It returns the application result; it does
+not print or log it.
+
+| Method | Application | Covered operations |
+|---|---|---|
+| `config` | management | USB/NFC application enablement, mode, lock code, timeouts, reset |
+| `otp` | OTP | Slot inventory, Yubico OTP, static password, HOTP, HMAC challenge-response, settings, NDEF, swap, delete |
+| `oath` | OATH | Account list/add/URI/import/rename/delete/code, access password, caller-owned cache, reset |
+| `fido` | FIDO | PIN changes/verification, minimum PIN length, resident credential list/delete, fingerprints, UV/attestation policy, reset |
+| `piv` | PIV | PIN/PUK/management key, key generation/import/export/move/delete/attestation, certificates, CSR and object management, reset |
+| `openpgp` | OpenPGP | PIN/admin/reset code and retry policy, key import/attestation/touch policy, certificates, reset |
+| `hsmauth` | HSM Auth | Asymmetric/symmetric/derived credentials, credential passwords, management protection, reset |
+| `security_domain` | Security Domain | SCP key information, generation/import/export/deletion/allowlists and reset |
+| `apdu` | smartcard | Explicit APDUs. Mutations require `confirm: true` |
+
+Unknown command grammar is rejected. Do not pass a shell string. Use separate
+argv elements: `args: ['keys', 'info', '9a']`, not `args: 'keys info 9a'`.
+Short aliases and `--option=value` are rejected. `--` is available before a
+positional identifier that begins with a dash.
+
+### Confirmation, secrets and deadlines
+
+Existing-slot HMAC calculation is the vault unlock path. Omitted `confirm` is
+allowed. If `confirm` is present it must be literal `true`; `false`, `nil` and
+`'true'` are rejected before any open.
+
+Mutations, OATH calculation, provisioning and raw APDUs require literal
+`confirm: true` before the device is opened. Confirmation does not guess
+factory PINs, retry a blocked application, or delete a credential. Native OATH
+does not delete or repair a corrupted credential. HOTP still advances its
+counter. A password-protected OATH account needs an in-memory `password:` or
+`access_key:`, or a caller `secret_provider`.
+
+PINs, PUKs, management keys, access codes and OATH passwords stay in memory or
+come from that provider. They are not argv, exception text, or logs. For a
+private operator terminal, outside an agent request:
+
+```ruby
+yk.interact(
+  args: %w[fido access change-pin], serial: '12345678',
+  confirm: true, operator: true, timeout: 90
+)
+```
+
+`interact` prompts on the controlling console, or on an explicitly supplied
+readable and writable `terminal:` IO, then runs one native command. It returns
+only `:completed`. It does not start a process, retain a transcript, or close
+caller-owned IO. Run it outside curses and recorded tool sessions. Ruby does
+not guarantee string zeroization.
+
+`timeout:` is one finite positive budget in seconds, default **30**. It covers
+open, secure-channel setup, authentication and commands. Remaining time is
+what later exchanges receive; each step does not get a fresh 30 seconds.
+`SCardCancel` does not universally interrupt `SCardTransmit`, and killing a
+Ruby thread does not cancel a native driver call. After a timeout or
+interruption, inspect device state before retrying a mutation.
+
+Missing libraries, command failure, timeout, output limits and malformed
+responses raise `DependencyError`, `CommandError`, `TimeoutError`,
+`OutputLimitError` or `ResponseError`. These inherit from `YubiKey::Error`.
+Missing consent raises `ConfirmationRequired`. Invalid caller values raise
+`ArgumentError`. Errors do not include request bytes.
+
+### Secure channel
+
+`secure_channel:` is an explicit Hash, not a file of inline CLI keys. It
+requires `scp:` (`:scp03`, `:scp11a`, `:scp11b` or `:scp11c`) and integer
+`kvn:`. SCP03 also requires 16-byte in-memory `key_enc` and `key_mac`. A
+failed secure-channel handshake does not fall back to plaintext. The owned
+handle is still closed.
+
+## Existing-slot HMAC challenge-response
+
+```ruby
+require 'securerandom'
+challenge = SecureRandom.random_bytes(32) # Public challenge, not a provisioning key.
+response = PWN::Plugins::YubiKey.challenge_response(
+  challenge: challenge,
+  slot: 2,
+  serial: '12345678',
+  timeout: 30
+); nil # Suppress sensitive return-value echo in an interactive console.
+```
+
+`challenge:` is a raw Ruby String of **1–64 bytes**, not pre-encoded hex.
+`slot:` is integer **1 or 2**, default **2**. The return value is exactly
+**20 raw bytes**, encoding `ASCII-8BIT`. A touch-enabled slot requires a
+physical touch before timeout. Missing or incompatible slots fail. This method
+never programs, resets or repairs a slot. FIDO-only Security Key models cannot
+provide this OTP HMAC operation.
+
+The challenge is not placed on a child argv, because no child is started. Do
+not use a password as the challenge. The HMAC response is sensitive key
+material in the Ruby process.
+
+## Explicit HMAC provisioning
+
+Provisioning is separate from authentication and vault unlock. It **overwrites
+the chosen slot**. The existing HMAC secret cannot be read back. Keep another
+authentication method, and test recovery before discarding the new key.
+
+```ruby
+require 'securerandom'
+secret_key = SecureRandom.random_bytes(20); nil
+PWN::Plugins::YubiKey.provision_challenge_response(
+  key: secret_key,
+  serial: '12345678',
+  slot: 2,
+  confirm: true,
+  timeout: 30
+) # => :verified only after a fresh challenge matches the supplied key
+```
+
+`confirm: true` is required before open. An explicit serial, reader,
+device path or caller-owned connection is required. `touch:` defaults to
+`true`. Optional access codes are six raw bytes, supplied in memory, not at a
+CLI prompt. The method checks a fresh challenge with Ruby OpenSSL HMAC-SHA1
+and returns `:verified` only when that check passes. Touch the device when the
+slot requires it. If programming succeeds and readback fails, the slot may
+already have changed: inspect it before retrying. Do not assume rollback.
+
+## Exact OATH retrieval
+
+```ruby
+code = PWN::Plugins::YubiKey.oath_code(
+  account: 'Example:alice', # Exact identifier, not a substring.
+  serial: '12345678',
+  confirm: true,
+  timeout: 30
+); nil
+```
+
+The result is **6–8 decimal digits**, preserving leading zeros. The account
+must be an exact control-free String of 1 to 64 bytes. Steam alphanumeric
+codes are outside this method. `confirm: true` is required before open, including
+for TOTP, because HOTP advances its counter and a protected account may
+authenticate. Consent does not authorize deleting a corrupted credential.
+Device errors do not fall back to a manual token.
+
+## Authentication and interoperability limits
+
+FIDO PIN, resident-credential and fingerprint management is **not website
+login**. U2F/FIDO2/WebAuthn enrollment and assertions belong to the browser and
+relying party. This module does not fabricate assertions. Submit an OATH code
+only to a matching authenticator-code challenge, never an SMS-only or passkey
+challenge. PayPal's SMS adapter rejects hardware OATH before login.
+
+PIV and OpenPGP management do not supply a TLS client, SSH agent or GPG
+middleware, and do not export non-exportable private keys. YubiHSM Auth
+credentials are not a YubiHSM. Device and firmware errors stay errors. They do
+not trigger reset, provisioning, a software-secret fallback, or repeated PIN
+attempts.
+
+## Offline verification
+
+```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
+```
+
+Those specs use synthetic connections and credentials, including an independent
+RFC 2202 HMAC-SHA1 vector. They do not open a physical key, log in to a website,
+or prove every firmware variant. USB/NFC, touch, PIN protection and real
+relying-party login remain separate opt-in checks.
+
+- [RFC 2202 HMAC test vectors](https://www.rfc-editor.org/rfc/rfc2202)
+- [GlobalPlatform Card Specification](https://globalplatform.org/specs-library/card-specification/)
+- [Yubico OTP protocol notes](https://developers.yubico.com/OTP/)