pwn 0.5.613 → 0.5.617

data/documentation/Troubleshooting.md

@@ -0,0 +1,38 @@
+# Troubleshooting
+
+## Common Issues
+
+### Burp / ZAP Proxy Problems
+- Prefer `PWN::Plugins::BurpSuite`
+- 502 errors usually mean upstream proxy not listening or crashed. Check with `ps`, `ss -tlnp`, restart via plugin methods.
+
+### Ruby / Gemset Issues
+- Use RVM and the gemset defined in `.ruby-version` / `.ruby-gemset`.
+- Re-run `./install.sh ruby-gem` or the vagrant provisioner after Ruby upgrades.
+
+### AI / LLM Authentication
+- Grok uses OAuth device flow (public client) — see `xai_grok_oauth_device_flow` skill.
+- Store credentials via `PWN::Config` or environment as documented.
+
+### SHIFT+ENTER Not Working in pwn-ai
+- Requires tmux `extended-keys on` on **both** inner and outer sides.
+- See recent lessons in memory for exact tmux config.
+
+### Git / Permissions
+- Run `sudo chown -R $USER:$USER /opt/pwn` if permission issues after install.
+
+## Diagnostics
+
+```bash
+pwn
+PWN.help
+# Inside REPL:
+PWN::Config
+PWN::Plugins::PWNLogger
+```
+
+Check `~/.pwn/` for logs, metrics, learning files.
+
+Report bugs via GitHub issues with full reproduction + `pwn` version.
+
+[[Diagrams]]

data/documentation/What-is-PWN.md

@@ -0,0 +1,53 @@
+# What is PWN
+
+**PWN** (pronounced /pōn/ — "pone") is an open-source **offensive-security
+automation framework** and **continuous-security-integration** platform,
+distributed as a Ruby gem.
+
+It gives security researchers, red teamers, bug-bounty hunters and DevSecOps
+engineers a single, scriptable surface over the entire offensive toolchain —
+from OSINT and network discovery, through web/cloud/hardware/radio
+exploitation, to reporting and disclosure — and puts a **self-improving,
+tool-calling AI agent** on top of it.
+
+## In numbers
+
+| Namespace | Count | What it is |
+|---|---|---|
+| `PWN::Plugins::*` | **66** | Wrappers for external + native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, …) |
+| `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::*` | **21** | Site-specific browser automations (HackerOne, BugCrowd, Google, LinkedIn, …) |
+| `PWN::SDR::*` | **6** | GQRX, FlipperZero, RFIDler, SonMicro, decoders, band tables |
+| `PWN::AI::*` | **5** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama |
+| `bin/pwn_*` | **52** | Headless CLI drivers for CI/CD |
+| Agent toolsets | **10** | terminal · pwn · memory · skills · sessions · learning · metrics · extrospection · cron · swarm |
+
+## The three ways to use it
+
+1. **`pwn` REPL** — a Pry shell with the whole `PWN::` namespace pre-loaded.
+   Prototype an attack chain interactively, one method call at a time.
+2. **`pwn-ai`** — a natural-language TUI (or `pwn --ai "…"` one-shot) where an
+   LLM plans and executes those same method calls for you, records what
+   worked, and gets better at it.
+3. **`bin/pwn_*` drivers** — thin CLIs over the plugins, for cron and CI/CD.
+
+## What makes it different
+
+- **Everything is Ruby, everything is a method.** No YAML DSLs, no plugins-in-a-
+  black-box. If you can call it in the REPL, the AI agent can call it, a driver
+  can call it, and a cron job can call it.
+- **Closed self-improvement loop.** Metrics + Learning (introspection) and
+  Snapshot + Drift + Intel (extrospection) feed `extro_correlate`, which tells
+  the agent whether a failure was *its* fault or *the world* changed — and
+  writes the lesson back into the prompt for next time.
+- **Native multi-agent.** `PWN::AI::Agent::Swarm` runs personas (each a full
+  tool-calling agent, optionally on a *different* LLM engine) that debate,
+  broadcast and share an append-only bus — no IRC daemon, no external service.
+
+![Overall Architecture](diagrams/overall-pwn-architecture.svg)
+
+**Next:** [Why PWN](Why-PWN.md) · [How PWN Works](How-PWN-Works.md) ·
+[Installation](Installation.md)
+
+[← Home](Home.md)

data/documentation/Why-PWN.md

