← Files Codex SecurityARCHIVED FILE
scripts/workbench_scan_start.py
19.2 KB · Nov 18, 2026 · 06:11 UTC
"""Shared scan-start helpers for the Codex Security workbench."""
from __future__ import annotations
import argparse
import errno
import json
import os
import re
import sqlite3
import sys
import tempfile
from collections.abc import Callable, Iterator
from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
# 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
from finalize_scan_contract import write_scan_local_bytes
from workbench.storage import (
archive_source_directory,
create_private_temporary_directory,
short_archive_prefix,
state_dir,
)
from workbench_feedback import get_scan_feedback
from workbench_target import (
directory_content_digest,
git_revision,
worktree_content_digest,
)
from workbench_validation import optional_text, read_json_object
def safe_segment(value: str) -> str:
"""Normalize a filename segment, falling back to ``scan`` for an empty result."""
segment = re.sub(r"[^\w.-]", "-", value)
if segment != value:
segment = segment.strip("-")
return segment or "scan"
def compact_timestamp() -> str:
"""Return the current UTC time in YYYYMMDDTHHMMSSZ format."""
return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
def loaded_plugin_version() -> str:
"""Read the required version string from the loaded plugin's manifest."""
manifest = read_json_object(
Path(__file__).resolve().parents[1] / ".codex-plugin" / "plugin.json"
)
version = manifest.get("version")
if not isinstance(version, str) or not version:
raise SystemExit("plugin.json: expected a nonempty Codex Security plugin version.")
return version
def scan_target_identity(
target: Path,
diff_target: dict[str, str] | None,
*,
metadata: os.stat_result | None = None,
expected_digest: str | None = None,
) -> tuple[str, str | None, int | str, int | str]:
"""Return revision, content digest, device ID, and inode for scan registration.
An explicit diff uses its head revision and a None digest. Other targets use
the worktree or directory digest. Device and inode use the SQLite-safe representation.
"""
if metadata is None:
metadata = target.stat()
revision = diff_target["headRevision"] if diff_target else git_revision(target)
snapshot_digest = None
if diff_target is None:
snapshot_digest = (
directory_content_digest(target)
if revision == "unversioned"
else worktree_content_digest(target, expected_digest=expected_digest)
)
return (
revision,
snapshot_digest,
serialize_filesystem_identity(metadata.st_dev),
serialize_filesystem_identity(metadata.st_ino),
)
@dataclass(frozen=True)
class WindowsResumeTarget:
path: Path
snapshot: tuple[str, str | None, int | str, int | str]
native_id: tuple[int, int] | None
def prepare_cli_scan_target(
target: Path, diff_target: dict[str, str] | None, mode: str, launch_kind: str
) -> tuple[tuple[str, str | None, int | str, int | str], WindowsResumeTarget | None]:
if os.name == "nt" and mode in {"standard", "deep"} and launch_kind == "scan":
from windows_scan_local_files import pinned_resume_checkout
with pinned_resume_checkout(target) as native:
snapshot = scan_target_identity(target, diff_target)
return snapshot, WindowsResumeTarget(target, snapshot, native)
return scan_target_identity(target, diff_target), None
def scan_diff_identity(
diff_target: dict[str, str] | None,
) -> tuple[str | None, str | None, str | None, str | None]:
"""Return kind, base, head, and optional digest in database order, or four nulls."""
if diff_target is None:
return (None, None, None, None)
return (
diff_target["kind"],
diff_target["baseRevision"],
diff_target["headRevision"],
diff_target.get("contentDigest"),
)
def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
"""Rebuild the diff target from a scan row, or return None for a full scan."""
if not row["diff_target_kind"]:
return None
target = {
"baseRevision": row["diff_base_revision"],
"headRevision": row["diff_head_revision"],
"kind": row["diff_target_kind"],
}
if row["diff_content_digest"]:
target["contentDigest"] = row["diff_content_digest"]
return target
@contextmanager
def archive_scan(
connection: sqlite3.Connection,
args: argparse.Namespace,
scan_dir: Path,
timestamp: str,
canonical_directory: Callable[[Path], Path],
*,
before_archive: Callable[[], None] | None = None,
) -> Iterator[Path | None]:
"""Yield the archive directory while preparing the original scan path for reuse."""
archived_scan_dir = (
canonical_directory(Path(args.archived_scan_dir).expanduser())
if args.archived_scan_dir is not None
else None
)
if archived_scan_dir is not None and (
not args.archive_existing
or archived_scan_dir.parent != scan_dir.parent
or archive_source_directory(archived_scan_dir, scan_dir) != scan_dir
):
raise SystemExit("The archived scan must be a previous sibling of the scan directory.")
previous_scan = connection.execute(
"SELECT id, status FROM scans WHERE scan_dir = ?", (str(scan_dir),)
).fetchone()
if previous_scan is not None:
if not args.archive_existing:
raise SystemExit(
"The scan artifact directory belongs to an existing scan. "
"Use --archive-existing to preserve that scan and start a new one."
)
if previous_scan["status"] == "running":
raise SystemExit("Cannot archive the output of a running scan.")
has_contents = next(scan_dir.iterdir(), None) is not None
if has_contents and (not args.archive_existing or archived_scan_dir is not None):
raise SystemExit("The scan artifact directory must be empty before the scan starts.")
if previous_scan is None and not (args.archive_existing and has_contents):
yield archived_scan_dir
return
has_artifacts = (
connection.execute(
"SELECT 1 FROM scan_artifacts WHERE scan_id = ? LIMIT 1", (previous_scan["id"],)
).fetchone()
if previous_scan is not None
else None
)
moved = False
try:
if archived_scan_dir is None:
configured_state = state_dir(canonical=False)
protected_directories = [
*(path.resolve() for path in (configured_state, *configured_state.parents)),
*(
Path(row[2]).resolve().parent
for row in connection.execute("PRAGMA database_list")
if row[2]
),
]
if any(path == scan_dir or scan_dir in path.parents for path in protected_directories):
raise SystemExit(
"Cannot archive output containing the workbench state or active database."
)
if has_artifacts and not has_contents:
raise SystemExit(
"The archived scan directory is required to preserve existing scan artifacts."
)
if before_archive is not None:
before_archive()
try:
reserved = tempfile.mkdtemp(
prefix=f"{scan_dir.name}.previous-", dir=scan_dir.parent
)
except OSError as error:
if os.name != "posix" or error.errno != errno.ENAMETOOLONG:
raise
reserved = tempfile.mkdtemp(
prefix=short_archive_prefix(scan_dir.name), dir=scan_dir.parent
)
archived_scan_dir = Path(reserved).resolve()
archived_scan_dir.rmdir()
scan_dir.rename(archived_scan_dir)
moved = True
if os.name == "nt":
from windows_scan_local_files import create_directory_with_same_dacl
create_directory_with_same_dacl(scan_dir, archived_scan_dir)
else:
scan_dir.mkdir(mode=0o700)
scan_dir.chmod(0o700)
if previous_scan is not None:
connection.execute(
"UPDATE scans SET scan_dir = ?, updated_at = ? WHERE id = ?",
(str(archived_scan_dir), timestamp, previous_scan["id"]),
)
connection.execute(
"""UPDATE finding_workflows SET scan_dir = ?,
results_json = CASE WHEN json_extract(results_json, '$.scan.sarifPath') = ?
THEN json_set(results_json, '$.scan.sarifPath', ?) ELSE results_json END
WHERE scan_id = ? AND scan_dir = ?""",
(
str(archived_scan_dir),
str(scan_dir / "exports" / "results.sarif"),
str(archived_scan_dir / "exports" / "results.sarif"),
previous_scan["id"],
str(scan_dir),
),
)
def archive_path(value: str | None) -> str | None:
if value is None or not Path(value).is_relative_to(scan_dir):
return value
return str(archived_scan_dir / Path(value).relative_to(scan_dir))
connection.create_function("archive_path", 1, archive_path)
try:
for table, columns in (
("scan_artifacts", ("path",)),
("deep_scan_workers", ("prompt_path", "artifact_dir", "result_manifest_path")),
(
"deep_scan_runs",
(
"manifest_path",
"canonical_inventory_path",
"canonical_finding_report_path",
"canonical_candidates_path",
"dedupe_report_path",
"seed_research_path",
"work_ledger_path",
"raw_candidates_path",
"coverage_ledger_path",
"findings_dir",
),
),
):
assignments = ", ".join(
f"{column} = archive_path({column})" for column in columns
)
connection.execute(
f"UPDATE {table} SET {assignments} WHERE scan_id = ?",
(previous_scan["id"],),
)
finally:
connection.create_function("archive_path", 1, None)
# The caller commits registration before leaving this context. Older SDKs
# supplied an already-moved directory; only restore moves we own.
yield archived_scan_dir
except BaseException:
if moved:
if not connection.in_transaction:
current_owner = connection.execute(
"SELECT id FROM scans WHERE scan_dir = ?", (str(scan_dir),)
).fetchone()
if current_owner is not None and (
previous_scan is None or current_owner["id"] != previous_scan["id"]
):
# A post-commit interrupt must not undo the saved archive location.
raise
try:
scan_dir.rmdir()
except FileNotFoundError:
# Registration may fail before recreating the empty output directory.
pass
archived_scan_dir.rename(scan_dir)
raise
def restore_cli_scan_archive(
connection: sqlite3.Connection,
args: argparse.Namespace,
canonical_directory: Callable[[Path], Path],
) -> dict[str, str]:
supplied_scan_dir = Path(args.scan_dir).expanduser().absolute()
supplied_archive = Path(args.archived_scan_dir).expanduser().absolute()
connection.execute("BEGIN IMMEDIATE")
try:
scan_dir = supplied_scan_dir.resolve()
archived_scan_dir = supplied_archive.resolve()
archived_owner = connection.execute(
"SELECT id FROM scans WHERE scan_dir = ?", (str(archived_scan_dir),)
).fetchone()
previous_scan = connection.execute(
"SELECT id FROM scans WHERE scan_dir = ?", (str(scan_dir),)
).fetchone()
previous_scan_id = previous_scan["id"] if previous_scan is not None else None
if archived_owner is not None:
disposition = "already-recorded"
elif previous_scan_id != args.previous_scan_id:
disposition = "ownership-changed"
else:
archived_scan_dir = canonical_directory(supplied_archive)
if (
os.path.normcase(supplied_scan_dir) != os.path.normcase(scan_dir)
or archived_scan_dir.parent != scan_dir.parent
or not archived_scan_dir.name.startswith(f"{scan_dir.name}.previous-")
):
raise SystemExit(
"The archived scan must be a previous sibling of the scan directory."
)
try:
supplied_scan_dir.lstat()
except FileNotFoundError:
pass
else:
canonical_directory(supplied_scan_dir).rmdir()
archived_scan_dir.rename(scan_dir)
disposition = "restored"
connection.commit()
except BaseException:
connection.rollback()
raise
return {
"disposition": disposition,
"scanDir": str(scan_dir),
"archivedScanDir": str(archived_scan_dir),
}
@contextmanager
def register_windows_resume_output(
connection: sqlite3.Connection,
scan_id: str,
scan_dir: Path,
target: WindowsResumeTarget,
before_create: Callable[[], None],
) -> Iterator[None]:
from windows_scan_local_files import create_deep_resume_output, pinned_resume_checkout
def committed() -> bool:
# A signal can arrive after commit. The registered scan then owns its child.
return (
not connection.in_transaction
and connection.execute("SELECT 1 FROM scans WHERE id = ?", (scan_id,)).fetchone()
is not None
)
with pinned_resume_checkout(target.path) as current:
if current != target.native_id or (
current is None and scan_target_identity(target.path, None) != target.snapshot
):
raise SystemExit(
"The selected scan target changed while the scan was starting. Try again."
)
before_create()
with create_deep_resume_output(scan_dir, committed) as identity:
connection.execute(
"UPDATE scans SET windows_resume_output_identity = ?, windows_resume_target_identity = ? WHERE id = ?",
(
json.dumps(identity),
json.dumps(target.native_id) if target.native_id is not None else None,
scan_id,
),
)
yield
def insert_running_scan(
connection: sqlite3.Connection,
*,
scan_id: str,
workspace: sqlite3.Row,
target: Path,
scope: str,
diff_target: dict[str, str] | None,
target_identity: tuple[str, str | None, int | str, int | str],
repository_generation: str | None,
source_scopes: dict[str, Any],
target_root: Path,
target_summary: str | None,
scope_file_count: int | None,
timestamp: str,
handoff_status: str = "pending",
model: str | None = None,
reasoning_effort: str | None = None,
scan_dir: Path | None = None,
surface: str | None = "plugin",
package_version: str | None = None,
launch_kind: str = "scan",
hosted: bool = False,
) -> str:
revision = target_identity[0]
native_scan = scan_dir is None
user_context = optional_text(workspace["user_context"])
try:
plugin_version = loaded_plugin_version()
except SystemExit:
# Missing version attribution must not prevent scan registration.
plugin_version = None
if scan_dir is None:
scan_dir = create_private_temporary_directory(
target_root,
prefix=f"{safe_segment(revision)}_{compact_timestamp()}_",
)
connection.execute(
"""
INSERT INTO scans (
id, workspace_id, target_id, repository_generation, target_path,
target_revision, target_snapshot_digest,
target_device, target_inode, source_scopes_json, scope, mode, user_context,
deep_scan_owner_thread_id, diff_target_kind, diff_base_revision,
diff_head_revision, diff_content_digest, target_summary, scan_dir, model,
reasoning_effort, status, phase, handoff_status, started_at, created_at, updated_at,
launch_surface, launch_package_version, launch_plugin_version, launch_kind
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
'running', ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
scan_id,
workspace["id"],
workspace["target_id"],
repository_generation,
str(target),
*target_identity,
json.dumps(source_scopes, allow_nan=False, separators=(",", ":"), sort_keys=True),
scope,
workspace["default_mode"],
user_context,
workspace["thread_id"] if workspace["default_mode"] == "deep" else None,
*scan_diff_identity(diff_target or None),
target_summary,
str(scan_dir),
optional_text(model, maximum=200),
optional_text(reasoning_effort, maximum=32),
"threat_model"
if not hosted
and launch_kind == "scan"
and workspace["default_mode"] == "standard"
and handoff_status == "delivered"
else "preflight",
handoff_status,
timestamp,
timestamp,
timestamp,
surface,
package_version,
plugin_version,
launch_kind,
),
)
connection.execute(
"""
INSERT INTO scan_progress (
scan_id, scope_file_count, review_items_total, review_items_completed,
reportable_findings_count, updated_at
) VALUES (?, ?, 0, 0, 0, ?)
""",
(scan_id, scope_file_count, timestamp),
)
connection.execute(
"UPDATE workspaces SET active_scan_id = ?, updated_at = ? WHERE id = ?",
(scan_id, timestamp, workspace["id"]),
)
if native_scan:
scan = next(connection.execute("SELECT * FROM scans WHERE id = ?", (scan_id,)))
false_positives = get_scan_feedback(connection, scan)["falsePositives"]
if false_positives:
write_scan_local_bytes(
scan_dir,
"artifacts/01_context/false_positive_feedback.json",
(json.dumps(false_positives, allow_nan=False) + "\n").encode(),
)
return scan_id
if __name__ == "__main__":
argparse.ArgumentParser(description=__doc__).parse_args()
SHA-256: 1ee02b3ff745b0926330c993757448be7b813067642abbdf024352b32ad1fd6e