riciplay-miniproxy 0.4.0

package/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.

package/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

package/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));

package/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": {}
+}

package/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');