@openai/codex-security 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +44 -14
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/references/core-scan.md +1 -1
  6. package/_bundled_plugin/references/final-report.md +4 -2
  7. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  8. package/_bundled_plugin/references/scan-contract.md +18 -7
  9. package/_bundled_plugin/schemas/scan-manifest.schema.json +2 -2
  10. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +23 -0
  11. package/_bundled_plugin/scripts/deep_scan_workbench.py +88 -1
  12. package/_bundled_plugin/scripts/finalize_scan_contract.py +58 -18
  13. package/_bundled_plugin/scripts/report_projection.py +19 -8
  14. package/_bundled_plugin/scripts/workbench_cli.py +13 -0
  15. package/_bundled_plugin/scripts/workbench_db.py +149 -167
  16. package/_bundled_plugin/scripts/workbench_finding_index.py +101 -0
  17. package/_bundled_plugin/scripts/workbench_remediation.py +19 -0
  18. package/_bundled_plugin/scripts/workbench_saved_results.py +1289 -0
  19. package/_bundled_plugin/scripts/workbench_schema.py +28 -0
  20. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +4 -4
  21. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  22. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  23. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  24. package/dist/api.d.ts +2 -0
  25. package/dist/api.d.ts.map +1 -1
  26. package/dist/api.js +54 -7
  27. package/dist/api.js.map +1 -1
  28. package/dist/cli.d.ts.map +1 -1
  29. package/dist/cli.js +13 -0
  30. package/dist/cli.js.map +1 -1
  31. package/dist/custom-validation-prompt.js +3 -3
  32. package/dist/custom-validation-prompt.js.map +1 -1
  33. package/dist/models.d.ts +1 -1
  34. package/dist/models.d.ts.map +1 -1
  35. package/dist/models.js.map +1 -1
  36. package/package.json +2 -2
