Metadata-Version: 2.4
Name: redrun-scan
Version: 0.1.0
Summary: RedRun — continuous, proof-backed security testing you run yourself.
Author: RedRun
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.10.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: dnspython>=2.7.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: lxml>=5.3.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40.0; extra == "ai"
Provides-Extra: tools
Requires-Dist: sslyze>=6.0.0; extra == "tools"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"

# 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)
```bash
# 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.
```bash
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
```bash
# 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`.

```bash
# 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):

```bash
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"`).

```bash
# 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)
```bash
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):
```bash
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.
