redrun-scan 0.1.0__py3-none-any.whl

redrun/__main__.py

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

redrun/app/__init__.py

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

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/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/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/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"

redrun/app/phases.py

@@ -0,0 +1,257 @@
+"""Phase-structured tool layer.
+
+Each phase holds adapters. A built-in adapter wraps the existing engine; external
+tools (e.g. sslyze) are additional adapters. Every adapter MUST return verified,
+proof-backed Findings — raw tool output is never surfaced (zero-FP gate).
+"""
+from __future__ import annotations
+
+import abc
+import asyncio
+import hashlib
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, ClassVar, Optional
+
+from redrun.app.models import Phase
+from redrun.engine.schemas import AttackSurfaceMap, Finding
+
+if TYPE_CHECKING:
+    from redrun.engine.scope import ScopeValidator
+
+
+@dataclass
+class ScanContext:
+    """Shared state threaded through the phases of one scan."""
+    host: str                       # bare host (no scheme/port)
+    target: str                     # original target (may include :port)
+    scope: Optional["ScopeValidator"]   # ScopeValidator | None (set for active)
+    mode: str                       # passive | active
+    surface: Optional[AttackSurfaceMap] = None
+    findings: list[Finding] = field(default_factory=list)
+
+
+class ToolAdapter(abc.ABC):
+    name: ClassVar[str] = "adapter"
+    phase: ClassVar[Phase] = Phase.VULN_ASSESSMENT
+
+    def available(self) -> bool:
+        return True
+
+    @abc.abstractmethod
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        ...
+
+
+# ── built-in adapters: wrap the existing engine ─────────────────────────────
+class ReconBuiltin(ToolAdapter):
+    name = "recon_builtin"
+    phase = Phase.RECON
+
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        from redrun.engine.recon import ReconAgent
+        surface = await ReconAgent().run(ctx.host)
+        if isinstance(surface, Exception):
+            surface = AttackSurfaceMap(target=ctx.target, scan_time=datetime.utcnow())
+        ctx.surface = surface
+        return []  # recon is discovery; it produces no findings itself
+
+
+class EnumerationBuiltin(ToolAdapter):
+    name = "enum_builtin"
+    phase = Phase.ENUMERATION
+
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        # Endpoint/tech enumeration is folded into recon's surface today; the
+        # active checks in vuln-assessment consume it. No standalone findings yet.
+        return []
+
+
+class VulnAssessmentBuiltin(ToolAdapter):
+    name = "vuln_builtin"
+    phase = Phase.VULN_ASSESSMENT
+
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        from redrun.engine.active_scanner import ActiveScanner
+        from redrun.engine.nuclei_scanner import NucleiScanner
+        subs = ctx.surface.subdomains if ctx.surface else []
+        # NOTE: call ActiveScanner.scan with the VENDORED engine's signature
+        # (target, subdomains) — the vendored copy predates the backend's
+        # `active=` param. Active vs passive is expressed by whether the
+        # EXPLOITATION phase runs, not by a flag here.
+        passive, nuclei = await asyncio.gather(
+            ActiveScanner().scan(ctx.target, subs),
+            NucleiScanner().scan(ctx.host),
+            return_exceptions=True)
+        out: list[Finding] = []
+        out += passive if isinstance(passive, list) else []
+        out += nuclei if isinstance(nuclei, list) else []
+        return out
+
+
+class ExploitationBuiltin(ToolAdapter):
+    name = "exploit_builtin"
+    phase = Phase.EXPLOITATION
+
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        if ctx.mode != "active" or ctx.scope is None or ctx.surface is None:
+            return []
+        from redrun.engine.exploitation import ExploitationAgent
+        ctx.surface.target = ctx.target
+        try:
+            return await ExploitationAgent().run(ctx.surface, ctx.scope)
+        except Exception as e:
+            print(f"[phases] exploitation phase error: {e}")
+            return []
+
+
+class ExposureBuiltin(ToolAdapter):
+    name = "exposure_builtin"
+    phase = Phase.EXPOSURE
+
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        from redrun.engine.schemas import Remediation, Severity
+        out: list[Finding] = []
+        surface = ctx.surface
+        if not surface:
+            return out
+        for bucket in surface.open_buckets:
+            out.append(Finding(
+                id=f"s3_open_{bucket.replace('.', '_')}",
+                title="Publicly Accessible S3 Bucket", severity=Severity.CRITICAL,
+                cvss_score=9.8, description=f"S3 bucket '{bucket}' is publicly listable.",
+                affected_asset=bucket,
+                proof_of_concept=f"GET https://{bucket}/  ->  200 OK (XML listing)",
+                remediation=Remediation(
+                    summary="Set bucket ACL private; enable Block Public Access.",
+                    effort="1h", references=[])))
+        for secret in surface.exposed_secrets:
+            out.append(Finding(
+                id=f"secret_{hashlib.sha256(secret.source.encode()).hexdigest()[:8]}",
+                title=f"Exposed {secret.type} on GitHub", severity=Severity.HIGH,
+                cvss_score=8.2,
+                description=f"A {secret.type} for this domain was found publicly.",
+                affected_asset=secret.source,
+                proof_of_concept=f"Source: {secret.source}\nType: {secret.type}\n"
+                                 f"Preview: {secret.preview}",
+                remediation=Remediation(
+                    summary=f"Rotate the exposed {secret.type}; purge from Git history.",
+                    effort="1d", references=[])))
+        return out
+
+
+class SslyzeAdapter(ToolAdapter):
+    """TLS analysis via sslyze. Optional (pip extra `tools`). Output is verified
+    into findings; we never surface raw scan structs."""
+    name = "sslyze"
+    phase = Phase.VULN_ASSESSMENT
+
+    def available(self) -> bool:
+        try:
+            import sslyze  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    async def run(self, ctx: ScanContext) -> list[Finding]:
+        import asyncio
+        analysis = await asyncio.to_thread(self._analyze, ctx.host)
+        if analysis is None:
+            return []
+        return self._verify(ctx.host, analysis)
+
+    def _analyze(self, host: str) -> Optional[dict]:
+        try:
+            from sslyze import (Scanner, ServerScanRequest,
+                                ServerNetworkLocation, ScanCommand)
+        except ImportError:
+            return None
+        try:
+            req = ServerScanRequest(
+                server_location=ServerNetworkLocation(hostname=host, port=443),
+                scan_commands={ScanCommand.CERTIFICATE_INFO,
+                               ScanCommand.SSL_2_0_CIPHER_SUITES,
+                               ScanCommand.SSL_3_0_CIPHER_SUITES,
+                               ScanCommand.TLS_1_0_CIPHER_SUITES})
+            scanner = Scanner()
+            scanner.queue_scans([req])
+            cert_invalid, cert_reason, weak = False, None, []
+            for result in scanner.get_results():
+                attempts = result.scan_result
+                ci = getattr(attempts, "certificate_info", None)
+                if ci and getattr(ci, "status", None) and ci.status.name == "COMPLETED" \
+                        and ci.result:
+                    errs = []
+                    for dep in ci.result.certificate_deployments:
+                        for pv in dep.path_validation_results:
+                            if not pv.was_validation_successful and pv.validation_error:
+                                errs.append(pv.validation_error.lower())
+                    if errs:
+                        cert_invalid = True
+                        joined = " ".join(errs)
+                        if "not valid at validation time" in joined or "expired" in joined:
+                            cert_reason = "expired"
+                        elif "self" in joined and "sign" in joined:
+                            cert_reason = "self_signed"
+                        else:
+                            cert_reason = "untrusted"
+                for proto, attr in (("SSL 2.0", "ssl_2_0_cipher_suites"),
+                                    ("SSL 3.0", "ssl_3_0_cipher_suites"),
+                                    ("TLS 1.0", "tls_1_0_cipher_suites")):
+                    cs = getattr(attempts, attr, None)
+                    if cs and getattr(cs, "status", None) and cs.status.name == "COMPLETED" \
+                            and cs.result and cs.result.accepted_cipher_suites:
+                        weak.append(proto)
+            return {"cert_invalid": cert_invalid, "cert_reason": cert_reason,
+                    "weak_protocols": weak}
+        except Exception as e:
+            print(f"[phases] sslyze analyze error: {e}")
+            return None
+
+    def _verify(self, host: str, analysis: dict) -> list[Finding]:
+        from redrun.engine.schemas import Remediation, Severity
+        out: list[Finding] = []
+        if analysis.get("cert_invalid"):
+            reason = analysis.get("cert_reason") or "untrusted"
+            title = {"expired": "Expired TLS Certificate",
+                     "self_signed": "Self-Signed TLS Certificate",
+                     "untrusted": "Untrusted TLS Certificate"}[reason]
+            out.append(Finding(
+                id=f"tls_cert_{reason}_{host.replace('.', '_')}",
+                title=title, severity=Severity.HIGH, cvss_score=7.4,
+                description=f"{host} presents a certificate that fails path "
+                            f"validation (sslyze classification: {reason}).",
+                affected_asset=host,
+                proof_of_concept=f"sslyze CERTIFICATE_INFO on {host}:443 -> path "
+                                 f"validation failed ({reason})",
+                remediation=Remediation(
+                    summary="Install a valid, trusted, unexpired certificate; "
+                            "automate renewal.",
+                    effort="1h", references=[
+                        "https://cheatsheetseries.owasp.org/cheatsheets/"
+                        "Transport_Layer_Security_Cheat_Sheet.html"])))
+        weak = analysis.get("weak_protocols") or []
+        if weak:
+            out.append(Finding(
+                id=f"tls_weak_proto_{host.replace('.', '_')}",
+                title="Weak TLS Protocols Enabled", severity=Severity.MEDIUM,
+                cvss_score=5.9,
+                description=f"{host} accepts deprecated protocol(s): "
+                            f"{', '.join(weak)}.",
+                affected_asset=host,
+                proof_of_concept=f"sslyze on {host}:443: accepted cipher suites "
+                                 f"present for: {', '.join(weak)}",
+                remediation=Remediation(
+                    summary="Disable SSLv2/SSLv3/TLS1.0; require TLS 1.2+.",
+                    effort="1h", references=[])))
+        return out
+
+
+REGISTRY: list[ToolAdapter] = [
+    ReconBuiltin(), EnumerationBuiltin(), VulnAssessmentBuiltin(),
+    SslyzeAdapter(), ExploitationBuiltin(), ExposureBuiltin(),
+]
+
+
+def available_adapters(phase: Phase) -> list[ToolAdapter]:
+    return [a for a in REGISTRY if a.phase == phase and a.available()]

