pwn 0.5.617 → 0.5.618

data/documentation/Agent-Tool-Registry.md

@@ -0,0 +1,56 @@
+# Agent Tool Registry
+
+`PWN::AI::Agent::Registry` (`lib/pwn/ai/agent/registry.rb`) collects every
+LLM-callable function into named **toolsets**. A persona is granted a subset of
+toolsets; the JSON-Schema for each tool is what the model actually sees.
+
+![Tool registry](diagrams/agent-tool-registry.svg)
+
+## Toolsets → Tools
+
+| Toolset | Tools | Backed by |
+|---|---|---|
+| `terminal` | `shell` | `Open3.capture3` on the host |
+| `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
+| `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
+| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` | `~/.pwn/skills/*.md` |
+| `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_reflect_toggle` | `PWN::AI::Agent::Learning` → `~/.pwn/learning.jsonl` |
+| `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
+| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` → `~/.pwn/extrospection.json` |
+| `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
+| `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
+
+## Adding a tool
+
+```ruby
+# lib/pwn/ai/agent/tools/my_thing.rb
+PWN::AI::Agent::Registry.register(
+  name: 'my_thing_do',
+  toolset: 'my_thing',
+  description: 'One-line summary the LLM will read.',
+  parameters: {
+    type: 'object',
+    properties: { target: { type: 'string' } },
+    required: ['target']
+  }
+) do |args|
+  PWN::Plugins::MyThing.do(target: args['target'])
+end
+```
+
+Drop the file in `lib/pwn/ai/agent/tools/`, it's auto-loaded on next launch.
+
+## Restricting a persona
+
+```yaml
+# ~/.pwn/agents.yml
+recon:
+  role: "Passive OSINT only. Never touch the target directly."
+  toolsets: [terminal, pwn, memory, extrospection]   # no swarm, no cron
+  engine: ollama
+```
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Swarm](Swarm.md)
+
+[← Home](Home.md)

data/documentation/Banner.md

@@ -0,0 +1,17 @@
+# `PWN::Banner` — Startup Art
+
+15 ANSI banners; one is picked at random every time the REPL starts. Purely
+cosmetic, entirely necessary.
+
+`Anon · Bubble · Cheshire · CodeCave · DontPanic · ForkBomb · FSociety ·
+JmpEsp · Matrix · Ninja · OffTheAir · Pirate · Radare2 · Radare2AI ·
+WhiteRabbit`
+
+```ruby
+puts PWN::Banner::Matrix.get
+welcome-banner          # REPL command: redraw a random one
+```
+
+Add your own: drop a module in `lib/pwn/banner/` implementing `self.get`.
+
+[← Home](Home.md)

data/documentation/Blockchain.md

@@ -0,0 +1,18 @@
+# `PWN::Blockchain` — BTC · ETH
+
+Lightweight helpers for on-chain recon and wallet interaction.
+Source: `lib/pwn/blockchain/*.rb`.
+
+| Module | Purpose |
+|---|---|
+| `PWN::Blockchain::BTC` | Address balance/UTXO lookup, tx broadcast, key helpers |
+| `PWN::Blockchain::ETH` | Address balance, contract call, event log query |
+
+Also exposed to the agent via `PWN::AI::Agent::BTC` for wallet-aware prompts.
+
+```ruby
+PWN::Blockchain::BTC.balance(address: 'bc1q…')
+PWN::Blockchain::ETH.call(contract: '0x…', method: 'owner()')
+```
+
+[← Home](Home.md)

data/documentation/Bounty.md

@@ -0,0 +1,21 @@
+# `PWN::Bounty` — Bug-Bounty Lifecycle Tooling
+
+| Module | Purpose |
+|---|---|
+| `PWN::Bounty::LifecycleAuthzReplay` | Record an authenticated browser session, then replay every request under a *different* principal to surface horizontal/vertical authz bugs |
+
+Pairs naturally with:
+
+- [`PWN::WWW::HackerOne`](WWW.md) / `BugCrowd` / `Synack` — programme navigation
+- `PWN::Plugins::HackerOne` — submissions API
+- [`PWN::Plugins::BurpSuite`](BurpSuite.md) — capture the session to replay
+
+```ruby
+PWN::Bounty::LifecycleAuthzReplay.start(
+  har_path: 'admin_session.har',
+  replay_as: { cookie: 'session=LOW_PRIV_TOKEN' },
+  proxy: 'http://127.0.0.1:8080'
+)
+```
+
+[← Home](Home.md) · [WWW](WWW.md)

data/documentation/BurpSuite.md

@@ -1,26 +1,51 @@
-# Burp Suite Integration
+# `PWN::Plugins::BurpSuite` ⭐
 
-**Preferred** web application proxy and scanner in PWN.
+The **preferred** web proxy / scanner in PWN (see
+[Burp vs ZAP](Diagrams.md#burp--vs-zap-selection)). Wraps Burp Suite
+Professional's headless mode + REST API.
 
-## Why Burp Over ZAP
+![Web application testing](diagrams/web-application-testing.svg)
 
-Burp Suite Professional offers richer scanning, more comprehensive plugin ecosystem, and better active/passive scanning capabilities for modern web apps. Use `PWN::Plugins::BurpSuite` by default.
+## Configure
 
-## Key Methods (incomplete list - inspect in REPL)
+```yaml
+# ~/.pwn/config.yml
+burp:
+  jar: /opt/burpsuite_pro/burpsuite_pro.jar
+  api_key: <REST-API-KEY>
+  bind_ip: 127.0.0.1
+  proxy_port: 8080
+  api_port: 1337
+```
 
-- `PWN::Plugins::BurpSuite.start(...)`
-- `PWN::Plugins::BurpSuite.stop`
-- `PWN::Plugins::BurpSuite.get_sitemap(...)`
-- `PWN::Plugins::BurpSuite.send_request(...)`
-- Live spidering and scanning orchestration
-- Integration with TransparentBrowser for proxied browsing
+## Core methods
 
-## Typical Usage via Agent
+```ruby
+burp = PWN::Plugins::BurpSuite.start(headless: true)
 
-> "Start BurpSuite, configure TransparentBrowser to proxy through it, spider target, run active scan, report findings."
+# drive traffic through it
+b = PWN::Plugins::TransparentBrowser.open(
+      browser_type: :headless, proxy: 'http://127.0.0.1:8080')
+b[:browser].goto 'https://target'
 
-See `lib/pwn/plugins/burp_suite.rb` for full API and source.
+# scan
+PWN::Plugins::BurpSuite.active_scan(burp_obj: burp,
+                                    target_url: 'https://target')
+issues = PWN::Plugins::BurpSuite.get_scan_issues(burp_obj: burp)
 
-Also see [Plugins](Plugins.md) and [pwn-ai Agent](pwn-ai-Agent.md).
+PWN::Plugins::BurpSuite.stop(burp_obj: burp)
+```
 
-[[Diagrams]]
+## CLI drivers
+
+- `pwn_burp_suite_pro_active_scan -t URL -o out/`
+- `pwn_burp_suite_pro_active_rest_api_scan` — pure REST, no JVM spawn
+
+## Why preferred over ZAP
+
+Richer scanner, larger BApp ecosystem, more reliable REST surface. `Zaproxy`
+remains as an OSS fallback and is API-compatible enough that swapping is a
+one-line change.
+
+[← Home](Home.md) · [Transparent-Browser](Transparent-Browser.md) ·
+[Plugins](Plugins.md)

data/documentation/CLI-Drivers.md

@@ -0,0 +1,58 @@
+# CLI Drivers — `bin/pwn_*`
+
+52 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)
+
+## Full list
+
+```text
+pwn                              pwn_jenkins_thinBackup_aws_s3
+pwn_android_war_dialer           pwn_jenkins_update_plugins
+pwn_autoinc_version              pwn_jenkins_useradd
+pwn_aws_describe_resources       pwn_mail_agent
+pwn_bdba_groups                  pwn_msf_postgres_login
+pwn_bdba_scan                    pwn_nessus_cloud_scan_crud
+pwn_burp_suite_pro_active_rest_api_scan   pwn_nessus_cloud_vulnscan
+pwn_burp_suite_pro_active_scan   pwn_nexpose
+pwn_char_base64_encoding         pwn_nmap_discover_tcp_udp
+pwn_char_dec_encoding            pwn_openvas_vulnscan
+pwn_char_hex_escaped_encoding    pwn_pastebin_sample_filter
+pwn_char_html_entity_encoding    pwn_phone
+pwn_char_unicode_escaped_encoding  pwn_rdoc_to_jsonl
+pwn_char_url_encoding            pwn_sast
+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
+```
+
+Run any with `--help` for its flags.
+
+## Typical CI usage
+
+```yaml
+# .gitlab-ci.yml
+sast:
+  image: 0dayinc/pwn:latest
+  script:
+    - pwn_sast -d "$CI_PROJECT_DIR" -o sast_out/
+    - pwn_defectdojo_importscan -f sast_out/report.json -e "$DD_ENGAGEMENT"
+```
+
+## Write your own
+
+See [Drivers](Drivers.md) — copy any file in `bin/`, swap the plugin call,
+`rake install`, done.
+
+[← Home](Home.md)

data/documentation/Configuration.md

@@ -0,0 +1,66 @@
+# Configuration — `~/.pwn/config.yml`
+
+Everything configurable lives in one YAML file, loaded by `PWN::Config` at
+startup and available in-process as `PWN::Env`.
+
+## Minimal example
+
+```yaml
+# ~/.pwn/config.yml
+ai:
+  engine: anthropic          # openai | anthropic | grok | gemini | ollama
+  anthropic:
+    key: sk-ant-…
+  openai:
+    key: sk-…
+  grok:
+    oauth: true              # RFC-8628 device flow, no client_secret
+  ollama:
+    base_url: http://localhost:11434
+    model: llama3.1:70b
+  agent:
+    max_iters:      40       # tool-loop cap per turn
+    max_depth:      3        # swarm recursion cap
+    auto_reflect:   true     # Learning.auto_reflect after every final answer
+    auto_extrospect: true    # Extrospection.auto_extrospect likewise
+
+burp:
+  jar: /opt/burpsuite_pro/burpsuite_pro.jar
+  api_key: …
+
+metasploit:
+  host: 127.0.0.1
+  port: 55553
+  user: msf
+  pass: …
+```
+
+## Reading / writing at runtime
+
+```ruby
+PWN::Env[:ai][:engine]                 # => :anthropic
+PWN::Env[:ai][:agent][:auto_reflect]   # => true
+PWN::Config.reload!
+```
+
+## Sections PWN looks for
+
+| Key path | Consumed by |
+|---|---|
+| `ai.engine` | `PWN::AI::Agent::Loop` — which client to instantiate |
+| `ai.<engine>.key` / `.oauth` | `PWN::AI::OpenAI` / `Anthropic` / `Grok` / `Gemini` / `Ollama` |
+| `ai.agent.max_iters` | hard stop on tool-call rounds |
+| `ai.agent.max_depth` | `Swarm` recursion guard |
+| `ai.agent.auto_reflect` | toggle `Learning.auto_reflect` |
+| `ai.agent.auto_extrospect` | toggle `Extrospection.auto_extrospect` |
+| `burp.*` | `PWN::Plugins::BurpSuite` |
+| `metasploit.*` | `PWN::Plugins::Metasploit` |
+| `zap.*` | `PWN::Plugins::Zaproxy` |
+| `shodan.key` / `hunter.key` / … | respective OSINT plugins |
+| `aws.*` | `PWN::AWS::*` (falls back to standard AWS SDK env/instance-profile) |
+
+## Other files under `~/.pwn/`
+
+See [Persistence](Persistence.md) for the full map.
+
+[← Home](Home.md)

data/documentation/Contributing.md

@@ -1,31 +1,45 @@
 # Contributing
 
-Contributions that expand PWN's offensive capabilities are highly welcome.
+## Repo layout
 
-## How to Help
+```text
+lib/pwn/                # all namespaces
+lib/pwn/plugins/        # 66 plugin modules
+lib/pwn/ai/agent/       # agent core
+lib/pwn/ai/agent/tools/ # LLM tool registrations
+bin/                    # 52 pwn_* drivers
+spec/                   # RSpec (incl. conventions_spec)
+documentation/          # this wiki + diagrams
+```
 
-- New plugins (especially zero-day research, exploitation primitives, novel AI integrations)
-- Improvements to existing modules
-- New SAST signatures
-- AI skills (see [Skills-Memory-Learning](Skills-Memory-Learning.md))
-- Better documentation / wiki pages
-- Bridges to more commercial/open security tools
-- Bug reports with clear reproduction steps
+## Conventions (enforced by `spec/conventions_spec.rb`)
 
-## Process
+1. Every public module method is `public_class_method def self.name(opts = {})`.
+2. Every arg-accepting `def self.*` uses **exactly** `(opts = {})` — no
+   positional args, no keyword args.
+3. Every module has `self.help` returning a usage string.
+4. `# frozen_string_literal: true` at the top of every `.rb`.
 
-1. Review [CONTRIBUTING.md](../CONTRIBUTING.md) in the repo root.
-2. Open an issue or PR on https://github.com/0dayInc/pwn
-3. For large features, discuss first via email (support@0dayinc.com) or GitHub.
+## Quality gates
 
-## Code Style
+```bash
+rvmsudo rake            # rubocop + rspec — must be zero offenses
+```
 
-Follow RuboCop (project is clean). Write self-documenting methods with parameter descriptions matching existing plugin style.
+## Adding a plugin
 
-## Access
+1. `lib/pwn/plugins/my_thing.rb` following the conventions above.
+2. Autoload entry in `lib/pwn/plugins.rb`.
+3. `spec/lib/pwn/plugins/my_thing_spec.rb`.
+4. Optional `bin/pwn_my_thing` driver (see [Drivers](Drivers.md)).
+5. Optional agent tool in `lib/pwn/ai/agent/tools/` (see
+   [Agent Tool Registry](Agent-Tool-Registry.md)).
+6. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
+   relevant `.dot` in `documentation/diagrams/dot/` → `./build.sh`.
 
-If you have access to additional commercial LLMs, scanners, or bug bounty programs you are willing to integrate, please reach out.
+## Commit / release
 
-Thank you for helping push the state of open offensive security tooling forward!
+`./git_commit.sh` bumps `PWN::VERSION`, regenerates
+`third_party/pwn_rdoc.jsonl`, runs the gates, and pushes.
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/Cron.md

@@ -0,0 +1,47 @@
+# Cron — Scheduled Autonomous Jobs
+
+`PWN::Cron` (`lib/pwn/cron.rb`) stores job definitions in
+`~/.pwn/cron/jobs.yml` and can install a matching system-`crontab` line that
+invokes `PWN::Cron.run(<id>)` on schedule.
+
+![Cron scheduling](diagrams/cron-scheduling.svg)
+
+## Job kinds
+
+| Kind | Executed as | Use for |
+|---|---|---|
+| `prompt:` | `pwn --ai "<prompt>"` one-shot | "Re-scan scope nightly and diff findings" |
+| `ruby:` | `TOPLEVEL_BINDING.eval` in-process | Direct `PWN::Plugins` calls |
+| `script:` | `exec` external file | Anything not in Ruby |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `cron_create(schedule:, prompt:/ruby:/script:, install_crontab:)` | Define a job |
+| `cron_list` | id · name · schedule · enabled · last_run · last_status |
+| `cron_run(id:)` | Fire immediately (updates last_run/last_status) |
+| `cron_enable` / `cron_disable` | Toggle without deleting |
+| `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab — `crontab -e` yourself) |
+
+## Example
+
+```ruby
+cron_create(
+  name: 'nightly_scope_sweep',
+  schedule: '0 2 * * *',
+  prompt: 'extro_snapshot, then NmapIt sweep 10.0.0.0/24, extro_observe every '\
+          'new open port, extro_correlate, and post a one-paragraph summary.',
+  install_crontab: true
+)
+```
+
+At 02:00 the system cron fires `PWN::Cron.run`, which spins up a headless
+`pwn-ai` turn. Because `auto_reflect` and `auto_extrospect` are on, the run
+also updates Learning/Metrics/Extrospection — so tomorrow's interactive
+session already knows what changed overnight.
+
+**See also:** [Sessions](Sessions.md) · [Extrospection](Extrospection.md) ·
+[CLI Drivers](CLI-Drivers.md)
+
+[← Home](Home.md)

data/documentation/Drivers.md

@@ -1,25 +1,52 @@
-# Drivers & Custom Automation
+# Drivers — Turn a REPL Session into a Shipped Binary
 
-`PWN::Driver` and the `/opt/pwn/bin/` directory provide patterns for packaging reusable security automation.
+A **driver** is a small executable in `bin/` that wires `OptionParser` to one
+or more `PWN::` calls. All 52 shipped `pwn_*` binaries follow the same
+15-line template.
 
-## What is a Driver?
+![History → Driver → CI](diagrams/history-to-drivers.svg)
 
-A self-contained Ruby script or gem that:
-- Loads the `pwn` environment
-- Orchestrates multiple plugins, AI calls, or custom logic
-- Can be scheduled via cron or run standalone
+## Workflow
 
-## Examples
+1. **Prototype in the REPL** until the calls work.
+2. `history` → copy the winning lines.
+3. Drop them into the template below as `bin/pwn_<name>`.
+4. `chmod +x bin/pwn_<name>` · add to `pwn.gemspec` executables · `rake install`.
+5. (Optional) `learning_distill_skill(name: '<name>')` so the agent knows the
+   procedure too.
 
-Look in `/opt/pwn/bin/` (shipped with the gem).
+## Template
 
-## Creating New Drivers
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-1. Study existing examples in `bin/`.
-2. Use `PWN::Driver` helpers where appropriate.
-3. Leverage the full plugin + AI surface.
-4. Distill recurring successful patterns into **Skills**.
+require 'optparse'
+require 'pwn'
 
-Drivers + Skills + Agent = extremely powerful autonomous red teaming / research platform.
+opts = {}
+OptionParser.new do |o|
+  o.banner = "USAGE: #{File.basename($PROGRAM_NAME)} [opts]"
+  o.on('-tTARGET', '--target=TARGET', 'Required target') { |v| opts[:target] = v }
+  o.on('-oDIR',    '--out=DIR',       'Output directory') { |v| opts[:out]    = v }
+end.parse!
 
-[[Diagrams]]
+raise OptionParser::MissingArgument, '-t' unless opts[:target]
+
+result = PWN::Plugins::NmapIt.port_scan(target: opts[:target])
+PWN::Reports::Fuzz.generate(result: result, dir_path: opts[:out]) if opts[:out]
+puts result
+```
+
+## Three artefact types from one REPL session
+
+| Artefact | Made with | Consumed by |
+|---|---|---|
+| `bin/pwn_<name>` | template above | shell / CI |
+| `~/.pwn/skills/<name>.md` | `learning_distill_skill` | every future pwn-ai prompt |
+| `cron` job | `cron_create(ruby: '…')` | system crontab → unattended |
+
+**See also:** [CLI Drivers](CLI-Drivers.md) · [Cron](Cron.md) ·
+[Skills, Memory & Learning](Skills-Memory-Learning.md)
+
+[← Home](Home.md)

data/documentation/Extrospection.md

@@ -0,0 +1,54 @@
+# Extrospection — World Awareness
+
+`PWN::AI::Agent::Extrospection` is the **outward-facing** counterpart to
+[Learning](Skills-Memory-Learning.md). Where Learning/Metrics ask *"how well
+did **I** do?"*, Extrospection asks *"what does the **world** look like right
+now, and has it changed under me?"*
+
+![Extrospection engine](diagrams/extrospection-world-awareness.svg)
+
+## Verbs
+
+| Tool | Does | Persists to |
+|---|---|---|
+| `extro_snapshot` | Fingerprint host/net/toolchain/repo/env → hash | `extrospection.json` (`snapshot` + rotates `previous`) |
+| `extro_drift` | Diff live-vs-stored (or stored-vs-previous) | — returns `{changed, added, removed}` with dotted keys |
+| `extro_observe` | Record a recon fact (banner, CVE match, topology note) | `observations[]` |
+| `extro_observations` | Query recorded facts by source/category/target/tag | — |
+| `extro_intel` | Query NVD / CIRCL / Exploit-DB for keyword or CVE | optional `record: true` → `:intel` observations |
+| `extro_correlate` | **Join** introspection ↔ extrospection | — actionable findings |
+| `extro_stats` | snapshot age · observation count · drift counts | — |
+| `extro_reset` | Wipe snapshot + observations (new engagement) | — |
+| `extro_auto_toggle` | Enable/disable auto-snapshot after every final answer | `PWN::Env[:ai][:agent][:auto_extrospect]` |
+
+## `extro_correlate` — the point of the whole thing
+
+```text
+(a) Metrics tools with <50 % success   ×  toolchain drift / missing binaries
+(b) Learning failures on day X         ×  host/net/repo drift on day X
+(c) recorded :intel observations       ×  installed component versions
+```
+
+Output tells the agent whether a failure was **its own fault** ("I called the
+API wrong") or **the world changed** ("nmap was upgraded and the flag moved")
+— and that distinction is written back into MEMORY so the next run doesn't
+waste iterations rediscovering it.
+
+## Typical engagement flow
+
+```ruby
+extro_reset(confirm: true)             # clean slate for new scope
+extro_snapshot                         # baseline
+# … recon …
+extro_observe(source: 'nmap', target: '10.0.0.5',
+              category: 'recon', data: 'OpenSSH 8.2p1 Ubuntu')
+extro_intel(query: 'OpenSSH 8.2p1', record: true)
+# … days later, something breaks …
+extro_drift                            # what moved?
+extro_correlate                        # why did it break?
+```
+
+**See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[pwn-ai Agent](pwn-ai-Agent.md)
+
+[← Home](Home.md)

data/documentation/FFI.md

@@ -0,0 +1,14 @@
+# `PWN::FFI` — Native Calls
+
+`PWN::FFI::Stdio` (`lib/pwn/ffi/stdio.rb`) exposes libc functions to Ruby via
+the `ffi` gem — useful for shellcode testing, format-string research and
+low-level RE without leaving the REPL.
+
+```ruby
+PWN::FFI::Stdio.printf(fmt: "leak: %p\n", args: [0x41414141])
+```
+
+Combine with `PWN::Plugins::Assembly` (opcodes ↔ asm) and `pwn-asm` for a
+minimal in-process exploit-dev workbench.
+
+[← Home](Home.md) · [Hardware](Hardware.md)

data/documentation/Fuzzing.md

@@ -0,0 +1,36 @@
+# Fuzzing — `PWN::Plugins::Fuzz` · `Sock` · `Packet`
+
+![Fuzzing workflow](diagrams/fuzzing-workflow.svg)
+
+## Generate
+
+```ruby
+payloads = PWN::Plugins::Fuzz.generate(
+  seed: "GET / HTTP/1.1\r\nHost: t\r\n\r\n",
+  strategy: :radamsa,       # :radamsa | :bitflip | :dictionary
+  count: 500
+)
+enc = PWN::Plugins::Char.url_encode(str: payloads.first)
+```
+
+## Deliver
+
+```ruby
+payloads.each do |p|
+  PWN::Plugins::Sock.connect(target: '10.0.0.5', port: 8080) do |s|
+    s.write(p); s.read
+  end
+end
+```
+
+For raw L2/L3: `PWN::Plugins::Packet`.
+CLI network fuzzer: `pwn_fuzz_net_app_proto -t HOST -p PORT -f seeds/`
+
+## Monitor & report
+
+`PWN::Plugins::PS` watches the target process; `PWN::Plugins::Log` tails its
+log; `PWN::Reports::Fuzz` renders crash → HTML/JSON.
+
+Feed unique crashes back as new seeds (`Log → Fuzz` dashed edge in the diagram).
+
+[← Home](Home.md) · [Reporting](Reporting.md)

data/documentation/Hardware.md

@@ -0,0 +1,40 @@
+# Hardware & Physical-Layer Hacking
+
+![Hardware hacking](diagrams/hardware-hacking.svg)
+![Reverse engineering](diagrams/reverse-engineering-flow.svg)
+
+## Serial / Bus
+
+| Module | Use |
+|---|---|
+| `PWN::Plugins::Serial` | Generic UART (`/dev/ttyUSB*`) — read/write, baud detect |
+| `PWN::Plugins::BusPirate` | SPI/I²C/1-Wire via Bus Pirate |
+| `PWN::Plugins::MSR206` | ISO magstripe read/write (tracks 1-3) |
+
+CLI: `pwn_serial_msr206`, `pwn_serial_qualcomm_commands`,
+`pwn_serial_check_voicemail`, `pwn_serial_son_micro_sm132_rfid`
+
+## Mobile
+
+`PWN::Plugins::Android` — `adb_net_connect`, `adb_sh`, `adb_push/pull`,
+`take_screenshot`, `screen_record`, `list_installed_apps`, `dumpsys`,
+`open_app`, `find_hidden_codes`, `swipe`, `input`, `input_special`,
+`invoke_event_listener`. CLI war-dialer: `pwn_android_war_dialer`.
+
+## Voice / Telephony
+
+`PWN::Plugins::BareSIP` (SIP recon/war-dial), `PWN::Plugins::Voice` (TTS).
+CLI: `pwn_phone`.
+
+## Radio
+
+See [SDR](SDR.md) — GQRX, FlipperZero, RFIDler, SonMicro.
+
+## Binary / RE
+
+- `PWN::Plugins::XXD` — hex dump / patch
+- `PWN::Plugins::Assembly` + `pwn-asm` REPL — opcodes ↔ asm, multi-arch
+- `PWN::Plugins::BlackDuckBinaryAnalysis` — SBOM + CVE match on firmware
+- [`PWN::FFI`](FFI.md) — call libc from Ruby
+
+[← Home](Home.md) · [SDR](SDR.md) · [FFI](FFI.md)

data/documentation/Metasploit.md

@@ -0,0 +1,34 @@
+# `PWN::Plugins::Metasploit`
+
+RPC client for `msfrpcd` — search modules, set options, run exploits, interact
+with sessions, all from Ruby.
+
+## Configure
+
+```yaml
+# ~/.pwn/config.yml
+metasploit:
+  host: 127.0.0.1
+  port: 55553
+  user: msf
+  pass: …
+```
+
+Start the daemon: `msfrpcd -U msf -P … -a 127.0.0.1 -p 55553 -S`
+
+## Use
+
+```ruby
+msf = PWN::Plugins::Metasploit.connect
+mods = PWN::Plugins::Metasploit.search(msf_obj: msf, query: 'jenkins')
+PWN::Plugins::Metasploit.use(msf_obj: msf,
+  module_type: 'exploit',
+  module_name: 'multi/http/jenkins_script_console')
+PWN::Plugins::Metasploit.set_option(msf_obj: msf, opt: 'RHOSTS', val: '10.0.0.5')
+job = PWN::Plugins::Metasploit.run(msf_obj: msf)
+PWN::Plugins::Metasploit.sessions(msf_obj: msf)
+```
+
+CLI: `pwn_msf_postgres_login -H 10.0.0.5 -U users.txt -P pass.txt`
+
+[← Home](Home.md) · [Plugins](Plugins.md)