@@ -0,0 +1,1289 @@
1
+ """Retain semantic scan drafts without rerunning analysis or changing run state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import copy
7
+ import hashlib
8
+ import json
9
+ import os
10
+ import re
11
+ import stat
12
+ import sys
13
+ from collections.abc import Callable, Iterator
14
+ from dataclasses import dataclass
15
+ from pathlib import Path
16
+ from types import ModuleType
17
+ from typing import Any
18
+
19
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
20
+ from finalize_scan_contract import (
21
+ ContractError,
22
+ _finding_strength,
23
+ _populate_unsealed_artifact_envelope,
24
+ _populate_unsealed_manifest_envelope,
25
+ _prepare_scan_finalization,
26
+ _read_scan_local_json,
27
+ _read_scan_local_json_bytes,
28
+ _recover_unsealed_findings,
29
+ _remove_scan_local_file_if_exists,
30
+ _validate_completion_binding,
31
+ _write_prepared_scan_finalization,
32
+ finalize_scan,
33
+ finding_candidate_id,
34
+ open_scan_local_file_descriptor,
35
+ write_scan_local_bytes,
36
+ )
37
+ from workbench_validation import path_within_scope
38
+
39
+ _PUBLISHED_OUTPUTS = (
40
+ "findings.json",
41
+ "coverage.json",
42
+ "scan-manifest.json",
43
+ "report.md",
44
+ "report.html",
45
+ "exports/results.sarif",
46
+ )
47
+ _PUBLICATION_FOLLOW_UP_WARNING = (
48
+ "Saved scan evidence remains on disk; result publication needs follow-up:"
49
+ )
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class WorkbenchDbContext:
54
+ ARTIFACTS: dict[str, str]
55
+ artifact_path: Callable[..., Path | None]
56
+ deep_scan: ModuleType
57
+ expected_coverage_mode: Callable[..., str]
58
+ handoff: ModuleType
59
+ index_findings: Callable[..., None]
60
+ now: Callable[[], str]
61
+ optional_text: Callable[..., str | None]
62
+ parse_scan_cost: Callable[..., dict[str, Any] | None]
63
+ published_manifest_digest: Callable[..., str]
64
+ read_json_object: Callable[[Path], dict[str, Any]]
65
+ require_canonical_scan_directory: Callable[[Path], Path]
66
+ require_recorded_manifest_digest: Callable[..., None]
67
+ require_scan: Callable[..., Any]
68
+ require_uuid: Callable[[str, str], str]
69
+ require_workspace: Callable[..., Any]
70
+ scan_completion_lock: Callable[..., Any]
71
+ scan_context: Callable[..., dict[str, Any]]
72
+ verify_manifest_binding: Callable[..., None]
73
+ workbench_completion_binding: Callable[..., dict[str, Any]]
74
+ workspace_state: Callable[..., dict[str, Any]]
75
+
76
+
77
+ def _encoded(value: Any) -> bytes:
78
+ return json.dumps(
79
+ value, ensure_ascii=True, allow_nan=False, sort_keys=True, separators=(",", ":")
80
+ ).encode()
81
+
82
+
83
+ def _digest(value: Any) -> str:
84
+ return hashlib.sha256(_encoded(value)).hexdigest()
85
+
86
+
87
+ def _children(scan_dir: Path, relative: str) -> list[str]:
88
+ cursor = scan_dir
89
+ for part in Path(relative).parts:
90
+ if part in {"..", "."}:
91
+ return []
92
+ cursor = cursor / part
93
+ try:
94
+ if not stat.S_ISDIR(cursor.lstat().st_mode):
95
+ return []
96
+ except FileNotFoundError:
97
+ return []
98
+ return sorted(child.name for child in cursor.iterdir())
99
+
100
+
101
+ def _finding_key(finding: dict[str, Any]) -> str:
102
+ # Wording and evidence may improve between checkpoints; distinct source locations
103
+ # must not collide merely because two workers chose the same semantic identity.
104
+ provenance = finding.get("provenance")
105
+ identity = (
106
+ provenance.get("preservedIdentity", finding.get("identity"))
107
+ if isinstance(provenance, dict)
108
+ else finding.get("identity")
109
+ )
110
+ if not isinstance(identity, dict):
111
+ extensions = finding.get("extensions")
112
+ source = str(
113
+ (extensions.get("candidateId") if isinstance(extensions, dict) else None)
114
+ or finding.get("title")
115
+ or "finding"
116
+ )
117
+ identity = {
118
+ "anchor": re.sub(r"[^a-z0-9._/-]+", "-", source.lower()).strip("._/-") or "finding"
119
+ }
120
+ locations = finding.get("locations", [])
121
+ if not isinstance(locations, list):
122
+ locations = []
123
+ return _digest(
124
+ [
125
+ finding.get("ruleId"),
126
+ identity,
127
+ sorted(
128
+ (
129
+ (
130
+ location.get("path"),
131
+ location.get("startLine"),
132
+ location.get("endLine", location.get("startLine")),
133
+ )
134
+ for location in locations
135
+ if isinstance(location, dict)
136
+ ),
137
+ key=_encoded,
138
+ ),
139
+ ]
140
+ )
141
+
142
+
143
+ def _worker_candidate_key(
144
+ worker_id: str, candidate_id: str, finding: dict[str, Any]
145
+ ) -> tuple[str, str, Any, Any, Any]:
146
+ """Identify one worker-local candidate without merging unrelated locations."""
147
+ provenance = finding.get("provenance")
148
+ identity = (
149
+ provenance.get("preservedIdentity", finding.get("identity"))
150
+ if isinstance(provenance, dict)
151
+ else finding.get("identity")
152
+ )
153
+ anchor = identity.get("anchor") if isinstance(identity, dict) else None
154
+ instance = identity.get("instance") if isinstance(identity, dict) else None
155
+ return worker_id, candidate_id, finding.get("ruleId"), anchor, instance
156
+
157
+
158
+ def _finding_content(finding: dict[str, Any]) -> dict[str, Any]:
159
+ """Return substantive finding content without generated identity or provenance."""
160
+ return {
161
+ key: value
162
+ for key, value in finding.items()
163
+ if key not in {"findingId", "occurrenceId", "fingerprints", "identity", "provenance"}
164
+ }
165
+
166
+
167
+ def _ensure_finding_identity(finding: Any, *, candidate_only: bool = False) -> None:
168
+ if not isinstance(finding, dict) or "identity" in finding:
169
+ return
170
+ if candidate_only and not finding_candidate_id(finding):
171
+ return
172
+ extensions = finding.get("extensions")
173
+ source = str(
174
+ (extensions.get("candidateId") if isinstance(extensions, dict) else None)
175
+ or finding.get("title")
176
+ or "finding"
177
+ )
178
+ anchor = re.sub(r"[^a-z0-9._/-]+", "-", source.lower()).strip("._/-") or "finding"
179
+ finding["identity"] = {"anchor": anchor}
180
+
181
+
182
+ def _retained_findings(finding: dict[str, Any]) -> Iterator[dict[str, Any]]:
183
+ """Yield canonical and historical findings without trusting candidate IDs."""
184
+ pending = [finding]
185
+ seen: set[int] = set()
186
+ while pending:
187
+ current = pending.pop()
188
+ marker = id(current)
189
+ if marker in seen:
190
+ continue
191
+ seen.add(marker)
192
+ yield current
193
+ provenance = current.get("provenance")
194
+ if not isinstance(provenance, dict):
195
+ continue
196
+ previous = provenance.get("previousFindings")
197
+ if isinstance(previous, list):
198
+ pending.extend(item for item in reversed(previous) if isinstance(item, dict))
199
+ sources = provenance.get("sourceFindings")
200
+ if isinstance(sources, list):
201
+ pending.extend(
202
+ source["finding"]
203
+ for source in reversed(sources)
204
+ if isinstance(source, dict) and isinstance(source.get("finding"), dict)
205
+ )
206
+
207
+
208
+ def merge_saved_results(
209
+ scan_dir: Path,
210
+ scan_id: str,
211
+ binding: dict[str, Any],
212
+ workers: list[Any],
213
+ warnings: list[str],
214
+ *,
215
+ stopped: bool,
216
+ reason: str,
217
+ frozen_source_digests: dict[str, str] | None = None,
218
+ ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:
219
+ """Read only bound parent/worker files; return an unsealed loss-preserving union."""
220
+ initial_warnings = set(warnings)
221
+ parent: dict[str, Any] | None = None
222
+ parent_manifest: dict[str, Any] | None = None
223
+ if frozen_source_digests is None:
224
+ try:
225
+ parent_manifest = _read_scan_local_json(
226
+ scan_dir, "scan-manifest.json", "Saved parent manifest"
227
+ )
228
+ parent_findings = _read_scan_local_json(
229
+ scan_dir, "findings.json", "Saved parent findings"
230
+ )
231
+ parent_coverage = _read_scan_local_json(
232
+ scan_dir, "coverage.json", "Saved parent coverage"
233
+ )
234
+ parent_scan = parent_manifest.get("scan")
235
+ if not isinstance(parent_scan, dict):
236
+ raise ContractError("Saved parent manifest has no scan object")
237
+ if (parent_scan.get("sealedAt") or parent_scan.get("artifacts")) and (
238
+ parent_scan.get("id", scan_id) != scan_id
239
+ or parent_findings.get("scanId", scan_id) != scan_id
240
+ or parent_coverage.get("scanId", scan_id) != scan_id
241
+ ):
242
+ raise ContractError("Saved parent documents belong to a different scan")
243
+ parent = {
244
+ "scanId": scan_id,
245
+ "findings": parent_findings.get("findings"),
246
+ "coverage": parent_coverage,
247
+ **{
248
+ key: parent_scan[key]
249
+ for key in ("scope", "threatModel", "complete")
250
+ if key in parent_scan
251
+ },
252
+ }
253
+ if not isinstance(parent["findings"], list):
254
+ raise ContractError("Saved parent draft has no findings array")
255
+ if not parent_scan.get("sealedAt"):
256
+ payload = _encoded(parent)
257
+ write_scan_local_bytes(
258
+ scan_dir,
259
+ f"checkpoints/{hashlib.sha256(payload).hexdigest()}.json",
260
+ payload,
261
+ )
262
+ except (ContractError, OSError, ValueError) as exc:
263
+ if not stopped:
264
+ raise
265
+ if (scan_dir / "scan-manifest.json").exists():
266
+ warnings.append(f"Could not read the saved parent draft: {exc}")
267
+ parent_manifest = None
268
+ parent = None
269
+
270
+ sources: list[tuple[str, dict[str, Any], str | None]] = []
271
+ parent_preserved_sources: dict[str, str] = {}
272
+ source_digests: dict[str, str] = {}
273
+ if parent_manifest:
274
+ recorded = parent_manifest["scan"].get("preservedSources", {})
275
+ if isinstance(recorded, dict):
276
+ parent_preserved_sources = recorded
277
+ source_digests.update(parent_preserved_sources)
278
+ paths: dict[str, str | None] = {}
279
+ current_results: set[str] = set()
280
+ reducer_outputs: list[tuple[Any, str, list[str], int]] = []
281
+ accepted_reducers = [
282
+ worker
283
+ for worker in workers
284
+ if worker["kind"] == "dedup"
285
+ and worker["status"] == "succeeded"
286
+ and worker["result_manifest_path"]
287
+ ]
288
+ latest_reducer: str | None = None
289
+ if accepted_reducers:
290
+ reducer = max(
291
+ accepted_reducers, key=lambda worker: (worker["completed_at"] or "", worker["id"])
292
+ )
293
+ try:
294
+ latest_reducer = Path(reducer["result_manifest_path"]).relative_to(scan_dir).as_posix()
295
+ paths[latest_reducer] = None
296
+ except ValueError:
297
+ warnings.append("Skipped a reducer result outside the scan directory.")
298
+
299
+ def checkpoints(directory: str, worker_id: str | None) -> None:
300
+ for name in _children(scan_dir, directory):
301
+ if re.fullmatch(r"[0-9a-f]{64}\.json", name):
302
+ paths[f"{directory}/{name}"] = worker_id
303
+
304
+ checkpoints("checkpoints", None)
305
+ for worker in workers:
306
+ try:
307
+ output = Path(worker["artifact_dir"]).relative_to(scan_dir).as_posix()
308
+ except (TypeError, ValueError):
309
+ warnings.append("Skipped a worker checkpoint outside the scan directory.")
310
+ continue
311
+ if worker["kind"] == "dedup":
312
+
313
+ def reducer_output(directory: str, attempt: int, reducer_worker: Any) -> None:
314
+ result_path = f"{directory}/result.json"
315
+ checkpoint_paths = [
316
+ f"{directory}/checkpoints/{name}"
317
+ for name in _children(scan_dir, f"{directory}/checkpoints")
318
+ if re.fullmatch(r"[0-9a-f]{64}\.json", name)
319
+ ]
320
+ if not checkpoint_paths:
321
+ return
322
+ paths[result_path] = None
323
+ for checkpoint_path in checkpoint_paths:
324
+ paths[checkpoint_path] = None
325
+ reducer_outputs.append((reducer_worker, result_path, checkpoint_paths, attempt))
326
+
327
+ reducer_output(output, int(worker["attempt"] or 0), worker)
328
+ attempts = (
329
+ Path(output).parent if Path(output).name == "output" else Path(output)
330
+ ) / "attempts"
331
+ for name in _children(scan_dir, attempts.as_posix()):
332
+ match = re.fullmatch(r"attempt-(\d+)", name)
333
+ if match:
334
+ reducer_output((attempts / name).as_posix(), int(match.group(1)), worker)
335
+ continue
336
+ if worker["kind"] != "discovery":
337
+ continue
338
+ paths[f"{output}/result.json"] = worker["id"]
339
+ current_results.add(f"{output}/result.json")
340
+ checkpoints(f"{output}/checkpoints", worker["id"])
341
+ attempts = (
342
+ Path(output).parent if Path(output).name == "output" else Path(output)
343
+ ) / "attempts"
344
+ for name in _children(scan_dir, attempts.as_posix()):
345
+ if re.fullmatch(r"attempt-\d+", name):
346
+ archived = (attempts / name).as_posix()
347
+ paths[f"{archived}/result.json"] = worker["id"]
348
+ checkpoints(f"{archived}/checkpoints", worker["id"])
349
+ if worker["result_manifest_path"]:
350
+ try:
351
+ current_path = Path(worker["result_manifest_path"]).relative_to(scan_dir).as_posix()
352
+ paths[current_path] = worker["id"]
353
+ current_results.add(current_path)
354
+ except ValueError:
355
+ warnings.append("Skipped a worker result outside the scan directory.")
356
+
357
+ if frozen_source_digests is not None:
358
+ paths = {
359
+ relative: worker_id
360
+ for relative, worker_id in paths.items()
361
+ if relative in frozen_source_digests
362
+ }
363
+ current_results.intersection_update(frozen_source_digests)
364
+ if latest_reducer not in frozen_source_digests:
365
+ latest_reducer = None
366
+
367
+ for relative, worker_id in paths.items():
368
+ try:
369
+ draft = _read_scan_local_json(scan_dir, relative, "Saved scan checkpoint")
370
+ if draft.get("scanId") != scan_id:
371
+ raise ContractError("checkpoint belongs to a different scan")
372
+ if not isinstance(draft.get("findings"), list) or not isinstance(
373
+ draft.get("coverage"), dict
374
+ ):
375
+ raise ContractError("checkpoint has no semantic findings or coverage")
376
+ digest = _digest(draft)
377
+ if frozen_source_digests is not None and frozen_source_digests[relative] != digest:
378
+ raise ContractError("checkpoint changed after the scan stopped")
379
+ source_digests[relative] = digest
380
+ sources.append((relative, draft, worker_id))
381
+ except (ContractError, OSError, ValueError) as exc:
382
+ if (scan_dir / relative).exists():
383
+ warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
384
+ if frozen_source_digests is not None:
385
+ if frozen_source_digests.keys() - source_digests.keys():
386
+ raise ContractError("Frozen stopped-scan checkpoint set is incomplete.")
387
+
388
+ drafts_by_path = {relative: draft for relative, draft, _ in sources}
389
+ latest_reducer_key = (
390
+ (reducer["completed_at"] or "", reducer["id"], int(reducer["attempt"] or 0))
391
+ if accepted_reducers and latest_reducer in drafts_by_path
392
+ else None
393
+ )
394
+ if latest_reducer_key is None:
395
+ latest_reducer = None
396
+ for worker, result_path, checkpoint_paths, attempt in reducer_outputs:
397
+ result = drafts_by_path.get(result_path)
398
+ if result is None or not any(
399
+ drafts_by_path.get(checkpoint_path) == result for checkpoint_path in checkpoint_paths
400
+ ):
401
+ continue
402
+ current_results.add(result_path)
403
+ candidate_key = (worker["completed_at"] or "", worker["id"], attempt)
404
+ if latest_reducer_key is None or candidate_key > latest_reducer_key:
405
+ latest_reducer_key = candidate_key
406
+ latest_reducer = result_path
407
+
408
+ if parent is None and latest_reducer is not None:
409
+ parent = next((draft for relative, draft, _ in sources if relative == latest_reducer), None)
410
+
411
+ if parent is None and not sources:
412
+ return None
413
+ if (
414
+ parent_manifest
415
+ and parent_manifest["scan"].get("sealedAt")
416
+ and parent_manifest["scan"].get("status") == binding["status"]
417
+ and parent_manifest["scan"].get("preservedSources") == source_digests
418
+ and all(warning in initial_warnings for warning in warnings)
419
+ ):
420
+ return None
421
+
422
+ target_kind = binding["allowedTargetKinds"][0]
423
+ if (
424
+ target_kind == "git_worktree"
425
+ and "snapshotDigest" not in binding["target"]
426
+ and "git_revision" in binding["allowedTargetKinds"]
427
+ ):
428
+ target_kind = "git_revision"
429
+ target = {"kind": target_kind, **binding["target"]}
430
+ if target["kind"] == "git_diff" and "snapshotDigest" not in target:
431
+ diff_kind = {"commit": "commit", "branch_diff": "range"}[binding["coverageMode"]]
432
+ digest = hashlib.sha256(
433
+ b"codex-security-diff/v1\0"
434
+ + diff_kind.encode()
435
+ + b"\0"
436
+ + target["baseRevision"].encode()
437
+ + b"\0"
438
+ + target["headRevision"].encode()
439
+ ).hexdigest()
440
+ target["snapshotDigest"] = f"codex-security-snapshot/v1:sha256:{digest}"
441
+ manifest = (
442
+ copy.deepcopy(parent_manifest)
443
+ if parent_manifest
444
+ else {"scan": {"target": target, "scope": binding["scope"]}}
445
+ )
446
+ for key in ("sealedAt", "artifacts"):
447
+ manifest["scan"].pop(key, None)
448
+ manifest["scan"]["preservedSources"] = source_digests
449
+ coverage = (
450
+ copy.deepcopy(parent["coverage"])
451
+ if parent
452
+ else {
453
+ "completeness": "partial",
454
+ "mode": binding["coverageMode"],
455
+ "inventoryStrategy": "diff"
456
+ if binding["coverageMode"] in {"commit", "branch_diff", "working_tree"}
457
+ else "scoped_path"
458
+ if binding["coverageMode"] == "scoped_path"
459
+ else "repository",
460
+ **binding["scope"],
461
+ "surfaces": [],
462
+ "explicitExclusions": [],
463
+ "deferred": [],
464
+ }
465
+ )
466
+ canonical_rows = (
467
+ {
468
+ id(item)
469
+ for field in ("surfaces", "explicitExclusions", "deferred")
470
+ for item in (coverage.get(field) if isinstance(coverage.get(field), list) else [])
471
+ }
472
+ if parent_manifest
473
+ else set()
474
+ )
475
+ findings: list[dict[str, Any]] = []
476
+ finding_positions: dict[str, int] = {}
477
+ represented: dict[str, str | None] = {}
478
+ represented_candidates: dict[tuple[str, str, Any, Any, Any], str | None] = {}
479
+ represented_history: dict[str, set[str]] = {}
480
+ represented_candidate_history: dict[tuple[str, str, Any, Any, Any], set[str]] = {}
481
+ rejected_history: dict[tuple[str, str], list[dict[str, Any]]] = {}
482
+ stopped_parent_seal = bool(
483
+ stopped and parent_manifest and parent_manifest["scan"].get("sealedAt")
484
+ )
485
+
486
+ def valid_finding(value: Any) -> bool:
487
+ # Use the finalizer's own per-record recovery before a draft can suppress
488
+ # an earlier checkpoint. Invalid latest records must not hide valid history.
489
+ document = {"scanId": scan_id, "findings": [copy.deepcopy(value)]}
490
+ if isinstance(document["findings"][0], dict):
491
+ _ensure_finding_identity(document["findings"][0], candidate_only=True)
492
+ _recover_unsealed_findings(
493
+ {"scan": {"id": scan_id, "target": binding["target"]}},
494
+ document,
495
+ Path(__file__).resolve().parent.parent / "schemas",
496
+ scan_dir,
497
+ [],
498
+ )
499
+ return bool(document["findings"])
500
+
501
+ all_sources = ([("parent", parent, None)] if parent else []) + sources
502
+ current_drafts = ([(None, parent)] if parent else []) + [
503
+ (worker_id, draft) for relative, draft, worker_id in sources if relative in current_results
504
+ ]
505
+ resolved: dict[tuple[str | None, str], str] = {}
506
+ for owner, draft in current_drafts:
507
+ for finding in draft["findings"]:
508
+ if (
509
+ isinstance(finding, dict)
510
+ and valid_finding(finding)
511
+ and (candidate_id := finding_candidate_id(finding))
512
+ ):
513
+ resolved.setdefault((owner, candidate_id), "reported")
514
+ for field in ("surfaces", "explicitExclusions"):
515
+ items = draft["coverage"].get(field, [])
516
+ for item in items if isinstance(items, list) else []:
517
+ if (
518
+ isinstance(item, dict)
519
+ and isinstance(item.get("candidateId"), str)
520
+ and item.get("disposition") in {"reported", "rejected", "not_applicable"}
521
+ ):
522
+ resolved.setdefault((owner, item["candidateId"]), item["disposition"])
523
+ # Only the current parent may claim that another worker finding was absorbed.
524
+ # A superseded checkpoint must not suppress a newer independent result.
525
+ for draft in [parent] if parent else []:
526
+ for finding in draft["findings"]:
527
+ if valid_finding(finding):
528
+ canonical_key = _finding_key(finding)
529
+ for retained in _retained_findings(finding):
530
+ retained_key = _finding_key(retained)
531
+ if retained is not finding:
532
+ represented_history.setdefault(retained_key, set()).add(
533
+ _digest(_finding_content(retained))
534
+ )
535
+ previous_key = represented.get(retained_key)
536
+ if retained_key not in represented:
537
+ represented[retained_key] = canonical_key
538
+ elif previous_key != canonical_key:
539
+ # Ambiguous history cannot suppress an independent source.
540
+ represented[retained_key] = None
541
+ originals = finding["provenance"].get("sourceFindings", [])
542
+ for original in originals if isinstance(originals, list) else []:
543
+ if isinstance(original, dict) and isinstance(original.get("finding"), dict):
544
+ source_id = original.get("id")
545
+ candidate_id = finding_candidate_id(original["finding"])
546
+ if isinstance(source_id, str) and ":" in source_id and candidate_id:
547
+ candidate_key = _worker_candidate_key(
548
+ source_id.rsplit(":", 1)[0],
549
+ candidate_id,
550
+ original["finding"],
551
+ )
552
+ previous_key = represented_candidates.get(candidate_key)
553
+ if candidate_key not in represented_candidates:
554
+ represented_candidates[candidate_key] = canonical_key
555
+ elif previous_key != canonical_key:
556
+ # Candidate ids are only authoritative within one
557
+ # logical worker. Multiple canonical owners make
558
+ # that worker-local identity ambiguous.
559
+ represented_candidates[candidate_key] = None
560
+ represented_candidate_history.setdefault(candidate_key, set()).add(
561
+ _digest(_finding_content(original["finding"]))
562
+ )
563
+ resolved.setdefault(candidate_key, "reported")
564
+ for relative, draft, worker_id in all_sources:
565
+ superseded = (
566
+ worker_id is None
567
+ and parent is not None
568
+ and parent.get("complete") is not False
569
+ and relative != "parent"
570
+ and (not stopped_parent_seal or relative in parent_preserved_sources)
571
+ ) or (
572
+ relative not in current_results
573
+ and any(
574
+ saved_worker == worker_id
575
+ and saved_path in current_results
576
+ and current.get("complete") is not False
577
+ for saved_path, current, saved_worker in sources
578
+ )
579
+ )
580
+ if (
581
+ (relative != "parent" or not parent_manifest)
582
+ and not superseded
583
+ and (
584
+ draft.get("complete") is False
585
+ or draft["coverage"].get("completeness") != "complete"
586
+ )
587
+ and coverage.get("completeness") in {"complete", "unknown"}
588
+ ):
589
+ coverage["completeness"] = "partial"
590
+ if superseded and not stopped:
591
+ continue
592
+ if "threatModel" not in manifest["scan"] and isinstance(draft.get("threatModel"), dict):
593
+ manifest["scan"]["threatModel"] = copy.deepcopy(draft["threatModel"])
594
+ for value in draft["findings"]:
595
+ if relative == "parent" and parent_manifest:
596
+ finding = copy.deepcopy(value)
597
+ _ensure_finding_identity(finding, candidate_only=True)
598
+ provenance = finding.get("provenance") if isinstance(finding, dict) else None
599
+ owner = provenance.get("workerId") if isinstance(provenance, dict) else None
600
+ candidate_id = finding_candidate_id(finding) if isinstance(finding, dict) else None
601
+ if (
602
+ stopped_parent_seal
603
+ and isinstance(owner, str)
604
+ and candidate_id
605
+ and resolved.get((owner, candidate_id)) in {"rejected", "not_applicable"}
606
+ ):
607
+ rejected_history.setdefault((owner, candidate_id), []).append(finding)
608
+ continue
609
+ if valid_finding(finding):
610
+ finding_positions.setdefault(_finding_key(finding), len(findings))
611
+ findings.append(finding)
612
+ continue
613
+ if relative != "parent" and parent and value in parent["findings"]:
614
+ continue
615
+ if not isinstance(value, dict):
616
+ warnings.append(f"Retained malformed finding evidence in {relative}.")
617
+ continue
618
+ source_value = copy.deepcopy(value)
619
+ finding = copy.deepcopy(value)
620
+ candidate_id = finding_candidate_id(finding)
621
+ if relative != "parent" and resolved.get((worker_id, candidate_id)) in {
622
+ "rejected",
623
+ "not_applicable",
624
+ }:
625
+ surfaces = coverage.get("surfaces")
626
+ for item in surfaces if isinstance(surfaces, list) else []:
627
+ if isinstance(item, dict) and item.get("candidateId") == candidate_id:
628
+ if not isinstance(item.get("previousFindings"), list):
629
+ item["previousFindings"] = []
630
+ history = item["previousFindings"]
631
+ if not any(
632
+ isinstance(previous, dict)
633
+ and _finding_key(previous) == _finding_key(finding)
634
+ and _finding_content(previous) == _finding_content(finding)
635
+ for previous in history
636
+ ):
637
+ history.append(finding)
638
+ continue
639
+ for key in ("findingId", "occurrenceId", "fingerprints"):
640
+ finding.pop(key, None)
641
+ locations = finding.get("locations", [])
642
+ if not isinstance(locations, list) or not any(
643
+ isinstance(location, dict)
644
+ and isinstance(location.get("path"), str)
645
+ and any(
646
+ path_within_scope(location["path"], path)
647
+ for path in binding["scope"]["includePaths"]
648
+ )
649
+ for location in locations
650
+ ):
651
+ warnings.append(f"Skipped out-of-scope finding from {relative}.")
652
+ coverage["completeness"] = "partial"
653
+ continue
654
+ provenance = finding.setdefault("provenance", {"source": "local_plugin"})
655
+ if not isinstance(provenance, dict):
656
+ findings.append(finding)
657
+ continue
658
+ if worker_id:
659
+ provenance.setdefault("workerId", worker_id)
660
+ _ensure_finding_identity(finding)
661
+ if not valid_finding(finding):
662
+ findings.append(finding)
663
+ continue
664
+ key = _finding_key(finding)
665
+ represented_by_parent = False
666
+ if relative != "parent":
667
+ if key in represented:
668
+ mapped_key = represented[key]
669
+ historical_contents = represented_history.get(key, set())
670
+ elif worker_id and candidate_id:
671
+ candidate_key = _worker_candidate_key(
672
+ worker_id, candidate_id, finding
673
+ )
674
+ if candidate_key not in represented_candidates:
675
+ represented_candidates[candidate_key] = key
676
+ mapped_key = represented_candidates[candidate_key]
677
+ historical_contents = represented_candidate_history.get(candidate_key, set())
678
+ else:
679
+ mapped_key = None
680
+ historical_contents = set()
681
+ if mapped_key is not None:
682
+ key = mapped_key
683
+ represented_by_parent = (
684
+ _digest(_finding_content(source_value)) in historical_contents
685
+ )
686
+ if key in finding_positions:
687
+ retained = findings[finding_positions[key]]
688
+ if finding != retained:
689
+ if represented_by_parent:
690
+ previous = copy.deepcopy(source_value)
691
+ previous_history = previous.get("provenance", {}).pop(
692
+ "previousFindings", []
693
+ )
694
+ elif _finding_strength(finding) > _finding_strength(retained):
695
+ previous = copy.deepcopy(retained)
696
+ previous_history = previous["provenance"].pop("previousFindings", [])
697
+ retained = finding
698
+ findings[finding_positions[key]] = retained
699
+ else:
700
+ previous = copy.deepcopy(source_value)
701
+ previous_history = previous.get("provenance", {}).pop(
702
+ "previousFindings", []
703
+ )
704
+ retained_provenance = retained["provenance"]
705
+ retained_history = retained_provenance.get("previousFindings")
706
+ history = (
707
+ [item for item in retained_history if isinstance(item, dict)]
708
+ if isinstance(retained_history, list)
709
+ else []
710
+ )
711
+ retained_provenance["previousFindings"] = history
712
+ for original in [
713
+ *(previous_history if isinstance(previous_history, list) else []),
714
+ previous,
715
+ ]:
716
+ if not isinstance(original, dict):
717
+ continue
718
+ source_key = _finding_key(original)
719
+ source_content = _finding_content(original)
720
+ already_retained = any(
721
+ source_key == _finding_key(historical)
722
+ and source_content == _finding_content(historical)
723
+ for historical in _retained_findings(retained)
724
+ )
725
+ if (
726
+ not already_retained
727
+ and original not in history
728
+ and original != retained
729
+ ):
730
+ history.append(original)
731
+ continue
732
+ finding_positions[key] = len(findings)
733
+ findings.append(finding)
734
+ if superseded:
735
+ continue
736
+ for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
737
+ items = draft["coverage"].get(field, [])
738
+ if not isinstance(items, list):
739
+ continue
740
+ output = coverage.setdefault(field, [])
741
+ if not isinstance(output, list):
742
+ # Keep malformed canonical collections for the existing finalizer's
743
+ # recovery and warnings rather than silently changing its contract.
744
+ continue
745
+ for item in items:
746
+ if field == "openQuestions" and isinstance(item, str):
747
+ item = {"question": item.strip()}
748
+ if (
749
+ field == "surfaces"
750
+ and isinstance(item, dict)
751
+ and item.get("disposition") in {"rejected", "not_applicable"}
752
+ and isinstance(item.get("candidateId"), str)
753
+ and (history_findings := rejected_history.get((worker_id, item["candidateId"])))
754
+ ):
755
+ item = copy.deepcopy(item)
756
+ if not isinstance(item.get("previousFindings"), list):
757
+ item["previousFindings"] = []
758
+ history = item["previousFindings"]
759
+ for finding in history_findings:
760
+ if not any(
761
+ isinstance(previous, dict)
762
+ and _finding_key(previous) == _finding_key(finding)
763
+ and _finding_content(previous) == _finding_content(finding)
764
+ for previous in history
765
+ ):
766
+ history.append(copy.deepcopy(finding))
767
+ if (
768
+ isinstance(item, dict)
769
+ and (worker_id, item.get("candidateId")) in resolved
770
+ and (field == "deferred" or item.get("disposition") == "needs_follow_up")
771
+ ):
772
+ continue
773
+ if isinstance(item, dict) and "id" not in item:
774
+ semantic_item = dict(item)
775
+ if field == "surfaces":
776
+ semantic_item.setdefault("receiptRefs", [])
777
+ if any(
778
+ isinstance(existing, dict)
779
+ and {key: value for key, value in existing.items() if key != "id"}
780
+ == semantic_item
781
+ for existing in output
782
+ ):
783
+ continue
784
+ if item not in output:
785
+ output.append(copy.deepcopy(item))
786
+
787
+ identities: dict[str, str] = {}
788
+ for finding in findings:
789
+ if not valid_finding(finding):
790
+ continue
791
+ identity = finding.get("identity")
792
+ if not isinstance(identity, dict):
793
+ continue
794
+ key = _encoded([finding.get("ruleId"), identity]).decode()
795
+ variant = _finding_key(finding)
796
+ if key in identities and identities[key] != variant:
797
+ finding.setdefault("provenance", {})["preservedIdentity"] = copy.deepcopy(identity)
798
+ identity["instance"] = f"{identity.get('instance', 'saved')}-{variant[:16]}"
799
+ identities[key] = variant
800
+ for field in ("surfaces", "explicitExclusions", "deferred"):
801
+ used: set[str] = set()
802
+ items = coverage.setdefault(field, [])
803
+ for item in items if isinstance(items, list) else []:
804
+ if not isinstance(item, dict):
805
+ continue
806
+ if id(item) in canonical_rows:
807
+ if isinstance(item.get("id"), str):
808
+ used.add(item["id"])
809
+ continue
810
+ item.setdefault("id", item.get("candidateId") or f"saved-{_digest(item)[:16]}")
811
+ if item["id"] in used:
812
+ item["id"] = f"{item['id']}-{_digest(item)[:16]}"
813
+ used.add(item["id"])
814
+ if field == "surfaces":
815
+ item.setdefault("receiptRefs", [])
816
+ if stopped or any(warning not in initial_warnings for warning in warnings):
817
+ coverage["completeness"] = "partial"
818
+ if stopped:
819
+ if not isinstance(coverage.get("deferred"), list):
820
+ coverage["deferred"] = []
821
+ item = {"id": "scan-stopped", "reason": reason}
822
+ if item not in coverage["deferred"]:
823
+ coverage["deferred"].append(item)
824
+ return manifest, {"findings": findings}, coverage
825
+
826
+
827
+ def coverage_for_comparison(db: Any, scan: Any) -> dict[str, Any]:
828
+ if scan["seal_manifest_digest"] is None:
829
+ raise SystemExit("Only sealed scans can be compared.")
830
+ scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
831
+ db.require_recorded_manifest_digest(scan, scan_dir)
832
+ try:
833
+ _, _, manifest, _, coverage, was_sealed, _ = _prepare_scan_finalization(scan_dir)
834
+ except ContractError as exc:
835
+ raise SystemExit(str(exc)) from exc
836
+ if not was_sealed or manifest["scan"]["id"] != scan["id"]:
837
+ raise SystemExit("Only sealed scans can be compared.")
838
+ return coverage
839
+
840
+
841
+ def _snapshot_published_outputs(scan_dir: Path) -> dict[str, bytes | None]:
842
+ snapshots: dict[str, bytes | None] = {}
843
+ for relative in _PUBLISHED_OUTPUTS:
844
+ descriptor = -1
845
+ try:
846
+ descriptor = open_scan_local_file_descriptor(
847
+ scan_dir, relative, "Published scan output"
848
+ )
849
+ with os.fdopen(descriptor, "rb") as handle:
850
+ descriptor = -1
851
+ snapshots[relative] = handle.read()
852
+ except ContractError:
853
+ path = scan_dir / relative
854
+ if path.exists() or path.is_symlink():
855
+ raise
856
+ snapshots[relative] = None
857
+ finally:
858
+ if descriptor >= 0:
859
+ os.close(descriptor)
860
+ return snapshots
861
+
862
+
863
+ def _restore_published_outputs(scan_dir: Path, snapshots: dict[str, bytes | None]) -> None:
864
+ for relative, contents in snapshots.items():
865
+ if contents is None:
866
+ path = scan_dir / relative
867
+ if path.exists() or path.is_symlink():
868
+ _remove_scan_local_file_if_exists(scan_dir, relative)
869
+ else:
870
+ write_scan_local_bytes(scan_dir, relative, contents)
871
+
872
+
873
+ def preserve_scan_results_locked(db: Any, connection: Any, scan_id: str) -> bool:
874
+ """Publish or verify retained terminal results through the workbench host."""
875
+ scan = db.require_scan(connection, scan_id)
876
+ if scan["status"] != "failed":
877
+ return False
878
+ frozen_source_digests: dict[str, str] | None = None
879
+ raw_frozen_sources = scan["retained_source_digests_json"]
880
+ if raw_frozen_sources is not None:
881
+ parsed_frozen_sources = json.loads(raw_frozen_sources)
882
+ if not isinstance(parsed_frozen_sources, dict) or not all(
883
+ isinstance(relative, str) and isinstance(digest, str)
884
+ for relative, digest in parsed_frozen_sources.items()
885
+ ):
886
+ raise ContractError("Saved stopped-scan source digests are malformed.")
887
+ frozen_source_digests = parsed_frozen_sources
888
+ scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
889
+ deep_run = connection.execute(
890
+ "SELECT status FROM deep_scan_runs WHERE scan_id = ?", (scan_id,)
891
+ ).fetchone()
892
+ outcome = (
893
+ "canceled"
894
+ if scan["canceled_at"]
895
+ else "interrupted"
896
+ if deep_run and deep_run["status"] == "interrupted"
897
+ else "failed"
898
+ )
899
+ stored_warnings = json.loads(scan["completion_warnings_json"])
900
+ publication_follow_up_warnings = [
901
+ warning
902
+ for warning in stored_warnings
903
+ if isinstance(warning, str) and warning.startswith(_PUBLICATION_FOLLOW_UP_WARNING)
904
+ ]
905
+ warnings = [
906
+ warning for warning in stored_warnings if warning not in publication_follow_up_warnings
907
+ ]
908
+
909
+ def record_publication(manifest: dict[str, Any], findings: dict[str, Any]) -> None:
910
+ retained_sources = manifest.get("scan", {}).get("preservedSources")
911
+ if not isinstance(retained_sources, dict) or not all(
912
+ isinstance(relative, str) and isinstance(source_digest, str)
913
+ for relative, source_digest in retained_sources.items()
914
+ ):
915
+ raise ContractError("Stopped scan source digests could not be frozen.")
916
+ digest = db.published_manifest_digest(scan_dir, manifest)
917
+ timestamp = db.now()
918
+ with connection:
919
+ for kind, filename in db.ARTIFACTS.items():
920
+ path = db.artifact_path(scan_dir, filename, required=True)
921
+ connection.execute(
922
+ "INSERT OR REPLACE INTO scan_artifacts "
923
+ "(scan_id, kind, path, created_at) VALUES (?, ?, ?, ?)",
924
+ (scan_id, kind, str(path), scan["completed_at"]),
925
+ )
926
+ # Delete only vanished occurrences; stable IDs retain triage and remediation.
927
+ existing_ids = {
928
+ row["id"]
929
+ for row in connection.execute(
930
+ "SELECT id FROM finding_occurrences WHERE scan_id = ?", (scan_id,)
931
+ )
932
+ }
933
+ retained_ids = {finding["occurrenceId"] for finding in findings["findings"]}
934
+ connection.executemany(
935
+ "DELETE FROM finding_occurrences WHERE id = ? AND scan_id = ?",
936
+ ((occurrence_id, scan_id) for occurrence_id in existing_ids - retained_ids),
937
+ )
938
+ db.index_findings(connection, scan_id, findings, scan["completed_at"])
939
+ connection.execute(
940
+ "UPDATE scans SET seal_manifest_digest = ?, retained_source_digests_json = "
941
+ "COALESCE(retained_source_digests_json, ?), completion_warnings_json = ?, "
942
+ "updated_at = ? WHERE id = ? AND status = 'failed'",
943
+ (
944
+ digest,
945
+ json.dumps(retained_sources, sort_keys=True),
946
+ json.dumps(list(dict.fromkeys(warnings))),
947
+ timestamp,
948
+ scan_id,
949
+ ),
950
+ )
951
+ connection.execute(
952
+ "UPDATE scan_progress SET reportable_findings_count = ?, updated_at = ? "
953
+ "WHERE scan_id = ?",
954
+ (len(findings["findings"]), timestamp, scan_id),
955
+ )
956
+
957
+ existing_path = db.artifact_path(scan_dir, db.ARTIFACTS["manifest"], required=False)
958
+ existing_scan = db.read_json_object(existing_path).get("scan", {}) if existing_path else {}
959
+ if scan["seal_manifest_digest"] is not None or (
960
+ isinstance(existing_scan, dict)
961
+ and (
962
+ existing_scan.get("sealedAt") is not None or existing_scan.get("artifacts") is not None
963
+ )
964
+ ):
965
+ db.require_recorded_manifest_digest(scan, scan_dir)
966
+ existing, existing_findings, _ = finalize_scan(
967
+ scan_dir, expected_coverage_mode=db.expected_coverage_mode(scan)
968
+ )
969
+ db.verify_manifest_binding(scan, existing)
970
+ if existing_scan.get("status") == outcome:
971
+ existing_sources = existing_scan.get("preservedSources")
972
+ if frozen_source_digests is None:
973
+ if not isinstance(existing_sources, dict) or not all(
974
+ isinstance(relative, str) and isinstance(digest, str)
975
+ for relative, digest in existing_sources.items()
976
+ ):
977
+ raise ContractError("Stopped scan source digests could not be frozen.")
978
+ frozen_source_digests = existing_sources
979
+ if existing_sources == frozen_source_digests:
980
+ if (
981
+ raw_frozen_sources is not None
982
+ and scan["seal_manifest_digest"] is not None
983
+ and not publication_follow_up_warnings
984
+ ):
985
+ return True
986
+ record_publication(existing, existing_findings)
987
+ return True
988
+ raise ContractError("Stopped scan sources changed after terminal publication.")
989
+ binding = {**db.workbench_completion_binding(scan, scan["completed_at"]), "status": outcome}
990
+ documents = merge_saved_results(
991
+ scan_dir,
992
+ scan_id,
993
+ binding,
994
+ connection.execute(
995
+ "SELECT * FROM deep_scan_workers WHERE scan_id = ? ORDER BY created_at, id",
996
+ (scan_id,),
997
+ ).fetchall(),
998
+ warnings,
999
+ stopped=True,
1000
+ reason=(
1001
+ f"Scan {outcome}; saved findings and pending review were preserved. "
1002
+ f"{scan['failure_message'] or ''}"
1003
+ ).strip(),
1004
+ frozen_source_digests=frozen_source_digests,
1005
+ )
1006
+ if documents is None:
1007
+ unpublished_warnings = list(dict.fromkeys([*warnings, *publication_follow_up_warnings]))
1008
+ if unpublished_warnings != stored_warnings:
1009
+ with connection:
1010
+ connection.execute(
1011
+ "UPDATE scans SET completion_warnings_json = ?, updated_at = ? "
1012
+ "WHERE id = ? AND status = 'failed'",
1013
+ (json.dumps(unpublished_warnings), db.now(), scan_id),
1014
+ )
1015
+ return False
1016
+ prepared = _prepare_scan_finalization(
1017
+ scan_dir,
1018
+ expected_coverage_mode=db.expected_coverage_mode(scan),
1019
+ completion_binding=binding,
1020
+ completion_warnings=warnings,
1021
+ draft_documents=documents,
1022
+ )
1023
+ snapshots = _snapshot_published_outputs(scan_dir)
1024
+ try:
1025
+ manifest, findings, _ = _write_prepared_scan_finalization(prepared)
1026
+ db.verify_manifest_binding(scan, manifest)
1027
+ record_publication(manifest, findings)
1028
+ except BaseException:
1029
+ _restore_published_outputs(scan_dir, snapshots)
1030
+ raise
1031
+ return True
1032
+
1033
+
1034
+ def refresh_stopped_scan_results(
1035
+ db: Any, connection: Any, scan_id: str, *, strict: bool = False
1036
+ ) -> None:
1037
+ scan = db.require_scan(connection, scan_id)
1038
+ if scan["status"] != "failed":
1039
+ return
1040
+ scan_id = scan["id"]
1041
+ with db.scan_completion_lock(scan_id):
1042
+ if strict:
1043
+ if preserve_scan_results_locked(db, connection, scan_id):
1044
+ db.deep_scan.clear_deep_scan_publication_failure(connection, scan_id)
1045
+ else:
1046
+ preserve_stopped_results_after_transition(db, connection, scan_id)
1047
+
1048
+
1049
+ def preserve_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:
1050
+ scan_id = db.require_uuid(args.scan_id, "scan-id")
1051
+ with db.scan_completion_lock(scan_id):
1052
+ scan = db.require_scan(connection, scan_id)
1053
+ if scan["status"] != "failed":
1054
+ raise SystemExit("Only a stopped scan can preserve terminal results.")
1055
+ workspace = db.require_workspace(connection, scan["workspace_id"])
1056
+ owner = (
1057
+ scan["continuation_thread_id"]
1058
+ or scan["deep_scan_owner_thread_id"]
1059
+ or workspace["thread_id"]
1060
+ )
1061
+ if args.thread_id is not None and args.thread_id != owner:
1062
+ raise SystemExit("Saved results can only be published from the owning Codex thread.")
1063
+ if args.coordinator_generation is not None:
1064
+ if args.thread_id is None:
1065
+ raise SystemExit("A coordinator result refresh requires its owning thread.")
1066
+ db.deep_scan.require_current_coordinator(
1067
+ db.deep_scan.require_deep_scan_run(connection, scan_id), args
1068
+ )
1069
+ else:
1070
+ db.handoff.require_current_continuation(
1071
+ scan,
1072
+ args.claim_token,
1073
+ error_message="Saved results are owned by another continuation.",
1074
+ )
1075
+ published = preserve_scan_results_locked(db, connection, scan_id)
1076
+ if not published and scan["canceled_at"] is not None:
1077
+ raise SystemExit("Saved scan results could not be published or verified.")
1078
+ if published:
1079
+ db.deep_scan.clear_deep_scan_publication_failure(connection, scan_id)
1080
+ return db.scan_context(connection, scan_id)
1081
+
1082
+
1083
+ def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
1084
+ scan_id = db.require_uuid(args.scan_id, "scan-id")
1085
+ with db.scan_completion_lock(scan_id):
1086
+ scan = db.require_scan(connection, scan_id)
1087
+ db.handoff.require_current_continuation(
1088
+ scan, args.claim_token, error_message="Scan draft is owned by another continuation."
1089
+ )
1090
+ if scan["status"] != "running" or scan["seal_manifest_digest"] is not None:
1091
+ raise SystemExit(
1092
+ "The scan stopped; its saved checkpoint was retained without replacing sealed results."
1093
+ )
1094
+ scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
1095
+ if args.checkpoint_path is not None:
1096
+ try:
1097
+ checkpoint_relative = Path(args.checkpoint_path).relative_to(scan_dir).as_posix()
1098
+ except ValueError as exc:
1099
+ raise SystemExit(
1100
+ "Scan checkpoint must be inside the registered scan drafts directory."
1101
+ ) from exc
1102
+ if not re.fullmatch(r"drafts/[0-9a-fA-F-]+\.checkpoint\.json", checkpoint_relative):
1103
+ raise SystemExit(
1104
+ "Scan checkpoint must be inside the registered scan drafts directory."
1105
+ )
1106
+ checkpoint, checkpoint_contents = _read_scan_local_json_bytes(
1107
+ scan_dir, checkpoint_relative, "Staged scan checkpoint"
1108
+ )
1109
+ if checkpoint.get("scanId") != scan_id:
1110
+ raise SystemExit("Staged scan checkpoint belongs to another scan.")
1111
+ checkpoint_digest = hashlib.sha256(checkpoint_contents).hexdigest()
1112
+ write_scan_local_bytes(
1113
+ scan_dir,
1114
+ f"checkpoints/{checkpoint_digest}.json",
1115
+ checkpoint_contents,
1116
+ )
1117
+ if (
1118
+ args.expected_draft_digest is not None
1119
+ and args.expected_draft_digest != _scan_draft_digest(scan_dir)
1120
+ ):
1121
+ raise SystemExit(
1122
+ "scan_draft_conflict: canonical scan results changed; reconcile the saved checkpoint again."
1123
+ )
1124
+ try:
1125
+ relative = Path(args.draft_path).relative_to(scan_dir).as_posix()
1126
+ except ValueError as exc:
1127
+ raise SystemExit(
1128
+ "Scan draft must be inside the registered scan drafts directory."
1129
+ ) from exc
1130
+ if not re.fullmatch(r"drafts/[0-9a-fA-F-]+\.json", relative):
1131
+ raise SystemExit("Scan draft must be inside the registered scan drafts directory.")
1132
+ draft = _read_scan_local_json(scan_dir, relative, "Staged scan draft")
1133
+ manifest, findings, coverage = draft["manifest"], draft["findings"], draft["coverage"]
1134
+ binding = db.workbench_completion_binding(scan, db.now())
1135
+ # Validate on copies: saved canonical documents remain ordinary unsealed drafts.
1136
+ copied_manifest = copy.deepcopy(manifest)
1137
+ copied_findings = copy.deepcopy(findings)
1138
+ copied_coverage = copy.deepcopy(coverage)
1139
+ _populate_unsealed_manifest_envelope(copied_manifest, copied_manifest["scan"], binding)
1140
+ _populate_unsealed_artifact_envelope(
1141
+ copied_manifest, copied_findings, copied_coverage, binding
1142
+ )
1143
+ _validate_completion_binding(copied_manifest, copied_findings, copied_coverage, binding)
1144
+ for filename, document in (
1145
+ ("findings.json", findings),
1146
+ ("coverage.json", coverage),
1147
+ ("scan-manifest.json", manifest),
1148
+ ):
1149
+ write_scan_local_bytes(
1150
+ scan_dir,
1151
+ filename,
1152
+ (json.dumps(document, allow_nan=False, indent=2) + "\n").encode(),
1153
+ )
1154
+ return {"scanId": scan_id, "status": "draft_written"}
1155
+
1156
+
1157
+ def _scan_draft_digest(scan_dir: Path) -> str:
1158
+ digest = hashlib.sha256()
1159
+ for filename in ("scan-manifest.json", "findings.json", "coverage.json"):
1160
+ digest.update(filename.encode())
1161
+ digest.update(b"\0")
1162
+ try:
1163
+ (scan_dir / filename).lstat()
1164
+ except FileNotFoundError:
1165
+ digest.update(b"missing\0")
1166
+ continue
1167
+ _, contents = _read_scan_local_json_bytes(scan_dir, filename, filename)
1168
+ digest.update(b"present\0")
1169
+ digest.update(contents)
1170
+ digest.update(b"\0")
1171
+ return digest.hexdigest()
1172
+
1173
+
1174
+ def fail_scan(db: Any, connection: Any, args: Any) -> dict[str, Any]:
1175
+ with db.scan_completion_lock(db.require_uuid(args.scan_id, "scan-id")):
1176
+ return fail_scan_locked(db, connection, args)
1177
+
1178
+
1179
+ def fail_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
1180
+ scan_id = db.require_uuid(args.scan_id, "scan-id")
1181
+ cost_json = db.parse_scan_cost(args.cost_json)
1182
+ connection.execute("BEGIN IMMEDIATE")
1183
+ try:
1184
+ timestamp = db.now()
1185
+ scan = db.require_scan(connection, scan_id)
1186
+ if scan["status"] == "failed":
1187
+ connection.commit()
1188
+ return db.scan_context(connection, scan["id"])
1189
+ if scan["status"] == "complete":
1190
+ raise SystemExit("A completed scan cannot be marked failed.")
1191
+ db.handoff.require_current_continuation(
1192
+ scan,
1193
+ args.claim_token,
1194
+ error_message="Scan failure is owned by another continuation.",
1195
+ )
1196
+ message = db.optional_text(args.message, maximum=2400)
1197
+ updated = connection.execute(
1198
+ """
1199
+ UPDATE scans
1200
+ SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?,
1201
+ cost_json = ?
1202
+ WHERE id = ? AND status = 'running'
1203
+ """,
1204
+ (message, timestamp, timestamp, cost_json, scan["id"]),
1205
+ )
1206
+ if updated.rowcount != 1:
1207
+ raise SystemExit("Only a running scan can be marked failed.")
1208
+ db.deep_scan.fail_from_parent_scan(connection, scan["id"], message, timestamp)
1209
+ progress_updated = connection.execute(
1210
+ "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
1211
+ (timestamp, scan["id"]),
1212
+ )
1213
+ if progress_updated.rowcount != 1:
1214
+ raise SystemExit("Codex Security scan progress not found.")
1215
+ connection.commit()
1216
+ except BaseException:
1217
+ connection.rollback()
1218
+ raise
1219
+ preserve_stopped_results_after_transition(db, connection, scan["id"])
1220
+ return db.scan_context(connection, scan["id"])
1221
+
1222
+
1223
+ def cancel_scan(db: Any, connection: Any, args: Any) -> dict[str, Any]:
1224
+ with db.scan_completion_lock(db.require_uuid(args.scan_id, "scan-id")):
1225
+ return cancel_scan_locked(db, connection, args)
1226
+
1227
+
1228
+ def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
1229
+ scan_id = db.require_uuid(args.scan_id, "scan-id")
1230
+ thread_id = db.optional_text(args.thread_id, maximum=512)
1231
+ connection.execute("BEGIN IMMEDIATE")
1232
+ try:
1233
+ timestamp = db.now()
1234
+ scan = db.require_scan(connection, scan_id)
1235
+ workspace = db.require_workspace(connection, scan["workspace_id"])
1236
+ owning_thread_id = scan["continuation_thread_id"] or workspace["thread_id"]
1237
+ if thread_id is not None and owning_thread_id != thread_id:
1238
+ raise SystemExit("A scan can only be canceled from its owning Codex thread.")
1239
+ if scan["canceled_at"] is not None:
1240
+ connection.commit()
1241
+ return db.workspace_state(connection, scan["workspace_id"])
1242
+ if scan["status"] != "running":
1243
+ raise SystemExit("Only a running scan can be canceled.")
1244
+ updated = connection.execute(
1245
+ """
1246
+ UPDATE scans
1247
+ SET status = 'failed', canceled_at = ?, completed_at = ?, updated_at = ?
1248
+ WHERE id = ? AND status = 'running'
1249
+ """,
1250
+ (timestamp, timestamp, timestamp, scan["id"]),
1251
+ )
1252
+ if updated.rowcount != 1:
1253
+ raise SystemExit("Only a running scan can be canceled.")
1254
+ db.deep_scan.cancel_from_parent_scan(connection, scan["id"], timestamp)
1255
+ progress_updated = connection.execute(
1256
+ "UPDATE scan_progress SET updated_at = ? WHERE scan_id = ?",
1257
+ (timestamp, scan["id"]),
1258
+ )
1259
+ if progress_updated.rowcount != 1:
1260
+ raise SystemExit("Codex Security scan progress not found.")
1261
+ connection.commit()
1262
+ except BaseException:
1263
+ connection.rollback()
1264
+ raise
1265
+ preserve_stopped_results_after_transition(db, connection, scan["id"])
1266
+ return db.workspace_state(connection, scan["workspace_id"])
1267
+
1268
+
1269
+ def preserve_stopped_results_after_transition(
1270
+ db: Any, connection: Any, scan_id: str
1271
+ ) -> None:
1272
+ try:
1273
+ published = preserve_scan_results_locked(db, connection, scan_id)
1274
+ except (ContractError, OSError, SystemExit, ValueError) as exc:
1275
+ scan = db.require_scan(connection, scan_id)
1276
+ warnings = json.loads(scan["completion_warnings_json"])
1277
+ warning = f"Saved scan evidence remains on disk; result publication needs follow-up: {exc}"
1278
+ with connection:
1279
+ connection.execute(
1280
+ "UPDATE scans SET completion_warnings_json = ? WHERE id = ?",
1281
+ (json.dumps(list(dict.fromkeys([*warnings, warning]))), scan_id),
1282
+ )
1283
+ return
1284
+ if published:
1285
+ db.deep_scan.clear_deep_scan_publication_failure(connection, scan_id)
1286
+
1287
+
1288
+ if __name__ == "__main__":
1289
+ argparse.ArgumentParser(description=__doc__).parse_args()