Content
# proxying
**Local-first HTTP(S) MITM capture** — Web UI, REST Compose, rules, scripts, breakpoints, and MCP for AI agents.
No cloud. No accounts. No phone-home. Data stays on your machine (`~/.proxying` by default).
| Listen | Role |
|--------|------|
| `127.0.0.1:8080` | MITM proxy |
| `127.0.0.1:9090` | Web UI + control API + MCP HTTP |
<p align="center">
<img src="docs/images/ui-traffic.png" alt="proxying Web UI — live traffic capture list" width="100%" />
</p>
<p align="center">
<img src="docs/images/ui-detail.png" alt="proxying inspector — flow overview and detail" width="49%" />
<img src="docs/images/ui-rest.png" alt="proxying Compose — REST client" width="49%" />
</p>
> Full guide (install, CA trust, Android, API, troubleshooting): **[docs/USAGE.md](docs/USAGE.md)**
---
## Quick start
```bash
make release # build Web UI + bin/proxying
./bin/proxying # or: go run ./cmd/proxying
```
Open **http://127.0.0.1:9090** — traffic list, rules, REST panel.
```bash
./bin/proxying -version
./bin/proxying \
-proxy-addr 127.0.0.1:8080 \
-api-addr 127.0.0.1:9090 \
-data-dir ~/.proxying
```
### Point traffic at the proxy
```bash
export http_proxy=http://127.0.0.1:8080
export https_proxy=http://127.0.0.1:8080
curl -v https://example.com/
```
### Trust the local CA (HTTPS MITM)
```bash
curl -o proxying-ca.pem http://127.0.0.1:9090/api/ca.pem
```
| OS | Trust store |
|----|-------------|
| **Linux** | `sudo cp proxying-ca.pem /usr/local/share/ca-certificates/proxying-ca.crt && sudo update-ca-certificates` — or NSS: `certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n proxying -i proxying-ca.pem` |
| **macOS** | `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain proxying-ca.pem` |
| **Windows** | `certutil -addstore -f Root proxying-ca.pem` |
The CA private key lives under `-data-dir` with mode `0600`. **Never share it.**
---
## Features
- **MITM capture** — HTTP/HTTPS (goproxy), ring-buffer store, live SSE updates
- **Rules** — host allow/block, header/body rewrite, map-local (path-jailed)
- **JS scripts** — `onRequest` / `onResponse` via goja (sandboxed + timeout)
- **Breakpoints** — pause matched request/response, resume with optional edit
- **REST Compose** — send requests, env `{{var}}`, collections on disk, from-flow
- **Import / export** — HAR, CHLS; capture pause
- **Embedded SPA** — single binary with Web UI
- **MCP** — tools for OpenCode, Cursor, Claude Desktop
---
## Security defaults
| Default | Why |
|---------|-----|
| Bind `127.0.0.1` only | API + MITM not exposed on the LAN |
| CA key mode `0600` | Root of trust for all MITM certs |
| Scripts sandboxed + timeout | goja: no OS/network; default 100ms |
| Breakpoints max 32 + 60s timeout | Caps held connections |
| REST `http`/`https` only | `file://` rejected |
| map-local path jail | No filesystem escape |
This is a **debug tool on your machine**. Anyone who can reach the API can read captures and drive the proxy. Do **not** bind `0.0.0.0` without access control.
---
## Scripts
Place `*.js` under `~/.proxying/scripts/` (or your `-data-dir`):
```js
function onRequest(flow) {
flow.request.headers["X-Debug"] = "1";
}
function onResponse(flow) {
flow.response.headers["X-Out"] = "1";
}
```
Allowlisted fields only: `request.{method,url,headers,body}`, `response.{status,headers,body}`.
---
## Breakpoints
```bash
# enable + match
curl -X PUT http://127.0.0.1:9090/api/breakpoints \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"match":{"host":"example.com"}}'
# list holds
curl http://127.0.0.1:9090/api/breakpoints
# resume (optional header edits)
curl -X POST http://127.0.0.1:9090/api/breakpoints/{id}/resume \
-H 'Content-Type: application/json' \
-d '{"headers":{"X-Edited":"1"}}'
```
**Limit:** a hold blocks the proxy request goroutine until resume or timeout. CONNECT tunnel frames and HTTP/2 multiplexing are not paused independently. Client ALPN is advertised as `http/1.1` for full body capture.
---
## REST API (examples)
```bash
curl -X POST http://127.0.0.1:9090/api/rest/send \
-H 'Content-Type: application/json' \
-d '{"method":"GET","url":"https://example.com/"}'
curl -X POST http://127.0.0.1:9090/api/rest/from-flow/{id}
curl -X PUT http://127.0.0.1:9090/api/rest/env \
-H 'Content-Type: application/json' \
-d '{"env":{"base":"https://api.example.com"}}'
```
---
## MCP (AI agents)
### Tools
| Tool | Description |
|------|-------------|
| `list_flows` | List MITM captures (host / method / status / query) |
| `get_flow` | Full flow by id |
| `clear_flows` | Clear buffer |
| `set_capture_paused` | Pause or resume capture |
| `rest_send` | Send an HTTP(S) request |
| `rest_from_flow` | Build/send REST from a capture |
| `list_rules` | List MITM rules |
| `add_host_block_rule` | Block a host |
### Stdio (OpenCode / Cursor / Claude Desktop)
```json
{
"mcpServers": {
"proxying": {
"command": "/absolute/path/to/proxying",
"args": ["-mcp-stdio", "-data-dir", "/home/you/.proxying"]
}
}
}
```
Use the **same** `-data-dir` as the running UI process so the agent sees live captures.
### Streamable HTTP
While the UI is running:
```
http://127.0.0.1:9090/mcp
```
### Legacy helpers (web UI)
- `GET /api/mcp/tools`
- `POST /api/mcp/call` with `{"name":"list_flows","arguments":{}}`
---
## Android (short)
1. Run: `./bin/proxying -proxy-addr 0.0.0.0:8080 -api-addr 127.0.0.1:9090`
2. Install `ca.pem` as a **user CA** on the device
3. Wi‑Fi proxy → `PC_LAN_IP:8080`
4. Many apps need repack + `networkSecurityConfig` that trusts user CAs; certificate pinning needs extra bypass
Details: [docs/USAGE.md](docs/USAGE.md) (Android section) and [docs/android-mitm.md](docs/android-mitm.md).
---
## Develop
```bash
make test # Go tests
make build-go # binary only (uses committed embedded UI)
make build # rebuild web + go embed
make release # versioned release build
```
Prerequisites: **Go 1.22+** (built with 1.25), **Node 20+** only when rebuilding the Web UI.
---
## Docker Compose
```bash
cd deploy/compose
docker compose up -d --build
```
See [deploy/compose/README.md](deploy/compose/README.md). Binds `127.0.0.1` only; data volume persists CA and rules.
---
## License
MIT — see [LICENSE](LICENSE).
---
## Credits
Built with help from **Grok-4.5** (xAI).
Connection Info
You Might Also Like
No recommendations available