pwn 0.5.613 → 0.5.615

data/documentation/Installation.md

@@ -0,0 +1,50 @@
+# Installation
+
+Tested primarily on Debian-based Linux (including Kali) and macOS using RVM-managed Ruby.
+
+## 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
+```
+
+## Video Guide
+
+[![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
+
+## Ruby Gem Updates
+
+```bash
+$ rvm use ruby-4.0.5@pwn
+$ gem uninstall --all --executables pwn
+$ gem install --verbose pwn
+```
+
+For multi-user RVM use `rvmsudo` instead of `sudo` on gem commands.
+
+## Upgrade Path (Ruby + PWN)
+
+Use the vagrant provisioner or:
+
+```bash
+$ /opt/pwn/vagrant/provisioners/pwn.sh
+```
+
+This rebuilds the gemset when `.ruby-version` advances.
+
+## Requirements
+
+- Ruby (via RVM recommended)
+- Git
+- Build tools (for native extensions)
+- Optional: Burp Suite Pro, Metasploit, etc. for full plugin capability
+
+See the root [README.md](../README.md) and `install.sh` for latest details.
+
+[[Diagrams]]

data/documentation/NmapIt.md

@@ -0,0 +1,18 @@
+# NmapIt
+
+`PWN::Plugins::NmapIt` provides a convenient Ruby wrapper around Nmap for reconnaissance.
+
+## Features
+
+- 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)
+
+Commonly used early in agent workflows:
+
+> "Run NmapIt against 10.0.0.0/24, identify web services, then spider with TransparentBrowser."
+
+See source in `lib/pwn/plugins/nmap_it.rb`.
+
+[[Diagrams]]

data/documentation/Plugins.md

@@ -0,0 +1,59 @@
+# Plugins
+
+PWN ships with **66+** plugins under `PWN::Plugins::*`.
+
+## Browsing Plugins
+
+```ruby
+PWN::Plugins.constants.sort
+PWN::Plugins::BurpSuite.methods(false).sort   # preferred web proxy/scanner
+```
+
+## 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**
+
+### Utility
+- **file_fu**, **json_pathify**, **log**, **pwn_logger**, **thread_pool**
+- **monkey_patch**, **xxd**, **char**, **vin**, **ssn**, **credit_card**
+
+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`
+
+Each plugin has self-documenting method signatures viewable via the REPL or source in `lib/pwn/plugins/`.
+
+See individual plugin pages or source for details. Many plugins accept common options and return rich Ruby objects.
+
+[[Diagrams]]

data/documentation/Reporting.md

@@ -0,0 +1,28 @@
+# Reporting
+
+`PWN::Reports` generates structured output from scans, agent runs, SAST results, and manual findings.
+
+## Capabilities
+
+- 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
+
+## Template
+
+See example report templates in the PWN repo (or generate with `PWN::Reports`). Full pipeline in [Diagrams](Diagrams.md).
+
+## Usage Patterns
+
+Typically invoked at the end of reconnaissance → scanning → exploitation → analysis workflows:
+
+```ruby
+PWN::Reports.generate(...)
+```
+
+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]]

data/documentation/SAST.md

@@ -0,0 +1,32 @@
+# SAST (Static Application Security Testing)
+
+`PWN::SAST` provides a growing collection of static analysis signatures and test case generators.
+
+## Location
+
+`lib/pwn/sast/` — one file per vulnerability class or mechanism.
+
+## 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
+
+```ruby
+PWN::SAST.constants
+PWN::SAST::TestCaseEngine.generate(...)
+# Or call specific check modules
+```
+
+SAST results feed directly into reporting and can be orchestrated by the `pwn-ai` agent or custom drivers.
+
+See `lib/pwn/sast/` source for the full and growing list of modules.
+
+[[Diagrams]]

data/documentation/Skills-Memory-Learning.md