@@ -0,0 +1,48 @@
+# Why PWN
+
+## The problem
+
+Offensive security is a **toolchain problem**. A single engagement touches
+`nmap`, `burp`, `msfconsole`, a headless browser, `adb`, `gqrx`, three cloud
+consoles, a fuzzer, `radare2`, a spreadsheet of findings, and a bug-bounty
+submission form. Each tool has its own config, its own output format, and its
+own idea of what a "target" is. Gluing them together is 80 % of the job — and
+that glue is rewritten, badly, on every engagement.
+
+Meanwhile, LLM agents are extraordinary at *planning* attack chains but have no
+reliable, auditable way to *execute* them against a real host.
+
+## The design bet
+
+PWN bets that the right abstraction is **plain Ruby methods with a uniform
+`opts = {}` signature**, exposed simultaneously to:
+
+- a human in a REPL,
+- an LLM in a tool-calling loop,
+- a shell script in CI,
+- a cron job at 3 am.
+
+Because every capability is a method, the same line of code works in all four
+contexts. Because every method is open-source Ruby, it's auditable — critical
+when the caller is an autonomous agent.
+
+## Why open primitives matter
+
+| Closed / black-box | PWN |
+|---|---|
+| "Trust our scanner" | `cat lib/pwn/sast/sql.rb` — read the regex yourself |
+| Per-seat licence for the glue | MIT-licensed glue; bring your own Burp Pro / Nessus key |
+| Agent output is a PDF | Agent output is a `PWN::Reports` object *and* a distilled skill *and* a memory entry |
+| One vendor's model | Five interchangeable engines; swarm can pit them against each other |
+
+## Why the self-improvement loop matters
+
+A pentest framework that doesn't learn repeats the same dead-end scans forever.
+PWN records **per-tool success rate**, **per-task outcome**, **host drift**,
+and **external CVE intel**, then correlates them so tomorrow's run starts where
+today's finished. See [Skills, Memory & Learning](Skills-Memory-Learning.md)
+and [Extrospection](Extrospection.md).
+
+**Next:** [How PWN Works](How-PWN-Works.md)
+
+[← Home](Home.md)

data/documentation/diagrams/ai-integration-tool-calling.svg

