pypproxy 0.1.0__tar.gz

pypproxy-0.1.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies

pypproxy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main, feat/**]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: latest
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: uv run ruff check pypproxy/
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check pypproxy/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: latest
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short

pypproxy-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

pypproxy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write  # for trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: latest
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build distribution
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/paxy/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pypproxy-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Go
+bin/
+*.exe
+*.test
+*.out
+vendor/
+
+# Node
+web/node_modules/
+web/dist/
+
+# paxy runtime
+.paxy/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+site/
+__pycache__/

pypproxy-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

pypproxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypproxy-0.1.0/Makefile

@@ -0,0 +1,37 @@
+.PHONY: install run dev web-install web-build web-dev test lint clean docs-dev docs-build
+
+install:
+	uv sync
+
+run:
+	uv run python main.py
+
+gui:
+	uv run python main.py --mode gui
+
+cui:
+	uv run python main.py --mode cui
+
+web-install:
+	cd web && npm install
+
+web-build:
+	cd web && npm run build
+
+web-dev:
+	cd web && npm run dev
+
+test:
+	uv run pytest tests/ -v
+
+lint:
+	uv run ruff check paxy/
+
+clean:
+	rm -rf __pycache__ paxy/**/__pycache__ .pytest_cache site/ web/dist/
+
+docs-dev:
+	mkdocs serve
+
+docs-build:
+	mkdocs build

pypproxy-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: pypproxy
+Version: 0.1.0
+Summary: MITM HTTP/HTTPS proxy for inspecting and modifying traffic
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: brotli>=1.1.0
+Requires-Dist: cbor2>=5.6.0
+Requires-Dist: cryptography>=48.0.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: httpx[http2]>=0.27.0
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: nicegui>=3.12.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: websockets>=16.0

pypproxy-0.1.0/README.md

