codetrail-cli 1.4.1__py3-none-any.whl

codetrail/repo/history.py

@@ -0,0 +1,262 @@
+"""A target's history, filtered: logs and diffs never show excluded paths or secrets (design section 3.3).
+
+Commit messages and diffs are scanned with gitleaks as text. A flagged message is withheld, and so is a file's patch
+when it holds a finding, which catches a secret that a commit removed although the file is clean now.
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from codetrail.repo.git import run_git
+from codetrail.repo.secrets import SecretScanner
+
+WITHHELD_MESSAGE = "[withheld: gitleaks flagged this message]"
+
+
+@dataclass(frozen=True)
+class Commit:
+    sha: str
+    author: str
+    date: str
+    subject: str
+    body: str
+    files: list[str]
+    is_merge: bool
+
+
+@dataclass(frozen=True)
+class FileDiff:
+    path: str
+    status: str
+    patch: str | None  # None when gitleaks flagged it
+
+
+def commits_between(
+    mirror: Path, start: str | None, end: str, visible: Callable[[str], bool], scanner: SecretScanner
+) -> list[Commit]:
+    """The commits after `start` up to `end`, oldest first; merges list the files they bring to the first parent.
+
+    Each commit is read on its own, with NUL between fields (git messages can't hold NUL), so no text in a message
+    can forge or break a record.
+    """
+    revision_range = end if start is None else f"{start}..{end}"
+    revisions = run_git(["rev-list", "--reverse", "--end-of-options", revision_range], git_dir=mirror)
+    commits = [_read_commit(mirror, sha, visible) for sha in revisions.decode().split()]
+    return _withhold_flagged_messages(commits, scanner)
+
+
+def _read_commit(mirror: Path, sha: str, visible: Callable[[str], bool]) -> Commit:
+    header = run_git(["show", "-s", "--format=%H%x00%an%x00%aI%x00%P%x00%s%x00%b", sha], git_dir=mirror)
+    commit_sha, author, date, parents, subject, body = header.decode("utf-8", "replace").split("\0", 5)
+    parent_list = parents.split()
+    changed = ["diff-tree", "--no-commit-id", "-r", "-z", "--name-only"]
+    changed += [parent_list[0], sha] if parent_list else ["--root", sha]
+    names = run_git(changed, git_dir=mirror).decode("utf-8", "surrogateescape").split("\0")
+    files = [name for name in names if name and visible(name)]
+    return Commit(commit_sha, author, date, subject, body.strip(), files, len(parent_list) > 1)
+
+
+LOG_FIELDS = 5  # sha, author, date, subject, body
+
+
+def latest_commits(mirror: Path, end: str, limit: int, scanner: SecretScanner) -> list[Commit]:
+    """The latest `limit` non-merge commits up to `end`, newest first, with flagged messages withheld.
+
+    One git call: fields and records are separated by NUL, which no message can hold. Files aren't listed.
+    """
+    output = run_git(
+        ["log", f"-n{limit}", "--no-merges", "-z", "--format=%H%x00%an%x00%aI%x00%s%x00%b", "--end-of-options", end],
+        git_dir=mirror,
+    ).decode("utf-8", "replace")
+    fields = output.split("\0")
+    records = (fields[start : start + LOG_FIELDS] for start in range(0, len(fields) - LOG_FIELDS + 1, LOG_FIELDS))
+    commits = [
+        Commit(sha, author, date, subject, body.strip(), [], False) for sha, author, date, subject, body in records
+    ]
+    return _withhold_flagged_messages(commits, scanner)
+
+
+WITHHELD_TAG = "[withheld: gitleaks flagged this tag]"
+TAG_FIELDS = 9  # name, type, object, peeled type, peeled object, date, the commit's date, subject, body
+
+
+@dataclass(frozen=True)
+class Tag:
+    name: str
+    commit: str
+    date: int  # seconds since the epoch: the tagger's date, or the commit's for a lightweight tag
+    message: str  # an annotated tag's subject and body; empty for a lightweight or withheld tag
+
+
+def read_tags(mirror: Path, end: str, scanner: SecretScanner) -> list[Tag]:
+    """The tags on commits in `end`'s history, with flagged names and messages withheld (design section 19.2).
+
+    One git call, fields separated by NUL, which no name or message can hold. Tags on anything but a commit are
+    skipped, so a tag on a blob of an excluded file is never read; the tagger is never read either. A tag with no
+    tagger date takes its commit's. The subject and
+    body are read apart because a signed tag's whole contents would end with its signature.
+    """
+    output = run_git(["for-each-ref", f"--merged={end}", "--format=%(refname:strip=2)%00%(objecttype)%00%(objectname)"
+                      "%00%(*objecttype)%00%(*objectname)%00%(creatordate:unix)%00%(*committerdate:unix)%00"
+                      "%(contents:subject)%00%(contents:body)%00", "refs/tags"],
+                     git_dir=mirror).decode("utf-8", "replace")  # fmt: skip
+    fields = output.split("\0")
+    tags = []
+    for start in range(0, len(fields) - TAG_FIELDS + 1, TAG_FIELDS):
+        name, kind, sha, peeled_kind, peeled, date, commit_date, subject, body = fields[start : start + TAG_FIELDS]
+        name = name.lstrip("\n")  # each record ends with a newline after its last NUL; a name can't hold one
+        if kind == "commit":
+            tags.append(Tag(name, sha, int(date), ""))
+        elif kind == "tag" and peeled_kind == "commit":
+            date = date or commit_date  # a tag made before git recorded taggers has no date of its own
+            message = f"{subject}\n\n{body.strip()}" if body.strip() else subject
+            tags.append(Tag(name, peeled, int(date), message.strip()))
+    flagged = _flagged_indexes([f"{tag.name}\n{tag.message}" for tag in tags], scanner)
+    return [Tag(WITHHELD_TAG, tag.commit, tag.date, "") if index in flagged else tag for index, tag in enumerate(tags)]
+
+
+def commit_totals(mirror: Path, end: str) -> tuple[int, int]:
+    """How many commits `end`'s history holds, and how many of them are merges."""
+    total = run_git(["rev-list", "--count", "--end-of-options", end], git_dir=mirror)
+    merges = run_git(["rev-list", "--count", "--merges", "--end-of-options", end], git_dir=mirror)
+    return int(total), int(merges)
+
+
+def commit_times(mirror: Path, end: str, limit: int) -> list[int]:
+    """The author times of the latest `limit` commits, newest first: no message, name or email is read."""
+    output = run_git(["log", f"-n{limit}", "--format=%at", "--end-of-options", end], git_dir=mirror)
+    return [int(line) for line in output.split()]
+
+
+def first_commit_time(mirror: Path, end: str) -> int | None:
+    """The earliest author time among the root commits of `end`'s history: a cheap "started on" for the home card."""
+    output = run_git(["log", "--max-parents=0", "--format=%at", "--end-of-options", end], git_dir=mirror)
+    return min((int(line) for line in output.split()), default=None)
+
+
+COMMIT_MARK = "\x01"
+
+
+def changed_files(mirror: Path, end: str, limit: int) -> list[tuple[int, list[str]]]:
+    """Each of the latest `limit` non-merge commits' author time and changed paths, newest first (sections 19.1, 20.2).
+
+    One git call printing only a mark with the time per commit, and its file names, NUL-separated: no message, name or
+    email. The mark holds a random token drawn for this call, so no file name can pose as a commit, and only ASCII
+    digits follow it. Names aren't filtered here; callers name only allowed files.
+    """
+    token = secrets.token_hex(16)
+    header_pattern = re.compile(re.escape(COMMIT_MARK + token) + r"([0-9]{1,12})")
+    output = run_git(["log", f"-n{limit}", "--no-merges", "-z", "--name-only", f"--format=%x01{token}%at",
+                      "--end-of-options", end], git_dir=mirror).decode("utf-8", "surrogateescape")  # fmt: skip
+    commits: list[tuple[int, list[str]]] = []
+    first_name = False
+    for field in output.split("\0"):
+        header = header_pattern.fullmatch(field.lstrip("\n"))
+        if header:
+            commits.append((int(header[1]), []))
+            first_name = True
+        elif field and commits:
+            name = field[1:] if first_name and field.startswith("\n") else field  # a newline ends the header
+            first_name = False
+            if name:
+                commits[-1][1].append(name)
+    return commits
+
+
+def files_changed_since(mirror: Path, end: str, since: date) -> set[str]:
+    """The paths that differ between the last commit before the date and `end`: names only, which callers filter.
+
+    One tree diff, however many commits came since; with no commit before the date, every path in `end` counts.
+    """
+    base = run_git(["rev-list", "-1", f"--before={since.isoformat()}", "--end-of-options", end], git_dir=mirror)
+    if base.strip():
+        arguments = ["diff-tree", "-r", "--name-only", "--no-renames", "-z", "--end-of-options", base.decode().strip(),
+                     end]  # fmt: skip
+    else:
+        arguments = ["ls-tree", "-r", "--name-only", "-z", "--end-of-options", end]
+    output = run_git(arguments, git_dir=mirror)
+    return {name for name in output.decode("utf-8", "surrogateescape").split("\0") if name}
+
+
+def merges_between(mirror: Path, start: str, end: str) -> int:
+    count = run_git(["rev-list", "--count", "--merges", "--first-parent", "--end-of-options", f"{start}..{end}"],
+                    git_dir=mirror)  # fmt: skip
+    return int(count)
+
+
+def diff_between(
+    mirror: Path, start: str, end: str, visible: Callable[[str], bool], scanner: SecretScanner
+) -> list[FileDiff]:
+    arguments = ["diff-tree", "-r", "--name-status", "--no-renames", "-z", "--end-of-options", start, end]
+    output = run_git(arguments, git_dir=mirror)
+    fields = output.decode("utf-8", "surrogateescape").split("\0")
+    changes = [(fields[i], fields[i + 1]) for i in range(0, len(fields) - 1, 2) if visible(fields[i + 1])]
+    patches = [
+        run_git(
+            ["diff-tree", "-r", "-p", "--no-renames", "--end-of-options", start, end, "--", f":(literal){path}"],
+            git_dir=mirror,
+        ).decode("utf-8", "replace")
+        for _status, path in changes
+    ]
+    flagged = _flagged_indexes(patches, scanner)
+    return [
+        FileDiff(path, status, None if index in flagged else patch)
+        for index, ((status, path), patch) in enumerate(zip(changes, patches, strict=True))
+    ]
+
+
+def _withhold_flagged_messages(commits: list[Commit], scanner: SecretScanner) -> list[Commit]:
+    flagged = _flagged_indexes([f"{commit.subject}\n{commit.body}" for commit in commits], scanner)
+    return [
+        Commit(c.sha, c.author, c.date, WITHHELD_MESSAGE, "", c.files, c.is_merge) if index in flagged else c
+        for index, c in enumerate(commits)
+    ]
+
+
+def _flagged_indexes(texts: Sequence[str], scanner: SecretScanner) -> set[int]:
+    """Scans all texts in one gitleaks run and returns the indexes of those holding a finding."""
+    if not texts:
+        return set()
+    first_lines, line = [], 1
+    for text in texts:
+        first_lines.append(line)
+        line += text.count("\n") + 1
+    combined = "\n".join(texts)
+    flagged = set()
+    for finding in scanner.scan_text(combined):
+        index = max(i for i, first in enumerate(first_lines) if first <= finding.line)
+        flagged.add(index)
+    return flagged
+
+
+def commit_count(mirror: Path, start: str, end: str) -> int:
+    return int(run_git(["rev-list", "--count", "--end-of-options", f"{start}..{end}"], git_dir=mirror))
+
+
+def changed_paths(mirror: Path, start: str, end: str) -> list[str]:
+    """Paths changed between two commits; only names, which callers filter before showing."""
+    arguments = ["diff-tree", "-r", "--name-only", "--no-renames", "-z", "--end-of-options", start, end]
+    output = run_git(arguments, git_dir=mirror)
+    return [name for name in output.decode("utf-8", "surrogateescape").split("\0") if name]
+
+
+def recent_commits(
+    mirror: Path,
+    end: str,
+    paths: Sequence[str],
+    limit: int,
+    visible: Callable[[str], bool],
+    scanner: SecretScanner,
+) -> list[Commit]:
+    """The latest commits (at most `limit`, oldest first) that touched any of `paths`, filtered like commits_between."""
+    pathspecs = [f":(literal){path}" for path in paths if path] or ["."]
+    shas = run_git(["log", f"-n{limit}", "--format=%H", "--end-of-options", end, "--", *pathspecs],
+                   git_dir=mirror).decode().split()  # fmt: skip
+    commits = [_read_commit(mirror, sha, visible) for sha in reversed(shas)]
+    return _withhold_flagged_messages(commits, scanner)

codetrail/repo/mirror.py

@@ -0,0 +1,137 @@
+"""Codetrail's mirror of a target: a bare clone, fetched over the file:// transport (design section 3.2).
+
+The target is only ever read, by git's upload-pack: no command runs inside the target, and `--no-local` stops a clone
+from hardlinking the target's object files.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from codetrail.errors import CodetrailError
+from codetrail.repo.git import run_git
+
+
+@dataclass(frozen=True)
+class TreeEntry:
+    mode: str
+    blob: str
+    path: str
+
+
+def repository_url(path: Path) -> str:
+    return path.expanduser().resolve().as_uri()
+
+
+def check_branch(repository: Path, branch: str) -> None:
+    """Fails unless the repository has the branch; reads it over file:// only."""
+    found = run_git(
+        ["ls-remote", "--heads", "--", repository_url(repository), f"refs/heads/{branch}"],
+        allowed_exit_codes=(0, 2),
+    )
+    if not found.strip():
+        raise CodetrailError(f"{repository} has no branch {branch!r}.")
+
+
+def refresh_mirror(mirror: Path, repository: Path, branch: str) -> str:
+    """Clones or fetches the branch into the mirror, with the tags that point into it, and returns its head commit.
+
+    The branch is fetched without tags; then the mirror's tags that the target no longer has, or that point elsewhere
+    now, are deleted, and a second fetch of the branch brings the rest by git's tag auto-follow, which takes only tags
+    on objects the mirror holds, so no other branch's commits come in (design section 19.2). Its errors are replaced,
+    since they name tags.
+    """
+    check_branch(repository, branch)
+    url = repository_url(repository)
+    if not (mirror / "HEAD").exists():
+        mirror.parent.mkdir(parents=True, exist_ok=True)
+        run_git(
+            [
+                "clone",
+                "--quiet",
+                "--bare",
+                "--no-local",
+                "--no-tags",
+                "--single-branch",
+                "--branch",
+                branch,
+                "--",
+                url,
+                str(mirror),
+            ]
+        )
+    refspec = f"+refs/heads/{branch}:refs/heads/{branch}"
+    run_git(["fetch", "--quiet", "--no-tags", "--prune", "--", url, refspec], git_dir=mirror)
+    _drop_stale_tags(mirror, url)
+    try:
+        # Fetching the branch again, now up to date, brings only the tags git's auto-follow takes.
+        run_git(["fetch", "--quiet", "--", url, refspec], git_dir=mirror)
+    except CodetrailError:
+        # git's message names the tag it couldn't write, which no scan has passed yet; the update's error shows it.
+        raise CodetrailError("git couldn't fetch the branch's tags into the mirror.") from None
+    return head_commit(mirror, branch)
+
+
+def _drop_stale_tags(mirror: Path, url: str) -> None:
+    """Deletes the mirror's tags that the target no longer has or that point elsewhere now; touches only refs/tags/."""
+    listed = run_git(["ls-remote", "--tags", "--", url]).decode("utf-8", "surrogateescape")
+    remote = {}
+    for line in listed.splitlines():
+        sha, _, ref = line.partition("\t")
+        if ref.startswith("refs/tags/") and not ref.endswith("^{}"):
+            remote[ref] = sha
+    local = run_git(["for-each-ref", "--format=%(refname)%00%(objectname)", "refs/tags"], git_dir=mirror)
+    stale = []
+    for line in local.decode("utf-8", "surrogateescape").splitlines():
+        ref, _, sha = line.partition("\0")
+        if ref.startswith("refs/tags/") and remote.get(ref) != sha:
+            stale.append(f"delete {ref}\0{sha}\0")
+    if stale:
+        try:
+            run_git(["update-ref", "-z", "--stdin"], git_dir=mirror,
+                    input="".join(stale).encode("utf-8", "surrogateescape"))  # fmt: skip
+        except CodetrailError:
+            # git's message names the tag, which no scan has passed yet; the update's error would show it.
+            raise CodetrailError(f"git couldn't remove {len(stale)} stale tag(s) from the mirror.") from None
+
+
+def head_commit(mirror: Path, branch: str) -> str:
+    return run_git(["rev-parse", "--verify", f"refs/heads/{branch}^{{commit}}"], git_dir=mirror).decode().strip()
+
+
+def list_tree(mirror: Path, commit: str) -> list[TreeEntry]:
+    output = run_git(["ls-tree", "-r", "-z", "--full-tree", commit], git_dir=mirror)
+    entries = []
+    for record in output.split(b"\0"):
+        if not record:
+            continue
+        header, path = record.split(b"\t", 1)
+        mode, _kind, blob = header.decode().split(" ")
+        entries.append(TreeEntry(mode=mode, blob=blob, path=path.decode("utf-8", "surrogateescape")))
+    return entries
+
+
+def read_file_at(mirror: Path, commit: str, path: str) -> bytes | None:
+    """The file's content at the commit, or None when it doesn't exist there."""
+    try:
+        return run_git(["cat-file", "blob", f"{commit}:{path}"], git_dir=mirror)
+    except CodetrailError:
+        return None
+
+
+def read_blobs(mirror: Path, blobs: list[str]) -> Iterator[tuple[str, bytes]]:
+    """Each blob's content, in order, read with one `git cat-file --batch`."""
+    if not blobs:
+        return
+    output = run_git(["cat-file", "--batch"], git_dir=mirror, input="".join(f"{blob}\n" for blob in blobs).encode())
+    position = 0
+    for blob in blobs:
+        header_end = output.index(b"\n", position)
+        name, kind, size = output[position:header_end].decode().split(" ")
+        if name != blob or kind != "blob":
+            raise CodetrailError(f"git cat-file returned {kind} {name} for blob {blob}")
+        start = header_end + 1
+        yield blob, output[start : start + int(size)]
+        position = start + int(size) + 1

codetrail/repo/refresh.py

@@ -0,0 +1,41 @@
+"""Refreshes a target's sources: mirror, rules, scan and materialization."""
+
+from __future__ import annotations
+
+from codetrail.config import Paths, check_containment, load_global, load_target
+from codetrail.lock import target_in_use, target_lock
+from codetrail.repo.mirror import read_file_at, refresh_mirror
+from codetrail.repo.rules import ExclusionRules
+from codetrail.repo.secrets import SecretScanner
+from codetrail.repo.source import SourceManifest, build_source
+
+TARGET_IGNORE_FILE = ".codetrailignore"
+
+
+def ignore_lines(paths: Paths, name: str, target_file: bytes | None) -> list[str]:
+    """The target's own .codetrailignore (from the commit), then the founder's ignore file."""
+    lines = target_file.decode("utf-8", "replace").splitlines() if target_file else []
+    founder_file = paths.ignore_file(name)
+    if founder_file.exists():
+        lines += founder_file.read_text(encoding="utf-8").splitlines()
+    return lines
+
+
+def refresh_source(paths: Paths, name: str) -> SourceManifest:
+    """Refreshes the target's sources under its lock, after checking no folder would be made inside the target."""
+    with target_in_use(paths, name):
+        check_containment(paths, load_target(paths, name).repository)
+        with target_lock(paths, name):
+            return refresh_while_locked(paths, name)
+
+
+def refresh_while_locked(paths: Paths, name: str) -> SourceManifest:
+    """Refreshes the target's sources; the caller holds the target's lock."""
+    target = load_target(paths, name)
+    check_containment(paths, target.repository)
+    scanner = SecretScanner(load_global(paths).tools)
+    data = paths.target_data(name)
+    mirror = data / "mirror.git"
+    commit = refresh_mirror(mirror, target.repository, target.branch)
+    rules = ExclusionRules(ignore_lines(paths, name, read_file_at(mirror, commit, TARGET_IGNORE_FILE)))
+    return build_source(mirror, commit, rules, scanner, data)

codetrail/repo/rules.py

@@ -0,0 +1,83 @@
+"""The exclusion rules (design section 3.3; ADR 0001).
+
+Built-in secret patterns come first and nothing can override them. Ignore lines, in gitignore syntax, come from the
+target's `.codetrailignore` and the founder's ignore file, in that order.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from collections.abc import Sequence
+from enum import StrEnum
+
+from pathspec import GitIgnoreSpec
+
+# Environment files, Terraform variables, private keys and credential files: never read, whatever the rules say.
+BUILTIN_FILE_PATTERNS: tuple[str, ...] = (
+    ".env",
+    ".env.*",
+    ".dev.vars",
+    "*.p8",
+    "*.p12",
+    "*.pem",
+    "*.keystore",
+    "*.jks",
+    "*.tfstate",
+    "*.tfstate.backup",
+    "*.tfvars",
+    "*.tfvars.json",
+    "*.key",
+    "*.pfx",
+    "id_rsa*",
+    "id_ed25519*",
+    "*.ppk",
+    ".netrc",
+    ".npmrc",
+    ".pypirc",
+)
+# Templates such as .env.example hold no secrets. The exception applies to file patterns only, so nothing under an
+# excluded folder comes back.
+EXAMPLE_EXCEPTION = "!*.example"
+BUILTIN_DIRECTORY_PATTERNS: tuple[str, ...] = (".terraform/",)
+# gitleaks obeys these from the folder it scans, so they never reach source/.
+SCANNER_SETTINGS_PATTERNS: tuple[str, ...] = (".gitleaksignore", ".gitleaks.toml")
+
+
+# Code points HFS+ ignores in names, so ".g\u200cit" lands as ".git" (git's is_hfs_dotgit checks the same ones).
+IGNORED_IN_NAMES = dict.fromkeys([*range(0x200C, 0x2010), *range(0x202A, 0x202F), *range(0x206A, 0x2070), 0xFEFF])
+
+
+def on_disk_key(path: str) -> str:
+    """The name a case-insensitive, normalizing file system (APFS, HFS+) sees for a path."""
+    return unicodedata.normalize("NFC", path.translate(IGNORED_IN_NAMES)).casefold()
+
+
+class Reason(StrEnum):
+    SECRET_PATTERN = "secret pattern"  # noqa: S105 - a reason label, not a password
+    IGNORED = "ignore rules"
+    GITLEAKS = "gitleaks"
+    SCANNER_SETTINGS = "scanner settings"
+    NOT_A_FILE = "symlink or submodule"
+    UNSAFE_PATH = "unsafe path"
+
+
+class ExclusionRules:
+    """Decides whether a path in a target exists for Codetrail."""
+
+    def __init__(self, ignore_lines: Sequence[str]) -> None:
+        self._secret_files = GitIgnoreSpec.from_lines([*BUILTIN_FILE_PATTERNS, EXAMPLE_EXCEPTION])
+        self._secret_directories = GitIgnoreSpec.from_lines(BUILTIN_DIRECTORY_PATTERNS)
+        self._scanner_settings = GitIgnoreSpec.from_lines(SCANNER_SETTINGS_PATTERNS)
+        # Ignore lines match in any case too, as git's do on macOS.
+        self._ignored = GitIgnoreSpec.from_lines([line.lower() for line in ignore_lines])
+
+    def reason(self, path: str) -> Reason | None:
+        # The built-in patterns are lower-case and match in any case: macOS volumes ignore case.
+        folded = path.lower()
+        if self._secret_directories.match_file(folded) or self._secret_files.match_file(folded):
+            return Reason.SECRET_PATTERN
+        if self._scanner_settings.match_file(on_disk_key(path)):
+            return Reason.SCANNER_SETTINGS
+        if self._ignored.match_file(folded):
+            return Reason.IGNORED
+        return None

codetrail/repo/secrets.py

@@ -0,0 +1,145 @@
+"""Scans for secrets with gitleaks (design section 3.4; ADR 0002).
+
+gitleaks always runs with Codetrail's own configuration, ignores `gitleaks:allow` comments and `.gitleaksignore`
+files, and never sees GITLEAKS_* settings, so nothing in a target can switch the scan off. Findings carry the path,
+the rule and the line, never the value. A missing, failing or stuck gitleaks raises, so callers fail closed, with what
+it printed. A mise shim is resolved to its binary first, since gitleaks runs in an empty folder where no version is set.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import tempfile
+from contextlib import suppress
+from dataclasses import dataclass
+from importlib.resources import as_file, files
+from pathlib import Path
+
+from codetrail.config import ToolsSettings
+from codetrail.errors import CodetrailError
+from codetrail.repo.rules import on_disk_key
+
+COMMON_FLAGS = (
+    "--report-format", "json", "--redact", "--no-banner", "--exit-code", "0", "--ignore-gitleaks-allow",
+    "--gitleaks-ignore-path", os.devnull, "--log-level", "error",
+)  # fmt: skip
+POINT_AT_ANOTHER = "To run a particular gitleaks, set [tools] gitleaks in the configuration to its absolute path."
+RAISE_THE_TIMEOUT = "For a large repository, raise [tools] gitleaks_timeout_seconds in the configuration."
+ESCAPE_SEQUENCES = re.compile(r"\x1b\[[0-9;?]*[A-Za-z]|[^\x20-\x7e]")
+MAX_EXPLANATION = 300
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: str
+    rule: str
+    line: int
+
+
+class SecretScanner:
+    def __init__(self, tools: ToolsSettings) -> None:
+        self._executable = tools.gitleaks
+        self._timeout_seconds = tools.gitleaks_timeout_seconds
+
+    def scan_directory(self, root: Path) -> list[Finding]:
+        """Every finding under `root`, with paths relative to it."""
+        if any(on_disk_key(child.name) == ".gitleaksignore" for child in root.iterdir()):
+            raise CodetrailError(f"{root} holds a .gitleaksignore, which gitleaks would obey; refusing to scan it.")
+        findings = self._run(["dir", str(root)], None)
+        resolved = root.resolve()
+        return [
+            Finding(path=str(Path(item.path).resolve().relative_to(resolved)), rule=item.rule, line=item.line)
+            for item in findings
+        ]
+
+    def scan_text(self, text: str) -> list[Finding]:
+        """Every finding in the text, with an empty path and the line within the text."""
+        return self._run(["stdin"], text.encode("utf-8", "surrogateescape"))
+
+    def _run(self, arguments: list[str], input: bytes | None) -> list[Finding]:
+        environment = {key: value for key, value in os.environ.items() if not key.startswith("GITLEAKS_")}
+        executable = self._binary(environment)
+        with as_file(files("codetrail.repo") / "gitleaks.toml") as config, tempfile.TemporaryDirectory() as folder:
+            report = Path(folder) / "report.json"
+            command = [executable, *arguments, "--config", str(config), *COMMON_FLAGS, "--report-path", str(report)]
+            # An empty working directory: `gitleaks stdin` would load ./.gitleaksignore from wherever it runs.
+            try:
+                result = subprocess.run(  # noqa: S603
+                    command, input=input, capture_output=True, env=environment, check=False, cwd=folder,
+                    timeout=self._timeout_seconds,
+                )  # fmt: skip
+            except subprocess.TimeoutExpired:
+                raise CodetrailError(
+                    f"gitleaks didn't finish within {self._timeout_seconds:g} seconds "
+                    f"([tools] gitleaks_timeout_seconds); the scan didn't complete. {RAISE_THE_TIMEOUT}"
+                ) from None
+            if result.returncode != 0 or not report.exists():
+                raise CodetrailError(
+                    f"gitleaks failed (exit code {result.returncode}); the scan didn't complete. "
+                    f"It said: {_explanation(result.stderr)}. {POINT_AT_ANOTHER}"
+                )
+            items = json.loads(report.read_text() or "[]")
+        return [Finding(path=item["File"], rule=item["RuleID"], line=int(item["StartLine"])) for item in items]
+
+    def _binary(self, environment: dict[str, str]) -> str:
+        """The gitleaks to run; for a mise shim, the one mise picks in the folder Codetrail was started from."""
+        found = shutil.which(self._executable)
+        if found is None:
+            raise CodetrailError(
+                f"gitleaks wasn't found ({self._executable!r}); Codetrail won't read a repository without it. "
+                f"Install it (for example with `mise install`). {POINT_AT_ANOTHER}"
+            )
+        shim = Path(found)
+        mise = shim.resolve()
+        if mise.name != "mise":
+            return found
+        # A shim picks the version from its working directory, and gitleaks runs in an empty one, so ask mise here.
+        # Its own process group, killed whole on a timeout or an interrupt (the terminal's Ctrl-C no longer reaches
+        # it): a template's exec() can start commands that outlive mise.
+        with subprocess.Popen(  # noqa: S603
+            [str(mise), "which", shim.name],
+            stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=environment,
+            start_new_session=True,
+        ) as process:  # fmt: skip
+            try:
+                stdout, stderr = process.communicate(timeout=self._timeout_seconds)
+            except BaseException as error:
+                with suppress(ProcessLookupError, PermissionError):
+                    os.killpg(process.pid, signal.SIGKILL)
+                process.wait()
+                if not isinstance(error, subprocess.TimeoutExpired):
+                    raise
+                raise CodetrailError(
+                    f"{found} is a mise shim, and mise didn't say which gitleaks it runs here within "
+                    f"{self._timeout_seconds:g} seconds ([tools] gitleaks_timeout_seconds); the scan didn't run. "
+                    f"Check the mise configuration in the folder Codetrail was started from. {POINT_AT_ANOTHER}"
+                ) from None
+        binary = Path(stdout.decode("utf-8", "replace").strip())
+        if process.returncode != 0 or not binary.is_absolute():
+            # Only mise's own error lines: it quotes the configuration line it couldn't parse on the lines after.
+            raise CodetrailError(
+                f"{found} is a mise shim, and mise couldn't say which gitleaks it runs here "
+                f"(exit code {process.returncode}). It said: {_explanation(stderr, 'mise ERROR')}. "
+                "Run Codetrail from a folder whose mise configuration sets gitleaks, or set a global version with "
+                f"`mise use -g gitleaks`. {POINT_AT_ANOTHER}"
+            )
+        # A trusted mise configuration in the folder, perhaps a target's, can name any program with a path: version.
+        installs = (shim.parent.parent / "installs" / shim.name).resolve()
+        resolved = binary.resolve()  # checked and run as one path, so no link can change in between
+        if not resolved.is_relative_to(installs) or not resolved.is_file():
+            raise CodetrailError(
+                f"mise named {_explanation(stdout)} as gitleaks here, which isn't one of mise's own installs "
+                f"in {installs}; Codetrail won't run it. {POINT_AT_ANOTHER}"
+            )
+        return str(resolved)
+
+
+def _explanation(stderr: bytes, prefix: str = "") -> str:
+    """A program's error lines that start with `prefix`, as one printable line without colour codes, cut short."""
+    lines = (ESCAPE_SEQUENCES.sub("", line).strip() for line in stderr.decode("utf-8", "replace").splitlines())
+    return "; ".join(line for line in lines if line.startswith(prefix) and line)[:MAX_EXPLANATION] or "nothing"