redrun-scan 0.1.0__tar.gz

redrun_scan-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+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.

redrun_scan-0.1.0/README.md

@@ -0,0 +1,153 @@
+# 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.

redrun_scan-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI ("redrun" is taken). The CLI command stays `redrun`
+# (see [project.scripts]) and the import package stays `redrun/`.
+name = "redrun-scan"
+version = "0.1.0"
+description = "RedRun — continuous, proof-backed security testing you run yourself."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "RedRun" }]
+dependencies = [
+    "pydantic>=2.10.0",
+    "httpx>=0.28.0",
+    "dnspython>=2.7.0",
+    "beautifulsoup4>=4.12.0",
+    "lxml>=5.3.0",
+    "cryptography>=42.0.0",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+]
+
+[project.optional-dependencies]
+# AI executive summaries / attack-chain narrative (set ANTHROPIC_API_KEY to use).
+ai = ["anthropic>=0.40.0"]
+tools = ["sslyze>=6.0.0"]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0", "httpx>=0.28.0"]
+
+[project.scripts]
+redrun = "redrun.cli:main"
+
+# Explicitly list packages so setuptools does NOT treat the hyphenated
+# docker/egress-proxy data dir as a (invalid) namespace package.
+[tool.setuptools]
+packages = ["redrun", "redrun.app", "redrun.engine", "redrun.engine.tools"]
+
+[tool.setuptools.package-data]
+"redrun.engine" = ["docker/egress-proxy/*"]

redrun_scan-0.1.0/redrun/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from redrun.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

redrun_scan-0.1.0/redrun/app/__init__.py

@@ -0,0 +1 @@
+"""RedRun local control plane — the FastAPI app behind `redrun serve`."""

redrun_scan-0.1.0/redrun/app/auth.py

@@ -0,0 +1,50 @@
+"""Per-launch local API token + same-origin guard.
+
+The control plane runs an exploitation engine, so the only caller allowed is the
+app's own webview. We require a per-launch token header AND reject any cross-site
+Origin (defeats a malicious page reaching 127.0.0.1 via DNS-rebinding/CSRF).
+"""
+from __future__ import annotations
+
+import hmac
+import secrets
+from urllib.parse import urlparse
+
+from fastapi import Header, HTTPException
+from typing import Optional
+
+
+def is_allowed_origin(origin: Optional[str]) -> bool:
+    """True if the Origin is same-origin/loopback or the Tauri shell, or absent
+    (non-browser client). A foreign site is rejected (anti DNS-rebind/CSRF).
+
+    Uses exact hostname matching (not prefix) so spoofed domains like
+    http://127.0.0.1.evil.com cannot bypass the guard.
+    """
+    if origin is None:
+        return True
+    parsed = urlparse(origin)
+    host = parsed.hostname  # None for schemes like tauri:// without //host
+    return (
+        host in ("127.0.0.1", "localhost", "::1")
+        or (parsed.scheme == "tauri" and host in ("localhost", None))
+    )
+
+
+class LocalAuth:
+    def __init__(self, token: str):
+        self.token = token
+
+    @staticmethod
+    def new_token() -> str:
+        return secrets.token_urlsafe(32)
+
+    async def require(
+        self,
+        x_redrun_token: Optional[str] = Header(default=None),
+        origin: Optional[str] = Header(default=None),
+    ) -> None:
+        if not is_allowed_origin(origin):
+            raise HTTPException(status_code=403, detail="Cross-origin blocked")
+        if not x_redrun_token or not hmac.compare_digest(x_redrun_token, self.token):
+            raise HTTPException(status_code=401, detail="Invalid local token")

redrun_scan-0.1.0/redrun/app/db.py

