pwn 0.5.615 → 0.5.618

data/documentation/How-PWN-Works.md

@@ -1,60 +1,62 @@
 # How PWN Works
 
-PWN is structured as a Ruby gem with a rich `PWN::` namespace.
-
-## Visual Architecture Overview
-
-See the full set of **[Data Flow Diagrams](Diagrams.md)** (18+ SVGs) for detailed visualization of data flows, including:
-
-![Overall PWN Architecture](diagrams/overall-pwn-architecture.svg)
-
-- [PWN-AI Feedback Learning Loop](diagrams/pwn-ai-feedback-learning-loop.svg) — the core self-improving closed loop
-- [REPL Prototyping](diagrams/pwn-repl-prototyping.svg)
-- [History → Drivers & Skills](diagrams/history-to-drivers.svg)
-- [AI Tool Calling Integration](diagrams/ai-integration-tool-calling.svg)
-- [Plugin Ecosystem](diagrams/plugin-ecosystem.svg)
-- And many more specific workflows (Pen Testing, Web, Fuzzing, SAST, RE, etc.)
-
-## Namespace Overview
-
-| Namespace          | Description |
-|--------------------|-------------|
-| `PWN::Plugins::*`  | 67+ specialized modules (see [Plugins](Plugins.md)) |
-| `PWN::AI::*`       | Multi-provider LLM clients + autonomous `PWN::AI::Agent` |
-| `PWN::SAST`        | Static application security testing + test case generation |
-| `PWN::Reports`     | Automated reporting from scans, agents, findings |
-| `PWN::Memory`      | Persistent facts across sessions |
-| `PWN::Sessions`    | Record / replay conversations and workflows |
-| `PWN::Cron`        | Scheduled autonomous tasks |
-| `PWN::Skills`      | Reusable markdown procedures (distilled from successful runs) |
-| `PWN::Config`      | Environment + credential management |
-| `PWN::Driver`      | Framework for custom security automation packages |
-
-## Primary Interfaces
-
-1. **pwn REPL** — Pry-powered interactive shell (launched via `pwn` command). Full `PWN` namespace pre-loaded.
-2. **pwn-ai** — Autonomous AI agent TUI inside the REPL (highly recommended). Uses tool calling for `pwn_eval`, shell, skills, memory, etc.
-3. **Custom Drivers** — See `/opt/pwn/bin/` examples and [Drivers](Drivers.md).
-
-## LLM Tool Calling
-
-The agent can:
-- Execute any PWN plugin method directly
-- Run shell commands
-- Recall/remember facts
-- Distill new skills from successful workflows
-- Use multiple LLM providers (OpenAI, Anthropic, Gemini, Grok OAuth, Ollama, ...)
-
-Example:
-```
-pwn-ai
-> Use NmapIt to scan target.example.com, spider with TransparentBrowser, proxy via BurpSuite, run SAST if source available, then generate report.
-```
-
-See the Diagrams and:
-- [pwn REPL](pwn-REPL.md)
-- [pwn-ai Agent](pwn-ai-Agent.md)
-- [Plugins](Plugins.md)
-- [AI Integration](AI-Integration.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
+PWN is five layers, each visible in the source tree. Edges only ever go
+**down** one layer (or sideways within a layer), which is why the diagrams
+below have no criss-crossing lines.
 
+![Overall Architecture](diagrams/overall-pwn-architecture.svg)
+
+## L0 — Actors
+
+Humans (`pwn` REPL, `pwn-ai` TUI), CI runners (`pwn --ai "…"`, `bin/pwn_*`),
+LLM providers (over HTTPS), and targets (hosts, web apps, clouds, radios,
+hardware).
+
+## L1 — Entry points  (`bin/`)
+
+| Entry | File | Purpose |
+|---|---|---|
+| `pwn` REPL | `lib/pwn/plugins/repl.rb` | Pry with `PWN::` pre-loaded + custom commands |
+| `pwn-ai` | `lib/pwn/ai/agent/loop.rb` | Agent TUI inside the REPL |
+| `pwn --ai PROMPT` | `bin/pwn` | Headless one-shot agent (CI-friendly) |
+| `bin/pwn_*` | 52 files | Thin OptionParser wrappers over one plugin each |
+| `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs → any of the above |
+
+## L2 — AI agent core  (`lib/pwn/ai/agent/`)
+
+| Module | Role |
+|---|---|
+| `Loop` | plan → dispatch tool_calls → observe → repeat until final answer |
+| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** |
+| `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
+| `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / EXTROSPECTION blocks |
+| `Metrics` · `Learning` | **introspection** — how well am I doing? |
+| `Extrospection` | **extrospection** — what does the world look like? |
+| `Swarm` | multi-agent personas over a shared JSONL bus |
+
+See [Agent Tool Registry](Agent-Tool-Registry.md) for every tool the LLM can call.
+
+## L3 — Capability namespaces  (`lib/pwn/*`)
+
+`Plugins` (66) · `SAST` (48) · `WWW` (21) · `AWS` (90) · `SDR` · `Blockchain` ·
+`Bounty` · `Reports` · `FFI` · `Banner`. Each is a plain module of
+`public_class_method def self.x(opts = {})` methods — callable identically from
+the REPL, from `pwn_eval`, or from a driver.
+
+## L4 — Persistence  (`~/.pwn/`)
+
+Everything the framework remembers between processes lives in one directory:
+
+![~/.pwn map](diagrams/persistence-filesystem.svg)
+
+See [Persistence](Persistence.md) for the byte-level layout of each file.
+
+## The feedback loop
+
+The reason L2 exists is to close this loop on every turn:
+
+![Self-improvement loop](diagrams/pwn-ai-feedback-learning-loop.svg)
+
+**Next:** [pwn REPL](pwn-REPL.md) · [pwn-ai Agent](pwn-ai-Agent.md)
+
+[← Home](Home.md)

data/documentation/Installation.md

@@ -1,50 +1,75 @@
 # Installation
 
-Tested primarily on Debian-based Linux (including Kali) and macOS using RVM-managed Ruby.
+PWN is tested on **Debian-based Linux** (Kali, Ubuntu) and **macOS**, using
+Ruby via **RVM**.
 
-## Quick Install (Recommended)
+## Quick install (recommended)
 
 ```bash
-$ cd /opt
-$ sudo git clone https://github.com/0dayInc/pwn
-$ cd /opt/pwn
-$ ./install.sh
-$ ./install.sh ruby-gem
-$ pwn
-pwn[v0.5.613]:001 >>> PWN.help
+cd /opt
+sudo git clone https://github.com/0dayinc/pwn
+cd /opt/pwn
+./install.sh          # system deps (nmap, chromium, graphviz, …)
+./install.sh ruby-gem # rvm gemset + bundle install + rake install
+pwn                   # launch the REPL
 ```
 
-## Video Guide
-
-[![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
+```text
+pwn[v0.5.616]:001 >>> PWN.help
+```
 
-## Ruby Gem Updates
+## Gem-only install
 
 ```bash
-$ rvm use ruby-4.0.5@pwn
-$ gem uninstall --all --executables pwn
-$ gem install --verbose pwn
+rvm install ruby-4.0.5
+rvm use     ruby-4.0.5@pwn --create
+gem install --verbose pwn
+pwn
 ```
 
-For multi-user RVM use `rvmsudo` instead of `sudo` on gem commands.
+## Upgrading
 
-## Upgrade Path (Ruby + PWN)
+```bash
+rvm use ruby-4.0.5@pwn
+gem uninstall --all --executables pwn
+gem install --verbose pwn
+```
 
-Use the vagrant provisioner or:
+or from a checkout:
 
 ```bash
-$ /opt/pwn/vagrant/provisioners/pwn.sh
+cd /opt/pwn && git pull && rvmsudo rake install
 ```
 
-This rebuilds the gemset when `.ruby-version` advances.
+## First-run configuration
+
+`pwn` creates `~/.pwn/` on first launch. Add at least one LLM engine to
+`~/.pwn/config.yml` to enable `pwn-ai` — see [Configuration](Configuration.md).
 
-## Requirements
+## Optional external tools
 
-- Ruby (via RVM recommended)
-- Git
-- Build tools (for native extensions)
-- Optional: Burp Suite Pro, Metasploit, etc. for full plugin capability
+PWN wraps these when present on `$PATH`; none are hard requirements:
+
+| Tool | Used by |
+|---|---|
+| `nmap` | `PWN::Plugins::NmapIt` |
+| Burp Suite Pro (+ REST API) | `PWN::Plugins::BurpSuite` |
+| `msfconsole` / msfrpcd | `PWN::Plugins::Metasploit` |
+| `chromium` / `google-chrome` | `PWN::Plugins::TransparentBrowser` |
+| `zaproxy` | `PWN::Plugins::Zaproxy` (fallback) |
+| `gqrx` | `PWN::SDR::GQRX` |
+| `adb` | `PWN::Plugins::Android` |
+| `graphviz` (`dot`) | rebuilding these diagrams |
+| `tor` | `PWN::Plugins::Tor` |
+
+## Verify
+
+```ruby
+pwn[v0.5.616]:001 >>> PWN::Plugins.constants.count   # => 66
+pwn[v0.5.616]:002 >>> PWN::SAST.constants.count      # => 48
+pwn[v0.5.616]:003 >>> pwn-ai                         # launches agent TUI
+```
 
-See the root [README.md](../README.md) and `install.sh` for latest details.
+**Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md)
 
-[[Diagrams]]
+[← Home](Home.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)

data/documentation/NmapIt.md

@@ -1,18 +1,24 @@
-# NmapIt
+# `PWN::Plugins::NmapIt`
 
-`PWN::Plugins::NmapIt` provides a convenient Ruby wrapper around Nmap for reconnaissance.
+Thin, composable wrapper over `nmap` with structured XML parsing.
 
-## Features
+![Network & infra testing](diagrams/network-infra-testing.svg)
 
-- Easy target specification (hosts, ranges, CIDR)
-- Parsing of XML output into usable Ruby structures
-- Service version detection, script execution support
-- Integration with other plugins (e.g. feed into TransparentBrowser or Shodan)
+```ruby
+r = PWN::Plugins::NmapIt.port_scan(
+  target: '10.0.0.0/24',
+  ports:  '1-1024',
+  service_scan: true,
+  script:  'default,vuln',
+  output_xml: '/tmp/scan.xml'
+)
+r[:hosts].each { |h| puts "#{h[:ip]} → #{h[:ports].map { |p| p[:portid] }}" }
+```
 
-Commonly used early in agent workflows:
+CLI: `pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/`
 
-> "Run NmapIt against 10.0.0.0/24, identify web services, then spider with TransparentBrowser."
+Pairs with `extro_observe` to persist banners for later
+[correlation](Extrospection.md), and with `PWN::Plugins::Sock` /
+`PWN::Plugins::Metasploit` for follow-up.
 
-See source in `lib/pwn/plugins/nmap_it.rb`.
-
-[[Diagrams]]
+[← Home](Home.md) · [Plugins](Plugins.md)

data/documentation/Persistence.md

@@ -0,0 +1,38 @@
+# `~/.pwn/` — Persistence Map
+
+Every byte PWN remembers between processes lives here.
+
+![~/.pwn map](diagrams/persistence-filesystem.svg)
+
+| Path | Owner | Format | Reset tool | Purpose |
+|---|---|---|---|---|
+| `config.yml` | `PWN::Config` | YAML | edit by hand | engines, keys, agent options |
+| `memory.json` | `PWN::Memory` | JSON array | `memory_clear` | facts · prefs · lessons · env — injected into every prompt |
+| `skills/*.md` | `PWN::Config.load_skills` | Markdown + YAML front-matter | `skill_delete` | reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST) |
+| `learning.jsonl` | `PWN::AI::Agent::Learning` | JSON-per-line | `learning_reset` | task outcome log → success_rate |
+| `metrics.json` | `PWN::AI::Agent::Metrics` | JSON | `metrics_reset` | per-tool calls · success · avg_duration · last_error |
+| `extrospection.json` | `PWN::AI::Agent::Extrospection` | JSON | `extro_reset` | host snapshot + previous baseline + observations[] |
+| `sessions/*.jsonl` | `PWN::Sessions` | JSON-per-line | `sessions_delete` | full transcript per pwn-ai run |
+| `cron/jobs.yml` | `PWN::Cron` | YAML | `cron_remove` | scheduled prompt/ruby/script jobs |
+| `cron/log/*.log` | `PWN::Cron` | text | rm | last_run output |
+| `agents.yml` | `PWN::AI::Agent::Swarm` | YAML | edit / `agent_spawn` | persona registry |
+| `swarm/<id>/bus.jsonl` | `Swarm` | JSON-per-line | rm -rf | append-only multi-agent chat |
+| `swarm/<id>/personas.json` | `Swarm` | JSON | rm | persona → session_id map |
+| `~/.pwn_history` | Pry | text | rm | REPL input history |
+
+## Back it up
+
+```bash
+tar czf pwn-state-$(date +%F).tgz -C "$HOME" .pwn
+```
+
+## Start fresh for a new engagement
+
+```ruby
+# inside pwn-ai — keeps config & skills, wipes engagement-specific state
+extro_reset(confirm: true)     # host snapshot + observations
+learning_reset(confirm: true)  # task outcomes (optional)
+metrics_reset(confirm: true)   # tool telemetry (optional)
+```
+
+[← Home](Home.md) · [Configuration](Configuration.md)

data/documentation/Plugins.md

@@ -1,59 +1,109 @@
-# Plugins
+# `PWN::Plugins` — All 66 Modules
 
-PWN ships with **66+** plugins under `PWN::Plugins::*`.
+Every plugin is a plain Ruby module of `public_class_method def self.x(opts = {})`
+methods with self-documenting `.help`. Source: `lib/pwn/plugins/*.rb`.
 
-## Browsing Plugins
+![Plugin ecosystem](diagrams/plugin-ecosystem.svg)
+
+## Discover in the REPL
 
 ```ruby
 PWN::Plugins.constants.sort
-PWN::Plugins::BurpSuite.methods(false).sort   # preferred web proxy/scanner
+PWN::Plugins::BurpSuite.help
+ls PWN::Plugins::NmapIt
+show-source PWN::Plugins::Fuzz.generate
 ```
 
-## Major Categories & Highlights
-
-### Web / Proxy / Scanning
-- **burp_suite** (preferred) — Headless + live interaction with Burp Suite Professional
-- **zaproxy** — OWASP ZAP support (fallback)
-- **transparent_browser** — Headless/visible browser automation, spidering, JS execution
-- **spider**
-- **nmap_it** — Nmap wrapper + parsing
-- **nessus_cloud**, **nexpose_vuln_scan**, **openvas**
-
-### Exploitation & Post-Exploitation
-- **metasploit**
-- **assembly**
-- **fuzz**
-- **packet**
-- **beef** (Browser Exploitation Framework)
-- **tor**
-
-### Recon / OSINT
-- **shodan**
-- **hunter**
-- **ip_info**
-- **github**
-- **hacker_one**
-
-### Data & Auth
-- **authentication_helper**, **basic_auth**, **oauth2**
-- **dao_ldap**, **dao_mongo**, **dao_postgres**, **dao_sqlite3**
-- **vault**
-
-### Mobile / Hardware / Misc
-- **android**
-- **serial**, **bus_pirate**, **msr206**
-- **ocr**, **pdf_parse**, **voice**
-- **blockchain**, **bounty** (HackerOne), **defect_dojo**
+## By category
 
-### Utility
-- **file_fu**, **json_pathify**, **log**, **pwn_logger**, **thread_pool**
-- **monkey_patch**, **xxd**, **char**, **vin**, **ssn**, **credit_card**
+### Web / Proxy / Browser
+| Module | Purpose | Doc |
+|---|---|---|
+| **`BurpSuite`** ⭐ | Headless + REST control of Burp Pro; active/passive scan | [BurpSuite](BurpSuite.md) |
+| `Zaproxy` | OWASP ZAP (fallback) | — |
+| **`TransparentBrowser`** | Watir/Chrome headless or visible; devtools; proxy-aware | [Transparent-Browser](Transparent-Browser.md) |
+| `Spider` | Recursive crawler | — |
+| `OpenAPI` | Swagger/OpenAPI parse + fuzz targets | — |
+| `URIScheme` | URI helpers | — |
+
+### Network
+| Module | Purpose | Doc |
+|---|---|---|
+| **`NmapIt`** | Nmap wrapper + XML parse | [NmapIt](NmapIt.md) |
+| `Sock` | Raw TCP/UDP client; banner grab | — |
+| `Packet` | Craft/sniff L2/L3 (PacketFu) | — |
+| `Tor` | Start/rotate Tor for egress | — |
+| `IPInfo` | Geo/ASN lookup | — |
+
+### Exploitation
+| Module | Purpose | Doc |
+|---|---|---|
+| **`Metasploit`** | msfrpcd client; run modules; sessions | [Metasploit](Metasploit.md) |
+| **`Fuzz`** | Mutation/generation fuzzer | [Fuzzing](Fuzzing.md) |
+| `BeEF` | Browser Exploitation Framework hooks | — |
+| `Assembly` | asm ↔ opcodes (multi-arch, keystone/capstone) | — |
+
+### OSINT / Recon
+| Module | Purpose |
+|---|---|
+| `Shodan` | host/search/GraphQL introspection |
+| `Hunter` | email discovery |
+| `Github` | code/secret search |
+| `HackerOne` | program/report API |
+
+### Data Access / Parsing
+| Module | Purpose |
+|---|---|
+| `DAOLdap` · `DAOMongo` · `DAOPostgres` · `DAOSqlite3` | DB clients |
+| `JSONPathify` | JSONPath query |
+| `PDFParse` · `OCR` | document extraction |
+| `ScannableCodes` | QR/barcode gen/read |
 
-Full list (current as of build):
-`android assembly authentication_helper baresip basic_auth beef black_duck_binary_analysis burp_suite bus_pirate char credit_card dao_ldap dao_mongo dao_postgres dao_sqlite3 defect_dojo detect_os ein file_fu fuzz git github hacker_one hunter ip_info irc jenkins jira_data_center json_pathify log mail_agent metasploit monkey_patch msr206 nessus_cloud nexpose_vuln_scan nmap_it oauth2 ocr open_api openvas packet pdf_parse pony ps pwn_logger rabbit_mq repl scannable_codes serial shodan slack_client sock spider ssn thread_pool tor transparent_browser twitter_api uri_scheme vault vin voice vsphere xxd zaproxy`
+### Auth / Secrets
+| Module | Purpose |
+|---|---|
+| `OAuth2` · `BasicAuth` · `AuthenticationHelper` | credential flows |
+| `Vault` | HashiCorp Vault |
+
+### Hardware / Physical
+| Module | Purpose | Doc |
+|---|---|---|
+| `Serial` · `BusPirate` | UART/SPI/I²C | [Hardware](Hardware.md) |
+| `MSR206` | magstripe reader/writer | [Hardware](Hardware.md) |
+| `Android` | adb push/pull/shell/screencap | [Hardware](Hardware.md) |
+| `BareSIP` · `Voice` | VoIP war-dialing / TTS | [Hardware](Hardware.md) |
+
+### CI / DevOps / Vuln-Mgmt
+| Module | Purpose |
+|---|---|
+| `Jenkins` | jobs/views/plugins/users |
+| `Git` | repo helpers |
+| `vSphere` | VMware inventory |
+| `DefectDojo` | import/reimport findings |
+| `BlackDuckBinaryAnalysis` | SBOM + CVE match |
+| `NessusCloud` · `NexposeVulnScan` · `OpenVAS` | commercial/OSS scanners |
+| `JiraDataCenter` | ticket findings |
+
+### Comms
+| Module | Purpose |
+|---|---|
+| `MailAgent` · `Pony` | SMTP send |
+| `SlackClient` · `IRC` · `TwitterAPI` | chat/notify |
+| `RabbitMQ` | AMQP |
+
+### Utility
+`FileFu` · `ThreadPool` · `Log` · `PwnLogger` · `Char` · `XXD` · `DetectOS` ·
+`CreditCard` · `SSN` · `EIN` · `VIN` · `PS` · `MonkeyPatch` · `REPL`
 
-Each plugin has self-documenting method signatures viewable via the REPL or source in `lib/pwn/plugins/`.
+## Full alphabetical list
 
-See individual plugin pages or source for details. Many plugins accept common options and return rich Ruby objects.
+`Android Assembly AuthenticationHelper BareSIP BasicAuth BeEF
+BlackDuckBinaryAnalysis BurpSuite BusPirate Char CreditCard DAOLdap DAOMongo
+DAOPostgres DAOSqlite3 DefectDojo DetectOS EIN FileFu Fuzz Git Github
+HackerOne Hunter IPInfo IRC Jenkins JiraDataCenter JSONPathify Log MailAgent
+Metasploit MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt OAuth2 OCR
+OpenAPI OpenVAS Packet PDFParse Pony PS PwnLogger RabbitMQ REPL ScannableCodes
+Serial Shodan SlackClient Sock Spider SSN ThreadPool Tor TransparentBrowser
+TwitterAPI URIScheme Vault VIN Voice Vsphere XXD Zaproxy`
 
-[[Diagrams]]
+[← Home](Home.md) · [Diagrams](Diagrams.md)

data/documentation/Reporting.md

@@ -1,28 +1,35 @@
-# Reporting
+# `PWN::Reports` — Findings Pipeline
 
-`PWN::Reports` generates structured output from scans, agent runs, SAST results, and manual findings.
+![Reporting pipeline](diagrams/reporting-pipeline.svg)
 
-## Capabilities
+## Generators  (`lib/pwn/reports/*.rb`)
 
-- Vulnerability report templating (Markdown + other formats)
-- Integration with defect trackers (`PWN::Plugins::DefectDojo`, Jira, etc.)
-- Automated report generation after agent tasks or plugin runs
-- Custom report drivers
+| Module | Consumes | Emits |
+|---|---|---|
+| `Reports::SAST` | `PWN::SAST::Factory` output | HTML (with `HTMLHeader`/`HTMLFooter`) + JSON |
+| `Reports::Fuzz` | `PWN::Plugins::Fuzz` crash log | HTML + JSON |
+| `Reports::URIBuster` | `pwn_www_uri_buster` output | HTML |
+| `Reports::Phone` | `PWN::Plugins::BareSIP` recon | HTML |
+| `Reports::HTMLHeader` / `HTMLFooter` | — | shared chrome for all HTML reports |
 
-## Template
+## Delivery integrations
 
-See example report templates in the PWN repo (or generate with `PWN::Reports`). Full pipeline in [Diagrams](Diagrams.md).
+| Plugin | Purpose |
+|---|---|
+| `PWN::Plugins::DefectDojo` | `importscan` / `reimportscan` / `engagement_create` (also `bin/pwn_defectdojo_*`) |
+| `PWN::Plugins::JiraDataCenter` | Create issues from findings |
+| `PWN::Plugins::SlackClient` / `MailAgent` | Notify |
 
-## Usage Patterns
-
-Typically invoked at the end of reconnaissance → scanning → exploitation → analysis workflows:
+## Example
 
 ```ruby
-PWN::Reports.generate(...)
+findings = PWN::SAST::Factory.start(dir_path: './src')
+PWN::Reports::SAST.generate(
+  dir_path: './src', results_hash: findings, output_dir: './out'
+)
+PWN::Plugins::DefectDojo.importscan(
+  engagement_id: 42, file: './out/report.json', scan_type: 'PWN SAST'
+)
 ```
 
-The `pwn-ai` agent is frequently instructed to "analyze findings and produce a report."
-
-Combined with `PWN::Plugins::HackerOne` / bounty modules for streamlined disclosure workflows.
-
-[[Diagrams]]
+[← Home](Home.md) · [SAST](SAST.md) · [Fuzzing](Fuzzing.md)

data/documentation/SAST.md

@@ -1,32 +1,49 @@
-# SAST (Static Application Security Testing)
+# `PWN::SAST` — Static Application Security Testing
 
-`PWN::SAST` provides a growing collection of static analysis signatures and test case generators.
+48 language-aware rule modules + a `TestCaseEngine` + a `Factory` loader.
+Source: `lib/pwn/sast/*.rb`. CLI: `bin/pwn_sast`.
 
-## Location
+![SAST pipeline](diagrams/code-scanning-sast.svg)
 
-`lib/pwn/sast/` — one file per vulnerability class or mechanism.
+## Run it
 
-## Current Coverage (examples)
-
-- Command execution (multiple languages)
-- Deserialization (Java, etc.)
-- Eval / dangerous functions
-- CSRF, redirect, inner HTML, postMessage issues
-- Log4j, ReDoS, path traversal patterns
-- Credential / secret patterns (keystore, passwords, AWS keys)
-- Modern issues: prototype pollution, etc.
-- Custom signature engine + factory
-
-## Usage
+```bash
+# CLI driver
+pwn_sast -d /path/to/src -o /tmp/sast_out
+```
 
 ```ruby
-PWN::SAST.constants
-PWN::SAST::TestCaseEngine.generate(...)
-# Or call specific check modules
+# REPL / pwn_eval
+findings = PWN::SAST::Factory.start(dir_path: '/path/to/src')
+PWN::Reports::SAST.generate(dir_path: '/path/to/src',
+                            results_hash: findings,
+                            output_dir: '/tmp/sast_out')
 ```
 
-SAST results feed directly into reporting and can be orchestrated by the `pwn-ai` agent or custom drivers.
+## Rule families (48 modules)
+
+| Family | Modules |
+|---|---|
+| **Command execution** | `CmdExecutionJava` · `CmdExecutionPython` · `CmdExecutionRuby` · `CmdExecutionGoLang` · `CmdExecutionScala` · `Shell` · `Sudo` |
+| **Web / DOM** | `CSRF` · `Redirect` · `ReDOS` · `InnerHTML` · `OuterHTML` · `LocationHash` · `WindowLocationHash` · `PostMessage` · `LocalStorage` · `BeefHook` |
+| **Injection / eval** | `SQL` · `Eval` · `DeserialJava` · `Log4J` · `PHPInputMechanisms` · `PHPTypeJuggling` · `TypeScriptTypeJuggling` |
+| **Crypto / secrets** | `MD5` · `SSL` · `Keystore` · `PaddingOracle` · `PrivateKey` · `Signature` · `Token` · `Password` · `Base64` · `HTTPAuthorizationHeader` |
+| **Memory / native** | `BannedFunctionCallsC` · `UseAfterFree` |
+| **Infra / meta** | `AWS` · `AMQPConnectAsGuest` · `ApacheFileSystemUtilAPI` · `PomVersion` · `Version` · `Port` · `Logger` · `ThrowErrors` · `TaskTag` · `Emoticon` |
+| **Engine** | `Factory` (loader) · `TestCaseEngine` (probe generator) |
+
+## Write a rule
+
+Each rule implements `self.scan(opts = {})` taking `dir_path:` and returning an
+array of `{file:, line:, match:, cwe:, severity:}` hashes. Copy any existing
+rule in `lib/pwn/sast/`, add your regex/AST logic, and it's auto-loaded by
+`Factory`.
+
+## Downstream
+
+`PWN::Reports::SAST` → HTML + JSON → `PWN::Plugins::DefectDojo.importscan` →
+`PWN::Plugins::JiraDataCenter` tickets.
 
-See `lib/pwn/sast/` source for the full and growing list of modules.
+**See also:** [Reporting](Reporting.md) · [CLI Drivers](CLI-Drivers.md)
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/SDR.md

@@ -0,0 +1,40 @@
+# `PWN::SDR` — Software-Defined Radio & RF
+
+![SDR flow](diagrams/sdr-radio-flow.svg)
+
+## Modules  (`lib/pwn/sdr/*.rb`)
+
+| Module | Purpose |
+|---|---|
+| **`GQRX`** | Remote-control a running GQRX instance over TCP: tune, set demod, squelch, record, `get_spectrum_snapshot` (pure-Ruby FFT), scan ranges |
+| `FlipperZero` | Serial control of Flipper (sub-GHz, NFC, IR, iButton) |
+| `RFIDler` | 125 kHz RFID reader/emulator |
+| `SonMicroRFID` | SM130 13.56 MHz reader |
+| `FrequencyAllocation` | ITU/FCC band-plan lookup — "what lives at 433.92 MHz?" |
+| `Decoder::*` | Demodulator/protocol helpers |
+
+## CLI
+
+```bash
+pwn_gqrx_scanner --start 430e6 --stop 440e6 --step 12.5e3 --mode fast
+pwn_gqrx_scanner --start 118e6 --stop 137e6 --mode iterative --squelch -60
+```
+
+See skill `pwn_gqrx_scanner_fast_vs_iterative_scanning` for the trade-off.
+
+## REPL example
+
+```ruby
+g = PWN::SDR::GQRX.connect(host: '127.0.0.1', port: 7356)
+PWN::SDR::GQRX.set_freq(gqrx_sock: g, freq: 433_920_000)
+PWN::SDR::GQRX.set_demod(gqrx_sock: g, demod: 'AM')
+snap = PWN::SDR::GQRX.get_spectrum_snapshot(gqrx_sock: g)
+PWN::SDR::FrequencyAllocation.lookup(freq: 433_920_000)
+# => { band: 'ISM 433', typical: ['garage doors', 'weather stations', …] }
+```
+
+Record signal intel with `extro_observe(source: 'gqrx', category: 'recon', …)`.
+
+**See also:** [Hardware](Hardware.md) · [Extrospection](Extrospection.md)
+
+[← Home](Home.md)