attackmap 0.6.4__py3-none-any.whl

attackmap/sdk/__init__.py

@@ -0,0 +1,278 @@
+"""Public, stable contract surface for AttackMap analyzers.
+
+Anything you can import from ``attackmap.sdk`` is part of the stable analyzer
+contract. Anything you cannot is an internal implementation detail of the
+``attackmap`` package and may change without a major-version bump.
+
+## What an analyzer is
+
+An analyzer is a Python object that satisfies :class:`AnalyzerProtocol`:
+
+- exposes ``metadata: AnalyzerMetadata``
+- exposes a ``name`` property
+- implements ``detect(root) -> bool`` — does this repo look like something
+  the analyzer should run on?
+- implements ``analyze(root) -> AnalyzerResult`` — extract structured
+  signals (routes, external calls, hints, …) from the repo
+
+External analyzers register themselves via the ``attackmap.analyzers``
+Python entry-point group. See the README of any official analyzer (e.g.
+``attackmap-analyzer-python``) for a working example.
+
+## Responsibilities
+
+Analyzers emit **structured signals** — small, evidence-bearing data points
+with a file/line citation. They do *not* generate findings, attack paths,
+or reports. Specifically:
+
+| Owned by analyzers | Owned by core |
+|---|---|
+| Detecting whether they should run | Discovering and loading analyzers |
+| Extracting routes, external calls, databases | Merging results across analyzers |
+| Emitting auth/secret/service/edge/protocol/framework/entrypoint hints | Building the system graph |
+| Surface-level normalization (path canonicalization, etc.) | Generating findings + severity |
+| | Generating attack paths and threat-model output |
+| | Rendering CLI / JSON / markdown reports |
+
+If you find yourself wanting to add finding generation or report rendering
+to an analyzer, the answer is almost always "emit a richer signal and let
+core do the reasoning."
+
+## Merge semantics
+
+When multiple analyzers run against the same repo, their results are
+merged by `attackmap.analyzers.merge_analyzer_results`. The schema is
+declared in `attackmap.merge.MERGE_SCHEMA`; the rules are:
+
+- **Order**: first-seen wins. Analyzers (built-in and plugin alike) run
+  in ``(metadata.priority, name)`` order, so the lower priority value wins
+  a duplicate signal.
+- **Opt-in**: an analyzer with ``enabled_by_default=False`` runs only when
+  selected with ``--module``; ``detect()`` still gates it.
+- **Dedup**: each list field has a stable tuple key, e.g. routes are
+  deduped by ``(path, method, file)`` and auth hints by ``(hint, file)``.
+- **Route auth** (#256): a plugin that knows a route's guard sets
+  ``Route.auth`` to ``"required"`` or ``"anonymous"`` (plus ``guards`` and
+  ``guard_evidence``). Core trusts it over its own regex resolution and the
+  ±40-line auth-hint window; ``"unknown"`` (the default) keeps the old
+  behavior. On duplicate route keys a known state fills in an unknown one.
+- **Languages**: union, sorted for stable display.
+- **Files scanned**: summed.
+
+Two analyzers that both emit a route for the same ``(path, method, file)``
+produce one route in the merged result — whichever was emitted first.
+
+## App attack surface (#188, #190)
+
+A platform plugin (the Apple analyzers: Swift and Objective-C) reports
+app-side issues as :class:`AppSurfaceIssue` items in
+``ScanResult.app_surface_issues``: App Transport Security exceptions, custom
+URL-scheme handlers, weakening entitlements, WKWebView script built from
+strings, secrets in UserDefaults or on the pasteboard, unvalidated XPC peers,
+and classes, selectors or libraries resolved from runtime strings. The
+``kind`` should be one of :data:`APP_SURFACE_ISSUE_KINDS` (it is typed ``str``:
+a record with a kind this core doesn't know is dropped and noted under
+``analyzer_errors``, the rest of the result is kept); ``severity`` and
+``confidence`` are per instance. Records are merged by ``(kind, file, line,
+evidence_text)``; on a duplicate the more severe, then more confident, wins. Core turns each kind into one aggregated finding (rule id = the
+kind, dashed, e.g. ``apple-ats-insecure-loads``) with CWE/OWASP taxonomy.
+Entry points such as URL schemes, universal links and XPC services also go in
+``entrypoint_hints`` so they show up in the surface inventory.
+
+## Contributing taint sinks (#240)
+
+An analyzer can teach core's taint pass new sink signatures (a framework's
+file-serving helper, an ORM's raw-query escape hatch) without touching core.
+Register an entry point in the ``attackmap.taint_sinks`` group
+(:data:`TAINT_SINK_PLUGIN_GROUP`) that resolves to a list of sink entries, a
+callable returning one, or a path to a YAML file with a ``sinks:`` list::
+
+    [project.entry-points."attackmap.taint_sinks"]
+    myframework = "attackmap_analyzer_myframework.sinks:SINKS"
+
+    SINKS = [
+        {
+            "id": "myframework-raw-sql",          # unique; prefix with your plugin
+            "kind": "sql_execute",                # one of TAINT_SINK_KINDS
+            "langs": ["python"],
+            "regex": r"\\bRaw\\.sql\\s*\\(",
+            "gate": "tainted",                    # or "any"
+            "args": [0],                          # or "all" / "receiver" / "rest"
+            "cwe": 89,                            # required
+        },
+    ]
+
+Entries use the same schema as core's ``taint_sinks.yaml`` and must carry a
+``cwe``. Check them in your tests with :func:`validate_taint_sink`; at scan
+time an invalid entry is skipped with a warning instead of failing the scan.
+Plugins reuse core's sink kinds (findings, CWE taxonomy and exploitability are
+keyed on them) and core still decides reachability, flow and severity.
+
+## Cloud / IaC misconfigurations
+
+IaC plugins (Terraform, Kubernetes / Helm, compose, Dockerfile) report
+misconfigurations as :class:`CloudMisconfig` records in
+``ScanResult.cloud_misconfigs``, not as auth or entrypoint hints, which core
+treats as recon (an ``AuthHint`` next to a route even counts as an auth
+signal). ``kind`` is one of :data:`CLOUD_MISCONFIG_KINDS`; each kind is a core
+rule id (``privileged_container`` → ``privileged-container``) with CWE/OWASP
+ids. Core emits one finding per (kind, severity): instances keep their own
+severity in SARIF and in the ``--fail-on-new-high`` gate, and a kind's usual
+severity keeps the plain title (other tiers add "(low-severity instances)")::
+
+    CloudMisconfig(
+        kind="host_path_mount", file="k8s/agent.yaml", line=31,
+        resource="DaemonSet/agent container agent", platform="kubernetes",
+        severity="high", confidence=0.9,
+        escalation_path="hostPath / → node root → kubelet credentials",
+        evidence_text="path: /",
+    )
+
+Set ``severity`` per instance (a ``docker.sock`` mount is worse than
+``/var/log``), lower ``confidence`` for settings you inferred from a default
+rather than read, and put ``for_each``/``count`` or module provenance in
+``context``. Report literal values only: a templated value
+(``{{ .Values.x }}``, ``var.x``) is not a misconfiguration you can see.
+
+``platform`` is one of :data:`CLOUD_MISCONFIG_PLATFORMS`. The free-text fields
+are redacted, folded to one line and capped (evidence, context and escalation
+path 300 characters, resource 200). Records merge on (kind, file, line,
+resource, evidence); for a true duplicate the more severe report wins.
+
+``kind`` is typed ``str``: core drops records with a kind it doesn't know (a
+plugin built against a newer core), keeps the rest of the result and notes the
+drop under ``analyzer_errors`` (``--strict-analyzers`` fails instead). A new kind needs a
+core release (finding spec + taxonomy entry). A plugin that must also run on
+cores older than this record should feature-detect it (``try: from
+attackmap.sdk import CloudMisconfig`` / ``hasattr(ScanResult,
+"cloud_misconfigs")``) and keep emitting its old hints there, because an older
+core ignores the records.
+## Weakness and supply-chain records (#189, #191)
+
+Some bug classes are decided inside one function and don't fit the
+route-seeded taint pass, e.g. C/C++ memory-safety sinks (``strcpy`` from a
+traced input, a non-literal ``printf`` format, ``system`` on a built
+command). An analyzer may emit those as :class:`CodeWeakness` records in
+``result.code_weaknesses``. ``kind`` must be one of
+:data:`CODE_WEAKNESS_KINDS`; core owns the finding title, mitigation and
+taxonomy for each kind. For the native kinds (``unbounded_copy``,
+``format_string``, ``native_command_exec``, ``tainted_copy_length``,
+``alloc_size_overflow``) set ``severity`` and ``confidence`` per instance
+from whether an input reaches the sink in the same function, and name that
+input in ``source_kind`` / ``source_line``. Core groups the instances into
+one finding per (kind, severity tier), like :class:`CloudMisconfig`. ``kind``
+(and ``DependencyHint.ecosystem``) is typed ``str``: core drops a record with
+a value it doesn't know and notes it under ``analyzer_errors``.
+
+Manifest-level supply-chain risks an analyzer understands better than core
+(a CMake ``FetchContent`` ``GIT_TAG`` on a branch) go in
+``result.supply_chain_issues`` as :class:`SupplyChainIssue` records, using
+the kinds core already reports (``mutable_vcs_dependency``, ...).
+
+## Versioning
+
+The names exported below are stable across minor releases of the
+``attackmap`` package. Breaking changes to this surface only happen on
+a major-version bump; deprecations get one release of overlap.
+"""
+
+from __future__ import annotations
+
+from .contracts import (
+    AnalyzerMetadata,
+    AnalyzerProtocol,
+    AnalyzerRepositoryModule,
+    AnalyzerResult,
+    normalize_analyzer_metadata,
+)
+from ..safe_fs import contained_file, is_contained, read_repo_text, walk_repo
+from . import fs
+from .fs import DEFAULT_SKIP_DIRS, iter_repo_files, line_of, line_snippet, read_source, rel
+from ..taint_sinks import PLUGIN_GROUP as TAINT_SINK_PLUGIN_GROUP
+from ..taint_sinks import SINK_KINDS as TAINT_SINK_KINDS
+from ..taint_sinks import validate_sink_entry as validate_taint_sink
+from .models import (
+    CLOUD_MISCONFIG_KINDS,
+    CLOUD_MISCONFIG_PLATFORMS,
+    APP_SURFACE_ISSUE_KINDS,
+    CODE_WEAKNESS_KINDS,
+    DEPENDENCY_ECOSYSTEMS,
+    AppSurfaceIssue,
+    AppSurfaceIssueKind,
+    AuthHint,
+    CloudMisconfig,
+    CloudMisconfigKind,
+    CloudMisconfigPlatform,
+    CodeWeakness,
+    DatabaseHint,
+    DependencyEcosystem,
+    DependencyHint,
+    EdgeHint,
+    EntrypointHint,
+    ExternalCall,
+    FrameworkHint,
+    ProtocolHint,
+    Route,
+    ScanResult,
+    SecretHint,
+    ServiceHint,
+    SupplyChainIssue,
+)
+
+__all__ = [
+    "AnalyzerResult",
+    "AnalyzerMetadata",
+    "AnalyzerRepositoryModule",
+    "AnalyzerProtocol",
+    "normalize_analyzer_metadata",
+    "Route",
+    "ExternalCall",
+    "DatabaseHint",
+    "AuthHint",
+    "ServiceHint",
+    "EdgeHint",
+    "EntrypointHint",
+    "ProtocolHint",
+    "FrameworkHint",
+    "SecretHint",
+    "ScanResult",
+    "DependencyHint",
+    # Package ecosystems a DependencyHint may carry (#255).
+    "DependencyEcosystem",
+    "DEPENDENCY_ECOSYSTEMS",
+    # Cloud / IaC / container misconfigurations (terraform#4, iac#1); core
+    # turns each kind into a finding.
+    "CloudMisconfig",
+    "CloudMisconfigKind",
+    "CLOUD_MISCONFIG_KINDS",
+    "CloudMisconfigPlatform",
+    "CLOUD_MISCONFIG_PLATFORMS",
+    # App attack-surface issues a platform plugin may emit (#188, #190).
+    "AppSurfaceIssue",
+    "AppSurfaceIssueKind",
+    "APP_SURFACE_ISSUE_KINDS",
+    # Function-local weakness and supply-chain records (#189, #191).
+    "CodeWeakness",
+    "CODE_WEAKNESS_KINDS",
+    "SupplyChainIssue",
+    # Repo-confined filesystem helpers (#234): walk and read the scanned repo
+    # without following symlinks out of it. Plugins should use these instead
+    # of Path.rglob / read_text.
+    "walk_repo",
+    "is_contained",
+    "contained_file",
+    "read_repo_text",
+    # Shared plugin walker/reader (#253): prunes by repo-relative dir name,
+    # skips AttackMap output, caps size, never raises on unreadable files.
+    "fs",
+    "DEFAULT_SKIP_DIRS",
+    "iter_repo_files",
+    "read_source",
+    "rel",
+    "line_of",
+    "line_snippet",
+    # Plugin-contributed taint sinks (#240).
+    "TAINT_SINK_PLUGIN_GROUP",
+    "TAINT_SINK_KINDS",
+    "validate_taint_sink",
+]

