redrun-scan 0.1.0

RedRun — continuous, proof-backed security testing you run yourself.

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 [e-mail] --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.