attackmap 0.6.4__py3-none-any.whl

attackmap/threat_model.py

@@ -0,0 +1,3441 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .analyzer import identify_attack_surfaces
+from .webhook_verification import describe as describe_webhook
+from .exploitability import best_by_sink_kind, score_exploitability
+from .models import (
+    AttackPath,
+    AttackSurface,
+    AttackTechnique,
+    BolaCandidate,
+    CloudMisconfig,
+    DatabaseHint,
+    ExternalCall,
+    Finding,
+    FindingLocation,
+    Route,
+    ScanResult,
+    TaintChain,
+    TaintFlowStep,
+)
+from .srcpaths import evidence_locations
+from .taint_sinks import SINK_KINDS, canonical_kind, kind_label
+from .authz import find_bfla_routes
+from .route_auth_fusion import synthesize_unauthenticated_routes, unauthenticated_routes
+from .taxonomy import cwe_tag, taxonomy_for
+
+LOW_QUALITY_SEGMENTS = ("/tests/", "/__tests__/", "/fixtures/", "/mocks/", "/examples/")
+
+# Cap on the number of basic-archetype attack paths emitted per scan.
+# Lifted from 1 in #24; capped here to keep reports focused — anything
+# beyond the top few is typically redundant with what findings already
+# surface. Chain-archetype paths (atproto / service / framework) emit
+# alone and don't count toward this cap.
+MAX_ATTACK_PATHS = 5
+_MAX_BOLA_PATHS = 3
+
+# Per-archetype fan-out cap (#5). When multiple distinct files satisfy
+# an archetype (e.g. three different public-data routes each writing
+# to their own datastore), emit one path per file up to this many.
+# Keeps the multi-vector story visible without exploding into noise.
+MAX_PER_ARCHETYPE_FANOUT = 3
+
+
+def _surface_label(surface: AttackSurface) -> str:
+    return f"{surface.method} {surface.route} in {surface.file}"
+
+
+def _severity_rank(value: str) -> int:
+    return {"high": 0, "medium": 1, "low": 2}.get(value, 3)
+
+
+# #4: prioritization scoring. Higher score = triage first within severity.
+# Formula: severity_weight × confidence_multiplier, rounded to int.
+_SEVERITY_WEIGHT = {"high": 100, "medium": 50, "low": 10}
+_CONFIDENCE_MULTIPLIER = {"high": 1.0, "medium": 0.75, "low": 0.5}
+
+
+def compute_finding_score(severity: str, confidence: str) -> int:
+    """Compute the prioritization score for a finding.
+
+    Range: 5 (low/low) to 100 (high/high). Used as a secondary sort key
+    inside a severity band so a HIGH/HIGH lands above a HIGH/LOW.
+    """
+    return int(_SEVERITY_WEIGHT.get(severity, 0) * _CONFIDENCE_MULTIPLIER.get(confidence, 0.5))
+
+
+def _action_step(label: str, action: str) -> str:
+    return f"{label}: {action}"
+
+
+def _rule_slug_kind(kind: str) -> str:
+    """Rule id for a spec-driven detector family (#223): its kind, dashed."""
+    return kind.replace("_", "-")
+
+
+def _locs(items, file_attr: str = "file", line_attr: str = "line") -> list[FindingLocation]:
+    """Structured locations for every item behind a finding (#214)."""
+    out: list[FindingLocation] = []
+    seen: set[tuple[str, int | None]] = set()
+    for item in items:
+        file = getattr(item, file_attr, None)
+        if not file:
+            continue
+        line = getattr(item, line_attr, None)
+        key = (file, line)
+        if key not in seen:
+            seen.add(key)
+            out.append(FindingLocation(file=file, line=line))
+    return out
+
+
+def _fill_missing_locations(findings: list[Finding]) -> None:
+    """Findings without structured locations fall back to evidence parsing."""
+    for finding in findings:
+        if not finding.locations:
+            finding.locations = [FindingLocation(file=f, line=l) for f, l in evidence_locations(finding.evidence)]
+
+
+def _webhook_state(surface: AttackSurface) -> str:
+    return surface.webhook_verification.state if surface.webhook_verification is not None else "unknown"
+
+
+def _webhook_detail(surface: AttackSurface) -> str:
+    v = surface.webhook_verification
+    if v is not None and v.state == "absent":
+        return "no signature verification found in the handler"
+    if v is not None and v.notes:
+        return "; ".join(v.notes)
+    return "signature verification could not be determined"
+
+
+def _webhook_extra_notes(surface: AttackSurface) -> list[str]:
+    """Notes beyond what the state's description already says."""
+    v = surface.webhook_verification
+    if v is None:
+        return []
+    return [note for note in v.notes if not (v.state == "no_replay_guard" and "timestamp" in note)]
+
+
+def _webhook_locs(surfaces: list[AttackSurface]) -> list[FindingLocation]:
+    """The route and the line its verification state rests on."""
+    out = _locs(surfaces)
+    seen = {(loc.file, loc.line) for loc in out}
+    for surface in surfaces:
+        evidence = surface.webhook_verification.evidence if surface.webhook_verification else None
+        if not evidence or ":" not in evidence:
+            continue
+        file, _, line = evidence.rpartition(":")
+        if line.isdigit() and (file, int(line)) not in seen:
+            seen.add((file, int(line)))
+            out.append(FindingLocation(file=file, line=int(line)))
+    return out
+
+
+def _webhook_weak_point(surface: AttackSurface) -> str:
+    """The attack path's weak point, citing the verification state (#243)."""
+    v = surface.webhook_verification
+    state = _webhook_state(surface)
+    if state == "absent":
+        return (
+            f"No signature verification was found for the event payload (handler at {surface.location()}), "
+            "so a forged event is processed as if it came from the provider"
+        )
+    if state == "weak_compare" and v is not None:
+        return (
+            f"The HMAC signature is compared with a non-constant-time equality at {v.evidence}, "
+            "so response timing reveals how much of a forged signature matched"
+        )
+    if state == "no_replay_guard" and v is not None:
+        return (
+            f"The signature is verified at {v.evidence}, but the signed timestamp is never checked, "
+            "so a captured event can be replayed"
+        )
+    return (
+        "The endpoint is treated like a trusted integration boundary before its input is fully verified "
+        "(signature verification could not be determined statically)"
+    )
+
+
+def _finding_evidence(surface: AttackSurface) -> str:
+    details: list[str] = [_surface_label(surface)]
+    if surface.auth_signals:
+        details.append(f"auth signals: {', '.join(surface.auth_signals)}")
+    else:
+        details.append("no auth signals observed")
+    if surface.data_store_interaction:
+        details.append("data store reachable")
+    if surface.outbound_integration:
+        details.append("external integration reachable")
+    return "; ".join(details)
+
+
+def _distinct_by_file(
+    surfaces: list[AttackSurface],
+    predicate,
+    limit: int,
+) -> list[AttackSurface]:
+    """Return the first `limit` surfaces matching `predicate`, one per file.
+
+    Used by #5 fan-out so a repo with three public-data routes in three
+    different files each produces its own concrete path — while three
+    routes in the same file collapse to one (same story anyway).
+    """
+    picked: list[AttackSurface] = []
+    seen_files: set[str] = set()
+    for surface in surfaces:
+        if not predicate(surface):
+            continue
+        if surface.file in seen_files:
+            continue
+        seen_files.add(surface.file)
+        picked.append(surface)
+        if len(picked) >= limit:
+            break
+    return picked
+
+
+def _same_file_datastore(surface: AttackSurface, scan: ScanResult) -> tuple[str, str] | None:
+    """Return `(kind, file)` of a datastore in the same file as the surface,
+    or None. Used by #5 to make Propagation steps name the concrete sink."""
+    for hint in scan.databases:
+        if hint.file == surface.file:
+            return (hint.kind, hint.file)
+    return None
+
+
+def _same_file_external(surface: AttackSurface, scan: ScanResult) -> tuple[str, str] | None:
+    """Return `(target, file)` of an external call in the same file as the
+    surface, or None. #5 narrative enrichment."""
+    for call in scan.external_calls:
+        if call.file == surface.file:
+            return (call.target, call.file)
+    return None
+
+
+def _surface_evidence(surface: AttackSurface, scan: ScanResult, max_items: int = 4) -> list[str]:
+    """Collect concrete evidence tied to a surface — same-file signals only.
+
+    Used by basic-archetype attack paths to anchor their narrative in
+    specific databases, external calls, and secrets present in the same
+    file as the entry surface, rather than emitting a generic 4-step
+    story. Keeps the evidence chain narrow and defensible: if it's in
+    the same file as the vulnerable route, we can cite it without
+    speculating about how signals connect.
+    """
+    evidence: list[str] = []
+    for hint in scan.databases:
+        if hint.file == surface.file:
+            evidence.append(f"data store in same file: {hint.kind} ({hint.file})")
+    for call in scan.external_calls:
+        if call.file == surface.file:
+            evidence.append(f"external call in same file: {call.target} ({call.file})")
+    for secret in scan.secret_hints:
+        if secret.file == surface.file:
+            evidence.append(f"env-configured secret in same file: {secret.name} ({secret.file})")
+    return evidence[:max_items]
+
+
+@dataclass(frozen=True)
+class ProbableChain:
+    route_method: str
+    route_path: str
+    route_file: str
+    controller: str | None
+    action: str | None
+    service: str | None
+    sink: str
+    confidence: float
+    evidence: list[str]
+
+
+@dataclass(frozen=True)
+class ServiceChain:
+    route_method: str
+    route_path: str
+    route_file: str
+    entry_service: str
+    next_service: str | None
+    sink: str
+    confidence: float
+    evidence: list[str]
+    env_risk: str | None = None
+
+
+@dataclass(frozen=True)
+class AtprotoChain:
+    route_method: str
+    route_path: str
+    route_file: str
+    namespace: str
+    entry_service: str
+    next_service: str | None
+    sink: str
+    confidence: float
+    evidence: list[str]
+    env_risk: str | None = None
+
+
+# SecretHint kinds that name a secret without containing its value.
+NON_LITERAL_SECRET_KINDS = frozenset({"env_reference", "env_template"})
+
+
+def _extract_prefixed_hints(scan: ScanResult, prefix: str) -> list[tuple[str, str]]:
+    grouped_hints: list[tuple[str, str]] = []
+    for hint in scan.auth_hints:
+        if hint.hint.startswith(prefix):
+            grouped_hints.append((hint.hint.removeprefix(prefix), hint.file))
+
+    # Phase-2 migration support: allow specialized non-auth hint categories to
+    # carry prefixed values while keeping auth_hints fallback behavior.
+    if prefix.startswith("service_"):
+        for hint in scan.service_hints:
+            if hint.hint.startswith(prefix):
+                grouped_hints.append((hint.hint.removeprefix(prefix), hint.file))
+    elif prefix.startswith("edge:"):
+        for hint in scan.edge_hints:
+            if hint.hint.startswith(prefix):
+                grouped_hints.append((hint.hint.removeprefix(prefix), hint.file))
+    elif prefix.startswith("entrypoint:"):
+        for hint in scan.entrypoint_hints:
+            if hint.hint.startswith(prefix):
+                grouped_hints.append((hint.hint.removeprefix(prefix), hint.file))
+    elif prefix.startswith(("atproto_", "protocol:")):
+        for hint in scan.protocol_hints:
+            if hint.hint.startswith(prefix):
+                grouped_hints.append((hint.hint.removeprefix(prefix), hint.file))
+    elif prefix.startswith(("controller:", "service:", "omeka_", "laminas_")):
+        for hint in scan.framework_hints:
+            if hint.hint.startswith(prefix):
+                grouped_hints.append((hint.hint.removeprefix(prefix), hint.file))
+
+    deduped: list[tuple[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for item in grouped_hints:
+        if item in seen:
+            continue
+        seen.add(item)
+        deduped.append(item)
+    return deduped
+
+
+def _provenance_by_hint(scan: ScanResult) -> dict[str, str]:
+    """Index hint text -> `source_analyzer` across framework/auth hints.
+
+    Used by the chain linker (#13) to name the analyzer that produced
+    each contributing signal in the emitted evidence line. Empty dict
+    when no signals carry provenance (e.g. hand-constructed test scans).
+    """
+    index: dict[str, str] = {}
+    for hint_list in (scan.framework_hints, scan.auth_hints):
+        for hint in hint_list:
+            src = getattr(hint, "source_analyzer", None)
+            if src and hint.hint not in index:
+                index[hint.hint] = src
+    return index
+
+
+def _cited(label: str, value: str, provenance: dict[str, str], hint_key: str) -> str:
+    """Format `label: value` and append `[via <analyzer>]` when provenance exists."""
+    source = provenance.get(hint_key)
+    base = f"{label}: {value}"
+    return f"{base} [via {source}]" if source else base
+
+
+def _is_low_quality_source(path_or_text: str) -> bool:
+    normalized = path_or_text.replace("\\", "/").lower()
+    return any(segment in f"/{normalized}/" for segment in LOW_QUALITY_SEGMENTS)
+
+
+def _runtime_routes(scan: ScanResult) -> list[Route]:
+    return [route for route in scan.routes if not _is_low_quality_source(route.file)]
+
+
+def _extract_edge_hints(scan: ScanResult) -> list[tuple[str, str, str]]:
+    edges: list[tuple[str, str, str]] = []
+    all_edge_hints = [*scan.edge_hints, *scan.auth_hints]
+    for hint in all_edge_hints:
+        if not hint.hint.startswith("edge:"):
+            continue
+        raw_edge = hint.hint.removeprefix("edge:")
+        if "->" not in raw_edge:
+            continue
+        source, target = raw_edge.split("->", 1)
+        source_name = source.strip().lower()
+        target_name = target.strip().lower()
+        if not source_name or not target_name:
+            continue
+        edges.append((source_name, target_name, hint.file))
+    return edges
+
+
+def _infer_service_name_from_file(file_path: str) -> str | None:
+    normalized = file_path.replace("\\", "/")
+    parts = normalized.split("/")
+    for parent in ("services", "packages", "apps"):
+        if parent in parts:
+            idx = parts.index(parent)
+            if idx + 1 < len(parts):
+                return parts[idx + 1].lower()
+    return None
+
+
+def _file_service_map(scan: ScanResult) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for service_name, service_file in _extract_prefixed_hints(scan, "service_name:"):
+        mapping[service_file] = service_name.lower()
+    for path in [*mapping.keys(), *(route.file for route in scan.routes), *(db.file for db in scan.databases), *(call.file for call in scan.external_calls)]:
+        if path in mapping:
+            continue
+        inferred = _infer_service_name_from_file(path)
+        if inferred:
+            mapping[path] = inferred
+    return mapping
+
+
+def _sink_on_chain(evidence: list[str]) -> bool:
+    """False when the chain's sink was only borrowed from elsewhere in the repo."""
+    return not any("elsewhere in repo" in item for item in evidence)
+
+
+def _build_service_chains(scan: ScanResult) -> list[ServiceChain]:
+    service_edges = _extract_edge_hints(scan)
+    has_service_hints = any(h.hint.startswith("service_name:") for h in [*scan.service_hints, *scan.auth_hints])
+    if not service_edges and not has_service_hints:
+        return []
+
+    file_service = _file_service_map(scan)
+    edge_targets_by_source: dict[str, list[str]] = {}
+    for source, target, _file in service_edges:
+        edge_targets_by_source.setdefault(source, []).append(target)
+
+    databases_by_service: dict[str, DatabaseHint] = {}
+    for database in scan.databases:
+        service = file_service.get(database.file)
+        if service and service not in databases_by_service:
+            databases_by_service[service] = database
+
+    outbound_by_service: dict[str, ExternalCall] = {}
+    env_url_by_service: dict[str, str] = {}
+    for call in scan.external_calls:
+        service = file_service.get(call.file)
+        if not service:
+            continue
+        if call.target.startswith("env://"):
+            env_url_by_service.setdefault(service, call.target)
+            continue
+        outbound_by_service.setdefault(service, call)
+
+    chains: list[ServiceChain] = []
+    for route in _runtime_routes(scan):
+        evidence = [f"route {route.method} {route.path} in {route.file}"]
+        confidence = 0.35
+        entry_service = file_service.get(route.file) or _infer_service_name_from_file(route.file) or "entry-service"
+        if file_service.get(route.file):
+            confidence += 0.25
+            evidence.append(f"entry service from file-local hint: {entry_service}")
+        else:
+            confidence += 0.1
+            evidence.append(f"entry service inferred from repository layout: {entry_service}")
+
+        next_service = None
+        sink = "privileged downstream action"
+        env_risk = env_url_by_service.get(entry_service)
+
+        candidates = edge_targets_by_source.get(entry_service, [])
+        if candidates:
+            next_service = candidates[0]
+            confidence += 0.15
+            evidence.append(f"inter-service edge: {entry_service}->{next_service}")
+
+        sink_service = next_service or entry_service
+        if sink_service in databases_by_service:
+            db_hint = databases_by_service[sink_service]
+            sink = "database"
+            confidence += 0.2
+            evidence.append(f"database sink in service {sink_service}: {db_hint.kind} ({db_hint.file})")
+        elif sink_service in outbound_by_service:
+            ext_hint = outbound_by_service[sink_service]
+            sink = "external dependency"
+            confidence += 0.15
+            evidence.append(f"external sink in service {sink_service}: {ext_hint.target} ({ext_hint.file})")
+        elif scan.databases:
+            sink = "database"
+            confidence += 0.05
+            evidence.append(f"database hint elsewhere in repo: {scan.databases[0].kind} ({scan.databases[0].file})")
+        elif scan.external_calls:
+            sink = "external dependency"
+            confidence += 0.05
+            evidence.append(f"external call elsewhere in repo: {scan.external_calls[0].target} ({scan.external_calls[0].file})")
+
+        if env_risk:
+            confidence += 0.05
+            evidence.append(f"env-configured dependency in entry service: {env_risk}")
+
+        chains.append(
+            ServiceChain(
+                route_method=route.method,
+                route_path=route.path,
+                route_file=route.file,
+                entry_service=entry_service,
+                next_service=next_service,
+                sink=sink,
+                confidence=min(confidence, 0.95),
+                evidence=evidence,
+                env_risk=env_risk,
+            )
+        )
+
+    chains.sort(key=lambda chain: chain.confidence, reverse=True)
+    return chains
+
+
+def _is_atproto_scan(scan: ScanResult) -> bool:
+    return any(hint.hint.startswith("atproto_") for hint in [*scan.protocol_hints, *scan.auth_hints])
+
+
+def _extract_xrpc_namespace(route_path: str) -> str | None:
+    marker = "/xrpc/"
+    if marker not in route_path:
+        return None
+    value = route_path.split(marker, 1)[1].strip("/")
+    if not value:
+        return None
+    if value.startswith("com.atproto."):
+        return "com.atproto"
+    if value.startswith("app.bsky."):
+        return "app.bsky"
+    return None
+
+
+def _build_atproto_chains(scan: ScanResult) -> list[AtprotoChain]:
+    if not _is_atproto_scan(scan):
+        return []
+
+    file_service = _file_service_map(scan)
+    for service_name, service_file in _extract_prefixed_hints(scan, "atproto_service_note:"):
+        file_service.setdefault(service_file, service_name.lower())
+
+    edge_targets_by_source: dict[str, list[str]] = {}
+    for source, target, _file in _extract_edge_hints(scan):
+        edge_targets_by_source.setdefault(source, []).append(target)
+
+    namespaces = {name for name, _file in _extract_prefixed_hints(scan, "atproto_namespace:")}
+    lexicons = {name for name, _file in _extract_prefixed_hints(scan, "atproto_lexicon:")}
+    xrpc_refs = {name for name, _file in _extract_prefixed_hints(scan, "atproto_xrpc_ref:")}
+    service_edges = {name for name, _file in _extract_prefixed_hints(scan, "atproto_service_edge:")}
+    stream_hints = {name for name, _file in _extract_prefixed_hints(scan, "atproto_event_stream:")}
+
+    databases_by_service: dict[str, tuple[str, str]] = {}
+    for database in scan.databases:
+        service = file_service.get(database.file)
+        if service and service not in databases_by_service:
+            databases_by_service[service] = (database.kind, database.file)
+
+    outbound_by_service: dict[str, tuple[str, str]] = {}
+    env_url_by_service: dict[str, str] = {}
+    for call in scan.external_calls:
+        service = file_service.get(call.file)
+        if not service:
+            continue
+        if call.target.startswith("env://"):
+            env_url_by_service.setdefault(service, call.target)
+            continue
+        outbound_by_service.setdefault(service, (call.target, call.file))
+
+    chains: list[AtprotoChain] = []
+    for route in _runtime_routes(scan):
+        namespace = _extract_xrpc_namespace(route.path)
+        if namespace is None:
+            continue
+
+        evidence = [f"xrpc route {route.method} {route.path} in {route.file}"]
+        confidence = 0.45
+        if namespace in namespaces:
+            confidence += 0.1
+            evidence.append(f"namespace signal observed: {namespace}")
+
+        endpoint_name = route.path.removeprefix("/xrpc/")
+        if endpoint_name in lexicons:
+            confidence += 0.1
+            evidence.append(f"lexicon-defined endpoint: {endpoint_name}")
+        if endpoint_name in xrpc_refs:
+            confidence += 0.05
+            evidence.append(f"code-level xrpc reference: {endpoint_name}")
+
+        entry_service = file_service.get(route.file) or _infer_service_name_from_file(route.file) or "entry-service"
+        if file_service.get(route.file):
+            confidence += 0.15
+            evidence.append(f"entry service from analyzer hints: {entry_service}")
+        else:
+            confidence += 0.05
+            evidence.append(f"entry service inferred from repository layout: {entry_service}")
+
+        next_service = None
+        sink = "privileged downstream action"
+        env_risk = env_url_by_service.get(entry_service)
+
+        edge_candidates = edge_targets_by_source.get(entry_service, [])
+        if edge_candidates:
+            next_service = edge_candidates[0]
+            confidence += 0.1
+            evidence.append(f"inter-service edge: {entry_service}->{next_service}")
+        elif service_edges:
+            next_service = sorted(service_edges)[0]
+            confidence += 0.05
+            evidence.append(f"atproto env-derived service edge: {entry_service}->{next_service}")
+
+        sink_service = next_service or entry_service
+        if sink_service in databases_by_service:
+            kind, db_file = databases_by_service[sink_service]
+            sink = "database"
+            confidence += 0.15
+            evidence.append(f"database sink in service {sink_service}: {kind} ({db_file})")
+        elif sink_service in outbound_by_service:
+            target, outbound_file = outbound_by_service[sink_service]
+            sink = "external dependency"
+            confidence += 0.12
+            evidence.append(f"outbound sink in service {sink_service}: {target} ({outbound_file})")
+        elif scan.databases:
+            sink = "database"
+            confidence += 0.03
+            evidence.append(f"database hint elsewhere in repo: {scan.databases[0].kind} ({scan.databases[0].file})")
+        elif scan.external_calls:
+            sink = "external dependency"
+            confidence += 0.03
+            evidence.append(f"external call elsewhere in repo: {scan.external_calls[0].target} ({scan.external_calls[0].file})")
+
+        if env_risk:
+            confidence += 0.04
+            evidence.append(f"env-configured dependency in entry service: {env_risk}")
+        if stream_hints:
+            confidence += 0.03
+            evidence.append(f"event stream exposure hints: {', '.join(sorted(stream_hints)[:2])}")
+
+        chains.append(
+            AtprotoChain(
+                route_method=route.method,
+                route_path=route.path,
+                route_file=route.file,
+                namespace=namespace,
+                entry_service=entry_service,
+                next_service=next_service,
+                sink=sink,
+                confidence=min(confidence, 0.95),
+                evidence=evidence,
+                env_risk=env_risk,
+            )
+        )
+
+    chains.sort(key=lambda chain: chain.confidence, reverse=True)
+    return chains
+
+
+def _file_module_key(file_path: str) -> str:
+    normalized = file_path.replace("\\", "/")
+    marker = "/module/"
+    if marker in normalized:
+        suffix = normalized.split(marker, 1)[1]
+        parts = suffix.split("/")
+        if parts and parts[0]:
+            return f"module/{parts[0].lower()}"
+    parts = normalized.split("/")
+    if parts:
+        return parts[0].lower()
+    return normalized.lower()
+
+
+def _guess_action(route_path: str) -> str | None:
+    lower = route_path.lower()
+    if "/admin" in lower:
+        return "admin action"
+    if "/api" in lower:
+        return "api action"
+    if lower.startswith("/s/") or "/site" in lower:
+        return "site action"
+    return None
+
+
+def _is_framework_mvc_scan(scan: ScanResult) -> bool:
+    framework_values = [*scan.framework_hints, *scan.auth_hints]
+    return any(
+        hint.hint.startswith("controller:")
+        or hint.hint.startswith("service:")
+        or hint.hint.startswith("omeka_")
+        or hint.hint.startswith("laminas_")
+        for hint in framework_values
+    )
+
+
+def confidence_bucket(value: float) -> str:
+    """Bucket a numeric confidence into the low/medium/high labels #13 asks
+    for. Thresholds picked so a bare route+sink lands in `low`, a chain
+    with controller+sink lands in `medium`, and a chain that also picks
+    up an Omeka/Laminas framework signal (extension or dependency hint)
+    lands in `high`.
+    """
+    if value >= 0.75:
+        return "high"
+    if value >= 0.55:
+        return "medium"
+    return "low"
+
+
+_TAINT_SINK_LABEL: dict[str, str] = {
+    "sql_execute": "database (SQL execute)",
+    "subprocess_shell": "command execution",
+    "eval": "code eval",
+    "exec": "code exec",
+    "dynamic_open": "filesystem open",
+    "unsafe_deserialization": "unsafe deserialization",
+    "ssti": "template injection",
+    "ssrf": "outbound request (SSRF)",
+    "nosql_injection": "NoSQL query",
+    "open_redirect": "redirect target",
+}
+# Kinds added through the sink registry (#240) take its labels.
+for _kind in SINK_KINDS:
+    _TAINT_SINK_LABEL.setdefault(_kind, kind_label(_kind))
+
+
+# Per-sink-kind specification for the dedicated taint findings (#68).
+# Each dangerous sink kind reachable from a route produces one aggregated
+# Finding. `severity` is the Finding severity; `technique` is an ATT&CK
+# reference. Sinks NOT in this table (sql_execute, dynamic_open) are
+# surfaced through the probable-chain finding path instead of a dedicated
+# finding.
+_TAINT_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "eval": {
+        "severity": "high",
+        "title": "Request-reachable code execution via eval",
+        "mitigation": "Never pass request-derived data to eval. Use a domain-specific parser or an explicit allow-list of operations.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "exec": {
+        "severity": "high",
+        "title": "Request-reachable code execution via exec",
+        "mitigation": "Never pass request-derived data to exec. Refactor to call named functions selected via a validated allow-list.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "subprocess_shell": {
+        "severity": "high",
+        "title": "Request-reachable OS command execution",
+        "mitigation": "Prefer argv-list subprocess calls with shell=False. Never interpolate request data into a shell string; validate and constrain any external command inputs.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "unsafe_deserialization": {
+        "severity": "high",
+        "title": "Request-reachable unsafe deserialization",
+        "mitigation": "Do not deserialize attacker-controlled data with pickle/marshal/yaml.load/ObjectInputStream/unserialize. Use a data-only format (JSON) with a schema, or a safe loader (yaml.safe_load).",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "ssti": {
+        "severity": "high",
+        "title": "Request-reachable server-side template injection",
+        "mitigation": "Never render request-derived strings as templates. Pass untrusted data as template *variables* (auto-escaped), not as the template source.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "ssrf": {
+        "severity": "medium",
+        "title": "Request-reachable server-side request forgery (SSRF)",
+        "mitigation": "Validate and allow-list outbound destinations, resolve and pin DNS, block link-local/metadata ranges (169.254.0.0/16, fd00::/8), and disable redirects to internal hosts.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "nosql_injection": {
+        "severity": "medium",
+        "title": "Request-reachable NoSQL injection",
+        "mitigation": "Never pass a raw request object as a query filter. Cast and validate each field, reject operator keys ($where, $gt, ...) in user input, and disable server-side JavaScript execution.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    # --- #240 sink catalog expansion -------------------------------------
+    "zip_slip": {
+        "severity": "high",
+        "title": "Request-reachable archive extraction without path checks (zip-slip)",
+        "mitigation": "Extract only after validating every member path resolves inside the destination (tarfile: `extractall(filter=\"data\")` on Python 3.12+; adm-zip/unzipper: check `path.resolve(dest, entry)` starts with `dest`). Reject absolute paths, `..` segments and links.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "code_injection": {
+        "severity": "high",
+        "title": "Request input selects or builds code to run (code injection)",
+        "mitigation": "Never build code (new Function, vm.run*, string setTimeout) or pick modules/methods (import_module, getattr, send, constantize) from request input. Map an allow-listed key to a fixed callable instead.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "expression_injection": {
+        "severity": "high",
+        "title": "Request input evaluated as an expression (SpEL/OGNL/MVEL/script injection)",
+        "mitigation": "Do not parse or evaluate request-derived strings with SpEL, OGNL, MVEL or a ScriptEngine. Use a SimpleEvaluationContext / sandbox if expressions are a feature, and pass user data only as variables.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "jndi_injection": {
+        "severity": "high",
+        "title": "Request input reaches a JNDI lookup (JNDI injection)",
+        "mitigation": "Never pass request-derived names to `Context.lookup`. Look up fixed, configured names only, and disable remote codebases (`com.sun.jndi.*.object.trustURLCodebase=false`).",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "ldap_injection": {
+        "severity": "medium",
+        "title": "Request input reaches an LDAP search filter (LDAP injection)",
+        "mitigation": "Escape every request-derived value with an LDAP filter encoder (ldap.filter.escape_filter_chars, ldap_escape(..., LDAP_ESCAPE_FILTER), Spring LdapEncoder.filterEncode) or build filters with a parameterized API.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "xpath_injection": {
+        "severity": "medium",
+        "title": "Request input reaches an XPath expression (XPath injection)",
+        "mitigation": "Use XPath variables (XPathVariableResolver, lxml `xpath(expr, name=value)`) instead of concatenating request data into the expression.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "header_injection": {
+        "severity": "low",
+        "title": "Request input sets an HTTP response header (header injection)",
+        "mitigation": "Most frameworks now reject CR/LF in header values, but a caller-controlled value can still steer Location, Content-Disposition or cookies. Allow-list or encode the value before setting the header.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "regex_injection": {
+        "severity": "low",
+        "title": "Request input compiled as a regular expression (ReDoS)",
+        "mitigation": "Escape request input before embedding it in a pattern (re.escape, escapeStringRegexp, Pattern.quote, regexp.QuoteMeta, preg_quote), or match it as a literal. Use a linear-time engine (RE2) where user patterns are a feature.",
+        "technique_id": "T1499.004",
+        "technique_name": "Endpoint Denial of Service: Application or System Exploitation",
+        "tactic": "Impact",
+    },
+    "open_redirect": {
+        "severity": "medium",
+        "title": "Request-reachable open redirect",
+        "mitigation": "Never redirect to a request-derived URL directly. Redirect only to a server-side allow-list of paths/hosts, or map an opaque key to the destination; reject absolute URLs and protocol-relative (`//`) targets.",
+        "technique_id": "T1204",
+        "technique_name": "User Execution",
+        "tactic": "Execution",
+    },
+}
+
+
+# Flow-confirmed findings (#239) for sink kinds that are NOT dangerous on
+# reachability alone — a SQL call or file open is everywhere. These fire only
+# when the intra-procedural pass traced a request source into the sink's
+# dangerous argument (`TaintChain.source_kind` set, not sanitized), so the
+# finding names the exact source line and route.
+_FLOW_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "sql_execute": {
+        "rule_id": "sql-injection",
+        "severity": "high",
+        "title": "Request input flows into a raw SQL query (SQL injection)",
+        "mitigation": "Use parameterized queries / bound parameters for every request-derived value. Never build SQL with f-strings, concatenation, .format or %; allow-list identifiers (table/column names) that can't be bound.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    # `dynamic_open` chains are folded in here as an alias (#240).
+    "path_traversal": {
+        "rule_id": "path-traversal",
+        "severity": "high",
+        "title": "Request input flows into a filesystem path (path traversal)",
+        "mitigation": "Never build filesystem paths from request input directly. Reduce it to a basename (secure_filename / path.basename), resolve it against a fixed base directory and verify the result stays inside it, or map an opaque id to a server-side path.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+}
+
+# Cap on per-route flow lines cited in one aggregated taint finding, and on
+# the SARIF codeFlows it carries.
+_MAX_FLOW_EVIDENCE = 10
+_MAX_CODE_FLOWS = 20
+
+
+def _flow_evidence(chains: list[TaintChain]) -> list[str]:
+    """One `flow:` evidence line per distinct route with a traced source (#239)."""
+    lines: list[str] = []
+    seen: set[tuple[str, str, str, int | None]] = set()
+    traced = [c for c in chains if c.source_kind]
+    for c in sorted(traced, key=lambda c: (c.hops, c.route_file, c.sink_line or 0, c.route_path)):
+        key = (c.route_method, c.route_path, c.sink_file, c.sink_line)
+        if key in seen:
+            continue
+        seen.add(key)
+        if len(lines) == _MAX_FLOW_EVIDENCE:
+            lines.append(f"+{len(traced) - _MAX_FLOW_EVIDENCE} more traced flow(s)")
+            break
+        lines.append(
+            f"flow: {c.route_method} {c.route_path} — {c.source_kind} source at "
+            f"{c.sink_file}:{c.source_line} → sink at {c.sink_file}:{c.sink_line}"
+        )
+    return lines
+
+
+def _code_flows(chains: list[TaintChain]) -> list[list[TaintFlowStep]]:
+    """Distinct traced flows (by sink + source) for SARIF codeFlows."""
+    out: list[list[TaintFlowStep]] = []
+    seen: set[tuple[str, int | None, int | None]] = set()
+    for c in chains:
+        if not c.flow:
+            continue
+        key = (c.sink_file, c.sink_line, c.source_line)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(list(c.flow))
+        if len(out) == _MAX_CODE_FLOWS:
+            break
+    return out
+
+
+# Per-kind spec for insecure-crypto findings (#70). One aggregated
+# finding per crypto weakness kind present in the scan.
+_CRYPTO_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "weak_password_hash": {
+        "severity": "high",
+        "title": "Weak password hashing (MD5/SHA-1)",
+        "mitigation": "Hash passwords with a memory-hard KDF — argon2id, scrypt, or bcrypt — never a bare MD5/SHA-1/SHA-256 digest. Migrate existing hashes on next login.",
+        "technique_id": "T1110.002",
+        "technique_name": "Brute Force: Password Cracking",
+        "tactic": "Credential Access",
+    },
+    "weak_cipher": {
+        "severity": "high",
+        "title": "Weak or broken cipher (DES/3DES/RC4/Blowfish)",
+        "mitigation": "Replace legacy ciphers with AES-256-GCM (or ChaCha20-Poly1305). DES/3DES/RC4 are cryptographically broken.",
+        "technique_id": "T1600",
+        "technique_name": "Weaken Encryption",
+        "tactic": "Defense Evasion",
+    },
+    "ecb_mode": {
+        "severity": "medium",
+        "title": "Insecure ECB block-cipher mode",
+        "mitigation": "ECB leaks plaintext structure. Use an authenticated mode (AES-GCM) with a unique per-message nonce; in Java, always specify the transformation explicitly (e.g. \"AES/GCM/NoPadding\").",
+        "technique_id": "T1600",
+        "technique_name": "Weaken Encryption",
+        "tactic": "Defense Evasion",
+    },
+    "static_iv_salt": {
+        "severity": "medium",
+        "title": "Hard-coded IV or salt",
+        "mitigation": "Generate the IV/nonce and salt randomly per operation with a CSPRNG and store/transmit them alongside the ciphertext. A static IV/salt defeats the primitive's security.",
+        "technique_id": "T1600",
+        "technique_name": "Weaken Encryption",
+        "tactic": "Defense Evasion",
+    },
+    "insecure_random": {
+        "severity": "medium",
+        "title": "Insecure randomness for a security value",
+        "mitigation": "Use a CSPRNG for tokens/keys/salts/nonces/OTPs: `secrets` (Python), `crypto.randomBytes` (Node), `crypto/rand` (Go). `Math.random`/`random`/`rand`/`mt_rand` are predictable.",
+        "technique_id": "T1600",
+        "technique_name": "Weaken Encryption",
+        "tactic": "Defense Evasion",
+    },
+    "insecure_tls": {
+        "severity": "high",
+        "title": "TLS certificate/hostname verification disabled",
+        "mitigation": "Never disable certificate or hostname verification (`verify=False`, `rejectUnauthorized: false`, `InsecureSkipVerify: true`) or use deprecated TLS/SSL versions. Fix the trust store instead of turning off validation.",
+        "technique_id": "T1557",
+        "technique_name": "Adversary-in-the-Middle",
+        "tactic": "Credential Access",
+    },
+}
+
+
+# Per-kind spec for web-hardening findings (#71).
+_WEB_HARDENING_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "cors_wildcard_credentials": {
+        "severity": "high",
+        "title": "CORS allows credentials with a wildcard/reflected origin",
+        "mitigation": "Never combine `Access-Control-Allow-Credentials: true` with a `*` or reflected origin. Allow-list explicit trusted origins; if credentials aren't needed, drop the credentials flag.",
+        "technique_id": "T1539",
+        "technique_name": "Steal Web Session Cookie",
+        "tactic": "Credential Access",
+    },
+    "cors_wildcard_origin": {
+        "severity": "low",
+        "title": "CORS allows any origin (without credentials)",
+        "mitigation": "A wildcard or reflected origin lets any site read these responses. That is fine for genuinely public, unauthenticated data; otherwise allow-list the trusted origins. Never add credentials to this policy.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "cors_untrusted_origin": {
+        # high when the file also allows credentials, else medium
+        "title": "Origin allow-list admits untrusted origins (unanchored regex, partial match or null)",
+        "mitigation": "Compare the Origin against an exact allow-list of scheme://host[:port] values. Anchor origin regexes with `^` and `$` and escape dots; check subdomains with `.endsWith('.example.com')` (leading dot), never `includes`/`endsWith('example.com')`. Never allow the `null` origin, which sandboxed iframes and `file:` pages send.",
+        "technique_id": "T1539",
+        "technique_name": "Steal Web Session Cookie",
+        "tactic": "Credential Access",
+    },
+    "csrf_disabled": {
+        "severity": "medium",
+        "title": "CSRF protection disabled or exempted",
+        "mitigation": "Keep CSRF protection on for cookie-authenticated, state-changing routes. If an endpoint is a token-authenticated API that legitimately doesn't need it, scope the exemption narrowly and document why.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "csrf_unprotected_session": {
+        "severity": "medium",
+        "title": "Cookie-session auth with state-changing routes and no CSRF protection",
+        "mitigation": "Cookie-authenticated state-changing routes need a CSRF defence: CSRF-token middleware (`csrf-csrf`/`csrf-sync`, Django `CsrfViewMiddleware`, Flask-WTF `CSRFProtect`) or a session cookie with `SameSite=Strict` (or `Lax`, if no state changes on GET).",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "insecure_cookie": {
+        "severity": "medium",
+        "title": "Session cookie set without secure flags",
+        "mitigation": "Set `HttpOnly`, `Secure`, and `SameSite=Lax` (or `Strict`) on session cookies. `SameSite=None` must always be paired with `Secure`.",
+        "technique_id": "T1539",
+        "technique_name": "Steal Web Session Cookie",
+        "tactic": "Credential Access",
+    },
+    "weak_csp": {
+        "severity": "medium",
+        "title": "Content-Security-Policy allows unsafe-inline/unsafe-eval",
+        "mitigation": "Remove `'unsafe-inline'` and `'unsafe-eval'` from the CSP; use nonces or hashes for inline scripts. These directives largely defeat CSP's XSS protection.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "debug_enabled": {
+        "severity": "medium",
+        "title": "Debug mode or unrestricted management endpoints enabled",
+        "mitigation": "Never ship with debug mode on (Flask/Django `DEBUG`, Rails `consider_all_requests_local`) or Spring actuator endpoints exposed with `*`. Debug consoles leak internals and can enable RCE.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+}
+
+
+# Methods a forged cross-site request can use to change state (#244). `ANY`
+# covers routers that don't record a method (Django URLconfs).
+_CSRF_MUTATING_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE", "ANY"})
+
+
+# Per-kind spec for novel vuln-class findings (#77).
+_CODE_WEAKNESS_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "prototype_pollution": {
+        "severity": "high",
+        "title": "Prototype pollution",
+        "mitigation": "Never write attacker-controlled keys to `__proto__`/`constructor.prototype` or deep-merge a raw request object. Use a null-prototype object (`Object.create(null)`), a Map, or a merge that rejects `__proto__`/`constructor` keys.",
+        "technique_id": "T1059.007",
+        "technique_name": "Command and Scripting Interpreter: JavaScript",
+        "tactic": "Execution",
+    },
+    "mass_assignment": {
+        "severity": "high",
+        "title": "Mass assignment / overposting",
+        "mitigation": "Never bind a whole request body to a model. Explicitly allow-list assignable fields (serializers, DTOs, strong params with a field list) so attackers can't set privileged attributes (is_admin, role, owner_id).",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "jwt_weakness": {
+        "severity": "high",
+        "title": "JWT verification weakness (alg=none / signature not verified)",
+        "mitigation": "Pin an explicit allow-list of signing algorithms (never include `none`), always verify the signature, and reject tokens whose header `alg` isn't expected. Don't decode without verifying.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    # JWT verification (#243)
+    "jwt_alg_confusion": {
+        "severity": "high",
+        "title": "JWT verified without a pinned algorithm (algorithm confusion)",
+        "mitigation": "Pass an explicit algorithm allow-list on every verify: jsonwebtoken `verify(token, key, { algorithms: ['RS256'] })`, PyJWT `decode(token, key, algorithms=['RS256'])`, golang-jwt `jwt.WithValidMethods([]string{\"RS256\"})` or a keyfunc that checks `token.Method`. Otherwise a token signed with HS256 using the public key as the HMAC secret can pass as an RS256 token.",
+        "technique_id": "T1606",
+        "technique_name": "Forge Web Credentials",
+        "tactic": "Credential Access",
+    },
+    "jwt_unverified_decode": {
+        "severity": "high",
+        "title": "JWT decoded without signature verification",
+        "mitigation": "`decode` / `decodeJwt` / `ParseUnverified` / `get_unverified_claims` only base64-decode the token. Trust its claims only after a verifying call (`jwt.verify`, jose `jwtVerify`, PyJWT `decode` with a key and `algorithms`, golang-jwt `Parse` with a keyfunc).",
+        "technique_id": "T1606",
+        "technique_name": "Forge Web Credentials",
+        "tactic": "Credential Access",
+    },
+    "jwt_claims_unchecked": {
+        "severity": "medium",
+        "title": "JWT expiry or claims not validated",
+        "mitigation": "Leave expiry checking on (no `ignoreExpiration`, `verify_exp: False` or `WithoutClaimsValidation`), and with authlib call `claims.validate()` after `jwt.decode`. Expired or stolen tokens otherwise stay valid forever.",
+        "technique_id": "T1550.001",
+        "technique_name": "Use Alternate Authentication Material: Application Access Token",
+        "tactic": "Lateral Movement",
+    },
+    "jwt_header_trust": {
+        "severity": "high",
+        "title": "JWT key lookup trusts the unverified token header (kid / jku / x5u)",
+        "mitigation": "The header is attacker-controlled until the signature is verified. Look `kid` up in a fixed key map (or a bound SQL parameter), never a file path or an interpolated query, and never fetch keys from a header `jku`/`x5u` URL: pin the JWKS URL in configuration.",
+        "technique_id": "T1606",
+        "technique_name": "Forge Web Credentials",
+        "tactic": "Credential Access",
+    },
+    "jwt_weak_secret": {
+        "severity": "high",
+        "title": "Short JWT signing secret hard-coded in source",
+        "mitigation": "Load the HMAC secret from a secret manager or the environment and make it at least 256 bits of randomness. A short secret can be brute-forced offline from a single captured token, after which any token can be forged.",
+        "technique_id": "T1606",
+        "technique_name": "Forge Web Credentials",
+        "tactic": "Credential Access",
+    },
+    # OAuth clients and sessions (#243, part 2)
+    "oauth_missing_state": {
+        "severity": "medium",
+        "title": "OAuth authorization request without `state` (login CSRF)",
+        "mitigation": "Send an unguessable `state` bound to the user's session on every authorization request and reject callbacks whose `state` doesn't match (passport: `state: true`). Without it an attacker can complete the flow with their own code and log the victim into the attacker's account.",
+        "technique_id": "T1528",
+        "technique_name": "Steal Application Access Token",
+        "tactic": "Credential Access",
+    },
+    "oauth_implicit_flow": {
+        "severity": "medium",
+        "title": "OAuth implicit flow (`response_type=token`)",
+        "mitigation": "Use the authorization code flow with PKCE (`response_type=code`). The implicit flow returns the access token in the redirect URL, where history, referrers and injected scripts can read it; OAuth 2.1 removes it.",
+        "technique_id": "T1528",
+        "technique_name": "Steal Application Access Token",
+        "tactic": "Credential Access",
+    },
+    "oauth_redirect_uri_loose": {
+        "severity": "high",
+        "title": "OAuth redirect URI matched by prefix, suffix, substring or wildcard",
+        "mitigation": "Compare the redirect URI against an allow-list by exact string match (RFC 9700 §4.1.3). Prefix, suffix, substring and wildcard checks let `https://app.example.com.evil.net` or `https://evil.net/?x=app.example.com` through, and the authorization code or token is delivered to the attacker.",
+        "technique_id": "T1528",
+        "technique_name": "Steal Application Access Token",
+        "tactic": "Credential Access",
+    },
+    "oauth_missing_pkce": {
+        "severity": "medium",
+        "title": "Public OAuth client without PKCE",
+        "mitigation": "Browser and mobile clients can't keep a client secret, so send a `code_challenge` with `code_challenge_method=S256` and the matching `code_verifier` at the token exchange. Never disable PKCE or use `plain`. Without it an intercepted authorization code can be redeemed by anyone.",
+        "technique_id": "T1528",
+        "technique_name": "Steal Application Access Token",
+        "tactic": "Credential Access",
+    },
+    "session_fixation": {
+        "severity": "medium",
+        "title": "Session not regenerated at login (session fixation)",
+        "mitigation": "Issue a new session id when the user authenticates: `req.session.regenerate()` before storing the user (express-session), `session_regenerate_id(true)` in PHP. Otherwise a session id planted before login becomes an authenticated session for the attacker.",
+        "technique_id": "T1539",
+        "technique_name": "Steal Web Session Cookie",
+        "tactic": "Credential Access",
+    },
+    "session_weak_secret": {
+        "severity": "high",
+        "title": "Short session signing secret hard-coded in source",
+        "mitigation": "Load the session secret from a secret manager or the environment (no hard-coded fallback such as `'dev'`) and make it at least 256 bits of randomness. A known or brute-forced secret lets anyone sign session cookies; for Flask and cookie-session that is the whole session, including the user id.",
+        "technique_id": "T1606",
+        "technique_name": "Forge Web Credentials",
+        "tactic": "Credential Access",
+    },
+    "xxe": {
+        "severity": "high",
+        "title": "XML external entity (XXE) processing enabled",
+        "mitigation": "Disable DTD/external-entity resolution in the XML parser (lxml `resolve_entities=False`, Java `disallow-doctype-decl`/secure processing, PHP keep `libxml_disable_entity_loader` default). Prefer a data format without entities where possible.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "redos": {
+        "severity": "medium",
+        "title": "Regular expression vulnerable to catastrophic backtracking (ReDoS)",
+        "mitigation": "Rewrite the pattern to avoid nested quantifiers ((a+)+, (.*)*) and ambiguous alternation; use possessive quantifiers/atomic groups, a linear-time engine (RE2), or cap the length of user-supplied strings matched against it.",
+        "technique_id": "T1499",
+        "technique_name": "Endpoint Denial of Service",
+        "tactic": "Impact",
+    },
+    "insecure_upload": {
+        "severity": "high",
+        "title": "Uploaded file persisted with a client-controlled name/path",
+        "mitigation": "Never derive the stored path from the client filename. Generate a server-side name, store outside the web root, validate content type/size, and strip path separators before use.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "graphql_exposure": {
+        "severity": "low",
+        "title": "GraphQL introspection / playground enabled",
+        "mitigation": "Disable introspection and the GraphiQL/playground UI in production, and add query depth/complexity limits to prevent schema disclosure and expensive-query DoS.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "graphql_no_query_limits": {
+        "severity": "low",
+        "title": "GraphQL server without query depth or complexity limits",
+        "mitigation": "Bound query cost at the server: a depth limit (`graphql-depth-limit`, Strawberry `QueryDepthLimiter`, graphene `depth_limit_validator`), a complexity or cost limit (`graphql-query-complexity`, gqlgen `FixedComplexityLimit`), or GraphQL Armor. Deeply nested or aliased queries otherwise exhaust the server.",
+        "technique_id": "T1499.003",
+        "technique_name": "Endpoint Denial of Service: Application Exhaustion Flood",
+        "tactic": "Impact",
+    },
+    "graphql_batching": {
+        "severity": "medium",
+        "title": "GraphQL HTTP batching enabled",
+        "mitigation": "Disable batched HTTP requests unless clients need them. If they do, cap the batch size and rate-limit per operation, not per HTTP request, so one request can't carry thousands of login or OTP attempts.",
+        "technique_id": "T1110",
+        "technique_name": "Brute Force",
+        "tactic": "Credential Access",
+    },
+    "prompt_injection_attempt": {
+        "severity": "low",
+        "title": "Text aimed at automated reviewers (possible prompt injection)",
+        "mitigation": "Review who added these lines. Text addressed to automated (LLM-based) reviewers, instructions to disregard earlier rules, chat-template role tags or invisible/bidirectional Unicode in source are attempts to steer automated review (or hide code from humans, as in Trojan Source). AttackMap fences such content as untrusted and strips flagged lines from LLM excerpts; remove them from the code.",
+        "technique_id": "T1027",
+        "technique_name": "Obfuscated Files or Information",
+        "tactic": "Defense Evasion",
+    },
+}
+
+
+# Token-authentication kinds (#243: JWT and OAuth), tagged `token-auth` so
+# the benchmark scores them as one class.
+_TOKEN_AUTH_KINDS = frozenset(
+    {
+        "jwt_weakness",
+        "jwt_alg_confusion",
+        "jwt_unverified_decode",
+        "jwt_claims_unchecked",
+        "jwt_header_trust",
+        "jwt_weak_secret",
+        "oauth_missing_state",
+        "oauth_implicit_flow",
+        "oauth_redirect_uri_loose",
+        "oauth_missing_pkce",
+    }
+)
+# Session kinds (#243, part 2): the benchmark's `session_auth` class.
+_SESSION_AUTH_KINDS = frozenset({"session_fixation", "session_weak_secret"})
+
+
+def _auth_class_tag(kind: str) -> list[str]:
+    if kind in _TOKEN_AUTH_KINDS:
+        return ["token-auth"]
+    if kind in _SESSION_AUTH_KINDS:
+        return ["session-auth"]
+    return []
+
+
+# Rank for picking the most severe issue in an aggregated group.
+_SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2}
+
+
+def _cwe_tags(kind: str) -> list[str]:
+    """`external/cwe/cwe-NNN` finding tags from the taxonomy registry."""
+    entry = taxonomy_for(_rule_slug_kind(kind))
+    return [cwe_tag(c) for c in entry.cwe] if entry else []
+
+
+# Native C/C++ sinks (#189), emitted by the C/C++ analyzer plugins with a
+# per-instance severity and confidence: an input from the network or a request
+# traced to the sink in the same function is high, a local input (argv, env,
+# stdin, a file) medium, no traced input low. Findings are split per
+# (kind, severity tier) with `tiered_findings`; `tier` is the kind's usual
+# severity, which keeps the plain title and sets the SARIF rule metadata.
+_NATIVE_WEAKNESS_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "unbounded_copy": {
+        "tier": "high",
+        "title": "Unbounded buffer copy (strcpy/strcat/sprintf/gets)",
+        "mitigation": "Copy with an explicit destination size: `snprintf(dst, sizeof dst, \"%s\", src)`, `strlcpy`/`strlcat`, or `std::string`. Never use `gets` (use `fgets(buf, sizeof buf, stdin)`), and give every `scanf` `%s` a field width. Check the input length against the destination before copying.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "format_string": {
+        "tier": "high",
+        "title": "Non-constant printf-family format string",
+        "mitigation": "Pass data as an argument, never as the format: `printf(\"%s\", msg)`, `syslog(LOG_ERR, \"%s\", msg)`. Build with `-Wformat -Wformat-security` (and `-Werror=format-security`) so the compiler rejects non-literal formats.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "native_command_exec": {
+        "tier": "high",
+        "title": "OS command execution with a non-constant command (system/popen/exec)",
+        "mitigation": "Don't build shell command lines from input. Run the program directly with `execv`/`posix_spawn` and a fixed path and argument vector, validate each argument against an allow-list, and never pass input to `sh -c`, `system` or `popen`.",
+        "technique_id": "T1059.004",
+        "technique_name": "Command and Scripting Interpreter: Unix Shell",
+        "tactic": "Execution",
+    },
+    "tainted_copy_length": {
+        "tier": "high",
+        "title": "Memory copy with an input-controlled length (memcpy/memmove)",
+        "mitigation": "Bound the length by the destination before copying (`if (n > sizeof dst) reject;`), and never take a copy length straight from a packet or request header. Prefer containers that carry their own size.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "alloc_size_overflow": {
+        "tier": "high",
+        "title": "Allocation size computed from input without an overflow check",
+        "mitigation": "Check the multiplication before allocating (`if (n > SIZE_MAX / size) reject;`, `__builtin_mul_overflow`), or use `calloc(n, size)` / `reallocarray`, which fail on overflow. A wrapped size allocates a short buffer that the following writes overflow.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+}
+
+# Native weakness evidence (#189): the input the emitter traced to the sink.
+# `CodeWeakness.source_kind` is validated against these keys.
+_NATIVE_SOURCE_LABEL = {
+    "request": "request input",
+    "network": "network input",
+    "stdin": "standard input",
+    "argv": "command-line argument",
+    "env": "environment variable",
+    "file": "file contents",
+    "other": "other input",
+}
+
+
+def _native_evidence_line(w) -> str:
+    line = f"{w.file}:{w.line}" if w.line else w.file
+    if w.evidence_text:
+        line += f" — {w.evidence_text}"
+    if w.source_kind:
+        label = _NATIVE_SOURCE_LABEL.get(w.source_kind, "other input")
+        at = f" (line {w.source_line})" if w.source_line else ""
+        line += f" [input: {label}{at}]"
+    else:
+        line += " [no input source traced]"
+    return line
+
+
+# CI-workflow security (#142). Severity is taken from the emitted issues (some
+# kinds tier per instance — e.g. unpinned semver tag vs. branch ref), so the
+# spec carries only the title, remediation and ATT&CK mapping. CWE/OWASP ids
+# live in the taxonomy registry (`taxonomy.py`, #250).
+_WORKFLOW_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "script_injection": {
+        "title": "CI script injection via untrusted context in a run: step",
+        "mitigation": "Never interpolate `${{ github.event.* }}` / `github.head_ref` directly into a run: script — a crafted issue/PR title or branch name runs arbitrary shell. Bind the value to an `env:` variable and reference it as `\"$ENVVAR\"` so it's passed as data, not expanded into the command.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "pr_target_checkout": {
+        "title": "pull_request_target checks out untrusted PR code",
+        "mitigation": "`pull_request_target` runs with the base repo's secrets in scope. Don't check out and build the PR head ref in that context. Use `pull_request` for untrusted code, or check out only the base ref and never run fork-supplied build/test scripts with secrets available.",
+        "technique_id": "T1195",
+        "technique_name": "Supply Chain Compromise",
+        "tactic": "Initial Access",
+    },
+    "unpinned_action": {
+        "title": "Unpinned GitHub Action (not pinned to a commit SHA)",
+        "mitigation": "Pin third-party actions to a full 40-character commit SHA (`uses: org/action@<sha>`), not a moving tag or branch. A tag/branch lets the action owner — or anyone who compromises them — change what runs in your pipeline. Dependabot can keep the pinned SHAs updated.",
+        "technique_id": "T1195.001",
+        "technique_name": "Supply Chain Compromise: Compromise Software Dependencies and Development Tools",
+        "tactic": "Initial Access",
+    },
+    "secret_in_run": {
+        "title": "Secret interpolated into a run: shell step",
+        "mitigation": "Don't expand `${{ secrets.* }}` directly into a run: script — it can leak via the command line (`ps`), step logs, or a child process. Pass the secret through the step's `env:` block and reference it as an environment variable.",
+        "technique_id": "T1552",
+        "technique_name": "Unsecured Credentials",
+        "tactic": "Credential Access",
+    },
+    "broad_permissions": {
+        "title": "Over-broad GITHUB_TOKEN permissions (write-all)",
+        "mitigation": "Set least-privilege `permissions:` per job (default to `contents: read` and grant only what a job needs). `write-all` gives a compromised step or action full write access to the repo, releases, packages, and more.",
+        "technique_id": "T1078",
+        "technique_name": "Valid Accounts",
+        "tactic": "Privilege Escalation",
+    },
+    "self_hosted_pr": {
+        "title": "Self-hosted runner exposed to pull-request code",
+        "mitigation": "Self-hosted runners on a `pull_request`/`pull_request_target` trigger let fork PRs run arbitrary code on your infrastructure (and persist between jobs). Use ephemeral GitHub-hosted runners for public-repo PR workflows, or gate self-hosted jobs behind an environment/approval and never on `pull_request_target`.",
+        "technique_id": "T1584.004",
+        "technique_name": "Compromise Infrastructure: Server",
+        "tactic": "Resource Development",
+    },
+    # #246
+    "workflow_run_artifact_poisoning": {
+        "title": "workflow_run consumes untrusted artifacts or code from the triggering run",
+        "mitigation": "A `workflow_run` job runs with the base repo's token and secrets, but the triggering run's artifacts and head commit come from the (possibly forked) PR. Treat downloaded artifacts as untrusted data: extract them outside the workspace, never execute or `source` them, validate their contents, and don't check out `github.event.workflow_run.head_sha` in a privileged job.",
+        "technique_id": "T1195.002",
+        "technique_name": "Supply Chain Compromise: Compromise Software Supply Chain",
+        "tactic": "Initial Access",
+    },
+    "issue_comment_pr_checkout": {
+        "title": "issue_comment workflow checks out and runs pull-request code",
+        "mitigation": "`issue_comment` workflows (\"/ok-to-test\", \"/deploy\") run with the base repo's token and secrets. Checking out `refs/pull/N/head` or running `gh pr checkout` there executes fork code with those privileges — and the PR can change after the comment. Gate on `author_association`, pin the checkout to the commit SHA the maintainer reviewed, and run untrusted code in an unprivileged `pull_request` workflow instead.",
+        "technique_id": "T1195.002",
+        "technique_name": "Supply Chain Compromise: Compromise Software Supply Chain",
+        "tactic": "Initial Access",
+    },
+    "github_script_injection": {
+        "title": "CI code injection via untrusted context in actions/github-script",
+        "mitigation": "`actions/github-script`'s `script:` is JavaScript evaluated with the token in scope; `${{ github.event.* }}` inside it is spliced in before evaluation. Pass the value through `env:` and read it as `process.env.NAME`, or read it from `context.payload` inside the script.",
+        "technique_id": "T1059.007",
+        "technique_name": "Command and Scripting Interpreter: JavaScript",
+        "tactic": "Execution",
+    },
+    "github_env_injection": {
+        "title": "Untrusted value written to $GITHUB_ENV / $GITHUB_PATH",
+        "mitigation": "A newline in an attacker-controlled value written to `$GITHUB_ENV` defines arbitrary variables (`LD_PRELOAD`, `NODE_OPTIONS`, `BASH_ENV`) for every later step; `$GITHUB_PATH` hijacks executables. Don't write untrusted input to these files; if you must, strip newlines and use a random heredoc delimiter, or pass it via `env:` on the step that needs it.",
+        "technique_id": "T1574",
+        "technique_name": "Hijack Execution Flow",
+        "tactic": "Persistence",
+    },
+    "default_token_permissions": {
+        "title": "Workflow relies on default GITHUB_TOKEN permissions",
+        "mitigation": "Add a top-level `permissions:` block (e.g. `permissions: { contents: read }`) and grant extra scopes per job. Without it the token gets the repository/organization default, which is read/write on many older repositories and organizations.",
+        "technique_id": "T1078",
+        "technique_name": "Valid Accounts",
+        "tactic": "Privilege Escalation",
+    },
+    "oidc_on_untrusted_trigger": {
+        "title": "OIDC token (id-token: write) available to pull-request-triggered workflow",
+        "mitigation": "`id-token: write` lets any step mint an OIDC token your cloud trusts. Don't grant it on `pull_request_target`, `issue_comment` or `workflow_run` workflows that touch PR input; move deployment to a `push`/`release` workflow behind a protected environment, and scope the cloud trust policy to `ref:refs/heads/main`.",
+        "technique_id": "T1078.004",
+        "technique_name": "Valid Accounts: Cloud Accounts",
+        "tactic": "Privilege Escalation",
+    },
+    "secrets_inherit": {
+        "title": "Reusable workflow receives every secret (secrets: inherit)",
+        "mitigation": "`secrets: inherit` passes all repository and organization secrets to the called workflow. List only the secrets it needs (`secrets: { NPM_TOKEN: ${{ secrets.NPM_TOKEN }} }`) and pin the reusable workflow to a commit SHA.",
+        "technique_id": "T1552",
+        "technique_name": "Unsecured Credentials",
+        "tactic": "Credential Access",
+    },
+    "checkout_persist_credentials": {
+        "title": "actions/checkout leaves the token in .git/config for untrusted code",
+        "mitigation": "`actions/checkout` persists the `GITHUB_TOKEN` in `.git/config` by default. On `pull_request_target` / `issue_comment` / `workflow_run` jobs that later run PR code or artifacts, set `persist-credentials: false` so that code can't read the write-capable token.",
+        "technique_id": "T1552.001",
+        "technique_name": "Unsecured Credentials: Credentials In Files",
+        "tactic": "Credential Access",
+    },
+    "cache_poisoning_pr_target": {
+        "title": "Actions cache written from untrusted PR context (cache poisoning)",
+        "mitigation": "Caches saved in a `pull_request_target` job land in the base branch's cache scope, so PR code (or a PR-chosen key) can poison what `push`/release builds restore. Don't use `actions/cache` or `setup-*` `cache:` in jobs that run PR code; use `actions/cache/restore` only, or run untrusted builds under `pull_request`.",
+        "technique_id": "T1195.002",
+        "technique_name": "Supply Chain Compromise: Compromise Software Supply Chain",
+        "tactic": "Initial Access",
+    },
+    "docker_action_unpinned": {
+        "title": "Docker action image not pinned by digest",
+        "mitigation": "`uses: docker://image:tag` (or a docker `action.yml` image) follows a mutable tag. Pin it by digest (`docker://image@sha256:<digest>`) so a re-pushed tag can't change what runs in the pipeline.",
+        "technique_id": "T1195.001",
+        "technique_name": "Supply Chain Compromise: Compromise Software Dependencies and Development Tools",
+        "tactic": "Initial Access",
+    },
+    "curl_pipe_shell": {
+        "title": "Remote script piped into a shell in CI (curl | sh)",
+        "mitigation": "`curl … | sh` runs whatever the server returns at build time, with the job's token and secrets in scope. Download to a file, verify a pinned checksum or signature, then execute — or use a pinned action/package instead.",
+        "technique_id": "T1105",
+        "technique_name": "Ingress Tool Transfer",
+        "tactic": "Command and Control",
+    },
+}
+
+
+
+# Dependency supply-chain risk beyond CVEs (#247). Severity comes from the
+# emitted issues (tiered per instance, e.g. locked vs unlocked).
+_SUPPLY_CHAIN_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "dependency_confusion": {
+        "title": "Dependency confusion risk: internal package names resolvable from a public registry",
+        "mitigation": "Install private packages from a single index that proxies the public one (`--index-url`, not `--extra-index-url`); publish npm packages under an owned scope with an `@org:registry=` mapping; register placeholder names on the public registry for internal packages.",
+        "technique_id": "T1195.001",
+        "technique_name": "Supply Chain Compromise: Compromise Software Dependencies and Development Tools",
+        "tactic": "Initial Access",
+    },
+    "typosquat_candidate": {
+        "title": "Possible typosquatted dependency (one edit from a popular package)",
+        "mitigation": "Confirm the dependency is the package you meant (check the registry page, maintainers and download counts). If it's a typo of the popular package, replace it and audit any machine that installed it.",
+        "technique_id": "T1195.001",
+        "technique_name": "Supply Chain Compromise: Compromise Software Dependencies and Development Tools",
+        "tactic": "Initial Access",
+    },
+    "mutable_vcs_dependency": {
+        "title": "Dependency pinned to a mutable git ref, URL or fork",
+        "mitigation": "Pin VCS dependencies to a full commit SHA (`git+https://…@<sha>`, `github:user/repo#<sha>`, Cargo `rev = \"<sha>\"`), add a hash to archive URLs (`#sha256=` / `--hash=`), and prefer published registry releases over forks.",
+        "technique_id": "T1195.001",
+        "technique_name": "Supply Chain Compromise: Compromise Software Dependencies and Development Tools",
+        "tactic": "Initial Access",
+    },
+    "install_script": {
+        "title": "Dependency install scripts run code at install time",
+        "mitigation": "Install with `--ignore-scripts` in CI and allow-list the packages that need build steps. Never pipe a download into a shell from an install hook; vendor or checksum-verify the script instead.",
+        "technique_id": "T1059",
+        "technique_name": "Command and Scripting Interpreter",
+        "tactic": "Execution",
+    },
+    "unlocked_manifest": {
+        "title": "Dependencies resolved without a lockfile or integrity hashes",
+        "mitigation": "Commit the lockfile (`package-lock.json`, `composer.lock`, `Pipfile.lock`) and install with the frozen/ci mode (`npm ci`, `composer install`); regenerate lockfile entries that lack an `integrity` hash.",
+        "technique_id": "T1195.001",
+        "technique_name": "Supply Chain Compromise: Compromise Software Dependencies and Development Tools",
+        "tactic": "Initial Access",
+    },
+    "insecure_registry": {
+        "title": "Package registry reached over plain HTTP or without TLS verification",
+        "mitigation": "Use `https://` for every registry and index URL, and remove `strict-ssl=false` / `--trusted-host` so a network attacker can't substitute packages in transit.",
+        "technique_id": "T1557",
+        "technique_name": "Adversary-in-the-Middle",
+        "tactic": "Credential Access",
+    },
+}
+
+# Cloud / IaC / container-runtime misconfigurations (terraform#4, iac#1),
+# reported by IaC plugins as `CloudMisconfig` records. Severity comes from the
+# records (plugins tier per instance: a docker.sock mount outranks /var/log),
+# and core emits one finding per (kind, severity) so each instance keeps its
+# own severity in SARIF, the diff gate and the report. `tier` is the kind's
+# usual severity: its finding keeps the plain title; other tiers get a
+# "(<severity>-severity instances)" suffix, so titles (and finding ids)
+# depend only on the tier. CWE/OWASP/ATT&CK ids live in `taxonomy.py`.
+_CLOUD_MISCONFIG_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "iac_module_unpinned": {
+        "tier": "medium",
+        "title": "Infrastructure module is sourced from a mutable reference",
+        "mitigation": "Pin git module sources to a commit SHA or release tag (`?ref=v1.2.3`), and give every registry module an exact `version`. A branch or an unpinned source lets whoever controls it change what `terraform apply` builds.",
+    },
+    "public_network_access": {
+        "tier": "medium",
+        "title": "Cloud resource is reachable from the public internet",
+        "mitigation": "Turn off public network access (`public_network_access_enabled = false`, no public IP, `publicly_accessible = false`) and reach the resource through private endpoints, a VPN or a bastion.",
+    },
+    "public_cluster_endpoint": {
+        "tier": "medium",
+        "title": "Kubernetes API endpoint is open to the internet",
+        "mitigation": "Disable the public endpoint (`endpoint_public_access = false`) or restrict it with `public_access_cidrs` to the networks that administer the cluster.",
+    },
+    "plaintext_listener": {
+        "tier": "medium",
+        "title": "Load balancer serves plain HTTP without redirecting to HTTPS",
+        "mitigation": "Make the HTTP listener's default action a 301 redirect to HTTPS, and serve traffic only on an HTTPS/TLS listener with a current TLS policy.",
+    },
+    "api_no_authorizer": {
+        "tier": "medium",
+        "title": "API Gateway route accepts unauthenticated requests",
+        "mitigation": "Attach an authorizer (IAM, Cognito, JWT or a Lambda authorizer) to every route that isn't meant to be public. API Gateway's default authorization is NONE, so a route without one is open to the internet.",
+    },
+    "unencrypted_storage": {
+        "tier": "medium",
+        "title": "Data store is not encrypted at rest",
+        "mitigation": "Enable encryption at rest (`storage_encrypted = true`, ideally with a customer-managed KMS key). Existing unencrypted instances need a snapshot-and-restore to an encrypted copy.",
+    },
+    "public_data_access": {
+        "tier": "high",
+        "title": "Storage or search data is readable by anyone",
+        "mitigation": "Remove public grants (`allUsers`, `Principal \"*\"` without a condition, public ACLs), keep the account-level public-access block on, and share data through signed URLs or scoped principals instead.",
+    },
+    "public_invoker": {
+        "tier": "low",
+        "title": "Serverless function or service can be invoked by anyone",
+        "mitigation": "If the function isn't meant to be public, require authentication on its endpoint: bind the invoker role to specific service accounts or groups instead of `allUsers` / `allAuthenticatedUsers` (Cloud Run, Cloud Functions), or use `authorization_type = \"AWS_IAM\"` on a Lambda function URL.",
+    },
+    "privileged_container": {
+        "tier": "high",
+        "title": "Container runs privileged (equivalent to root on the host)",
+        "mitigation": "Remove `privileged: true`. Grant the one capability the workload needs (`capabilities.add`) instead, and enforce the Pod Security `restricted` (or at least `baseline`) profile on the namespace.",
+    },
+    "privilege_escalation_allowed": {
+        "tier": "medium",
+        "title": "Container allows privilege escalation",
+        "mitigation": "Set `allowPrivilegeEscalation: false` in every container's securityContext so setuid binaries and file capabilities can't raise the process's privileges.",
+    },
+    "container_runs_as_root": {
+        "tier": "medium",
+        "title": "Container runs as root",
+        "mitigation": "Add a non-root `USER` to the image's final stage, and set `runAsNonRoot: true` with a non-zero `runAsUser` in the pod securityContext.",
+    },
+    "missing_security_context": {
+        "tier": "low",
+        "title": "Workload has no restrictive security context",
+        "mitigation": "Give each pod a securityContext with `runAsNonRoot: true`, and each container `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true` and `capabilities: {drop: [ALL]}`.",
+    },
+    "host_path_mount": {
+        "tier": "high",
+        "title": "Workload mounts a sensitive host path",
+        "mitigation": "Replace hostPath volumes with emptyDir, a PVC, a ConfigMap or a CSI driver. Never mount the container runtime socket or the host root; if a node agent truly needs a host path, mount the narrowest path read-only.",
+    },
+    "host_namespace_shared": {
+        "tier": "high",
+        "title": "Workload shares the host's network, PID or IPC namespace",
+        "mitigation": "Remove `hostNetwork`, `hostPID` and `hostIPC` (compose: `network_mode: host`, `pid: host`, `ipc: host`). Publish ports through a Service or port mapping instead.",
+    },
+    "dangerous_capability": {
+        "tier": "high",
+        "title": "Container is granted a dangerous Linux capability",
+        "mitigation": "Drop `ALL` capabilities and add back only what the workload needs. `SYS_ADMIN`, `SYS_PTRACE`, `SYS_MODULE`, `NET_ADMIN` and `ALL` let a compromised process break out of the container or take over the node's network.",
+    },
+    "security_profile_disabled": {
+        "tier": "medium",
+        "title": "Container seccomp or AppArmor confinement is disabled",
+        "mitigation": "Use the runtime's default seccomp profile (`seccompProfile: RuntimeDefault`) and AppArmor profile instead of `unconfined`.",
+    },
+    "exposed_service": {
+        "tier": "low",
+        "title": "Kubernetes Service is exposed outside the cluster without source ranges",
+        "mitigation": "Use a ClusterIP Service behind an authenticated Ingress, mark the load balancer internal, or restrict it with `loadBalancerSourceRanges`.",
+    },
+    "unpinned_container_image": {
+        "tier": "low",
+        "title": "Container image uses a mutable tag (`latest` or none)",
+        "mitigation": "Pin images to a version tag, ideally with its digest (`image:1.2.3@sha256:…`), so a pushed tag can't change what runs.",
+    },
+    "dockerfile_remote_add": {
+        "tier": "medium",
+        "title": "Dockerfile ADD downloads a remote file without a checksum",
+        "mitigation": "Download with a pinned version and verify a checksum or signature (`ADD --checksum=sha256:…`, or `curl` plus `sha256sum -c` in a RUN step) before using the file.",
+    },
+    "dockerfile_curl_pipe_shell": {
+        "tier": "medium",
+        "title": "Image build pipes a downloaded script into a shell",
+        "mitigation": "Download the script to a file, verify its checksum or signature, then run it, or install the tool from a package manager with signature checks.",
+    },
+    "rbac_wildcard": {
+        "tier": "high",
+        "title": "RBAC role grants wildcard verbs or resources",
+        "mitigation": "List the exact resources and verbs the subject needs. A `*` verb or resource also grants every resource type added later, including Secrets and RBAC objects.",
+    },
+    "rbac_escalation": {
+        "tier": "high",
+        "title": "RBAC role can escalate privileges (escalate, bind, impersonate or pods/exec)",
+        "mitigation": "Remove `escalate`, `bind` and `impersonate` from roles that don't administer RBAC, and grant `pods/exec` / `pods/attach` only to operators who need a shell in the pod.",
+    },
+    "rbac_secret_access": {
+        "tier": "medium",
+        "title": "RBAC role can read Kubernetes Secrets",
+        "mitigation": "Scope Secret access to a namespaced Role with `resourceNames` for the specific Secrets the workload uses, and avoid `list`/`watch` (which return every Secret's contents).",
+    },
+    "cluster_admin_binding": {
+        "tier": "high",
+        "title": "Binding grants cluster-admin or binds a broad built-in group",
+        "mitigation": "Bind `cluster-admin` only to named human administrators, never to service accounts or to `system:authenticated` / `system:unauthenticated` / `system:anonymous`. Give workloads a dedicated Role with the permissions they need.",
+    },
+}
+
+# Spec tables whose findings are split by severity tier (see `tiered_findings`).
+_TIERED_SPEC_TABLES: tuple[dict[str, dict[str, str]], ...] = (
+    _CLOUD_MISCONFIG_FINDING_SPEC,
+    _NATIVE_WEAKNESS_FINDING_SPEC,
+)
+
+
+def check_tiered_tables(tables: tuple[dict[str, dict[str, str]], ...]) -> None:
+    """Every tiered kind is in one table only and has a valid default tier,
+    so `tiered_rule_defaults` can't silently pick the wrong spec."""
+    seen: dict[str, int] = {}
+    for index, table in enumerate(tables):
+        for kind, spec in table.items():
+            if kind in seen:
+                raise ValueError(f"tiered kind {kind!r} is registered twice (tables {seen[kind]} and {index})")
+            if spec.get("tier") not in {"high", "medium", "low"}:
+                raise ValueError(f"tiered kind {kind!r} has no valid default tier")
+            seen[kind] = index
+
+
+check_tiered_tables(_TIERED_SPEC_TABLES)
+
+# App attack surface reported by platform plugins (#188, #190): the Apple
+# analyzers (Swift, Objective-C). Severity is per instance (a global ATS
+# exception outranks a per-domain one), so the finding takes the max; the spec
+# severity is the catalog's default. CWE/OWASP ids live in `taxonomy.py`.
+_APP_SURFACE_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "apple_ats_insecure_loads": {
+        "severity": "medium",
+        "confidence": "high",
+        "title": "App Transport Security exceptions allow cleartext HTTP",
+        "mitigation": "Remove `NSAllowsArbitraryLoads` and serve every endpoint over HTTPS (TLS 1.2+). If one legacy host truly needs HTTP, scope an `NSExceptionDomains` entry to that host and document why; for devices on the local network use `NSAllowsLocalNetworking` instead of disabling ATS.",
+        "technique_id": "T1557",
+        "technique_name": "Adversary-in-the-Middle",
+        "tactic": "Credential Access / Collection",
+    },
+    "apple_custom_url_scheme": {
+        "severity": "low",
+        "confidence": "high",
+        "title": "Custom URL scheme handler accepts links from any app or web page",
+        "mitigation": "Treat every incoming URL as untrusted input: allow-list the hosts, paths and parameters the handler acts on, and ask the user before any state-changing action. Any app can register the same scheme, so never deliver tokens or OAuth codes through it; use universal links (associated domains) or `ASWebAuthenticationSession` for auth callbacks.",
+        "technique_id": "T1204.001",
+        "technique_name": "User Execution: Malicious Link",
+        "tactic": "Execution",
+    },
+    "apple_webview_js_injection": {
+        "severity": "medium",
+        "confidence": "medium",
+        "title": "WKWebView JavaScript is built by string interpolation (script injection risk)",
+        "mitigation": "Don't splice values into JavaScript source. Pass them as arguments with `callAsyncJavaScript(_:arguments:in:in:)`, or JSON-encode them (`JSONEncoder`/`JSONSerialization`) before embedding, so page content, URL fragments or user input can't break out of the string literal.",
+        "technique_id": "T1059.007",
+        "technique_name": "Command and Scripting Interpreter: JavaScript",
+        "tactic": "Execution",
+    },
+    "apple_insecure_secret_storage": {
+        "severity": "medium",
+        "confidence": "medium",
+        "title": "Secrets are stored in UserDefaults instead of the Keychain",
+        "mitigation": "UserDefaults is an unencrypted plist in the app container and lands in backups. Store tokens, passwords and keys in the Keychain (`SecItemAdd` with a `kSecAttrAccessible...ThisDeviceOnly` class) and delete the old UserDefaults value on upgrade.",
+        "technique_id": "T1552.001",
+        "technique_name": "Unsecured Credentials: Credentials In Files",
+        "tactic": "Credential Access",
+    },
+    "apple_pasteboard_secret": {
+        "severity": "low",
+        "confidence": "medium",
+        "title": "Secret values are copied to the general pasteboard",
+        "mitigation": "Any app (and Universal Clipboard on nearby devices) can read the general pasteboard. Don't copy secrets; if the user must, set `localOnly` and an `expirationDate` with `UIPasteboard.setItems(_:options:)`.",
+        "technique_id": "T1115",
+        "technique_name": "Clipboard Data",
+        "tactic": "Collection",
+    },
+    "apple_hardened_runtime_exception": {
+        "severity": "medium",
+        "confidence": "high",
+        "title": "Entitlements weaken the hardened runtime (library validation, DYLD variables or executable memory)",
+        "mitigation": "Drop `com.apple.security.cs.disable-library-validation`, `allow-dyld-environment-variables`, `allow-unsigned-executable-memory` and `disable-executable-page-protection` unless a plug-in model or JIT truly needs them. They let an attacker inject code into the signed process; if one is required, confine the code that needs it to a separate helper.",
+        "technique_id": "T1574",
+        "technique_name": "Hijack Execution Flow",
+        "tactic": "Stealth / Execution",
+    },
+    "apple_debuggable_entitlement": {
+        "severity": "low",
+        "confidence": "high",
+        "title": "Entitlements allow debugger attachment (get-task-allow)",
+        "mitigation": "`get-task-allow` lets other processes attach to the app and read or patch its memory. Keep it out of committed entitlements and let Xcode add it to Debug builds only; release and notarized builds must not carry it.",
+        "technique_id": "T1055",
+        "technique_name": "Process Injection",
+        "tactic": "Stealth / Privilege Escalation",
+    },
+    "apple_xpc_unvalidated_peer": {
+        "severity": "high",
+        "confidence": "medium",
+        "title": "XPC listener accepts connections without validating the peer",
+        "mitigation": "In `listener(_:shouldAcceptNewConnection:)` verify the client before accepting: set `setCodeSigningRequirement(_:)` (macOS 13+) or check the connection's audit token against a code-signing requirement with `SecCodeCopyGuestWithAttributes` + `SecCodeCheckValidity`. Never authorize by PID alone.",
+        "technique_id": "T1068",
+        "technique_name": "Exploitation for Privilege Escalation",
+        "tactic": "Privilege Escalation",
+    },
+    "apple_dynamic_dispatch": {
+        "severity": "medium",
+        "confidence": "medium",
+        "title": "Classes, selectors or libraries are resolved from strings built at runtime",
+        "mitigation": "Map external values to an allow-list of known classes/selectors instead of building names with string formatting, and load libraries only from fixed paths inside the signed bundle. A name or path an attacker can influence selects arbitrary code.",
+        "technique_id": "T1129",
+        "technique_name": "Shared Modules",
+        "tactic": "Execution",
+    },
+}
+
+_ANOMALY_FINDING_SPEC: dict[str, dict[str, str]] = {
+    "auth_outlier": {
+        "severity": "high",
+        "title": "Authorization outlier — route missing an auth check its siblings enforce",
+        "mitigation": "Confirm whether the flagged route is intended to be public. If not, apply the same auth/authorization guard its sibling routes use (decorator, middleware, or policy). Inconsistent enforcement across a resource cohort is a common source of broken access control.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "validation_outlier": {
+        "severity": "medium",
+        "title": "Validation outlier — handler skips input validation its peers apply",
+        "mitigation": "Apply the same input validation/schema its sibling handlers use. An unvalidated state-changing endpoint among validated peers is a likely gap for injection or malformed-input bugs.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "method_outlier": {
+        "severity": "medium",
+        "title": "Method outlier — lone state-changing endpoint in a read-only cohort",
+        "mitigation": "Verify the state-changing endpoint is intended and adequately protected. A single write method among an otherwise read-only resource cohort can indicate an accidentally-exposed mutation.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+    "invariant_violation": {
+        "severity": "high",
+        "title": "Invariant violation — handler reaches a dangerous sink without the guard its peers apply",
+        "mitigation": "Confirm whether the flagged handler should reach this sink unguarded. If not, apply the same auth/validation guard its sibling handlers place before the sink. A mined invariant broken by a single site is a common shape for a forgotten check on an injection or access-control path.",
+        "technique_id": "T1190",
+        "technique_name": "Exploit Public-Facing Application",
+        "tactic": "Initial Access",
+    },
+}
+
+
+def _numeric_to_confidence(value: float) -> str:
+    """Map an anomaly's numeric confidence onto the Finding scale."""
+    if value >= 0.75:
+        return "high"
+    if value >= 0.55:
+        return "medium"
+    return "low"
+
+
+# ---- Severity-tiered findings (shared) -------------------------------------
+# A detector family whose records carry their own severity emits one finding
+# per (kind, severity tier), so each instance keeps its severity in SARIF, the
+# --fail-on-new-high gate and the report. Its spec table gives every kind a
+# `tier` (the kind's usual severity) and is listed in `_TIERED_SPEC_TABLES`, so
+# SARIF rule metadata comes from that default tier, not from whichever tier
+# happens to come first.
+_SEVERITY_TIERS = ("high", "medium", "low")
+
+
+def tier_title(title: str, tier: str, default_tier: str) -> str:
+    """The kind's usual tier keeps the plain title; other tiers get a suffix.
+    Depends only on the tier, so adding a low instance never renames (re-ids)
+    the high finding, and each tier has its own finding id."""
+    return title if tier == default_tier else f"{title} ({tier}-severity instances)"
+
+
+def tiered_findings(
+    kind: str,
+    spec: dict[str, str],
+    items: list,
+    *,
+    evidence: Callable[[Any], str],
+    locations: Callable[[list], list[FindingLocation]] | None = None,
+    tags: list[str],
+    attack_techniques: list[AttackTechnique] | None = None,
+) -> list[Finding]:
+    """One finding per severity tier of ``items`` (records with `severity`
+    and a `confidence`: numeric, low/medium/high, or unset = medium).
+    Confidence is the max over the tier's records; evidence lists the most
+    confident first (stable, so callers can pre-sort ties), capped at 10."""
+    out: list[Finding] = []
+    for tier in _SEVERITY_TIERS:
+        tier_items = sorted((i for i in items if i.severity == tier), key=lambda i: -_confidence_value(i))
+        if not tier_items:
+            continue
+        lines = [evidence(i) for i in tier_items[:10]]
+        if len(tier_items) > 10:
+            lines.append(f"+{len(tier_items) - 10} more occurrence(s)")
+        out.append(
+            Finding(
+                title=tier_title(spec["title"], tier, spec["tier"]),
+                rule_id=_rule_slug_kind(kind),
+                severity=tier,  # type: ignore[arg-type]
+                evidence=lines,
+                locations=(locations or instance_locs)(tier_items),
+                mitigation=spec["mitigation"],
+                confidence=_numeric_to_confidence(_confidence_value(tier_items[0])),  # type: ignore[arg-type]
+                tags=list(tags),
+                attack_techniques=list(attack_techniques or []),
+            )
+        )
+    return out
+
+
+# Low/medium/high confidences on the numeric scale `_numeric_to_confidence`
+# reads back (the same scale `merge.keep_more_severe` ranks by).
+_CONFIDENCE_VALUE = {"low": 0.3, "medium": 0.6, "high": 0.9}
+
+
+def _confidence_value(item: Any) -> float:
+    value = getattr(item, "confidence", None)
+    if isinstance(value, str):
+        return _CONFIDENCE_VALUE.get(value, 0.6)
+    return 0.6 if value is None else float(value)
+
+
+def tiered_rule_defaults(rule_id: str) -> tuple[str, str, str] | None:
+    """``(title, default tier, mitigation)`` of a severity-tiered rule, for
+    SARIF rule metadata; None for other rules."""
+    kind = rule_id.replace("-", "_")
+    for table in _TIERED_SPEC_TABLES:
+        spec = table.get(kind)
+        if spec is not None:
+            return spec["title"], spec["tier"], spec["mitigation"]
+    return None
+
+
+def instance_locs(items: list) -> list[FindingLocation]:
+    """One location per record of a tiered family, carrying an `instance`
+    key (resource + evidence) for its fingerprint. Unlike `_locs`, two
+    resources at the same (file, line) — or both without a line — stay two
+    locations."""
+    out: list[FindingLocation] = []
+    seen: set[tuple] = set()
+    for item in items:
+        instance = "\x1f".join(str(getattr(item, a, None) or "") for a in ("resource", "evidence_text"))
+        key = (item.file, item.line, instance)
+        if key not in seen:
+            seen.add(key)
+            out.append(FindingLocation(file=item.file, line=item.line, instance=instance))
+    return out
+
+
+def _cloud_misconfig_evidence(issue: CloudMisconfig) -> str:
+    """`file:line [resource] — evidence (context) → escalation path`."""
+    text = f"{issue.file}:{issue.line}" if issue.line else issue.file
+    if issue.resource:
+        text += f" [{issue.resource}]"
+    if issue.evidence_text:
+        text += f" — {issue.evidence_text}"
+    if issue.context:
+        text += f" ({issue.context})"
+    if issue.escalation_path:
+        text += f" → {issue.escalation_path}"
+    return text
+
+
+def _taint_by_route_file(scan: ScanResult) -> dict[str, list[TaintChain]]:
+    """Group taint chains by originating route file for fast lookup."""
+    out: dict[str, list[TaintChain]] = {}
+    for chain in scan.taint_chains:
+        out.setdefault(chain.route_file, []).append(chain)
+    return out
+
+
+def _best_taint_for_route(
+    route: Route, taint_by_file: dict[str, list[TaintChain]]
+) -> TaintChain | None:
+    candidates = [
+        c
+        for c in taint_by_file.get(route.file, ())
+        if c.route_path == route.path
+        and c.route_method == route.method
+        and not c.sanitized  # #137: a neutralized path isn't a probable exploit
+        and not c.speculative  # #148a: an unconfirmed recall lead isn't a probable exploit
+    ]
+    if not candidates:
+        return None
+    # Prefer the closest sink (fewest import hops); break ties by confidence.
+    return min(candidates, key=lambda c: (c.hops, -c.confidence))
+
+
+def _build_probable_chains(scan: ScanResult) -> list[ProbableChain]:
+    controllers = _extract_prefixed_hints(scan, "controller:")
+    services = _extract_prefixed_hints(scan, "service:")
+    taint_by_file = _taint_by_route_file(scan)
+    # Framework-family hints from the Omeka/Laminas analyzers. These aren't
+    # required to build a chain but they *strengthen* the evidence when
+    # present — see #13. Each contributes a small confidence bump and an
+    # evidence line naming the file it came from.
+    laminas_mappings = _extract_prefixed_hints(scan, "laminas_controller_mapping")
+    laminas_deps = _extract_prefixed_hints(scan, "laminas_dependency")
+    omeka_deps = _extract_prefixed_hints(scan, "omeka_dependency")
+    omeka_extensions = _extract_prefixed_hints(scan, "omeka_extension:")
+    omeka_surfaces = _extract_prefixed_hints(scan, "omeka_surface:")
+
+    # Provenance index: hint value -> source_analyzer, so we can name the
+    # analyzer that emitted each contributing signal in the chain evidence
+    # (#14).
+    provenance = _provenance_by_hint(scan)
+
+    db_by_module = {_file_module_key(db.file): db for db in scan.databases}
+    external_by_module = {_file_module_key(call.file): call for call in scan.external_calls}
+
+    chains: list[ProbableChain] = []
+    for route in _runtime_routes(scan):
+        module_key = _file_module_key(route.file)
+        evidence = [f"route {route.method} {route.path} in {route.file}"]
+        confidence = 0.35
+
+        route_controller = next((name for name, file in controllers if file == route.file), None)
+        if route_controller is None:
+            route_controller = next((name for name, file in controllers if _file_module_key(file) == module_key), None)
+            if route_controller:
+                confidence += 0.15
+                evidence.append(
+                    _cited("controller inferred by module proximity", route_controller, provenance, f"controller:{route_controller}")
+                )
+        else:
+            confidence += 0.25
+            evidence.append(
+                _cited("controller in same file", route_controller, provenance, f"controller:{route_controller}")
+            )
+
+        route_service = next((name for name, file in services if file == route.file), None)
+        if route_service is None:
+            route_service = next((name for name, file in services if _file_module_key(file) == module_key), None)
+            if route_service:
+                confidence += 0.10
+                evidence.append(
+                    _cited("service inferred by module proximity", route_service, provenance, f"service:{route_service}")
+                )
+        else:
+            confidence += 0.20
+            evidence.append(
+                _cited("service in same file", route_service, provenance, f"service:{route_service}")
+            )
+
+        # Framework-family reinforcement. Each additional Omeka/Laminas
+        # signal in the same module bumps confidence a little; a route
+        # that lands on Omeka admin surface with an extension binding
+        # ends up in the `high` bucket.
+        for label, hints, weight, key_prefix in (
+            ("laminas controller mapping", laminas_mappings, 0.05, "laminas_controller_mapping"),
+            ("laminas dependency", laminas_deps, 0.03, "laminas_dependency"),
+            ("omeka dependency", omeka_deps, 0.03, "omeka_dependency"),
+            ("omeka extension binding", omeka_extensions, 0.05, "omeka_extension:"),
+        ):
+            same_module_hint = next(
+                (name for name, file in hints if _file_module_key(file) == module_key),
+                None,
+            )
+            if same_module_hint is not None:
+                confidence += weight
+                evidence.append(
+                    _cited(label, same_module_hint or "(marker)", provenance, f"{key_prefix}{same_module_hint or ''}".rstrip(":"))
+                )
+
+        # Omeka surface (admin / api / site) classification. Doesn't
+        # affect chain confidence directly — the route's surface risk is
+        # handled elsewhere — but naming the surface in evidence gives
+        # readers of the attack path a domain-shaped hook.
+        omeka_surface = next(
+            (name for name, file in omeka_surfaces if _file_module_key(file) == module_key),
+            None,
+        )
+        if omeka_surface is not None:
+            evidence.append(
+                _cited("omeka surface classification", omeka_surface, provenance, f"omeka_surface:{omeka_surface}")
+            )
+
+        sink = "privileged action"
+        best_taint = _best_taint_for_route(route, taint_by_file)
+        if module_key in db_by_module:
+            sink = "database"
+            confidence += 0.2
+            evidence.append(f"database hint in same module: {db_by_module[module_key].kind} ({db_by_module[module_key].file})")
+        elif module_key in external_by_module:
+            sink = "external integration"
+            confidence += 0.15
+            evidence.append(f"external call in same module: {external_by_module[module_key].target} ({external_by_module[module_key].file})")
+        elif best_taint is not None:
+            # Taint chain gives us a specific cross-file sink cite —
+            # stronger than the "sink somewhere in repo" fallback (#45).
+            sink = _TAINT_SINK_LABEL[best_taint.sink_kind]
+            confidence += 0.15
+            evidence.append(
+                f"taint chain: {best_taint.sink_kind} at {best_taint.sink_file}:{best_taint.sink_line} "
+                f"reachable in {best_taint.hops} import hop(s) via {' → '.join(best_taint.files)}"
+            )
+        elif scan.databases:
+            sink = "database"
+            confidence += 0.05
+            evidence.append(f"database hint elsewhere in repo: {scan.databases[0].kind} ({scan.databases[0].file})")
+        elif scan.external_calls:
+            sink = "external integration"
+            confidence += 0.05
+            evidence.append(
+                f"external call elsewhere in repo: {scan.external_calls[0].target} ({scan.external_calls[0].file})"
+            )
+
+        # If we already attributed a same-module sink, taint chain still
+        # corroborates — add it as evidence without re-shaping the sink.
+        if best_taint is not None and sink not in {
+            _TAINT_SINK_LABEL[best_taint.sink_kind],
+            "privileged action",
+        }:
+            confidence += 0.05
+            evidence.append(
+                f"taint chain corroborates: {best_taint.sink_kind} at "
+                f"{best_taint.sink_file}:{best_taint.sink_line} ({best_taint.hops} hop(s))"
+            )
+
+        action = _guess_action(route.path)
+        if action:
+            confidence += 0.05
+            evidence.append(f"route naming suggests {action}")
+
+        chains.append(
+            ProbableChain(
+                route_method=route.method,
+                route_path=route.path,
+                route_file=route.file,
+                controller=route_controller,
+                action=action,
+                service=route_service,
+                sink=sink,
+                confidence=min(confidence, 0.95),
+                evidence=evidence,
+            )
+        )
+
+    chains.sort(key=lambda chain: chain.confidence, reverse=True)
+    return chains
+
+
+def generate_findings(scan: ScanResult, attack_surfaces: list[AttackSurface] | None = None) -> list[Finding]:
+    surfaces = attack_surfaces if attack_surfaces is not None else identify_attack_surfaces(scan)
+    runtime_surfaces = [surface for surface in surfaces if not _is_low_quality_source(surface.file)]
+    findings: list[Finding] = []
+    # Chain *findings* need evidence for every hop (#258 follow-up): a sink found
+    # only "elsewhere in repo" is not on the chain, and an "inter-service" chain
+    # needs an actual inter-service edge. Attack paths keep the looser chains.
+    atproto_chains = [c for c in _build_atproto_chains(scan) if _sink_on_chain(c.evidence)]
+    service_chains = [
+        c for c in _build_service_chains(scan) if c.next_service and _sink_on_chain(c.evidence)
+    ]
+    chains = (
+        [c for c in _build_probable_chains(scan) if _sink_on_chain(c.evidence)]
+        if _is_framework_mvc_scan(scan)
+        else []
+    )
+    webhook_surfaces = [
+        surface
+        for surface in runtime_surfaces
+        if surface.category == "webhook"
+        and surface.exposure == "public"
+        and surface.method in {"POST", "PUT", "PATCH", "DELETE", "ANY"}
+        and (surface.data_store_interaction or surface.outbound_integration)
+        and not any(
+            signal in {"jwt", "jwt_verified", "oauth", "authorization", "service_auth"} for signal in surface.auth_signals
+        )
+        and _webhook_state(surface) in {"absent", "unknown"}
+        and not (surface.webhook_verification is not None and surface.webhook_verification.inert)
+    ]
+    weak_webhook_surfaces = [
+        surface
+        for surface in runtime_surfaces
+        if surface.category == "webhook"
+        and surface.exposure == "public"
+        and surface.method in {"POST", "PUT", "PATCH", "DELETE", "ANY"}
+        and _webhook_state(surface) in {"weak_compare", "no_replay_guard"}
+    ]
+    admin_surfaces = [surface for surface in runtime_surfaces if surface.category == "admin"]
+    upload_surfaces = [surface for surface in runtime_surfaces if surface.category == "upload"]
+    auth_surfaces = [surface for surface in runtime_surfaces if surface.category == "auth"]
+    public_data_surfaces = [
+        surface
+        for surface in runtime_surfaces
+        if surface.exposure == "public" and surface.data_store_interaction and surface.category != "health"
+    ]
+    public_integration_surfaces = [
+        surface
+        for surface in runtime_surfaces
+        if surface.exposure == "public" and surface.outbound_integration
+    ]
+
+    if webhook_surfaces:
+        findings.append(
+            Finding(
+                title="Public webhook endpoint may trust attacker-controlled events",
+                rule_id="public-webhook",
+                severity="high",
+                evidence=[
+                    f"{_finding_evidence(surface)}; {_webhook_detail(surface)}" for surface in webhook_surfaces[:10]
+                ],
+                locations=_locs(webhook_surfaces),
+                mitigation="Require signature verification before processing webhook payloads, reject replays, and keep any downstream state change behind strict validation.",
+                confidence="high",
+                tags=["exposed-endpoint", "auth-missing"],
+            )
+        )
+
+    if weak_webhook_surfaces:
+        findings.append(
+            Finding(
+                title="Webhook signature verification is weak or replayable",
+                rule_id="webhook-weak-verification",
+                severity="medium",
+                evidence=[
+                    "; ".join([describe_webhook(surface), *_webhook_extra_notes(surface)])
+                    for surface in weak_webhook_surfaces[:10]
+                ],
+                locations=_webhook_locs(weak_webhook_surfaces),
+                mitigation=(
+                    "Compare signatures with a constant-time function (`crypto.timingSafeEqual`, "
+                    "`hmac.compare_digest`, `hmac.Equal`, `hash_equals`), or use the provider's SDK verifier. "
+                    "For schemes that sign a timestamp, reject events older than a few minutes; "
+                    "deduplicate on the event or delivery id."
+                ),
+                confidence="medium",
+                tags=["exposed-endpoint", "webhook-verification"],
+            )
+        )
+
+    if admin_surfaces:
+        findings.append(
+            Finding(
+                title="Administrative routes appear reachable from the main application surface",
+                rule_id="exposed-admin-route",
+                severity="high",
+                evidence=[_finding_evidence(surface) for surface in admin_surfaces[:10]],
+                locations=_locs(admin_surfaces),
+                mitigation="Require strong authentication and explicit server-side authorization on every admin action, and move admin routes behind a narrower exposure boundary where possible.",
+                confidence="high",
+                tags=["exposed-endpoint", "auth-missing", "privileged"],
+            )
+        )
+
+    if upload_surfaces:
+        findings.append(
+            Finding(
+                title="Upload or import routes expand attacker-controlled input handling",
+                rule_id="upload-route",
+                severity="high",
+                evidence=[_finding_evidence(surface) for surface in upload_surfaces[:10]],
+                locations=_locs(upload_surfaces),
+                mitigation="Constrain accepted formats, isolate parsers, scan uploaded content, and treat imported files as untrusted all the way through storage and processing.",
+                confidence="medium",
+                tags=["exposed-endpoint", "input-handling"],
+            )
+        )
+
+    # Per surface (#340): one guarded auth-category route used to suppress
+    # the finding for all of them, including the real login endpoint.
+    weak_auth_surfaces = [surface for surface in auth_surfaces if not surface.auth_signals]
+    if weak_auth_surfaces:
+        findings.append(
+            Finding(
+                title="Authentication routes were detected without strong nearby auth controls",
+                rule_id="weak-auth-route",
+                severity="medium",
+                evidence=[_finding_evidence(surface) for surface in weak_auth_surfaces[:10]],
+                locations=_locs(weak_auth_surfaces),
+                mitigation="Review these routes for rate limiting, credential validation, token or session handling, and the exact point where trust is established server-side.",
+                confidence="medium",
+                tags=["exposed-endpoint", "auth-missing"],
+            )
+        )
+
+    # Fuse per-route middleware/guard chains + auth_hints into precise
+    # "unauthenticated state-changing route" findings (#140). Complements the
+    # category-specific findings above (webhook/upload/auth) by covering
+    # public_api and privileged (admin/internal, #242) mutating routes with
+    # per-route chain resolution.
+    unauth_routes = unauthenticated_routes(scan, runtime_surfaces)
+    findings.extend(synthesize_unauthenticated_routes(scan, runtime_surfaces, unauth_routes))
+    unauth_keys = {(r.method, r.path, r.file) for r, _ in unauth_routes}
+
+    # Function-level authorization (#242, OWASP API5): privileged routes that
+    # check authentication but never a role or permission.
+    bfla = find_bfla_routes(scan, runtime_surfaces)
+    if bfla:
+        evidence = [line for _, line in bfla[:10]]
+        if len(bfla) > 10:
+            evidence.append(f"+{len(bfla) - 10} more privileged route(s) with no role check")
+        findings.append(
+            Finding(
+                title="Privileged route checks authentication but not role (BFLA)",
+                rule_id="bfla-privileged-route",
+                severity="high",
+                evidence=evidence,
+                locations=[FindingLocation(file=r.file, line=r.line) for r, _ in bfla],
+                mitigation=(
+                    "Authenticate AND authorize privileged actions: require an explicit role or "
+                    "permission check (`requireRole('admin')`, `@roles_required`, "
+                    "`permission_classes=[IsAdminUser]`, `@PreAuthorize(\"hasRole('ADMIN')\")`) on "
+                    "the route, its router, or the service it calls, so any logged-in user cannot "
+                    "invoke admin functions."
+                ),
+                confidence="medium",
+                tags=["exposed-endpoint", "privileged", "function-level-authz"],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id="T1068",
+                        name="Exploitation for Privilege Escalation",
+                        tactic="Privilege Escalation",
+                        url="https://attack.mitre.org/techniques/T1068/",
+                    )
+                ],
+            )
+        )
+
+    if public_integration_surfaces and not any(
+        h.hint in {"jwt", "jwt_verified", "oauth", "bearer", "token"} for h in scan.auth_hints
+    ):
+        findings.append(
+            Finding(
+                title="Public routes appear to influence outbound integrations without clear auth signals",
+                rule_id="unauth-outbound-integration",
+                severity="medium",
+                evidence=[_finding_evidence(surface) for surface in public_integration_surfaces[:10]],
+                locations=_locs(public_integration_surfaces),
+                mitigation="Check how outbound requests are authenticated, signed, and authorized, and confirm that untrusted route input cannot directly steer third-party actions.",
+                confidence="medium",
+                tags=["integration-risk", "auth-missing"],
+            )
+        )
+
+    # Split secret findings by kind (#39). Hard-coded literals get HIGH
+    # severity — exposure is broader than env references (visible to
+    # anyone with repo read access, not just runtime access) — and their
+    # own tags so downstream triage and reporting can distinguish them.
+    # `env_template` is a variable *declared* in a template such as
+    # `.env.example` (iac plugin): a name, not a value, so it belongs with the
+    # env references rather than the HIGH hard-coded-literal finding.
+    hardcoded_secrets = [h for h in scan.secret_hints if h.kind not in NON_LITERAL_SECRET_KINDS]
+    env_reference_secrets = [h for h in scan.secret_hints if h.kind in NON_LITERAL_SECRET_KINDS]
+
+    if hardcoded_secrets:
+        # Group by kind for evidence line density; still cap at 10 total.
+        evidence_lines = [
+            f"[{hint.kind}] {hint.name} in {hint.file}"
+            for hint in hardcoded_secrets[:10]
+        ]
+        findings.append(
+            Finding(
+                title="Hard-coded secret literals were found in source or config",
+                rule_id="hardcoded-secret",
+                severity="high",
+                evidence=evidence_lines,
+                locations=_locs(hardcoded_secrets),
+                mitigation=(
+                    "Rotate every detected credential immediately, purge it from git history, "
+                    "and move to environment-injected or vault-managed values. Anyone with read "
+                    "access to the repository already has these secrets."
+                ),
+                # Keyword-proximity assignments alone (#252) are a weaker signal.
+                confidence="high" if any(h.confidence >= 0.6 for h in hardcoded_secrets) else "medium",
+                tags=["secret-exposure", "data-risk", "hardcoded-literal"],
+            )
+        )
+
+    # Secrets in git history (#252, opt-in --secrets-history). One finding;
+    # evidence says whether each value is still in HEAD.
+    if scan.secret_history:
+        history = scan.secret_history
+        removed = sum(1 for h in history if not h.still_in_head)
+        findings.append(
+            Finding(
+                title="Hard-coded secrets were found in git history",
+                rule_id="secret-in-git-history",
+                severity="high",
+                evidence=[
+                    f"[{h.kind}] {h.name} in {h.file} — introduced in {h.introduced_in[:12]}, "
+                    f"{'still in HEAD' if h.still_in_head else 'removed from HEAD (still in history)'}"
+                    for h in history[:10]
+                ]
+                + ([f"+{len(history) - 10} more"] if len(history) > 10 else []),
+                locations=_locs(history),
+                mitigation=(
+                    "Rotate every listed credential: removing it in a later commit does not revoke it, and "
+                    f"{removed} of {len(history)} survive only in history, where every clone and fork keeps them. "
+                    "Then rewrite history (git filter-repo) if the repository is shared, and add a pre-commit secret scanner."
+                ),
+                confidence="high",
+                tags=["secret-exposure", "data-risk", "git-history"],
+            )
+        )
+
+    if env_reference_secrets:
+        findings.append(
+            Finding(
+                title="Secret-bearing environment variables are referenced in executable paths",
+                rule_id="secret-env-reference",
+                severity="medium",
+                evidence=[f"{hint.name} in {hint.file}" for hint in env_reference_secrets[:10]],
+                locations=_locs(env_reference_secrets),
+                mitigation="Confirm these secrets are injected securely, never logged or returned, rotated regularly, and scoped only to the privileges each route actually needs.",
+                confidence="high",
+                tags=["secret-exposure"],
+            )
+        )
+
+    if public_data_surfaces:
+        findings.append(
+            Finding(
+                title="Public routes likely sit close to sensitive data operations",
+                rule_id="public-data-route",
+                severity="medium",
+                evidence=[_finding_evidence(surface) for surface in public_data_surfaces[:10]],
+                locations=_locs(public_data_surfaces),
+                mitigation="Validate untrusted input before it reaches business logic, enforce authorization at the route boundary, and verify that downstream queries or writes stay parameterized.",
+                confidence="medium",
+                tags=["exposed-endpoint", "data-risk"],
+            )
+        )
+
+    if atproto_chains:
+        top_atproto_chain = atproto_chains[0]
+        findings.append(
+            Finding(
+                title="AT Protocol XRPC surface chains into a downstream trust boundary",
+                rule_id="atproto-trust-chain",
+                severity="high" if top_atproto_chain.sink in {"database", "privileged downstream action"} else "medium",
+                evidence=[f"confidence={top_atproto_chain.confidence:.2f}", *top_atproto_chain.evidence[:6]],
+                mitigation=(
+                    "Enforce namespace-specific authz on XRPC handlers, validate service-auth at each hop, and constrain "
+                    "downstream service/database permissions per endpoint."
+                ),
+                confidence="high" if top_atproto_chain.confidence >= 0.7 else "medium",
+                tags=["atproto-chain", "data-risk"],
+            )
+        )
+
+    if service_chains:
+        top_service_chain = service_chains[0]
+        findings.append(
+            Finding(
+                title="Inter-service trust chain reaches a sensitive downstream sink",
+                rule_id="service-trust-chain",
+                severity="high" if top_service_chain.sink in {"database", "privileged downstream action"} else "medium",
+                evidence=[f"confidence={top_service_chain.confidence:.2f}", *top_service_chain.evidence[:6]],
+                mitigation=(
+                    "Apply explicit authn/authz checks at each service hop, constrain service-to-service callers, and "
+                    "treat env-configured upstream and downstream endpoints as untrusted until verified."
+                ),
+                confidence="high" if top_service_chain.confidence >= 0.7 else "medium",
+                tags=["service-chain", "data-risk"],
+            )
+        )
+
+    if chains:
+        top_chain = chains[0]
+        findings.append(
+            Finding(
+                title="Framework route-to-service chain reaches a sensitive sink",
+                rule_id="framework-sink-chain",
+                severity="high" if top_chain.sink in {"database", "privileged action"} else "medium",
+                evidence=[f"confidence={top_chain.confidence:.2f}", *top_chain.evidence[:6]],
+                mitigation=(
+                    "Validate and authorize at the route boundary, enforce controller-level policy checks, and gate "
+                    "service/factory entry points before database writes or privileged actions."
+                ),
+                confidence="high" if top_chain.confidence >= 0.7 else "medium",
+                tags=["framework-chain", "data-risk"],
+            )
+        )
+
+    # #60 — CVE hits on SBOM entries. One Finding per vulnerable dep,
+    # aggregating every advisory affecting it in the evidence list.
+    vulns_by_pkg: dict[tuple[str, str, str], list] = {}
+    for vuln in scan.vulnerabilities:
+        vulns_by_pkg.setdefault(
+            (vuln.ecosystem, vuln.package_name, vuln.package_version), []
+        ).append(vuln)
+    for (eco, name, version), pkg_vulns in vulns_by_pkg.items():
+        top_severity = min(
+            (_severity_rank(v.severity) for v in pkg_vulns), default=_severity_rank("medium")
+        )
+        title_severity_word = {0: "critical", 1: "moderate", 2: "low"}.get(top_severity, "moderate")
+        evidence_lines: list[str] = []
+        for v in sorted(pkg_vulns, key=lambda x: (_severity_rank(x.severity), x.id)):
+            summary_snip = (v.summary[:120] + "…") if len(v.summary) > 120 else v.summary
+            aliases = f" (aka {', '.join(v.aliases[:3])})" if v.aliases else ""
+            score = f" CVSS {v.cvss_score:.1f}" if v.cvss_score is not None else ""
+            ref = v.references[0] if v.references else ""
+            ref_part = f" — {ref}" if ref else ""
+            evidence_lines.append(
+                f"{v.id}{aliases} [{v.severity}{score}]: {summary_snip}{ref_part}"
+            )
+        finding_severity = "high" if top_severity == 0 else ("medium" if top_severity == 1 else "low")
+        # Transitive-dependency provenance (#143): cite the resolution path so a
+        # reviewer can see the vulnerable package was pulled in indirectly.
+        transitive = next((v for v in pkg_vulns if not v.direct), None)
+        provenance_lines: list[str] = []
+        if transitive is not None:
+            if transitive.resolution_path:
+                provenance_lines.append(
+                    f"Transitive dependency — resolution path: {transitive.resolution_path}"
+                )
+            else:
+                provenance_lines.append("Transitive (indirect) dependency")
+        findings.append(
+            Finding(
+                title=f"Vulnerable dependency: {name}@{version} ({eco})",
+                rule_id="vulnerable-dependency",
+                severity=finding_severity,  # type: ignore[arg-type]
+                evidence=[
+                    f"{len(pkg_vulns)} known advisor{'y' if len(pkg_vulns) == 1 else 'ies'} for "
+                    f"{title_severity_word}-severity impact",
+                    *provenance_lines,
+                    *evidence_lines[:10],
+                ],
+                mitigation=(
+                    f"Upgrade `{name}` beyond the affected range shown, verify no direct"
+                    " or transitive callers depend on removed symbols, and re-run"
+                    " `attackmap analyze --cve` to confirm the finding clears."
+                ),
+                confidence="high",
+                tags=["cve", "dependency", eco],
+            )
+        )
+
+    # Broken object-level authorization (BOLA/IDOR, #69). Routes with a
+    # resource-id param that reach a datastore with no ownership check
+    # nearby. Split into a HIGH finding for write methods and a MEDIUM
+    # finding for reads, per the OWASP API #1 severity shape.
+    # An unauthenticated write is already reported (with its missing control)
+    # by the unauthenticated-route finding; BOLA is about *which* object an
+    # identified caller may touch (#242). Test/fixture/example routes are
+    # skipped like every other route finding's.
+    bola = [
+        c for c in scan.authz_candidates
+        if (c.route_method, c.route_path, c.route_file) not in unauth_keys
+        and not _is_low_quality_source(c.route_file)
+    ]
+    if bola:
+        # Object identifiers arrive via path params, query params, RPC methods
+        # (XRPC/tRPC), or GraphQL fields (#139). A write is any mutating HTTP
+        # verb or a GraphQL mutation.
+        _write_methods = {"POST", "PUT", "PATCH", "DELETE", "MUTATION"}
+        _surface_label = {
+            "path_param": "path id",
+            "query_param": "query param",
+            "rpc_method": "RPC method",
+            "graphql_field": "field arg",
+        }
+        write_candidates = [c for c in bola if c.route_method in _write_methods]
+        read_candidates = [c for c in bola if c.route_method not in _write_methods]
+        for group, severity, verb in (
+            (write_candidates, "high", "modify"),
+            (read_candidates, "medium", "read"),
+        ):
+            if not group:
+                continue
+            # Authenticated-but-unscoped routes (the classic IDOR) lead.
+            group = sorted(group, key=lambda c: c.confidence != "high")
+            evidence = [
+                f"{c.route_method} {c.route_path} "
+                f"({_surface_label.get(c.surface, 'id')} `{c.id_param}`) "
+                f"in {c.route_file} — {c.db_evidence}"
+                + (f"; {c.authn_evidence}, but no object-level check in the handler" if c.authn_evidence else "")
+                for c in group[:10]
+            ]
+            if len(group) > 10:
+                evidence.append(f"+{len(group) - 10} more route(s) with the same pattern")
+            findings.append(
+                Finding(
+                    title=f"Possible broken object-level authorization (BOLA/IDOR) on {verb} routes",
+                    rule_id=f"bola-{verb}",
+                    severity=severity,  # type: ignore[arg-type]
+                    evidence=evidence,
+                    locations=_locs(group, "route_file", "route_line"),
+                    mitigation=(
+                        "Enforce an object-level authorization check on every access: confirm the "
+                        "authenticated principal owns or may access the requested resource id "
+                        "server-side — scope the query by the caller's identity or evaluate a policy "
+                        "— before reading or modifying the record. Never trust the id from the "
+                        "request alone."
+                    ),
+                    confidence="high" if any(c.confidence == "high" for c in group) else "medium",
+                    tags=["broken-authorization", "exposed-endpoint", "data-risk"],
+                    attack_techniques=[
+                        AttackTechnique(
+                            technique_id="T1190",
+                            name="Exploit Public-Facing Application",
+                            tactic="Initial Access",
+                            url="https://attack.mitre.org/techniques/T1190/",
+                        )
+                    ],
+                )
+            )
+
+    # Insecure crypto / weak randomness (#70). One aggregated finding per
+    # weakness kind present, ordered by the spec's declaration.
+    crypto_by_kind: dict[str, list] = {}
+    for weakness in scan.crypto_weaknesses:
+        crypto_by_kind.setdefault(weakness.kind, []).append(weakness)
+    for kind, spec in _CRYPTO_FINDING_SPEC.items():
+        items = crypto_by_kind.get(kind)
+        if not items:
+            continue
+        evidence = [
+            f"{w.file}:{w.line} — {w.evidence_text}" if w.evidence_text else f"{w.file}:{w.line}"
+            for w in items[:10]
+        ]
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more occurrence(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                severity=spec["severity"],  # type: ignore[arg-type]
+                evidence=evidence,
+                locations=_locs(items),
+                mitigation=spec["mitigation"],
+                confidence="medium",
+                tags=["insecure-crypto"],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Web-hardening gaps (#71). One aggregated finding per issue kind.
+    web_by_kind: dict[str, list] = {}
+    for issue in scan.web_hardening_issues:
+        web_by_kind.setdefault(issue.kind, []).append(issue)
+    for kind, spec in _WEB_HARDENING_FINDING_SPEC.items():
+        items = web_by_kind.get(kind)
+        if not items:
+            continue
+        if kind == "csrf_unprotected_session" and not any(
+            r.method.upper() in _CSRF_MUTATING_METHODS for r in scan.routes
+        ):
+            continue  # no state-changing route to forge a request against
+        evidence = [
+            f"{i.file}:{i.line} — {i.evidence_text}" if i.evidence_text else f"{i.file}:{i.line}"
+            for i in items[:10]
+        ]
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more occurrence(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                # Some kinds tier per instance (CORS: credentials or not, #244).
+                severity=max((i.severity for i in items), key=_SEVERITY_ORDER.__getitem__),  # type: ignore[arg-type]
+                evidence=evidence,
+                locations=_locs(items),
+                mitigation=spec["mitigation"],
+                confidence="medium",
+                tags=["web-hardening"],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Novel vuln classes (#77). One aggregated finding per weakness kind.
+    code_by_kind: dict[str, list] = {}
+    for weakness in scan.code_weaknesses:
+        code_by_kind.setdefault(weakness.kind, []).append(weakness)
+    for kind, spec in _CODE_WEAKNESS_FINDING_SPEC.items():
+        items = code_by_kind.get(kind)
+        if not items:
+            continue
+        evidence = [
+            f"{i.file}:{i.line} — {i.evidence_text}" if i.evidence_text else f"{i.file}:{i.line}"
+            for i in items[:10]
+        ]
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more occurrence(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                severity=spec["severity"],  # type: ignore[arg-type]
+                evidence=evidence,
+                locations=_locs(items),
+                mitigation=spec["mitigation"],
+                confidence="medium",
+                tags=["novel-vuln", *_auth_class_tag(kind)],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # CI workflow security (#142). One aggregated finding per issue kind; the
+    # finding severity is the max over that kind's issues (some kinds tier per
+    # instance — semver-tag vs. branch unpinned action, PR vs. PR-target runner).
+    workflow_by_kind: dict[str, list] = {}
+    for issue in scan.workflow_issues:
+        workflow_by_kind.setdefault(issue.kind, []).append(issue)
+    for kind, spec in _WORKFLOW_FINDING_SPEC.items():
+        items = workflow_by_kind.get(kind)
+        if not items:
+            continue
+        severity = max((i.severity for i in items), key=_SEVERITY_ORDER.__getitem__)
+        evidence = []
+        for i in items[:10]:
+            loc = f"{i.file}:{i.line}" if i.line else i.file
+            detail = f" — {i.evidence_text}" if i.evidence_text else ""
+            ctx = f" [{i.context}]" if i.context else ""
+            evidence.append(f"{loc}{ctx}{detail}")
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more occurrence(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                severity=severity,  # type: ignore[arg-type]
+                evidence=evidence,
+                locations=_locs(items),
+                mitigation=spec["mitigation"],
+                confidence="high",
+                tags=["ci-security", "supply-chain", *_cwe_tags(kind)],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Dependency supply-chain risk (#247). One aggregated finding per kind,
+    # severity the max over that kind's issues.
+    supply_by_kind: dict[str, list] = {}
+    for issue in scan.supply_chain_issues:
+        supply_by_kind.setdefault(issue.kind, []).append(issue)
+    for kind, spec in _SUPPLY_CHAIN_FINDING_SPEC.items():
+        items = supply_by_kind.get(kind)
+        if not items:
+            continue
+        severity = max((i.severity for i in items), key=_SEVERITY_ORDER.__getitem__)
+        evidence = []
+        for i in items[:10]:
+            loc = f"{i.file}:{i.line}" if i.line else i.file
+            evidence.append(f"{loc} — {i.evidence_text}" if i.evidence_text else loc)
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more occurrence(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                severity=severity,  # type: ignore[arg-type]
+                evidence=evidence,
+                locations=_locs(items),
+                mitigation=spec["mitigation"],
+                confidence="medium" if kind == "typosquat_candidate" else "high",
+                tags=["supply-chain", "dependency-risk", *_cwe_tags(kind)],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Native C/C++ weaknesses (#189): one finding per (kind, severity tier).
+    # Within a tier, traced instances lead, then by location.
+    for kind, spec in _NATIVE_WEAKNESS_FINDING_SPEC.items():
+        items = sorted(
+            code_by_kind.get(kind, []),
+            key=lambda w: (w.source_kind is None, w.file, w.line or 0),
+        )
+        findings.extend(
+            tiered_findings(
+                kind, spec, items,
+                evidence=_native_evidence_line,
+                tags=[
+                    "novel-vuln", "native",
+                    *(["memory-safety"] if kind != "native_command_exec" else []),
+                    *_cwe_tags(kind),
+                ],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Cloud / IaC / container misconfigurations (terraform#4, iac#1). One
+    # finding per (kind, severity tier); confidence is the max over that
+    # tier's records, and evidence lists the most confident first.
+    cloud_by_kind: dict[str, list] = {}
+    for issue in scan.cloud_misconfigs:
+        cloud_by_kind.setdefault(issue.kind, []).append(issue)
+    for kind, spec in _CLOUD_MISCONFIG_FINDING_SPEC.items():
+        findings.extend(
+            tiered_findings(
+                kind, spec, cloud_by_kind.get(kind, []),
+                evidence=_cloud_misconfig_evidence,
+                tags=["cloud-misconfig", *_cwe_tags(kind)],
+            )
+        )
+
+    # App attack surface from platform plugins (#188, #190). One aggregated
+    # finding per kind, at its most severe instance.
+    app_by_kind: dict[str, list] = {}
+    for issue in scan.app_surface_issues:
+        app_by_kind.setdefault(issue.kind, []).append(issue)
+    for kind, spec in _APP_SURFACE_FINDING_SPEC.items():
+        items = app_by_kind.get(kind)
+        if not items:
+            continue
+        items.sort(key=lambda i: -_SEVERITY_ORDER[i.severity])
+        evidence = []
+        for i in items[:10]:
+            loc = f"{i.file}:{i.line}" if i.line else i.file
+            evidence.append(f"{loc} — {i.evidence_text}" if i.evidence_text else loc)
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more occurrence(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                severity=items[0].severity,
+                evidence=evidence,
+                locations=_locs(items),
+                mitigation=spec["mitigation"],
+                confidence=spec["confidence"],  # type: ignore[arg-type]
+                tags=["app-surface", *_cwe_tags(kind)],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Anomaly / outlier findings (#78). One aggregated finding per kind,
+    # each evidence line naming the peer group and the deviation. The
+    # finding's confidence tracks the strongest (most consistent) cohort.
+    anomalies_by_kind: dict[str, list] = {}
+    for anomaly in scan.anomalies:
+        anomalies_by_kind.setdefault(anomaly.kind, []).append(anomaly)
+    for kind, spec in _ANOMALY_FINDING_SPEC.items():
+        items = anomalies_by_kind.get(kind)
+        if not items:
+            continue
+        items.sort(key=lambda a: -a.confidence)
+        evidence = []
+        for a in items[:10]:
+            loc = f"{a.route_file}:{a.route_line}" if a.route_line else a.route_file
+            peers = f" (peers: {', '.join(a.peer_examples)})" if a.peer_examples else ""
+            # Cite the mined invariant (invariant_violation) as the norm broken.
+            invariant = f" [invariant: {a.invariant}]" if a.invariant else ""
+            evidence.append(
+                f"{a.route_method} {a.route_path} [{loc}] — {a.deviation}{invariant}{peers} "
+                f"[confidence={a.confidence:.2f}]"
+            )
+        if len(items) > 10:
+            evidence.append(f"+{len(items) - 10} more outlier(s)")
+        findings.append(
+            Finding(
+                title=spec["title"],
+                rule_id=_rule_slug_kind(kind),
+                severity=spec["severity"],  # type: ignore[arg-type]
+                evidence=evidence,
+                locations=_locs(items, "route_file", "route_line"),
+                mitigation=spec["mitigation"],
+                confidence=_numeric_to_confidence(items[0].confidence),
+                tags=["anomaly"],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    # Dangerous taint sinks each get a dedicated, sink-specific finding
+    # (#68) — surfaced even outside the framework-MVC gate that `chains`
+    # sits behind. One aggregated finding per sink kind reachable from a
+    # route, ordered by the spec's declaration.
+    taint_by_kind: dict[str, list] = {}
+    speculative_by_kind: dict[str, list] = {}
+    flow_by_kind: dict[str, list] = {}
+    for chain in scan.taint_chains:
+        # Sanitized chains (#137) are neutralized before the sink — keep them
+        # as evidence in scan.taint_chains but don't raise a finding for them.
+        if chain.sanitized:
+            continue
+        flow_kind = canonical_kind(chain.sink_kind)
+        if flow_kind in _FLOW_FINDING_SPEC:
+            # Reach alone isn't a finding for SQL / generic file opens — only a
+            # traced flow (#239). The #240 path sinks (send_file, sendFile,
+            # include…) are request-gated already, so their chains count.
+            confirmed = chain.source_kind or chain.sink_kind not in ("sql_execute", "dynamic_open")
+            if confirmed and not chain.speculative:
+                flow_by_kind.setdefault(flow_kind, []).append(chain)
+            continue
+        if chain.sink_kind not in _TAINT_FINDING_SPEC:
+            continue
+        # Speculative recall chains (#148a) are segregated into their own
+        # clearly-marked, low-severity finding below — so the confirmed finding
+        # (and default behavior) is untouched and they can't trip fail-on-new-high.
+        if chain.speculative:
+            speculative_by_kind.setdefault(chain.sink_kind, []).append(chain)
+        else:
+            taint_by_kind.setdefault(chain.sink_kind, []).append(chain)
+    taint_findings_by_kind: dict[str, Finding] = {}
+    for kind, spec in _TAINT_FINDING_SPEC.items():
+        kind_chains = taint_by_kind.get(kind)
+        if not kind_chains:
+            continue
+        top = min(kind_chains, key=lambda c: (c.hops, -c.confidence))
+        evidence = [
+            f"route {top.route_method} {top.route_path} in {top.route_file}",
+            f"sink at {top.sink_file}:{top.sink_line} ({_TAINT_SINK_LABEL.get(kind, kind)})",
+            f"import path: {' → '.join(top.files)} ({top.hops} hop(s))",
+        ]
+        if len(kind_chains) > 1:
+            evidence.append(
+                f"+{len(kind_chains) - 1} more route(s) reach a {_TAINT_SINK_LABEL.get(kind, kind)} sink"
+            )
+        evidence += _flow_evidence(kind_chains)
+        taint_finding = Finding(
+            title=spec["title"],
+            rule_id=_rule_slug_kind(kind),
+            severity=spec["severity"],  # type: ignore[arg-type]
+            evidence=evidence,
+            locations=_locs(kind_chains, "sink_file", "sink_line") + _locs(kind_chains, "route_file", "route_line"),
+            mitigation=spec["mitigation"],
+            confidence="medium",
+            tags=["taint-chain", "input-handling", "data-risk"],
+            attack_techniques=[
+                AttackTechnique(
+                    technique_id=spec["technique_id"],
+                    name=spec["technique_name"],
+                    tactic=spec["tactic"],
+                    url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                )
+            ],
+        )
+        taint_finding.code_flows = _code_flows(kind_chains)
+        taint_findings_by_kind[kind] = taint_finding
+        findings.append(taint_finding)
+
+    # Flow-confirmed SQL injection / path traversal (#239): one aggregated
+    # finding per kind, citing each traced route→source→sink.
+    for kind, spec in _FLOW_FINDING_SPEC.items():
+        kind_chains = flow_by_kind.get(kind)
+        if not kind_chains:
+            continue
+        top = min(kind_chains, key=lambda c: (c.hops, -c.confidence))
+        evidence = [
+            f"route {top.route_method} {top.route_path} in {top.route_file}",
+            f"sink at {top.sink_file}:{top.sink_line} ({_TAINT_SINK_LABEL.get(kind, kind)})",
+            f"import path: {' → '.join(top.files)} ({top.hops} hop(s))",
+        ] + _flow_evidence(kind_chains)
+        flow_finding = Finding(
+            title=spec["title"],
+            rule_id=spec["rule_id"],
+            severity=spec["severity"],  # type: ignore[arg-type]
+            evidence=evidence,
+            locations=_locs(kind_chains, "sink_file", "sink_line") + _locs(kind_chains, "route_file", "route_line"),
+            mitigation=spec["mitigation"],
+            confidence="high" if any(c.confidence >= 0.75 for c in kind_chains) else "medium",
+            tags=["taint-chain", "taint-flow", "input-handling", "data-risk"],
+            attack_techniques=[
+                AttackTechnique(
+                    technique_id=spec["technique_id"],
+                    name=spec["technique_name"],
+                    tactic=spec["tactic"],
+                    url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                )
+            ],
+            code_flows=_code_flows(kind_chains),
+        )
+        taint_findings_by_kind[kind] = flow_finding
+        findings.append(flow_finding)
+
+    # Exploitability fusion (#79): attach the best 'exploitable now' score for
+    # each sink kind to its aggregated taint finding, so triage can lead with
+    # the public + no-auth + dangerous-sink combinations.
+    if taint_findings_by_kind:
+        best = best_by_sink_kind(score_exploitability(scan, attack_surfaces))
+        for kind, finding in taint_findings_by_kind.items():
+            scored = best.get(kind)
+            if scored is not None:
+                finding.exploitability = scored.score
+                finding.exploitability_tier = scored.tier
+
+    # Speculative recall findings (#148a). One low-severity, clearly-marked
+    # finding per sink kind reached only via a widened recall knob (deeper hop
+    # or a relaxed gate). Kept at LOW severity so they stay out of the
+    # `--fail-on-new-high` gate — they're leads for `--hunt --verify` to
+    # adjudicate, not asserted flows. Only ever present in `--recall` scans.
+    for kind, spec in _TAINT_FINDING_SPEC.items():
+        kind_chains = speculative_by_kind.get(kind)
+        if not kind_chains:
+            continue
+        top = min(kind_chains, key=lambda c: (c.hops, -c.confidence))
+        label = _TAINT_SINK_LABEL.get(kind, kind)
+        evidence = [
+            "SPECULATIVE (recall mode): surfaced by widened discovery, not confirmed — "
+            "adjudicate with --hunt --verify",
+            f"route {top.route_method} {top.route_path} in {top.route_file}",
+            f"sink at {top.sink_file}:{top.sink_line} ({label}), {top.hops} hop(s)",
+        ]
+        if len(kind_chains) > 1:
+            evidence.append(f"+{len(kind_chains) - 1} more speculative route(s) reach a {label} sink")
+        findings.append(
+            Finding(
+                title=f"Speculative reach to a {label} sink (recall mode)",
+                rule_id=f"speculative-{_rule_slug_kind(kind)}",
+                severity="low",
+                evidence=evidence,
+                locations=_locs(kind_chains, "sink_file", "sink_line") + _locs(kind_chains, "route_file", "route_line"),
+                mitigation=(
+                    "Recall mode widened taint discovery to surface this reach; provenance "
+                    "is unconfirmed. Verify whether untrusted input actually reaches the sink "
+                    f"(run `--hunt --verify`). If it does, treat it as a {spec['title'].lower()}."
+                ),
+                confidence="low",
+                tags=["taint-chain", "speculative", "recall"],
+                attack_techniques=[
+                    AttackTechnique(
+                        technique_id=spec["technique_id"],
+                        name=spec["technique_name"],
+                        tactic=spec["tactic"],
+                        url=f"https://attack.mitre.org/techniques/{spec['technique_id'].replace('.', '/')}/",
+                    )
+                ],
+            )
+        )
+
+    if not findings:
+        findings.append(
+            Finding(
+                title="Heuristic scan found only a limited attack surface",
+                rule_id="limited-surface",
+                severity="low",
+                evidence=["No major route, secret, or integration patterns triggered a stronger finding."],
+                mitigation="Treat this as a weak signal, expand parser coverage, and manually validate the real entry points and trust boundaries.",
+                confidence="low",
+                tags=["weak-signal"],
+            )
+        )
+
+    _fill_missing_locations(findings)
+
+    # #4: attach numeric score for triage ordering, then sort by
+    # (severity, -score, title). Same-severity findings surface in
+    # confidence-weighted order so a HIGH/HIGH beats a HIGH/LOW.
+    for finding in findings:
+        finding.score = compute_finding_score(finding.severity, finding.confidence)
+    return sorted(
+        findings,
+        key=lambda f: (_severity_rank(f.severity), -(f.score or 0), f.title),
+    )
+
+
+def generate_attack_paths(scan: ScanResult, attack_surfaces: list[AttackSurface] | None = None) -> list[AttackPath]:
+    """
+    Generate plausible attacker-centric paths from recon signals.
+
+    If `attack_surfaces` is provided, reuse it to avoid redundant surface
+    recomputation in callers that already translated recon -> surface.
+    """
+    surfaces_source = attack_surfaces if attack_surfaces is not None else identify_attack_surfaces(scan)
+    surfaces = [surface for surface in surfaces_source if not _is_low_quality_source(surface.file)]
+    atproto_chains = _build_atproto_chains(scan)
+    service_chains = _build_service_chains(scan)
+    chains = _build_probable_chains(scan) if _is_framework_mvc_scan(scan) else []
+
+    if atproto_chains:
+        top_chain = atproto_chains[0]
+        chain_label = (
+            f"{top_chain.entry_service} -> {top_chain.next_service}"
+            if top_chain.next_service
+            else top_chain.entry_service
+        )
+        steps = [
+            _action_step(
+                "Entry",
+                f"Attacker reaches {top_chain.route_method} {top_chain.route_path} in {top_chain.route_file}",
+            ),
+            _action_step("Namespace", f"Endpoint is exposed in AT Protocol namespace `{top_chain.namespace}`"),
+            _action_step("Service entry", f"XRPC request is handled by service `{top_chain.entry_service}`"),
+        ]
+        if top_chain.next_service:
+            steps.append(
+                _action_step(
+                    "Propagation",
+                    f"Service trust edge allows request influence to reach `{top_chain.next_service}`",
+                )
+            )
+        if top_chain.env_risk:
+            steps.append(
+                _action_step(
+                    "Config risk",
+                    f"Runtime behavior depends on env-configured endpoint {top_chain.env_risk}, which can widen downstream trust exposure",
+                )
+            )
+        steps.extend(
+            [
+                _action_step("Sink", f"Influence reaches {top_chain.sink} through protocol-driven service flow"),
+                _action_step("Evidence", f"confidence={top_chain.confidence:.2f}; {'; '.join(top_chain.evidence[:4])}"),
+            ]
+        )
+        return [
+            AttackPath(
+                name="AT Protocol namespace trust-chain abuse",
+                steps=steps,
+                impact=(
+                    f"An exposed XRPC namespace can be abused to propagate across `{chain_label}` and affect {top_chain.sink} "
+                    "when per-namespace authorization and inter-service trust controls are weak."
+                ),
+            )
+        ]
+
+    if service_chains:
+        top_chain = service_chains[0]
+        chain_label = (
+            f"{top_chain.entry_service} -> {top_chain.next_service}"
+            if top_chain.next_service
+            else top_chain.entry_service
+        )
+        steps = [
+            _action_step(
+                "Entry",
+                f"Attacker reaches {top_chain.route_method} {top_chain.route_path} in {top_chain.route_file}",
+            ),
+            _action_step("Service entry", f"Request is handled by service `{top_chain.entry_service}`"),
+        ]
+        if top_chain.next_service:
+            steps.append(
+                _action_step(
+                    "Propagation",
+                    f"Service-to-service trust edge allows request influence to reach `{top_chain.next_service}`",
+                )
+            )
+        if top_chain.env_risk:
+            steps.append(
+                _action_step(
+                    "Config risk",
+                    f"Runtime behavior depends on env-configured endpoint {top_chain.env_risk}, which can widen trust assumptions if misconfigured",
+                )
+            )
+        steps.extend(
+            [
+                _action_step(
+                    "Sink",
+                    f"Influence reaches {top_chain.sink}, creating a plausible unauthorized downstream action path",
+                ),
+                _action_step(
+                    "Evidence",
+                    f"confidence={top_chain.confidence:.2f}; {'; '.join(top_chain.evidence[:4])}",
+                ),
+            ]
+        )
+        return [
+            AttackPath(
+                name="Distributed service trust-chain abuse",
+                steps=steps,
+                impact=(
+                    f"A public API foothold can propagate across `{chain_label}` and affect {top_chain.sink} "
+                    "if service boundaries or downstream trust checks are weak."
+                ),
+            )
+        ]
+
+    if chains:
+        top_chain = chains[0]
+        controller_text = top_chain.controller or "framework controller mapping"
+        service_text = top_chain.service or "framework service/factory"
+        action_text = top_chain.action or "application action"
+        sink_text = top_chain.sink
+        evidence_text = "; ".join(top_chain.evidence[:4])
+        return [
+            AttackPath(
+                name="Framework route-to-sink attack chain",
+                steps=[
+                    _action_step(
+                        "Entry",
+                        f"Attacker reaches {top_chain.route_method} {top_chain.route_path} in {top_chain.route_file}",
+                    ),
+                    _action_step("Routing", f"Framework route config maps request toward {controller_text} ({action_text})"),
+                    _action_step("Execution", f"Controller path likely invokes {service_text}"),
+                    _action_step(
+                        "Sink",
+                        f"Request influence reaches {sink_text}, creating an opportunity for unauthorized state change or abuse",
+                    ),
+                    _action_step(
+                        "Evidence",
+                        f"confidence={top_chain.confidence:.2f} ({confidence_bucket(top_chain.confidence)}); {evidence_text}",
+                    ),
+                ],
+                impact=(
+                    "A public request can be chained through framework routing and service execution to sensitive operations "
+                    "if boundary validation and authorization checks are weak or misplaced."
+                ),
+            )
+        ]
+
+    # Basic archetypes append rather than early-return. A single scan can
+    # surface multiple distinct attack-path archetypes — see #24. Each
+    # archetype consumes one surface; we dedup by surface identity so the
+    # same route doesn't anchor two paths.
+    # A webhook that verifies its signature doesn't anchor a spoofing path (#243).
+    webhook_surface = next(
+        (surface for surface in surfaces if surface.category == "webhook" and _webhook_state(surface) != "verified"),
+        None,
+    )
+    admin_surface = next((surface for surface in surfaces if surface.category == "admin"), None)
+    auth_surface = next((surface for surface in surfaces if surface.category == "auth"), None)
+    upload_surface = next((surface for surface in surfaces if surface.category == "upload"), None)
+    public_data_surface = next(
+        (surface for surface in surfaces if surface.exposure == "public" and surface.data_store_interaction and surface.category != "health"),
+        None,
+    )
+    integration_surface = next(
+        (surface for surface in surfaces if surface.exposure == "public" and surface.outbound_integration),
+        None,
+    )
+
+    paths: list[AttackPath] = []
+    consumed: set[tuple[str, str, str]] = set()
+
+    def _surface_key(surface: AttackSurface) -> tuple[str, str, str]:
+        return (surface.file, surface.route, surface.method)
+
+    def _claim(surface: AttackSurface | None) -> bool:
+        if surface is None:
+            return False
+        key = _surface_key(surface)
+        if key in consumed:
+            return False
+        consumed.add(key)
+        return True
+
+    def _with_evidence(surface: AttackSurface, base_steps: list[str]) -> list[str]:
+        # If we can cite concrete file-local artifacts (data stores,
+        # external calls, secrets), append an Evidence step so the path
+        # narrative is anchored in specific code, not just archetype-level
+        # generalities. See #15.
+        evidence = _surface_evidence(surface, scan)
+        if evidence:
+            return [*base_steps, _action_step("Evidence", "; ".join(evidence))]
+        return base_steps
+
+    if webhook_surface and (public_data_surface or integration_surface) and _claim(webhook_surface):
+        # Webhooks consume their downstream propagation surface so the
+        # public-data / integration archetypes don't also fire on the
+        # same route.
+        if public_data_surface:
+            _claim(public_data_surface)
+        if integration_surface:
+            _claim(integration_surface)
+        # Enrich the Propagation steps with concrete same-file artifacts
+        # when we can find them — see #5.
+        webhook_db = _same_file_datastore(webhook_surface, scan)
+        webhook_ext = _same_file_external(webhook_surface, scan)
+        steps = [
+            _action_step("Entry", f"An attacker reaches {webhook_surface.method} {webhook_surface.route} in {webhook_surface.file}, a webhook-style endpoint that accepts untrusted inbound events"),
+            _action_step("Weak point", _webhook_weak_point(webhook_surface)),
+        ]
+        if public_data_surface:
+            if webhook_db:
+                steps.append(_action_step(
+                    "Propagation",
+                    f"Attacker-controlled input reaches a `{webhook_db[0]}` data store in `{webhook_db[1]}`, making unauthorized writes or state changes plausible",
+                ))
+            else:
+                steps.append(_action_step("Propagation", "Attacker-controlled input is processed close to a data store, making unauthorized writes or state changes plausible"))
+        if integration_surface:
+            if webhook_ext:
+                steps.append(_action_step(
+                    "Propagation",
+                    f"The same request path also influences an outbound call to `{webhook_ext[0]}` from `{webhook_ext[1]}`, widening the blast radius beyond the application itself",
+                ))
+            else:
+                steps.append(_action_step("Propagation", "The same request path can also influence outbound service calls, which widens the blast radius beyond the application itself"))
+        steps.append(_action_step("Impact", "The attacker drives business actions that should only occur after a trusted event or validated request"))
+        paths.append(
+            AttackPath(
+                name="External event spoofing into internal state change",
+                steps=_with_evidence(webhook_surface, steps),
+                impact="Unauthorized state changes can be triggered from the internet and then propagated into internal data or downstream systems.",
+            )
+        )
+
+    if _claim(admin_surface):
+        paths.append(
+            AttackPath(
+                name="Administrative route abuse",
+                steps=_with_evidence(admin_surface, [
+                    _action_step("Entry", f"An attacker reaches {admin_surface.method} {admin_surface.route} in {admin_surface.file}, a route associated with privileged behavior"),
+                    _action_step("Weak point", "Authentication or authorization around that route is bypassed, reused, or enforced too late"),
+                    _action_step("Propagation", "Administrative actions execute with attacker influence and affect higher-value parts of the system"),
+                    _action_step("Impact", "Privileged changes, sensitive data access, or configuration abuse follow from a single foothold"),
+                ]),
+                impact="Privilege escalation or destructive administrative actions from a route that should be tightly controlled.",
+            )
+        )
+
+    if _claim(auth_surface):
+        paths.append(
+            AttackPath(
+                name="Authentication boundary bypass",
+                steps=_with_evidence(auth_surface, [
+                    _action_step("Entry", f"An attacker targets {auth_surface.method} {auth_surface.route} in {auth_surface.file}, which controls login, tokens, or session state"),
+                    _action_step("Weak point", "Credential handling, token validation, or session establishment is weaker than the route implies"),
+                    _action_step("Propagation", "The attacker converts that weakness into an authenticated foothold"),
+                    _action_step("Impact", "The foothold becomes the starting point for deeper movement into protected application behavior"),
+                ]),
+                impact="Account takeover or a trusted session that opens access to additional internal actions.",
+            )
+        )
+
+    if _claim(upload_surface):
+        paths.append(
+            AttackPath(
+                name="Untrusted file handling abuse",
+                steps=_with_evidence(upload_surface, [
+                    _action_step("Entry", f"An attacker submits content to {upload_surface.method} {upload_surface.route} in {upload_surface.file}"),
+                    _action_step("Weak point", "The application accepts or parses attacker-controlled files too broadly"),
+                    _action_step("Propagation", "Storage, parsing, or downstream consumers treat that content as safer than it is"),
+                    _action_step("Impact", "The result is execution, persistence of malicious content, or operational disruption"),
+                ]),
+                impact="Stored malicious content, parser abuse, or denial of service from untrusted file input.",
+            )
+        )
+
+    # Per-file fan-out for public_data. A repo with distinct data-touching
+    # files each becomes its own path (bounded by MAX_ATTACK_PATHS at the
+    # end). See #5.
+    for candidate in _distinct_by_file(
+        surfaces,
+        lambda s: s.exposure == "public" and s.data_store_interaction and s.category != "health",
+        limit=MAX_PER_ARCHETYPE_FANOUT,
+    ):
+        if not _claim(candidate):
+            continue
+        db = _same_file_datastore(candidate, scan)
+        propagation = (
+            f"Attacker-controlled data reaches a `{db[0]}` data store in `{db[1]}`"
+            if db
+            else "Attacker-controlled data reaches code operating close to the data store"
+        )
+        paths.append(
+            AttackPath(
+                name="Public input into sensitive data path",
+                steps=_with_evidence(candidate, [
+                    _action_step("Entry", f"An attacker uses {candidate.method} {candidate.route} in {candidate.file} as a public foothold"),
+                    _action_step("Weak point", "Input validation or authorization is weaker than the route exposure suggests"),
+                    _action_step("Propagation", propagation),
+                    _action_step("Impact", "Confidentiality, integrity, or authorization guarantees around application data are weakened"),
+                ]),
+                impact="Unauthorized data access or modification through a public-facing application route.",
+            )
+        )
+
+    for candidate in _distinct_by_file(
+        surfaces,
+        lambda s: s.exposure == "public" and s.outbound_integration,
+        limit=MAX_PER_ARCHETYPE_FANOUT,
+    ):
+        if not _claim(candidate):
+            continue
+        ext = _same_file_external(candidate, scan)
+        propagation = (
+            f"Spoofed, replayed, or attacker-steered interaction with `{ext[0]}` (from `{ext[1]}`) affects internal logic"
+            if ext
+            else "Spoofed, replayed, or attacker-steered third-party interactions affect internal logic"
+        )
+        paths.append(
+            AttackPath(
+                name="Outbound trust boundary abuse",
+                steps=_with_evidence(candidate, [
+                    _action_step("Entry", f"An attacker influences {candidate.method} {candidate.route} in {candidate.file}, which sits near an outbound integration"),
+                    _action_step("Weak point", "The application assumes too much trust in external calls or responses"),
+                    _action_step("Propagation", propagation),
+                    _action_step("Impact", "Unsafe business decisions or downstream actions follow from a weak external trust boundary"),
+                ]),
+                impact="Poisoned state or unsafe downstream actions caused by over-trusting an external dependency.",
+            )
+        )
+
+    # BOLA/IDOR archetype (#69): an id-bearing route reaching data with no
+    # ownership check. Independent of the surface-claim machinery above —
+    # it keys off scan.authz_candidates.
+    bola = [c for c in scan.authz_candidates if not _is_low_quality_source(c.route_file)]
+    if bola:
+        _bola_write_methods = {"POST", "PUT", "PATCH", "DELETE", "MUTATION"}
+        # One path per distinct candidate file (#242), writes and authenticated
+        # routes first, bounded so a sprawling app can't crowd out other paths.
+        by_file: dict[str, BolaCandidate] = {}
+        for cand in sorted(
+            bola,
+            key=lambda c: (c.route_method not in _bola_write_methods, c.confidence != "high", c.route_file),
+        ):
+            by_file.setdefault(cand.route_file, cand)
+        for top in list(by_file.values())[:_MAX_BOLA_PATHS]:
+            action = "modify" if top.route_method in _bola_write_methods else "read"
+            paths.append(
+                AttackPath(
+                    name="Object-level authorization bypass (BOLA/IDOR)",
+                    steps=[
+                        _action_step(
+                            "Entry",
+                            f"{'An authenticated' if top.authn_evidence else 'An'} attacker calls {top.route_method} {top.route_path} in {top.route_file}, which takes a resource id (`{top.id_param}`)",
+                        ),
+                        _action_step(
+                            "Weak point",
+                            "No ownership or authorization check is visible in the handler — the resource id from the request is trusted directly",
+                        ),
+                        _action_step(
+                            "Propagation",
+                            f"The attacker enumerates or substitutes `{top.id_param}` values; {top.db_evidence}, so the query returns another principal's record",
+                        ),
+                        _action_step(
+                            "Impact",
+                            f"Cross-tenant / cross-user ability to {action} records that should be out of scope for the caller",
+                        ),
+                    ],
+                    impact=f"Horizontal privilege escalation — attackers {action} other users' objects by changing an id in the request.",
+                )
+            )
+
+    # Cap to keep report output focused; if more than this fires, the
+    # extras are usually redundant noise that downstream review surfaces
+    # via findings anyway.
+    return paths[:MAX_ATTACK_PATHS]
+
+
+def rule_catalog() -> list[tuple[str, str, str]]:
+    """Every core rule id with its finding title and severity (#223), for
+    `attackmap rules` and the docs. Family specs are expanded per kind."""
+    rules: list[tuple[str, str, str]] = [
+        ("public-webhook", "Public webhook endpoint may trust attacker-controlled events", "high"),
+        ("webhook-weak-verification", "Webhook signature verification is weak or replayable", "medium"),
+        ("exposed-admin-route", "Administrative routes appear reachable from the main application surface", "high"),
+        ("upload-route", "Upload or import routes expand attacker-controlled input handling", "medium"),
+        ("weak-auth-route", "Authentication routes were detected without strong nearby auth controls", "medium"),
+        ("unauth-outbound-integration", "Public routes appear to influence outbound integrations without clear auth signals", "medium"),
+        ("hardcoded-secret", "Hard-coded secret literals were found in source or config", "high"),
+        ("secret-in-git-history", "Hard-coded secrets were found in git history", "high"),
+        ("secret-env-reference", "Secret-bearing environment variables are referenced in executable paths", "medium"),
+        ("public-data-route", "Public routes likely sit close to sensitive data operations", "medium"),
+        ("atproto-trust-chain", "AT Protocol XRPC surface chains into a downstream trust boundary", "medium"),
+        ("service-trust-chain", "Inter-service trust chain reaches a sensitive downstream sink", "medium"),
+        ("framework-sink-chain", "Framework route-to-service chain reaches a sensitive sink", "medium"),
+        ("vulnerable-dependency", "Vulnerable dependency: <package>@<version> (<ecosystem>)", "varies"),
+        ("limited-surface", "Heuristic scan found only a limited attack surface", "low"),
+        ("bola-modify", "Possible broken object-level authorization (BOLA/IDOR) on modify routes", "high"),
+        ("bola-read", "Possible broken object-level authorization (BOLA/IDOR) on read routes", "medium"),
+        ("unauth-state-change", "State-changing routes are reachable without an authentication control", "high"),
+        ("bfla-privileged-route", "Privileged route checks authentication but not role (BFLA)", "high"),
+    ]
+    for spec_table in (
+        _TAINT_FINDING_SPEC, _CRYPTO_FINDING_SPEC, _WEB_HARDENING_FINDING_SPEC,
+        _CODE_WEAKNESS_FINDING_SPEC, _NATIVE_WEAKNESS_FINDING_SPEC, _WORKFLOW_FINDING_SPEC, _ANOMALY_FINDING_SPEC,
+        _SUPPLY_CHAIN_FINDING_SPEC, _APP_SURFACE_FINDING_SPEC, _CLOUD_MISCONFIG_FINDING_SPEC,
+    ):
+        for kind, spec in spec_table.items():
+            rules.append((_rule_slug_kind(kind), spec["title"], spec.get("severity", "varies")))
+    for spec in _FLOW_FINDING_SPEC.values():
+        rules.append((spec["rule_id"], spec["title"], spec["severity"]))
+    for kind in _TAINT_FINDING_SPEC:
+        label = _TAINT_SINK_LABEL.get(kind, kind)
+        rules.append((f"speculative-{_rule_slug_kind(kind)}", f"Speculative reach to a {label} sink (recall mode)", "low"))
+    return sorted(rules)