attackmap/sdk/contracts.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from ..analyzer_contracts import (
+    AnalyzerMetadata,
+    AnalyzerProtocol,
+    AnalyzerRepositoryModule,
+    AnalyzerResult,
+    normalize_analyzer_metadata,
+)
+
+__all__ = [
+    "AnalyzerResult",
+    "AnalyzerMetadata",
+    "AnalyzerRepositoryModule",
+    "AnalyzerProtocol",
+    "normalize_analyzer_metadata",
+]

attackmap/sdk/fs.py

@@ -0,0 +1,156 @@
+"""Shared repo walking and reading for analyzer plugins (#253).
+
+Every plugin used to copy the same ``root.rglob(...)`` plus
+``any(part in SKIP_DIRS for part in path.parts)`` walk. That pattern:
+
+- matched skip dirs against *absolute* path parts, so a repo checked out under
+  ``/build/...`` or ``~/src/out/...`` silently yielded no files at all;
+- didn't prune, so it still descended all of ``node_modules`` and ``target``;
+- followed symlinks out of the repo;
+- let one unreadable file raise out of ``analyze()``;
+- dropped latin-1/cp1252 sources without saying so.
+
+Use :func:`iter_repo_files` and :func:`read_source` instead. They prune by
+*repo-relative* directory name, never follow symlinks out of the repo, skip
+AttackMap's own output directories, cap file size, and never raise on an
+unreadable file.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection, Iterator
+from pathlib import Path
+
+from ..safe_fs import is_contained, max_file_bytes, walk_repo
+from ..srcpaths import SKIP_DIRS, is_test_file, line_number
+
+# Directories no analyzer should descend into. Plugins extend it for their
+# ecosystem, e.g. ``DEFAULT_SKIP_DIRS | {"bin", "obj"}`` for .NET.
+DEFAULT_SKIP_DIRS: frozenset[str] = frozenset(SKIP_DIRS | {"vendor", "bower_components", ".mypy_cache", ".pytest_cache"})
+
+_BINARY_SNIFF_BYTES = 8192
+
+
+def iter_repo_files(
+    root: str | Path,
+    *,
+    suffixes: Collection[str] | None = None,
+    names: Collection[str] | None = None,
+    skip_dirs: Collection[str] = DEFAULT_SKIP_DIRS,
+    max_bytes: int | None = None,
+    include_tests: bool = True,
+    on_skip: Callable[[Path, str], None] | None = None,
+) -> Iterator[Path]:
+    """Yield the repo's regular files, sorted and depth-first.
+
+    - ``suffixes`` (e.g. ``{".go"}``, case-insensitive) and ``names`` (exact
+      file names, e.g. ``{"go.mod"}``) filter the files; a file matching
+      either is yielded. With neither, every file is.
+    - ``skip_dirs`` are matched against directory *names inside the repo* and
+      pruned, so the walk never enters them, and directories above ``root``
+      never count.
+    - Files larger than ``max_bytes`` (default: the core per-file cap,
+      ``ATTACKMAP_MAX_FILE_BYTES``) are skipped.
+    - ``include_tests=False`` drops test/spec/fixture files (see
+      ``ATTACKMAP_INCLUDE_TESTS``).
+    - ``on_skip(path, reason)`` is called for each skipped symlink,
+      oversized file or directory excluded by an AttackMap output marker, so
+      a plugin can report what it didn't analyze.
+    """
+    root_path = Path(root)
+    wanted_suffixes = {s.lower() for s in suffixes} if suffixes is not None else None
+    wanted_names = set(names) if names is not None else None
+    skip = frozenset(skip_dirs)
+    cap = max_bytes if max_bytes is not None else max_file_bytes()
+
+    def _symlink(path: Path) -> None:
+        if on_skip is not None:
+            on_skip(path, "symlink not followed")
+
+    def _pruned(path: Path) -> None:
+        if on_skip is not None:
+            on_skip(path, "directory skipped (output marker)")
+
+    for path in walk_repo(root_path, prune=skip.__contains__, on_symlink=_symlink, on_prune=_pruned):
+        if wanted_suffixes is not None or wanted_names is not None:
+            if not (
+                (wanted_suffixes is not None and path.suffix.lower() in wanted_suffixes)
+                or (wanted_names is not None and path.name in wanted_names)
+            ):
+                continue
+        if not include_tests and is_test_file(rel(path, root_path)):
+            continue
+        try:
+            oversized = path.stat().st_size > cap
+        except OSError:
+            continue
+        if oversized:
+            if on_skip is not None:
+                on_skip(path, "oversized file skipped")
+            continue
+        yield path
+
+
+def read_source(path: str | Path, *, root: str | Path | None = None) -> str | None:
+    """Read a source file as text, or return None if it can't be read.
+
+    Decodes UTF-8 (with or without a BOM), then falls back to cp1252 and finally
+    latin-1, so legacy-encoded sources are analyzed rather than dropped.
+    Returns None for unreadable files (``OSError``), binary files (a NUL byte
+    in the first 8 KiB) and, when ``root`` is given, paths outside it.
+    """
+    file_path = Path(path)
+    if root is not None:
+        if not file_path.is_absolute():
+            file_path = Path(root) / file_path
+        if not is_contained(root, file_path):
+            return None
+    try:
+        data = file_path.read_bytes()
+    except OSError:
+        return None
+    if b"\x00" in data[:_BINARY_SNIFF_BYTES]:
+        return None
+    for encoding in ("utf-8-sig", "cp1252"):
+        try:
+            return data.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return data.decode("latin-1")
+
+
+def rel(path: str | Path, root: str | Path) -> str:
+    """``path`` relative to ``root``, POSIX-style (``src/app.py``)."""
+    try:
+        return Path(path).relative_to(Path(root)).as_posix()
+    except ValueError:
+        return Path(path).as_posix()
+
+
+def line_of(content: str, offset: int) -> int:
+    """1-indexed line of a character offset (e.g. ``match.start()``)."""
+    return line_number(content, offset)
+
+
+def line_snippet(content: str, line: int, max_len: int = 200) -> str:
+    """The stripped text of 1-indexed ``line``, truncated to ``max_len``.
+
+    Lines are split on ``\n`` only, matching :func:`line_of`; ``str.splitlines``
+    would also break on form feeds and other separators common in legacy C and
+    put the snippet on the wrong line.
+    """
+    lines = content.split("\n")
+    if line < 1 or line > len(lines):
+        return ""
+    text = lines[line - 1].strip()
+    return text if len(text) <= max_len else text[: max_len - 1] + "…"
+
+
+__all__ = [
+    "DEFAULT_SKIP_DIRS",
+    "iter_repo_files",
+    "read_source",
+    "rel",
+    "line_of",
+    "line_snippet",
+]

attackmap/sdk/models.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from ..models import (
+    CLOUD_MISCONFIG_KINDS,
+    CLOUD_MISCONFIG_PLATFORMS,
+    CloudMisconfig,
+    CloudMisconfigKind,
+    CloudMisconfigPlatform,
+    APP_SURFACE_ISSUE_KINDS,
+    DEPENDENCY_ECOSYSTEMS,
+    AppSurfaceIssue,
+    AppSurfaceIssueKind,
+    DependencyEcosystem,
+    DependencyHint,
+    CODE_WEAKNESS_KINDS,
+    CodeWeakness,
+    SupplyChainIssue,
+)
+from ..recon_models import (
+    AuthHint,
+    DatabaseHint,
+    EdgeHint,
+    EntrypointHint,
+    ExternalCall,
+    FrameworkHint,
+    ProtocolHint,
+    Route,
+    ScanResult,
+    SecretHint,
+    ServiceHint,
+)
+
+__all__ = [
+    "Route",
+    "ExternalCall",
+    "DatabaseHint",
+    "AuthHint",
+    "ServiceHint",
+    "EdgeHint",
+    "EntrypointHint",
+    "ProtocolHint",
+    "FrameworkHint",
+    "SecretHint",
+    "ScanResult",
+    "DependencyHint",
+    "DependencyEcosystem",
+    "DEPENDENCY_ECOSYSTEMS",
+    "CloudMisconfig",
+    "CloudMisconfigKind",
+    "CLOUD_MISCONFIG_KINDS",
+    "CloudMisconfigPlatform",
+    "CLOUD_MISCONFIG_PLATFORMS",
+    "AppSurfaceIssue",
+    "AppSurfaceIssueKind",
+    "APP_SURFACE_ISSUE_KINDS",
+    "CodeWeakness",
+    "CODE_WEAKNESS_KINDS",
+    "SupplyChainIssue",
+]

attackmap/secrets_history.py

@@ -0,0 +1,161 @@
+"""Opt-in git-history secret scan (#252, ``--secrets-history N``).
+
+Most leaked credentials live in history, not the working tree: a key is
+committed, noticed, and "removed" in a later commit while every clone keeps
+it. This pass runs the same detectors as the working-tree scan over the
+lines *added* by the last ``N`` commits (all refs), and reports for each
+secret the commit that introduced it and whether it is still in ``HEAD``.
+
+Safety:
+- Off by default; only ``--secrets-history`` runs it.
+- Bounded: at most ``MAX_COMMITS`` commits, ``MAX_OUTPUT_BYTES`` of patch
+  text, ``MAX_LINE_CHARS`` per line and a wall-clock timeout. Hitting a bound
+  is recorded as a scan limitation, never silently.
+- Git is invoked through ``gitref.hardened_git_command``: no hooks, pager,
+  fsmonitor, external diff, textconv or lazy fetch, and system/global config
+  ignored, so a hostile repo can't execute code through its git config.
+- Raw secret values exist only in memory while matching (to fingerprint and
+  test ``still_in_head``); every emitted record is masked (#235).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+import time
+from pathlib import Path
+
+from .gitref import hardened_git_command, hardened_git_env
+from .models import SecretHistoryHit
+from .redact import mask_secret
+from .scanner import _line_snippet, iter_secret_matches
+from .srcpaths import in_skipped_dir, is_test_file, is_vendored_file
+
+DEFAULT_COMMITS = 100
+MAX_COMMITS = 5000
+MAX_OUTPUT_BYTES = 64 * 1024 * 1024
+MAX_LINE_CHARS = 4096
+TIMEOUT_SECONDS = 120.0
+_COMMIT_MARKER = "\x1ecommit "
+
+
+def _run(root: Path, *args: str) -> subprocess.CompletedProcess[bytes]:
+    return subprocess.run(
+        hardened_git_command(root, *args),
+        capture_output=True,
+        check=False,
+        stdin=subprocess.DEVNULL,
+        env=hardened_git_env(),
+        timeout=30,
+    )
+
+
+def _head_text(root: Path, prefix: str, rel: str, cache: dict[str, str | None]) -> str | None:
+    if rel not in cache:
+        result = _run(root, "cat-file", "blob", f"HEAD:{prefix}{rel}")
+        cache[rel] = result.stdout.decode("utf-8", errors="replace") if result.returncode == 0 else None
+    return cache[rel]
+
+
+def scan_secret_history(
+    root: str | Path,
+    commits: int = DEFAULT_COMMITS,
+    *,
+    max_output_bytes: int = MAX_OUTPUT_BYTES,
+    timeout: float = TIMEOUT_SECONDS,
+) -> tuple[list[SecretHistoryHit], list[str]]:
+    """Scan the patches of the last ``commits`` commits under ``root``.
+
+    Returns ``(hits, limitations)``. A directory that isn't a git checkout
+    yields no hits and one limitation line.
+    """
+    root_path = Path(root).resolve()
+    commits = max(1, min(int(commits), MAX_COMMITS))
+    probe = _run(root_path, "rev-parse", "--show-prefix")
+    if probe.returncode != 0:
+        return [], [f"--secrets-history skipped: {root_path} is not a git repository"]
+    prefix = probe.stdout.decode("utf-8", errors="replace").strip()
+
+    proc = subprocess.Popen(
+        hardened_git_command(
+            root_path, "log", "--all", "-n", str(commits), "-p", "-U0",
+            "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames",
+            "--diff-filter=AM", f"--format=format:{_COMMIT_MARKER}%H",
+            "--", ".",
+        ),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        env=hardened_git_env(),
+    )
+    limitations: list[str] = []
+    # fingerprint -> [kind, file, line_text_masked, introduced_in, literal]
+    found: dict[tuple[str, str, str], list] = {}
+    commit = ""
+    current: str | None = None
+    read = 0
+    seen_commits: set[str] = set()
+    started = time.monotonic()
+    assert proc.stdout is not None
+    try:
+        for raw in proc.stdout:
+            read += len(raw)
+            if read > max_output_bytes:
+                limitations.append(f"--secrets-history stopped after {max_output_bytes} bytes of patch output")
+                break
+            if time.monotonic() - started > timeout:
+                limitations.append(f"--secrets-history stopped after {timeout:.0f}s")
+                break
+            line = raw.decode("utf-8", errors="replace").rstrip("\n")
+            if line.startswith(_COMMIT_MARKER):
+                commit = line[len(_COMMIT_MARKER):].strip()
+                seen_commits.add(commit)
+                current = None
+                continue
+            if line.startswith("+++ "):
+                target = line[4:]
+                current = target[2:] if target.startswith("b/") else None
+                if current is not None and prefix and current.startswith(prefix):
+                    current = current[len(prefix):]
+                if current is not None and in_skipped_dir(Path(current)):
+                    current = None
+                continue
+            if current is None or not line.startswith("+") or len(line) > MAX_LINE_CHARS:
+                continue
+            added = line[1:]
+            first_party = not is_test_file(current) and not is_vendored_file(current)
+            for kind, literal, offset, _confidence in iter_secret_matches(
+                added, entropy=False, generic=first_party, urls=first_party
+            ):
+                fingerprint = (kind, current, hashlib.sha256(literal.encode("utf-8")).hexdigest())
+                snippet = _line_snippet(added, offset).replace(literal, mask_secret(literal))
+                # `git log` is newest first, so the last sighting is the oldest:
+                # keep overwriting `introduced_in`.
+                found[fingerprint] = [kind, current, snippet, commit, literal]
+    finally:
+        proc.stdout.close()
+        if proc.poll() is None:
+            proc.kill()
+        proc.wait()
+
+    head_cache: dict[str, str | None] = {}
+    hits: list[SecretHistoryHit] = []
+    for kind, rel, snippet, introduced, literal in found.values():
+        head = _head_text(root_path, prefix, rel, head_cache)
+        hits.append(
+            SecretHistoryHit(
+                name=mask_secret(literal) if kind != "pem_private_key" else literal,
+                kind=kind,
+                file=rel,
+                introduced_in=introduced,
+                still_in_head=bool(head) and literal in head,
+                evidence_text=snippet,
+            )
+        )
+    found.clear()
+    hits.sort(key=lambda h: (h.still_in_head, h.file, h.kind, h.introduced_in))
+    if len(seen_commits) >= commits:
+        limitations.append(
+            f"--secrets-history scanned the last {commits} commit(s); older history was not checked"
+        )
+    return hits, limitations