@@ -0,0 +1,44 @@
+# Skills, Memory & Learning
+
+One of PWN's most powerful features is its self-improving closed loop.
+
+## Memory (`PWN::Memory`)
+
+Persistent facts, preferences, lessons, and environment data stored in `~/.pwn/memory.json`.
+
+Use from REPL / agent:
+- `PWN::Memory.remember(key, value, category: :fact)`
+- `PWN::Memory.recall(query)`
+
+Injected into every future `pwn-ai` session.
+
+## Skills
+
+Reusable, versionable markdown procedures stored in `~/.pwn/skills/`.
+
+- Created automatically via distillation of successful agent runs.
+- Manually via `skill_create` or editing YAML+markdown files.
+- Contain front-matter `references:` (CWE, CVE, ATT&CK, NIST, URLs).
+- Exposed to the agent and listed via `skill_list` / `skill_view`.
+
+Example skills:
+- `deep_exploitation`
+- `vulnerability_research_fundamentals`
+- `xai_grok_oauth_device_flow`
+
+## Learning Loop
+
+- `PWN::AI::Agent::Metrics` — per-tool success rate + duration (`~/.pwn/metrics.json`)
+- `PWN::AI::Agent::Learning` — outcomes, reflections, skill distillation (`~/.pwn/learning.jsonl`)
+- Successful workflows become durable skills available to all future sessions.
+
+## Management Commands (REPL)
+
+- `pwn-ai-memory`
+- `pwn-ai-sessions`
+- `pwn-ai-cron`
+- `skill_list`, `skill_view`, `skill_create`, `skill_add_reference`
+
+This system turns one-off wins into institutional knowledge.
+
+[[Diagrams]]

data/documentation/Transparent-Browser.md

@@ -0,0 +1,32 @@
+# Transparent Browser
+
+`PWN::Plugins::TransparentBrowser` — powerful browser automation (headless + visible) built on top of Selenium / Watir / Ferrum / similar.
+
+## Primary Uses
+
+- Web spidering / crawling
+- JavaScript-heavy application interaction
+- Automated form submission, auth flows
+- Screenshotting, DOM inspection
+- Proxied browsing (pairs excellently with BurpSuite)
+
+## Example Calls
+
+```ruby
+browser = PWN::Plugins::TransparentBrowser.open_browser(
+  browser_type: :chrome,
+  proxy: 'http://127.0.0.1:8080'   # Burp
+)
+browser.goto 'https://target.example.com'
+# ... interact ...
+browser.close
+```
+
+Agent-friendly.
+
+## See Also
+
+- [Burp Suite](BurpSuite.md)
+- [Plugins](Plugins.md)
+
+[[Diagrams]]

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,34 @@
+# What is PWN
+
+PWN (pronounced /pōn/ or "pone") is a powerful open-source **offensive cybersecurity automation framework** and **continuous security integration platform**.
+
+## Core Purpose
+
+- Rapidly discover zero-days
+- Automate exploitation and post-exploitation
+- Perform advanced web application penetration testing
+- Conduct source code analysis (SAST)
+- Orchestrate infrastructure reconnaissance at scale
+- Execute AI-augmented autonomous security operations
+
+## Architecture Highlights
+
+PWN provides over 60 production-grade plugins, full LLM integration with tool-calling agents, persistent memory, reusable skills, session/cron management, and a highly interactive REPL (Pry-powered) for prototyping and driving complex security workflows.
+
+All core automation primitives are open to promote trust, peer review, and collaborative innovation in adversarial security.
+
+## Key Components
+
+- `PWN::Plugins::*` — 66+ specialized modules
+- `PWN::AI::*` — Multi-LLM clients + autonomous agent
+- `PWN::SAST` — Static analysis & test case generation
+- `PWN::Reports` — Automated reporting
+- `PWN::Memory`, `Sessions`, `Cron`, `Skills`, `Config`
+- `PWN::Driver` — Custom automation packages
+
+See:
+- [How PWN Works](How-PWN-Works.md)
+- [Plugins](Plugins.md)
+- [pwn-ai Agent](pwn-ai-Agent.md)
+
+[[Diagrams]]

data/documentation/Why-PWN.md

@@ -0,0 +1,18 @@
+# Why PWN
+
+In cybersecurity, proprietary black-box tools dominate. Threats evolve daily. An **open framework** for core security primitives, vulnerability research, exploitation techniques, and intelligent automation is essential.
+
+## Key Benefits
+
+- **Transparency & Auditability**: Foundational modules remain open.
+- **Extensibility**: Seamless bridges to commercial tools (Burp Suite Professional [preferred], Metasploit, Nmap, Nessus, ZAP, etc.).
+- **Collaboration**: Accelerates zero-day discovery and reliable exploit development.
+- **Continuous Security**: Integrates into CI/CD pipelines.
+- **Reusable Intelligence**: AI skills, persistent memory, learning loops.
+- **Accessibility**: Advanced red team / vuln research capabilities available to all.
+
+PWN stands on the shoulders of security giants while keeping the core open and auditable.
+
+See [How PWN Works](How-PWN-Works.md) for architecture.
+
+[[Diagrams]]

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

