← Files Codex SecurityARCHIVED FILE
scripts/workbench_source_scopes.py
15.2 KB · Nov 18, 2026 · 06:11 UTC
"""Bind optional finding excerpts to the Git objects selected at scan start."""
from __future__ import annotations
import argparse
import json
import os
import re
import sqlite3
import stat
import sys
from functools import cache
from pathlib import Path, PurePosixPath
from typing import Any
from unicodedata import normalize
sys.path.insert(0, str(Path(__file__).resolve().parent))
from workbench_target import (
clean_worktree_content_digest,
git_command,
git_worktree_context,
)
from workbench_validation import reject_non_finite_json
OBJECT_ID = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
def expected_target_kinds(scan: sqlite3.Row) -> list[str]:
"""Return the manifest target kinds compatible with the stored scan mode, revision, and snapshot digest."""
if scan["mode"] == "diff":
return ["git_diff"]
if scan["target_revision"] == "unversioned":
return ["directory_snapshot"]
if scan["target_snapshot_digest"] is None:
return ["git_worktree", "git_revision"]
if scan["target_snapshot_digest"] == clean_worktree_content_digest():
return ["git_revision"]
return ["git_worktree"]
def requested_scan_paths(scan: sqlite3.Row) -> list[str]:
"""Return the explicit paths in the saved launch recipe, falling back to the scan’s original scope."""
if "recipe_json" in scan.keys() and scan["recipe_json"] is not None:
recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
target = recipe["target"]
if target["kind"] == "paths":
return target["paths"]
return [scan["scope"]]
def public_scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:
"""Return the decoded launch recipe with the internal file-scope metadata removed."""
recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
recipe.pop("_codexSecurityFileScopes", None)
return recipe
def normalized_path_component(value: str) -> str:
return normalize("NFC", normalize("NFD", value).casefold())
def relative_path(value: str) -> PurePosixPath | None:
path = PurePosixPath(value)
return None if "\\" in value or path.is_absolute() or ".." in path.parts else path
def safe_source_path(target: Path, value: str) -> Path | None:
"""Resolve a repository-relative POSIX path and return None if it is invalid or resolves outside the target."""
parsed = relative_path(value)
if parsed is None:
return None
try:
path = (target / parsed.as_posix()).resolve()
path.relative_to(target)
return path
except (OSError, RuntimeError, ValueError):
return None
def offline_git_bytes(repository: Path, *arguments: str) -> bytes | None:
"""Return raw stdout for a successful offline Git command with replacement objects disabled, otherwise None."""
result = git_command(
repository,
*arguments,
text=False,
offline=True,
environment_overrides={"GIT_NO_REPLACE_OBJECTS": "1"},
)
return result.stdout if result.returncode == 0 else None
@cache
def tree_entries(repository: Path, tree: str) -> dict[str, tuple[tuple[str, str, str], ...]] | None:
"""Index a Git tree by normalized name, retaining every original name, entry kind, and object ID in each group."""
content = offline_git_bytes(repository, "ls-tree", "-z", tree)
if content is None:
return None
entries: dict[str, list[tuple[str, str, str]]] = {}
for record in content.split(b"\0"):
if not record:
continue
metadata, separator, name = record.partition(b"\t")
fields = metadata.split(b" ")
if not separator or len(fields) != 3:
return None
mode, object_type, raw_object = fields
object_id = raw_object.decode("ascii")
if not OBJECT_ID.fullmatch(object_id):
return None
kind = (
"directory"
if mode == b"040000" and object_type == b"tree"
else "file"
if mode in {b"100644", b"100755"} and object_type == b"blob"
else "other"
)
decoded_name = os.fsdecode(name)
entries.setdefault(normalized_path_component(decoded_name), []).append(
(decoded_name, kind, object_id)
)
return {name: tuple(matches) for name, matches in entries.items()}
def exact_tree_path(repository: Path, tree: str, value: str) -> tuple[str, str, str] | None:
path = relative_path(value)
if path is None:
return None
kind, object_id = "directory", tree
for name in path.parts:
if kind != "directory":
return None
entries = tree_entries(repository, object_id) or {}
aliases = entries.get(normalized_path_component(name), ())
if len(aliases) != 1:
return None
entry_name, kind, object_id = aliases[0]
if entry_name != name:
return None
return path.as_posix(), kind, object_id
def ordinary_path(metadata: os.stat_result) -> bool:
return not (
getattr(metadata, "st_file_attributes", 0)
& getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
) and (stat.S_ISDIR(metadata.st_mode) or stat.S_ISREG(metadata.st_mode))
def filesystem_alias(selected: Path, candidate: Path) -> bool:
if normalized_path_component(selected.name) != normalized_path_component(candidate.name):
return False
try:
if not all(ordinary_path(path.lstat()) for path in (selected, candidate)):
return False
if not selected.samefile(candidate):
return False
with os.scandir(selected.parent) as entries:
return (
sum(
normalized_path_component(entry.name)
== normalized_path_component(selected.name)
for entry in entries
)
== 1
)
except OSError:
return False
def existing_tree_path(
repository: Path, tree: str, value: str, filesystem_root: Path
) -> tuple[str, str, str] | None:
path = relative_path(value)
if path is None:
return None
canonical: list[str] = []
kind, object_id = "directory", tree
for index, name in enumerate(path.parts, start=1):
if kind != "directory":
return None
entries = tree_entries(repository, object_id) or {}
aliases = entries.get(normalized_path_component(name), ())
selected = filesystem_root / PurePosixPath(*path.parts[:index])
matches = []
try:
if not ordinary_path(selected.lstat()):
return None
for entry in aliases:
candidate = filesystem_root / PurePosixPath(*canonical, entry[0])
# Every colliding Git name needs a filesystem witness. Missing
# names cannot establish which entry the user selected.
if not ordinary_path(candidate.lstat()):
return None
if selected.samefile(candidate) and (
entry[0] == name or filesystem_alias(selected, candidate)
):
matches.append(entry)
except OSError:
return None
if len(matches) != 1:
return None
name, kind, object_id = matches[0]
canonical.append(name)
return PurePosixPath(*canonical).as_posix(), kind, object_id
def target_tree(target: Path, revision: str) -> tuple[Path, str] | None:
repository, prefix = git_worktree_context(target)
raw_tree = offline_git_bytes(repository, "rev-parse", "--verify", f"{revision}^{{tree}}")
tree = raw_tree.decode("ascii").strip() if raw_tree is not None else ""
if not OBJECT_ID.fullmatch(tree):
return None
selected = existing_tree_path(repository, tree, prefix, repository)
if selected is None or selected[1] != "directory":
return None
return repository, selected[2]
def capture_source_scopes(
target: Path,
target_identity: tuple[str, str | None, int | str, int | str],
paths: list[str],
*,
diff_target_kind: str | None = None,
) -> dict[str, Any]:
"""Bind requested paths to the local Git objects that may supply excerpts later.
Return the revision and the file or tree IDs that can be verified locally.
A working-tree diff, dirty snapshot, or replacement ref leaves the scope list
empty. A path that cannot be bound adds no authority to read other paths.
"""
revision, snapshot = target_identity[:2]
result: dict[str, Any] = {"version": 1, "revision": revision, "scopes": []}
# HEAD cannot represent the uncommitted bytes reviewed by a working-tree scan.
if diff_target_kind == "working_tree":
return result
if revision == "unversioned" or (
snapshot is not None and snapshot != clean_worktree_content_digest()
):
return result
try:
repository, _ = git_worktree_context(target)
if offline_git_bytes(repository, "replace", "--list") != b"":
# A revision alone does not identify the replacement view scanned.
return result
context = target_tree(target, revision)
if context is None:
return result
repository, tree = context
result["targetTree"] = tree
for requested in paths:
selected = safe_source_path(target, requested)
if selected is None:
continue
canonical = existing_tree_path(repository, tree, requested, target)
if canonical is None or canonical[1] not in {"file", "directory"}:
continue
try:
metadata = selected.stat()
except OSError:
continue
if (canonical[1] == "directory") != stat.S_ISDIR(metadata.st_mode):
continue
result["scopes"].append(
{
"path": PurePosixPath(requested).as_posix(),
"canonicalPath": canonical[0],
"kind": canonical[1],
"objectId": canonical[2],
}
)
except (OSError, RuntimeError, SystemExit, UnicodeError, ValueError):
# Excerpts are optional. Failure to bind a scope never widens it and
# must not prevent the scan itself from starting.
pass
return result
def load_source_scopes(
scan: sqlite3.Row, target: Path, requested: list[str]
) -> tuple[Path, str, list[dict[str, str]]] | None:
"""Return the repository, tree ID, and valid source scopes, or None when none can be established.
Use saved object IDs for current records. For a legacy scan, reconstruct only
unambiguous entries from its original revision and respect any recorded file kinds.
"""
kind = scan["diff_target_kind"] if "diff_target_kind" in scan.keys() else None
if kind == "working_tree" or (
"mode" in scan.keys() and scan["mode"] == "diff" and kind not in ("commit", "range")
):
return None
saved = scan["source_scopes_json"] if "source_scopes_json" in scan.keys() else None
paths = {PurePosixPath(path).as_posix() for path in requested}
if saved is not None:
metadata = json.loads(saved)
if (
not isinstance(metadata, dict)
or metadata.get("version") != 1
or metadata.get("revision") != scan["target_revision"]
):
return None
tree = metadata.get("targetTree")
records = metadata.get("scopes")
if (
not isinstance(tree, str)
or not OBJECT_ID.fullmatch(tree)
or not isinstance(records, list)
):
return None
scopes = [
record
for record in records
if isinstance(record, dict)
and isinstance(record.get("path"), str)
and record.get("path") in paths
and isinstance(record.get("canonicalPath"), str)
and relative_path(record["canonicalPath"]) is not None
and record.get("kind") in ("file", "directory")
and isinstance(record.get("objectId"), str)
and OBJECT_ID.fullmatch(record["objectId"])
]
return (git_worktree_context(target)[0], tree, scopes) if scopes else None
# Exact, unambiguous historical entries establish legacy scope kinds.
# Keep any previously recorded file kinds as an additional constraint.
recipe = scan["recipe_json"] if "recipe_json" in scan.keys() else None
legacy_recipe = json.loads(recipe) if recipe else None
legacy_files = (
legacy_recipe.get("_codexSecurityFileScopes") if isinstance(legacy_recipe, dict) else None
)
repository, _ = git_worktree_context(target)
if offline_git_bytes(repository, "replace", "--list") != b"":
# Old records do not say which replacement view was scanned.
return None
context = target_tree(target, scan["target_revision"])
if context is None:
return None
repository, tree = context
scopes = []
for path in paths:
entry = exact_tree_path(repository, tree, path)
if entry is None or entry[1] not in {"file", "directory"}:
continue
kind = entry[1]
if isinstance(legacy_files, list) and kind != (
"file" if path in legacy_files else "directory"
):
continue
scopes.append(
{
"path": path,
"canonicalPath": path,
"kind": kind,
"objectId": entry[2],
}
)
return (repository, tree, scopes) if scopes else None
def source_object_for_path(
repository: Path, tree: str, target: Path, value: str, scope: dict[str, str]
) -> str | None:
"""Return the Git blob ID for a file covered by the recorded scope, or None if the path cannot be verified."""
path = relative_path(value)
if path is None or safe_source_path(target, value) is None:
return None
prefixes = {PurePosixPath(scope[name]).parts for name in ("path", "canonicalPath")}
suffix: tuple[str, ...] | None = None
for prefix in sorted(prefixes, key=len, reverse=True):
if path.parts[: len(prefix)] == prefix:
suffix = path.parts[len(prefix) :]
break
if suffix is None:
for length in {len(prefix) for prefix in prefixes}:
if length > len(path.parts) or scope["kind"] == "file" and length != len(path.parts):
continue
selected = existing_tree_path(
repository, tree, PurePosixPath(*path.parts[:length]).as_posix(), target
)
if selected == (scope["canonicalPath"], scope["kind"], scope["objectId"]):
suffix = path.parts[length:]
break
if suffix is None:
return None
if scope["kind"] == "file":
return scope["objectId"] if not suffix else None
relative = PurePosixPath(*suffix).as_posix()
entry = exact_tree_path(repository, scope["objectId"], relative)
if entry is None:
selected = safe_source_path(target, scope["canonicalPath"])
if selected is not None:
entry = existing_tree_path(repository, scope["objectId"], relative, selected)
return entry[2] if entry is not None and entry[1] == "file" else None
def main() -> None:
argparse.ArgumentParser(description=__doc__).parse_args()
if __name__ == "__main__":
main()
SHA-256: 2ecd66dc35c390cecbacbb8c92a444e3f2d5ce49284581fcea036a0c11450529