← Files Codex SecurityARCHIVED FILE
scripts/workbench_source_excerpt.py
5.08 KB · Nov 18, 2026 · 06:11 UTC
"""Read bounded finding source excerpts from sealed Git revisions."""
from __future__ import annotations
import argparse
import sqlite3
import sys
from pathlib import Path, PurePosixPath
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parent))
from workbench_source_scopes import (
load_source_scopes,
normalized_path_component,
offline_git_bytes,
relative_path,
safe_source_path,
source_object_for_path,
)
from workbench_target import clean_worktree_content_digest
CONTEXT_LINES = 3
MAX_BYTES = 16_000
MAX_LINES = 60
def finding_source_excerpt(
scan: sqlite3.Row,
target: Path | None,
locations: list[dict[str, Any]],
scopes: list[str],
) -> str | None:
"""Return numbered context from a finding location at the scanned Git revision.
Args:
scan: Saved scan row with its revision, snapshot digest, and scope metadata.
target: Local target directory in which to resolve the recorded Git objects.
locations: Displayed finding locations, using one-based line numbers.
scopes: Selected paths used to interpret saved source scopes.
Returns:
A bounded excerpt, or None when a location, scope, or local blob cannot
supply it. Root-control locations have priority.
"""
if target is None or not locations or scan["target_revision"] == "unversioned":
return None
snapshot = scan["target_snapshot_digest"]
if snapshot is not None and snapshot != clean_worktree_content_digest():
return None
locations = [
location
for location in locations
if isinstance(path := location.get("path"), str)
and isinstance(location.get("startLine"), int)
and safe_source_path(target, path) is not None
]
if not locations:
return None
try:
context = load_source_scopes(scan, target, scopes)
except (OSError, RuntimeError, SystemExit, UnicodeError, ValueError):
return None
if context is None:
return None
repository, tree, records = context
indexed: dict[tuple[str, ...], list[dict[str, str]]] = {}
for record in records:
for name in ("path", "canonicalPath"):
parts = tuple(
normalized_path_component(part) for part in PurePosixPath(record[name]).parts
)
indexed.setdefault(parts, []).append(record)
lengths = sorted({len(parts) for parts in indexed})
def source_object(path: str) -> str | None:
parsed = relative_path(path)
if parsed is None:
return None
parts = tuple(normalized_path_component(part) for part in parsed.parts)
try:
for length in lengths:
if length > len(parts):
break
for record in indexed.get(parts[:length], []):
object_id = source_object_for_path(repository, tree, target, path, record)
if object_id is not None:
return object_id
except (OSError, RuntimeError, SystemExit, UnicodeError, ValueError):
# An unavailable source object leaves the optional excerpt absent.
pass
return None
locations.sort(
key=lambda location: (
location.get("role") != "root_control",
"root_control" not in str(location.get("role") or "").lower(),
)
)
for location in locations:
object_id = source_object(location["path"])
if object_id is not None:
break
else:
return None
start_line, end_line = location["startLine"], location.get("endLine")
source = scanned_source_text(repository, object_id)
if not source or "\0" in source:
return None
# Match location validation and SARIF hashing: CR, LF, and CRLF are line breaks.
# Keep form feeds and Unicode separators within their original source lines.
normalized = source.replace("\r\n", "\n").replace("\r", "\n")
lines = normalized.removesuffix("\n").split("\n")
if start_line < 1 or start_line > len(lines):
return None
last_affected_line = end_line if isinstance(end_line, int) else start_line
excerpt_start = max(1, start_line - CONTEXT_LINES)
excerpt_end = min(
len(lines),
max(start_line, last_affected_line) + CONTEXT_LINES,
excerpt_start + MAX_LINES - 1,
)
width = len(str(excerpt_end))
excerpt = "\n".join(
f"{line_number:>{width}} {lines[line_number - 1]}"
for line_number in range(excerpt_start, excerpt_end + 1)
)
return excerpt.encode("utf-8")[:MAX_BYTES].decode("utf-8", errors="ignore")
def scanned_source_text(repository: Path, object_id: str) -> str | None:
"""Decode the locally available Git blob as UTF-8 with replacement, or return None on lookup failure."""
try:
content = offline_git_bytes(repository, "cat-file", "blob", object_id)
except (OSError, RuntimeError, SystemExit):
return None
return content.decode("utf-8", errors="replace") if content is not None else None
if __name__ == "__main__":
argparse.ArgumentParser(description=__doc__).parse_args()
SHA-256: 97667580f629597a284939ff60e137af3526e217165a7946de2420f19ea489d7