attackmap 0.6.4__py3-none-any.whl

attackmap/safe_fs.py

@@ -0,0 +1,285 @@
+"""Filesystem access confined to the scanned repository (#234, #228).
+
+AttackMap scans untrusted checkouts, so a symlink in the repo must never make
+it read a file outside the repo (and report or send that file's content
+elsewhere), and a symlink planted where a report is about to be written must
+never redirect that write.
+
+Read side:
+    * :func:`walk_repo` yields the regular files under a root without
+      following symlinks — symlinked files are skipped and symlinked
+      directories are not descended. Set ``ATTACKMAP_FOLLOW_SYMLINKS=1`` to
+      follow symlinks whose target resolves inside the root.
+    * :func:`is_contained` / :func:`contained_file` validate a path (or a
+      repo-relative path taken from evidence text) before it is read.
+    * :func:`read_repo_text` reads a file only if it is contained.
+
+Write side:
+    * :func:`safe_write_text` refuses to write through a symlink or outside
+      the output directory, and never follows a symlink planted at the target.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Iterable, Iterator
+from pathlib import Path
+
+FOLLOW_SYMLINKS_ENV = "ATTACKMAP_FOLLOW_SYMLINKS"
+# Written into every report directory (#216); walk_repo never descends into a
+# directory that contains it, whatever the directory is called.
+OUTPUT_MARKER = ".attackmap-output"
+
+# Marker files the current run must not honour (GHSA-j544-8x8g-c3mw): under
+# --suppress-from-ref the CLI registers every marker that is not present at
+# the trusted ref, so a pull request cannot exclude a directory from the scan
+# by committing an empty `.attackmap-output`. Absolute, normalized paths.
+_UNTRUSTED_MARKERS: set[str] = set()
+
+
+def set_untrusted_output_markers(markers: Iterable[str | Path]) -> None:
+    """Replace the set of marker files ``walk_repo`` must ignore."""
+    _UNTRUSTED_MARKERS.clear()
+    _UNTRUSTED_MARKERS.update(os.path.abspath(str(m)) for m in markers)
+
+
+def output_marker_files(root: str | Path) -> list[Path]:
+    """Every ``OUTPUT_MARKER`` file under ``root`` (not the root's own), as
+    paths relative to ``root``; symlinks are not followed."""
+    root_path = Path(root)
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root_path):
+        dirnames[:] = sorted(d for d in dirnames if not (Path(dirpath) / d).is_symlink())
+        if OUTPUT_MARKER in filenames and Path(dirpath) != root_path:
+            marker = Path(dirpath) / OUTPUT_MARKER
+            if marker.is_file() and not marker.is_symlink():
+                found.append(marker.relative_to(root_path))
+    return found
+MAX_FILE_BYTES_ENV = "ATTACKMAP_MAX_FILE_BYTES"
+# Files larger than this are not read (#236): a hostile or generated multi-MB
+# file must not stall a CI scan. Real source files are far smaller.
+DEFAULT_MAX_FILE_BYTES = 2_000_000
+
+
+class UnsafePathError(OSError):
+    """A read or write would escape the repository / output directory."""
+
+
+def max_file_bytes() -> int:
+    raw = os.environ.get(MAX_FILE_BYTES_ENV, "").strip()
+    try:
+        value = int(raw) if raw else DEFAULT_MAX_FILE_BYTES
+    except ValueError:
+        value = DEFAULT_MAX_FILE_BYTES
+    return value if value > 0 else DEFAULT_MAX_FILE_BYTES
+
+
+def is_oversized(path: Path) -> bool:
+    """True when ``path`` is larger than the per-file read cap."""
+    try:
+        return path.stat().st_size > max_file_bytes()
+    except OSError:
+        return False
+
+
+def follow_symlinks_enabled() -> bool:
+    return os.environ.get(FOLLOW_SYMLINKS_ENV, "").strip().lower() in {"1", "true", "yes"}
+
+
+def _resolved_within(root: Path, path: Path) -> bool:
+    try:
+        return path.resolve().is_relative_to(root.resolve())
+    except (OSError, RuntimeError):  # RuntimeError: symlink loop on some Pythons
+        return False
+
+
+def is_contained(root: str | Path, path: str | Path) -> bool:
+    """True when ``path`` is inside ``root`` and is not reached via a symlink.
+
+    Every component between ``root`` and ``path`` is checked with ``lstat`` —
+    a symlinked directory in the middle of the path disqualifies it just like
+    a symlinked file. With ``ATTACKMAP_FOLLOW_SYMLINKS=1`` symlinks are allowed
+    as long as the fully resolved path stays inside ``root``.
+    """
+    root_path = Path(root)
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = root_path / candidate
+    try:
+        rel = candidate.relative_to(root_path)
+    except ValueError:
+        try:
+            rel = candidate.relative_to(root_path.resolve())
+            root_path = root_path.resolve()
+        except ValueError:
+            return False
+    if ".." in rel.parts:
+        return False
+    if follow_symlinks_enabled():
+        return _resolved_within(root_path, candidate)
+    current = root_path
+    for part in rel.parts:
+        current = current / part
+        if current.is_symlink():
+            return False
+    return _resolved_within(root_path, candidate)
+
+
+def is_unsafe_link(root: str | Path, entry: Path) -> bool:
+    """For hand-rolled ``iterdir`` walkers: True when ``entry`` is a symlink
+    that must be skipped (always, unless follow mode is on and it resolves
+    inside ``root``)."""
+    if not entry.is_symlink():
+        return False
+    return not (follow_symlinks_enabled() and _resolved_within(Path(root), entry))
+
+
+def contained_file(root: str | Path, rel: str | Path) -> Path | None:
+    """Resolve a repo-relative path from untrusted text (evidence, plugin
+    output) to a regular file inside ``root``, or ``None``.
+
+    Absolute paths and paths with ``..`` components are rejected outright.
+    """
+    rel_path = Path(rel)
+    if rel_path.is_absolute() or ".." in rel_path.parts or str(rel).startswith("~"):
+        return None
+    candidate = Path(root) / rel_path
+    if not is_contained(root, candidate):
+        return None
+    try:
+        return candidate if candidate.is_file() else None
+    except OSError:
+        return None
+
+
+def read_repo_text(
+    root: str | Path, path: str | Path, *, encoding: str = "utf-8", errors: str = "strict"
+) -> str:
+    """``Path.read_text`` that refuses paths outside ``root`` or behind a symlink."""
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = Path(root) / candidate
+    if not is_contained(root, candidate):
+        raise UnsafePathError(f"refusing to read outside the repository: {path}")
+    return candidate.read_text(encoding=encoding, errors=errors)
+
+
+def walk_repo(
+    root: str | Path,
+    *,
+    prune: Callable[[str], bool] | None = None,
+    on_symlink: Callable[[Path], None] | None = None,
+    on_prune: Callable[[Path], None] | None = None,
+) -> Iterator[Path]:
+    """Yield regular files under ``root`` (depth-first, sorted per directory).
+
+    Symlinks are skipped — symlinked files are not yielded and symlinked
+    directories are not descended — and ``on_symlink(path)`` is called for
+    each. With ``ATTACKMAP_FOLLOW_SYMLINKS=1`` symlinks whose target resolves
+    inside ``root`` are followed (cycle-safe); ones pointing outside are still
+    skipped. ``prune(dirname)`` returning True skips descending into a
+    directory. ``on_prune(dir)`` is called for each directory skipped
+    because it carries an output marker, so the caller can record it.
+    """
+    root_path = Path(root)
+    follow = follow_symlinks_enabled()
+    seen_dirs: set[str] = set()
+    for dirpath, dirnames, filenames in os.walk(root_path, followlinks=follow):
+        current = Path(dirpath)
+        if follow:
+            real = os.path.realpath(dirpath)
+            if real in seen_dirs or not _resolved_within(root_path, current):
+                dirnames[:] = []
+                continue
+            seen_dirs.add(real)
+        kept_dirs = []
+        for name in sorted(dirnames):
+            if prune is not None and prune(name):
+                continue
+            child = current / name
+            # Our own report output, under any name (#216). Not checked for the
+            # root itself, so `-o .` can't make a repo unscannable. A marker the
+            # CLI registered as untrusted (added since the PR base) is ignored
+            # and the directory is scanned (GHSA-j544-8x8g-c3mw).
+            marker = child / OUTPUT_MARKER
+            if marker.is_file() and not marker.is_symlink():
+                if os.path.abspath(marker) not in _UNTRUSTED_MARKERS:
+                    if on_prune is not None:
+                        on_prune(child)
+                    continue
+            if child.is_symlink() and not (follow and _resolved_within(root_path, child)):
+                if on_symlink is not None:
+                    on_symlink(child)
+                continue
+            kept_dirs.append(name)
+        dirnames[:] = kept_dirs
+        for name in sorted(filenames):
+            child = current / name
+            if child.is_symlink() and not (follow and _resolved_within(root_path, child)):
+                if on_symlink is not None:
+                    on_symlink(child)
+                continue
+            try:
+                if child.is_file():
+                    yield child
+            except OSError:
+                continue
+
+
+def ensure_output_dir(out_dir: str | Path, *, mark: bool = False) -> Path:
+    """Create the report directory, refusing a symlinked one.
+
+    No ancestor inside the current working directory (usually the checkout
+    being scanned) may be a symlink that leads outside it — otherwise a
+    committed ``reports -> /somewhere`` link would redirect every report write
+    (#228). Symlinks that stay inside the cwd are allowed, which also covers
+    system links such as macOS's ``/var`` and ``/tmp`` (→ ``/private/...``)
+    when the cwd is ``/``, as it is for a GUI-launched or test-runner process.
+    """
+    out = Path(out_dir)
+    absolute = out.absolute()
+    cwd = Path.cwd()
+    real_cwd = cwd.resolve()
+    for candidate in (absolute, *absolute.parents):
+        if candidate == cwd or not candidate.is_relative_to(cwd):
+            continue
+        if candidate.is_symlink() and not candidate.resolve().is_relative_to(real_cwd):
+            raise UnsafePathError(f"refusing to write reports through a symlink: {candidate}")
+    out.mkdir(parents=True, exist_ok=True)
+    if out.is_symlink():
+        raise UnsafePathError(f"refusing to write reports into a symlinked directory: {out}")
+    if mark:
+        marker = out / OUTPUT_MARKER
+        if not marker.exists() and not marker.is_symlink():
+            safe_write_text(
+                out,
+                marker,
+                "AttackMap report directory. AttackMap never scans a directory containing this file.\n",
+            )
+    return out
+
+
+def safe_write_text(out_dir: str | Path, path: str | Path, text: str, *, encoding: str = "utf-8") -> None:
+    """Write ``text`` to ``path`` without following symlinks.
+
+    Refuses when ``path`` is (or sits behind) a symlink, or resolves outside
+    ``out_dir``. The final open uses ``O_NOFOLLOW`` so a symlink swapped in
+    after the check is not followed either.
+    """
+    out = Path(out_dir)
+    target = Path(path)
+    if out.is_symlink():
+        raise UnsafePathError(f"refusing to write reports into a symlinked directory: {out}")
+    if target.is_symlink():
+        raise UnsafePathError(f"refusing to write through a symlink: {target}")
+    if not target.parent.resolve().is_relative_to(out.resolve()):
+        raise UnsafePathError(f"refusing to write outside the output directory {out}: {target}")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(target, flags, 0o644)
+    except OSError as exc:
+        if target.is_symlink():
+            raise UnsafePathError(f"refusing to write through a symlink: {target}") from exc
+        raise
+    with os.fdopen(fd, "w", encoding=encoding) as handle:
+        handle.write(text)

attackmap/sarif.py

@@ -0,0 +1,373 @@
+"""SARIF 2.1.0 report emission.
+
+Turns AttackMap `Finding` records into a SARIF log that GitHub Code
+Scanning (and other SARIF consumers — VS Code, Sonatype IQ, etc.)
+ingest natively. Every field the finding model carries maps to a SARIF
+property; nothing new is computed here — it's a serialization layer.
+
+Reference: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from urllib.parse import quote
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from .srcpaths import evidence_locations
+from .md import md_text
+from .models import AttackPath, Finding, TaintFlowStep, finding_rule_id
+from .taxonomy import CWE_NAMES, cwe_tag, cwe_url, taxonomy_for
+
+
+SARIF_VERSION = "2.1.0"
+SARIF_SCHEMA_URI = (
+    "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/"
+    "Schemata/sarif-schema-2.1.0.json"
+)
+TOOL_INFO_URI = "https://github.com/mlaify/AttackMap"
+
+
+# ---------------------------------------------------------------------------
+# Severity + score mappings
+# ---------------------------------------------------------------------------
+
+
+def _sarif_level(severity: str) -> str:
+    """SARIF `level` is one of `error`, `warning`, `note`, `none`."""
+    return {"high": "error", "medium": "warning", "low": "note"}.get(severity, "warning")
+
+
+def _security_severity(severity: str, confidence: str) -> str:
+    """SARIF `securitySeverity` is a 0.0-10.0 string, mirroring CVSS.
+
+    We derive it heuristically from `Finding.severity × Finding.confidence`
+    so consumers that filter by CVSS band (a common GitHub Code Scanning
+    workflow) get a reasonable ordering out of the box.
+    """
+    weights = {"high": 9.0, "medium": 6.0, "low": 3.0}
+    multiplier = {"high": 1.0, "medium": 0.75, "low": 0.5}.get(confidence, 0.75)
+    value = weights.get(severity, 6.0) * multiplier
+    # Clamp to SARIF's 0.0-10.0 range and 1-decimal precision.
+    return f"{min(10.0, max(0.0, value)):.1f}"
+
+
+def _slugify(text: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug or "finding"
+
+
+SRCROOT = "%SRCROOT%"
+
+
+def _sarif_uri(file_path: str) -> str:
+    """Repo-relative, forward-slashed, percent-encoded artifact URI (#230)."""
+    return quote(file_path.replace("\\", "/").lstrip("/"), safe="/@()[]+~-._")
+
+
+def _sarif_location(file_path: str, line_num: int | None) -> dict[str, Any]:
+    physical: dict[str, Any] = {"artifactLocation": {"uri": _sarif_uri(file_path), "uriBaseId": SRCROOT}}
+    # No fabricated `startLine: 1` (#230): a location without a known line is
+    # a file-level location with no region.
+    if line_num is not None and line_num >= 1:
+        physical["region"] = {"startLine": line_num}
+    return {"physicalLocation": physical}
+
+
+def _instances(finding: Finding) -> list[tuple[str, int | None, str | None]]:
+    """``(file, line, fingerprint)`` per instance: structured locations first
+    (with their #222 fingerprints), else the files cited in evidence."""
+    if finding.locations:
+        pairs = [(loc.file, loc.line, loc.fingerprint) for loc in finding.locations]
+    else:
+        pairs = [(f, l, None) for f, l in evidence_locations(finding.evidence)]
+    # A fingerprint makes an instance distinct even at a repeated (file, line):
+    # two resources without a line in one file are two results.
+    seen: set[tuple[str, int | None, str | None]] = set()
+    out: list[tuple[str, int | None, str | None]] = []
+    for file, line, fp in pairs:
+        norm = file.replace("\\", "/")
+        key = (norm, line, fp)
+        if key not in seen:
+            seen.add(key)
+            out.append((norm, line, fp))
+    return out
+
+
+def _finding_locations(finding: Finding) -> list[dict[str, Any]]:
+    return [_sarif_location(file, line) for file, line, _ in _instances(finding)]
+
+
+def _locations_from_evidence(evidence: list[str]) -> list[dict[str, Any]]:
+    return [_sarif_location(path, line) for path, line in evidence_locations(evidence)]
+
+
+# ---------------------------------------------------------------------------
+# SARIF construction
+# ---------------------------------------------------------------------------
+
+
+def _tool_version() -> str:
+    try:
+        return version("attackmap")
+    except PackageNotFoundError:
+        return "0.0.0-dev"
+
+
+def _build_rules(findings: list[Finding]) -> list[dict[str, Any]]:
+    """One SARIF rule per unique finding title. Consumers use rule ids
+    to filter, ignore, or roll up findings; sharing the rule across
+    identical-title findings keeps the taxonomy stable."""
+    rules_by_id: dict[str, dict[str, Any]] = {}
+    for finding in findings:
+        rule_id = finding_rule_id(finding)
+        if rule_id in rules_by_id:
+            continue
+        title, severity, confidence, mitigation = finding.title, finding.severity, finding.confidence, finding.mitigation
+        # A severity-tiered rule has a finding per tier: describe the rule by
+        # its spec's default tier, not by whichever tier came first.
+        from .threat_model import tiered_rule_defaults
+
+        defaults = tiered_rule_defaults(rule_id)
+        if defaults is not None:
+            title, severity, mitigation = defaults
+            confidence = "high"
+        rules_by_id[rule_id] = {
+            "id": rule_id,
+            "name": title,
+            "shortDescription": {"text": title},
+            "fullDescription": {"text": title},
+            "help": {"text": mitigation, "markdown": mitigation},
+            "defaultConfiguration": {"level": _sarif_level(severity)},
+            "properties": {
+                "tags": list(finding.tags),
+                "security-severity": _security_severity(severity, confidence),
+            },
+        }
+        _add_rule_taxonomy(rules_by_id[rule_id], rule_id)
+    return list(rules_by_id.values())
+
+
+CWE_TAXONOMY = "CWE"
+
+
+def _add_rule_taxonomy(rule: dict[str, Any], rule_id: str) -> None:
+    """CWE tags, helpUri, CWE relationships and the OWASP/ASVS/ATT&CK ids
+    from the taxonomy registry (#250). Unregistered rules are left as is."""
+    entry = taxonomy_for(rule_id)
+    if entry is None:
+        return
+    props = rule["properties"]
+    # Detectors may already tag the CWE (workflow findings do); keep one copy.
+    props["tags"] = list(dict.fromkeys([*props["tags"], *(cwe_tag(c) for c in entry.cwe)]))
+    props["cwe"] = entry.cwe_ids
+    props["owasp"] = list(entry.owasp)
+    if entry.asvs:
+        props["asvs"] = list(entry.asvs)
+    if entry.attack:
+        props["attack"] = list(entry.attack)
+    rule["helpUri"] = cwe_url(entry.cwe[0])
+    rule["relationships"] = [
+        {"target": {"id": str(c), "toolComponent": {"name": CWE_TAXONOMY}}, "kinds": ["superset"]}
+        for c in entry.cwe
+    ]
+
+
+def _cwe_taxonomy(rules: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """The run's CWE `taxonomies` entry: one taxon per CWE a rule cites."""
+    ids = sorted(
+        {int(rel["target"]["id"]) for rule in rules for rel in rule.get("relationships", [])}
+    )
+    if not ids:
+        return None
+    return {
+        "name": CWE_TAXONOMY,
+        "organization": "MITRE",
+        "informationUri": "https://cwe.mitre.org/",
+        "shortDescription": {"text": "The MITRE Common Weakness Enumeration"},
+        "taxa": [
+            {
+                "id": str(c),
+                "name": CWE_NAMES.get(c, f"CWE-{c}"),
+                "shortDescription": {"text": CWE_NAMES.get(c, f"CWE-{c}")},
+                "helpUri": cwe_url(c),
+            }
+            for c in ids
+        ],
+    }
+
+
+def _stable_hash(*parts: object) -> str:
+    return hashlib.sha256("\x1f".join(str(p) for p in parts).encode("utf-8")).hexdigest()[:32]
+
+
+def _code_flow(steps: list[TaintFlowStep]) -> dict[str, Any]:
+    """A traced source→sink flow (#239) as a SARIF ``codeFlow``: one
+    threadFlow whose locations are the source, each propagation /
+    sanitizer / guard step, and the sink."""
+    locations = []
+    for step in steps:
+        loc = _sarif_location(step.file, step.line)
+        loc["message"] = {"text": f"{step.kind}: {step.evidence_text or ''}".rstrip(": ")}
+        locations.append({"location": loc, "kinds": [step.kind]})
+    source = steps[0] if steps else None
+    text = f"{source.evidence_text} flows to the sink" if source and source.evidence_text else "taint flow"
+    return {"message": {"text": text}, "threadFlows": [{"locations": locations}]}
+
+
+def _flows_by_sink(finding: Finding) -> dict[tuple[str, int | None], list[dict[str, Any]]]:
+    out: dict[tuple[str, int | None], list[dict[str, Any]]] = {}
+    for steps in finding.code_flows:
+        if not steps:
+            continue
+        sink = steps[-1]
+        out.setdefault((sink.file.replace("\\", "/"), sink.line), []).append(_code_flow(steps))
+    return out
+
+
+def _build_result(finding: Finding, *, suppression_reason: str | None = None) -> list[dict[str, Any]]:
+    """One SARIF result per finding instance (#230).
+
+    Each result carries a single primary location and a partial fingerprint
+    derived from (rule id, instance fingerprint) — never evidence text — so
+    Code Scanning keeps alert identity (and dismissals) stable when another
+    instance appears or a snippet changes. Evidence lives in properties.
+    """
+    rule_id = finding_rule_id(finding)
+    properties: dict[str, Any] = {
+        "tags": list(finding.tags),
+        "security-severity": _security_severity(finding.severity, finding.confidence),
+        "confidence": finding.confidence,
+    }
+    if finding.score is not None:
+        # SARIF `rank` is 0-100, higher = more important — same
+        # direction as `score` from #4.
+        properties["rank"] = float(finding.score)
+    if finding.evidence:
+        properties["evidence"] = list(finding.evidence[:8])
+
+    def result(location: dict[str, Any] | None, fingerprint: str) -> dict[str, Any]:
+        r: dict[str, Any] = {
+            "ruleId": rule_id,
+            "level": _sarif_level(finding.severity),
+            "message": {
+                "text": finding.title,
+                "markdown": f"**{md_text(finding.title)}**\n\n{finding.mitigation}",
+            },
+            "partialFingerprints": {"attackmapInstance/v1": fingerprint},
+            "properties": properties,
+        }
+        if location is not None:
+            r["locations"] = [location]
+        # Suppressed findings stay in the log (not dropped) but carry a SARIF
+        # `suppressions` array so viewers / GitHub Code Scanning show them as
+        # suppressed rather than active (#144).
+        if suppression_reason is not None:
+            r["suppressions"] = [
+                {"kind": "external", "justification": suppression_reason or "suppressed by AttackMap"}
+            ]
+        return r
+
+    instances = _instances(finding)
+    if not instances:
+        # Repo-level finding (no citable file): identity is the rule + title.
+        return [result(None, _stable_hash(rule_id, finding.title))]
+    results = [
+        result(_sarif_location(file, line), _stable_hash(rule_id, fp or f"{file}:{line}"))
+        for file, line, fp in instances
+    ]
+    # Traced taint flows (#239) ride on the result at their sink location.
+    flows = _flows_by_sink(finding)
+    if flows:
+        for r, (file, line, _) in zip(results, instances):
+            matched = flows.pop((file, line), None)
+            if matched:
+                r["codeFlows"] = matched
+    return results
+
+
+def _build_results(findings: list[Finding]) -> list[dict[str, Any]]:
+    return [r for finding in findings for r in _build_result(finding)]
+
+
+def _build_code_flows_from_attack_paths(
+    attack_paths: list[AttackPath],
+) -> list[dict[str, Any]]:
+    """Turn each attack path into a SARIF `codeFlow`. This gives the
+    narrative a first-class home separate from findings — SARIF viewers
+    render codeFlows as expandable step lists.
+
+    Codeflows aren't attached to a specific result here (attack paths
+    are repo-scoped, not per-finding); consumers that want them
+    inline can traverse the tool.driver.properties.attackPaths link.
+    """
+    flows: list[dict[str, Any]] = []
+    for path in attack_paths:
+        # Steps are narrative, not code positions: a message-only location
+        # (no fabricated empty URI / line 1, #230).
+        thread_flow_locations = [{"location": {"message": {"text": step}}} for step in path.steps]
+        flows.append(
+            {
+                "message": {"text": f"{path.name}: {path.impact}"},
+                "threadFlows": [{"locations": thread_flow_locations}],
+            }
+        )
+    return flows
+
+
+def build_sarif(
+    findings: list[Finding],
+    attack_paths: list[AttackPath] | None = None,
+    *,
+    suppressed: list[tuple[Finding, str]] | None = None,
+) -> dict[str, Any]:
+    """Serialize `findings` (+ optional `attack_paths`) as a SARIF 2.1.0
+    log dict. Caller is responsible for writing it to disk.
+
+    `suppressed` is a list of ``(finding, justification)`` pairs (#144):
+    they are emitted as results carrying a SARIF ``suppressions`` array so
+    consumers show them as suppressed rather than active.
+    """
+    suppressed = suppressed or []
+    # Rules taxonomy must cover suppressed findings too, so their ruleId
+    # resolves in viewers.
+    rules = _build_rules(findings + [f for f, _ in suppressed])
+    results = _build_results(findings)
+    for f, reason in suppressed:
+        results.extend(_build_result(f, suppression_reason=reason))
+
+    driver: dict[str, Any] = {
+        "name": "AttackMap",
+        "version": _tool_version(),
+        "informationUri": TOOL_INFO_URI,
+        "rules": rules,
+    }
+    cwe_taxonomy = _cwe_taxonomy(rules)
+    if cwe_taxonomy is not None:
+        driver["supportedTaxonomies"] = [{"name": CWE_TAXONOMY}]
+    run: dict[str, Any] = {
+        "tool": {"driver": driver},
+        # Artifact URIs are relative to the scanned repo root; the absolute
+        # local path is deliberately not embedded.
+        "originalUriBaseIds": {SRCROOT: {"description": {"text": "Root of the scanned repository."}}},
+        "results": results,
+    }
+    if cwe_taxonomy is not None:
+        run["taxonomies"] = [cwe_taxonomy]
+    if attack_paths:
+        # Attach codeflows at the run level via a properties bag. SARIF
+        # allows tool-defined properties here; consumers who care about
+        # attack paths can traverse `run.properties.attackPaths`.
+        run["properties"] = {
+            "attackPaths": _build_code_flows_from_attack_paths(attack_paths),
+        }
+    return {
+        "$schema": SARIF_SCHEMA_URI,
+        "version": SARIF_VERSION,
+        "runs": [run],
+    }
+
+
+__all__ = ["build_sarif", "SARIF_VERSION"]