pwn 0.5.627 → 0.5.629

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e41f7773a146dc00b0f3eb205ef5f0bd4ed7cc894e2a7b0448aa398fc3e23c0
-  data.tar.gz: 22e69de2b918558f4702adf91b68615eabe0ddc0d5676b4fe2beb1602c935f13
+  metadata.gz: 2f0c536ea0f5b7dbd2c88621241adfa866f7ed726ee4e2109abe83aef13b0385
+  data.tar.gz: 7e3bc1436b9ce27c63da25dc609eab317a009b1339a843a6cdfe03469386b195
 SHA512:
-  metadata.gz: 271dc24b5a41f4d16ac1a1a1f9c9d4ac6b0cfe2aa3358eb8d7e16058a9036f9e8d73c4528e8a17a8e9c6d31dc263c8a8de56047816f88caad35ba128874e8258
-  data.tar.gz: 5cacca96d75ff106f28b5d344b98bb91eb01887332598e28106379fccfafbaf2547ce7f27d983ac8d16ad71964480e2c0fce73ffd152ef3f46af771d8306672b
+  metadata.gz: 572496cd5d2754022fdb35c360db8e5fec65cd91693ea196f8e44666c28141f198b3353146cd658aa07b93d0add52e3808448fe0836b38830c2fb1b553d8dad2
+  data.tar.gz: 7dc0f6160402b01d8acb694e72d86daef36743fd9b9f0b84a2f87da0d77367798e8ef429463e25f36747f359c5b621615e61e26df29033de9561a24d926af4a6

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-05 17:51:34 UTC using RuboCop version 1.86.1.
+# on 2026-07-10 16:56:14 UTC using RuboCop version 1.88.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,7 +13,7 @@ Layout/TrailingWhitespace:
   Exclude:
     - 'lib/pwn/banner/radare2_ai.rb'
 
-# Offense count: 11
+# Offense count: 14
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Lint/NestedMethodDefinition:
   Exclude:
@@ -30,17 +30,16 @@ Lint/RedundantTypeConversion:
     - 'lib/pwn/plugins/jenkins.rb'
     - 'lib/pwn/plugins/repl.rb'
 
-# Offense count: 4
-Lint/ShadowedException:
-  Exclude:
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
-
-# Offense count: 302
+# Offense count: 296
 # This cop supports safe autocorrection (--autocorrect).
 Lint/UselessAssignment:
   Enabled: false
 
+# Offense count: 2
+Lint/UselessConstantScoping:
+  Exclude:
+    - 'lib/pwn/sdr/decoder/bluetooth.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: CheckForMethodsWithNoSideEffects.
@@ -49,7 +48,7 @@ Lint/Void:
     - 'bin/pwn_web_cache_deception'
 
 # Offense count: 1
-# Configuration parameters: LengthThreshold.
+# Configuration parameters: Max.
 Metrics/CollectionLiteralLength:
   Exclude:
     - 'lib/pwn/plugins/uri_scheme.rb'
@@ -66,7 +65,7 @@ Metrics/MethodLength:
   Exclude:
     - 'lib/pwn/banner/code_cave.rb'
 
-# Offense count: 8
+# Offense count: 9
 Naming/AccessorMethodName:
   Exclude:
     - 'lib/pwn/ai/anthropic.rb'
@@ -78,6 +77,13 @@ Naming/AccessorMethodName:
     - 'lib/pwn/plugins/jira_data_center.rb'
     - 'lib/pwn/plugins/vin.rb'
 
+# Offense count: 5
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/pwn/sdr/decoder/lora.rb'
+
 # Offense count: 2
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
@@ -98,7 +104,7 @@ Style/Alias:
 Style/ClassVars:
   Enabled: false
 
-# Offense count: 273
+# Offense count: 277
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
 # SupportedStyles: assign_to_condition, assign_inside_condition
@@ -150,13 +156,11 @@ Style/MultipleComparison:
     - 'lib/pwn/www/duckduckgo.rb'
     - 'lib/pwn/www/twitter.rb'
 
-# Offense count: 5
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantBegin:
   Exclude:
     - 'lib/pwn/plugins/transparent_browser.rb'
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
 
 # Offense count: 94
 # This cop supports safe autocorrection (--autocorrect).
