riciplay-miniproxy 0.4.0__tar.gz

riciplay_miniproxy-0.4.0/.gitignore

@@ -0,0 +1,3 @@
+dist/
+__pycache__/
+*.pyc

riciplay_miniproxy-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaidux
+
+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.

riciplay_miniproxy-0.4.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.3
+Name: riciplay-miniproxy
+Version: 0.4.0
+Summary: A lightweight HTTP/S interception proxy for security research — always-on capture, timing, scope guard, Repeater + Intruder dashboard
+Project-URL: Homepage, https://github.com/Zaidux/miniproxy
+Project-URL: Repository, https://github.com/Zaidux/miniproxy
+Author: Zaidux
+License: MIT
+Keywords: bugbounty,interception,intruder,mitmproxy,proxy,repeater,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: flask>=3.0.0
+Requires-Dist: mitmproxy>=10.0.0
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# MiniProxy
+
+A lightweight HTTP/S interception proxy for security research — the standalone Burp-style toolkit from the [Riciplay](https://github.com/Zaidux/Riciplay) ecosystem. Built on **mitmproxy**, **Flask**, and **SQLite**.
+
+Ships the **v4 capture engine** (the same addon the Riciplay CLI embeds):
+
+- **Always-on capture** — every request/response is logged with full headers, bodies, and status codes. (The old intercept toggle silently produced empty captures on fresh DBs; it's gone.)
+- **Static-asset streaming** — JS/CSS/images stream through without buffering, so heavy SPAs don't pay a per-flow decode tax.
+- **Timing** — `ttfb_ms` / `total_ms` on every flow. Oracles and timing side-channels need numbers.
+- **Scope guard** — `--scope '*.target.com'` keeps out-of-scope traffic out of your capture DB (or 403-blocks it with `--block-out-of-scope`).
+- **Repeater** — pick a logged request, edit method/headers/body, resend, inspect.
+- **Intruder** — mark parameters with `§param§` placeholders, supply a wordlist, fuzz every position; results highlighted by status code and stored in the DB.
+
+## Install
+
+```bash
+# Python (PyPI)
+pip install riciplay-miniproxy
+
+# or Node (npm — installs the Python package on postinstall)
+npm install -g riciplay-miniproxy
+```
+
+Requires Python 3.10+ and [mitmproxy](https://mitmproxy.org/).
+
+## Quick start
+
+```bash
+miniproxy start                          # proxy on :8080
+miniproxy start --scope '*.target.com'   # capture only in-scope traffic
+miniproxy dashboard                      # web UI on :5000 (Log/Repeater/Intruder)
+```
+
+Then point your browser/system at `http://127.0.0.1:8080` (HTTPS interception uses mitmproxy's CA — run `mitmdump` once and install `~/.mitmproxy/mitmproxy-ca-cert.pem` if you haven't).
+
+```bash
+miniproxy log                  # recent captured requests (with timing; reads the DB directly)
+miniproxy log --id 5           # full detail for request #5
+miniproxy send --url https://example.com/api --method POST \
+               --headers '{"Content-Type":"application/json"}' \
+               --body '{"key":"value"}'
+miniproxy status
+miniproxy stop
+```
+
+State (pid, port, default capture DB) lives under `~/.miniproxy/`.
+
+## The dashboard
+
+`miniproxy dashboard` serves a dark-theme SPA:
+
+- **Proxy** — capture status and scope
+- **Log** — live request feed; click any row for full headers/bodies/timing
+- **Repeater** — edit and resend any captured request
+- **Intruder** — `§param§` placeholders + wordlist fuzzing, results by status code
+
+## Relation to the Riciplay CLI
+
+The Riciplay CLI (`pip install riciplay-cli`) embeds this same engine with agent-first extras: per-session capture DBs, RULES.md-derived scope enforcement, headless replay with response diffing, and bounded payload sweeps driven by the AI agent. Use MiniProxy standalone when you want the manual Burp-like workflow; use Riciplay when you want the agent to drive.
+
+## Project structure
+
+```
+src/miniproxy/
+├── addon/
+│   ├── proxy.py        # mitmproxy addon — v4 capture engine
+│   └── db.py           # SQLite handler (timing columns, intruder results, pruning)
+├── app.py              # Flask dashboard (API + UI)
+├── intruder.py         # §placeholder§ fuzzing engine
+├── server.py           # start/stop/status process manager
+└── __main__.py         # the `miniproxy` entry point (start/stop/status/
+                        #   dashboard/send/log — log and send work without
+                        #   any dashboard running)
+```
+
+## License
+
+MIT

riciplay_miniproxy-0.4.0/README.md

@@ -0,0 +1,78 @@
+# MiniProxy
+
+A lightweight HTTP/S interception proxy for security research — the standalone Burp-style toolkit from the [Riciplay](https://github.com/Zaidux/Riciplay) ecosystem. Built on **mitmproxy**, **Flask**, and **SQLite**.
+
+Ships the **v4 capture engine** (the same addon the Riciplay CLI embeds):
+
+- **Always-on capture** — every request/response is logged with full headers, bodies, and status codes. (The old intercept toggle silently produced empty captures on fresh DBs; it's gone.)
+- **Static-asset streaming** — JS/CSS/images stream through without buffering, so heavy SPAs don't pay a per-flow decode tax.
+- **Timing** — `ttfb_ms` / `total_ms` on every flow. Oracles and timing side-channels need numbers.
+- **Scope guard** — `--scope '*.target.com'` keeps out-of-scope traffic out of your capture DB (or 403-blocks it with `--block-out-of-scope`).
+- **Repeater** — pick a logged request, edit method/headers/body, resend, inspect.
+- **Intruder** — mark parameters with `§param§` placeholders, supply a wordlist, fuzz every position; results highlighted by status code and stored in the DB.
+
+## Install
+
+```bash
+# Python (PyPI)
+pip install riciplay-miniproxy
+
+# or Node (npm — installs the Python package on postinstall)
+npm install -g riciplay-miniproxy
+```
+
+Requires Python 3.10+ and [mitmproxy](https://mitmproxy.org/).
+
+## Quick start
+
+```bash
+miniproxy start                          # proxy on :8080
+miniproxy start --scope '*.target.com'   # capture only in-scope traffic
+miniproxy dashboard                      # web UI on :5000 (Log/Repeater/Intruder)
+```
+
+Then point your browser/system at `http://127.0.0.1:8080` (HTTPS interception uses mitmproxy's CA — run `mitmdump` once and install `~/.mitmproxy/mitmproxy-ca-cert.pem` if you haven't).
+
+```bash
+miniproxy log                  # recent captured requests (with timing; reads the DB directly)
+miniproxy log --id 5           # full detail for request #5
+miniproxy send --url https://example.com/api --method POST \
+               --headers '{"Content-Type":"application/json"}' \
+               --body '{"key":"value"}'
+miniproxy status
+miniproxy stop
+```
+
+State (pid, port, default capture DB) lives under `~/.miniproxy/`.
+
+## The dashboard
+
+`miniproxy dashboard` serves a dark-theme SPA:
+
+- **Proxy** — capture status and scope
+- **Log** — live request feed; click any row for full headers/bodies/timing
+- **Repeater** — edit and resend any captured request
+- **Intruder** — `§param§` placeholders + wordlist fuzzing, results by status code
+
+## Relation to the Riciplay CLI
+
+The Riciplay CLI (`pip install riciplay-cli`) embeds this same engine with agent-first extras: per-session capture DBs, RULES.md-derived scope enforcement, headless replay with response diffing, and bounded payload sweeps driven by the AI agent. Use MiniProxy standalone when you want the manual Burp-like workflow; use Riciplay when you want the agent to drive.
+
+## Project structure
+
+```
+src/miniproxy/
+├── addon/
+│   ├── proxy.py        # mitmproxy addon — v4 capture engine
+│   └── db.py           # SQLite handler (timing columns, intruder results, pruning)
+├── app.py              # Flask dashboard (API + UI)
+├── intruder.py         # §placeholder§ fuzzing engine
+├── server.py           # start/stop/status process manager
+└── __main__.py         # the `miniproxy` entry point (start/stop/status/
+                        #   dashboard/send/log — log and send work without
+                        #   any dashboard running)
+```
+
+## License
+
+MIT

riciplay_miniproxy-0.4.0/bin/miniproxy

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// MiniProxy launcher — delegates to the Python package (riciplay-miniproxy).
+//
+//   miniproxy <args>  →  python3 -m miniproxy <args>
+//
+// The Python package is installed by scripts/postinstall.js (pip install
+// riciplay-miniproxy). If python3 is missing the user gets a clear error
+// rather than a silent failure.
+
+const { spawn } = require('child_process');
+
+const args = process.argv.slice(2);
+const proc = spawn('python3', ['-m', 'miniproxy', ...args], { stdio: 'inherit' });
+
+proc.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('Error: python3 not found. MiniProxy is a Python tool — install Python 3.10+ first.');
+    process.exit(1);
+  }
+  console.error('Error:', err.message);
+  process.exit(1);
+});
+
+proc.on('close', (code) => process.exit(code ?? 1));

riciplay_miniproxy-0.4.0/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "riciplay-miniproxy",
+  "version": "0.4.0",
+  "description": "A lightweight HTTP/S interception proxy for security research — always-on capture, timing, scope guard, Repeater + Intruder dashboard",
+  "main": "index.js",
+  "bin": {
+    "miniproxy": "./bin/miniproxy"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "echo \"Ensure the Python package riciplay-miniproxy is published to PyPI first\"",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zaidux/miniproxy.git"
+  },
+  "keywords": [
+    "proxy",
+    "mitmproxy",
+    "interception",
+    "security",
+    "bugbounty",
+    "repeater",
+    "intruder",
+    "pentesting"
+  ],
+  "author": "Zaidux <zaiduabubakar777@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Zaidux/miniproxy/issues"
+  },
+  "homepage": "https://github.com/Zaidux/miniproxy#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "bin/",
+    "scripts/postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "peerDependencies": {}
+}

riciplay_miniproxy-0.4.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "riciplay-miniproxy"
+version = "0.4.0"
+description = "A lightweight HTTP/S interception proxy for security research — always-on capture, timing, scope guard, Repeater + Intruder dashboard"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Zaidux"},
+]
+keywords = ["proxy", "mitmproxy", "interception", "security", "bugbounty", "repeater", "intruder"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: Internet :: Proxy Servers",
+]
+dependencies = [
+    "mitmproxy>=10.0.0",
+    "Flask>=3.0.0",
+    "requests>=2.31.0",
+]
+
+[project.scripts]
+miniproxy = "miniproxy.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/Zaidux/miniproxy"
+Repository = "https://github.com/Zaidux/miniproxy"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/miniproxy"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/miniproxy",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "bin",
+    "scripts",
+]

