attackmap 0.6.4__py3-none-any.whl

attackmap/review_eval.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+def load_eval_fixture(path: str | Path) -> dict[str, Any]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def load_review_text(path: str | Path) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+
+def _extract_section(text: str, heading: str) -> str:
+    pattern = re.compile(rf"^\s*##\s+{re.escape(heading)}\s*$", re.MULTILINE)
+    match = pattern.search(text)
+    if match is None:
+        return ""
+    start = match.end()
+    next_heading = re.search(r"^\s*##\s+.+$", text[start:], re.MULTILINE)
+    end = start + next_heading.start() if next_heading else len(text)
+    return text[start:end].strip()
+
+
+def _extract_bullets(section_text: str) -> list[str]:
+    return [line.strip()[2:].strip() for line in section_text.splitlines() if line.strip().startswith("- ")]
+
+
+def _count_matches(text: str, pattern: str) -> int:
+    return len(re.findall(pattern, text, flags=re.IGNORECASE))
+
+
+def _missing_keyword_groups(text: str, groups: list[list[str]]) -> list[list[str]]:
+    """For each group, `text` must contain at least one member. Return
+    the groups that had *no* member present — those are the failures.
+
+    Enables the #44 fix: instead of requiring `["signing", "service"]`
+    literally (which fails when Claude legitimately writes `DPoP` or
+    `JWKS` for the same concept), the v2 rubric declares each concept
+    as a group of synonyms.
+    """
+    missing: list[list[str]] = []
+    lowered = text.lower()
+    for group in groups:
+        if not any(term.lower() in lowered for term in group):
+            missing.append(list(group))
+    return missing
+
+
+def _flat_keywords(*, groups: list[list[str]] | None, legacy: list[str] | None) -> list[list[str]]:
+    """Normalize either the v2 group shape or the v1 flat shape into
+    groups. A flat list of `["a", "b"]` becomes `[["a"], ["b"]]` —
+    each term is its own single-synonym group. Preserves v1 behavior
+    exactly while letting the same code drive both."""
+    if groups:
+        return [list(g) for g in groups]
+    if legacy:
+        return [[term] for term in legacy]
+    return []
+
+
+def evaluate_review_text(review_text: str, fixture: dict[str, Any]) -> dict[str, Any]:
+    expectations = fixture.get("expectations", {})
+    checks: list[dict[str, Any]] = []
+
+    grounding = expectations.get("grounding", {})
+    citation_pattern = grounding.get("citation_pattern", r"(?:surface|finding|path):\d+")
+    citations = sorted(set(re.findall(citation_pattern, review_text, flags=re.IGNORECASE)))
+    # Two ways to constrain which IDs are legitimate (see #44):
+    #   - `allowed_id_pattern`: regex — flexible, accepts any evidence-pack
+    #     ID shape (asset:*, insight:*, control:*, detect:*, plus higher
+    #     surface/finding indices). Preferred for v2 rubrics.
+    #   - `allowed_ids`: exact whitelist — v1 behavior, still supported.
+    # If both are set, the pattern wins.
+    allowed_id_pattern_raw = grounding.get("allowed_id_pattern")
+    if allowed_id_pattern_raw:
+        allowed_id_re = re.compile(allowed_id_pattern_raw, flags=re.IGNORECASE)
+        unknown_citations = sorted(c for c in citations if not allowed_id_re.fullmatch(c))
+    else:
+        allowed_ids = set(grounding.get("allowed_ids", []))
+        unknown_citations = (
+            sorted(citation for citation in citations if citation not in allowed_ids)
+            if allowed_ids
+            else []
+        )
+    min_citations = int(grounding.get("min_citations", 0))
+    grounding_pass = len(citations) >= min_citations and not unknown_citations
+    checks.append(
+        {
+            "name": "grounding",
+            "passed": grounding_pass,
+            "details": {
+                "citations_found": citations,
+                "unknown_citations": unknown_citations,
+                "min_citations_required": min_citations,
+            },
+        }
+    )
+
+    observed_inferred = expectations.get("observed_inferred", {})
+    observed_token = observed_inferred.get("observed_token", r"\bOBSERVED\b")
+    inferred_token = observed_inferred.get("inferred_token", r"\bINFERRED\b")
+    observed_count = _count_matches(review_text, observed_token)
+    inferred_count = _count_matches(review_text, inferred_token)
+    observed_required = int(observed_inferred.get("min_observed", 0))
+    inferred_required = int(observed_inferred.get("min_inferred", 0))
+    oi_pass = observed_count >= observed_required and inferred_count >= inferred_required
+    checks.append(
+        {
+            "name": "observed_vs_inferred_discipline",
+            "passed": oi_pass,
+            "details": {
+                "observed_count": observed_count,
+                "inferred_count": inferred_count,
+                "min_observed_required": observed_required,
+                "min_inferred_required": inferred_required,
+            },
+        }
+    )
+
+    strengths_expectation = expectations.get("strengths", {})
+    strengths_section = _extract_section(review_text, "Strengths")
+    strengths_items = _extract_bullets(strengths_section)
+    strengths_groups = _flat_keywords(
+        groups=strengths_expectation.get("required_keyword_groups"),
+        legacy=strengths_expectation.get("required_keywords"),
+    )
+    missing_strengths_groups = _missing_keyword_groups(strengths_section, strengths_groups)
+    min_strengths_items = int(strengths_expectation.get("min_items", 0))
+    strengths_pass = len(strengths_items) >= min_strengths_items and not missing_strengths_groups
+    checks.append(
+        {
+            "name": "strengths_coverage",
+            "passed": strengths_pass,
+            "details": {
+                "item_count": len(strengths_items),
+                "min_items_required": min_strengths_items,
+                "missing_keyword_groups": missing_strengths_groups,
+            },
+        }
+    )
+
+    weakness_expectation = expectations.get("weaknesses_hotspots", {})
+    weakness_section = _extract_section(review_text, "Weaknesses / Risk Hotspots")
+    weakness_items = _extract_bullets(weakness_section)
+    min_weakness_items = int(weakness_expectation.get("min_items", 0))
+    weakness_groups = _flat_keywords(
+        groups=weakness_expectation.get("required_term_groups"),
+        legacy=weakness_expectation.get("required_terms"),
+    )
+    missing_weakness_groups = _missing_keyword_groups(weakness_section, weakness_groups)
+    weakness_pass = len(weakness_items) >= min_weakness_items and not missing_weakness_groups
+    checks.append(
+        {
+            "name": "weakness_hotspot_quality",
+            "passed": weakness_pass,
+            "details": {
+                "item_count": len(weakness_items),
+                "min_items_required": min_weakness_items,
+                "missing_term_groups": missing_weakness_groups,
+            },
+        }
+    )
+
+    recommendation_expectation = expectations.get("recommendations", {})
+    recommendation_section = _extract_section(review_text, "Prioritized Recommendations")
+    recommendation_items = _extract_bullets(recommendation_section)
+    min_recommendation_items = int(recommendation_expectation.get("min_items", 0))
+    action_verbs = [verb.lower() for verb in recommendation_expectation.get("action_verbs", [])]
+    recommendation_text = recommendation_section.lower()
+    recommendation_verbs_present = [verb for verb in action_verbs if verb in recommendation_text]
+    # `action_verbs` is a single "at least one of these must appear" check —
+    # semantically already a group. Keep the flat list shape for
+    # backward-compat; a rubric can just widen it with synonyms.
+    recommendation_pass = len(recommendation_items) >= min_recommendation_items and bool(recommendation_verbs_present)
+    checks.append(
+        {
+            "name": "recommendation_usefulness",
+            "passed": recommendation_pass,
+            "details": {
+                "item_count": len(recommendation_items),
+                "min_items_required": min_recommendation_items,
+                "action_verbs_present": recommendation_verbs_present,
+            },
+        }
+    )
+
+    false_positive_expectation = expectations.get("false_positive_control", {})
+    banned_phrases = [phrase.lower() for phrase in false_positive_expectation.get("banned_phrases", [])]
+    lowered_review = review_text.lower()
+    found_banned = [phrase for phrase in banned_phrases if phrase in lowered_review]
+    caution_groups = _flat_keywords(
+        groups=false_positive_expectation.get("required_caution_groups"),
+        legacy=false_positive_expectation.get("required_cautions"),
+    )
+    missing_caution_groups = _missing_keyword_groups(review_text, caution_groups)
+    false_positive_pass = not found_banned and not missing_caution_groups
+    checks.append(
+        {
+            "name": "false_positive_control",
+            "passed": false_positive_pass,
+            "details": {
+                "found_banned_phrases": found_banned,
+                "missing_required_caution_groups": missing_caution_groups,
+            },
+        }
+    )
+
+    passed_count = sum(1 for check in checks if check["passed"])
+    total_count = len(checks)
+    score = round((passed_count / total_count) * 100.0, 2) if total_count else 0.0
+    return {
+        "fixture_id": fixture.get("fixture_id", "unknown"),
+        "target": fixture.get("target", {}),
+        "summary": {
+            "score": score,
+            "passed_checks": passed_count,
+            "total_checks": total_count,
+            "status": "pass" if passed_count == total_count else "fail",
+        },
+        "checks": checks,
+    }
+
+
+def run_evaluation(fixture_path: str | Path, review_path: str | Path) -> dict[str, Any]:
+    fixture = load_eval_fixture(fixture_path)
+    review_text = load_review_text(review_path)
+    return evaluate_review_text(review_text, fixture)
+
+
+def _resolve_review_path_for_fixture(fixture_path: Path, fixture: dict[str, Any], reviews_dir: Path) -> Path:
+    configured = fixture.get("review_file")
+    if isinstance(configured, str) and configured.strip():
+        return (reviews_dir / configured).resolve()
+    return (reviews_dir / f"{fixture_path.stem}.md").resolve()
+
+
+def run_evaluation_suite(fixtures_dir: str | Path, reviews_dir: str | Path) -> dict[str, Any]:
+    fixture_dir_path = Path(fixtures_dir).resolve()
+    review_dir_path = Path(reviews_dir).resolve()
+    fixture_paths = sorted(fixture_dir_path.glob("*.json"))
+    cases: list[dict[str, Any]] = []
+
+    for fixture_path in fixture_paths:
+        fixture = load_eval_fixture(fixture_path)
+        review_path = _resolve_review_path_for_fixture(fixture_path, fixture, review_dir_path)
+        if not review_path.exists():
+            cases.append(
+                {
+                    "fixture_id": fixture.get("fixture_id", fixture_path.stem),
+                    "summary": {
+                        "score": 0.0,
+                        "passed_checks": 0,
+                        "total_checks": 1,
+                        "status": "fail",
+                    },
+                    "checks": [
+                        {
+                            "name": "review_file_presence",
+                            "passed": False,
+                            "details": {"missing_review_path": str(review_path)},
+                        }
+                    ],
+                }
+            )
+            continue
+        cases.append(run_evaluation(fixture_path, review_path))
+
+    passed = sum(1 for case in cases if case["summary"]["status"] == "pass")
+    total = len(cases)
+    avg_score = round(sum(case["summary"]["score"] for case in cases) / total, 2) if total else 0.0
+    return {
+        "suite": {
+            "fixtures_dir": str(fixture_dir_path),
+            "reviews_dir": str(review_dir_path),
+            "fixture_count": total,
+            "passed": passed,
+            "failed": total - passed,
+            "average_score": avg_score,
+            "status": "pass" if total > 0 and passed == total else "fail",
+        },
+        "cases": cases,
+    }
+
+
+def _main() -> int:
+    parser = argparse.ArgumentParser(description="Evaluate AttackMap defensive review output against a fixture spec.")
+    parser.add_argument("--fixture", help="Path to evaluation fixture JSON.")
+    parser.add_argument("--review", help="Path to review markdown output to evaluate.")
+    parser.add_argument("--fixtures-dir", help="Directory containing evaluation fixture JSON files.")
+    parser.add_argument("--reviews-dir", help="Directory containing review markdown outputs for suite mode.")
+    parser.add_argument("--json", action="store_true", help="Print full JSON result.")
+    args = parser.parse_args()
+
+    if args.fixtures_dir or args.reviews_dir:
+        if not (args.fixtures_dir and args.reviews_dir):
+            parser.error("--fixtures-dir and --reviews-dir must be used together.")
+        if args.fixture or args.review:
+            parser.error("Use either single mode (--fixture/--review) or suite mode (--fixtures-dir/--reviews-dir), not both.")
+        suite_result = run_evaluation_suite(args.fixtures_dir, args.reviews_dir)
+        if args.json:
+            print(json.dumps(suite_result, indent=2))
+        else:
+            summary = suite_result["suite"]
+            print(f"Suite fixtures: {summary['fixture_count']}")
+            print(f"Pass: {summary['passed']}, Fail: {summary['failed']}, Average score: {summary['average_score']}")
+            print(f"Status: {summary['status']}")
+            for case in suite_result["cases"]:
+                case_summary = case["summary"]
+                print(f"- {case['fixture_id']}: {case_summary['status']} ({case_summary['score']})")
+        return 0 if suite_result["suite"]["status"] == "pass" else 1
+
+    if not (args.fixture and args.review):
+        parser.error("Single mode requires --fixture and --review.")
+
+    result = run_evaluation(args.fixture, args.review)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        summary = result["summary"]
+        print(f"Fixture: {result['fixture_id']}")
+        print(f"Score: {summary['score']} ({summary['passed_checks']}/{summary['total_checks']} checks)")
+        print(f"Status: {summary['status']}")
+        for check in result["checks"]:
+            mark = "PASS" if check["passed"] else "FAIL"
+            print(f"- {mark}: {check['name']}")
+    return 0 if result["summary"]["status"] == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