@@ -0,0 +1,57 @@
+"""SQLite connection + schema for the local control plane."""
+from __future__ import annotations
+
+import sqlite3
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS targets (
+    id              TEXT PRIMARY KEY,
+    label           TEXT NOT NULL,
+    host_or_url     TEXT NOT NULL,
+    scope           TEXT NOT NULL DEFAULT '[]',   -- JSON list of hosts/CIDRs
+    authorized      INTEGER NOT NULL DEFAULT 0,
+    enabled_phases  TEXT NOT NULL DEFAULT '[]',   -- JSON list of phase names
+    tags            TEXT NOT NULL DEFAULT '[]',   -- JSON list
+    created_at      TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS scans (
+    id            TEXT PRIMARY KEY,
+    target_id     TEXT NOT NULL REFERENCES targets(id) ON DELETE CASCADE,
+    mode          TEXT NOT NULL,
+    status        TEXT NOT NULL,
+    phase         TEXT,
+    progress      INTEGER NOT NULL DEFAULT 0,
+    started_at    TEXT,
+    completed_at  TEXT,
+    duration      REAL,
+    report        TEXT NOT NULL DEFAULT '{}',
+    source        TEXT NOT NULL DEFAULT 'manual'
+);
+CREATE INDEX IF NOT EXISTS idx_scans_target ON scans(target_id);
+CREATE TABLE IF NOT EXISTS settings (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+"""
+
+
+def connect(path: str) -> sqlite3.Connection:
+    conn = sqlite3.connect(path, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.execute("PRAGMA journal_mode = WAL")
+    return conn
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """Idempotent column adds for DBs created before a column existed."""
+    cols = {r["name"] for r in conn.execute("PRAGMA table_info(scans)")}
+    if "source" not in cols:
+        conn.execute(
+            "ALTER TABLE scans ADD COLUMN source TEXT NOT NULL DEFAULT 'manual'")
+
+
+def init_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(_SCHEMA)
+    _migrate(conn)
+    conn.commit()

redrun_scan-0.1.0/redrun/app/events.py

@@ -0,0 +1,31 @@
+"""In-process async pub/sub. One queue per WebSocket subscriber, keyed by scan id.
+A small per-scan backlog lets a client that connects mid-scan replay the events it
+missed; the authoritative final state is always in GET /v1/scans/{id}."""
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict, deque
+
+
+class EventHub:
+    def __init__(self, backlog: int = 64):
+        self._subs: dict[str, list[asyncio.Queue]] = defaultdict(list)
+        self._backlog: dict[str, deque] = defaultdict(lambda: deque(maxlen=backlog))
+
+    def subscribe(self, scan_id: str) -> asyncio.Queue:
+        q: asyncio.Queue = asyncio.Queue()
+        for event in self._backlog.get(scan_id, ()):  # replay what was missed
+            q.put_nowait(event)
+        self._subs[scan_id].append(q)
+        return q
+
+    def unsubscribe(self, scan_id: str, q: asyncio.Queue) -> None:
+        if q in self._subs.get(scan_id, []):
+            self._subs[scan_id].remove(q)
+        if not self._subs.get(scan_id):
+            self._subs.pop(scan_id, None)
+
+    async def publish(self, scan_id: str, event: dict) -> None:
+        self._backlog[scan_id].append(event)
+        for q in list(self._subs.get(scan_id, [])):
+            await q.put(event)

redrun_scan-0.1.0/redrun/app/models.py

@@ -0,0 +1,60 @@
+"""Local control-plane domain types. Finding is reused from the engine schema."""
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class Phase(str, Enum):
+    RECON = "recon"
+    ENUMERATION = "enumeration"
+    VULN_ASSESSMENT = "vuln_assessment"
+    EXPLOITATION = "exploitation"
+    EXPOSURE = "exposure"
+
+
+# Phases an ACTIVE scan may run; passive excludes EXPLOITATION.
+PASSIVE_PHASES = [Phase.RECON, Phase.ENUMERATION, Phase.VULN_ASSESSMENT, Phase.EXPOSURE]
+ACTIVE_PHASES = [Phase.RECON, Phase.ENUMERATION, Phase.VULN_ASSESSMENT,
+                 Phase.EXPLOITATION, Phase.EXPOSURE]
+
+
+class ScanStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    INTERRUPTED = "interrupted"
+
+
+class Target(BaseModel):
+    id: str
+    label: str
+    host_or_url: str
+    scope: list[str] = Field(default_factory=list)
+    authorized: bool = False
+    enabled_phases: list[str] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    # rolled-up display state (computed from scans, not stored on the row)
+    status: str = "idle"
+    last_scan_at: Optional[datetime] = None
+    latest_risk_score: Optional[int] = None
+    open_findings: dict = Field(default_factory=dict)
+
+
+class ScanRecord(BaseModel):
+    id: str
+    target_id: str
+    mode: str = "passive"
+    status: ScanStatus = ScanStatus.PENDING
+    phase: Optional[str] = None
+    progress: int = 0
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    duration: Optional[float] = None
+    report: dict = Field(default_factory=dict)
+    source: str = "manual"