riciplay_miniproxy-0.4.0/scripts/postinstall.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// MiniProxy npm postinstall — installs the Python package from PyPI.
+//
+// This npm package is a thin launcher; the real implementation is the
+// Python package `riciplay-miniproxy`. If it is not importable, pip
+// install it. Failures are warnings, not errors: the user may be
+// installing without network access or managing Python themselves.
+
+const { execSync, spawnSync } = require('child_process');
+const os = require('os');
+
+console.log('\n🔌 Installing MiniProxy (HTTP/S interception proxy)...\n');
+
+const isWin = os.platform() === 'win32';
+const python = isWin ? 'python' : 'python3';
+const pip = isWin ? 'pip' : 'pip3';
+
+function hasCommand(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+try {
+  const probe = spawnSync(python, ['-c', 'import miniproxy'], { stdio: 'ignore' });
+  if (probe.status === 0) {
+    console.log('✓ Python package `miniproxy` already importable.');
+  } else {
+    console.log('Installing riciplay-miniproxy from PyPI...');
+    execSync(`${pip} install --upgrade riciplay-miniproxy`, { stdio: 'inherit' });
+    console.log('✓ Installed riciplay-miniproxy.');
+  }
+} catch (err) {
+  console.warn(
+    `\n⚠ Could not install the Python package automatically (${err.message}).\n` +
+    '  MiniProxy needs Python 3.10+ and mitmproxy. Install manually with:\n' +
+    '    pip install riciplay-miniproxy\n'
+  );
+}
+
+console.log('\nUsage: miniproxy start --port 8080   # then miniproxy dashboard\n');

riciplay_miniproxy-0.4.0/src/miniproxy/__init__.py

@@ -0,0 +1,9 @@
+"""MiniProxy — a lightweight HTTP/S interception proxy for security research.
+
+Ships the canonical v4 capture engine (the same addon the Riciplay CLI
+embeds): always-on capture, static-asset streaming, per-flow TTFB/total
+timing, and a RULES-style scope guard with skip/block modes — plus a Flask
+dashboard (Log / Repeater / Intruder) and a small manager CLI.
+"""
+
+__version__ = "0.4.0"

riciplay_miniproxy-0.4.0/src/miniproxy/__main__.py

@@ -0,0 +1,150 @@
+"""MiniProxy entry point — ``miniproxy`` / ``python -m miniproxy``.
+
+Subcommands:
+  start      Start the interception proxy (mitmdump + v4 addon)
+  stop       Stop the proxy
+  status     Proxy status
+  dashboard  Run the Flask dashboard (Log / Repeater / Intruder UI)
+  send       Send a request through the dashboard's Repeater
+  log        Show captured requests
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="miniproxy",
+        description="HTTP/S interception proxy for security research.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_start = sub.add_parser("start", help="Start the interception proxy")
+    p_start.add_argument("--port", type=int, default=8080)
+    p_start.add_argument("--db", default=None, help="SQLite capture DB path")
+    p_start.add_argument("--scope", nargs="*", default=None,
+                         help="Capture-scope hosts (*.domain wildcards); "
+                              "out-of-scope traffic is not captured")
+    p_start.add_argument("--block-out-of-scope", action="store_true",
+                         help="403-block out-of-scope traffic instead of passing it through")
+    p_start.add_argument("--mitmdump", default="mitmdump")
+
+    sub.add_parser("stop", help="Stop the proxy")
+    sub.add_parser("status", help="Proxy status")
+
+    p_dash = sub.add_parser("dashboard", help="Run the Flask dashboard")
+    p_dash.add_argument("--port", type=int, default=5000)
+    p_dash.add_argument("--host", default="127.0.0.1")
+
+    p_send = sub.add_parser("send", help="Send a request via the dashboard Repeater")
+    p_send.add_argument("--url", required=True)
+    p_send.add_argument("--method", default="GET")
+    p_send.add_argument("--headers", default="{}", help="JSON object of headers")
+    p_send.add_argument("--body", default="")
+
+    p_log = sub.add_parser("log", help="Show captured requests")
+    p_log.add_argument("--id", type=int, default=None)
+    p_log.add_argument("--limit", type=int, default=30)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "start":
+        from miniproxy import server
+        result = server.start(
+            port=args.port, db_path=args.db, scope_hosts=args.scope,
+            out_of_scope="block" if args.block_out_of_scope else "skip",
+            mitmdump_path=args.mitmdump,
+        )
+        print(result["message"])
+        return 0 if result["status"] in ("started", "already_running") else 1
+
+    if args.command == "stop":
+        from miniproxy import server
+        result = server.stop()
+        print(result["message"])
+        return 0 if result["status"] in ("stopped", "not_running") else 1
+
+    if args.command == "status":
+        from miniproxy import server
+        result = server.status()
+        print(result["message"])
+        return 0 if result["status"] == "running" else 1
+
+    if args.command == "dashboard":
+        from miniproxy.app import app
+        app.run(host=args.host, port=args.port, debug=False)
+        return 0
+
+    if args.command == "send":
+        # Direct request — no dashboard needed (mirrors the Repeater API's
+        # semantics: no redirects, self-signed certs allowed, 15s timeout).
+        import json as _json
+
+        import requests
+        import urllib3
+
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+        try:
+            headers = _json.loads(args.headers)
+            if not isinstance(headers, dict):
+                headers = {}
+        except ValueError:
+            print("Error: --headers must be a JSON object", file=sys.stderr)
+            return 1
+        try:
+            resp = requests.request(
+                method=args.method.upper(), url=args.url, headers=headers,
+                data=args.body, timeout=15, verify=False, allow_redirects=False,
+            )
+        except requests.RequestException as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+        print(f"Status: {resp.status_code}")
+        print(f"Headers: {_json.dumps(dict(resp.headers), indent=2)}")
+        body_text = resp.text or ""
+        print(f"Body ({len(body_text)} chars):")
+        print(body_text[:2000] + ("..." if len(body_text) > 2000 else ""))
+        return 0
+
+    if args.command == "log":
+        # Reads the capture DB directly — the dashboard does not need to
+        # be running to inspect what the proxy captured.
+        from miniproxy.addon.db import Database
+        from miniproxy.server import STATE_DIR
+
+        db = Database(os.environ.get("MINIPROXY_DB_PATH") or (STATE_DIR / "proxy.db"))
+        if args.id is not None:
+            row = db.get_request(args.id)
+            if row is None:
+                print(f"No captured request with id={args.id}.", file=sys.stderr)
+                return 1
+            print(f"ID:      {row.get('id')}")
+            print(f"Method:  {row.get('method')}")
+            print(f"URL:     {row.get('url')}")
+            print(f"Status:  {row.get('response_code')}")
+            print(f"TTFB:    {row.get('ttfb_ms')} ms | Total: {row.get('total_ms')} ms")
+            print(f"Headers: {str(row.get('headers') or '')[:500]}")
+            print(f"Body:    {str(row.get('body') or '')[:1000]}")
+            return 0
+        logs = db.get_logs(limit=max(args.limit, 1))
+        print(f"{'ID':>4} {'METHOD':<7} {'STATUS':<5} {'MS':>7}  URL")
+        print("-" * 72)
+        for r in logs:
+            ms = r.get("total_ms")
+            ms_s = f"{ms:.0f}" if isinstance(ms, (int, float)) else "?"
+            print(f"{r.get('id', '?'):>4} {r.get('method', '?'):<7} "
+                  f"{r.get('response_code', '?'):<5} {ms_s:>7}  "
+                  f"{str(r.get('url', ''))[:60]}")
+        if not logs:
+            print("(no captured requests yet)")
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

riciplay_miniproxy-0.4.0/src/miniproxy/addon/__init__.py

@@ -0,0 +1,7 @@
+"""MiniProxy addon package — the canonical v4 mitmproxy addon.
+
+``proxy.py`` and ``db.py`` are loaded by mitmdump BY PATH (``mitmdump -s
+.../addon/proxy.py``); the ``__init__.py`` exists so the same files are
+importable as a regular package (tests, tooling) via the try/except import
+at the top of ``proxy.py``.
+"""