@@ -0,0 +1,134 @@
+<?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 &amp; Tool Calling Pages: 1 -->
+<svg width="878pt" height="235pt"
+ viewBox="0.00 0.00 878.00 235.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(4 230.55)">
+<title>PWN AI Integration &amp; Tool Calling</title>
+<polygon fill="white" stroke="none" points="-4,4 -4,-230.55 874.47,-230.55 874.47,4 -4,4"/>
+<!-- User -->
+<g id="node1" class="node">
+<title>User</title>
+<path fill="none" stroke="black" d="M55,-143.82C55,-143.82 12,-143.82 12,-143.82 6,-143.82 0,-137.82 0,-131.82 0,-131.82 0,-119.82 0,-119.82 0,-113.82 6,-107.82 12,-107.82 12,-107.82 55,-107.82 55,-107.82 61,-107.82 67,-113.82 67,-119.82 67,-119.82 67,-131.82 67,-131.82 67,-137.82 61,-143.82 55,-143.82"/>
+<text xml:space="preserve" text-anchor="middle" x="33.5" y="-122.52" font-family="Arial" font-size="9.00">User Prompt</text>
+</g>
+<!-- Agent -->
+<g id="node2" class="node">
+<title>Agent</title>
+<ellipse fill="none" stroke="black" cx="274.61" cy="-125.82" rx="45.61" ry="18"/>
+<text xml:space="preserve" text-anchor="middle" x="274.61" y="-122.52" font-family="Arial" font-size="9.00">PWN::AI::Agent</text>
+</g>
+<!-- User&#45;&gt;Agent -->
+<g id="edge1" class="edge">
+<title>User&#45;&gt;Agent</title>
+<path fill="none" stroke="black" d="M67.36,-127.31C73.24,-127.52 79.3,-127.71 85,-127.82 140.99,-128.93 155.01,-128.72 211,-127.82 213.07,-127.79 215.18,-127.75 217.31,-127.7"/>
+<polygon fill="black" stroke="black" points="217.39,-131.2 227.3,-127.46 217.22,-124.21 217.39,-131.2"/>
+</g>
+<!-- Agent&#45;&gt;User -->
+<g id="edge11" class="edge">
+<title>Agent&#45;&gt;User</title>
+<path fill="none" stroke="black" d="M239.56,-113.84C230.4,-111.14 220.42,-108.68 211,-107.32 155.58,-99.3 140.14,-97.54 85,-107.32 82.83,-107.71 80.63,-108.18 78.42,-108.72"/>
+<polygon fill="black" stroke="black" points="77.55,-105.33 68.91,-111.46 79.49,-112.05 77.55,-105.33"/>
+<text xml:space="preserve" text-anchor="middle" x="148" y="-110.52" font-family="Times,serif" font-size="14.00">final answer + artifacts</text>
+</g>
+<!-- LLM -->
+<g id="node3" class="node">
+<title>LLM</title>
+<path fill="none" stroke="black" d="M553.72,-183.82C553.72,-183.82 488.97,-183.82 488.97,-183.82 482.97,-183.82 476.97,-177.82 476.97,-171.82 476.97,-171.82 476.97,-159.82 476.97,-159.82 476.97,-153.82 482.97,-147.82 488.97,-147.82 488.97,-147.82 553.72,-147.82 553.72,-147.82 559.72,-147.82 565.72,-153.82 565.72,-159.82 565.72,-159.82 565.72,-171.82 565.72,-171.82 565.72,-177.82 559.72,-183.82 553.72,-183.82"/>
+<text xml:space="preserve" text-anchor="middle" x="521.34" y="-167.77" font-family="Arial" font-size="9.00">LLM (Grok OAuth,</text>
+<text xml:space="preserve" text-anchor="middle" x="521.34" y="-157.27" font-family="Arial" font-size="9.00">OpenAI, etc.)</text>
+</g>
+<!-- Agent&#45;&gt;LLM -->
+<g id="edge2" class="edge">
+<title>Agent&#45;&gt;LLM</title>
+<path fill="none" stroke="black" d="M288.28,-143.25C299.59,-157.19 317.52,-175.71 338.22,-183.82 378.83,-199.74 428.27,-193.41 465.38,-184.11"/>
+<polygon fill="black" stroke="black" points="466.25,-187.5 475.01,-181.54 464.45,-180.74 466.25,-187.5"/>
+<text xml:space="preserve" text-anchor="middle" x="397.84" y="-213.25" font-family="Times,serif" font-size="14.00">build prompt +</text>
+<text xml:space="preserve" text-anchor="middle" x="397.84" y="-196.75" font-family="Times,serif" font-size="14.00">tools schema</text>
+</g>
+<!-- Agent&#45;&gt;LLM -->
+<g id="edge10" class="edge">
+<title>Agent&#45;&gt;LLM</title>
+<path fill="none" stroke="black" d="M311.12,-137.1C319.91,-139.59 329.35,-142.02 338.22,-143.82 380.46,-152.39 428.95,-158.05 465.27,-161.48"/>
+<polygon fill="black" stroke="black" points="464.82,-164.95 475.1,-162.38 465.46,-157.98 464.82,-164.95"/>
+<text xml:space="preserve" text-anchor="middle" x="397.84" y="-163.67" font-family="Times,serif" font-size="14.00">continue conversation</text>
+</g>
+<!-- Tools -->
+<g id="node4" class="node">
+<title>Tools</title>
+<path fill="none" stroke="black" d="M555.22,-90.82C555.22,-90.82 487.47,-90.82 487.47,-90.82 481.47,-90.82 475.47,-84.82 475.47,-78.82 475.47,-78.82 475.47,-52.82 475.47,-52.82 475.47,-46.82 481.47,-40.82 487.47,-40.82 487.47,-40.82 555.22,-40.82 555.22,-40.82 561.22,-40.82 567.22,-46.82 567.22,-52.82 567.22,-52.82 567.22,-78.82 567.22,-78.82 567.22,-84.82 561.22,-90.82 555.22,-90.82"/>
+<text xml:space="preserve" text-anchor="middle" x="521.34" y="-78.27" font-family="Arial" font-size="9.00">Tool Registry</text>
+<text xml:space="preserve" text-anchor="middle" x="521.34" y="-67.77" font-family="Arial" font-size="9.00">(pwn_eval, shell,</text>
+<text xml:space="preserve" text-anchor="middle" x="521.34" y="-57.27" font-family="Arial" font-size="9.00">memory_*, skill_*, </text>
+<text xml:space="preserve" text-anchor="middle" x="521.34" y="-46.77" font-family="Arial" font-size="9.00">learning_*)</text>
+</g>
+<!-- Agent&#45;&gt;Tools -->
+<g id="edge4" class="edge">
+<title>Agent&#45;&gt;Tools</title>
+<path fill="none" stroke="black" d="M302.38,-111.22C313.24,-105.83 326.06,-100.12 338.22,-96.32 379.22,-83.5 427.19,-75.74 463.61,-71.26"/>
+<polygon fill="black" stroke="black" points="463.98,-74.74 473.5,-70.1 463.16,-67.79 463.98,-74.74"/>
+<text xml:space="preserve" text-anchor="middle" x="397.84" y="-99.52" font-family="Times,serif" font-size="14.00">dispatch</text>
+</g>
+<!-- LLM&#45;&gt;Agent -->
+<g id="edge3" class="edge">
+<title>LLM&#45;&gt;Agent</title>
+<path fill="none" stroke="black" d="M497.01,-147.34C485.74,-139.55 471.62,-131.37 457.47,-127.32 415.52,-115.31 365.86,-115.83 329.04,-118.85"/>
+<polygon fill="black" stroke="black" points="329.2,-115.32 319.56,-119.72 329.83,-122.29 329.2,-115.32"/>
+<text xml:space="preserve" text-anchor="middle" x="397.84" y="-130.52" font-family="Times,serif" font-size="14.00">tool_calls[]</text>
+</g>
+<!-- Tools&#45;&gt;Agent -->
+<g id="edge9" class="edge">
+<title>Tools&#45;&gt;Agent</title>
+<path fill="none" stroke="black" d="M475.11,-50.64C436.87,-40.5 381.54,-32.32 338.22,-52.32 317.61,-61.84 301.28,-81.85 290.48,-98.6"/>
+<polygon fill="black" stroke="black" points="287.77,-96.32 285.55,-106.68 293.74,-99.97 287.77,-96.32"/>
+<text xml:space="preserve" text-anchor="middle" x="397.84" y="-55.52" font-family="Times,serif" font-size="14.00">results</text>
+</g>
+<!-- PWNNS -->
+<g id="node5" class="node">
+<title>PWNNS</title>
+<path fill="none" stroke="black" d="M849.47,-119.57C849.47,-119.57 784.72,-119.57 784.72,-119.57 778.72,-119.57 772.72,-113.57 772.72,-107.57 772.72,-107.57 772.72,-92.07 772.72,-92.07 772.72,-86.07 778.72,-80.07 784.72,-80.07 784.72,-80.07 849.47,-80.07 849.47,-80.07 855.47,-80.07 861.47,-86.07 861.47,-92.07 861.47,-92.07 861.47,-107.57 861.47,-107.57 861.47,-113.57 855.47,-119.57 849.47,-119.57"/>
+<text xml:space="preserve" text-anchor="middle" x="817.09" y="-107.02" font-family="Arial" font-size="9.00">PWN Namespace</text>
+<text xml:space="preserve" text-anchor="middle" x="817.09" y="-96.52" font-family="Arial" font-size="9.00">(Plugins, SAST,</text>
+<text xml:space="preserve" text-anchor="middle" x="817.09" y="-86.02" font-family="Arial" font-size="9.00">Reports, etc.)</text>
+</g>
+<!-- Tools&#45;&gt;PWNNS -->
+<g id="edge5" class="edge">
+<title>Tools&#45;&gt;PWNNS</title>
+<path fill="none" stroke="black" d="M543.86,-91.12C554.94,-102.19 569.43,-113.97 585.22,-119.82 642.67,-141.11 713.47,-129.99 761.41,-117.49"/>
+<polygon fill="black" stroke="black" points="762.29,-120.88 771.02,-114.87 760.45,-114.12 762.29,-120.88"/>
+<text xml:space="preserve" text-anchor="middle" x="665.47" y="-135" font-family="Times,serif" font-size="14.00">PWN::Plugins::XXX.method</text>
+</g>
+<!-- External -->
+<g id="node6" class="node">
+<title>External</title>
+<path fill="none" stroke="black" d="M858.47,-49.82C858.47,-49.82 775.72,-49.82 775.72,-49.82 769.72,-49.82 763.72,-43.82 763.72,-37.82 763.72,-37.82 763.72,-25.82 763.72,-25.82 763.72,-19.82 769.72,-13.82 775.72,-13.82 775.72,-13.82 858.47,-13.82 858.47,-13.82 864.47,-13.82 870.47,-19.82 870.47,-25.82 870.47,-25.82 870.47,-37.82 870.47,-37.82 870.47,-43.82 864.47,-49.82 858.47,-49.82"/>
+<text xml:space="preserve" text-anchor="middle" x="817.09" y="-33.77" font-family="Arial" font-size="9.00">External Tools</text>
+<text xml:space="preserve" text-anchor="middle" x="817.09" y="-23.27" font-family="Arial" font-size="9.00">(curl, nmap, msf, burp)</text>
+</g>
+<!-- Tools&#45;&gt;External -->
+<g id="edge6" class="edge">
+<title>Tools&#45;&gt;External</title>
+<path fill="none" stroke="black" d="M567.39,-51.28C573.34,-49.74 579.39,-48.36 585.22,-47.32 641,-37.37 705.4,-33.68 751.98,-32.37"/>
+<polygon fill="black" stroke="black" points="752,-35.87 761.91,-32.12 751.83,-28.87 752,-35.87"/>
+<text xml:space="preserve" text-anchor="middle" x="665.47" y="-50.52" font-family="Times,serif" font-size="14.00">shell commands</text>
+</g>
+<!-- PWNNS&#45;&gt;Tools -->
+<g id="edge7" class="edge">
+<title>PWNNS&#45;&gt;Tools</title>
+<path fill="none" stroke="black" d="M772.39,-88.11C763.61,-86.08 754.41,-84.19 745.72,-82.82 689.35,-73.93 624.21,-69.64 578.88,-67.61"/>
+<polygon fill="black" stroke="black" points="579.16,-64.12 569.02,-67.19 578.87,-71.11 579.16,-64.12"/>
+<text xml:space="preserve" text-anchor="middle" x="665.47" y="-102.52" font-family="Times,serif" font-size="14.00">return value</text>
+<text xml:space="preserve" text-anchor="middle" x="665.47" y="-86.02" font-family="Times,serif" font-size="14.00">or exception</text>
+</g>
+<!-- External&#45;&gt;Tools -->
+<g id="edge8" class="edge">
+<title>External&#45;&gt;Tools</title>
+<path fill="none" stroke="black" d="M763.5,-14.94C715.56,-2.41 643.54,9.14 585.22,-12.32 573.27,-16.72 562.04,-24.5 552.48,-32.79"/>
+<polygon fill="black" stroke="black" points="550.26,-30.08 545.3,-39.44 555.01,-35.22 550.26,-30.08"/>
+<text xml:space="preserve" text-anchor="middle" x="665.47" y="-15.52" font-family="Times,serif" font-size="14.00">stdout/stderr</text>
+</g>
+</g>
+</svg>

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

