nat-engine 1__py3-none-any.whl

mannf/product/demo.py

@@ -0,0 +1,844 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Demo orchestrator for the ``nat demo`` command.
+
+Populates the NAT server's in-memory state with a curated set of
+microservice scan results, live agent telemetry, and pre-seeded OWASP
+security findings so that every dashboard tab has content the moment
+the browser opens.
+
+Also exposes a standalone ``run_demo()`` entry-point (Issue #140) that
+loads pre-generated sample report data from ``docs/demo/sample-reports/``
+and renders a formatted console summary plus an HTML report.
+
+Issue #58  — ``nat demo`` CLI subcommand
+Issue #59  — Curated demo data & "wow factor" scenarios
+Issue #140 — Demo & Landing Page: Marketing-Ready Reporting Examples
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import pathlib
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Curated demo service topology (Issue #59)
+# ---------------------------------------------------------------------------
+# Service names are recognisable to sales prospects; failure/error/latency
+# values are tuned so the risk heatmap tells a compelling story.
+
+_DEMO_SERVICES_CONFIG: List[Dict[str, Any]] = [
+    {
+        "name": "checkout-api",
+        "failure_rate": 0.18,
+        "error_rate": 0.04,
+        "latency_ms": 25,
+        "latency_jitter_ms": 5,
+    },
+    {
+        # latency spikes → anomaly detection demo
+        "name": "auth-gateway",
+        "failure_rate": 0.12,
+        "error_rate": 0.03,
+        "latency_ms": 35,
+        "latency_jitter_ms": 20,
+    },
+    {
+        "name": "user-profile-svc",
+        "failure_rate": 0.03,
+        "error_rate": 0.01,
+        "latency_ms": 10,
+        "latency_jitter_ms": 5,
+    },
+    {
+        # highest risk → highlighted in risk heatmap
+        "name": "payment-processor",
+        "failure_rate": 0.22,
+        "error_rate": 0.06,
+        "latency_ms": 30,
+        "latency_jitter_ms": 10,
+    },
+    {
+        "name": "inventory-service",
+        "failure_rate": 0.08,
+        "error_rate": 0.02,
+        "latency_ms": 12,
+        "latency_jitter_ms": 5,
+    },
+    {
+        "name": "notification-svc",
+        "failure_rate": 0.04,
+        "error_rate": 0.01,
+        "latency_ms": 8,
+        "latency_jitter_ms": 5,
+    },
+    {
+        "name": "search-api",
+        "failure_rate": 0.05,
+        "error_rate": 0.01,
+        "latency_ms": 15,
+        "latency_jitter_ms": 5,
+    },
+    {
+        "name": "analytics-pipeline",
+        "failure_rate": 0.06,
+        "error_rate": 0.01,
+        "latency_ms": 50,
+        "latency_jitter_ms": 10,
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Curated OWASP security findings (Issue #59)
+# ---------------------------------------------------------------------------
+# Pre-seeded so the Security tab has content immediately on browser open.
+
+_DEMO_SECURITY_FINDINGS: List[Dict[str, Any]] = [
+    {
+        "check_id": "API1",
+        "check_name": "Broken Object Level Authorization",
+        "severity": "critical",
+        "endpoint": "GET /checkout-api/orders/{order_id}",
+        "title": "BOLA — Order enumeration allows cross-user data access",
+        "description": (
+            "The order retrieval endpoint does not verify that the "
+            "requesting user owns the queried order. Any authenticated "
+            "user can access orders belonging to other users by "
+            "incrementing the order_id path parameter."
+        ),
+        "evidence": (
+            "User A successfully retrieved order data owned by User B "
+            "by requesting GET /checkout-api/orders/10042 with User A "
+            "credentials. HTTP 200 with full order payload returned."
+        ),
+        "remediation": (
+            "Add an ownership check in the order retrieval handler: "
+            "verify that order.user_id == authenticated_user.id before "
+            "returning the response. Return HTTP 403 on mismatch."
+        ),
+        "cwe_id": "CWE-639",
+        "confidence": 0.90,
+    },
+    {
+        "check_id": "API2",
+        "check_name": "Broken Authentication",
+        "severity": "critical",
+        "endpoint": "POST /auth-gateway/token",
+        "title": "Expired JWT tokens accepted without expiry validation",
+        "description": (
+            "The auth-gateway accepts bearer tokens that have passed "
+            "their expiry timestamp (exp claim). Expired tokens remain "
+            "valid indefinitely, allowing long-term session hijacking "
+            "after credential theft."
+        ),
+        "evidence": (
+            "HTTP 200 returned for a request authenticated with a JWT "
+            "whose exp claim was set 24 hours in the past. The token "
+            "was accepted and a new session was created."
+        ),
+        "remediation": (
+            "Enforce strict JWT expiry validation on every inbound "
+            "request. Reject tokens with exp < now() with HTTP 401. "
+            "Consider adding a short-lived refresh token flow."
+        ),
+        "cwe_id": "CWE-287",
+        "confidence": 0.92,
+    },
+    {
+        "check_id": "API3",
+        "check_name": "Broken Object Property Level Authorization",
+        "severity": "high",
+        "endpoint": "GET /user-profile-svc/users/{id}",
+        "title": "Sensitive fields exposed to unprivileged users",
+        "description": (
+            "The user profile endpoint returns sensitive internal fields "
+            "(ssn_hash, internal_id, admin_flags) that should only be "
+            "visible to administrators. Standard authenticated users "
+            "receive these fields in the response body."
+        ),
+        "evidence": (
+            "Standard user GET /user-profile-svc/users/42 response body "
+            "contains: internal_id, ssn_hash, admin_flags=false. "
+            "Fields are present regardless of caller role."
+        ),
+        "remediation": (
+            "Apply field-level access control using a role-based field "
+            "filter. Return only permitted fields per caller role. "
+            "Use an allowlist approach rather than a blocklist."
+        ),
+        "cwe_id": "CWE-213",
+        "confidence": 0.85,
+    },
+    {
+        "check_id": "API4",
+        "check_name": "Unrestricted Resource Consumption",
+        "severity": "medium",
+        "endpoint": "POST /payment-processor/charges",
+        "title": "No rate limiting on payment charge endpoint",
+        "description": (
+            "The payment processor charge endpoint has no rate limiting "
+            "or request throttling. An attacker can submit unlimited "
+            "charge attempts in rapid succession, enabling DoS attacks "
+            "and brute-force card validation."
+        ),
+        "evidence": (
+            "500 sequential POST /payment-processor/charges requests "
+            "completed without any 429 Too Many Requests response or "
+            "observable throttling. All requests processed at full speed."
+        ),
+        "remediation": (
+            "Implement per-user rate limiting on the payment endpoint "
+            "(e.g. 10 requests/minute). Return HTTP 429 with "
+            "Retry-After header on breach. Add exponential backoff "
+            "for repeated failures."
+        ),
+        "cwe_id": "CWE-770",
+        "confidence": 0.88,
+    },
+    {
+        "check_id": "API8",
+        "check_name": "Security Misconfiguration",
+        "severity": "high",
+        "endpoint": "GET /analytics-pipeline/health",
+        "title": "Debug mode enabled — stack traces in production responses",
+        "description": (
+            "The analytics-pipeline service has debug mode enabled in "
+            "production. Error responses include full Python stack "
+            "traces, sys.path contents, and environment variable names, "
+            "leaking sensitive infrastructure details."
+        ),
+        "evidence": (
+            "Triggered a 500 error by sending a malformed request. "
+            "Response body contained: full traceback, module paths "
+            "revealing framework versions, and partial env var names."
+        ),
+        "remediation": (
+            "Disable debug mode in production (DEBUG=False). Configure "
+            "a generic error handler that returns sanitised messages "
+            "and logs the full detail server-side only."
+        ),
+        "cwe_id": "CWE-1004",
+        "confidence": 0.95,
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Browser-level security findings (Phase 6.2 — SecurityScenarioGenerator)
+# ---------------------------------------------------------------------------
+# Pre-seeded so the Browser Security tab has content immediately on browser open.
+
+_DEMO_BROWSER_SECURITY_FINDINGS: List[Dict[str, Any]] = [
+    {
+        "check_id": "BROWSER-XSS",
+        "check_name": "Cross-Site Scripting (XSS)",
+        "severity": "high",
+        "endpoint": "BROWSER /login#input[name='username']",
+        "title": "Possible Cross-Site Scripting (XSS) in 'input[name='username']'",
+        "description": (
+            "An XSS payload injected into the username form field was reflected "
+            "in the page DOM without sanitization. An attacker could use this to "
+            "execute arbitrary JavaScript in the context of other users' browsers.\n\n"
+            "Field: input[name='username'], Page: /login, "
+            "Category: A03:2021 — Injection / CWE-79"
+        ),
+        "evidence": (
+            "Payload reflected verbatim: '<script>alert(\\'xss\\')</script>'; "
+            "XSS execution indicator found: '<script>'"
+        ),
+        "remediation": (
+            "Encode all user-supplied data before rendering it in HTML (use "
+            "context-aware output encoding). Implement a strict Content-Security-Policy "
+            "header. Validate and sanitize input server-side."
+        ),
+        "cwe_id": "CWE-79",
+        "confidence": 0.85,
+    },
+    {
+        "check_id": "BROWSER-SQL",
+        "check_name": "SQL Injection",
+        "severity": "high",
+        "endpoint": "BROWSER /search#input[name='q']",
+        "title": "Possible SQL Injection in 'input[name='q']'",
+        "description": (
+            "A SQL injection payload triggered an observable difference in the "
+            "page response. The application may be passing user input directly "
+            "to a database query without parameterization.\n\n"
+            "Field: input[name='q'], Page: /search, "
+            "Category: A03:2021 — Injection / CWE-89"
+        ),
+        "evidence": (
+            "Database error marker: 'SQL syntax'; "
+            "Canary token 'NAT-CANARY-A1B2C3D4E5F6' reflected in DOM/error output"
+        ),
+        "remediation": (
+            "Use parameterized queries or prepared statements for all database access. "
+            "Never concatenate user input into SQL strings. Apply the principle of "
+            "least privilege to database accounts."
+        ),
+        "cwe_id": "CWE-89",
+        "confidence": 0.80,
+    },
+    {
+        "check_id": "BROWSER-PATH_TRAVERSAL",
+        "check_name": "Path Traversal",
+        "severity": "medium",
+        "endpoint": "BROWSER /upload#input[name='filename']",
+        "title": "Possible Path Traversal in 'input[name='filename']'",
+        "description": (
+            "A path traversal sequence was accepted by the form and may have been "
+            "processed by the server, potentially allowing unauthorized file access.\n\n"
+            "Field: input[name='filename'], Page: /upload, "
+            "Category: A01:2021 — Path Traversal / CWE-22"
+        ),
+        "evidence": (
+            "Payload reflected verbatim: '../../etc/passwd'; "
+            "Canary token 'NAT-CANARY-F6E5D4C3B2A1' reflected in DOM/error output"
+        ),
+        "remediation": (
+            "Canonicalize file paths before use and validate they reside within the "
+            "expected directory. Reject paths containing '..' sequences. Use an "
+            "allowlist of permitted file names."
+        ),
+        "cwe_id": "CWE-22",
+        "confidence": 0.70,
+    },
+    {
+        "check_id": "BROWSER-SSRF",
+        "check_name": "Server-Side Request Forgery (SSRF)",
+        "severity": "critical",
+        "endpoint": "BROWSER /profile#input[name='avatar_url']",
+        "title": "Possible Server-Side Request Forgery (SSRF) in 'input[name='avatar_url']'",
+        "description": (
+            "An SSRF payload submitted via a URL-accepting field returned response "
+            "content indicating the server made an outbound request to an internal "
+            "or metadata endpoint.\n\n"
+            "Field: input[name='avatar_url'], Page: /profile, "
+            "Category: A10:2021 — SSRF / CWE-918"
+        ),
+        "evidence": (
+            "SSRF response marker: '169.254.169.254'; "
+            "Canary token 'NAT-CANARY-1A2B3C4D5E6F' reflected in DOM/error output"
+        ),
+        "remediation": (
+            "Validate and allowlist URLs accepted from user input. Block requests to "
+            "loopback, link-local, and metadata service addresses. Use a dedicated "
+            "egress proxy that enforces network-level controls."
+        ),
+        "cwe_id": "CWE-918",
+        "confidence": 0.90,
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Demo scan runner
+# ---------------------------------------------------------------------------
+
+
+async def run_demo_scan(port: int = 8080) -> None:
+    """Populate the server's in-memory state with curated demo data.
+
+    This coroutine is designed to run inside the **same** asyncio event loop
+    as the uvicorn server so that WebSocket telemetry broadcasts reach any
+    connected browser clients in real-time.
+
+    Parameters
+    ----------
+    port:
+        The port the NAT server is listening on (used for base_url labels).
+    """
+    import mannf.product.server as _srv
+    from mannf.core.distributed.system_under_test import (
+        MockDistributedSystem,
+        _ServiceConfig,
+    )
+    from mannf.core.nat_orchestrator import NATOrchestrator
+    from mannf.product.dashboard import telemetry
+
+    now_iso = datetime.now(timezone.utc).isoformat()
+    base_url = f"http://localhost:{port}"
+
+    # ----------------------------------------------------------------
+    # 1. Register a functional scan entry (History + Overview tabs)
+    # ----------------------------------------------------------------
+    scan_id = str(uuid.uuid4())
+    _srv._scans[scan_id] = {
+        "scan_id": scan_id,
+        "status": _srv.ScanStatus.RUNNING,
+        "created_at": now_iso,
+        "spec_name": "demo-microservices",
+        "base_url": base_url,
+        "summary": None,
+        "results": [],
+        "error": None,
+        "completed_at": None,
+    }
+
+    # ----------------------------------------------------------------
+    # 2. Pre-seed OWASP security findings (Security tab)
+    # ----------------------------------------------------------------
+    sec_scan_id = str(uuid.uuid4())
+    _srv._security_scans[sec_scan_id] = {
+        "scan_id": sec_scan_id,
+        "status": "completed",
+        "created_at": now_iso,
+        "target_url": base_url,
+        "report": {
+            "scan_id": sec_scan_id,
+            "timestamp": now_iso,
+            "target_url": base_url,
+            "total_endpoints_scanned": len(_DEMO_SERVICES_CONFIG),
+            "findings": _DEMO_SECURITY_FINDINGS,
+            "summary": {
+                "total_findings": len(_DEMO_SECURITY_FINDINGS),
+                "critical": sum(
+                    1 for f in _DEMO_SECURITY_FINDINGS if f["severity"] == "critical"
+                ),
+                "high": sum(
+                    1 for f in _DEMO_SECURITY_FINDINGS if f["severity"] == "high"
+                ),
+                "medium": sum(
+                    1 for f in _DEMO_SECURITY_FINDINGS if f["severity"] == "medium"
+                ),
+                "low": 0,
+                "info": 0,
+            },
+            "belief_guided": True,
+            "prioritization": [],
+        },
+        "error": None,
+        "completed_at": now_iso,
+    }
+
+    # ----------------------------------------------------------------
+    # 3. Build demo MockDistributedSystem with curated services
+    # ----------------------------------------------------------------
+    demo_services = [_ServiceConfig(**cfg) for cfg in _DEMO_SERVICES_CONFIG]
+    sut = MockDistributedSystem(services=demo_services, seed=42)
+
+    # ----------------------------------------------------------------
+    # 4. Create NATOrchestrator wired to server's shared data layer
+    # ----------------------------------------------------------------
+    risk_scorer = _srv._get_risk_scorer()
+    anomaly_detector = _srv._get_anomaly_detector()
+
+    orch = NATOrchestrator(
+        sut,
+        num_planners=2,
+        num_executors=4,
+        num_analyzers=2,
+        max_contracts=120,
+        suite_name="NAT Demo — Microservices Platform",
+        log_interval=20,
+        bid_timeout_s=0.03,
+        anomaly_detector=anomaly_detector,
+    )
+
+    # Broadcast initial agent state so the Agents tab populates before
+    # the scan completes (first snapshot; beliefs start at 0.5 priors).
+    all_agents = (
+        orch._planners + orch._executors + orch._analyzers + [orch._coordinator]
+    )
+    for agent in all_agents:
+        await telemetry.broadcast_agent_state(agent)
+
+    # ----------------------------------------------------------------
+    # 5. Run the orchestrator — agents collaborate via ECNP, results
+    #    flow through the shared anomaly detector and risk scorer.
+    # ----------------------------------------------------------------
+    logger.info("Demo scan %s: starting NATOrchestrator", scan_id)
+    suite = await orch.run()
+
+    # ----------------------------------------------------------------
+    # 6. Broadcast final agent states (beliefs updated after full run)
+    # ----------------------------------------------------------------
+    for agent in all_agents:
+        await telemetry.broadcast_agent_state(agent)
+
+    # Also feed orchestrator's risk scorer results into the server's
+    # shared risk scorer so the risk heatmap is populated.
+    for entry in orch.get_risk_report():
+        endpoint = entry.get("endpoint", "")
+        risk_score = entry.get("risk_score", 0.0)
+        if endpoint:
+            # Replay synthetic observations to seed the server scorer
+            _srv._get_risk_scorer().record(
+                endpoint,
+                _make_synthetic_result(endpoint, risk_score),
+            )
+
+    # ----------------------------------------------------------------
+    # 7. Build raw results list and update scan to COMPLETED
+    # ----------------------------------------------------------------
+    tc_by_id = {tc.id: tc for tc in suite.cases}
+    raw_results = []
+    for result in suite.results:
+        tc = tc_by_id.get(result.test_case_id)
+        target = tc.target if tc is not None else "unknown"
+        raw_results.append(
+            {
+                "test_id": result.test_case_id,
+                "target": target,
+                "passed": result.passed,
+                "execution_time_ms": result.execution_time_ms,
+                "error": result.error,
+                "actual_output": result.actual_output,
+            }
+        )
+
+    s = suite.summary()
+    completed_at = datetime.now(timezone.utc).isoformat()
+    _srv._scans[scan_id].update(
+        {
+            "status": _srv.ScanStatus.COMPLETED,
+            "completed_at": completed_at,
+            "summary": s,
+            "results": raw_results,
+        }
+    )
+
+    logger.info(
+        "Demo scan %s complete: total=%d passed=%d failed=%d",
+        scan_id,
+        s["total"],
+        s["passed"],
+        s["failed"],
+    )
+
+    # Broadcast scan completion to any connected WebSocket clients
+    from mannf.product.dashboard.app import manager as _ws_mgr
+
+    await _ws_mgr.broadcast(
+        {
+            "type": "scan_update",
+            "data": {
+                "scan_id": scan_id,
+                "status": _srv.ScanStatus.COMPLETED,
+                "total": s.get("total", 0),
+                "passed": s.get("passed", 0),
+                "failed": s.get("failed", 0),
+            },
+        }
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_synthetic_result(endpoint: str, risk_score: float) -> Any:
+    """Create a minimal :class:`~mannf.core.testing.models.TestResult` that
+    encodes the given *risk_score* as a passed/failed outcome for seeding
+    the server's shared :class:`~mannf.core.prioritization.risk_scorer.RiskScorer`.
+    """
+    from mannf.core.testing.models import TestResult
+
+    # risk_score ≥ 0.5 → treat as a failure signal
+    passed = risk_score < 0.5
+    return TestResult(
+        test_case_id=str(uuid.uuid4()),
+        passed=passed,
+        execution_time_ms=10.0,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Standalone demo runner (Issue #140)
+# ---------------------------------------------------------------------------
+
+#: Directory that contains pre-generated sample reports.
+_SAMPLE_REPORTS_DIR: pathlib.Path = (
+    pathlib.Path(__file__).parent.parent.parent.parent  # repo root
+    / "docs"
+    / "demo"
+    / "sample-reports"
+)
+
+#: HTML report template path.
+_HTML_TEMPLATE_PATH: pathlib.Path = (
+    pathlib.Path(__file__).parent.parent.parent.parent  # repo root
+    / "docs"
+    / "demo"
+    / "report-template.html"
+)
+
+
+def _load_sample_report(filename: str) -> Optional[Dict[str, Any]]:
+    """Load a single JSON sample report file.  Returns *None* on failure."""
+    path = _SAMPLE_REPORTS_DIR / filename
+    try:
+        with path.open(encoding="utf-8") as fh:
+            return json.load(fh)
+    except FileNotFoundError:
+        logger.warning("Sample report not found: %s", path)
+        return None
+    except json.JSONDecodeError as exc:
+        logger.warning("Failed to parse %s: %s", path, exc)
+        return None
+
+
+def _severity_counts(findings: List[Dict[str, Any]]) -> Dict[str, int]:
+    """Return a dict of severity → count for a list of security findings."""
+    counts: Dict[str, int] = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+    for f in findings:
+        sev = str(f.get("severity", "")).lower()
+        if sev in counts:
+            counts[sev] += 1
+    return counts
+
+
+def _print_section(title: str, *, width: int = 70) -> None:
+    """Print a formatted section separator to stdout."""
+    bar = "─" * width
+    print(f"\n{bar}")
+    print(f"  {title}")
+    print(bar)
+
+
+def _print_kv(key: str, value: str, indent: int = 4) -> None:
+    pad = " " * indent
+    print(f"{pad}{key:<30} {value}")
+
+
+def run_demo(
+    mode: str = "quick",
+    output_html: Optional[str] = None,
+) -> None:
+    """Load pre-generated sample report data and print a formatted demo.
+
+    Parameters
+    ----------
+    mode:
+        One of:
+
+        * ``"quick"`` – Loads data and prints results instantly (default).
+        * ``"simulated"`` – Adds realistic delays between phases to mimic a
+          live scan in progress (useful for screen recordings).
+        * ``"interactive"`` – Pauses between each phase so a presenter can
+          narrate before pressing Enter to continue.
+
+    output_html:
+        Optional file path.  When provided the standalone HTML report
+        template is copied to this path (ready to open in a browser or
+        send to a prospect).  If *None*, no HTML file is written.
+    """
+    delays: Dict[str, float]
+    if mode == "simulated":
+        delays = {
+            "header": 0.5,
+            "security": 2.0,
+            "functional": 1.5,
+            "visual": 1.0,
+            "accessibility": 1.2,
+            "performance": 1.0,
+            "summary": 0.8,
+        }
+    else:
+        delays = {k: 0.0 for k in ("header", "security", "functional", "visual", "accessibility", "performance", "summary")}
+
+    def _pause(phase: str) -> None:
+        delay = delays.get(phase, 0.0)
+        if mode == "interactive":
+            input(f"\n  ↵  Press Enter to continue to {phase}…")
+        elif delay > 0:
+            time.sleep(delay)
+
+    # ------------------------------------------------------------------
+    # Header
+    # ------------------------------------------------------------------
+    _pause("header")
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    print("\n" + "═" * 70)
+    print("  NAT — Neural Agent Testing Platform")
+    print("  Demo Report Viewer  ·  Issue #140")
+    print(f"  {now}")
+    print("═" * 70)
+    print("  Target: https://www.demo-store.example.com")
+    print("  Suite:  Full Platform Audit")
+    print("  Mode:   " + mode)
+
+    # ------------------------------------------------------------------
+    # Load all reports
+    # ------------------------------------------------------------------
+    unified = _load_sample_report("unified-report.json") or {}
+    security = _load_sample_report("security-scan-report.json") or {}
+    functional = _load_sample_report("functional-test-report.json") or {}
+    visual = _load_sample_report("visual-regression-report.json") or {}
+    a11y = _load_sample_report("accessibility-report.json") or {}
+    performance = _load_sample_report("performance-report.json") or {}
+
+    # ------------------------------------------------------------------
+    # Executive summary
+    # ------------------------------------------------------------------
+    health = unified.get("overall_health_score", "N/A")
+    grade = unified.get("health_grade", "?")
+    _print_section(f"📋 EXECUTIVE SUMMARY   Health Score: {health}/100  ({grade})")
+    exec_sum = unified.get("executive_summary", {})
+    headline = exec_sum.get("headline", "")
+    if headline:
+        # Word-wrap at ~64 chars
+        words = headline.split()
+        line = "    "
+        for word in words:
+            if len(line) + len(word) + 1 > 68:
+                print(line)
+                line = "    " + word + " "
+            else:
+                line += word + " "
+        if line.strip():
+            print(line)
+    print()
+    for action in exec_sum.get("critical_actions", []):
+        print(f"  ⚠  {action}")
+
+    # ------------------------------------------------------------------
+    # Security
+    # ------------------------------------------------------------------
+    _pause("security")
+    sec_sum = security.get("summary", {})
+    _print_section(
+        "🔒 SECURITY SCAN"
+        f"   {sec_sum.get('total_findings', 0)} findings  ·  "
+        f"Risk score: {sec_sum.get('risk_score', 'N/A')}"
+    )
+    _print_kv("Endpoints scanned:", str(security.get("total_endpoints_scanned", "?")))
+    _print_kv("Scan duration:", f"{security.get('scan_duration_seconds', '?')}s")
+    _print_kv("Critical:", str(sec_sum.get("critical", 0)))
+    _print_kv("High:", str(sec_sum.get("high", 0)))
+    _print_kv("Medium:", str(sec_sum.get("medium", 0)))
+    _print_kv("Low:", str(sec_sum.get("low", 0)))
+    print()
+    for finding in security.get("findings", [])[:5]:
+        sev = finding.get("severity", "?").upper()
+        title = finding.get("title", "")
+        ep = finding.get("affected_endpoint", "")
+        cvss = finding.get("cvss_score", "")
+        print(f"    [{sev:8s}]  CVSS {cvss:4}  {title}")
+        print(f"             {ep}")
+    remaining = len(security.get("findings", [])) - 5
+    if remaining > 0:
+        print(f"    … and {remaining} more findings (see security-scan-report.json)")
+
+    # ------------------------------------------------------------------
+    # Functional
+    # ------------------------------------------------------------------
+    _pause("functional")
+    func_sum = functional.get("summary", {})
+    total = func_sum.get("total", 0)
+    passed = func_sum.get("passed", 0)
+    failed = func_sum.get("failed", 0)
+    skipped = func_sum.get("skipped", 0)
+    pass_rate = func_sum.get("pass_rate", 0)
+    _print_section(
+        f"✅ FUNCTIONAL TESTS"
+        f"   {passed}/{total} passed  ·  {failed} failed  ·  {skipped} skipped"
+    )
+    _print_kv("Pass rate:", f"{pass_rate * 100:.1f}%")
+    _print_kv("Duration:", f"{functional.get('duration_seconds', '?')}s")
+    print()
+    failed_tests = [t for t in functional.get("tests", []) if t.get("status") == "failed"]
+    for t in failed_tests:
+        print(f"    [FAIL]  {t['id']}  {t['name']}")
+        fail = t.get("failure", {})
+        if fail.get("reason"):
+            print(f"            {fail['reason']}")
+
+    # ------------------------------------------------------------------
+    # Visual regression
+    # ------------------------------------------------------------------
+    _pause("visual")
+    vis_sum = visual.get("summary", {})
+    _print_section(
+        f"🖼  VISUAL REGRESSION"
+        f"   {vis_sum.get('pages_compared', 0)} pages  ·  "
+        f"{vis_sum.get('diffs_detected', 0)} diffs detected"
+    )
+    for page in visual.get("pages", []):
+        if page.get("status") == "diff_detected":
+            pct = page.get("diff_percent", 0)
+            print(f"    [DIFF]  {page['name']}  ({pct}% pixel diff)")
+            for region in page.get("diff_regions", []):
+                print(f"            · {region['label']}: {region['description'][:60]}…")
+
+    # ------------------------------------------------------------------
+    # Accessibility
+    # ------------------------------------------------------------------
+    _pause("accessibility")
+    a11y_sum = a11y.get("summary", {})
+    _print_section(
+        f"♿ ACCESSIBILITY  (WCAG {a11y.get('wcag_version', '2.1')} {a11y.get('wcag_level', 'AA')})"
+        f"   Score: {a11y.get('overall_score', '?')}%"
+    )
+    _print_kv("Violations:", str(a11y_sum.get("critical", 0)))
+    _print_kv("Warnings:", str(a11y_sum.get("warnings", 0)))
+    _print_kv("Passed checks:", str(a11y_sum.get("passed_checks", 0)))
+    print()
+    for v in a11y.get("violations", []):
+        print(f"    [VIOLATION]  WCAG {v['wcag_criterion']}  {v['issue']}")
+        print(f"                 {v['affected_page']}")
+
+    # ------------------------------------------------------------------
+    # Performance
+    # ------------------------------------------------------------------
+    _pause("performance")
+    perf_sum = performance.get("summary", {})
+    _print_section(
+        f"⚡ PERFORMANCE"
+        f"   Overall: {performance.get('overall_performance_score', '?')}/100"
+    )
+    _print_kv("Pages tested:", str(performance.get("pages", []).__len__()))
+    _print_kv("Avg LCP:", f"{perf_sum.get('avg_lcp_ms', '?')} ms")
+    _print_kv("Avg CLS:", str(perf_sum.get("avg_cls", "?")))
+    _print_kv("Avg TTFB:", f"{perf_sum.get('avg_ttfb_ms', '?')} ms")
+    print()
+    for page in performance.get("pages", []):
+        score = page.get("performance_score", 0)
+        grade_char = "✅" if score >= 85 else ("⚠️" if score >= 70 else "❌")
+        print(f"    {grade_char}  {score:3d}/100  {page['page']}")
+
+    # ------------------------------------------------------------------
+    # Final summary
+    # ------------------------------------------------------------------
+    _pause("summary")
+    _print_section("🔗 CROSS-CUTTING INSIGHTS")
+    for insight in unified.get("cross_cutting_insights", []):
+        sev = insight.get("severity", "info").upper()
+        print(f"    [{sev}]  {insight['insight'][:72]}…")
+
+    print()
+    print("═" * 70)
+    print("  ✅  Demo complete.  Full data in docs/demo/sample-reports/")
+    if output_html:
+        print(f"  📄  HTML report → {output_html}")
+    print("═" * 70 + "\n")
+
+    # ------------------------------------------------------------------
+    # HTML output
+    # ------------------------------------------------------------------
+    if output_html:
+        _write_html_report(output_html)
+
+
+def _write_html_report(dest: str) -> None:
+    """Copy the standalone HTML report template to *dest*."""
+    import shutil
+
+    dest_path = pathlib.Path(dest)
+    try:
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(_HTML_TEMPLATE_PATH, dest_path)
+        logger.info("HTML report written to %s", dest_path)
+    except OSError as exc:
+        logger.warning("Could not write HTML report to %s: %s", dest_path, exc)