riciplay-miniproxy 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,6 +10,8 @@ Ships the **v4 capture engine** (the same addon the Riciplay CLI embeds):
|
|
|
10
10
|
- **Scope guard** — `--scope '*.target.com'` keeps out-of-scope traffic out of your capture DB (or 403-blocks it with `--block-out-of-scope`).
|
|
11
11
|
- **Repeater** — pick a logged request, edit method/headers/body, resend, inspect.
|
|
12
12
|
- **Intruder** — mark parameters with `§param§` placeholders, supply a wordlist, fuzz every position; results highlighted by status code and stored in the DB.
|
|
13
|
+
- **TUI** — a full terminal UI (`miniproxy tui`, built with [Textual](https://textual.textualize.io)): live capture feed, master–detail inspection, filters, Repeater, Intruder results, and proxy control — no browser needed.
|
|
14
|
+
- **Connect any browser** — the dashboard's **Connect** tab serves a PAC file, the CA cert, and a QR code so your browser (on any OS/device, including over SSH to a VPS) can route itself through MiniProxy.
|
|
13
15
|
|
|
14
16
|
## Install
|
|
15
17
|
|
|
@@ -26,12 +28,39 @@ Requires Python 3.10+ and [mitmproxy](https://mitmproxy.org/).
|
|
|
26
28
|
## Quick start
|
|
27
29
|
|
|
28
30
|
```bash
|
|
29
|
-
miniproxy start # proxy on :8080
|
|
31
|
+
miniproxy start # proxy on :8080 + web UI on :5000 (URL is printed)
|
|
32
|
+
miniproxy start --port auto # pick any free port (busy ports also move up automatically)
|
|
30
33
|
miniproxy start --scope '*.target.com' # capture only in-scope traffic
|
|
31
|
-
miniproxy
|
|
34
|
+
miniproxy tui # terminal UI (live feed, repeater, filters)
|
|
35
|
+
miniproxy dashboard # web UI in the foreground (Log/Repeater/Intruder)
|
|
36
|
+
miniproxy stop # stop proxy + dashboard
|
|
32
37
|
```
|
|
33
38
|
|
|
34
|
-
Then point your browser/system at `http://127.0.0.1:8080` (HTTPS interception uses mitmproxy's CA — run `mitmdump` once
|
|
39
|
+
Then point your browser/system at `http://127.0.0.1:8080` — the dashboard's **Connect** tab (`/connect`) prints the exact settings, a one-click PAC URL, the CA download, and a QR code. HTTPS interception uses mitmproxy's CA — install it from the Connect tab or run `mitmdump` once (`~/.mitmproxy/mitmproxy-ca-cert.pem`). Capture is always on while the proxy runs; the web UI and TUI are just windows onto the same capture DB. Running the proxy on a VPS or another machine? See [docs/connect.md](docs/connect.md).
|
|
40
|
+
|
|
41
|
+
### Capturing from another machine
|
|
42
|
+
|
|
43
|
+
Since 0.6.0 the proxy binds `127.0.0.1` only, so it is **not** reachable from
|
|
44
|
+
other machines until you say so. Forward the port over SSH instead — the
|
|
45
|
+
proxy never needs a public address:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# on the client (laptop/phone), then point the browser at 127.0.0.1:8080
|
|
49
|
+
ssh -N -L 8080:127.0.0.1:8080 user@your-host
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
To publish the proxy on a LAN/VPS interface instead, bind it explicitly and
|
|
53
|
+
restrict who may connect:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
miniproxy start --proxy-host 0.0.0.0 --allow-client 203.0.113.7
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`--allow-client` is repeatable. Without it, a published proxy is an open
|
|
60
|
+
relay: anything that can reach the port can capture through it and write to
|
|
61
|
+
your database.
|
|
62
|
+
|
|
63
|
+
📚 **Full documentation in [`docs/`](docs/index.md)** — [setup](docs/setup.md) · [CLI & TUI](docs/cli-and-tui.md) · [web UI](docs/web-ui.md) · [connect browsers & devices](docs/connect.md) · [integrations](docs/integrations.md) · [troubleshooting](docs/troubleshooting.md) · [code audit](docs/AUDIT.md).
|
|
35
64
|
|
|
36
65
|
```bash
|
|
37
66
|
miniproxy log # recent captured requests (with timing; reads the DB directly)
|
|
@@ -45,14 +74,80 @@ miniproxy stop
|
|
|
45
74
|
|
|
46
75
|
State (pid, port, default capture DB) lives under `~/.miniproxy/`.
|
|
47
76
|
|
|
77
|
+
## The TUI
|
|
78
|
+
|
|
79
|
+
`miniproxy tui` opens a two-pane terminal dashboard over the same SQLite capture DB the dashboard uses (it does not need the dashboard — or even the proxy — running):
|
|
80
|
+
|
|
81
|
+
- **Left** — the live capture table (ID, method, status, latency, URL), polling every 2s (`--refresh` to tune).
|
|
82
|
+
- **Right** — tabbed detail panes for the selected request: Request (line, headers, body), Response (headers, body), Intruder results.
|
|
83
|
+
- **Filters** — method, status class (2xx/3xx/4xx/5xx/errors/pending), and URL substring, all applied live.
|
|
84
|
+
- **Proxy bar** — current proxy state; `p` starts/stops it without leaving the app.
|
|
85
|
+
- Selection survives refreshes, `c` copies the request as a ready-to-run curl command, `y` copies the response body.
|
|
86
|
+
|
|
87
|
+
Keys: `r` Repeater · `i` Intruder · `c` copy curl · `y` copy body · `p` proxy · `R` refresh · `f/t/s` focus URL/method/status filter · `j/k` + `g/G` navigate · `?` help · `q` quit.
|
|
88
|
+
|
|
89
|
+
## Capturing traffic from the terminal (no browser needed)
|
|
90
|
+
|
|
91
|
+
You do **not** need a browser in your terminal. A proxy is just a middleman: any HTTP client that points at `127.0.0.1:8080` appears in the capture — browser or not.
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# pane 1
|
|
95
|
+
miniproxy start
|
|
96
|
+
miniproxy tui
|
|
97
|
+
|
|
98
|
+
# pane 2 — point any client at the proxy
|
|
99
|
+
export https_proxy=http://127.0.0.1:8080 http_proxy=http://127.0.0.1:8080
|
|
100
|
+
curl https://api.github.com/zen # shows up in the TUI immediately
|
|
101
|
+
pip install requests # same
|
|
102
|
+
HTTPS_PROXY=$https_proxy npm ping # same
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Plain HTTP works with zero setup. For **HTTPS**, the client must trust mitmproxy's CA (exactly like a browser would):
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
export REQUESTS_CA_BUNDLE=~/.mitmproxy/mitmproxy-ca-cert.pem # python/requests/pip
|
|
109
|
+
export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem # node/npm
|
|
110
|
+
curl --cacert ~/.mitmproxy/mitmproxy-ca-cert.pem https://example.com
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Tools that ignore proxy env vars can usually be pointed explicitly (`curl -x`, `git config http.proxy`, `pip --proxy`). And when *your own browser* is the client, nothing changes: point it at the proxy as usual and keep the TUI open beside it — both views read the same DB in real time.
|
|
114
|
+
|
|
48
115
|
## The dashboard
|
|
49
116
|
|
|
50
117
|
`miniproxy dashboard` serves a dark-theme SPA:
|
|
51
118
|
|
|
52
|
-
- **
|
|
53
|
-
- **Log** —
|
|
119
|
+
- **Live** — capture status, live request feed; click any row for full headers/bodies/timing
|
|
120
|
+
- **Log** — the complete request history
|
|
54
121
|
- **Repeater** — edit and resend any captured request
|
|
55
122
|
- **Intruder** — `§param§` placeholders + wordlist fuzzing, results by status code
|
|
123
|
+
- **Connect** — PAC URL, CA download, QR code, and step-by-step settings for connecting any browser/device (including remotely)
|
|
124
|
+
|
|
125
|
+
Captures persist across refreshes and restarts until you click
|
|
126
|
+
**Clear all captures…**.
|
|
127
|
+
|
|
128
|
+
## Connecting a browser (yours, a phone, or anywhere)
|
|
129
|
+
|
|
130
|
+
You don't need a browser in your terminal — you need the browser to send its
|
|
131
|
+
traffic *through* the proxy:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
miniproxy connect # prints the exact settings + a scannable QR
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
or open the dashboard's **Connect** tab (`http://127.0.0.1:5000/connect`):
|
|
138
|
+
one-click PAC URL, CA download with per-OS steps, `curl -x` one-liners, a
|
|
139
|
+
persistent saved-device registry, and a scannable QR code. The TUI shows the same cheat-sheet on `w`. Running MiniProxy
|
|
140
|
+
on a VPS and pointing your laptop/phone at it from anywhere?
|
|
141
|
+
**[docs/connect.md](docs/connect.md)** covers both the SSH-tunnel and
|
|
142
|
+
public-exposure patterns.
|
|
143
|
+
|
|
144
|
+
## Community & project docs
|
|
145
|
+
|
|
146
|
+
- [Security policy](SECURITY.md) — report vulnerabilities privately; responsible-use rules
|
|
147
|
+
- [Contributing](CONTRIBUTING.md) — dev setup, testing requirements, PR process
|
|
148
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md) — Contributor Covenant
|
|
149
|
+
- [Changelog](CHANGELOG.md) — every release
|
|
150
|
+
- [Examples](examples/) — curl / pip / npm / Python / VPS recipes
|
|
56
151
|
|
|
57
152
|
## Relation to the Riciplay CLI
|
|
58
153
|
|
|
@@ -68,11 +163,26 @@ src/miniproxy/
|
|
|
68
163
|
├── app.py # Flask dashboard (API + UI)
|
|
69
164
|
├── intruder.py # §placeholder§ fuzzing engine
|
|
70
165
|
├── server.py # start/stop/status process manager
|
|
166
|
+
├── tui.py # Textual terminal UI (live feed, repeater, filters)
|
|
71
167
|
└── __main__.py # the `miniproxy` entry point (start/stop/status/
|
|
72
|
-
# dashboard/send/log — log and
|
|
73
|
-
# any dashboard running)
|
|
168
|
+
# dashboard/tui/send/log — log, send, and the TUI
|
|
169
|
+
# work without any dashboard running)
|
|
74
170
|
```
|
|
75
171
|
|
|
172
|
+
## Development
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
git clone https://github.com/Zaidux/miniproxy && cd miniproxy
|
|
176
|
+
pip install -e ".[dev]"
|
|
177
|
+
pytest # 100+ tests: db, devices, API, exports, intruder, process mgr, TUI, connect
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
CI runs the suite on Linux/macOS (Python 3.10/3.12) for every push and PR,
|
|
181
|
+
plus a JS syntax check on the dashboard. The web dashboard binds `127.0.0.1`
|
|
182
|
+
by default; LAN exposure is opt-in via `--dashboard-host 0.0.0.0` (pair it
|
|
183
|
+
with `--dashboard-token` for auth on state-changing endpoints) — see
|
|
184
|
+
[docs/web-ui.md](docs/web-ui.md).
|
|
185
|
+
|
|
76
186
|
## License
|
|
77
187
|
|
|
78
188
|
MIT
|
package/package.json
CHANGED