Riciplay

AI-powered bug bounty reconnaissance and penetration testing agent. This npm package is a launcher for the Python implementation (riciplay-cli on PyPI) — postinstall installs it via pip, and the riciplay command behaves identically to a native pip install.

What it does

• Agent sessions — an AI agent that plans and executes full investigations: recon → browsing → interception → findings
• Real browser control — trusted-input mouse/keyboard (hover menus, slider drags, canvas clicks), form-state autosave/restore, Cloudflare handling
• MiniProxy v4 interception — capture with TTFB/total timing, scope guard, Burp-style replay with response diffing, bounded payload sweeps
• Recon pipeline — subdomain/endpoint/tech discovery with durable per-program storage
• Notebook + findings — evidence-linked reporting across sessions

Install

npm install -g riciplay
# or the native Python path:
pip install riciplay-cli

Requires Node.js 18+ and an existing Python 3.12+ installation; this wrapper does not install Python itself. Chrome and proxy integrations are pulled in as Python dependencies. The 1.9.3 candidate uses riciplay-mitmproxy==12.3.1.1 and MiniProxy 0.9.7+. It rejects coexistence with upstream mitmproxy, refuses automatic shared-package removal, and requires a fresh venv for migration. Publication remains held until the complete fork chain and public installation/audit gates pass.

Usage

riciplay login        # interactive login with key
riciplay chat         # start an agent session

The npm wrapper

bin/riciplay resolves the pip-installed console script via PATH and falls back to invoking riciplay_cli.main:app through a detected Python 3.12+ interpreter. It explicitly excludes its own path as a candidate, so an npm global install (which symlinks this wrapper onto PATH) can never re-exec itself.

scripts/postinstall.js selects Python 3.12+ and runs that interpreter's -m pip to install riciplay-cli pinned to this launcher's exact version (riciplay-cli==<package.json version>). It checks the installed version both before and after installation, so an out-of-date install is upgraded instead of being silently kept. It degrades to a printed manual command when it can't (no network, --ignore-scripts, managed Python).

Before dispatching user commands, both PATH-console and module-fallback routes require the exact CLI version, Python 3.12+, Tornado 6.6+, and riciplay-mitmproxy==12.3.1.1 via a local metadata-only check. A stale PATH entry fails closed; it is not silently run after a failed installation. This is a version guard, not a substitute for the release dependency audit or a guarantee against a malicious executable placed on your PATH.

The two versions are locked together

The launcher and the Python package must be released at the same version, because postinstall pins the pair. That used to be an unenforced convention and it drifted (npm 1.8.95 against PyPI 1.8.96). Three things now enforce it:

• npm test / npm publish run scripts/check-version-sync.js — prepublishOnly refuses to publish a mismatched pair
• npm test, CI, and npm publish execute the real launcher regression. Publish also enforces the version-bound release-readiness.json hold and independently fetches exact non-yanked PyPI metadata, resolves riciplay-cli==<version> in a fresh Python 3.12 venv, rejects upstream/fork overlap, runs pip check, and requires a strict zero-finding pip-audit. A mutable readiness file alone is never release authorization. Release automation also supplies a new absolute RICIPLAY_PUBLIC_GATE_EVIDENCE path; prepublish records public artifact hashes there with create-only private permissions after all checks succeed. It also requires RICIPLAY_RELEASE_PYTHON to be the absolute validated Python 3.12 interpreter, avoiding PATH-dependent release resolution.
• pytest tests/test_version_sync.py fails the suite on drift, catching it at PR time
• python scripts/bump_version.py <version> moves both files together, so the correct action is also the easy one (--check to verify, --show to inspect)

Release order: PyPI first, then npm — the pinned postinstall needs the matching version to already exist on PyPI.

Repository: Zaidux/Riciplay