← Files Codex SecurityARCHIVED FILE
scripts/workbench_saved_results.py
69.8 KB · Nov 18, 2026 · 06:11 UTC
"""Retain semantic scan drafts without rerunning analysis or changing run state."""
from __future__ import annotations
import argparse
import base64
import copy
import hashlib
import json
import os
import re
import sqlite3
import sys
from collections.abc import Iterator
from contextlib import contextmanager
from pathlib import Path
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parent))
from finalize_scan_contract import (
ContractError,
ScanLocalIOError,
_populate_unsealed_artifact_envelope,
_populate_unsealed_manifest_envelope,
_prepare_scan_finalization,
_read_saved_threat_model,
_read_scan_local_json,
_read_scan_local_json_bytes,
_recover_unsealed_coverage,
_recover_unsealed_findings,
_remove_scan_local_file_if_exists,
_validate_completion_binding,
_write_prepared_scan_finalization,
finalize_scan,
manifest_is_sealed,
open_scan_local_file_descriptor,
write_scan_local_bytes,
write_threat_model_projection_if_possible,
)
from finalize_scan_contract import finding_candidate_id as finding_candidate_id
from review_state import checkpoint_review_state, review_state, review_summary, uses_legacy_review
from workbench.retained_coverage import merge_saved_results as merge_saved_results
from workbench.saved_coverage import (
_saved_coverage_id as _saved_coverage_id,
)
from workbench.saved_outputs import _restore_published_outputs, _snapshot_published_outputs
from workbench.saved_sources import (
_admit_parent_checkpoint,
_capture_saved_source,
_checkpoint_paths,
_CheckpointSnapshotError,
_encode_retained_sources,
_encoded,
_freeze_source_times,
_frozen_checkpoint_heads,
_frozen_source_times,
_is_source_order_snapshot,
_legacy_checkpoint_observed_at,
_parent_scan_draft,
_read_saved_parent_result,
_read_saved_result,
_require_current_deep_publication,
_restore_checkpoint_head,
_restore_frozen_model_capture,
_retained_checkpoint_state,
_retained_source_state,
_saved_result_paths,
_source_digests,
)
from workbench.saved_sources import (
_digest as _digest,
)
from workbench.storage import saved_deep_workers
from workbench_constants import PHASES
from workbench_coverage_receipts import (
_generic_surface_updates as _generic_surface_updates,
)
_PUBLICATION_FOLLOW_UP_WARNING = (
"Saved scan evidence remains on disk; result publication needs follow-up:"
)
_RESERVED_ARTIFACT_PATHS = json.loads(
Path(__file__).with_name("reserved_artifact_paths.json").read_text(encoding="utf-8")
)
def threat_model_fields(db: Any, scan: sqlite3.Row) -> dict[str, Any]:
"""Return availability and provenance for a saved threat model, reporting it as unavailable when verification fails."""
scan_dir = Path(scan["scan_dir"])
fields: dict[str, Any] = {"threatModelAvailable": False}
try:
db.require_recorded_manifest_digest(scan, scan_dir)
db.verify_manifest_binding(
scan, _read_scan_local_json(scan_dir, db.ARTIFACTS["manifest"], "scan manifest")
)
saved_model = _read_saved_threat_model(scan_dir)
if saved_model is not None:
description = saved_model[0]
fields.update(
threatModelAvailable=True,
threatModelProvenance=description["provenance"],
)
if description["path"] is not None:
fields["threatModelPath"] = description["path"]
except (ContractError, OSError, SystemExit):
# Unavailable optional model data must not prevent reading the saved scan.
pass
return fields
def refresh_completed_scan(
db: Any,
connection: sqlite3.Connection,
scan: sqlite3.Row,
cost_json: str | None,
) -> dict[str, Any]:
warnings = json.loads(scan["completion_warnings_json"])
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
db.require_recorded_manifest_digest(scan, scan_dir)
db.verify_manifest_binding(scan, db.read_json_object(scan_dir / db.ARTIFACTS["manifest"]))
try:
manifest, _, _ = finalize_scan(
scan_dir,
expected_coverage_mode=db.expected_coverage_mode(scan),
projection_warnings=warnings,
)
except ContractError as exc:
raise SystemExit(str(exc)) from exc
db.verify_manifest_binding(scan, manifest)
manifest_digest = db.published_manifest_digest(scan_dir, manifest)
db.pin_legacy_manifest_digest(connection, scan["id"], manifest_digest)
if cost_json is not None and scan["recipe_json"] is not None:
db.scan_usage.reconcile_completed_scan_cost(connection, scan, cost_json)
if warnings != json.loads(scan["completion_warnings_json"]):
with connection:
connection.execute(
"UPDATE scans SET completion_warnings_json = ? WHERE id = ?",
(json.dumps(warnings), scan["id"]),
)
return db.scan_context(connection, scan["id"])
def _saved_results_changed(db: Any, connection: Any, scan: Any) -> bool:
try:
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
manifest_path = db.artifact_path(scan_dir, db.ARTIFACTS["manifest"], required=False)
workers = saved_deep_workers(connection, scan)
paths = dict(_saved_result_paths(scan_dir, workers))
frozen_sources = scan["retained_source_digests_json"]
def has_saved_source() -> bool:
for path in paths:
try:
_read_saved_result(scan_dir, path, scan["id"], kind=paths[path])
return True
except (ContractError, OSError, ValueError):
continue
return False
if manifest_path is None:
if frozen_sources is not None:
return bool(_retained_source_state(frozen_sources)["sources"])
return has_saved_source()
if scan["seal_manifest_digest"] is None:
try:
_read_saved_parent_result(scan_dir, scan["id"])
return True
except (ContractError, OSError, ValueError):
pass
return has_saved_source()
manifest = _read_scan_local_json(
scan_dir,
manifest_path.relative_to(scan_dir).as_posix(),
"Saved scan manifest",
)
manifest_scan = manifest.get("scan")
if not isinstance(manifest_scan, dict):
return True
published_sources = _source_digests(
manifest_scan.get("preservedSources", {}),
"Published scan source digests are malformed.",
)
_, pending_recovery = _retained_checkpoint_state(scan)
if pending_recovery:
return True
published_heads = manifest_scan.get("preservedCheckpointHeads")
if published_heads is None:
published_heads = _frozen_checkpoint_heads(
scan_dir, scan["id"], published_sources, skip_unreadable=True
)
elif "." not in published_heads:
# Older publications recorded root observations without selecting a root head.
legacy_heads = _frozen_checkpoint_heads(
scan_dir, scan["id"], published_sources, skip_unreadable=True
)
if "." in legacy_heads:
published_heads = {**published_heads, ".": legacy_heads["."]}
checkpoint_heads = dict(published_heads)
current_sources = dict(published_sources)
paths.update({path: None for path in published_sources if _is_source_order_snapshot(path)})
for path in paths:
try:
captured = _capture_saved_source(
scan_dir,
path,
scan["id"],
kind=paths[path],
snapshot_head=path not in published_sources,
write=False,
checkpoint_heads=checkpoint_heads,
)
current_sources.update({path: value[0] for path, value in captured.items()})
directory = Path(path).parent.as_posix()
previous_head = published_heads.get(directory)
if (
Path(path).name == "checkpoint-head.json"
and previous_head in captured
and Path(previous_head).parent.name == "checkpoints"
):
observed = captured[checkpoint_heads[directory]][1]
if observed == _legacy_checkpoint_observed_at(
scan_dir, scan["id"], published_sources, previous_head
):
checkpoint_heads[directory] = previous_head
except (ContractError, OSError, ValueError):
_restore_checkpoint_head(checkpoint_heads, published_heads, published_sources, path)
return current_sources != published_sources or checkpoint_heads != published_heads
except (ContractError, OSError, SystemExit, ValueError):
return False
def _recovery_source_digests(
db: Any, connection: Any, scan: Any
) -> tuple[dict[str, str], bool, dict[str, str | None]]:
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
retained = _retained_source_state(scan["retained_source_digests_json"])
frozen_sources = retained.get("sources")
include_parent = frozen_sources is None
if retained.get("sourceTimes") is not None:
_restore_frozen_model_capture(
scan_dir,
scan["id"],
frozen_sources,
retained["sourceTimes"],
retained.get("threatModelSource"),
)
_freeze_source_times(
scan_dir,
scan["id"],
frozen_sources,
retained["sourceTimes"],
retained.get("parentContext"),
)
checkpoint_heads, pending_recovery = _retained_checkpoint_state(scan)
if pending_recovery:
return frozen_sources, False, checkpoint_heads
manifest_path = db.artifact_path(scan_dir, db.ARTIFACTS["manifest"], required=False)
if manifest_path is not None:
manifest = _read_scan_local_json(
scan_dir,
manifest_path.relative_to(scan_dir).as_posix(),
"Saved scan manifest",
)
manifest_scan = manifest.get("scan")
if not isinstance(manifest_scan, dict):
raise ContractError("Saved scan manifest has no scan object")
if scan["seal_manifest_digest"] is not None or manifest_is_sealed(manifest_scan):
if "preservedSources" in manifest_scan:
published_sources = _source_digests(
manifest_scan["preservedSources"],
"Published scan source digests are malformed.",
)
include_parent = not published_sources
if published_sources:
if frozen_sources is not None and frozen_sources != published_sources:
raise ContractError(
"Stopped scan sources changed after terminal publication."
)
frozen_sources = published_sources
elif frozen_sources is None:
frozen_sources = {}
else:
include_parent = True
workers = saved_deep_workers(connection, scan)
previous_heads = checkpoint_heads
if previous_heads is None:
previous_heads = _frozen_checkpoint_heads(scan_dir, scan["id"], frozen_sources or {})
checkpoint_heads = dict(previous_heads)
paths = dict(_saved_result_paths(scan_dir, workers))
recovery_sources = dict(frozen_sources or {})
parent_context: dict[str, str] = {}
source_times = _frozen_source_times(scan_dir, scan["id"], recovery_sources, parent_context)
for relative, expected_digest in recovery_sources.items():
try:
_, digest, observed = _read_saved_result(
scan_dir, relative, scan["id"], kind=paths.get(relative)
)
except (ContractError, OSError, ValueError) as exc:
raise ContractError("Frozen stopped-scan checkpoint set is incomplete.") from exc
if digest != expected_digest:
raise ContractError("checkpoint changed after the scan stopped")
if not _is_source_order_snapshot(relative):
source_times.setdefault(relative, observed)
snapshot_error = None
captured_records = {}
for relative in paths.keys() - recovery_sources.keys():
try:
captured = _capture_saved_source(
scan_dir,
relative,
scan["id"],
kind=paths[relative],
checkpoint_heads=checkpoint_heads,
)
except _CheckpointSnapshotError as exc:
snapshot_error = snapshot_error or exc
captured = exc.captured
captured_records.update(exc.records)
except (ContractError, OSError, ValueError):
_restore_checkpoint_head(
checkpoint_heads, previous_heads, frozen_sources or {}, relative
)
continue
if relative == "checkpoint-head.json":
parent_context["head"] = next(iter(captured))
for path, (digest, observed) in captured.items():
if path in recovery_sources and recovery_sources[path] != digest:
raise ContractError("checkpoint changed after the scan stopped")
recovery_sources[path] = digest
source_times.setdefault(path, observed)
try:
if snapshot_error is not None:
raise snapshot_error
_freeze_source_times(scan_dir, scan["id"], recovery_sources, source_times, parent_context)
except (ContractError, OSError) as exc:
failure = _CheckpointSnapshotError(
str(exc),
{
path: (digest, source_times[path])
for path, digest in recovery_sources.items()
if not _is_source_order_snapshot(path)
},
)
failure.records = captured_records
failure.heads = checkpoint_heads
failure.include_parent = include_parent
failure.parent_context = parent_context
raise failure from exc
return recovery_sources, include_parent, checkpoint_heads
def scan_results_recovery_needed(db: Any, connection: Any, scan: Any) -> bool:
"""Return whether a failed, uncanceled scan has a publication error or saved evidence to recover."""
if scan["status"] != "failed" or scan["canceled_at"] is not None:
return False
warnings = json.loads(scan["completion_warnings_json"])
if any(
isinstance(warning, str) and warning.startswith(_PUBLICATION_FOLLOW_UP_WARNING)
for warning in warnings
):
return True
publication_error = connection.execute(
"SELECT publication_error_message FROM deep_scan_runs WHERE scan_id = ?",
(scan["id"],),
).fetchone()
if publication_error is not None and publication_error["publication_error_message"]:
return True
return _saved_results_changed(db, connection, scan)
@contextmanager
def preserve_parent_head_on_error(scan_dir: Path) -> Iterator[None]:
"""Keep rejected completion attempts from becoming accepted parent observations."""
head_path = scan_dir / "checkpoint-head.json"
previous = None
try:
head_path.lstat()
except FileNotFoundError:
pass
else:
descriptor = open_scan_local_file_descriptor(
scan_dir, "checkpoint-head.json", "Saved parent checkpoint head"
)
with os.fdopen(descriptor, "rb") as handle:
metadata = os.fstat(handle.fileno())
previous = (handle.read(), metadata)
directories = ("checkpoints", "checkpoint-heads")
previous_files = {
relative for directory in directories for relative in _checkpoint_paths(scan_dir, directory)
}
try:
yield
except BaseException:
if previous is None:
_remove_scan_local_file_if_exists(scan_dir, "checkpoint-head.json")
else:
payload, metadata = previous
write_scan_local_bytes(scan_dir, "checkpoint-head.json", payload)
os.utime(head_path, ns=(metadata.st_atime_ns, metadata.st_mtime_ns))
current_files = {
relative
for directory in directories
for relative in _checkpoint_paths(scan_dir, directory)
}
for relative in current_files - previous_files:
_remove_scan_local_file_if_exists(scan_dir, relative)
raise
def coverage_for_comparison(db: Any, scan: Any) -> dict[str, Any]:
"""Return coverage from the verified, sealed scan or raise SystemExit if the stored scan cannot be matched."""
if scan["seal_manifest_digest"] is None:
raise SystemExit("Only sealed scans can be compared.")
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
db.require_recorded_manifest_digest(scan, scan_dir)
try:
prepared = _prepare_scan_finalization(scan_dir)
except ContractError as exc:
raise SystemExit(str(exc)) from exc
if not prepared.was_sealed or prepared.manifest["scan"]["id"] != scan["id"]:
raise SystemExit("Only sealed scans can be compared.")
return prepared.coverage
def preserve_deep_deadline_draft(
db: Any,
connection: Any,
scan: Any,
*,
preserve_reduction: bool = False,
allow_empty: bool = False,
) -> tuple[Path, dict[str, tuple[bytes, os.stat_result] | None], set[str]] | None:
"""Recover unfinished reviews at a settled Deep deadline without sealing the parent."""
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
warnings = json.loads(scan["completion_warnings_json"])
binding = db.workbench_completion_binding(scan, db.now())
workers = saved_deep_workers(connection, scan)
if preserve_reduction:
# Completed reviews already went through reduction. Only add evidence
# from unfinished reviews; raw accepted drafts must not undo that result.
workers = [
worker
for worker in workers
if worker["kind"] == "discovery" and worker["status"] == "canceled"
]
if not workers:
return None
_prepare_scan_finalization(
scan_dir,
expected_coverage_mode=db.expected_coverage_mode(scan),
completion_binding=binding,
allow_missing_writeups=True,
)
snapshots = _snapshot_published_outputs(
scan_dir, ("findings.json", "coverage.json", "scan-manifest.json", "checkpoint-head.json")
)
created_paths: set[str] = set()
try:
documents = merge_saved_results(
scan_dir,
scan["id"],
binding,
workers,
warnings,
stopped=not preserve_reduction,
preserve_canonical_parent=preserve_reduction,
project_worker_coverage=True,
# Without reduction, the coordinator's empty draft cannot replace worker evidence.
scan_mode="deep" if preserve_reduction else None,
finding_scope=db.requested_finding_scope(scan),
created_paths=created_paths,
current_contract=True,
reason=(
"The configured discovery time limit elapsed before any source review completed. "
"Saved findings and pending review were preserved without a completed reduction."
),
)
if documents is None:
if not allow_empty:
raise ContractError("Deep Scan deadline has no saved parent draft.")
_restore_published_outputs(scan_dir, snapshots, created_paths)
connection.execute(
"UPDATE scans SET completion_warnings_json = ? WHERE id = ?",
(json.dumps(list(dict.fromkeys(warnings))), scan["id"]),
)
return None
if preserve_reduction:
marker = {
"id": "scan-deadline",
"reason": (
"The configured discovery time limit elapsed. Saved findings and "
"pending work from unfinished source reviews were preserved."
),
}
if not any(
marker["id"] in (row.get("id"), row.get("candidateId"))
for key in ("deferred", "resolvedDeferred")
for row in documents[2].get(key, [])
):
documents[2]["deferred"].append(marker)
documents[0]["scan"].pop("complete", None)
expected_coverage_mode = db.expected_coverage_mode(scan)
if not preserve_reduction:
# A capped deadline can retain interrupted records even though its
# completion binding requires strict validation of completed findings.
_populate_unsealed_manifest_envelope(documents[0], documents[0]["scan"], binding)
_populate_unsealed_artifact_envelope(*documents, binding)
if expected_coverage_mode == "deep_repository":
documents[2]["inventoryStrategy"] = "repository"
elif expected_coverage_mode == "scoped_path":
documents[2]["inventoryStrategy"] = "scoped_path"
schema_dir = Path(__file__).resolve().parent.parent / "schemas"
discarded_findings = _recover_unsealed_findings(
documents[0], documents[1], schema_dir, scan_dir, warnings, current_contract=True
)
_recover_unsealed_coverage(
documents[2], schema_dir, scan_dir, warnings, discarded_findings
)
# Reuse stopped-result recovery's per-record validation, scope checks,
# source lineage, and receipt validation before admitting this draft.
prepared = _prepare_scan_finalization(
scan_dir,
expected_coverage_mode=expected_coverage_mode,
completion_binding=binding,
recover_unsealed=not preserve_reduction,
allow_missing_writeups=preserve_reduction,
draft_documents=documents,
finding_scope=db.requested_finding_scope(scan),
)
warnings.extend(prepared.warnings)
manifest, findings, coverage = prepared.manifest, prepared.findings, prepared.coverage
manifest["scan"].pop("sealedAt", None)
manifest["scan"].pop("artifacts", None)
manifest["scan"]["reviewState"] = checkpoint_review_state(coverage)
checkpoint = _parent_scan_draft(scan["id"], manifest["scan"], findings, coverage)
contents = _encoded(checkpoint)
name = f"{hashlib.sha256(contents).hexdigest()}.json"
checkpoint_path = f"checkpoints/{name}"
# This draft is recoverable parent evidence too. Restore its prior state
# on local publication failure or a later caller transaction rollback.
snapshots.update(_snapshot_published_outputs(scan_dir, (checkpoint_path,)))
write_scan_local_bytes(scan_dir, checkpoint_path, contents)
write_scan_local_bytes(scan_dir, "checkpoint-head.json", _encoded({"checkpoint": name}))
for filename, document in (
("findings.json", findings),
*([("coverage.json", coverage)] if "coverageRef" in manifest["scan"] else []),
("scan-manifest.json", manifest),
):
write_scan_local_bytes(scan_dir, filename, _encoded(document))
connection.execute(
"UPDATE scans SET completion_warnings_json = ? WHERE id = ?",
(json.dumps(list(dict.fromkeys(warnings))), scan["id"]),
)
except BaseException:
_restore_published_outputs(scan_dir, snapshots, created_paths)
raise
return scan_dir, snapshots, created_paths
def preserve_scan_results_locked(
db: Any,
connection: Any,
scan_id: str,
*,
recovery_source_digests: dict[str, str] | None = None,
recovery_checkpoint_heads: dict[str, str | None] | None = None,
include_parent_with_recovery: bool = False,
recovery_snapshot_error: _CheckpointSnapshotError | None = None,
) -> bool:
"""Publish or verify retained terminal results through the workbench host."""
scan = db.require_scan(connection, scan_id)
if scan["status"] != "failed":
return False
checkpoint_heads, pending_recovery = _retained_checkpoint_state(scan)
raw_frozen_sources = scan["retained_source_digests_json"]
retained = _retained_source_state(raw_frozen_sources)
frozen_source_digests = retained.get("sources")
saved_model_source = retained.get("threatModelSource")
model_source = [saved_model_source] if saved_model_source is not None else []
frozen_source_times = retained.get("sourceTimes")
canonical_sources = frozen_source_digests
if recovery_source_digests is not None:
frozen_source_digests = recovery_source_digests
checkpoint_heads = recovery_checkpoint_heads
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
if frozen_source_digests is not None:
_restore_frozen_model_capture(
scan_dir, scan_id, frozen_source_digests, frozen_source_times, saved_model_source
)
if frozen_source_times is not None and recovery_source_digests is None:
_freeze_source_times(
scan_dir,
scan_id,
frozen_source_digests,
frozen_source_times,
retained.get("parentContext"),
)
deep_run = connection.execute(
"SELECT status FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
).fetchone()
outcome = (
"canceled"
if scan["canceled_at"]
else "interrupted"
if deep_run and deep_run["status"] == "interrupted"
else "failed"
)
stored_warnings = json.loads(scan["completion_warnings_json"])
publication_follow_up_warnings = [
warning
for warning in stored_warnings
if isinstance(warning, str) and warning.startswith(_PUBLICATION_FOLLOW_UP_WARNING)
]
warnings = [
warning for warning in stored_warnings if warning not in publication_follow_up_warnings
]
def record_publication(manifest: dict[str, Any], findings: dict[str, Any]) -> None:
retained_sources = _source_digests(
manifest.get("scan", {}).get("preservedSources"),
"Stopped scan source digests could not be frozen.",
)
digest = db.published_manifest_digest(scan_dir, manifest)
timestamp = db.now()
with connection:
for kind, filename in db.ARTIFACTS.items():
path = db.artifact_path(scan_dir, filename, required=True)
connection.execute(
"INSERT OR REPLACE INTO scan_artifacts "
"(scan_id, kind, path, created_at) VALUES (?, ?, ?, ?)",
(scan_id, kind, str(path), scan["completed_at"]),
)
# Delete only vanished occurrences; stable IDs retain triage and remediation.
existing_ids = {
row["id"]
for row in connection.execute(
"SELECT id FROM finding_occurrences WHERE scan_id = ?", (scan_id,)
)
}
retained_ids = {finding["occurrenceId"] for finding in findings["findings"]}
connection.executemany(
"DELETE FROM finding_occurrences WHERE id = ? AND scan_id = ?",
((occurrence_id, scan_id) for occurrence_id in existing_ids - retained_ids),
)
db.index_findings(connection, scan_id, findings, scan["completed_at"])
connection.execute(
"UPDATE scans SET seal_manifest_digest = ?, retained_source_digests_json = ?, "
"retained_checkpoint_heads_json = ?, "
"completion_warnings_json = ?, "
"updated_at = ? WHERE id = ? AND status = 'failed'",
(
digest,
_encode_retained_sources(retained_sources, model_source),
json.dumps(
manifest["scan"].get("preservedCheckpointHeads", {}), sort_keys=True
),
json.dumps(list(dict.fromkeys(warnings))),
timestamp,
scan_id,
),
)
connection.execute(
"UPDATE scan_progress SET reportable_findings_count = ?, updated_at = ? "
"WHERE scan_id = ?",
(len(findings["findings"]), timestamp, scan_id),
)
existing_path = db.artifact_path(scan_dir, db.ARTIFACTS["manifest"], required=False)
existing_scan = db.read_json_object(existing_path).get("scan", {}) if existing_path else {}
existing = None
if scan["seal_manifest_digest"] is not None or (
isinstance(existing_scan, dict) and manifest_is_sealed(existing_scan)
):
db.require_recorded_manifest_digest(scan, scan_dir)
existing, existing_findings, _ = finalize_scan(
scan_dir,
expected_coverage_mode=db.expected_coverage_mode(scan),
projection_warnings=warnings,
)
db.verify_manifest_binding(scan, existing)
if existing_scan.get("status") == outcome:
existing_sources = existing_scan.get("preservedSources")
existing_heads = existing_scan.get("preservedCheckpointHeads")
if frozen_source_digests is None:
frozen_source_digests = _source_digests(
existing_sources, "Stopped scan source digests could not be frozen."
)
checkpoint_heads = existing_heads
unchanged = existing_sources == frozen_source_digests and (
existing_heads == checkpoint_heads
or (
"preservedCheckpointHeads" not in existing_scan
and recovery_source_digests is None
and not pending_recovery
)
)
if unchanged and not any(
Path(path).name == "checkpoint-head.json" for path in frozen_source_digests
):
if (
raw_frozen_sources is not None
and scan["seal_manifest_digest"] is not None
and not publication_follow_up_warnings
and warnings == stored_warnings
):
return True
record_publication(existing, existing_findings)
return True
if not unchanged and recovery_source_digests is None and not pending_recovery:
raise ContractError("Stopped scan sources changed after terminal publication.")
binding = {
**db.workbench_completion_binding(scan, scan["completed_at"], existing),
"status": outcome,
}
canonical_model_source = saved_model_source
canonical_model = existing_scan.get("threatModel") if isinstance(existing_scan, dict) else None
if existing is None and frozen_source_digests is not None:
# An unsealed live draft is a fallback only when its complete identity
# belongs to the frozen set. Otherwise recover from the captured sources.
canonical_model = None
try:
_, canonical_draft = _read_saved_parent_result(scan_dir, scan_id)
digest = _digest(canonical_draft)
path = f"checkpoints/{digest}.json"
if frozen_source_digests.get(path) == digest:
canonical_model_source = path
canonical_model = canonical_draft.get("threatModel")
except (ContractError, OSError, ValueError):
# This live fallback is optional.
pass
if recovery_source_digests is not None and not pending_recovery:
model_source.clear()
# Older pending recoveries retained the parent union without recording the mode.
legacy_parent = (
include_parent_with_recovery
or (pending_recovery is not None and pending_recovery.get("legacyParent", True) is True)
or (
recovery_source_digests is None
and frozen_source_digests == {}
and isinstance(existing_scan, dict)
and existing_scan.get("sealedAt") is not None
and "preservedSources" not in existing_scan
)
)
def pending_selection(heads: dict[str, str | None]) -> dict[str, Any]:
return {
"heads": heads,
"recoveryBaseDigest": scan["seal_manifest_digest"],
"legacyParent": legacy_parent,
}
try:
documents = merge_saved_results(
scan_dir,
scan_id,
binding,
saved_deep_workers(connection, scan),
warnings,
stopped=True,
scan_mode=scan["mode"],
finding_scope=db.requested_finding_scope(scan) if scan["mode"] == "deep" else None,
reason=(
f"Scan {outcome}; saved findings and pending review were preserved. "
f"{scan['failure_message'] or ''}"
).strip(),
frozen_source_digests=frozen_source_digests,
checkpoint_heads=checkpoint_heads,
frozen_model_source=model_source[0] if model_source else None,
selected_model_source=model_source,
project_worker_coverage=scan["mode"] == "deep",
canonical_model=canonical_model,
canonical_model_source=canonical_model_source,
canonical_sources=canonical_sources,
recovery_snapshot_error=recovery_snapshot_error,
allow_frozen_legacy_parent=legacy_parent,
parent_already_captured=pending_recovery is not None,
)
except _CheckpointSnapshotError as exc:
if frozen_source_digests is None or recovery_snapshot_error is not None:
# The stop has already committed. Keep the source set and times in
# the database even when auxiliary snapshot files cannot be written.
# Changed raw heads remain rejected on retry.
captured = exc.captured
retained_sources = {path: value[0] for path, value in captured.items()}
source_times = {path: value[1] for path, value in captured.items()}
retained_heads = exc.heads
if recovery_snapshot_error is not None:
_prepare_scan_finalization(
scan_dir,
expected_coverage_mode=db.expected_coverage_mode(scan),
completion_binding=binding,
recover_unsealed=True,
draft_documents=exc.documents,
finding_scope=db.requested_finding_scope(scan)
if scan["mode"] == "deep"
else None,
)
retained_heads = pending_selection(retained_heads)
with connection:
connection.execute(
"UPDATE scans SET retained_source_digests_json = ?, "
"retained_checkpoint_heads_json = ?, completion_warnings_json = ? "
"WHERE id = ? AND retained_source_digests_json IS ?",
(
_encode_retained_sources(
retained_sources, exc.model_source, source_times, exc.parent_context
),
json.dumps(retained_heads, sort_keys=True),
json.dumps(list(dict.fromkeys(warnings))),
scan_id,
raw_frozen_sources,
),
)
raise
if documents is None:
unpublished_warnings = list(dict.fromkeys([*warnings, *publication_follow_up_warnings]))
if unpublished_warnings != stored_warnings:
with connection:
connection.execute(
"UPDATE scans SET completion_warnings_json = ?, updated_at = ? "
"WHERE id = ? AND status = 'failed'",
(json.dumps(unpublished_warnings), db.now(), scan_id),
)
return False
retained_state = None
if (
frozen_source_digests is None
or scan["retained_checkpoint_heads_json"] is None
or recovery_source_digests is not None
or documents[0]["scan"]["preservedSources"] != frozen_source_digests
or model_source != ([saved_model_source] if saved_model_source is not None else [])
):
retained_sources = _source_digests(
documents[0].get("scan", {}).get("preservedSources"),
"Stopped scan source digests could not be frozen.",
)
retained_heads = documents[0]["scan"]["preservedCheckpointHeads"]
if (
recovery_source_digests is not None
or pending_recovery
or (existing is not None and existing_scan.get("status") == outcome)
):
retained_heads = pending_selection(retained_heads)
retained_state = (
_encode_retained_sources(retained_sources, model_source),
json.dumps(retained_heads, sort_keys=True),
json.dumps(list(dict.fromkeys(warnings))),
scan_id,
raw_frozen_sources,
)
def retain_sources() -> None:
if retained_state is not None:
with connection:
connection.execute(
"UPDATE scans SET retained_source_digests_json = ?, "
"retained_checkpoint_heads_json = ?, completion_warnings_json = ? "
"WHERE id = ? AND retained_source_digests_json IS ?",
retained_state,
)
first_preservation = recovery_source_digests is None and not pending_recovery
if first_preservation:
retain_sources()
prepared = _prepare_scan_finalization(
scan_dir,
expected_coverage_mode=db.expected_coverage_mode(scan),
completion_binding=binding,
recover_unsealed=True,
draft_documents=documents,
finding_scope=db.requested_finding_scope(scan) if scan["mode"] == "deep" else None,
)
if not first_preservation:
retain_sources()
warnings.extend(prepared.warnings)
snapshots = _snapshot_published_outputs(scan_dir)
try:
manifest, findings, _ = _write_prepared_scan_finalization(
prepared, projection_warnings=warnings
)
db.verify_manifest_binding(scan, manifest)
record_publication(manifest, findings)
except BaseException:
_restore_published_outputs(scan_dir, snapshots)
raise
return True
def recover_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:
"""Recover terminal results from saved checkpoints under the completion lock for a failed, uncanceled scan."""
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
if scan["status"] != "failed":
raise SystemExit("Only a stopped scan can recover terminal results.")
if scan["canceled_at"] is not None:
raise SystemExit("Canceled scans cannot recover terminal results.")
recovery_snapshot_error = None
try:
recovery_source_digests, include_parent, checkpoint_heads = _recovery_source_digests(
db, connection, scan
)
except _CheckpointSnapshotError as exc:
recovery_snapshot_error = exc
recovery_source_digests = {path: value[0] for path, value in exc.captured.items()}
include_parent = exc.include_parent
checkpoint_heads = exc.heads
if not preserve_scan_results_locked(
db,
connection,
scan_id,
recovery_source_digests=recovery_source_digests,
recovery_checkpoint_heads=checkpoint_heads,
include_parent_with_recovery=include_parent,
recovery_snapshot_error=recovery_snapshot_error,
):
raise SystemExit("No saved stopped-scan results were available to recover.")
db.deep_scan.clear_deep_scan_publication_failure(connection, scan_id)
return db.scan_context(connection, scan_id)
def preserve_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:
"""Publish results for a stopped scan under its completion lock and return the updated scan context."""
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
if scan["status"] != "failed":
raise SystemExit("Only a stopped scan can preserve terminal results.")
workspace = db.require_workspace(connection, scan["workspace_id"])
owner = (
scan["continuation_thread_id"]
or scan["deep_scan_owner_thread_id"]
or workspace["thread_id"]
)
if args.thread_id is not None and args.thread_id != owner:
raise SystemExit("Saved results can only be published from the owning Codex thread.")
if args.coordinator_generation is not None:
if args.thread_id is None:
raise SystemExit("A coordinator result refresh requires its owning thread.")
db.deep_scan.require_current_coordinator(
db.deep_scan.require_deep_scan_run(connection, scan_id), args
)
else:
db.handoff.require_current_continuation(
scan,
args.claim_token,
error_message="Saved results are owned by another continuation.",
)
published = preserve_scan_results_locked(db, connection, scan_id)
if not published and scan["canceled_at"] is not None:
raise SystemExit("Saved scan results could not be published or verified.")
if published:
db.deep_scan.clear_deep_scan_publication_failure(connection, scan_id)
return db.scan_context(connection, scan_id)
def read_or_save_artifact(args: Any) -> dict[str, Any]:
"""Read or publish supplemental bytes through verified filesystem handles."""
root = Path(args.artifact_root)
if args.command == "read-artifact":
descriptor = open_scan_local_file_descriptor(root, args.artifact_path, "Saved artifact")
with os.fdopen(descriptor, "rb") as source:
return {"content": base64.b64encode(source.read()).decode("ascii")}
write_scan_local_bytes(root, args.artifact_path, sys.stdin.buffer.read())
return {"path": str(root / args.artifact_path)}
def save_scan_artifact(db: Any, connection: Any, args: Any) -> dict[str, Any]:
"""Publish supplemental bytes under the same lock as finalization and recovery."""
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
db.handoff.require_tokenless_scan_owner(
connection, scan, getattr(args, "model_thread_id", None)
)
db.handoff.require_current_continuation(
scan,
args.claim_token,
error_message="Scan artifacts are owned by another continuation.",
)
if scan["status"] != "running" or scan["seal_manifest_digest"] is not None:
raise SystemExit("The scan stopped; its artifacts cannot be modified.")
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
manifest_path = db.artifact_path(scan_dir, "scan-manifest.json", required=False)
if manifest_path is not None:
manifest = db.read_json_object(manifest_path).get("scan", {})
if manifest_is_sealed(manifest):
raise SystemExit("The scan is sealed; its artifacts cannot be modified.")
output = args.artifact_path
key = output.lower()
if not (
key.startswith(("artifacts/", "findings/", "hardening/"))
or key == "report_validation.md"
) or any(
key == reserved or key.startswith(reserved + "/")
for reserved in _RESERVED_ARTIFACT_PATHS
):
raise SystemExit("Use the typed scan tools for canonical artifacts and checkpoints.")
write_scan_local_bytes(scan_dir, output, sys.stdin.buffer.read())
return {"scanId": scan_id, "path": str(scan_dir / output)}
def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
"""Publish a staged draft for the current continuation of a running, unsealed scan.
Read the draft from its registered scan directory and bind it to the scan
before publishing it under the completion lock. Return the scan ID, the
draft_written status, and any warning about the optional threat model.
"""
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
db.handoff.require_tokenless_scan_owner(
connection, scan, getattr(args, "model_thread_id", None)
)
db.handoff.require_current_continuation(
scan, args.claim_token, error_message="Scan draft is owned by another continuation."
)
if scan["status"] != "running" or scan["seal_manifest_digest"] is not None:
raise SystemExit(
"The scan stopped; its saved checkpoint was retained without replacing sealed results."
)
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
try:
relative = Path(args.draft_path).relative_to(scan_dir).as_posix()
except ValueError as exc:
raise SystemExit(
"Scan draft must be inside the registered scan drafts directory."
) from exc
if not re.fullmatch(r"drafts/[0-9a-fA-F-]+\.json", relative):
raise SystemExit("Scan draft must be inside the registered scan drafts directory.")
draft = _read_scan_local_json(scan_dir, relative, "Staged scan draft")
accepted_input = copy.deepcopy(draft)
accepted_checkpoint = None
manifest, findings, coverage = (
draft["manifest"],
draft["findings"],
draft.get("reviewState", draft.get("coverage")),
)
manifest["scan"]["reviewState"] = checkpoint_review_state(coverage)
manifest["scan"].pop("coverageRef", None)
binding = db.workbench_completion_binding(scan, db.now())
# Save scan IDs without sealing the draft.
_populate_unsealed_manifest_envelope(manifest, manifest["scan"], binding)
_populate_unsealed_artifact_envelope(manifest, findings, coverage, binding)
_validate_completion_binding(manifest, findings, coverage, binding)
manifest["scan"]["mode"] = coverage["mode"]
manifest["scan"]["review"] = review_summary(coverage)
projected = _parent_scan_draft(scan_id, manifest["scan"], findings, coverage)
admitted_input = None
checkpoint = manifest["scan"]
checkpoint_contents = None
if args.checkpoint_path is not None:
try:
checkpoint_relative = Path(args.checkpoint_path).relative_to(scan_dir).as_posix()
except ValueError as exc:
raise SystemExit(
"Scan checkpoint must be inside the registered scan drafts directory."
) from exc
if not re.fullmatch(r"drafts/[0-9a-fA-F-]+\.checkpoint\.json", checkpoint_relative):
raise SystemExit(
"Scan checkpoint must be inside the registered scan drafts directory."
)
checkpoint, checkpoint_contents = _read_scan_local_json_bytes(
scan_dir, checkpoint_relative, "Staged scan checkpoint"
)
accepted_checkpoint = checkpoint
if checkpoint.get("scanId") != scan_id:
raise SystemExit("Staged scan checkpoint belongs to another scan.")
if scan["mode"] == "deep":
checkpoint_contents = _admit_parent_checkpoint(
scan_dir, scan_id, checkpoint, projected
)
checkpoint_only = (
scan["mode"] == "deep"
and draft.get("deepScanPublication") is None
and checkpoint.get("complete") is False
and connection.execute(
"SELECT 1 FROM deep_scan_runs WHERE scan_id = ? "
"AND status = 'running' AND manifest_path = ?",
(scan_id, str(scan_dir / "scan-manifest.json")),
).fetchone()
is not None
)
if scan["mode"] == "deep" and not checkpoint_only:
_require_current_deep_publication(db, connection, scan, draft)
acceptance_input = {**accepted_input, "checkpoint": accepted_checkpoint}
acceptance_relative = Path(relative).with_suffix(".accepted.json").as_posix()
acknowledge = (
scan["mode"] == "deep"
and draft.get("deepScanPublication") is not None
and db.deep_scan.require_deep_scan_run(connection, scan_id)["workflow_version"]
in {"deep-scan-mcp/v1", "deep-security-scan/v1"}
)
if acknowledge and (scan_dir / acceptance_relative).exists():
accepted = _read_scan_local_json(scan_dir, acceptance_relative, "Accepted scan draft")
if (
accepted.get("status") == "draft_written"
and accepted.get("input") == acceptance_input
):
if accepted.get("draftDigest") != _scan_draft_digest(scan_dir):
raise SystemExit(
"scan_draft_conflict: canonical scan results changed after publication."
)
return {
"scanId": scan_id,
"status": "draft_written",
**({"warnings": accepted["warnings"]} if accepted.get("warnings") else {}),
}
if (
args.expected_draft_digest is not None
and args.expected_draft_digest != _scan_draft_digest(scan_dir)
):
raise SystemExit(
"scan_draft_conflict: canonical scan results changed; reconcile the saved checkpoint again."
)
if checkpoint_contents is not None:
checkpoint_digest = hashlib.sha256(checkpoint_contents).hexdigest()
if scan["mode"] == "deep":
admitted_input = f"{checkpoint_digest}.json"
write_scan_local_bytes(
scan_dir,
f"checkpoints/{checkpoint_digest}.json",
checkpoint_contents,
)
if checkpoint_only:
return {"scanId": scan_id, "status": "draft_written"}
projected_contents = _encoded(projected)
checkpoint_name = f"{hashlib.sha256(projected_contents).hexdigest()}.json"
checkpoint_relative = f"checkpoints/{checkpoint_name}"
if not (scan_dir / checkpoint_relative).exists():
write_scan_local_bytes(scan_dir, checkpoint_relative, projected_contents)
if checkpoint_only:
return {"scanId": scan_id, "status": "draft_written"}
head = {"checkpoint": checkpoint_name}
if admitted_input is not None:
head["inputCheckpoint"] = admitted_input
write_scan_local_bytes(scan_dir, "checkpoint-head.json", _encoded(head))
documents = {
filename: (json.dumps(document, allow_nan=False, indent=2) + "\n").encode()
for filename, document in (
("findings.json", findings),
("scan-manifest.json", manifest),
)
}
for filename, contents in documents.items():
write_scan_local_bytes(scan_dir, filename, contents)
_remove_scan_local_file_if_exists(scan_dir, "coverage.json")
if scan["mode"] == "deep" and manifest["scan"].get("complete") is not False:
# Select the accepted final publication before releasing the write lock.
with connection:
connection.execute(
"UPDATE deep_scan_runs SET manifest_path = ? "
"WHERE scan_id = ? AND status = 'running'",
(str(scan_dir / "scan-manifest.json"), scan_id),
)
model_warning = write_threat_model_projection_if_possible(scan_dir, manifest)
if acknowledge:
# Optional recovery evidence is written only after the publication succeeds.
try:
acceptance = {
"status": "draft_written",
"input": acceptance_input,
"draftDigest": _scan_draft_contents_digest(documents),
**({"warnings": [model_warning]} if model_warning else {}),
}
write_scan_local_bytes(scan_dir, acceptance_relative, _encoded(acceptance))
except (OSError, ScanLocalIOError):
# A missing receipt prevents recovery but does not undo accepted results.
pass
# Accepted Standard drafts are evidence of review or report assembly,
# even when the parent omitted its explicit progress call.
model_only_checkpoint = (
manifest["scan"].get("complete") is False
and isinstance(manifest["scan"].get("threatModel"), dict)
and not findings.get("findings")
and not coverage.get("surfaces")
and not coverage.get("deferred")
)
if scan["mode"] == "standard" and not model_only_checkpoint:
phase = "discovery" if manifest["scan"].get("complete") is False else "reporting"
earlier = PHASES[: PHASES.index(phase)]
placeholders = ",".join("?" for _ in earlier)
timestamp = db.now()
try:
with connection:
changed = connection.execute(
"UPDATE scans SET phase = ?, updated_at = ? "
f"WHERE id = ? AND status = 'running' AND phase IN ({placeholders})",
(phase, timestamp, scan_id, *earlier),
)
if changed.rowcount:
connection.execute(
"UPDATE scan_progress SET phase_items_total = 0, "
"phase_items_completed = 0, phase_progress_unit = NULL, updated_at = ? "
"WHERE scan_id = ?",
(timestamp, scan_id),
)
except sqlite3.Error as exc:
print(f"Could not save scan progress: {exc}", file=sys.stderr)
return {
"scanId": scan_id,
"status": "draft_written",
**({"warnings": [model_warning]} if model_warning else {}),
}
def _scan_draft_digest(scan_dir: Path) -> str:
documents: dict[str, bytes | None] = {}
for filename in ("scan-manifest.json", "findings.json", "coverage.json"):
try:
(scan_dir / filename).lstat()
except FileNotFoundError:
documents[filename] = None
continue
descriptor = open_scan_local_file_descriptor(scan_dir, filename, filename)
with os.fdopen(descriptor, "rb") as handle:
documents[filename] = handle.read()
return _scan_draft_contents_digest(documents)
def _scan_draft_contents_digest(documents: dict[str, bytes | None]) -> str:
digest = hashlib.sha256()
for filename in ("scan-manifest.json", "findings.json", "coverage.json"):
digest.update(filename.encode())
digest.update(b"\0")
contents = documents.get(filename)
if contents is None:
digest.update(b"missing\0")
else:
digest.update(b"present\0")
digest.update(contents)
digest.update(b"\0")
return digest.hexdigest()
def mark_running_scan_failed(
connection: sqlite3.Connection, scan_id: str, message: str | None, timestamp: str
) -> bool:
updated = connection.execute(
"""
UPDATE scans SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?,
log_completed_at = ?
WHERE id = ? AND status = 'running'
""",
(message, timestamp, timestamp, timestamp, scan_id),
)
return updated.rowcount == 1
def touch_scan_progress(
connection: sqlite3.Connection,
scan_id: str,
timestamp: str,
scope_file_count: int | None = None,
) -> bool:
updated = connection.execute(
"UPDATE scan_progress SET updated_at = ?, scope_file_count = COALESCE(?, scope_file_count) "
"WHERE scan_id = ?",
(timestamp, scope_file_count, scan_id),
)
return updated.rowcount == 1
def fail_scan(db: Any, connection: Any, args: Any) -> dict[str, Any]:
with db.scan_completion_lock(db.require_uuid(args.scan_id, "scan-id")):
return fail_scan_locked(db, connection, args)
def fail_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
scan_id = db.require_uuid(args.scan_id, "scan-id")
cost_json = db.parse_scan_cost(args.cost_json)
observed = db.require_scan(connection, scan_id)
scope_file_count = None
if observed["status"] == "running" and observed["mode"] == "standard":
db.handoff.require_tokenless_scan_owner(
connection, observed, getattr(args, "model_thread_id", None)
)
db.handoff.require_current_continuation(
observed,
args.claim_token,
error_message="Scan failure is owned by another continuation.",
)
scope_file_count = db.progress.reported_scope_file_count(db, observed)
connection.execute("BEGIN IMMEDIATE")
with connection:
timestamp = db.now()
scan = db.require_scan(connection, scan_id)
db.handoff.require_tokenless_scan_owner(
connection, scan, getattr(args, "model_thread_id", None)
)
if scan["status"] == "complete":
raise SystemExit("A completed scan cannot be marked failed.")
db.handoff.require_current_continuation(
scan,
args.claim_token,
error_message="Scan failure is owned by another continuation.",
)
if scan["status"] == "failed":
connection.commit()
record_stopped_scan_usage(db, connection, scan_id, cost_json)
return db.scan_context(connection, scan["id"])
message = db.optional_text(args.message)
if not mark_running_scan_failed(connection, scan_id, message, timestamp):
raise SystemExit("Only a running scan can be marked failed.")
db.deep_scan.fail_from_parent_scan(connection, scan["id"], message, timestamp)
if not touch_scan_progress(
connection,
scan_id,
timestamp,
scope_file_count if scan["scan_dir"] == observed["scan_dir"] else None,
):
raise SystemExit("Codex Security scan progress not found.")
record_stopped_scan_usage(db, connection, scan_id, cost_json)
preserve_stopped_results_after_transition(db, connection, scan["id"])
return db.scan_context(connection, scan["id"])
def cancel_scan(db: Any, connection: Any, args: Any) -> dict[str, Any]:
with db.scan_completion_lock(db.require_uuid(args.scan_id, "scan-id")):
return cancel_scan_locked(db, connection, args)
def require_cancel_owner(
db: Any, connection: Any, scan: sqlite3.Row, thread_id: str | None
) -> None:
workspace = db.require_workspace(connection, scan["workspace_id"])
owning_thread_id = scan["continuation_thread_id"] or workspace["thread_id"]
if thread_id is not None and owning_thread_id != thread_id:
raise SystemExit("A scan can only be canceled from its owning Codex thread.")
def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
scan_id = db.require_uuid(args.scan_id, "scan-id")
thread_id = db.optional_text(args.thread_id, maximum=512)
observed = db.require_scan(connection, scan_id)
scope_file_count = None
if observed["status"] == "running" and observed["mode"] == "standard":
require_cancel_owner(db, connection, observed, thread_id)
scope_file_count = db.progress.reported_scope_file_count(db, observed)
cost_json = db.parse_scan_cost(getattr(args, "cost_json", None))
# The app displays the active scan. A conversation may only receive the scan it canceled.
result_scan_id = scan_id if thread_id is not None else None
connection.execute("BEGIN IMMEDIATE")
with connection:
timestamp = db.now()
scan = db.require_scan(connection, scan_id)
require_cancel_owner(db, connection, scan, thread_id)
if scan["canceled_at"] is not None:
connection.commit()
record_stopped_scan_usage(db, connection, scan_id, cost_json)
return {
**db.workspace_state(
connection, scan["workspace_id"], result_scan_id=result_scan_id
),
"canceledScanId": scan["id"],
}
if scan["status"] != "running":
raise SystemExit("Only a running scan can be canceled.")
updated = connection.execute(
"""
UPDATE scans
SET status = 'failed', canceled_at = ?, completed_at = ?, updated_at = ?, log_completed_at = ?
WHERE id = ? AND status = 'running'
""",
(timestamp, timestamp, timestamp, timestamp, scan["id"]),
)
if updated.rowcount != 1:
raise SystemExit("Only a running scan can be canceled.")
db.deep_scan.cancel_from_parent_scan(connection, scan["id"], timestamp)
if not touch_scan_progress(
connection,
scan_id,
timestamp,
scope_file_count if scan["scan_dir"] == observed["scan_dir"] else None,
):
raise SystemExit("Codex Security scan progress not found.")
record_stopped_scan_usage(db, connection, scan_id, cost_json)
preserve_stopped_results_after_transition(db, connection, scan["id"])
return {
**db.workspace_state(connection, scan["workspace_id"], result_scan_id=result_scan_id),
"canceledScanId": scan["id"],
}
def record_stopped_scan_usage(
db: Any, connection: Any, scan_id: str, cost_json: str | None = None
) -> None:
"""Keep optional accounting independent of the already-persisted scan outcome."""
try:
scan = db.require_scan(connection, scan_id)
fields = db.scan_usage.merge_scan_usage_fields(
db.scan_usage.stored_scan_cost_fields(scan["cost_json"]),
db.scan_usage.stored_scan_cost_fields(cost_json),
)
fields = db.scan_usage.merge_scan_usage_fields(
fields,
{"usage": db.scan_usage.collect_scan_usage_safely(connection, scan)},
)
if fields:
encoded = db.parse_scan_cost(json.dumps(fields))
with connection:
connection.execute(
"UPDATE scans SET cost_json = ? WHERE id = ? AND status = 'failed'",
(encoded, scan_id),
)
except (Exception, SystemExit) as exc:
try:
print(f"Could not save stopped scan token usage: {exc}", file=sys.stderr)
except OSError:
# A closed diagnostic stream must not alter the persisted scan outcome.
pass
def preserve_stopped_results_after_transition(db: Any, connection: Any, scan_id: str) -> None:
"""Try to publish saved evidence after stopping a scan and record a warning if publication fails."""
try:
published = preserve_scan_results_locked(db, connection, scan_id)
except (ContractError, OSError, SystemExit, ValueError) as exc:
scan = db.require_scan(connection, scan_id)
warnings = json.loads(scan["completion_warnings_json"])
warning = f"Saved scan evidence remains on disk; result publication needs follow-up: {exc}"
with connection:
connection.execute(
"UPDATE scans SET completion_warnings_json = ? WHERE id = ?",
(json.dumps(list(dict.fromkeys([*warnings, warning]))), scan_id),
)
return
if published:
db.deep_scan.clear_deep_scan_publication_failure(connection, scan_id)
if __name__ == "__main__":
argparse.ArgumentParser(description=__doc__).parse_args()
def budget_exhausted_draft(
db: Any,
scan: sqlite3.Row,
scan_dir: Path,
candidates: list[dict[str, Any]],
warning: str,
) -> None:
documents: dict[str, dict[str, Any]] = {}
for name in ("scan-manifest.json", "findings.json"):
path = db.artifact_path(scan_dir, name, required=False)
if path is not None:
documents[name] = db.read_json_object(path)
if documents and len(documents) != 2:
raise SystemExit("Budget-exhausted scan contains an incomplete canonical scan draft.")
if documents:
manifest = documents["scan-manifest.json"]
findings = documents["findings.json"]
coverage = (
db.read_json_object(db.artifact_path(scan_dir, "coverage.json", required=True))
if uses_legacy_review(manifest["scan"])
else review_state(manifest["scan"])
)
if not isinstance(manifest.get("scan"), dict) or not isinstance(
findings.get("findings"), list
):
raise SystemExit("Budget-exhausted scan contains an invalid canonical scan draft.")
for key in ("surfaces", "explicitExclusions", "deferred"):
if not isinstance(coverage.get(key), list):
raise SystemExit("Budget-exhausted scan contains invalid canonical coverage.")
if manifest_is_sealed(manifest["scan"]):
raise SystemExit("Budget-exhausted scan cannot replace an already sealed scan draft.")
else:
contract = db.scan_contract(scan)
target_contract = contract["target"]
target: dict[str, Any] = {
"kind": target_contract["allowedKinds"][0],
"targetId": target_contract["targetId"],
"displayName": target_contract["displayName"],
}
if scan["target_revision"] != "unversioned":
target["revision"] = scan["target_revision"]
if "requiredSnapshotDigest" in target_contract:
target["snapshotDigest"] = target_contract["requiredSnapshotDigest"]
manifest = {
"scan": {
"target": target,
"scope": {"limitations": [warning]},
}
}
findings = {"findings": []}
coverage = {
"inventoryStrategy": (
"scoped_path" if db.expected_coverage_mode(scan) == "scoped_path" else "repository"
),
"surfaces": [],
"explicitExclusions": [],
"deferred": [],
}
findings_by_candidate = {
candidate_id
for finding in findings["findings"]
if isinstance(finding, dict)
and isinstance(candidate_id := finding_candidate_id(finding), str)
}
existing_deferred = {
item.get("candidateId", item.get("id"))
for item in coverage["deferred"]
if isinstance(item, dict) and isinstance(item.get("candidateId", item.get("id")), str)
}
existing_surfaces = {
item.get("id")
for item in coverage["surfaces"]
if isinstance(item, dict) and isinstance(item.get("id"), str)
}
for candidate in candidates:
candidate_id = candidate["candidate_id"]
if candidate_id in findings_by_candidate or candidate_id in existing_deferred:
continue
paths = list(dict.fromkeys(location["path"] for location in candidate["locations"]))
surface_id = f"candidate-{candidate_id}"
validation = candidate.get("validation")
validation = validation.get("disposition") if isinstance(validation, dict) else None
attack = candidate.get("attack_path")
attack = attack.get("decision") if isinstance(attack, dict) else None
disposition = (
"needs_follow_up"
if validation == "deferred" or attack == "deferred"
else "not_applicable"
if validation == "not_applicable"
else "rejected"
if validation == "suppressed" or attack == "ignore"
else "needs_follow_up"
)
if surface_id not in existing_surfaces:
coverage["surfaces"].append(
{
"id": surface_id,
"label": candidate["summary"],
"disposition": disposition,
"notes": candidate["evidence"],
"receiptRefs": [],
}
)
existing_surfaces.add(surface_id)
if disposition != "needs_follow_up":
continue
coverage["deferred"].append(
{
"id": candidate_id,
"candidateId": candidate_id,
"reason": (
"Validation was deferred because the scan reached its cost limit: "
f"{candidate['summary']}. Evidence: {candidate['evidence']}"
),
"paths": paths,
"surfaceIds": [surface_id],
}
)
deferred_reason = "Validation was deferred because the scan reached its cost limit."
limitations = manifest["scan"].setdefault("scope", {}).setdefault("limitations", [])
if deferred_reason not in limitations:
limitations.append(deferred_reason)
if not any(
isinstance(item, dict)
and isinstance(reason := item.get("reason"), str)
and (
reason == deferred_reason
or reason.startswith(
"Validation was deferred because the scan reached its cost limit: "
)
)
for item in coverage["deferred"]
):
coverage["deferred"].append(
{
"id": "scan-cost-limit",
"reason": deferred_reason,
}
)
coverage.pop("completeness", None)
manifest["scan"].pop("coverageRef", None)
manifest["scan"]["mode"] = db.expected_coverage_mode(scan)
manifest["scan"]["reviewState"] = checkpoint_review_state(coverage)
for name, payload in (
("findings.json", findings),
("scan-manifest.json", manifest),
):
try:
write_scan_local_bytes(
scan_dir,
name,
(json.dumps(payload, allow_nan=False, indent=2, sort_keys=True) + "\n").encode(),
)
except (ContractError, OSError, TypeError, ValueError) as exc:
raise SystemExit(f"Budget-exhausted scan draft could not be saved: {exc}") from exc
SHA-256: f0a4ac2411dd12dccce1c911e3bff5a60054a66c5d3706090661e4b1cc1bc8ea