@@ -0,0 +1,14 @@
+# pypproxy
+
+MITM HTTP/HTTPS proxy for inspecting and modifying traffic.
+
+[![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/)
+
+```bash
+pip install pypproxy
+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.

pypproxy-0.1.0/docs/api.md

@@ -0,0 +1,152 @@
+# API Reference
+
+The API server runs on `http://localhost:8081` by default.
+
+## Traffic
+
+### `GET /api/traffic`
+
+List captured entries.
+
+**Query parameters:** `offset`, `limit`, `method`, `host`, `search`, `protocol`
+
+### `GET /api/traffic/{id}`
+
+Get a single entry by ID.
+
+---
+
+## Rules
+
+### `GET /api/rules` · `POST /api/rules` · `PUT /api/rules/{id}` · `DELETE /api/rules/{id}`
+
+CRUD for intercept rules.
+
+---
+
+## Replay
+
+### `POST /api/replay`
+
+```json
+{"entry_id": 42, "options": {"override_host": "staging.example.com", "count": 1}}
+```
+
+---
+
+## Bulk Sender
+
+### `POST /api/bulk`
+
+```json
+{"entry_id": 42, "mode": "payloads", "payloads": [{"label": "p1", "body": "..."}], "concurrency": 10}
+```
+
+`mode`: `"payloads"` or `"race"`
+
+---
+
+## Active Scan
+
+### `POST /api/scan`
+
+```json
+{"entry_id": 42, "categories": ["xss", "sqli", "cmdi", "ssti", "path_traversal"], "concurrency": 5}
+```
+
+---
+
+## Export / Import
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/export/json` | Export all entries + rules as JSON |
+| `GET /api/export/har` | Export all entries as HAR 1.2 |
+| `POST /api/import/har` | Import entries from HAR body |
+| `POST /api/import/json` | Import entries from paxy JSON body |
+| `POST /api/import/rules` | Import rules from JSON body |
+
+---
+
+## Full-text Search
+
+### `GET /api/search?q=keyword&limit=50`
+
+Search across host, path, request body, response body, and headers using SQLite FTS5.
+
+---
+
+## Scope
+
+### `GET /api/scope`
+
+Returns `{"enabled": bool, "rules": [...]}`.
+
+### `POST /api/scope`
+
+```json
+{"enabled": true, "add": {"pattern": "*.example.com", "mode": "glob"}}
+{"remove": "*.example.com"}
+```
+
+---
+
+## GraphQL
+
+### `POST /api/graphql/introspect`
+
+```json
+{"url": "https://api.example.com/graphql", "headers": {"Authorization": "Bearer token"}}
+```
+
+### `GET /api/graphql/schemas`
+
+List cached schemas: `[{"host": "api.example.com", "query_type": "Query", ...}]`
+
+### `GET /api/graphql/schema/{host}`
+
+Full schema object for a host.
+
+### `DELETE /api/graphql/schema/{host}`
+
+Remove cached schema. Returns `204`.
+
+### `POST /api/graphql/replay`
+
+```json
+{"entry_id": 42, "query": "query { user { id } }", "variables": {"id": "123"}}
+```
+
+---
+
+## Misc
+
+### `POST /api/clear`
+
+Delete all captured entries. Returns `204`.
+
+---
+
+## WebSocket
+
+### `GET /ws`
+
+Upgrade to WebSocket. Pushes `Entry` JSON objects in real time.
+
+---
+
+## Schemas
+
+### Entry
+
+```python
+{
+  "id": int, "created_at": str,
+  "method": str, "scheme": str, "host": str, "path": str, "query": str,
+  "req_headers": dict, "req_body": str,          # base64
+  "status_code": int, "resp_headers": dict, "resp_body": str,  # base64
+  "duration_ms": int, "protocol": str,
+  "tags": list[str], "modified": bool, "color": str,
+  "graphql_operation": str, "graphql_op_type": str
+}
+```

pypproxy-0.1.0/docs/architecture.md

@@ -0,0 +1,109 @@
+# Architecture
+
+## Overview
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Client (browser / mobile app)                               │
+└────────────────────────┬─────────────────────────────────────┘
+                         │ HTTP / CONNECT
+┌────────────────────────▼─────────────────────────────────────┐
+│  paxy/proxy/proxy.py  (port :8080)                           │
+│  asyncio TCP server                                          │
+│  ├─ HTTP  → intercept → forward upstream (httpx, HTTP/2)     │
+│  ├─ CONNECT → TLS termination (MITM)                         │
+│  │    ├─ HTTP/HTTPS → intercept → forward upstream           │
+│  │    ├─ WebSocket  → paxy/proto/ws.py                       │
+│  │    ├─ gRPC       → paxy/proto/grpc.py                     │
+│  │    └─ MQTT       → paxy/proto/mqtt.py                     │
+│  └─ ignored hosts → raw TCP tunnel (passthrough)             │
+└─────────────┬────────────────────────┬───────────────────────┘
+              │                        │
+┌─────────────▼──────┐    ┌────────────▼──────────────────────┐
+│  paxy/cert/ca.py   │    │  paxy/interceptor/                 │
+│  CA + per-host TLS │    │  apply rules, record entries       │
+│  SSL Context cache │    └────────────┬───────────────────────┘
+│                    │                 │
+│  paxy/cert/        │    ┌────────────▼───────────────────────┐
+│  client_cert.py    │    │  paxy/store/store.py               │
+│  Mutual TLS certs  │    │  in-memory store + SQLite persist  │
+└────────────────────┘    │  asyncio pub/sub                   │
+                          └────────────┬───────────────────────┘
+                                       │
+          ┌────────────────────────────┼──────────────────────┐
+          │                            │                      │
+┌─────────▼──────────┐   ┌─────────────▼─────────┐  ┌────────▼──────────┐
+│  paxy/api/         │   │  paxy/ui/app.py        │  │  paxy/ui/cui.py   │
+│  FastAPI REST API  │   │  NiceGUI 4-tab UI      │  │  rich terminal UI │
+│  + WebSocket /ws   │   │  Traffic/Resender/     │  │  (CUI mode)       │
+│  Bulk/Export APIs  │   │  Bulk/Diff             │  └───────────────────┘
+└────────────────────┘   └─────────────────────────┘
+```
+
+## Package overview
+
+| Package | Responsibility |
+|---------|----------------|
+| `paxy/proxy` | asyncio TCP server; HTTP forwarding; TLS MITM for CONNECT; raw tunnel for ignored hosts |
+| `paxy/cert/ca` | CA certificate generation; per-host SSL Context cache |
+| `paxy/cert/client_cert` | Client certificate management for mutual TLS |
+| `paxy/interceptor` | Apply rules to requests and responses; record entries in the store |
+| `paxy/intercept` | Manual intercept manager; pause requests for user review |
+| `paxy/rule` | Rule evaluation engine; condition matching; priority ordering |
+| `paxy/store/store` | Thread-safe in-memory traffic store; asyncio pub/sub |
+| `paxy/store/db` | SQLite persistence via aiosqlite; load/save entries |
+| `paxy/store/filter_parser` | Filter expression parser (`host == x && method == POST`) |
+| `paxy/api` | FastAPI REST endpoints, WebSocket streaming, bulk/export APIs |
+| `paxy/ui/app` | NiceGUI 4-tab browser UI (Traffic, Resender, Bulk Sender, Diff) |
+| `paxy/ui/settings` | Settings page (rules, SSL passthrough, DNS, ports, client certs) |
+| `paxy/ui/detail` | Request/response detail panel with body view selector |
+| `paxy/ui/resender` | Resender tab — edit and re-send requests |
+| `paxy/ui/bulk_sender_ui` | Bulk Sender tab — parallel payload sending and race testing |
+| `paxy/ui/diff_view` | Diff tab — unified diff between two captured entries |
+| `paxy/ui/intercept_dialog` | Intercept dialog — pause, edit, forward or drop requests |
+| `paxy/ui/cui` | rich terminal UI (CUI mode) |
+| `paxy/proto/ws` | WebSocket frame relay and logging |
+| `paxy/proto/grpc` | gRPC length-prefix frame decoding |
+| `paxy/proto/mqtt` | MQTT frame decoding and detection |
+| `paxy/script` | Python script engine; `on_request` / `on_response` hooks |
+| `paxy/replay` | Async HTTP replay and parallel fuzzing via httpx |
+| `paxy/bulk` | Bulk sender and race condition test runner |
+| `paxy/dns` | Built-in DNS server with domain spoofing |
+| `paxy/exporter` | JSON/HAR export and rule import/export |
+| `paxy/codec` | Content-encoding decode (gzip/br/deflate); binary format decode (Protobuf/MessagePack/CBOR) |
+| `paxy/config` | YAML config loading |
+
+## Key design decisions
+
+### asyncio TCP server
+
+The proxy is a raw `asyncio.start_server` TCP server that parses HTTP manually.
+This lets a single connection handle HTTP/1.1 keep-alive, CONNECT tunnels, WebSocket upgrades, and MQTT detection without switching servers mid-connection.
+
+### TLS termination with `loop.start_tls()`
+
+After responding `200 Connection Established` to a CONNECT request, paxy calls `loop.start_tls()` to upgrade the existing asyncio transport to TLS server-side. Per-host certificates are cached as `ssl.SSLContext` objects.
+
+### SQLite persistence via aiosqlite
+
+All captured traffic is stored in memory for fast access. Writes to SQLite are fire-and-forget via `asyncio.run_coroutine_threadsafe`. On startup, `store.load_from_db()` restores prior sessions. The DB path defaults to `~/.paxy/paxy.db`.
+
+### Store pub/sub
+
+The `Store` maintains a list of `asyncio.Queue` subscribers. The proxy calls `loop.call_soon_threadsafe` to push entries into queues from the proxy coroutine. The UI polls each queue to receive live updates without blocking.
+
+### HTTP/2
+
+All upstream requests use `httpx` with `http2=True`. httpx negotiates HTTP/2 via ALPN where the server supports it and falls back to HTTP/1.1 transparently.
+
+### Filter expression engine
+
+The filter bar in the UI accepts a structured expression parsed by `paxy/store/filter_parser.py`. The parser tokenizes `field op value` conditions and evaluates them with AND/OR short-circuit logic against `Entry` objects in memory.
+
+### Binary format detection
+
+`paxy/codec.py` implements `sniff_content_type()` which combines Content-Type inspection with a JSON parse attempt and a binary entropy heuristic to guess the best display mode. Protobuf decoding uses wire-type heuristics without requiring a `.proto` schema.
+
+### GUI / CUI startup
+
+In **GUI mode**, `ui.run()` owns the event loop and the proxy is launched via `nicegui_app.on_startup`. In **CUI mode**, `asyncio.run()` owns the loop and `asyncio.gather` runs the proxy, uvicorn API server, and rich TUI concurrently.

pypproxy-0.1.0/docs/configuration.md

@@ -0,0 +1,78 @@
+# Configuration
+
+paxy can be configured via CLI flags or a YAML file. CLI flags take precedence over the config file.
+
+## YAML config file
+
+```bash
+uv run python main.py --config paxy.yaml
+```
+
+### Full example
+
+```yaml
+proxy:
+  addr: "0.0.0.0"
+  port: 8080
+  # Hosts to pass through without MITM (certificate pinning, internal services, etc.)
+  ignore:
+    - pinned.example.com
+    - internal.corp
+  # Maximum body size to capture, in bytes
+  max_body: 1048576  # 1 MB
+
+ca:
+  cert_path: /custom/ca-cert.pem
+  key_path:  /custom/ca-key.pem
+
+ui:
+  addr: "0.0.0.0"
+  port: 8081
+
+script:
+  path: /path/to/script.py
+```
+
+## Field reference
+
+### `proxy`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `addr` | string | `0.0.0.0` | Proxy listen address |
+| `port` | int | `8080` | Proxy port |
+| `ignore` | list | `[]` | Hosts to tunnel without MITM |
+| `max_body` | int | `1048576` | Max body bytes to capture |
+
+### `ca`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `cert_path` | string | `~/.paxy/ca-cert.pem` | CA certificate path |
+| `key_path` | string | `~/.paxy/ca-key.pem` | CA private key path |
+
+### `ui`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `addr` | string | `0.0.0.0` | Web UI / API listen address |
+| `port` | int | `8081` | Web UI / API port |
+
+### `script`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `path` | string | — | Python script path |
+
+## CLI flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--mode` | `gui` | UI mode: `gui` or `cui` |
+| `--addr` | `0.0.0.0` | Proxy listen address |
+| `--port` | `8080` | Proxy port |
+| `--ui-addr` | `0.0.0.0` | Web UI / API address |
+| `--ui-port` | `8081` | Web UI / API port |
+| `--config` | — | Config file path |
+| `--script` | — | Python script path |
+| `--ca-dir` | `~/.paxy` | Directory to store CA cert and key |