← Files Codex SecurityARCHIVED FILE
scripts/workbench_target_state.py
43.5 KB · Nov 18, 2026 · 06:11 UTC
"""Persist stable Codex Security target identities."""
from __future__ import annotations
import argparse
import ctypes
import hashlib
import os
import platform
import re
import sqlite3
import stat
import sys
from dataclasses import dataclass, replace
from datetime import datetime, timezone
from decimal import Decimal
from fractions import Fraction
from pathlib import Path
from urllib.parse import urlsplit
# Some plugin hosts launch Python with safe-path isolation enabled.
sys.path.insert(0, str(Path(__file__).resolve().parent))
from filesystem_identity import (
serialize_filesystem_identity,
stored_filesystem_identity_matches,
)
from workbench_target import (
_protected_repository_root,
git_bytes,
git_output,
git_worktree_context,
pin_scoped_git,
)
def stable_target_id(target: Path) -> str:
"""Hash the supplied path spelling into the workbench ID for a local workspace."""
digest = hashlib.sha256(f"local-workspace\0{target}".encode()).hexdigest()
return f"target_sha256_{digest}"
def repository_relative_path(target: Path) -> str | None:
"""Return the target's normalized location within its own Git worktree."""
worktree = _repository_worktree(target)
return worktree[1] if worktree is not None else None
def _repository_worktree(target: Path) -> tuple[Path, str] | None:
try:
return git_worktree_context(target)
except SystemExit:
return None
def _path_from_git_bytes(
value: bytes, relative_to: Path, *, strip_line_feed: bool = True
) -> Path | None:
if strip_line_feed and value.endswith(b"\n"):
value = value[:-2] if sys.platform == "win32" and value.endswith(b"\r\n") else value[:-1]
if not value or b"\0" in value:
return None
path = Path(os.fsdecode(value))
return Path(os.path.realpath(path if path.is_absolute() else relative_to / path))
def _git_path(target: Path, *args: str) -> Path | None:
value = git_bytes(target, *args)
return _path_from_git_bytes(value, target) if value is not None else None
def _same_existing_path(first: Path | None, second: Path | None) -> bool:
if first is None or second is None:
return False
try:
return first.samefile(second)
except OSError:
return False
def _registered_worktree(target: Path, root: Path, common: Path) -> bool:
registered = git_bytes(target, "worktree", "list", "--porcelain", "-z")
if registered is not None:
return any(
os.path.realpath(os.fsdecode(record[len(b"worktree ") :])) == str(root)
for record in registered.split(b"\0")
if record.startswith(b"worktree ")
)
# Git before 2.36 emits unquoted newline-delimited paths. Repository-side
# ownership records are unambiguous even when a checkout path has newlines.
gitdir = _git_path(target, "rev-parse", "--absolute-git-dir")
dotgit = root / ".git"
try:
mode = dotgit.lstat().st_mode
if stat.S_ISDIR(mode):
return _same_existing_path(gitdir, common) and _same_existing_path(gitdir, dotgit)
if not stat.S_ISREG(mode) or gitdir is None or not gitdir.is_dir():
return False
forward = dotgit.read_bytes()
if not forward.startswith(b"gitdir: ") or not _same_existing_path(
_path_from_git_bytes(forward[len(b"gitdir: ") :], root), gitdir
):
return False
if _same_existing_path(gitdir, common):
configured = git_bytes(
target,
"config",
"--null",
"--show-scope",
"--no-includes",
"--get",
"core.worktree",
)
fields = configured.split(b"\0") if configured is not None else []
if (
len(fields) != 3
or fields[0] not in (b"local", b"worktree")
or not fields[1]
or fields[2]
):
return False
configured_root = _path_from_git_bytes(fields[1], gitdir, strip_line_feed=False)
return _same_existing_path(configured_root, root)
return _same_existing_path(gitdir.parent, common / "worktrees") and _same_existing_path(
_path_from_git_bytes((gitdir / "gitdir").read_bytes(), gitdir), dotgit
)
except (OSError, ValueError):
return False
class _LinuxStatxTimestamp(ctypes.Structure):
_fields_ = (
("seconds", ctypes.c_int64),
("nanoseconds", ctypes.c_uint32),
("_reserved", ctypes.c_int32),
)
class _LinuxStatx(ctypes.Structure):
# Linux's statx UAPI keeps birth time at offset 0x50 in a 0x100-byte buffer.
_fields_ = (
("mask", ctypes.c_uint32),
("_before_birth_time", ctypes.c_ubyte * 76),
("birth_time", _LinuxStatxTimestamp),
("_after_birth_time", ctypes.c_ubyte * 160),
)
def _linux_repository_birth_time_ns(path: str) -> int | None:
if ctypes.sizeof(_LinuxStatx) != 256 or _LinuxStatx.birth_time.offset != 80:
return None
metadata = _LinuxStatx()
birth_time_mask = 0x800
arguments = (-100, os.fsencode(path), 0, birth_time_mask, ctypes.byref(metadata))
try:
libc = ctypes.CDLL(None, use_errno=True)
try:
statx = libc.statx
except AttributeError:
# Older musl has the syscall but no statx wrapper. Only use known LP64 ABIs.
if ctypes.sizeof(ctypes.c_void_p) != 8 or ctypes.sizeof(ctypes.c_long) != 8:
return None
number = {"x86_64": 332, "aarch64": 291}.get(platform.machine())
if number is None:
return None
statx = libc.syscall
statx.argtypes = (
ctypes.c_long,
ctypes.c_long,
ctypes.c_char_p,
ctypes.c_long,
ctypes.c_ulong,
ctypes.POINTER(_LinuxStatx),
)
statx.restype = ctypes.c_long
status = statx(number, *arguments)
else:
statx.argtypes = (
ctypes.c_int,
ctypes.c_char_p,
ctypes.c_int,
ctypes.c_uint,
ctypes.POINTER(_LinuxStatx),
)
statx.restype = ctypes.c_int
status = statx(*arguments)
except (AttributeError, OSError):
return None
birth_time = metadata.birth_time
if (
status != 0
or not metadata.mask & birth_time_mask
or not 0 <= birth_time.nanoseconds < 1_000_000_000
):
return None
birth_time_ns = birth_time.seconds * 1_000_000_000 + birth_time.nanoseconds
return birth_time_ns if birth_time_ns > 0 else None
def _repository_birth_time_ns(path: str, metadata: os.stat_result) -> int | None:
birth_time_ns = getattr(metadata, "st_birthtime_ns", None)
if birth_time_ns is not None:
return birth_time_ns if birth_time_ns > 0 else None
if os.name == "nt":
return metadata.st_ctime_ns if metadata.st_ctime_ns > 0 else None
birth_time = getattr(metadata, "st_birthtime", None)
if birth_time is not None:
return int(birth_time * 1_000_000_000) if birth_time > 0 else None
if not sys.platform.startswith("linux"):
return None
return _linux_repository_birth_time_ns(path)
@dataclass(frozen=True)
class GitRepositoryIdentity:
value: str
relative_path: str
common_directory: str
device: int | str
inode: int | str
birth_time_ns: int
object_birth_time_ns: int
previous_value: str | None = None
@property
def legacy_value(self) -> str:
return _identity_digest(
f"git-common-dir\0{self.common_directory}\0{self.device}\0{self.inode}\0"
f"{self.birth_time_ns}\0{self.relative_path}"
)
def _identity_digest(material: str, prefix: str = "repository_sha256_") -> str:
return f"{prefix}{hashlib.sha256(material.encode(errors='surrogateescape')).hexdigest()}"
def _repository_worktree_location(target: Path) -> tuple[Path, str] | None:
common_directory = _git_path(target, "rev-parse", "--path-format=absolute", "--git-common-dir")
worktree = _repository_worktree(target)
if common_directory is None or worktree is None:
return None
worktree_root, relative = worktree
if not _registered_worktree(target, worktree_root, common_directory):
return None
return common_directory, relative
def same_repository_worktree(before: Path, after: Path) -> bool:
before_location = _repository_worktree_location(before)
after_location = _repository_worktree_location(after)
return (
before_location is not None
and after_location is not None
and before_location[1] == after_location[1]
and _same_existing_path(before_location[0], after_location[0])
)
def _repository_identity_details(target: Path | str) -> GitRepositoryIdentity | None:
target = Path(target)
location = _repository_worktree_location(target)
if location is None:
return None
common_directory, relative = location
object_directory = _git_path(
target, "rev-parse", "--path-format=absolute", "--git-path", "objects"
)
if object_directory is None:
return None
canonical_directory = str(common_directory)
try:
metadata = common_directory.stat()
object_metadata = object_directory.stat()
except OSError:
return None
if not stat.S_ISDIR(metadata.st_mode) or not stat.S_ISDIR(object_metadata.st_mode):
return None
birth_time_ns = _repository_birth_time_ns(canonical_directory, metadata)
object_birth_time_ns = _repository_birth_time_ns(str(object_directory), object_metadata)
if birth_time_ns is None or object_birth_time_ns is None:
return None
device = serialize_filesystem_identity(metadata.st_dev)
inode = serialize_filesystem_identity(metadata.st_ino)
material = (
f"git-generation-v2\0{canonical_directory}\0{device}\0{inode}\0"
f"{birth_time_ns}\0{object_directory}\0"
f"{serialize_filesystem_identity(object_metadata.st_dev)}\0"
f"{serialize_filesystem_identity(object_metadata.st_ino)}\0"
f"{object_birth_time_ns}\0{relative}"
)
previous_value = None
value = _identity_digest(material)
if sys.platform == "linux":
try:
common_filesystem = os.statvfs(common_directory).f_fsid
object_filesystem = os.statvfs(object_directory).f_fsid
except OSError:
return None
previous_value = value
value = _identity_digest(
f"git-generation-v3\0{canonical_directory}\0{common_filesystem}\0{inode}\0"
f"{birth_time_ns}\0{object_directory}\0{object_filesystem}\0"
f"{serialize_filesystem_identity(object_metadata.st_ino)}\0"
f"{object_birth_time_ns}\0{relative}",
"repository_v3_sha256_",
)
return GitRepositoryIdentity(
value,
relative,
canonical_directory,
device,
inode,
birth_time_ns,
object_birth_time_ns,
previous_value,
)
def repository_identity(target: Path | str) -> str | None:
"""Identify matching Git worktree targets without storing remote credentials."""
identity = _repository_identity_details(target)
return identity.value if identity is not None else None
def repository_origin(target: Path) -> tuple[str, str] | None:
remote = git_output(target, "remote", "get-url", "origin")
if remote is None:
return None
if "://" in remote:
try:
parsed = urlsplit(remote)
port = parsed.port
except ValueError:
return None
if parsed.scheme not in {"https", "ssh"} or parsed.hostname is None:
return None
if parsed.query or parsed.fragment:
return None
host = parsed.hostname
if port is not None and port != {"https": 443, "ssh": 22}[parsed.scheme]:
host = f"{host}:{port}"
path = parsed.path
else:
authority, separator, path = remote.partition(":")
if not separator or "?" in path or "#" in path:
return None
host = authority.rsplit("@", 1)[-1]
path = path.strip("/").removesuffix(".git")
return (host.lower(), path) if host and path else None
def supports_repository_identity(connection: sqlite3.Connection) -> bool:
return any(
row["name"] == "repository_identity"
for row in connection.execute("PRAGMA table_info(security_targets)")
)
@dataclass(frozen=True)
class RepositoryTargetState:
target_id: str
target_path: str
stored_identity: str | None
resolved_path: str | None = None
metadata: os.stat_result | None = None
repository: GitRepositoryIdentity | None = None
ownership_matches: bool = False
strict_owner_matches: bool = False
generation_predates_history: bool = False
has_historical_scans: bool = False
missing: bool = False
previous_generation: str | None = None
@property
def live_identity(self) -> str | None:
return (
self.previous_generation or self.repository.value
if self.repository is not None
else None
)
@property
def verified_identity(self) -> str | None:
if not self.ownership_matches or self.repository is None:
return None
if self.stored_identity is None:
# Checkout ownership and repository age cannot identify an older Git generation.
return (
self.live_identity
if self.strict_owner_matches
and self.generation_predates_history
and not self.has_historical_scans
else None
)
return self.live_identity if self.live_identity == self.stored_identity else None
def require_owner(self) -> None:
if not self.ownership_matches:
raise SystemExit(
f"The repository checkout at {self.target_path} no longer matches its recorded "
"security scan history; refusing to reuse its target."
)
def _inspect_repository_target(
connection: sqlite3.Connection,
target_id: str,
target_path: str,
stored_identity: str | None,
*,
scan_columns: set[str] | None = None,
) -> RepositoryTargetState:
target = Path(target_path)
try:
resolved_path = str(target.resolve())
except (OSError, RuntimeError):
return RepositoryTargetState(target_id, target_path, stored_identity)
try:
metadata = target.stat()
except (FileNotFoundError, NotADirectoryError):
return RepositoryTargetState(
target_id,
target_path,
stored_identity,
resolved_path=resolved_path,
ownership_matches=True,
missing=True,
)
except OSError:
return RepositoryTargetState(
target_id, target_path, stored_identity, resolved_path=resolved_path
)
repository = _repository_identity_details(target)
if scan_columns is None:
scan_columns = {row["name"] for row in connection.execute("PRAGMA table_info(scans)")}
historical_scan = False
recorded_owner = False
malformed_owner = False
mismatch = False
strict_owner_matches = False
generation_predates_history = False
ownership_matches = True
if {"target_id", "target_path"} <= scan_columns:
recorded_generations = (
{
row[0]
for row in connection.execute(
"SELECT DISTINCT repository_generation FROM scans "
"WHERE (target_id = ? OR target_path = ?) AND repository_generation IS NOT NULL",
(target_id, target_path),
)
}
if "repository_generation" in scan_columns
else set()
)
generation_conflict = bool(recorded_generations) and (
repository is None
or recorded_generations not in ({repository.value}, {repository.previous_value})
)
if not {"target_device", "target_inode"} <= scan_columns:
historical_scan = (
connection.execute(
"SELECT 1 FROM scans WHERE target_id = ? OR target_path = ? LIMIT 1",
(target_id, target_path),
).fetchone()
is not None
)
strict_owner_matches = not historical_scan
generation_predates_history = repository is not None and not historical_scan
else:
strict_owner_matches = True
timestamps = (
", started_at, created_at" if {"started_at", "created_at"} <= scan_columns else ""
)
revisions = ", target_revision" if "target_revision" in scan_columns else ""
scans = connection.execute(
f"""
SELECT target_device, target_inode{timestamps}{revisions} FROM scans
WHERE target_id = ? OR target_path = ?
""",
(target_id, target_path),
).fetchall()
git_scans = [
scan
for scan in scans
if "target_revision" not in scan.keys() or scan["target_revision"] != "unversioned"
]
generation_predates_history = repository is not None and _repository_predates_history(
repository, git_scans
)
for scan in scans:
historical_scan = True
device, inode = scan["target_device"], scan["target_inode"]
if device is None and inode is None:
strict_owner_matches = False
continue
if device is None or inode is None:
malformed_owner = True
strict_owner_matches = False
continue
recorded_owner = True
if not stored_filesystem_identity_matches(device, metadata.st_dev):
strict_owner_matches = False
mismatch = mismatch or sys.platform != "linux"
if not stored_filesystem_identity_matches(inode, metadata.st_ino):
mismatch = True
strict_owner_matches = False
stored_matches = repository is not None and (
stored_identity
in {
repository.value,
repository.legacy_value,
repository.previous_value or repository.value,
}
or (
repository.value.startswith("repository_v3_sha256_")
and recorded_generations == {repository.value}
and isinstance(stored_identity, str)
and re.fullmatch(r"repository_sha256_[0-9a-f]{64}", stored_identity) is not None
)
)
verified_repository = repository is not None and (
stored_matches
or recorded_generations in ({repository.value}, {repository.previous_value})
)
ownership_matches = not (
malformed_owner
or mismatch
and (
not verified_repository or repository is None or repository.relative_path == "."
)
or stored_identity is not None
and (not stored_matches or historical_scan and not recorded_owner)
or stored_identity is None
and repository is not None
and historical_scan
and not verified_repository
and not generation_predates_history
)
ownership_matches = ownership_matches and not generation_conflict
previous_generation = None
if (
ownership_matches
and repository is not None
and repository.previous_value is not None
and supports_repository_identity(connection)
and "repository_generation" in scan_columns
and connection.execute(
"SELECT 1 FROM security_targets WHERE repository_identity = ? "
"UNION ALL SELECT 1 FROM scans WHERE repository_generation = ? LIMIT 1",
(repository.previous_value, repository.previous_value),
).fetchone()
is not None
):
previous_generation = repository.previous_value
return RepositoryTargetState(
target_id,
target_path,
stored_identity,
resolved_path,
metadata,
repository,
ownership_matches,
strict_owner_matches,
generation_predates_history,
historical_scan,
previous_generation=previous_generation,
)
def verified_repository_identity(
connection: sqlite3.Connection,
target_id: str,
target_path: str,
*,
stored_identity: str | None = None,
) -> str | None:
try:
return _inspect_repository_target(
connection, target_id, target_path, stored_identity
).verified_identity
except SystemExit:
# Historical identity enrichment is optional; active registration stays strict.
return None
def scan_repository_generation(scan: sqlite3.Row | dict) -> str | None:
return scan["repository_generation"] if "repository_generation" in scan.keys() else None
def scan_repository_group(scan: sqlite3.Row | dict) -> tuple[str, str]:
generation = scan_repository_generation(scan)
return ("repository", generation) if generation is not None else ("target", scan["target_id"])
@dataclass(frozen=True)
class RepositoryScanScope:
"""A verified generation and, separately, its exact target's legacy scans."""
generation: str | None = None
target_id: str | None = None
exact_target: bool = False
available: bool = True
def sql(
self, alias: str = "scans", *, supports_generation: bool = True
) -> tuple[str, tuple[str, ...]]:
if not self.available:
return "0", ()
if self.exact_target:
return (f"{alias}.target_id = ?", (self.target_id,)) if self.target_id else ("0", ())
clauses, values = [], []
if self.generation is not None and supports_generation:
clauses.append(f"{alias}.repository_generation = ?")
values.append(self.generation)
if self.target_id:
legacy = f"{alias}.repository_generation IS NULL AND " if supports_generation else ""
clauses.append(f"({legacy}{alias}.target_id = ?)")
values.append(self.target_id)
return (f"({' OR '.join(clauses)})", tuple(values)) if clauses else ("0", ())
def contains(self, scan: sqlite3.Row | dict) -> bool:
if not self.available:
return False
if self.exact_target:
return bool(self.target_id) and scan["target_id"] == self.target_id
generation = scan_repository_generation(scan)
if generation is not None:
return generation == self.generation
return bool(self.target_id) and scan["target_id"] == self.target_id
class RepositoryIdentityCache:
"""One request's saved identities and verified live aliases."""
def __init__(self, connection: sqlite3.Connection) -> None:
self.connection = connection
self.supports_identity = supports_repository_identity(connection)
self.scan_columns = {row["name"] for row in connection.execute("PRAGMA table_info(scans)")}
self.supports_generation = "repository_generation" in self.scan_columns
identity_column = "repository_identity" if self.supports_identity else "NULL"
self.targets = {
row["target_id"]: row
for row in connection.execute(
"SELECT id AS target_id, current_path AS target_path, "
f"{identity_column} AS repository_identity FROM security_targets"
)
}
self.targets_by_path = {row["target_path"]: row for row in self.targets.values()}
self._states: dict[tuple[str, str, str | None], RepositoryTargetState] = {}
self._origins: dict[str, tuple[str, str] | None] = {}
def for_row(self, row: sqlite3.Row | dict) -> RepositoryTargetState:
target = self.targets.get(row["target_id"])
stored = (
row["repository_identity"]
if "repository_identity" in row.keys()
else target["repository_identity"]
if target is not None
else None
)
key = (
row["target_id"] or "",
row["target_path"],
stored,
)
if key not in self._states:
self._states[key] = _inspect_repository_target(
self.connection, *key, scan_columns=self.scan_columns
)
return self._states[key]
def for_path(self, target_path: str) -> RepositoryTargetState:
path = Path(target_path)
if os.name != "nt" and ".." in path.parts:
last_parent = len(path.parts) - 1 - path.parts[::-1].index("..")
try:
# A missing final checkout can retain history. Every component
# traversed before a parent segment must still exist.
Path(*path.parts[: last_parent + 1]).stat()
except (OSError, RuntimeError):
return RepositoryTargetState("", target_path, None)
row = self.targets_by_path.get(target_path)
if row is None:
try:
canonical = str(Path(target_path).resolve())
except (OSError, RuntimeError):
canonical = None
row = self.targets_by_path.get(canonical)
if row is None:
row = next(
(
target
for target in self.targets.values()
if _same_existing_path(Path(target["target_path"]), Path(target_path))
),
None,
)
return self.for_row(
row
if row is not None
else {
"target_id": "",
"target_path": target_path,
"repository_identity": None,
}
)
def scope(self, target_id: str) -> RepositoryScanScope:
target = self.targets.get(target_id)
return (
self._scope_for_state(self.for_row(target))
if target is not None
else RepositoryScanScope(target_id=target_id)
)
def history_path(self, target_path: str) -> str:
"""Use the worktree root when a subdirectory has no saved history of its own."""
requested = self.for_path(target_path)
if (
not requested.ownership_matches
or requested.target_id
or requested.repository is None
or requested.repository.relative_path == "."
):
return target_path
if (
self.supports_generation
and self.connection.execute(
"SELECT 1 FROM scans WHERE repository_generation = ? LIMIT 1",
(requested.live_identity,),
).fetchone()
):
return target_path
worktree = _repository_worktree(Path(target_path))
return str(worktree[0]) if worktree is not None else target_path
def scope_for_path(self, target_path: str) -> RepositoryScanScope:
return self._scope_for_state(self.for_path(target_path))
def scope_for_scan(self, scan: sqlite3.Row | dict) -> RepositoryScanScope:
requested = self.for_row(scan)
generation = scan_repository_generation(scan)
if not requested.ownership_matches or (
generation is not None and generation != requested.live_identity
):
return RepositoryScanScope(available=False)
return RepositoryScanScope(generation, requested.target_id)
def _scope_for_state(self, requested: RepositoryTargetState) -> RepositoryScanScope:
if not requested.ownership_matches:
return RepositoryScanScope(available=False)
return RepositoryScanScope(
requested.live_identity if not requested.missing else None,
requested.target_id or None,
exact_target=requested.missing,
)
def origin(self, state: RepositoryTargetState) -> tuple[str, str] | None:
if state.target_path not in self._origins:
self._origins[state.target_path] = repository_origin(Path(state.target_path))
return self._origins[state.target_path]
def require_scan_checkout_owner(connection: sqlite3.Connection, scan: sqlite3.Row | dict) -> None:
identities = RepositoryIdentityCache(connection)
owner = identities.for_row(scan)
owner.require_owner()
if owner.missing or not identities.scope_for_scan(scan).contains(scan):
raise SystemExit("The saved scan no longer matches the selected repository checkout.")
def upgrade_linux_repository_generations(connection: sqlite3.Connection) -> None:
"""Convert only old digests authenticated before their device evidence changes."""
if sys.platform != "linux":
return
targets = connection.execute(
"SELECT id, current_path, repository_identity FROM security_targets "
"WHERE repository_identity GLOB 'repository_sha256_*' OR EXISTS ("
"SELECT 1 FROM scans WHERE (scans.target_id = security_targets.id "
"OR scans.target_path = security_targets.current_path) "
"AND repository_generation GLOB 'repository_sha256_*')"
).fetchall()
for target in targets:
try:
state = _inspect_repository_target(
connection, target["id"], target["current_path"], target["repository_identity"]
)
except SystemExit:
continue
_upgrade_repository_generation(connection, state)
def _upgrade_repository_generation(
connection: sqlite3.Connection, state: RepositoryTargetState
) -> RepositoryTargetState:
identity = state.repository
if (
identity is None
or identity.previous_value is None
or state.stored_identity not in (None, identity.value, identity.previous_value)
or not state.ownership_matches
or not state.strict_owner_matches
):
return state
connection.execute(
"UPDATE security_targets SET repository_identity = ? WHERE repository_identity = ?",
(identity.value, identity.previous_value),
)
connection.execute(
"UPDATE scans SET repository_generation = ? WHERE repository_generation = ?",
(identity.value, identity.previous_value),
)
return replace(
state,
stored_identity=(
identity.value
if state.stored_identity == identity.previous_value
else state.stored_identity
),
previous_generation=None,
)
def _pre_release_repository_identities(identity: GitRepositoryIdentity) -> set[str]:
directory = os.path.normcase(identity.common_directory)
relative = os.path.normcase(os.fspath(Path(identity.relative_path))).replace(os.sep, "/")
prefix = f"git-common-dir\0{directory}\0{identity.device}\0{identity.inode}\0"
identities = {_identity_digest(f"{prefix}{relative}")}
try:
generation = (Path(identity.common_directory) / "description").lstat()
except OSError:
return identities
if stat.S_ISREG(generation.st_mode):
identities.add(
_identity_digest(
f"{prefix}git-description\0"
f"{serialize_filesystem_identity(generation.st_dev)}\0"
f"{serialize_filesystem_identity(generation.st_ino)}\0"
f"{generation.st_ctime_ns}\0{relative}"
)
)
return identities
def _timestamp_ns(value: str) -> int | Fraction | None:
try:
# Python 3.10 requires three or six fractional digits; stored timestamps
# can come from newer runtimes that accept any RFC 3339 precision.
fraction = re.search(r"\.(\d+)(?:[Zz]|[+-]\d{2}:\d{2})$", value)
normalized = value
if (
fraction is not None
and fraction[1].isascii()
and re.search(r"[0-9]{2}:[0-9]{2}:[0-9]{2}$", value[: fraction.start()]) is not None
):
normalized = (
value[: fraction.start(1)]
+ fraction[1][:6].ljust(6, "0")
+ value[fraction.end(1) :]
)
if normalized.endswith(("Z", "z")):
normalized = normalized[:-1] + "+00:00"
timestamp = datetime.fromisoformat(normalized)
except (TypeError, ValueError):
return None
if timestamp.tzinfo is None:
return None
delta = timestamp - datetime(1970, 1, 1, tzinfo=timezone.utc)
nanoseconds = (delta.days * 86400 + delta.seconds) * 1_000_000_000 + delta.microseconds * 1000
# datetime truncates RFC 3339 fractions after six digits; sealed timestamps retain them.
if fraction is not None and len(fraction[1]) > 6:
return nanoseconds + Fraction(Decimal("0." + fraction[1][6:])) * 1000
return nanoseconds
def _repository_predates_history(
identity: GitRepositoryIdentity,
scans: list[sqlite3.Row],
*,
empty_timestamp: str | None = None,
) -> bool:
if not scans and empty_timestamp is None:
return True
if any(not {"started_at", "created_at"} <= set(scan.keys()) for scan in scans):
return False
timestamps = (
[_timestamp_ns(scan[column]) for scan in scans for column in ("started_at", "created_at")]
if scans
else [_timestamp_ns(empty_timestamp)]
)
repository_birth = max(identity.birth_time_ns, identity.object_birth_time_ns)
return all(value is not None for value in timestamps) and repository_birth <= min(timestamps)
def normalize_pre_release_repository_identities(connection: sqlite3.Connection) -> None:
"""Retain only individually established pre-release identity bindings."""
if not supports_repository_identity(connection):
return
identities = RepositoryIdentityCache(connection)
targets = connection.execute(
"SELECT id AS target_id, current_path AS target_path, created_at, repository_identity "
"FROM security_targets WHERE repository_identity IS NOT NULL"
).fetchall()
states = {target["target_id"]: identities.for_row(target) for target in targets}
anchors = {
state.stored_identity: state.repository
for state in states.values()
if state.repository is not None
and state.ownership_matches
and state.stored_identity
in {
state.repository.value,
state.repository.legacy_value,
state.repository.previous_value or state.repository.value,
}
}
for target in targets:
stored = target["repository_identity"]
state = states[target["target_id"]]
scans = connection.execute(
"SELECT started_at, created_at FROM scans WHERE target_id = ? OR target_path = ?",
(target["target_id"], target["target_path"]),
).fetchall()
anchor = anchors.get(stored)
identity = state.repository
replacement = None
if anchor is not None:
if _repository_predates_history(anchor, scans, empty_timestamp=target["created_at"]):
replacement = stored
elif (
identity is not None
and state.strict_owner_matches
and stored in _pre_release_repository_identities(identity)
and _repository_predates_history(identity, scans, empty_timestamp=target["created_at"])
):
replacement = identity.legacy_value
if replacement != stored:
connection.execute(
"UPDATE security_targets SET repository_identity = ? "
"WHERE id = ? AND repository_identity = ?",
(replacement, target["target_id"], stored),
)
def _bind_unscanned_repository_identity(
connection: sqlite3.Connection,
target_id: str,
target_path: str,
identity: str | None,
*,
previous_identity: str | None = None,
) -> bool:
return (
connection.execute(
"""
UPDATE security_targets
SET repository_identity = ?
WHERE id = ? AND current_path = ? AND repository_identity IS ?
AND NOT EXISTS (
SELECT 1 FROM scans
WHERE scans.target_id = security_targets.id
OR scans.target_path = security_targets.current_path
)
""",
(identity, target_id, target_path, previous_identity),
).rowcount
== 1
)
def backfill_repository_identities(connection: sqlite3.Connection) -> None:
if not supports_repository_identity(connection):
return
targets = connection.execute(
"""
SELECT targets.id, targets.current_path
FROM security_targets AS targets
WHERE targets.repository_identity IS NULL
AND NOT EXISTS (
SELECT 1 FROM scans
WHERE scans.target_id = targets.id OR scans.target_path = targets.current_path
)
"""
).fetchall()
for target in targets:
identity = verified_repository_identity(
connection, str(target["id"]), target["current_path"]
)
if identity is not None:
_bind_unscanned_repository_identity(
connection, str(target["id"]), target["current_path"], identity
)
def backfill_security_targets(connection: sqlite3.Connection) -> None:
"""Fill missing target IDs on scans and workspaces in the caller’s transaction."""
workspace_columns = {row["name"] for row in connection.execute("PRAGMA table_info(workspaces)")}
validated_workspace = (
" AND target_path_unvalidated = 0" if "target_path_unvalidated" in workspace_columns else ""
)
rows = connection.execute(
f"""
SELECT target_path FROM workspaces WHERE target_path IS NOT NULL{validated_workspace}
UNION
SELECT target_path FROM scans
"""
).fetchall()
for row in rows:
target_path = row["target_path"]
target_id = ensure_security_target(connection, target_path, verify_ownership=False)
connection.execute(
"UPDATE workspaces SET target_id = ? WHERE target_path = ? AND target_id IS NULL"
+ validated_workspace,
(target_id, target_path),
)
connection.execute(
"UPDATE scans SET target_id = ? WHERE target_path = ? AND target_id IS NULL",
(target_id, target_path),
)
backfill_repository_identities(connection)
@dataclass(frozen=True)
class RegisteredRepositoryTarget:
target_id: str
repository_generation: str | None
def _record_checkout_root(
connection: sqlite3.Connection, row: sqlite3.Row, state: RepositoryTargetState, inserted: bool
) -> None:
if "git_checkout_root" not in row.keys():
return
previous = row["git_checkout_root"]
# Migrations and old rows cannot attest to the former boundary of a checkout.
if previous is None and (not inserted or state.has_historical_scans):
return
target = Path(state.target_path)
if (
state.metadata is None
or not stat.S_ISDIR(state.metadata.st_mode)
or state.resolved_path != state.target_path
):
return
try:
root = _protected_repository_root(target)
except (OSError, RuntimeError):
return
if previous is None or root in Path(previous).parents:
connection.execute(
"UPDATE security_targets SET git_checkout_root = ? "
"WHERE id = ? AND current_path = ? AND git_checkout_root IS ?",
(str(root), state.target_id, state.target_path, previous),
)
def register_security_target(
connection: sqlite3.Connection, target_path: str, *, verify_ownership: bool = True
) -> RegisteredRepositoryTarget:
target_query = "SELECT * FROM security_targets WHERE current_path = ?"
existing = connection.execute(target_query, (target_path,)).fetchone()
inserted = False
if existing is None:
if verify_ownership:
# Pin ambient Git before the new row temporarily lacks a checkout boundary.
pin_scoped_git(Path(target_path))
target_id = stable_target_id(Path(target_path))
timestamp = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
# Leave repository_identity NULL until the guarded binding below succeeds.
insert = connection.execute(
"""
INSERT OR IGNORE INTO security_targets (
id, current_path, display_name, created_at, updated_at
) VALUES (?, ?, ?, ?, ?)
""",
(target_id, target_path, Path(target_path).name, timestamp, timestamp),
)
inserted = insert.rowcount == 1
existing = connection.execute(target_query, (target_path,)).fetchone()
if existing is None:
existing = connection.execute(
"SELECT * FROM security_targets WHERE id = ?", (target_id,)
).fetchone()
if existing is None or Path(existing["current_path"]) != Path(target_path):
raise SystemExit("The repository target changed while it was being registered.")
target_path = existing["current_path"]
target_id = str(existing["id"])
if "repository_identity" not in existing.keys():
return RegisteredRepositoryTarget(target_id, None)
try:
state = _inspect_repository_target(
connection, target_id, target_path, existing["repository_identity"]
)
except SystemExit:
if verify_ownership:
raise
return RegisteredRepositoryTarget(target_id, None)
if not state.has_historical_scans and state.live_identity != state.stored_identity:
_bind_unscanned_repository_identity(
connection,
target_id,
target_path,
state.live_identity,
previous_identity=existing["repository_identity"],
)
existing = connection.execute(target_query, (target_path,)).fetchone()
if existing is None:
raise SystemExit("The repository target changed while it was being registered.")
target_id = str(existing["id"])
state = _inspect_repository_target(
connection, target_id, target_path, existing["repository_identity"]
)
state = _upgrade_repository_generation(connection, state)
if verify_ownership:
state.require_owner()
if existing["repository_identity"] is None:
identity = state.verified_identity
if identity is not None and not _bind_unscanned_repository_identity(
connection, target_id, target_path, identity
):
# A writer may have registered history or bound this target after inspection.
existing = connection.execute(target_query, (target_path,)).fetchone()
if existing is None:
raise SystemExit("The repository target changed while it was being registered.")
target_id = str(existing["id"])
state = _inspect_repository_target(
connection, target_id, target_path, existing["repository_identity"]
)
if verify_ownership:
state.require_owner()
if verify_ownership:
_record_checkout_root(connection, existing, state, inserted)
return RegisteredRepositoryTarget(
target_id, state.live_identity if state.ownership_matches and not state.missing else None
)
def ensure_security_target(
connection: sqlite3.Connection, target_path: str, *, verify_ownership: bool = True
) -> str:
"""Return the stable ID for the registered target and its verified ownership."""
return register_security_target(
connection, target_path, verify_ownership=verify_ownership
).target_id
if __name__ == "__main__":
argparse.ArgumentParser(description=__doc__).parse_args()
SHA-256: 5471646ac8fe3f62d358c49ee2c0f0833ae14f57affe4bb9cea855158d0d6d1c