redrun/app/runner.py

@@ -0,0 +1,101 @@
+"""Scan runner: executes the phase pipeline as one async task, emits progress
+events, enforces the scope-inversion safety model and the license gate."""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Callable
+
+from redrun.app.events import EventHub
+from redrun.app.models import (ACTIVE_PHASES, PASSIVE_PHASES,
+                               ScanRecord, ScanStatus, Target)
+from redrun.app.phases import ScanContext, available_adapters
+from redrun.app.store import ScanStore
+from redrun.engine.scope import ScopeValidator
+
+
+def build_scope(host: str, allowlist: list[str]) -> ScopeValidator:
+    """Local scope: allow private IPs (internal testing is the point) but confine
+    strictly to the target's allowlist. Metadata/link-local stay blocked unless
+    explicitly listed."""
+    entries = [host] + [a for a in (allowlist or []) if a.strip()]
+    return ScopeValidator(entries, allow_private=True)
+
+
+class ScanRunner:
+    def __init__(self, scans: ScanStore, hub: EventHub,
+                 license_ok: Callable[[], bool]):
+        self.scans = scans
+        self.hub = hub
+        self.license_ok = license_ok
+
+    async def execute(self, scan: ScanRecord, target: Target) -> None:
+        scan.status = ScanStatus.RUNNING
+        scan.started_at = datetime.utcnow()
+        self.scans.save(scan)
+
+        if scan.mode == "active" and not self.license_ok():
+            return await self._fail(scan, "Active scans require a valid license.")
+        if scan.mode == "active" and not target.authorized:
+            return await self._fail(scan, "Target is not marked authorized.")
+
+        host = target.host_or_url.split("//")[-1].split("/")[0].split(":")[0]
+        scope = (build_scope(host, target.scope) if scan.mode == "active" else None)
+        ctx = ScanContext(host=host, target=target.host_or_url, scope=scope,
+                          mode=scan.mode)
+
+        phases = ACTIVE_PHASES if scan.mode == "active" else PASSIVE_PHASES
+        if target.enabled_phases:
+            phases = [p for p in phases if p.value in target.enabled_phases]
+
+        try:
+            for i, phase in enumerate(phases):
+                scan.phase = phase.value
+                scan.progress = int(i / max(len(phases), 1) * 100)
+                self.scans.save(scan)
+                await self.hub.publish(scan.id, {
+                    "phase": phase.value, "progress": scan.progress})
+                for adapter in available_adapters(phase):
+                    new = await self._run_adapter(adapter, ctx)
+                    ctx.findings.extend(new)
+                    for f in new:
+                        await self.hub.publish(scan.id, {
+                            "phase": phase.value, "finding": f.title,
+                            "severity": f.severity.value if hasattr(
+                                f.severity, "value") else str(f.severity)})
+        except Exception as e:  # one scan never crashes the control plane
+            return await self._fail(scan, f"{type(e).__name__}: {e}")
+
+        await self._complete(scan, ctx)
+
+    async def _run_adapter(self, adapter, ctx: ScanContext) -> list:
+        return await adapter.run(ctx)
+
+    async def _complete(self, scan: ScanRecord, ctx: ScanContext) -> None:
+        findings = ctx.findings
+        counts = {s: 0 for s in ("critical", "high", "medium", "low")}
+        for f in findings:
+            sev = f.severity.value if hasattr(f.severity, "value") else str(f.severity)
+            if sev in counts:
+                counts[sev] += 1
+        risk = min(100, counts["critical"] * 30 + counts["high"] * 15
+                   + counts["medium"] * 5 + counts["low"] * 1)
+        scan.status = ScanStatus.COMPLETED
+        scan.completed_at = datetime.utcnow()
+        scan.progress = 100
+        scan.duration = (scan.completed_at - scan.started_at).total_seconds()
+        scan.report = {
+            "risk_score": risk,
+            "critical_count": counts["critical"], "high_count": counts["high"],
+            "medium_count": counts["medium"], "low_count": counts["low"],
+            "findings": [f.model_dump() for f in findings],
+        }
+        self.scans.save(scan)
+        await self.hub.publish(scan.id, {"status": "completed", "progress": 100,
+                                         "risk_score": risk})
+
+    async def _fail(self, scan: ScanRecord, reason: str) -> None:
+        scan.status = ScanStatus.FAILED
+        scan.completed_at = datetime.utcnow()
+        scan.report = {"error": reason}
+        self.scans.save(scan)
+        await self.hub.publish(scan.id, {"status": "failed", "error": reason})