@@ -172,13 +176,6 @@ Style/RedundantParentheses:
   Exclude:
     - 'lib/pwn/plugins/xxd.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/RedundantSelf:
-  Exclude:
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
-
 # Offense count: 12
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantStringEscape:
@@ -189,14 +186,7 @@ Style/RedundantStringEscape:
     - 'lib/pwn/sast/redos.rb'
     - 'vagrant/provisioners/kali_customize.rb'
 
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-Style/RescueModifier:
-  Exclude:
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
-
-# Offense count: 19
+# Offense count: 17
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/SlicingWithRange:
   Exclude:

data/Gemfile

@@ -20,7 +20,7 @@ gem 'base32', '0.3.4'
 gem 'bitcoin-ruby', '0.0.20'
 gem 'brakeman', '8.0.5'
 gem 'bson', '5.2.0'
-gem 'bundler', '>=4.0.15'
+gem 'bundler', '>=4.0.16'
 gem 'bundler-audit', '>=0.9.3'
 gem 'bunny', '3.1.0'
 gem 'colorize', '1.1.0'

data/README.md

@@ -33,7 +33,7 @@ hardware / radio exploitation, to reporting and disclosure — and puts a
 **self-improving, tool-calling, multi-agent AI** on top of it.
 
 **In numbers:** 66 `PWN::Plugins` · 48 `PWN::SAST` rules · 90 `PWN::AWS`
-service wrappers · 21 `PWN::WWW` site drivers · 52 `bin/pwn_*` CLI drivers ·
+service wrappers · 21 `PWN::WWW` site drivers · 53 `bin/pwn_*` CLI drivers ·
 5 LLM engines · 10 agent toolsets · 45+ LLM-callable tools.
 
 Full page: [What is PWN](documentation/What-is-PWN.md)