@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: PWN_AI_Integration Pages: 1 -->
+<svg width="680pt" height="496pt"
+ viewBox="0.00 0.00 680.00 496.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(43.2 453.2)">
+<title>PWN_AI_Integration</title>
+<polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-453.2 636.7,-453.2 636.7,43.2 -43.2,43.2"/>
+<text xml:space="preserve" text-anchor="start" x="98.75" y="-388" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">PWN::AI — Multi&#45;Provider LLM Integration</text>
+<text xml:space="preserve" text-anchor="start" x="186.12" y="-376.55" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">one Agent Loop · five interchangeable engines</text>
+<g id="clust1" class="cluster">
+<title>cluster_c</title>
+<path fill="#2e1065" stroke="#6d28d9" d="M213.25,-8C213.25,-8 365,-8 365,-8 371,-8 377,-14 377,-20 377,-20 377,-351 377,-351 377,-357 371,-363 365,-363 365,-363 213.25,-363 213.25,-363 207.25,-363 201.25,-357 201.25,-351 201.25,-351 201.25,-20 201.25,-20 201.25,-14 207.25,-8 213.25,-8"/>
+<text xml:space="preserve" text-anchor="middle" x="289.12" y="-340" font-family="sans-Serif" font-size="20.00" fill="#ddd6fe">PWN::AI::* Clients</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster_api</title>
+<path fill="#450a0a" stroke="#b91c1c" stroke-dasharray="5,2" d="M468,-8C468,-8 581.5,-8 581.5,-8 587.5,-8 593.5,-14 593.5,-20 593.5,-20 593.5,-351 593.5,-351 593.5,-357 587.5,-363 581.5,-363 581.5,-363 468,-363 468,-363 462,-363 456,-357 456,-351 456,-351 456,-20 456,-20 456,-14 462,-8 468,-8"/>
+<text xml:space="preserve" text-anchor="middle" x="524.75" y="-340" font-family="sans-Serif" font-size="20.00" fill="#fecaca">Provider APIs</text>
+</g>
+<!-- Loop -->
+<g id="node1" class="node">
+<title>Loop</title>
+<path fill="#7dd3fc" stroke="#334155" stroke-width="2" d="M102.25,-188C102.25,-188 12,-188 12,-188 6,-188 0,-182 0,-176 0,-176 0,-164 0,-164 0,-158 6,-152 12,-152 12,-152 102.25,-152 102.25,-152 108.25,-152 114.25,-158 114.25,-164 114.25,-164 114.25,-176 114.25,-176 114.25,-182 108.25,-188 102.25,-188"/>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-172.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">PWN::AI::Agent::Loop</text>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-160.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">tool&#45;calling harness</text>
+</g>
+<!-- OpenAI -->
+<g id="node2" class="node">
+<title>OpenAI</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M303.62,-324C303.62,-324 273.62,-324 273.62,-324 267.62,-324 261.62,-318 261.62,-312 261.62,-312 261.62,-300 261.62,-300 261.62,-294 267.62,-288 273.62,-288 273.62,-288 303.62,-288 303.62,-288 309.62,-288 315.62,-294 315.62,-300 315.62,-300 315.62,-312 315.62,-312 315.62,-318 309.62,-324 303.62,-324"/>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-302.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">OpenAI</text>
+</g>
+<!-- Loop&#45;&gt;OpenAI -->
+<g id="edge1" class="edge">
+<title>Loop&#45;&gt;OpenAI</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M80.78,-188.81C108.07,-210.83 155.92,-247.41 201.25,-272 217.35,-280.74 236.19,-288.42 252.15,-294.26"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="250.85,-296.77 259.33,-296.82 252.73,-291.49 250.85,-296.77"/>
+</g>
+<!-- Anthropic -->
+<g id="node3" class="node">
+<title>Anthropic</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M305.25,-256C305.25,-256 272,-256 272,-256 266,-256 260,-250 260,-244 260,-244 260,-232 260,-232 260,-226 266,-220 272,-220 272,-220 305.25,-220 305.25,-220 311.25,-220 317.25,-226 317.25,-232 317.25,-232 317.25,-244 317.25,-244 317.25,-250 311.25,-256 305.25,-256"/>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-234.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Anthropic</text>
+</g>
+<!-- Loop&#45;&gt;Anthropic -->
+<g id="edge2" class="edge">
+<title>Loop&#45;&gt;Anthropic</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M115.15,-186.9C157.31,-199.39 213.54,-216.05 250.15,-226.9"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="249.12,-229.51 257.59,-229.1 250.71,-224.14 249.12,-229.51"/>
+</g>
+<!-- Grok -->
+<g id="node4" class="node">
+<title>Grok</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M324.75,-188C324.75,-188 252.5,-188 252.5,-188 246.5,-188 240.5,-182 240.5,-176 240.5,-176 240.5,-164 240.5,-164 240.5,-158 246.5,-152 252.5,-152 252.5,-152 324.75,-152 324.75,-152 330.75,-152 336.75,-158 336.75,-164 336.75,-164 336.75,-176 336.75,-176 336.75,-182 330.75,-188 324.75,-188"/>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-172.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Grok</text>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-160.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">OAuth device flow</text>
+</g>
+<!-- Loop&#45;&gt;Grok -->
+<g id="edge3" class="edge">
+<title>Loop&#45;&gt;Grok</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M115.15,-170C150.34,-170 195.32,-170 230.53,-170"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="230.21,-172.8 238.21,-170 230.21,-167.2 230.21,-172.8"/>
+</g>
+<!-- Gemini -->
+<g id="node5" class="node">
+<title>Gemini</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M303.62,-120C303.62,-120 273.62,-120 273.62,-120 267.62,-120 261.62,-114 261.62,-108 261.62,-108 261.62,-96 261.62,-96 261.62,-90 267.62,-84 273.62,-84 273.62,-84 303.62,-84 303.62,-84 309.62,-84 315.62,-90 315.62,-96 315.62,-96 315.62,-108 315.62,-108 315.62,-114 309.62,-120 303.62,-120"/>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-98.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Gemini</text>
+</g>
+<!-- Loop&#45;&gt;Gemini -->
+<g id="edge4" class="edge">
+<title>Loop&#45;&gt;Gemini</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M115.15,-153.1C157.92,-140.43 215.17,-123.47 251.73,-112.64"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="252.25,-115.4 259.12,-110.44 250.66,-110.03 252.25,-115.4"/>
+</g>
+<!-- Ollama -->
+<g id="node6" class="node">
+<title>Ollama</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M303.62,-52C303.62,-52 273.62,-52 273.62,-52 267.62,-52 261.62,-46 261.62,-40 261.62,-40 261.62,-28 261.62,-28 261.62,-22 267.62,-16 273.62,-16 273.62,-16 303.62,-16 303.62,-16 309.62,-16 315.62,-22 315.62,-28 315.62,-28 315.62,-40 315.62,-40 315.62,-46 309.62,-52 303.62,-52"/>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-36.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Ollama</text>
+<text xml:space="preserve" text-anchor="middle" x="288.62" y="-24.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">(local)</text>
+</g>
+<!-- Loop&#45;&gt;Ollama -->
+<g id="edge5" class="edge">
+<title>Loop&#45;&gt;Ollama</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M80.78,-151.19C108.07,-129.17 155.92,-92.59 201.25,-68 217.35,-59.26 236.19,-51.58 252.15,-45.74"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="252.73,-48.51 259.33,-43.18 250.85,-43.23 252.73,-48.51"/>
+</g>
+<!-- A1 -->
+<g id="node7" class="node">
+<title>A1</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.3" d="M553.25,-324C553.25,-324 495.25,-324 495.25,-324 489.25,-324 483.25,-318 483.25,-312 483.25,-312 483.25,-300 483.25,-300 483.25,-294 489.25,-288 495.25,-288 495.25,-288 553.25,-288 553.25,-288 559.25,-288 565.25,-294 565.25,-300 565.25,-300 565.25,-312 565.25,-312 565.25,-318 559.25,-324 553.25,-324"/>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-302.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">api.openai.com</text>
+</g>
+<!-- OpenAI&#45;&gt;A1 -->
+<g id="edge6" class="edge">
+<title>OpenAI&#45;&gt;A1</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M315.97,-306C353.96,-306 424.85,-306 473.03,-306"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="472.98,-308.8 480.98,-306 472.98,-303.2 472.98,-308.8"/>
+</g>
+<!-- A2 -->
+<g id="node8" class="node">
+<title>A2</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.3" d="M558.88,-256C558.88,-256 489.62,-256 489.62,-256 483.62,-256 477.62,-250 477.62,-244 477.62,-244 477.62,-232 477.62,-232 477.62,-226 483.62,-220 489.62,-220 489.62,-220 558.88,-220 558.88,-220 564.88,-220 570.88,-226 570.88,-232 570.88,-232 570.88,-244 570.88,-244 570.88,-250 564.88,-256 558.88,-256"/>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-234.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">api.anthropic.com</text>
+</g>
+<!-- Anthropic&#45;&gt;A2 -->
+<g id="edge7" class="edge">
+<title>Anthropic&#45;&gt;A2</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M317.81,-238C354.74,-238 420.36,-238 467.51,-238"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="467.31,-240.8 475.31,-238 467.31,-235.2 467.31,-240.8"/>
+</g>
+<!-- A3 -->
+<g id="node9" class="node">
+<title>A3</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.3" d="M539.25,-188C539.25,-188 509.25,-188 509.25,-188 503.25,-188 497.25,-182 497.25,-176 497.25,-176 497.25,-164 497.25,-164 497.25,-158 503.25,-152 509.25,-152 509.25,-152 539.25,-152 539.25,-152 545.25,-152 551.25,-158 551.25,-164 551.25,-164 551.25,-176 551.25,-176 551.25,-182 545.25,-188 539.25,-188"/>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-172.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">api.x.ai</text>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-160.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">auth.x.ai</text>
+</g>
+<!-- Grok&#45;&gt;A3 -->
+<g id="edge8" class="edge">
+<title>Grok&#45;&gt;A3</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M337.18,-170C381.49,-170 446.6,-170 486.89,-170"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="486.84,-172.8 494.84,-170 486.84,-167.2 486.84,-172.8"/>
+</g>
+<!-- A4 -->
+<g id="node10" class="node">
+<title>A4</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.3" d="M562.25,-120C562.25,-120 486.25,-120 486.25,-120 480.25,-120 474.25,-114 474.25,-108 474.25,-108 474.25,-96 474.25,-96 474.25,-90 480.25,-84 486.25,-84 486.25,-84 562.25,-84 562.25,-84 568.25,-84 574.25,-90 574.25,-96 574.25,-96 574.25,-108 574.25,-108 574.25,-114 568.25,-120 562.25,-120"/>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-104.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">generativelanguage</text>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-92.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">.googleapis.com</text>
+</g>
+<!-- Gemini&#45;&gt;A4 -->
+<g id="edge9" class="edge">
+<title>Gemini&#45;&gt;A4</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M315.97,-102C351.62,-102 416.24,-102 463.88,-102"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="463.81,-104.8 471.81,-102 463.81,-99.2 463.81,-104.8"/>
+</g>
+<!-- A5 -->
+<g id="node11" class="node">
+<title>A5</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.3" d="M554.38,-52C554.38,-52 494.12,-52 494.12,-52 488.12,-52 482.12,-46 482.12,-40 482.12,-40 482.12,-28 482.12,-28 482.12,-22 488.12,-16 494.12,-16 494.12,-16 554.38,-16 554.38,-16 560.38,-16 566.38,-22 566.38,-28 566.38,-28 566.38,-40 566.38,-40 566.38,-46 560.38,-52 554.38,-52"/>
+<text xml:space="preserve" text-anchor="middle" x="524.25" y="-30.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">localhost:11434</text>
+</g>
+<!-- Ollama&#45;&gt;A5 -->
+<g id="edge10" class="edge">
+<title>Ollama&#45;&gt;A5</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M315.97,-34C353.63,-34 423.6,-34 471.75,-34"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="471.71,-36.8 479.71,-34 471.71,-31.2 471.71,-36.8"/>
+</g>
+<!-- Cfg -->
+<g id="node12" class="node">
+<title>Cfg</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M108.25,-82.75C108.25,-85.78 85.33,-88.25 57.12,-88.25 28.92,-88.25 6,-85.78 6,-82.75 6,-82.75 6,-33.25 6,-33.25 6,-30.22 28.92,-27.75 57.12,-27.75 85.33,-27.75 108.25,-30.22 108.25,-33.25 108.25,-33.25 108.25,-82.75 108.25,-82.75"/>
+<path fill="none" stroke="#334155" stroke-width="1.3" d="M108.25,-82.75C108.25,-79.72 85.33,-77.25 57.12,-77.25 28.92,-77.25 6,-79.72 6,-82.75"/>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-66.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">PWN::Config</text>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-54.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">~/.pwn/config.yml</text>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-42.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">engine · key · oauth</text>
+</g>
+<!-- Cfg&#45;&gt;Loop -->
+<g id="edge11" class="edge">
+<title>Cfg&#45;&gt;Loop</title>
+<path fill="none" stroke="#fbbf24" stroke-width="1.3" stroke-dasharray="5,2" d="M57.12,-88.6C57.12,-104.97 57.12,-125 57.12,-141.1"/>
+<polygon fill="#fbbf24" stroke="#fbbf24" stroke-width="1.3" points="54.33,-141.06 57.13,-149.06 59.93,-141.06 54.33,-141.06"/>
+<text xml:space="preserve" text-anchor="middle" x="48.88" y="-116.83" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">active engine</text>
+</g>
+</g>
+</svg>

