ericmtzmtz/pwnproxyAn open, local-first security testing platform for pentesters, AI agents, CI/CD pipelines, and teams.
One security testing engine. Every interface.
An open, local-first security testing platform for pentesters, AI agents, CI/CD pipelines, and teams.
Traditional security tools were designed around a single tester using a desktop interface.
pwnproxy is built around a shared security testing engine that can be controlled through a terminal, TUI, REST API, WebSocket streams, CI/CD pipelines, or AI agents through MCP.
┌─────────────────────┐
│ pwnproxy core │
│ │
│ Proxy · Scanners │
│ Repeater · Intruder │
│ Sessions · Plugins │
└──────────┬──────────┘
│
┌───────────┬───────────┼───────────┬───────────┐
▼ ▼ ▼ ▼ ▼
CLI TUI REST API WebSocket MCP
│ │ │ │ │
Pentesters Pentesters Automation Teams AI Agents
The same core is used whether you are manually intercepting traffic, running an automated scan, integrating security checks into CI/CD, or giving an AI agent access to your testing workflow.
The proxy, scanners, storage, and automation run on your infrastructure.
No cloud dependency is required for the core testing workflow.
The CLI, TUI, REST API, WebSocket streams, and MCP server are interfaces to the same underlying system.
You do not need separate tools for manual testing and automation.
Run scans directly from the command line, consume JSON or SARIF output, and integrate findings into CI/CD pipelines.
pwnproxy exposes its capabilities through a native MCP server so compatible AI agents can interact with the same testing engine used by human operators.
Scanners and hooks use a plugin architecture designed for built-in and third-party extensions.
git clone https://github.com/ericmtzmtz/pwnproxy.git
cd pwnproxy
poetry install
Python 3.12 or later is required.
poetry run pwnproxy start --proxy-port 8080 --api-port 8000
This starts:
127.0.0.1:8080127.0.0.1:8000http://127.0.0.1:8000/docscurl -x http://127.0.0.1:8080 http://httpbin.org/get
poetry run pwnproxy history
poetry run pwnproxy scan url https://example.com \
--scanners sqli,xss \
--output sarif \
--output-file report.sarif
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Scan completed, no findings |
| 1 | Scan completed, findings found |
| 2 | Error |
pwnproxy is currently installed from source using Poetry (0.1.0 pre-release; 0.2.0-dev in CHANGELOG.md). PyPI packaging is planned for a future release.
Configuration lives in ~/.pwnproxy/config.toml — see config.example.toml for [triage] / [llm] / max_llm_per_scan and scope settings. Core testing (proxy, scanners, storage) works without an LLM API key; triage runs on heuristics by default.
Pause, inspect, modify, and resume HTTP/HTTPS traffic.
Built-in scanners currently include:
| Scanner | Detection |
|---|---|
| SQLi | Error-based (signatures + muted 5xx with negative controls / anti-WAF guards), boolean-blind (multi-round + baseline), time-based, OOB |
| XSS | Reflected/stored with context-aware exploitability (reflection ≠ XSS); static DOM sink signals (dom-xss, inferred) |
| LFI | Content signatures, traversal, and PHP wrappers |
| XXE | Error-based, XInclude, JSON mutation, and OOB workflows |
| SSRF | OOB/callback confirmation only (fail-closed; no speculative error-based SSRF) |
Findings use three confidence levels — tentative, inferred, and confirmed — so weak signals are not treated as exploits. LLM triage is opt-in; by default the pipeline stays on heuristics and never sends tentative findings to the LLM judge.
Scanners consume captured flows and can also be executed directly in headless mode.
Replay and modify raw HTTP requests independently from the proxy.
Findings preserve request data so detected issues can be manually validated.
Request fuzzing using Burp-style §marker§ positions.
Supported modes include:
Wordlist-based path and file discovery with:
Automatically extract and store:
Sessions are isolated and persisted locally.
Extend pwnproxy with custom scanners and hooks.
Plugins can be:
The same plugin interface is used for built-in and third-party scanners.
A watchdog tracks plugin failures and can automatically disable repeatedly failing plugins.
Run pwnproxy directly from the terminal.
pwnproxy start
pwnproxy history
pwnproxy findings
pwnproxy scan url https://example.com
pwnproxy plugin list
pwnproxy session list
Use an interactive terminal interface for:
Control the platform programmatically.
curl http://127.0.0.1:8000/api/v1/flows
The API exposes functionality for:
Interactive API documentation is available at:
http://127.0.0.1:8000/docs
Consume real-time events for traffic, findings, crawler activity, and other workflows.
Example streams:
/ws/traffic/ws/findings/ws/eventsThis allows external interfaces and automation systems to react to testing activity in real time.
pwnproxy includes a native MCP server that exposes the testing platform to MCP-compatible agents.
Claude / Copilot / Custom Agent
│
▼
┌──────────────┐
│ MCP Server │
└──────┬───────┘
│
▼
┌──────────────┐
│ pwnproxy API │
└──────┬───────┘
│
┌─────────┼─────────┐
▼ ▼ ▼
Traffic Findings Scanners
│ │ │
└─────────┼─────────┘
▼
Security workflow
Start pwnproxy:
pwnproxy start
Then configure your MCP-compatible agent:
{
"mcpServers": {
"pwnproxy": {
"command": "python",
"args": [
"-m",
"apps.mcp.src.pwnproxy_mcp.server"
]
}
}
}
The MCP server acts as a thin integration layer over the pwnproxy platform.
See:
docs/mcp.md
for agent-specific configuration and tool documentation.
pwnproxy
┌───────────────┐
│ Proxy Layer │
│ mitmproxy │
└───────┬───────┘
│
▼
┌─────────────────┐
│ HookBus │
│ async events │
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
Scanners Sessions Plugins
│ │ │
└──────────────────┼──────────────────┘
│
▼
┌─────────────────┐
│ Storage Layer │
│ SQLite / async │
└────────┬────────┘
│
▼
┌──────────────────────────────────────┐
│ Control Plane │
│ │
│ FastAPI · REST · WebSocket · Events │
└──────────────────┬───────────────────┘
│
┌──────────┬────────┼────────┬──────────┐
▼ ▼ ▼ ▼ ▼
CLI TUI REST WS MCP
pwnproxy is designed so that the core testing workflow is independent from the interface used to control it.
pwnproxy is not a Burp Suite clone.
Burp Suite remains an excellent tool for GUI-based manual testing.
pwnproxy focuses on a different architecture:
| Burp Suite | pwnproxy | |
|---|---|---|
| Primary model | Desktop application | Shared testing engine |
| Manual testing | GUI | TUI + API interfaces |
| Automation | Extensions / integrations | CLI + REST + SARIF |
| AI agents | External integrations | Native MCP server |
| Plugins | Java ecosystem | Python-based plugins |
| Headless workflows | Limited | Native |
| CI/CD | External tooling | Built-in output and exit codes |
| Local deployment | Yes | Yes |
pwnproxy can also import Burp scope configurations.
pwnproxy import burp --config burp-config.json
See:
docs/burp-migration.md
for migration details.
Run scans without starting the proxy:
pwnproxy scan url https://example.com \
--output sarif \
--output-file report.sarif
Example GitHub Actions workflow:
- name: Install pwnproxy
run: |
git clone https://github.com/ericmtzmtz/pwnproxy.git
cd pwnproxy
pip install poetry
poetry install
- name: Security scan
run: |
cd pwnproxy
poetry run pwnproxy scan url ${{ matrix.url }} \
--output sarif \
--output-file report.sarif
continue-on-error: true
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: pwnproxy/report.sarif
pwnproxy uses local SQLite storage per session.
A session can contain:
~/.pwnproxy/sessions/<session>/
├── traffic.db
├── scanner_results.db
├── sessions.db
└── tasks.db
This keeps testing data isolated and portable.
A complete session can be backed up or moved as a directory.
For larger collaborative or infrastructure deployments, the storage layer is designed around SQLAlchemy async abstractions.
Linux / macOS:
./dev.sh
Windows PowerShell:
.\dev.ps1
This starts:
:8080:8000:4321poetry run pytest
Maturity signals: 17 golden E2E workflows (tests/golden), versioned perf baseline (tests/perf/baseline.json, 281.9ms / 19 pages), and correlation_id observability.
See the contribution documentation for architecture and development details.
correlation_id) and extended LLM usage telemetry281.9ms / 19 pages, tests/perf/baseline.json)| Topic | Documentation |
|---|---|
| Installation | docs/installation.md |
| CLI | docs/cli.md |
| API | docs/api.md |
| MCP | docs/mcp.md |
| Architecture | docs/architecture.md |
| Plugins | docs/plugin-architecture.md |
| Scanners | docs/scanners.md |
| Directory Discovery | docs/directory-bruteforce.md |
| Burp Migration | docs/burp-migration.md |
| Flow Comments | docs/comments-on-flows.md |
| Development | docs/development.md |
[!WARNING] Security disclaimer — dependency advisories. pwnproxy's proxy engine is built on
mitmproxy, which pins several transitive dependencies to exact upper bounds. Some Dependabot advisories therefore cannot be fixed from this repository and stay open until upstreammitmproxywidens those constraints. They are documented below and re-evaluated on everymitmproxyupgrade. Everything else is kept on the latest patched release.
mitmproxy 12.2.x)These are transitive runtime dependencies whose installable version is capped by mitmproxy:
| Package | Advisories | Allowed by mitmproxy | Fixed in |
|---|---|---|---|
tornado | 7 — DoS, credential leak, gzip bomb, OOB read | >=6.5.0,<=6.5.5 | 6.5.8 |
h2 | 1 — duplicate Host request smuggling | =4.3.0 | 4.4.1 |
cryptography | 1 — PKCS#7 Bleichenbacher oracle | >=42.0,<=48.1 | 50.0.0 |
msgpack | 1 — OOB read on Unpacker reuse | >=1.0.0,<=1.1.2 | 1.2.1 |
Impact & mitigation: these paths handle HTTP controlled by the target being tested. As with any interception proxy, only run pwnproxy against systems you are authorized to test, keep it bound to loopback by default, and treat captured traffic as untrusted. Tracking: GitHub Dependabot alerts, reviewed on every mitmproxy release.
apps/web): astro remote code execution (critical), sharp, svgo (×2), js-yaml, smol-toml.weasyprint SSRF (both variants) in the optional reports-pdf extra, now ^70.weasyprint CSS injection (GHSA-jhhc-3hcp-qhm5) has no upstream patch yet. The reports-pdf extra is optional and not installed by default, so it does not affect the core install.npm audit --prefix apps/web
poetry run pip-audit # if pip-audit is installed
To report a security issue, contact [email protected].
Contributions are welcome.
git clone https://github.com/ericmtzmtz/pwnproxy.git
cd pwnproxy
poetry install
poetry run pytest
Before submitting a pull request:
Detailed architecture changes and specifications are tracked in:
openspec/openspec/changes/pwnproxy is maintained by NEXTECH SOLUTIONS — a cybersecurity services company based in Mexico.
The core platform is free and open source under the AGPLv3 license.
Professional services may include:
| Service | Description |
|---|---|
| Security assessments | Professional pentesting engagements and reporting |
| Custom development | Custom scanners, plugins, and integrations |
| Training | Hands-on security and DevSecOps training |
| Automation | Security testing workflows integrated into CI/CD |
For inquiries:
pwnproxy is licensed under the GNU Affero General Public License v3.0.
See:
LICENSE
You are free to use, modify, and distribute pwnproxy under the terms of the AGPLv3.
Built for security testing beyond the desktop.