From 9d965e23eff7b4419b97e283075fc76031110a76 Mon Sep 17 00:00:00 2001 From: yotti Date: Sat, 6 Jun 2026 23:25:28 +0900 Subject: [PATCH 1/2] docs: update README and docs for v0.3.0 (UI renewal, features, light/dark mode) --- README.md | 80 ++++++++++++++++- docs/getting-started.md | 66 +++++++------- docs/index.md | 30 ++++--- docs/web-ui.md | 185 +++++++++++++++++----------------------- 4 files changed, 203 insertions(+), 158 deletions(-) diff --git a/README.md b/README.md index 6ed00cd..08988d7 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,88 @@ # pypproxy -MITM HTTP/HTTPS proxy for inspecting and modifying traffic. +MITM HTTP/HTTPS proxy for inspecting, modifying, and testing traffic from browsers and mobile apps. [![CI](https://github.com/ykus4/pypproxy/actions/workflows/ci.yml/badge.svg)](https://github.com/ykus4/pypproxy/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/pypproxy)](https://pypi.org/project/pypproxy/) +[![Python](https://img.shields.io/pypi/pyversions/pypproxy)](https://pypi.org/project/pypproxy/) ```bash pip install pypproxy -pypproxy # GUI mode → http://localhost:8081 -pypproxy --mode cui # terminal UI +pypproxy # GUI mode → http://localhost:8081 +pypproxy --mode cui # Terminal UI ``` See the **[docs](https://ykus4.github.io/pypproxy/)** for setup, CA installation, and feature guides. + +## Features + +| Category | Features | +|----------|---------| +| **Proxy** | HTTP/HTTPS MITM, WebSocket, gRPC, MQTT, HTTP/2 | +| **UI** | Sidebar navigation, dark/light mode, real-time traffic table | +| **Intercept** | Manual request review, edit headers/body, forward or drop | +| **Rules** | Block / modify / redirect by host, path, method, header, body (regex) | +| **Decode** | Auto-detect gzip/brotli, JSON, XML, JWT, Base64, multipart, Protobuf, MessagePack, CBOR | +| **Replay** | One-click replay, parallel fuzzing, Resender tab with full editor | +| **Bulk Sender** | Payload list mode + race condition test | +| **Diff** | Unified diff between any two captured entries | +| **A/B Test** | Send same request to two hosts, compare responses | +| **Macro** | Chain requests with `{{variable}}` substitution and response extraction | +| **GraphQL** | Auto-detect, introspection, schema tree, query editor | +| **OpenAPI** | Auto-generate OpenAPI 3.0 spec from captured traffic | +| **Code Gen** | Export as curl / Python requests / JavaScript fetch / HTTPie | +| **Analytics** | Per-host stats, P95/P99 latency, status distribution | +| **Security** | JWT checker, header checker, token randomness, int overflow, CORS, SSRF, redirect, IDOR | +| **Frida** | SSL pinning bypass scripts, script injection, device management | +| **Sessions** | Group entries into named sessions with persistence | +| **Report** | Export HTML or Markdown report with findings | +| **Import/Export** | HAR, paxy JSON, OpenAPI, rules | +| **Full-text search** | SQLite FTS5 across all captured traffic | +| **Scope** | Capture only in-scope hosts | +| **DNS spoofing** | Built-in DNS server with domain override | +| **Scripts** | Python `on_request` / `on_response` hooks | +| **Plugins** | Drop `.py` files into `~/.pypproxy/plugins/` | + +## Quick start + +```bash +# Install +pip install pypproxy + +# Start (GUI mode) +pypproxy + +# Install CA certificate (macOS) +sudo security add-trusted-cert -d -r trustRoot \ + -k /Library/Keychains/System.keychain ~/.paxy/ca-cert.pem + +# Set system proxy (macOS) +networksetup -setwebproxy Wi-Fi 127.0.0.1 8080 +networksetup -setsecurewebproxy Wi-Fi 127.0.0.1 8080 +``` + +Open **http://localhost:8081** — traffic appears in real time. + +## Optional: Frida integration + +```bash +pip install 'pypproxy[frida]' +``` + +Enables one-click SSL pinning bypass and script injection from the Frida tab. + +## CLI flags + +``` +--mode gui (default) or cui +--port Proxy port (default 8080) +--ui-port Web UI port (default 8081) +--config Path to YAML config file +--script Path to Python script file +--ca-dir CA cert directory (default ~/.paxy) +--no-db Disable SQLite persistence +``` + +## License + +MIT diff --git a/docs/getting-started.md b/docs/getting-started.md index 730fb74..aa5d55c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,10 +3,24 @@ ## Requirements - Python 3.11+ -- [uv](https://docs.astral.sh/uv/) +- [uv](https://docs.astral.sh/uv/) (recommended) or pip ## Installation +### From PyPI + +```bash +pip install pypproxy +``` + +### With Frida support + +```bash +pip install 'pypproxy[frida]' +``` + +### From source + ```bash git clone https://github.com/ykus4/pypproxy cd pypproxy @@ -18,38 +32,30 @@ uv sync ### GUI mode (default) ```bash -uv run python main.py -# or -make gui +pypproxy ``` -Open `http://localhost:8081` in your browser to see the traffic viewer. +Open `http://localhost:8081` in your browser. ### CUI mode ```bash -uv run python main.py --mode cui -# or -make cui +pypproxy --mode cui ``` -A real-time traffic table renders directly in the terminal. - ## Startup output ``` -paxy MITM proxy +pypproxy MITM proxy proxy : 0.0.0.0:8080 UI : http://0.0.0.0:8081 CA : /Users/you/.paxy/ca-cert.pem -Install the CA cert in your browser/device to avoid TLS warnings. + DB : /Users/you/.paxy/pypproxy.db ``` On first run, `~/.paxy/ca-cert.pem` and `~/.paxy/ca-key.pem` are generated automatically. -## Installing the CA certificate - -To intercept HTTPS traffic, install the generated CA certificate as a trusted root on every device you want to inspect. +## Install the CA certificate ### macOS (system-wide) @@ -69,43 +75,33 @@ sudo security add-trusted-cert -d -r trustRoot \ 1. Transfer `ca-cert.pem` to the device 2. **Settings** → **Security** → **Install from storage** -!!! note - Android 7+ apps targeting API 24+ do not trust user-installed CAs by default. - Add a `network_security_config.xml` to the target app, or use a rooted device. - ### iOS -1. Send the certificate to the device via email or HTTP -2. Open the attachment — iOS prompts to install a profile -3. **Settings** → **General** → **VPN & Device Management** → install the profile +1. Send the certificate via email or AirDrop +2. Open it — iOS prompts to install a profile +3. **Settings** → **General** → **VPN & Device Management** → install 4. **Settings** → **General** → **About** → **Certificate Trust Settings** → enable full trust -## Configuring the proxy +## Configure the proxy -### macOS (system proxy) +### macOS ```bash networksetup -setwebproxy Wi-Fi 127.0.0.1 8080 networksetup -setsecurewebproxy Wi-Fi 127.0.0.1 8080 -``` -To disable: - -```bash +# To disable: networksetup -setwebproxystate Wi-Fi off networksetup -setsecurewebproxystate Wi-Fi off ``` -### Android +### Android / iOS -**Settings** → **Wi-Fi** → long-press your network → **Modify** → **Advanced** → **Proxy: Manual** +**Settings** → **Wi-Fi** → your network → **Proxy: Manual** - Host: your machine's IP (e.g. `192.168.1.10`) - Port: `8080` -### iOS - -**Settings** → **Wi-Fi** → tap the info icon → **Configure Proxy: Manual** +## Open the UI -- Server: your machine's IP -- Port: `8080` +Navigate to `http://localhost:8081`. Switch between **dark and light mode** using the ☀ button in the toolbar. diff --git a/docs/index.md b/docs/index.md index faca8a5..4365440 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ layout: home hero: name: pypproxy text: MITM Proxy - tagline: Intercept, inspect, and modify HTTP/HTTPS traffic from browsers and mobile apps. Written in Python. + tagline: Intercept, inspect, modify, and test HTTP/HTTPS traffic from browsers and mobile apps. Written in Python. actions: - theme: brand text: Get Started @@ -16,20 +16,26 @@ hero: features: - icon: 🔐 title: HTTPS Interception - details: Dynamically generate per-host certificates signed by a local CA. Terminate TLS and read every request and response in plain text. + details: Dynamically generate per-host certificates. Decrypt and read every request and response including HTTPS. - icon: 🖥️ - title: GUI Mode - details: Browser-based UI built with NiceGUI. Traffic streams in real time. Filter, inspect, and replay without leaving the page. - - icon: ⌨️ - title: CUI Mode - details: Terminal UI built with rich. Works over SSH and in CI environments with no browser required. + title: Modern UI + details: Sidebar navigation with dark/light mode toggle. Real-time traffic list, filter expressions, multi-format body decode. - icon: ⚙️ title: Rule Engine - details: Block, modify, or redirect traffic by matching host, path, method, header, or body. Full regex support. - - icon: 📝 - title: Python Scripting - details: Define on_request / on_response hooks in plain Python. No DSL to learn — the full standard library is available. + details: Block, modify, or redirect traffic by host, path, method, header, or body. Full regex support. - icon: 🔄 title: Replay & Fuzzing - details: Resend any captured request with one click. Increase count to fire hundreds of parallel requests for load testing or fuzzing. + details: One-click replay. Resender with full editor. Bulk Sender for parallel payloads. Macro runner for chained requests. + - icon: 🔬 + title: Security Testing + details: JWT checker, CORS/SSRF/redirect/IDOR checks, active scan (XSS/SQLi/CMDi), security header audit. + - icon: 📱 + title: Frida Integration + details: SSL pinning bypass scripts for iOS and Android. One-click script injection with real-time console output. + - icon: 📊 + title: Analytics & Reports + details: Per-host stats, P95/P99 latency. Export HTML/Markdown reports. OpenAPI spec auto-generation. + - icon: 🔌 + title: Protocol Support + details: HTTP/2, WebSocket, gRPC, MQTT, GraphQL — all intercepted and decoded. Protobuf/MessagePack/CBOR support. --- diff --git a/docs/web-ui.md b/docs/web-ui.md index b479c3f..f2cd12d 100644 --- a/docs/web-ui.md +++ b/docs/web-ui.md @@ -3,155 +3,124 @@ ## GUI Mode Start pypproxy in GUI mode (the default) and open `http://localhost:8081`. -The UI is built with [NiceGUI](https://nicegui.io/) and runs in the same Python process as the proxy. + +```bash +pypproxy # or +pypproxy --mode gui +``` ## Layout ``` -┌──────────────────────────────────────────────────────────────┐ -│ toolbar: pypproxy ● | Filter expression | Intercept | Clear | ⚙ │ -├─────────────────────────────────────────────────────────────-┤ -│ Traffic | Resender | Bulk Sender | Diff │ -├──────────────────────────┬───────────────────────────────────┤ -│ Traffic list │ Detail panel │ -│ (left 60%) │ (right 40%) │ -│ click row to select │ Request / Response │ -│ right-click for menu │ Body view selector │ -│ │ Replay button │ -└──────────────────────────┴───────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────┐ +│ sidebar (220px) │ toolbar: filter | Intercept | Clear | ⚙ ☀ │ +│ ├──────────────────────────────────────────────┤ +│ Traffic │ │ +│ ─── Tools ─── │ Traffic list (left) │ Detail panel │ +│ Resender │ click row to select │ Request / Response │ +│ Bulk Sender │ right-click for menu │ Body view selector │ +│ Macro │ │ Replay button │ +│ Diff │ │ +│ A/B Test │ │ +│ ─── Security ─── │ │ +│ Security │ │ +│ Adv Security │ │ +│ Scan │ │ +│ ─── Analysis ─── │ │ +│ GraphQL │ │ +│ Analytics │ │ +│ OpenAPI │ │ +│ ─── Dev ─── │ │ +│ Code Gen │ │ +│ Frida │ │ +│ Sessions │ │ +│ Report │ │ +│ ─── Data ─── │ │ +│ Import/Search │ │ +│ Settings (⚙) │ │ +└───────────────────┴──────────────────────────────────────────────┘ ``` -## Tabs +## Sidebar navigation + +Click any item in the sidebar to switch pages. The active item is highlighted with a blue left border. + +## Light / Dark mode + +Click the **☀ / 🌙 button** in the toolbar to toggle between light and dark mode. The preference is saved to `localStorage` and restored on next visit. -### Traffic +## Traffic list -The main traffic list. New requests are prepended in real time. +New requests appear in real time at the top. | Column | Description | |--------|-------------| -| ID | Sequential capture number | -| Method | HTTP method (color badge) | +| # | Sequential capture ID | +| Method | HTTP method (color pill) | | Host | Hostname | -| Path | Path including query string | -| Status | HTTP status (color badge) | +| Path | Path + query string | +| Status | HTTP status (color pill) | | Size | Response body size | -| ms | Response time in milliseconds | -| Proto | `http`, `https`, `ws`, `grpc` | - -**Row colors** — right-click any row to assign a color for visual grouping. +| ms | Response time | **Right-click menu:** -- Send to Resender -- Send to Bulk Sender -- Set as Diff left / Diff with left -- Set color - -### Resender - -Edit and re-send any request. Click **+ New** or right-click a traffic row → **Send to Resender**. - -- Method + URL bar -- Headers editor (raw text, one `Key: Value` per line) -- Body editor -- Response panel (status, headers, body) -- HTTP/2 supported automatically - -### Bulk Sender -Send many variants of one request concurrently. - -**Payload list mode:** Enter one payload per line (JSON or plain text). Each line becomes a separate request body. - -**Race condition mode:** Send the same request N times simultaneously to test for race conditions. - -Results table shows status code, response time, and errors per request. - -### Diff - -Compare two captured entries side by side. - -1. Right-click entry A → **Set as Diff left** -2. Right-click entry B → **Diff with left** -3. Switch to the Diff tab — unified diff is shown for Request, Response, and Headers. +| Action | Description | +|--------|-------------| +| Send to Resender | Open in editor | +| Send to Bulk Sender | Parallel payload testing | +| Add to Macro | Append to macro chain | +| A/B Test | Compare against another host | +| Generate Code | curl / requests / fetch / HTTPie | +| Security Check | JWT, header, randomness checks | +| Adv Security | CORS, SSRF, redirect, rate limit | +| Active Scan | XSS/SQLi/SSRF/CMDi auto-scan | +| Frida Hook | Generate and inject Frida script | +| Add to Session | Assign to active session | +| Set Diff left / Diff with left | Compare two entries | +| Set color | Highlight row | ## Filter expression -The filter bar accepts a structured expression: - -``` -field op value -field op value && field op value -field op value || field op value -``` - -**Fields:** `host`, `path`, `method`, `status`, `protocol`, `request`, `response`, `full_text` - -**Operators:** `==` (exact), `!=` (not equal), `contains` (substring), `~` (regex) - -**Examples:** ``` host == api.example.com method == POST && path contains /login status ~ ^[45] -full_text contains token +full_text contains Authorization ``` -## Body view selector +**Fields:** `host`, `path`, `method`, `status`, `protocol`, `request`, `response`, `full_text` +**Operators:** `==`, `!=`, `contains`, `~` (regex) +**Logic:** `&&`, `||` -The detail panel's body section has a view mode dropdown: +## Body view selector | Mode | Description | |------|-------------| -| Auto | Detect from Content-Type (default) | -| Text | Raw UTF-8 text | -| JSON | Pretty-printed JSON | -| Hex | Hex dump with ASCII column | -| Protobuf | Wire-type heuristic decode (no schema needed) | +| Auto | Detect from Content-Type | +| Text | Raw UTF-8 | +| JSON | Pretty-print | +| XML/HTML | minidom pretty-print | +| Hex | Hexdump with ASCII | +| URL-encoded | `key = value` per line | +| Multipart | Part-by-part display | +| Base64 | Decode standard or URL-safe | +| JWT | Header + payload as JSON | +| Protobuf | Wire-type heuristic decode | | MessagePack | Decoded to JSON | | CBOR | Decoded to JSON | ## Intercept toggle -Enable the **Intercept** toggle in the toolbar to pause every request for manual review. - -A dialog appears with the request headers and body. You can edit them before forwarding, or drop the request entirely. - -## Settings page - -Click ⚙ in the toolbar to open the settings page (`/settings`). - -### Rules - -Add, enable/disable, and delete intercept rules from the UI. - -### SSL Passthrough - -Add hosts that should be tunneled without TLS interception (for certificate-pinned apps). - -### DNS Overwrite - -Configure the built-in DNS server to redirect specific domains to a target IP. -Start the DNS server and point devices to this machine's IP for DNS. - -### Listen Ports - -Change the proxy and UI port (takes effect on restart). - -### Client Certificates - -Import client certificates for mutual TLS. Certificates are matched to hosts by glob pattern. +Enable the **Intercept** switch in the toolbar to pause every request for manual review. ## CUI Mode ```bash -uv run python main.py --mode cui +pypproxy --mode cui ``` -A rich-rendered table updates in real time inside the terminal. - | Key | Action | |-----|--------| | `q` / `Ctrl+C` | Quit | | `c` | Clear traffic | - -The REST API remains available at `:8081` in CUI mode. From ea15c733bc0df4bc8c4575b45048d7e68c00a6b4 Mon Sep 17 00:00:00 2001 From: yotti Date: Sat, 6 Jun 2026 23:30:57 +0900 Subject: [PATCH 2/2] docs: replace remaining 'paxy' with 'pypproxy' in docs titles and text --- docs/configuration.md | 2 +- docs/protocols.md | 6 +++--- mkdocs.yml | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5374f48..24af93a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration -paxy can be configured via CLI flags or a YAML file. CLI flags take precedence over the config file. +pypproxy can be configured via CLI flags or a YAML file. CLI flags take precedence over the config file. ## YAML config file diff --git a/docs/protocols.md b/docs/protocols.md index b11b956..6c8027d 100644 --- a/docs/protocols.md +++ b/docs/protocols.md @@ -2,7 +2,7 @@ ## GraphQL -paxy automatically detects GraphQL requests and provides dedicated tooling. +pypproxy automatically detects GraphQL requests and provides dedicated tooling. ### Detection @@ -41,7 +41,7 @@ Shows the operation type (query/mutation/subscription), operation name, and top- | `DELETE /api/graphql/schema/{host}` | Remove cached schema | | `POST /api/graphql/replay` | Re-send with modified query/variables | -### Modifier utilities (`paxy.graphql.modifier`) +### Modifier utilities (pypproxy.graphql.modifier) ```python from pypproxy.graphql.modifier import set_variable, build_query, build_mutation @@ -78,7 +78,7 @@ Enable `WSInterceptManager` to pause individual frames for manual review, simila ## gRPC gRPC uses HTTP/2 over TLS with a 5-byte length-prefix framing. -paxy detects it via the `Content-Type: application/grpc` header. +pypproxy detects it via the `Content-Type: application/grpc` header. The body view selector in the detail panel offers **Protobuf** mode for wire-type heuristic decoding (no schema needed). diff --git a/mkdocs.yml b/mkdocs.yml index 9730e52..150d89b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ -site_name: paxy -site_description: MITM HTTP/HTTPS proxy for inspecting and modifying traffic +site_name: pypproxy +site_description: MITM HTTP/HTTPS proxy for inspecting, modifying, and testing traffic site_url: https://ykus4.github.io/pypproxy/ repo_url: https://github.com/ykus4/pypproxy repo_name: ykus4/pypproxy