patchi 0.7.5__py3-none-any.whl

patchi/core/security/cdn_cache_agent.py

@@ -0,0 +1,357 @@
+"""
+CDNCacheSecurityAgent — CDN/edge cache security issues.
+
+Detects CDN-related security issues:
+- Cache poisoning via unvalidated headers
+- Origin bypass (missing origin access controls)
+- Cache-key normalization flaws
+- Missing cache-control directives
+- CDN configuration misconfigurations (CloudFront, Fastly, etc.)
+
+Uses static file analysis and optional external tools (curl).
+Does NOT call AI.
+Does NOT write to disk.
+Does NOT touch the queue.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ..agents.base import (
+    AgentDomain,
+    AgentGroup,
+    AgentInput,
+    AgentResult,
+    AgentStatus,
+    BaseAgent,
+    Finding,
+    Severity,
+    make_finding,
+    register,
+    safe_rglob,
+)
+from ..brain.trace_log import trace_agent
+
+_SOURCE_EXTENSIONS = {
+    "*.py",
+    "*.js",
+    "*.jsx",
+    "*.ts",
+    "*.tsx",
+    "*.java",
+    "*.php",
+    "*.rb",
+    "*.go",
+    "*.rs",
+    "*.cs",
+    "*.yaml",
+    "*.yml",
+    "*.toml",
+    "*.json",
+    "*.conf",
+    "*.cfg",
+    "*.nginx",
+}
+
+_CDN_CONFIG_NAMES = {
+    "cloudfront.yaml",
+    "cloudfront.yml",
+    "cloudfront.json",
+    "fastly.toml",
+    "fastly.yaml",
+    "fastly.yml",
+    "cloudflare.toml",
+    "cloudflare.yaml",
+    "cloudflare.yml",
+    "akamai.json",
+    "akamai.yaml",
+    "cloudfront-properties.json",
+}
+
+_CACHE_CONTROL_PATTERNS = [
+    re.compile(r"cache-control", re.IGNORECASE),
+    re.compile(r"surrogate-control", re.IGNORECASE),
+    re.compile(r"x-cache", re.IGNORECASE),
+    re.compile(r"cdn-cache", re.IGNORECASE),
+]
+
+_ORIGIN_BYPASS_PATTERNS = [
+    (re.compile(r"X-Forwarded-Host", re.IGNORECASE), "X-Forwarded-Host header manipulation"),
+    (re.compile(r"X-Original-URL", re.IGNORECASE), "X-Original-URL header injection"),
+    (re.compile(r"X-Rewrite-URL", re.IGNORECASE), "X-Rewrite-URL header injection"),
+    (re.compile(r"X-Real-IP", re.IGNORECASE), "X-Real-IP header spoofing"),
+]
+
+_CACHE_KEY_INJECTION_PATTERNS = [
+    (
+        re.compile(
+            r"(?:cache.?key|cacheKey|cache_key)\s*[=:]\s*.*\+|f['\"].*\{.*\}", re.IGNORECASE
+        ),
+        "Dynamic cache key construction via string concatenation",
+    ),
+    (re.compile(r"Vary\s*:\s*\*", re.IGNORECASE), "Wildcard Vary header may cause cache poisoning"),
+]
+
+
+_log = logging.getLogger("patchi.security.cdn_cache_agent")
+
+
+@register
+class CDNCacheSecurityAgent(BaseAgent):
+    """Agent for detecting CDN and edge cache security issues."""
+
+    group = AgentGroup.SECURITY
+    domain = AgentDomain.SECURITY
+    name = "CDNCacheSecurityAgent"
+    description = "CDN/edge cache security: cache poisoning, origin bypass, cache-key normalization"
+
+    def _run(self, inp: AgentInput, result: AgentResult) -> None:
+        findings: list[Finding] = []
+        files_scanned = 0
+
+        with trace_agent(self.name, inp.root) as trace:
+            # ── Static analysis ────────────────────────────────────────────
+            findings.extend(self._scan_cdn_configs(inp))
+            findings.extend(self._scan_cache_headers(inp))
+            findings.extend(self._scan_origin_bypass(inp))
+            findings.extend(self._scan_cache_key_issues(inp))
+
+            for pattern in _SOURCE_EXTENSIONS:
+                for fp in safe_rglob(inp.root, pattern):
+                    if fp.is_file():
+                        files_scanned += 1
+                        findings.extend(self._scan_file(fp, inp.root))
+
+            # ── External tool: curl ────────────────────────────────────────
+            if shutil.which("curl"):
+                findings.extend(self._run_curl_check(inp))
+
+            trace.findings = len(findings)
+            trace.files_scanned = files_scanned
+
+        result.status = AgentStatus.SUCCEEDED
+        result.findings = findings
+        result.data.update(
+            {
+                "cdn_findings": len(findings),
+                "curl_available": shutil.which("curl") is not None,
+            }
+        )
+        return
+
+    # ── CDN config file scan ───────────────────────────────────────────────
+
+    def _scan_cdn_configs(self, inp: AgentInput) -> list[Finding]:
+        findings: list[Finding] = []
+        for fp in safe_rglob(inp.root, "*"):
+            if fp.name in _CDN_CONFIG_NAMES:
+                rel = fp.relative_to(inp.root).as_posix()
+                try:
+                    content = fp.read_text(encoding="utf-8", errors="replace")
+                    if (
+                        "OriginAccessControl" not in content
+                        and "origin_access" not in content.lower()
+                    ):
+                        findings.append(
+                            make_finding(
+                                severity=Severity.HIGH,
+                                file=rel,
+                                line_start=0,
+                                title="CDN-01: Missing Origin Access Control",
+                                description=(
+                                    "CDN configuration file found without origin access control "
+                                    "settings. This may allow direct origin bypass."
+                                ),
+                                evidence=content[:200],
+                                suggestion="Enable Origin Access Identity (CloudFront) or Shield Origin (Fastly).",
+                            )
+                        )
+                    if "signed" not in content.lower() and "token" not in content.lower():
+                        findings.append(
+                            make_finding(
+                                severity=Severity.MEDIUM,
+                                file=rel,
+                                line_start=0,
+                                title="CDN-02: No Signed URLs/Cookies Configured",
+                                description="CDN distribution has no signed URL or signed cookie configuration.",
+                                suggestion="Enable signed URLs or signed cookies for authenticated content.",
+                            )
+                        )
+                except Exception as e:
+                    _log.warning("CDNCacheSecurityAgent._scan_cdn_configs failed: %s", e)
+        return findings
+
+    # ── Cache header analysis ──────────────────────────────────────────────
+
+    def _scan_cache_headers(self, inp: AgentInput) -> list[Finding]:
+        findings: list[Finding] = []
+        header_patterns = [
+            ("*.conf", ["nginx", "apache", "httpd"]),
+            ("*.cfg", ["nginx", "apache"]),
+            ("*.yaml", ["proxy", "upstream", "cache"]),
+            ("*.yml", ["proxy", "upstream", "cache"]),
+        ]
+        for pattern, _context_words in header_patterns:
+            for fp in safe_rglob(inp.root, pattern):
+                if not fp.is_file():
+                    continue
+                rel = fp.relative_to(inp.root).as_posix()
+                try:
+                    content = fp.read_text(encoding="utf-8", errors="replace")
+                    lines = content.splitlines()
+                    for i, line in enumerate(lines, 1):
+                        for rx in _CACHE_CONTROL_PATTERNS:
+                            if rx.search(line):
+                                if "no-store" not in line.lower() and "private" not in line.lower():
+                                    findings.append(
+                                        make_finding(
+                                            severity=Severity.MEDIUM,
+                                            file=rel,
+                                            line_start=i,
+                                            title="CDN-03: Cache-Control May Allow Sensitive Data Caching",
+                                            description=(
+                                                "Cache header found without no-store/private directive. "
+                                                "Sensitive data may be cached at the edge."
+                                            ),
+                                            evidence=line.strip(),
+                                            suggestion="Add 'no-store' or 'private' for sensitive endpoints.",
+                                        )
+                                    )
+                                break
+                except Exception as e:
+                    _log.warning("CDNCacheSecurityAgent._scan_cache_headers failed: %s", e)
+        return findings
+
+    # ── Origin bypass patterns ─────────────────────────────────────────────
+
+    def _scan_origin_bypass(self, inp: AgentInput) -> list[Finding]:
+        findings: list[Finding] = []
+        for pattern in ("*.py", "*.js", "*.ts", "*.java", "*.go", "*.rb", "*.php"):
+            for fp in safe_rglob(inp.root, pattern):
+                if not fp.is_file():
+                    continue
+                rel = fp.relative_to(inp.root).as_posix()
+                try:
+                    content = fp.read_text(encoding="utf-8", errors="replace")
+                    lines = content.splitlines()
+                    for i, line in enumerate(lines, 1):
+                        for rx, desc in _ORIGIN_BYPASS_PATTERNS:
+                            if rx.search(line) and "test" not in rel.lower():
+                                findings.append(
+                                    make_finding(
+                                        severity=Severity.HIGH,
+                                        file=rel,
+                                        line_start=i,
+                                        title="CDN-04: Origin Bypass via Header Injection",
+                                        description=desc,
+                                        evidence=line.strip(),
+                                        suggestion="Validate and strip CDN-injected headers at the origin.",
+                                    )
+                                )
+                except Exception as e:
+                    _log.warning("CDNCacheSecurityAgent._scan_origin_bypass failed: %s", e)
+        return findings
+
+    # ── Cache-key normalization ────────────────────────────────────────────
+
+    def _scan_cache_key_issues(self, inp: AgentInput) -> list[Finding]:
+        findings: list[Finding] = []
+        for pattern in ("*.py", "*.js", "*.ts", "*.go", "*.rb", "*.php", "*.conf"):
+            for fp in safe_rglob(inp.root, pattern):
+                if not fp.is_file():
+                    continue
+                rel = fp.relative_to(inp.root).as_posix()
+                try:
+                    content = fp.read_text(encoding="utf-8", errors="replace")
+                    lines = content.splitlines()
+                    for i, line in enumerate(lines, 1):
+                        for rx, desc in _CACHE_KEY_INJECTION_PATTERNS:
+                            if rx.search(line):
+                                findings.append(
+                                    make_finding(
+                                        severity=Severity.MEDIUM,
+                                        file=rel,
+                                        line_start=i,
+                                        title="CDN-05: Cache Key Injection Risk",
+                                        description=desc,
+                                        evidence=line.strip(),
+                                        suggestion="Normalize cache keys to prevent injection via headers.",
+                                    )
+                                )
+                except Exception as e:
+                    _log.warning("CDNCacheSecurityAgent._scan_cache_key_issues failed: %s", e)
+        return findings
+
+    # ── General source file scan ───────────────────────────────────────────
+
+    def _scan_file(self, fp: Path, root: Path) -> list[Finding]:
+        findings: list[Finding] = []
+        rel = fp.relative_to(root).as_posix()
+        try:
+            content = fp.read_text(encoding="utf-8", errors="replace")
+            # CDN-specific secrets
+            secret_patterns = [
+                (
+                    re.compile(
+                        r"(?:cloudfront|fastly|cloudflare)[_-]?(?:key|token|secret)\s*[:=]\s*['\"][^'\"]{8,}['\"]",
+                        re.IGNORECASE,
+                    ),
+                    "CDN-06: Hardcoded CDN Credential",
+                ),
+            ]
+            lines = content.splitlines()
+            for i, line in enumerate(lines, 1):
+                for rx, title in secret_patterns:
+                    if rx.search(line):
+                        findings.append(
+                            make_finding(
+                                severity=Severity.CRITICAL,
+                                file=rel,
+                                line_start=i,
+                                title=title,
+                                description="Hardcoded CDN credential found in source code.",
+                                evidence=line.strip()[:120],
+                                suggestion="Move CDN credentials to environment variables or a secrets manager.",
+                            )
+                        )
+        except Exception as e:
+            _log.warning("CDNCacheSecurityAgent._scan_file failed: %s", e)
+        return findings
+
+    # ── External tool: curl ────────────────────────────────────────────────
+
+    def _run_curl_check(self, inp: AgentInput) -> list[Finding]:
+        """Use curl to probe cache headers if a URL is provided in config."""
+        findings: list[Finding] = []
+        url = inp.config.get("cdn_probe_url")
+        if not url or not isinstance(url, str):
+            return findings
+
+        try:
+            proc = subprocess.run(
+                ["curl", "-sI", "-m", "10", url],
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+            if proc.returncode == 0:
+                headers_lower = proc.stdout.lower()
+                if "x-cache:" in headers_lower and "hit" in headers_lower:
+                    findings.append(
+                        make_finding(
+                            severity=Severity.LOW,
+                            file="(cdn_probe)",
+                            line_start=0,
+                            title="CDN-03: Cache Hit Detected on Probe URL",
+                            description="The probed URL returned a cache HIT. Verify sensitive data is not cached.",
+                            evidence=proc.stdout[:300],
+                        )
+                    )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            pass
+        return findings

patchi/core/security/chain_analyzer.py

@@ -0,0 +1,321 @@
+"""
+Exploit Chain Engine — turns isolated findings into attack narratives.
+
+A SQL injection in a rarely-hit endpoint is Medium. The same SQL injection
+reachable without authentication, chained past a missing rate limit into an
+unencrypted admin cookie, is Critical. Static scanners see the pieces; this
+module assembles the pieces into the story an attacker would tell.
+
+How it works (deterministic, zero AI, bounded):
+
+1. Each Finding becomes a node classified as an ENTRY (exposes attack
+   surface: missing auth, open CORS, debug mode...), an EXPLOIT (injection,
+   XSS, SSRF...), or an IMPACT amplifier (secrets, weak crypto, sensitive
+   data exposure).
+2. An edge A -> B ("A enables B") is added when the pair matches a chain
+   rule AND the findings are co-located (same file) or import-connected
+   (B's module imports A's module).
+3. A chain is any path entry -> ... -> impact of length >= 2.
+4. Chains are scored by exploitability and sorted worst-first.
+
+Severity escalation: a chain's severity is at least HIGH when it links two
+or more confirmed findings — the compound condition is what makes it
+dangerous, even if each piece alone looked Medium.
+
+No AI calls. No network. Pure graph analysis over the findings you already have.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+_log = logging.getLogger("patchi.security.chain_analyzer")
+
+
+class NodeRole(StrEnum):
+    """What role a finding plays in an attack chain."""
+
+    ENTRY = "entry"  # opens the door
+    EXPLOIT = "exploit"  # the actual attack step
+    IMPACT = "impact"  # what the attacker walks away with
+    STANDALONE = "standalone"  # not part of any known chain pattern
+
+
+# ── Chain rules ────────────────────────────────────────────────────────────────
+# Each rule: (source_type_pattern, target_type_pattern, edge_label).
+# Type patterns are matched with substring semantics against finding.type so
+# "sqli", "sql_injection", "injection_sql" all match "sql".
+
+_CHAIN_RULES: tuple[tuple[str, str, str], ...] = (
+    # Entry -> exploit edges
+    ("auth", "inject", "unauthenticated input reaches injector"),
+    ("auth", "xss", "unauthenticated input reaches XSS sink"),
+    ("auth", "ssrf", "unauthenticated request forges SSRF"),
+    ("auth", "idor", "no auth boundary protects object access"),
+    ("open_redirect", "xss", "redirect target smuggles script"),
+    ("cors", "xss", "permissive CORS lets attacker read XSS payload"),
+    ("debug", "inject", "debug mode leaks internals that shape payloads"),
+    ("rate_limit", "brute", "no throttle permits unlimited attempts"),
+    ("rate_limit", "inject", "no throttle permits payload fuzzing"),
+    # Exploit -> impact edges
+    ("inject", "secret", "injection exfiltrates stored secrets"),
+    ("inject", "sensitive_data", "injection dumps sensitive tables"),
+    ("ssrf", "secret", "SSRF reaches internal metadata/credential service"),
+    ("idor", "sensitive_data", "object access crosses ownership boundary"),
+    ("xss", "session", "script lifts session cookies/tokens"),
+    ("xss", "secret", "script scrapes secrets rendered into DOM"),
+    ("deserialization", "rce", "deserialization gadget yields code execution"),
+    ("command_injection", "secret", "command execution reads env/key material"),
+    ("path_traversal", "secret", "traversal reads key/config files"),
+    ("weak_crypto", "session", "forgeable tokens defeat session integrity"),
+    ("hardcoded_secret", "secret", "committed key grants direct access"),
+    # Amplifier edges
+    ("jwt", "auth", "token flaw defeats the auth layer itself"),
+    ("csrf", "state_change", "forged request drives privileged mutation"),
+)
+
+
+def _matches(pattern: str, finding_type: str) -> bool:
+    return pattern in finding_type.lower()
+
+
+def classify(finding_type: str) -> NodeRole:
+    """Classify a finding type into its chain role."""
+    t = finding_type.lower()
+    if any(k in t for k in ("auth", "cors", "debug", "rate_limit", "redirect", "open")):
+        return NodeRole.ENTRY
+    if any(
+        k in t
+        for k in (
+            "inject",
+            "xss",
+            "ssrf",
+            "idor",
+            "deserial",
+            "traversal",
+            "rce",
+            "sqli",
+            "xxe",
+        )
+    ):
+        return NodeRole.EXPLOIT
+    if any(
+        k in t
+        for k in (
+            "secret",
+            "crypto",
+            "sensitive",
+            "session",
+            "jwt",
+            "hardcoded",
+            "password",
+            "key",
+        )
+    ):
+        return NodeRole.IMPACT
+    return NodeRole.STANDALONE
+
+
+@dataclass
+class ChainNode:
+    """One finding participating in a chain."""
+
+    finding: Any  # patchi.core.agents.base.Finding
+    role: NodeRole
+
+    @property
+    def key(self) -> tuple:
+        f = self.finding
+        return (f.file, f.line, f.type)
+
+    @property
+    def severity(self) -> str:
+        return self.finding.severity.value
+
+
+@dataclass
+class Chain:
+    """An ordered attack path: entry -> exploits -> impact."""
+
+    nodes: list[ChainNode]
+    edges: list[str] = field(default_factory=list)
+
+    @property
+    def length(self) -> int:
+        return len(self.nodes)
+
+    @property
+    def severity(self) -> str:
+        """Escalated severity: multi-step chains are at least HIGH."""
+        order = ["info", "low", "medium", "high", "critical"]
+        worst = max(
+            (order.index(n.severity) for n in self.nodes if n.severity in order),
+            default=0,
+        )
+        if self.length >= 2:
+            worst = max(worst, order.index("high"))
+        if self.length >= 3:
+            worst = max(worst, order.index("critical"))
+        return order[worst]
+
+    @property
+    def score(self) -> float:
+        """Exploitability score 0-100: depth × severity × confirmation spread."""
+        sev_weight = {"info": 5, "low": 15, "medium": 35, "high": 70, "critical": 90}
+        base = max((sev_weight.get(n.severity, 20) for n in self.nodes), default=20)
+        depth_bonus = min((self.length - 1) * 8, 24)
+        agents = {n.finding.agent for n in self.nodes}
+        confirm_bonus = min(len(agents) * 4, 12)
+        return min(base + depth_bonus + confirm_bonus, 100)
+
+    @property
+    def narrative(self) -> str:
+        """Human-readable attack story assembled from the edge labels."""
+        parts = [f"[{n.finding.type}] {n.finding.file}:{n.finding.line}" for n in self.nodes]
+        story = " -> ".join(parts)
+        if self.edges:
+            story += "  |  " + "; ".join(self.edges)
+        return story
+
+    def to_dict(self) -> dict:
+        return {
+            "severity": self.severity,
+            "score": round(self.score, 1),
+            "length": self.length,
+            "narrative": self.narrative,
+            "steps": [
+                {
+                    "role": n.role.value,
+                    "type": n.finding.type,
+                    "file": n.finding.file,
+                    "line": n.finding.line,
+                    "severity": n.severity,
+                    "agent": n.finding.agent,
+                }
+                for n in self.nodes
+            ],
+        }
+
+
+class ChainAnalyzer:
+    """Builds exploit chains from a set of findings."""
+
+    def __init__(
+        self,
+        findings: Iterable[Any],
+        import_edges: dict[str, set[str]] | None = None,
+    ):
+        """
+        Args:
+            findings: patchi.core.agents.base.Finding objects (or duck-typed:
+                need .type/.file/.line/.severity/.agent).
+            import_edges: optional {importer_file: {imported_files...}} map.
+                Co-location alone is enough to link findings; import edges let
+                chains cross module boundaries (route -> service -> repo).
+        """
+        self.import_edges = import_edges or {}
+        self.nodes: list[ChainNode] = []
+        for f in findings:
+            role = classify(getattr(f, "type", ""))
+            if role is not NodeRole.STANDALONE:
+                self.nodes.append(ChainNode(finding=f, role=role))
+        self._index()
+
+    def _index(self) -> None:
+        self.by_file: dict[str, list[ChainNode]] = defaultdict(list)
+        for n in self.nodes:
+            self.by_file[n.finding.file].append(n)
+
+    def _connected(self, a: ChainNode, b: ChainNode) -> bool:
+        """True when b is reachable from a's location (same file or import path)."""
+        fa, fb = a.finding.file, b.finding.file
+        if fa == fb:
+            return True
+        return fb in self.import_edges.get(fa, set())
+
+    def _edge_label(self, src: ChainNode, dst: ChainNode) -> str | None:
+        st, dt = src.finding.type.lower(), dst.finding.type.lower()
+        for sp, dp, label in _CHAIN_RULES:
+            if _matches(sp, st) and _matches(dp, dt):
+                return label
+        return None
+
+    def _adjacency(self) -> dict[int, list[tuple[int, str]]]:
+        adj: dict[int, list[tuple[int, str]]] = defaultdict(list)
+        for i, src in enumerate(self.nodes):
+            for j, dst in enumerate(self.nodes):
+                if i == j:
+                    continue
+                # Enforce direction: entries start chains, impacts end them.
+                order = {NodeRole.ENTRY: 0, NodeRole.EXPLOIT: 1, NodeRole.IMPACT: 2}
+                if order[src.role] > order[dst.role]:
+                    continue
+                if not self._connected(src, dst):
+                    continue
+                label = self._edge_label(src, dst)
+                if label:
+                    adj[i].append((j, label))
+        return adj
+
+    def find_chains(self, max_chains: int = 50, max_depth: int = 5) -> list[Chain]:
+        """Return all entry->...->impact chains, worst-first, capped."""
+        adj = self._adjacency()
+        chains: list[Chain] = []
+
+        def dfs(idx: int, path: list[int], labels: list[str], seen: set[int]) -> None:
+            if len(chains) >= max_chains * 4 or len(path) > max_depth:
+                return
+            node = self.nodes[idx]
+            # Entry->exploit pairs are already actionable ("unauthenticated
+            # SQL injection"); record them AND keep walking toward impact.
+            if len(path) >= 2 and node.role in (NodeRole.EXPLOIT, NodeRole.IMPACT):
+                chains.append(Chain(nodes=[self.nodes[i] for i in path], edges=list(labels)))
+                if node.role == NodeRole.IMPACT:
+                    return  # impact terminates a chain
+            for j, label in adj.get(idx, []):
+                if j in seen:
+                    continue
+                dfs(j, path + [j], labels + [label], seen | {j})
+
+        for i, n in enumerate(self.nodes):
+            if n.role == NodeRole.ENTRY:
+                dfs(i, [i], [], {i})
+            elif n.role == NodeRole.EXPLOIT:
+                # Exploit-to-impact pairs also count (2-node chains).
+                for j, label in adj.get(i, []):
+                    if self.nodes[j].role == NodeRole.IMPACT:
+                        chains.append(
+                            Chain(
+                                nodes=[self.nodes[i], self.nodes[j]],
+                                edges=[label],
+                            )
+                        )
+
+        chains.sort(key=lambda c: c.score, reverse=True)
+        # Dedup identical narratives (same steps via different DFS orders)
+        seen_narratives: set[str] = set()
+        unique: list[Chain] = []
+        for c in chains:
+            sig = tuple(n.key for n in c.nodes)
+            if sig not in seen_narratives:
+                seen_narratives.add(sig)
+                unique.append(c)
+        return unique[:max_chains]
+
+    def summary(self) -> dict[str, Any]:
+        """Aggregate stats for reporting / web panels."""
+        chains = self.find_chains()
+        sev_counts: dict[str, int] = defaultdict(int)
+        for c in chains:
+            sev_counts[c.severity] += 1
+        return {
+            "findings_analyzed": len(self.nodes),
+            "chains_found": len(chains),
+            "by_severity": dict(sev_counts),
+            "worst": chains[0].to_dict() if chains else None,
+        }