attackmap/review_json.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+from .detection_opportunities import detection_coverage
+from .models import AttackPath, AttackSurface, Finding, ScanResult
+from .security_overlay import build_security_overlay
+
+# 1.3.0: weaknesses[].locations (#214); 1.4.0: weaknesses[].rule_id/taxonomy
+# (#250); 1.5.0: detection_opportunities[].sigma/... and detection_coverage (#251)
+SCHEMA_VERSION = "1.5.0"
+LOW_QUALITY_SEGMENTS = ("/tests/", "/__tests__/", "/fixtures/", "/mocks/", "/examples/")
+
+
+def _severity_rank(value: str) -> int:
+    return {"high": 0, "medium": 1, "low": 2}.get(value, 3)
+
+
+def _risk_rank(value: str) -> int:
+    return {"high": 0, "medium": 1, "low": 2}.get(value, 3)
+
+
+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 _is_protocol_derived_surface(surface: AttackSurface) -> bool:
+    file_lower = surface.file.lower()
+    route_lower = surface.route.lower()
+    return "lexicon" in file_lower or "/xrpc/" in route_lower or "atproto_" in " ".join(surface.auth_signals).lower()
+
+
+def _surface_evidence_class(surface: AttackSurface) -> str:
+    if _is_low_quality_source(surface.file):
+        return "low_quality"
+    if _is_protocol_derived_surface(surface):
+        return "inferred_protocol"
+    if surface.exposure == "public":
+        return "observed_runtime_public"
+    if surface.exposure == "internal":
+        return "observed_runtime_internal"
+    return "inferred"
+
+
+def _evidence_class_counts(surfaces: list[AttackSurface]) -> dict[str, int]:
+    counts = {
+        "observed_runtime_public": 0,
+        "observed_runtime_internal": 0,
+        "inferred_protocol": 0,
+        "inferred": 0,
+        "low_quality": 0,
+    }
+    for surface in surfaces:
+        counts[_surface_evidence_class(surface)] += 1
+    return counts
+
+
+def _strengths(scan: ScanResult, attack_surfaces: list[AttackSurface]) -> list[dict]:
+    strengths: list[dict] = []
+    auth_hints = sorted({hint.hint for hint in scan.auth_hints})
+    if auth_hints:
+        strengths.append(
+            {
+                "statement": "Authentication/identity indicators were observed in code signals.",
+                "evidence_basis": "observed",
+                "evidence": auth_hints[:8],
+            }
+        )
+    internal_surfaces = [surface for surface in attack_surfaces if surface.exposure == "internal"]
+    if internal_surfaces:
+        strengths.append(
+            {
+                "statement": "Some inferred entry points appear internal-only, reducing direct internet exposure when network boundaries are correctly enforced.",
+                "evidence_basis": "inferred",
+                "evidence": [f"{surface.method} {surface.route} ({surface.location()})" for surface in internal_surfaces[:6]],
+            }
+        )
+    if scan.secret_hints:
+        strengths.append(
+            {
+                "statement": "Secret references appear environment-driven rather than hardcoded literals.",
+                "evidence_basis": "observed",
+                "evidence": [f"{hint.name} ({hint.file})" for hint in scan.secret_hints[:8]],
+            }
+        )
+    if not strengths:
+        strengths.append(
+            {
+                "statement": "No strong defensive indicators were detected heuristically.",
+                "evidence_basis": "inferred",
+                "evidence": [],
+            }
+        )
+    return strengths[:4]
+
+
+def _related_surfaces_for_finding(finding: Finding, attack_surfaces: list[AttackSurface]) -> list[AttackSurface]:
+    combined = f"{finding.title} {' '.join(finding.evidence)}".lower()
+    related = [
+        surface
+        for surface in attack_surfaces
+        if surface.route.lower() in combined
+        or surface.file.lower() in combined
+        or surface.category.lower() in combined
+    ]
+    return related or attack_surfaces
+
+
+def _basis_label_for_surfaces(surfaces: list[AttackSurface]) -> str:
+    counts = _evidence_class_counts(surfaces)
+    total = max(sum(counts.values()), 1)
+    observed_total = counts["observed_runtime_public"] + counts["observed_runtime_internal"]
+    if (observed_total / total) >= 0.5:
+        return "observed"
+    if (counts["inferred_protocol"] / total) >= 0.5:
+        return "inferred_protocol"
+    if (counts["low_quality"] / total) >= 0.5:
+        return "low_quality"
+    return "mixed"
+
+
+def _weaknesses_and_hotspots(
+    attack_surfaces: list[AttackSurface],
+    findings: list[Finding],
+) -> tuple[list[dict], list[dict]]:
+    ordered_findings = sorted(findings, key=lambda finding: (_severity_rank(finding.severity), finding.title))
+    weakness_items = []
+    for finding in ordered_findings[:8]:
+        related = _related_surfaces_for_finding(finding, attack_surfaces)
+        weakness_items.append(
+            {
+                "title": finding.title,
+                "rule_id": finding.rule_id,
+                "taxonomy": finding.taxonomy.model_dump() if finding.taxonomy else None,
+                "severity": finding.severity,
+                "confidence": finding.confidence,
+                "evidence_basis": _basis_label_for_surfaces(related),
+                "evidence": finding.evidence[:10],
+                "locations": [loc.model_dump() for loc in finding.locations],
+                "mitigation": finding.mitigation,
+                "attack_techniques": [t.model_dump() for t in finding.attack_techniques],
+            }
+        )
+
+    runtime_surfaces = [surface for surface in attack_surfaces if not _is_low_quality_source(surface.file)]
+    hotspot_pool = runtime_surfaces if runtime_surfaces else attack_surfaces
+    hotspot_pool = sorted(
+        hotspot_pool,
+        key=lambda surface: (_risk_rank(surface.risk), surface.exposure != "public", surface.route),
+    )
+    hotspot_items = [
+        {
+            "surface": {
+                "method": surface.method,
+                "route": surface.route,
+                "file": surface.file,
+                "category": surface.category,
+                "risk": surface.risk,
+                "exposure": surface.exposure,
+            },
+            "evidence_class": _surface_evidence_class(surface),
+            "notes": surface.rationale[:3],
+        }
+        for surface in hotspot_pool[:6]
+    ]
+    return weakness_items, hotspot_items
+
+
+def _evidence_chains(attack_paths: list[AttackPath]) -> list[dict]:
+    chains = []
+    for path in attack_paths[:6]:
+        joined = " ".join(path.steps).lower()
+        basis = "inferred"
+        if "entry:" in joined and "confidence=" in joined:
+            basis = "observed_plus_inferred"
+        elif "entry:" in joined:
+            basis = "observed"
+        chains.append(
+            {
+                "name": path.name,
+                "impact": path.impact,
+                "evidence_basis": basis,
+                "steps": path.steps[:8],
+            }
+        )
+    return chains
+
+
+def _recommendations(findings: list[Finding], attack_surfaces: list[AttackSurface]) -> list[dict]:
+    ordered_findings = sorted(findings, key=lambda finding: (_severity_rank(finding.severity), finding.title))
+    recommendations: list[dict] = []
+    seen: set[str] = set()
+    for finding in ordered_findings:
+        mitigation = finding.mitigation.strip()
+        if not mitigation or mitigation in seen:
+            continue
+        seen.add(mitigation)
+        related = _related_surfaces_for_finding(finding, attack_surfaces)
+        recommendations.append(
+            {
+                "priority": finding.severity,
+                "evidence_basis": _basis_label_for_surfaces(related),
+                "action": mitigation,
+                "linked_finding": finding.title,
+            }
+        )
+        if len(recommendations) >= 8:
+            break
+    return recommendations
+
+
+def build_defensive_review_json(
+    scan: ScanResult,
+    attack_surfaces: list[AttackSurface],
+    findings: list[Finding],
+    attack_paths: list[AttackPath],
+) -> dict:
+    evidence_counts = _evidence_class_counts(attack_surfaces)
+    overlay = build_security_overlay(scan, attack_surfaces, findings, attack_paths)
+    weaknesses, hotspots = _weaknesses_and_hotspots(attack_surfaces, overlay.findings)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "target_metadata": {
+            "root": scan.root,
+            "files_scanned": scan.files_scanned,
+            "languages": scan.languages,
+        },
+        "system_overview": {
+            "repository_type": "web/service-facing" if scan.routes else "non-web",
+            "raw_inferred_entry_point_count": len(scan.routes),
+            "external_call_count": len(scan.external_calls),
+            "database_count": len(scan.databases),
+            "auth_hint_count": len(scan.auth_hints),
+            "secret_hint_count": len(scan.secret_hints),
+            "asset_count": len(overlay.assets),
+            "control_count_present": sum(1 for c in overlay.controls if c.strength != "absent"),
+            "control_count_absent": sum(1 for c in overlay.controls if c.strength == "absent"),
+            "notable_observation_count": len(overlay.insights),
+            "detection_opportunity_count": len(overlay.detection_opportunities),
+            "attack_techniques_observed_count": len(_flatten_attack_techniques(overlay)),
+        },
+        "attack_surface": {
+            "total_surfaces": len(attack_surfaces),
+            "evidence_class_counts": evidence_counts,
+            "surfaces": [
+                {
+                    "method": surface.method,
+                    "route": surface.route,
+                    "file": surface.file,
+                    "line": surface.line,
+                    "category": surface.category,
+                    "exposure": surface.exposure,
+                    "risk": surface.risk,
+                    "evidence_class": _surface_evidence_class(surface),
+                    "auth_signals": surface.auth_signals,
+                    "data_store_interaction": surface.data_store_interaction,
+                    "outbound_integration": surface.outbound_integration,
+                }
+                for surface in attack_surfaces[:60]
+            ],
+        },
+        "assets": [asset.model_dump() for asset in overlay.assets],
+        "controls": [control.model_dump() for control in overlay.controls],
+        "notable_observations": [insight.model_dump() for insight in overlay.insights],
+        "detection_opportunities": [opp.model_dump() for opp in overlay.detection_opportunities],
+        "detection_coverage": detection_coverage(overlay.findings, overlay.detection_opportunities),
+        "attack_techniques_observed": _flatten_attack_techniques(overlay),
+        "strengths": _strengths(scan, attack_surfaces),
+        "weaknesses_risk_hotspots": {
+            "weaknesses": weaknesses,
+            "risk_hotspots": hotspots,
+        },
+        "evidence_chains": _evidence_chains(attack_paths),
+        "recommendations": _recommendations(overlay.findings, attack_surfaces),
+        "raw_structured_signals": {
+            "scan": scan.model_dump(),
+            "attack_surfaces": [surface.model_dump() for surface in attack_surfaces],
+            "findings": [finding.model_dump() for finding in overlay.findings],
+            "attack_paths": [path.model_dump() for path in attack_paths],
+            "assets": [asset.model_dump() for asset in overlay.assets],
+            "controls": [control.model_dump() for control in overlay.controls],
+            "notable_observations": [insight.model_dump() for insight in overlay.insights],
+            "detection_opportunities": [opp.model_dump() for opp in overlay.detection_opportunities],
+        },
+        "limitations_meta": {
+            "analysis_mode": "heuristic",
+            "defensive_only": True,
+            "notes": [
+                "Observed vs inferred classifications are heuristic and based on route, file, and signal patterns.",
+                "Low-quality paths (tests/fixtures/mocks/examples) are retained in raw signals but separated in evidence class counts.",
+                "Use this artifact as a triage source-of-truth; validate high-priority items with repository context and runtime controls.",
+                "Assets, controls, and notable observations are heuristic overlays; absent-control entries indicate scanner did not find evidence, not necessarily that the control is missing in production.",
+                "ATT&CK technique mappings and detection opportunities are derived from insight kinds and finding rule ids; treat them as triage hooks for SIEM/detection-engineering work, not authoritative MITRE mappings.",
+                "Generated Sigma rules are status experimental: map their log-source fields to your pipeline and tune them on your own traffic before alerting on them.",
+            ],
+        },
+    }
+
+
+def _flatten_attack_techniques(overlay) -> list[dict]:
+    """Deduplicated list of ATT&CK techniques observed across insights and findings."""
+    by_id: dict[str, dict] = {}
+    for insight in overlay.insights:
+        for technique in insight.attack_techniques:
+            by_id.setdefault(technique.technique_id, technique.model_dump())
+    for finding in overlay.findings:
+        for technique in finding.attack_techniques:
+            by_id.setdefault(technique.technique_id, technique.model_dump())
+    return sorted(by_id.values(), key=lambda t: t["technique_id"])