Skip to main content

RedRun CLI

Proof-backed security testing you run yourself. A standalone command-line tool that runs RedRun's scanning engine locally on your machine — passive recon and real, evidence-verified exploitation (SQLi, XSS, SSRF, IDOR, broken auth) — with no cloud dependency.

This is the licensed-software M1 (see ../LICENSED-SOFTWARE-PLAN.md): the engine runs inside your own environment, so authorization is implicit (you point it at your own assets) and deeper/internal testing is possible.

Install (customers)

# Recommended: isolated install on PATH
pipx install ./dist/redrun-0.1.0-py3-none-any.whl
# or
pip install ./dist/redrun-0.1.0-py3-none-any.whl

For AI executive summaries: pipx install "redrun[ai]" and set ANTHROPIC_API_KEY.

Licensing

Passive scans are free. Active exploitation requires a license.

redrun license status                 # show current license
redrun license activate your.lic      # install a license file (offline-verified)

Licenses are Ed25519-signed and verified offline with an embedded public key — no server call, air-gap friendly. Tampering invalidates the signature.

Usage

# Passive scan — recon, headers, TLS, DNS, exposed paths, nuclei CVE templates
redrun scan example.com

# Active exploitation — requires explicit authorization
redrun scan staging.myapp.com --active --authorized

# Production-looking host needs an extra confirmation
redrun scan myapp.com --active --authorized --confirm-production

# Extra in-scope hosts, JSON export, kernel sandbox
redrun scan myapp.com --active --authorized --scope api.myapp.com --json out.json
redrun scan myapp.com --active --authorized --sandbox docker

Options

Flag Meaning
--active run real exploitation (not just passive observation)
--authorized confirm you own / may test the target (required for --active)
--confirm-production authorize an active scan against a production-looking host
--scope a,b additional in-scope hosts
--sandbox local|docker|auto containment for active scans (default local egress guard; docker = kernel iptables allowlist, needs a Docker host)
--json FILE write full results to JSON
--no-ai skip the AI executive summary

Local console (web UI)

RedRun ships a local web console — a targets dashboard, per-target scan history with live progress, an add-target flow, and license/settings — served by redrun serve from a single loopback process. The UI is a Vite + React SPA in ui/, built to redrun/app/static/ and served alongside the token-guarded /v1 API on 127.0.0.1.

# one-time: install UI deps
npm --prefix ui install
# build the UI (outputs to redrun/app/static/, served by `redrun serve`)
npm --prefix ui run build
# run the console — prints a URL containing the per-launch token
redrun serve

redrun serve binds 127.0.0.1:7800 by default and generates a fresh token each launch; open the printed http://127.0.0.1:7800/?token=… URL (the desktop shell will inject this for you in a later release). Every API request is checked for that token plus a same-origin guard, so a malicious web page cannot drive the local engine. If the UI hasn't been built yet, the API still runs and serve says so.

For UI development with hot reload, run the API and the Vite dev server side by side (the dev server proxies /v1 HTTP + WebSocket to the API):

redrun serve --port 7800          # terminal 1 (API + token)
npm --prefix ui run dev           # terminal 2 (proxies /v1 → 7800)

UI tests: npm --prefix ui test (Vitest + React Testing Library).

Desktop app (macOS)

RedRun ships as a native macOS app (Tauri) that bundles the Python control plane as a sidecar — no Python install required on the end-user machine. The Rust shell generates a per-launch loopback token, starts the sidecar, polls it until ready, and opens the console in the OS webview.

Build prerequisites: Rust (rustup), the Tauri CLI (cargo install tauri-cli --version "^2.0.0" --locked), and PyInstaller in the project venv (.venv/bin/python -m pip install "pyinstaller>=6.0").

# 1. Freeze the Python control plane into a Tauri resource (also builds the UI)
packaging/build-sidecar.sh
# 2. Run the desktop app in dev
cd desktop/src-tauri && cargo tauri dev
# 3. Produce a distributable .app / .dmg
cd desktop/src-tauri && cargo tauri build

The shell is the security boundary: it binds the API to 127.0.0.1, mints a fresh 256-bit token each launch, and passes it to the sidecar via env — the token is never on the command line. The shell supervises the sidecar (restarting it with a fresh token+port if it crashes) and kills it on quit, so no engine process is orphaned. A scan left running by a crash is marked interrupted on the next start.

Rust shell tests: cd desktop/src-tauri && cargo test. The end-to-end token-handoff is covered headlessly by tests/test_desktop_handoff.py (pytest -m network). Windows/Linux bundles, code-signing, and auto-update are not yet wired up.

Safety

  • Passive scans are read-only and legal on any domain.
  • Active scans send real attack payloads — only run them against systems you own or are authorized to test. The --authorized flag is your rules-of-engagement.
  • Active scanning is detection-only: it proves a vulnerability exists with request/response evidence, then stops — it never exfiltrates data or causes damage.
  • Outbound traffic is scope-enforced (egress guard by default; optional Docker kernel sandbox).

Optional

  • AI summaries: set ANTHROPIC_API_KEY and install the [ai] extra for an executive summary. Without it, the CLI runs fully offline.
  • Nuclei: if the nuclei binary is on PATH, CVE templates run automatically; otherwise that step is skipped.

Build & release (maintainers)

python -m build --wheel          # → dist/redrun-<v>-py3-none-any.whl

Issue a license (internal — needs the private signing key in scripts/.keys/, which is gitignored and must never ship):

python scripts/issue_license.py --email user@co.com --tier pro --days 365

Architecture

redrun/engine/ is a vendored copy of the scanning engine (recon, scope, egress guard, exploit tools, reporter). The CLI orchestrates it locally. Vendored for M1 to keep the tool standalone and zero-risk to the live web backend; a shared redrun_core package can de-duplicate later. redrun/licensing.py holds the embedded license-verification public key.

Metadata

Release files for redrun-scan 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for redrun-scan 0.1.0
File Size Uploaded Provenance Actions
redrun_scan-0.1.0.tar.gz 91.7 kB Without provenance Details for redrun_scan-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for redrun-scan 0.1.0
File Interpreter ABI Platform Actions
redrun_scan-0.1.0-py3-none-any.whl Python 3 none any Details for redrun_scan-0.1.0-py3-none-any.whl

Total release size: 185.7 kB

Release files / redrun_scan-0.1.0.tar.gz

Download URL redrun_scan-0.1.0.tar.gz
Size 91.7 kB
Tags Source
SHA-256 checksum
How to use checksums
bd999c500d27bb43607f6c36c94a5280fe644b4bdc740ee37fa85c190bc4ffe5
BLAKE2b-256 checksum
How to use checksums
17e05e68d6d243396d3d81e5019a867fd7aba8a7bc99fdb7fb1ce7e05cc19342
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / redrun_scan-0.1.0-py3-none-any.whl

Download URL redrun_scan-0.1.0-py3-none-any.whl
Size 94.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a777c325c3b4e036ee1160ea1500117ed0da550b3743f8bd898a6b68372eaafb
BLAKE2b-256 checksum
How to use checksums
5e610a3ff0764a98ddb067f3e45fdabafbd5b5ceaa099cb10b59a60b0293cf2c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for redrun-scan 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page