@@ -0,0 +1,84 @@
+<?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 BurpSuite vs Zaproxy Preference Pages: 1 -->
+<svg width="745pt" height="136pt"
+ viewBox="0.00 0.00 745.00 136.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(4 132.25)">
+<title>PWN BurpSuite vs Zaproxy Preference</title>
+<polygon fill="white" stroke="none" points="-4,4 -4,-132.25 740.75,-132.25 740.75,4 -4,4"/>
+<!-- Decision -->
+<g id="node1" class="node">
+<title>Decision</title>
+<path fill="none" stroke="black" d="M210.56,-86.38C210.56,-86.38 141.69,-64.62 141.69,-64.62 135.97,-62.81 135.97,-59.19 141.69,-57.38 141.69,-57.38 210.56,-35.62 210.56,-35.62 216.28,-33.81 227.72,-33.81 233.44,-35.62 233.44,-35.62 302.31,-57.38 302.31,-57.38 308.03,-59.19 308.03,-62.81 302.31,-64.62 302.31,-64.62 233.44,-86.38 233.44,-86.38 227.72,-88.19 216.28,-88.19 210.56,-86.38"/>
+<text xml:space="preserve" text-anchor="middle" x="222" y="-62.95" font-family="Arial" font-size="9.00">Web Proxy Choice</text>
+<text xml:space="preserve" text-anchor="middle" x="222" y="-52.45" font-family="Arial" font-size="9.00">in PWN</text>
+</g>
+<!-- Burp -->
+<g id="node2" class="node">
+<title>Burp</title>
+<path fill="none" stroke="black" d="M586.25,-128.25C586.25,-128.25 484,-128.25 484,-128.25 478,-128.25 472,-122.25 472,-116.25 472,-116.25 472,-79.75 472,-79.75 472,-73.75 478,-67.75 484,-67.75 484,-67.75 586.25,-67.75 586.25,-67.75 592.25,-67.75 598.25,-73.75 598.25,-79.75 598.25,-79.75 598.25,-116.25 598.25,-116.25 598.25,-122.25 592.25,-128.25 586.25,-128.25"/>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-115.7" font-family="Arial" font-size="9.00">PWN::Plugins::BurpSuite</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-105.2" font-family="Arial" font-size="9.00">(preferred for most cases)</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-94.7" font-family="Arial" font-size="9.00">&#45; Comprehensive scanning</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-84.2" font-family="Arial" font-size="9.00">&#45; Rich ecosystem</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-73.7" font-family="Arial" font-size="9.00">&#45; Active scan + extensions</text>
+</g>
+<!-- Decision&#45;&gt;Burp -->
+<g id="edge2" class="edge">
+<title>Decision&#45;&gt;Burp</title>
+<path fill="none" stroke="black" d="M290.13,-68.98C340.2,-74.94 408.58,-83.07 460.21,-89.21"/>
+<polygon fill="black" stroke="black" points="459.77,-92.68 470.12,-90.39 460.6,-85.73 459.77,-92.68"/>
+<text xml:space="preserve" text-anchor="middle" x="392.88" y="-91.28" font-family="Times,serif" font-size="14.00">default / most features</text>
+</g>
+<!-- Zap -->
+<g id="node3" class="node">
+<title>Zap</title>
+<path fill="none" stroke="black" d="M578,-50C578,-50 492.25,-50 492.25,-50 486.25,-50 480.25,-44 480.25,-38 480.25,-38 480.25,-12 480.25,-12 480.25,-6 486.25,0 492.25,0 492.25,0 578,0 578,0 584,0 590,-6 590,-12 590,-12 590,-38 590,-38 590,-44 584,-50 578,-50"/>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-37.45" font-family="Arial" font-size="9.00">PWN::Plugins::Zaproxy</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-26.95" font-family="Arial" font-size="9.00">(fallback)</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-16.45" font-family="Arial" font-size="9.00">&#45; Open source</text>
+<text xml:space="preserve" text-anchor="middle" x="535.12" y="-5.95" font-family="Arial" font-size="9.00">&#45; REST API scans</text>
+</g>
+<!-- Decision&#45;&gt;Zap -->
+<g id="edge3" class="edge">
+<title>Decision&#45;&gt;Zap</title>
+<path fill="none" stroke="black" d="M275.28,-48.35C293.1,-44.46 313.2,-40.54 331.75,-38 377.15,-31.77 428.69,-28.52 468.4,-26.82"/>
+<polygon fill="black" stroke="black" points="468.43,-30.32 478.29,-26.43 468.15,-23.33 468.43,-30.32"/>
+<text xml:space="preserve" text-anchor="middle" x="392.88" y="-57.7" font-family="Times,serif" font-size="14.00">if Burp unavailable</text>
+<text xml:space="preserve" text-anchor="middle" x="392.88" y="-41.2" font-family="Times,serif" font-size="14.00">or specific REST need</text>
+</g>
+<!-- Scan / Proxy / Exploit -->
+<g id="node5" class="node">
+<title>Scan / Proxy / Exploit</title>
+<path fill="none" stroke="black" d="M724.75,-79C724.75,-79 647.25,-79 647.25,-79 641.25,-79 635.25,-73 635.25,-67 635.25,-67 635.25,-55 635.25,-55 635.25,-49 641.25,-43 647.25,-43 647.25,-43 724.75,-43 724.75,-43 730.75,-43 736.75,-49 736.75,-55 736.75,-55 736.75,-67 736.75,-67 736.75,-73 730.75,-79 724.75,-79"/>
+<text xml:space="preserve" text-anchor="middle" x="686" y="-57.7" font-family="Arial" font-size="9.00">Scan / Proxy / Exploit</text>
+</g>
+<!-- Burp&#45;&gt;Scan / Proxy / Exploit -->
+<g id="edge4" class="edge">
+<title>Burp&#45;&gt;Scan / Proxy / Exploit</title>
+<path fill="none" stroke="black" d="M598.4,-82.52C606.93,-80.4 615.68,-78.23 624.19,-76.11"/>
+<polygon fill="black" stroke="black" points="624.86,-79.55 633.72,-73.75 623.17,-72.76 624.86,-79.55"/>
+</g>
+<!-- Zap&#45;&gt;Scan / Proxy / Exploit -->
+<g id="edge5" class="edge">
+<title>Zap&#45;&gt;Scan / Proxy / Exploit</title>
+<path fill="none" stroke="black" d="M590.29,-38.1C601.27,-40.75 612.88,-43.56 624.07,-46.27"/>
+<polygon fill="black" stroke="black" points="623.06,-49.62 633.61,-48.57 624.71,-42.82 623.06,-49.62"/>
+</g>
+<!-- UserTask -->
+<g id="node4" class="node">
+<title>UserTask</title>
+<path fill="none" stroke="black" d="M81.25,-79C81.25,-79 12,-79 12,-79 6,-79 0,-73 0,-67 0,-67 0,-55 0,-55 0,-49 6,-43 12,-43 12,-43 81.25,-43 81.25,-43 87.25,-43 93.25,-49 93.25,-55 93.25,-55 93.25,-67 93.25,-67 93.25,-73 87.25,-79 81.25,-79"/>
+<text xml:space="preserve" text-anchor="middle" x="46.62" y="-57.7" font-family="Arial" font-size="9.00">Web App Test Task</text>
+</g>
+<!-- UserTask&#45;&gt;Decision -->
+<g id="edge1" class="edge">
+<title>UserTask&#45;&gt;Decision</title>
+<path fill="none" stroke="black" d="M93.63,-61C101.15,-61 109.19,-61 117.45,-61"/>
+<polygon fill="black" stroke="black" points="117.3,-64.5 127.3,-61 117.3,-57.5 117.3,-64.5"/>
+</g>
+</g>
+</svg>