data/documentation/diagrams/build.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Regenerate every PWN data-flow diagram SVG from its .dot source.
+# Usage: ./build.sh            # build all
+#        ./build.sh foo.dot    # build one
+set -euo pipefail
+cd "$(dirname "$0")"
+DOT_BIN="${DOT_BIN:-dot}"
+SRC_DIR="dot"
+build_one() {
+  local src="$1"
+  local base="$(basename "$src" .dot)"
+  echo "  [dot] ${base}.svg"
+  "$DOT_BIN" -Tsvg "-Gfontnames=svg" "$src" -o "${base}.svg"
+}
+if [[ $# -gt 0 ]]; then
+  for f in "$@"; do build_one "$f"; done
+else
+  for f in "$SRC_DIR"/*.dot; do build_one "$f"; done
+fi
+echo "[done] $(ls -1 *.svg | wc -l) SVG diagram(s) in $(pwd)"

data/documentation/diagrams/burp-vs-zap-preference.svg

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: PWN_BurpVsZap Pages: 1 -->
+<svg width="639pt" height="421pt"
+ viewBox="0.00 0.00 639.00 421.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(43.2 377.9)">
+<title>PWN_BurpVsZap</title>
+<polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-377.9 595.45,-377.9 595.45,43.2 -43.2,43.2"/>
+<text xml:space="preserve" text-anchor="start" x="8" y="-312.7" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">Web Proxy Selection — BurpSuite ⭐ preferred over ZAP</text>
+<!-- Need -->
+<g id="node1" class="node">
+<title>Need</title>
+<polygon fill="#7dd3fc" stroke="#334155" stroke-width="1.3" points="286.12,-302.7 214.04,-263.1 286.12,-223.5 358.21,-263.1 286.12,-302.7"/>
+<text xml:space="preserve" text-anchor="middle" x="286.12" y="-265.6" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Need web proxy /</text>
+<text xml:space="preserve" text-anchor="middle" x="286.12" y="-253.6" font-family="sans-Serif" font-size="10.00" fill="#0f172a">active scanner?</text>
+</g>
+<!-- Burp -->
+<g id="node2" class="node">
+<title>Burp</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="2" d="M259.88,-147C259.88,-147 122.38,-147 122.38,-147 116.38,-147 110.38,-141 110.38,-135 110.38,-135 110.38,-115 110.38,-115 110.38,-109 116.38,-103 122.38,-103 122.38,-103 259.88,-103 259.88,-103 265.88,-103 271.88,-109 271.88,-115 271.88,-115 271.88,-135 271.88,-135 271.88,-141 265.88,-147 259.88,-147"/>
+<text xml:space="preserve" text-anchor="middle" x="191.12" y="-133.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">PWN::Plugins::BurpSuite</text>
+<text xml:space="preserve" text-anchor="middle" x="191.12" y="-121.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">headless · REST · richer scanner</text>
+<text xml:space="preserve" text-anchor="middle" x="191.12" y="-109.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">BApp ecosystem</text>
+</g>
+<!-- Need&#45;&gt;Burp -->
+<g id="edge1" class="edge">
+<title>Need&#45;&gt;Burp</title>
+<path fill="none" stroke="#34d399" stroke-width="2" d="M263.68,-235.55C252.87,-222.34 239.99,-205.92 229.38,-190.5 222.14,-179.99 214.84,-168.07 208.59,-157.37"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="2" points="211.09,-156.11 204.68,-150.58 206.24,-158.91 211.09,-156.11"/>
+<text xml:space="preserve" text-anchor="middle" x="267.25" y="-181.95" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">Burp Pro available</text>
+</g>
+<!-- Zap -->
+<g id="node3" class="node">
+<title>Zap</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M429.88,-143C429.88,-143 334.38,-143 334.38,-143 328.38,-143 322.38,-137 322.38,-131 322.38,-131 322.38,-119 322.38,-119 322.38,-113 328.38,-107 334.38,-107 334.38,-107 429.88,-107 429.88,-107 435.88,-107 441.88,-113 441.88,-119 441.88,-119 441.88,-131 441.88,-131 441.88,-137 435.88,-143 429.88,-143"/>
+<text xml:space="preserve" text-anchor="middle" x="382.12" y="-127.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">PWN::Plugins::Zaproxy</text>
+<text xml:space="preserve" text-anchor="middle" x="382.12" y="-115.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">OSS fallback</text>
+</g>
+<!-- Need&#45;&gt;Zap -->
+<g id="edge2" class="edge">
+<title>Need&#45;&gt;Zap</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M306.02,-233.9C323.14,-209.63 347.62,-174.92 364.16,-151.47"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="366.4,-153.15 368.73,-144.99 361.83,-149.92 366.4,-153.15"/>
+<text xml:space="preserve" text-anchor="middle" x="358.47" y="-181.95" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">fallback</text>
+</g>
+<!-- Both -->
+<g id="node4" class="node">
+<title>Both</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M390.5,-36C390.5,-36 181.75,-36 181.75,-36 175.75,-36 169.75,-30 169.75,-24 169.75,-24 169.75,-12 169.75,-12 169.75,-6 175.75,0 181.75,0 181.75,0 390.5,0 390.5,0 396.5,0 402.5,-6 402.5,-12 402.5,-12 402.5,-24 402.5,-24 402.5,-30 396.5,-36 390.5,-36"/>
+<text xml:space="preserve" text-anchor="middle" x="286.12" y="-20.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Same downstream:</text>
+<text xml:space="preserve" text-anchor="middle" x="286.12" y="-8.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">TransparentBrowser proxy · Reports · DefectDojo</text>
+</g>
+<!-- Burp&#45;&gt;Both -->
+<g id="edge3" class="edge">
+<title>Burp&#45;&gt;Both</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M210.81,-102.24C226.22,-85.21 247.65,-61.52 263.72,-43.77"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="265.63,-45.83 268.92,-38.02 261.48,-42.07 265.63,-45.83"/>
+</g>
+<!-- Zap&#45;&gt;Both -->
+<g id="edge4" class="edge">
+<title>Zap&#45;&gt;Both</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M366.27,-106.66C350.57,-89.49 326.37,-63.02 308.67,-43.66"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="310.79,-41.83 303.33,-37.82 306.66,-45.61 310.79,-41.83"/>
+</g>
+</g>
+</svg>

data/documentation/diagrams/code-scanning-sast.svg

@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: PWN_SAST Pages: 1 -->
+<svg width="818pt" height="484pt"
+ viewBox="0.00 0.00 818.00 484.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(43.2 441.2)">
+<title>PWN_SAST</title>
+<polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-441.2 775.2,-441.2 775.2,43.2 -43.2,43.2"/>
+<text xml:space="preserve" text-anchor="start" x="131.25" y="-376" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">PWN::SAST — Static Application Security Testing</text>
+<text xml:space="preserve" text-anchor="start" x="229.88" y="-364.55" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">48 rules · multi&#45;language · bin/pwn_sast · Reports::SAST</text>
+<g id="clust1" class="cluster">
+<title>cluster_engine</title>
+<path fill="#022c22" stroke="#047857" d="M178,-138C178,-138 290.75,-138 290.75,-138 296.75,-138 302.75,-144 302.75,-150 302.75,-150 302.75,-274 302.75,-274 302.75,-280 296.75,-286 290.75,-286 290.75,-286 178,-286 178,-286 172,-286 166,-280 166,-274 166,-274 166,-150 166,-150 166,-144 172,-138 178,-138"/>
+<text xml:space="preserve" text-anchor="middle" x="234.38" y="-263" font-family="sans-Serif" font-size="20.00" fill="#a7f3d0">SAST Engine</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster_rules</title>
+<path fill="#422006" stroke="#a16207" d="M384.75,-8C384.75,-8 538.75,-8 538.75,-8 544.75,-8 550.75,-14 550.75,-20 550.75,-20 550.75,-339 550.75,-339 550.75,-345 544.75,-351 538.75,-351 538.75,-351 384.75,-351 384.75,-351 378.75,-351 372.75,-345 372.75,-339 372.75,-339 372.75,-20 372.75,-20 372.75,-14 378.75,-8 384.75,-8"/>
+<text xml:space="preserve" text-anchor="middle" x="461.75" y="-328" font-family="sans-Serif" font-size="20.00" fill="#fde68a">Rule Families (48)</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster_out</title>
+<path fill="#2e1065" stroke="#6d28d9" d="M632.75,-138C632.75,-138 712,-138 712,-138 718,-138 724,-144 724,-150 724,-150 724,-274 724,-274 724,-280 718,-286 712,-286 712,-286 632.75,-286 632.75,-286 626.75,-286 620.75,-280 620.75,-274 620.75,-274 620.75,-150 620.75,-150 620.75,-144 626.75,-138 632.75,-138"/>
+<text xml:space="preserve" text-anchor="middle" x="672.38" y="-263" font-family="sans-Serif" font-size="20.00" fill="#ddd6fe">Output</text>
+</g>
+<!-- Src -->
+<g id="node1" class="node">
+<title>Src</title>
+<path fill="#7dd3fc" stroke="#334155" stroke-width="1.3" d="M76,-214C76,-214 12,-214 12,-214 6,-214 0,-208 0,-202 0,-202 0,-190 0,-190 0,-184 6,-178 12,-178 12,-178 76,-178 76,-178 82,-178 88,-184 88,-190 88,-190 88,-202 88,-202 88,-208 82,-214 76,-214"/>
+<text xml:space="preserve" text-anchor="middle" x="44" y="-198.88" font-family="sans-Serif" font-size="10.00" fill="#0f172a">📁 &#160;Source Tree</text>
+<text xml:space="preserve" text-anchor="middle" x="44" y="-186.12" font-family="sans-Serif" font-size="10.00" fill="#0f172a">git clone / repo</text>
+</g>
+<!-- Factory -->
+<g id="node2" class="node">
+<title>Factory</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.3" d="M261.75,-182C261.75,-182 206,-182 206,-182 200,-182 194,-176 194,-170 194,-170 194,-158 194,-158 194,-152 200,-146 206,-146 206,-146 261.75,-146 261.75,-146 267.75,-146 273.75,-152 273.75,-158 273.75,-158 273.75,-170 273.75,-170 273.75,-176 267.75,-182 261.75,-182"/>
+<text xml:space="preserve" text-anchor="middle" x="233.88" y="-166.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SAST::Factory</text>
+<text xml:space="preserve" text-anchor="middle" x="233.88" y="-154.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">rule loader</text>
+</g>
+<!-- Src&#45;&gt;Factory -->
+<g id="edge1" class="edge">
+<title>Src&#45;&gt;Factory</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" d="M88.57,-188.58C117.01,-183.73 154.19,-177.4 183.69,-172.38"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="184.02,-175.16 191.44,-171.06 183.08,-169.64 184.02,-175.16"/>
+</g>
+<!-- TCE -->
+<g id="node3" class="node">
+<title>TCE</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.3" d="M265.88,-247C265.88,-247 201.88,-247 201.88,-247 195.88,-247 189.88,-241 189.88,-235 189.88,-235 189.88,-223 189.88,-223 189.88,-217 195.88,-211 201.88,-211 201.88,-211 265.88,-211 265.88,-211 271.88,-211 277.88,-217 277.88,-223 277.88,-223 277.88,-235 277.88,-235 277.88,-241 271.88,-247 265.88,-247"/>
+<text xml:space="preserve" text-anchor="middle" x="233.88" y="-231.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">TestCaseEngine</text>
+<text xml:space="preserve" text-anchor="middle" x="233.88" y="-219.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">generate probes</text>
+</g>
+<!-- Src&#45;&gt;TCE -->
+<g id="edge2" class="edge">
+<title>Src&#45;&gt;TCE</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" d="M88.57,-203.65C115.84,-208.44 151.15,-214.65 180.02,-219.72"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="179.24,-222.42 187.6,-221.05 180.2,-216.91 179.24,-222.42"/>
+</g>
+<!-- Cmd -->
+<g id="node4" class="node">
+<title>Cmd</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M515.75,-52C515.75,-52 406.75,-52 406.75,-52 400.75,-52 394.75,-46 394.75,-40 394.75,-40 394.75,-28 394.75,-28 394.75,-22 400.75,-16 406.75,-16 406.75,-16 515.75,-16 515.75,-16 521.75,-16 527.75,-22 527.75,-28 527.75,-28 527.75,-40 527.75,-40 527.75,-46 521.75,-52 515.75,-52"/>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-36.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">cmd_execution_*</text>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-24.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">java · py · ruby · go · scala</text>
+</g>
+<!-- Factory&#45;&gt;Cmd -->
+<g id="edge3" class="edge">
+<title>Factory&#45;&gt;Cmd</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M257.15,-145.65C283.5,-124.59 329.29,-90 372.75,-67 379.97,-63.18 387.73,-59.58 395.54,-56.28"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="396.54,-58.89 402.88,-53.27 394.42,-53.71 396.54,-58.89"/>
+</g>
+<!-- Web -->
+<g id="node5" class="node">
+<title>Web</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M526.62,-117C526.62,-117 395.88,-117 395.88,-117 389.88,-117 383.88,-111 383.88,-105 383.88,-105 383.88,-93 383.88,-93 383.88,-87 389.88,-81 395.88,-81 395.88,-81 526.62,-81 526.62,-81 532.62,-81 538.62,-87 538.62,-93 538.62,-93 538.62,-105 538.62,-105 538.62,-111 532.62,-117 526.62,-117"/>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-101.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">csrf · redirect · redos</text>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-89.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">inner/outer_html · location_hash</text>
+</g>
+<!-- Factory&#45;&gt;Web -->
+<g id="edge4" class="edge">
+<title>Factory&#45;&gt;Web</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M274.39,-152.6C305.35,-143.68 349.28,-131 386.67,-120.22"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="387.22,-122.98 394.13,-118.07 385.67,-117.6 387.22,-122.98"/>
+</g>
+<!-- Cryp -->
+<g id="node6" class="node">
+<title>Cryp</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M519.5,-182C519.5,-182 403,-182 403,-182 397,-182 391,-176 391,-170 391,-170 391,-158 391,-158 391,-152 397,-146 403,-146 403,-146 519.5,-146 519.5,-146 525.5,-146 531.5,-152 531.5,-158 531.5,-158 531.5,-170 531.5,-170 531.5,-176 525.5,-182 519.5,-182"/>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-166.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">md5 · ssl · keystore</text>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-154.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">padding_oracle · private_key</text>
+</g>
+<!-- Factory&#45;&gt;Cryp -->
+<g id="edge5" class="edge">
+<title>Factory&#45;&gt;Cryp</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M274.39,-164C303.83,-164 345,-164 381.11,-164"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="380.69,-166.8 388.69,-164 380.69,-161.2 380.69,-166.8"/>
+</g>
+<!-- Data -->
+<g id="node7" class="node">
+<title>Data</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M510.88,-247C510.88,-247 411.62,-247 411.62,-247 405.62,-247 399.62,-241 399.62,-235 399.62,-235 399.62,-223 399.62,-223 399.62,-217 405.62,-211 411.62,-211 411.62,-211 510.88,-211 510.88,-211 516.88,-211 522.88,-217 522.88,-223 522.88,-223 522.88,-235 522.88,-235 522.88,-241 516.88,-247 510.88,-247"/>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-231.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">sql · eval · deserial_java</text>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-219.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">log4j · php_type_juggling</text>
+</g>
+<!-- TCE&#45;&gt;Data -->
+<g id="edge6" class="edge">
+<title>TCE&#45;&gt;Data</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M278.33,-229C309.8,-229 353.03,-229 389.45,-229"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="389.07,-231.8 397.07,-229 389.07,-226.2 389.07,-231.8"/>
+</g>
+<!-- Mem -->
+<g id="node8" class="node">
+<title>Mem</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M491,-312C491,-312 431.5,-312 431.5,-312 425.5,-312 419.5,-306 419.5,-300 419.5,-300 419.5,-288 419.5,-288 419.5,-282 425.5,-276 431.5,-276 431.5,-276 491,-276 491,-276 497,-276 503,-282 503,-288 503,-288 503,-300 503,-300 503,-306 497,-312 491,-312"/>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-296.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">banned_c_calls</text>
+<text xml:space="preserve" text-anchor="middle" x="461.25" y="-284.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">use_after_free</text>
+</g>
+<!-- TCE&#45;&gt;Mem -->
+<g id="edge7" class="edge">
+<title>TCE&#45;&gt;Mem</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M278.33,-241.53C315.99,-252.39 370.49,-268.11 410.01,-279.51"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="408.85,-282.09 417.32,-281.62 410.41,-276.71 408.85,-282.09"/>
+</g>
+<!-- Report -->
+<g id="node9" class="node">
+<title>Report</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M701.75,-182C701.75,-182 643,-182 643,-182 637,-182 631,-176 631,-170 631,-170 631,-158 631,-158 631,-152 637,-146 643,-146 643,-146 701.75,-146 701.75,-146 707.75,-146 713.75,-152 713.75,-158 713.75,-158 713.75,-170 713.75,-170 713.75,-176 707.75,-182 701.75,-182"/>
+<text xml:space="preserve" text-anchor="middle" x="672.38" y="-166.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Reports::SAST</text>
+<text xml:space="preserve" text-anchor="middle" x="672.38" y="-154.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">HTML + JSON</text>
+</g>
+<!-- Cmd&#45;&gt;Report -->
+<g id="edge8" class="edge">
+<title>Cmd&#45;&gt;Report</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M520.12,-52.52C530.59,-56.72 541.2,-61.57 550.75,-67 586.16,-87.14 621.93,-117.44 645.22,-138.81"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="643.12,-140.67 650.88,-144.07 646.93,-136.57 643.12,-140.67"/>
+</g>
+<!-- Web&#45;&gt;Report -->
+<g id="edge9" class="edge">
+<title>Web&#45;&gt;Report</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M522.18,-117.63C553.54,-127.38 591.51,-139.17 621.29,-148.43"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="620.3,-151.06 628.77,-150.76 621.96,-145.71 620.3,-151.06"/>
+</g>
+<!-- Cryp&#45;&gt;Report -->
+<g id="edge10" class="edge">
+<title>Cryp&#45;&gt;Report</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M531.89,-164C560.86,-164 593.87,-164 620.51,-164"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="620.42,-166.8 628.42,-164 620.42,-161.2 620.42,-166.8"/>
+</g>
+<!-- DD -->
+<g id="node10" class="node">
+<title>DD</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M704,-247C704,-247 640.75,-247 640.75,-247 634.75,-247 628.75,-241 628.75,-235 628.75,-235 628.75,-223 628.75,-223 628.75,-217 634.75,-211 640.75,-211 640.75,-211 704,-211 704,-211 710,-211 716,-217 716,-223 716,-223 716,-235 716,-235 716,-241 710,-247 704,-247"/>
+<text xml:space="preserve" text-anchor="middle" x="672.38" y="-231.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">DefectDojo</text>
+<text xml:space="preserve" text-anchor="middle" x="672.38" y="-219.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">import / reimport</text>
+</g>
+<!-- Data&#45;&gt;DD -->
+<g id="edge11" class="edge">
+<title>Data&#45;&gt;DD</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M523.3,-229C553.39,-229 589.33,-229 618.26,-229"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="618.22,-231.8 626.22,-229 618.22,-226.2 618.22,-231.8"/>
+</g>
+<!-- Mem&#45;&gt;DD -->
+<g id="edge12" class="edge">
+<title>Mem&#45;&gt;DD</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M503.57,-281.16C536.68,-270.87 583.34,-256.36 619.05,-245.26"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="619.66,-248.01 626.47,-242.96 618,-242.66 619.66,-248.01"/>
+</g>
+</g>
+</svg>

data/documentation/diagrams/dot/_THEME.md

@@ -0,0 +1,27 @@
+# PWN Diagram Visual Theme
+
+All `.dot` files in this directory share one visual language so the rendered
+SVGs feel like a single coherent product.
+
+| Element              | Color     | Hex       |
+|----------------------|-----------|-----------|
+| Background           | slate-900 | `#0f172a` |
+| Cluster border       | slate-700 | `#334155` |
+| Cluster fill         | slate-800 | `#1e293b` |
+| Actor / Entry (blue) | sky-300   | `#7dd3fc` |
+| AI / Agent (purple)  | violet-300| `#c4b5fd` |
+| Capability (green)   | emerald-300| `#6ee7b7`|
+| Persistence (amber)  | amber-300 | `#fcd34d` |
+| Target / Danger (red)| rose-300  | `#fda4af` |
+| Edge default         | slate-400 | `#94a3b8` |
+| Edge highlight       | sky-400   | `#38bdf8` |
+
+Layout rules (to avoid criss-crossed edges):
+1. `rankdir=TB` (or `LR` for pipelines), `newrank=true`, `splines=spline`.
+2. Group every layer with `{rank=same; ...}` — edges go layer→layer only.
+3. Side/back edges use `constraint=false` + `style=dashed` and are kept to ≤3 per diagram.
+4. One `subgraph cluster_*` per logical layer with a translucent fill.
+5. Node order inside a rank matches edge destinations in the next rank
+   (Graphviz then draws parallel non-crossing edges).
+
+Rebuild everything: `./build.sh` (from `documentation/diagrams/`).