@@ -86,7 +86,7 @@ The complete wiki lives in this repo at **[`documentation/Home.md`](documentatio
 |---|---|---|---|
 | [What is PWN](documentation/What-is-PWN.md) | [`pwn` REPL](documentation/pwn-REPL.md) | [AI / LLM Integration](documentation/AI-Integration.md) | [Plugins (66)](documentation/Plugins.md) |
 | [Why PWN](documentation/Why-PWN.md) | [`pwn-ai` Agent](documentation/pwn-ai-Agent.md) | [Agent Tool Registry](documentation/Agent-Tool-Registry.md) | [SAST (48)](documentation/SAST.md) |
-| [How PWN Works](documentation/How-PWN-Works.md) | [CLI Drivers (52)](documentation/CLI-Drivers.md) | [Memory · Skills · Learning](documentation/Skills-Memory-Learning.md) | [AWS (90)](documentation/AWS.md) |
+| [How PWN Works](documentation/How-PWN-Works.md) | [CLI Drivers (53)](documentation/CLI-Drivers.md) | [Memory · Skills · Learning](documentation/Skills-Memory-Learning.md) | [AWS (90)](documentation/AWS.md) |
 | [Installation](documentation/Installation.md) | [Build a Driver](documentation/Drivers.md) | [Mistakes (neg-feedback)](documentation/Mistakes.md) | [WWW (21)](documentation/WWW.md) |
 | [General Usage](documentation/General-PWN-Usage.md) | | [Extrospection](documentation/Extrospection.md) | [SDR / Radio](documentation/SDR.md) |
 | [Configuration](documentation/Configuration.md) | | [Swarm (multi-agent)](documentation/Swarm.md) | [Hardware](documentation/Hardware.md) |
@@ -103,18 +103,31 @@ Rebuild every SVG from its Graphviz source:
 
 ### **Installation** ###
 
-Tested on Debian-based Linux & macOS, Ruby via RVM.
+PWN is a **single gem** with a built-in post-install doctor/provisioner —
+`pwn setup` — that detects your package manager (`apt` · `dnf` · `pacman` ·
+`brew` · `port`) and installs exactly the OS headers + external tools each
+`PWN::` capability needs. Tested on Kali/Debian/Ubuntu, Fedora, Arch, macOS.
 
 ```
-$ cd /opt
-$ sudo git clone https://github.com/0dayinc/pwn
-$ cd /opt/pwn
-$ ./install.sh
-$ ./install.sh ruby-gem
+$ gem install pwn
+$ pwn setup                        # read-only doctor: which capabilities are usable?
+$ pwn setup --profile full --yes   # provision everything (or: web | net | sdr | vision | …)
 $ pwn
-pwn[v0.5.627]:001 >>> PWN.help
+pwn[v0.5.629]:001 >>> PWN.help
 ```
 
+Only need a subset?
+
+```
+$ pwn setup --list-profiles
+$ pwn setup --profile web          # TransparentBrowser · Burp · ZAP · Tor · sqlmap
+$ pwn setup --profile sdr --yes    # GQRX · rtl-sdr · hackrf · SoapySDR · FFI DSP
+$ pwn setup --profile net --dry-run
+```
+
+Also available as `pwn_setup` (standalone driver) and `pwn --setup[=PROFILE]`.
+The doctor exits non-zero when capabilities are degraded, so CI can gate on it.
+
 [![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
 
 Full page: [Installation](documentation/Installation.md) ·
@@ -131,20 +144,16 @@ Update PWN frequently — new plugins, agent tools, skills and zero-day tooling
 land regularly:
 
 ```
-$ rvm list gemsets
-$ rvm use ruby-4.0.5@pwn
-$ gem uninstall --all --executables pwn
-$ gem install --verbose pwn
+$ gem update pwn
+$ pwn setup            # re-doctor — new versions may add capabilities
 $ pwn
-pwn[v0.5.627]:001 >>> PWN.help
+pwn[v0.5.629]:001 >>> PWN.help
 ```
 
-If using a multi-user RVM install:
+From a git checkout:
 
 ```
-$ rvm use ruby-4.0.5@pwn
-$ rvmsudo gem uninstall --all --executables pwn
-$ rvmsudo gem install --verbose pwn
+$ cd /opt/pwn && git pull && rake install && pwn setup
 ```
 
 **Inside the `pwn` REPL:**
@@ -160,11 +169,10 @@ $ echo "$LONG_PROMPT" | pwn --ai -
 $ pwn -Y ./ci/pwn.yaml --ai 'Run pwn_sast against ./src and summarise HIGH findings' > findings.txt
 ```
 
-PWN periodically upgrades to the latest Ruby (`/opt/pwn/.ruby-version`).
-Easiest upgrade of Ruby + pwn from a previous install:
+**Provision a CI runner / Docker image:**
 
 ```
-$ /opt/pwn/vagrant/provisioners/pwn.sh
+$ pwn setup --profile web --yes && pwn setup --check   # exits 1 if degraded
 ```
 
 ---

data/bin/pwn

@@ -3,6 +3,19 @@
 
 require 'pwn'
 
+# ----------------------------------------------------------------------
+# Bare-word subcommand: `pwn setup [...]` → delegate to bin/pwn_setup so
+# `gem install pwn && pwn setup` is the canonical two-step install path.
+# Must be handled BEFORE OptionParser (which would reject `setup`).
+# ----------------------------------------------------------------------
+if ARGV.first == 'setup'
+  ARGV.shift
+  setup_bin = File.expand_path('pwn_setup', __dir__)
+  setup_bin = Gem.bin_path('pwn', 'pwn_setup') unless File.file?(setup_bin)
+  load setup_bin
+  exit
+end
+
 opts = PWN::Env[:driver_opts]
 pwn_driver = PWN::Driver::Parser.new do |options|
   options.on(
@@ -14,6 +27,16 @@ pwn_driver = PWN::Driver::Parser.new do |options|
   ) do |a|
     opts[:ai] = a
   end
+
+  options.on(
+    '-S[PROFILE]',
+    '--setup[=PROFILE]',
+    '<Optional - Post-install doctor / capability provisioner. With no ' \
+    "PROFILE runs a read-only check; with PROFILE (#{PWN::Setup::PROFILES.keys.join('|')}) " \
+    'installs OS deps for that capability set. Same as `pwn setup` / `pwn_setup`>'
+  ) do |p|
+    opts[:setup] = p || true
+  end
 end
 pwn_driver.auto_opts_help = false
 pwn_driver.parse!
@@ -21,7 +44,18 @@ pwn_driver.parse!
 begin
   pwn_pid = Process.pid
 
-  if opts[:ai]
+  if opts[:setup]
+    # ------------------------------------------------------------------
+    # `pwn --setup`            → PWN::Setup.check   (read-only doctor)
+    # `pwn --setup=web`        → PWN::Setup.deps(profile: :web)
+    # ------------------------------------------------------------------
+    if opts[:setup] == true
+      r = PWN::Setup.check
+      exit(r[:ok] ? 0 : 1)
+    else
+      PWN::Setup.deps(profile: opts[:setup])
+    end
+  elsif opts[:ai]
     # ------------------------------------------------------------------
     # Headless pwn-ai: behave as if the user typed PROMPT at the pwn-ai
     # TUI, but non-interactively — a single agent-loop turn with native

data/bin/pwn_setup

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'pwn'
+
+opts = PWN::Env[:driver_opts]
+pwn_driver = PWN::Driver::Parser.new do |options|
+  options.banner = "USAGE: #{File.basename($PROGRAM_NAME)} [opts]\n       " \
+                   "Post-install doctor & capability provisioner for the PWN gem.\n       " \
+                   "With no options, runs a read-only capability check.\n"
+
+  options.on('-c', '--check',
+             '<Optional - Read-only doctor: which PWN capabilities are usable on this host? (default action)>') do |o|
+    opts[:check] = o
+  end
+
+  options.on('-d', '--deps',
+             '<Optional - Install OS headers + external tools + rebuild native gems for --profile (default: full)>') do |o|
+    opts[:deps] = o
+  end
+
+  options.on('-pNAME', '--profile=NAME',
+             "<Optional - Capability profile: #{PWN::Setup::PROFILES.keys.join(' | ')} (default: full)>") do |o|
+    opts[:profile] = o
+  end
+
+  options.on('-l', '--list-profiles',
+             '<Optional - List capability profiles and exit>') do |o|
+    opts[:list] = o
+  end
+
+  options.on('-y', '--yes',
+             '<Optional - Assume yes; non-interactive (CI-friendly)>') do |o|
+    opts[:yes] = o
+  end
+
+  options.on('-n', '--dry-run',
+             '<Optional - Print the commands that would run, do not execute>') do |o|
+    opts[:dry_run] = o
+  end
+end
+pwn_driver.auto_opts_help = false
+pwn_driver.parse!
+
+begin
+  if opts[:list]
+    PWN::Setup.list_profiles
+  elsif opts[:deps] || opts[:profile]
+    PWN::Setup.deps(
+      profile: opts[:profile],
+      yes: opts[:yes],
+      dry_run: opts[:dry_run]
+    )
+  else
+    r = PWN::Setup.check
+    exit 1 unless r[:ok]
+  end
+rescue Interrupt
+  puts "\naborted."
+  exit 130
+rescue StandardError => e
+  warn "pwn_setup: #{e.class}: #{e.message}"
+  exit 1
+end

data/documentation/AI-Integration.md

@@ -1,7 +1,7 @@
 # AI / LLM Integration — `PWN::AI`
 
 One agent loop, five interchangeable engines. Swap providers by changing one
-line in `~/.pwn/config.yml`; the tool-calling contract is normalised so the
+line in `~/.pwn/pwn.yaml`; the tool-calling contract is normalised so the
 agent code never cares which model is behind it.
 
 ![Multi-provider integration](diagrams/ai-integration-tool-calling.svg)
@@ -14,23 +14,58 @@ agent code never cares which model is behind it.
 | `anthropic` | `PWN::AI::Anthropic` | `key:` | tool-use native |
 | `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 | local, `base_url:` + `model:` |
+| `ollama` | `PWN::AI::Ollama` | none | local — native `/api/chat` (`num_ctx`, `keep_alive`, low-temp + `format:'json'` on tool turns) and `/api/embed` for `PWN::MemoryIndex` |
+
+> PWN is **model-agnostic**. `ai.<engine>.model` is passed straight through to
+> the provider — the codebase and docs deliberately never name a specific
+> model id so you can point each engine at whatever the vendor currently
+> ships (or whatever `ollama list` shows locally).
 
 ## Selecting an engine
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml
 ai:
-  engine: grok
+  active: grok
   grok:
-    oauth: true   # first run opens https://accounts.x.ai/… device page
+    oauth:
+      enroll: true    # first run opens https://accounts.x.ai/… device page
 ```
 
 ```ruby
 # at runtime
-PWN::Env[:ai][:engine] = :ollama
+PWN::Env[:ai][:active] = :ollama
 ```
 
+## Engine-aware behaviour
+
+The harness adapts to the *class* of engine, not the model name:
+
+| Concern | Frontier (`openai` · `anthropic` · `grok` · `gemini`) | Local (`ollama`) |
+|---|---|---|
+| **PromptBuilder.budget** | full MEMORY / METRICS / MISTAKES / LEARNING / EXTRO blocks | tightened via `ai.ollama.prompt_budget` (extro off by default) |
+| **MEMORY ranking** | relevance-ranked when a local Ollama `embed_model` is reachable, else newest-first | relevance-ranked via `PWN::MemoryIndex` (`~/.pwn/memory.idx`) |
+| **Tool schemas shipped** | all toolsets | `CORE_TOOLS` + top-K keyword matches when `ai.agent.tool_router` is on |
+| **Pre-pass** | none | `plan_first` numbered tool plan before first dispatch |
+| **Few-shot** | none | `Learning.exemplars_for(request)` splices a prior successful trace |
+| **Dispatch parsing** | strict | tolerant — Levenshtein tool-name repair + JSON5-ish arg cleanup, each repair fingerprinted into `Mistakes` |
+| **Post-answer** | `auto_introspect` | `auto_introspect` **+** `fact_check_local_final` (auto `extro_verify` on CVE/version-shaped claims) |
+| **Metrics bucket** | `metrics.json[:tools][name][:engines][:<engine>]` | same — the `TOOL EFFECTIVENESS` block is per-engine so local telemetry never blends with frontier |
+
+## Teacher-student reflection
+
+`ai.reflect_engine` decouples *doing* from *learning-about-doing*:
+
+```yaml
+ai:
+  active: ollama            # the local model executes tools and answers
+  reflect_engine: anthropic # a frontier model writes the durable Memory :lesson
+```
+
+`PWN::AI::Agent::Reflect.on` temporarily flips the active engine for the
+introspection call only, so the local model reads back distilled reasoning it
+could not have produced itself.
+
 ## Direct client use (no agent)
 
 ```ruby
@@ -43,10 +78,14 @@ puts resp[:content]
 ## Model diversity in Swarm
 
 Because each persona in [`agents.yml`](Swarm.md) can override `engine:`, an
-`agent_debate` can literally pit Claude against Grok against a local Llama —
-real antagonism, not one model role-playing three voices.
+`agent_debate` can pit five *different providers* against each other — real
+antagonism, not one model role-playing three voices. The same mechanism backs
+`ai.agent.escalation_persona`: when a local model is stuck, `Loop.run` asks a
+frontier persona for a 3-line corrective hint and injects it as a synthetic
+tool result.
 
 **See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
-[Agent Tool Registry](Agent-Tool-Registry.md) · [Swarm](Swarm.md)
+[Agent Tool Registry](Agent-Tool-Registry.md) · [Swarm](Swarm.md) ·
+[Configuration](Configuration.md)
 
 [← Home](Home.md)

data/documentation/AWS.md

@@ -10,7 +10,7 @@ with the PWN `opts = {}` convention so they compose in the REPL and in
 
 Standard AWS SDK chain: `~/.aws/credentials` profile, env vars
 (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`), or
-instance profile. Optionally pin in `~/.pwn/config.yml` under `aws:`.
+instance profile. Optionally pin in `~/.pwn/pwn.yaml` under `aws:`.
 
 ## Quick enumeration
 

data/documentation/Agent-Tool-Registry.md

@@ -21,6 +21,30 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 | `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/` |
 
+
+## Dynamic tool-set slimming (`ai.agent.tool_router`)
+
+Shipping every schema on every turn overwhelms a small local model — the
+choice space is huge and it mis-routes (e.g. picks an RF tool for a git
+question). When `ai.agent.tool_router: true` **and** `Loop.run` passes the
+user request through as `relevance:`, `Registry.definitions` shrinks the
+pool to:
+
+```text
+CORE_TOOLS  = shell · pwn_eval · memory_remember · memory_recall
+              mistakes_record · mistakes_resolve · learning_note_outcome
+            + top-K keyword-ranked matches for THIS request
+              (ties break on Metrics per-engine success_rate → the router
+               itself is a learned component)
+```
+
+```ruby
+PWN::AI::Agent::Registry.definitions(relevance: 'nmap sweep 10.0.0.0/8', top_k: 10)
+PWN::AI::Agent::Registry.rank(query: 'run a shell command')   # inspect ranking
+```
+
+Frontier engines leave `tool_router` off and receive the full set.
+
 ## Adding a tool
 
 ```ruby

data/documentation/BurpSuite.md

@@ -6,10 +6,13 @@ Professional's headless mode + REST API.
 
 ![Web application testing](diagrams/web-application-testing.svg)
 
+> **Install:** `pwn setup --profile web` — burpsuite · zaproxy · chromium ·
+> geckodriver · sqlmap · tor. See [Installation](Installation.md).
+
 ## Configure
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml  (edit via `pwn-vault`)
 burp:
   jar: /opt/burpsuite_pro/burpsuite_pro.jar
   api_key: <REST-API-KEY>

data/documentation/CLI-Drivers.md

@@ -1,6 +1,6 @@
 # CLI Drivers — `bin/pwn_*`
 
-52 headless executables, each a thin `OptionParser` wrapper over one plugin
+53 headless executables, each a thin `OptionParser` wrapper over one plugin
 (or one workflow). They exist so CI/CD can call PWN without a REPL or an LLM.
 
 ![Driver anatomy](diagrams/driver-framework.svg)
@@ -26,19 +26,34 @@ pwn_crt_sh                       pwn_serial_check_voicemail
 pwn_defectdojo_engagement_create pwn_serial_msr206
 pwn_defectdojo_importscan        pwn_serial_qualcomm_commands
 pwn_defectdojo_reimportscan      pwn_serial_son_micro_sm132_rfid
-pwn_diff_csv_files_w_column_exclude  pwn_shodan_graphql_introspection
-pwn_domain_reversewhois          pwn_shodan_search
-pwn_fuzz_net_app_proto           pwn_simple_http_server
-pwn_gqrx_scanner                 pwn_web_cache_deception
-pwn_jenkins_create_job           pwn_www_checkip
-pwn_jenkins_create_view          pwn_www_uri_buster
-pwn_jenkins_install_plugin       pwn_xss_dom_vectors
-                                 pwn_zaproxy_active_rest_api_scan
-                                 pwn_zaproxy_active_scan
+pwn_diff_csv_files_w_column_exclude  pwn_setup
+pwn_domain_reversewhois          pwn_shodan_graphql_introspection
+pwn_fuzz_net_app_proto           pwn_shodan_search
+pwn_gqrx_scanner                 pwn_simple_http_server
+pwn_jenkins_create_job           pwn_web_cache_deception
+pwn_jenkins_create_view          pwn_www_checkip
+pwn_jenkins_install_plugin       pwn_www_uri_buster
 ```
 
 Run any with `--help` for its flags.
 
+## `pwn_setup` — post-install doctor & capability provisioner
+
+The one driver that isn't a plugin wrapper. It grows a bare `gem install pwn`
+into a fully-armed host by installing OS headers / external tools for whatever
+capability profile you ask for. Also reachable as `pwn setup` and
+`pwn --setup[=PROFILE]`.
+
+```bash
+pwn_setup                        # read-only doctor; exit 1 if degraded
+pwn_setup --list-profiles
+pwn_setup --profile web --yes    # CI-friendly, non-interactive
+pwn_setup --deps --dry-run       # print the apt/dnf/pacman/brew/port commands only
+```
+
+See [Installation](Installation.md) for the full profile table and
+`PWN::Setup` API.
+
 ## Typical CI usage
 
 ```yaml
@@ -46,6 +61,8 @@ Run any with `--help` for its flags.
 sast:
   image: 0dayinc/pwn:latest
   script:
+    - pwn_setup --profile net --yes
+    - pwn_setup --check                                   # gate: exit 1 if degraded
     - pwn_sast -d "$CI_PROJECT_DIR" -o sast_out/
     - pwn_defectdojo_importscan -f sast_out/report.json -e "$DD_ENGAGEMENT"
 ```