@openai/codex-security 0.6.0 → 0.7.0

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 (243) hide show
  1. package/README.md +68 -37
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  6. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/access-advisory.md +11 -0
  17. package/_bundled_plugin/references/core-scan.md +30 -77
  18. package/_bundled_plugin/references/final-report.md +45 -189
  19. package/_bundled_plugin/references/scan-contract.md +2 -0
  20. package/_bundled_plugin/references/scan-prologue.md +1 -1
  21. package/_bundled_plugin/references/scan-runtime.md +1 -5
  22. package/_bundled_plugin/references/threat-model.md +33 -41
  23. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  24. package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
  25. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  26. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  27. package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
  28. package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
  29. package/_bundled_plugin/scripts/report_projection.py +44 -15
  30. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  31. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  32. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
  33. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  34. package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
  35. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  36. package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
  37. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  38. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  39. package/_bundled_plugin/scripts/workbench_db.py +51 -22
  40. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  41. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  42. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  43. package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
  44. package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
  45. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  46. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  47. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  48. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  49. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  50. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  51. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  52. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  53. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  54. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  55. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  56. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  57. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  58. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  59. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  60. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  61. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  62. package/_bundled_plugin/skills/publish-findings/SKILL.md +28 -24
  63. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  64. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  65. package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
  66. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  67. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  68. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  69. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  70. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  71. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  72. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  73. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  74. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  75. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  76. package/dist/api.d.ts +5 -3
  77. package/dist/api.d.ts.map +1 -1
  78. package/dist/api.js +341 -37
  79. package/dist/api.js.map +1 -1
  80. package/dist/auth.d.ts.map +1 -1
  81. package/dist/auth.js +4 -1
  82. package/dist/auth.js.map +1 -1
  83. package/dist/cli.d.ts +2 -2
  84. package/dist/cli.d.ts.map +1 -1
  85. package/dist/cli.js +674 -419
  86. package/dist/cli.js.map +1 -1
  87. package/dist/component-scan.d.ts +8 -2
  88. package/dist/component-scan.d.ts.map +1 -1
  89. package/dist/component-scan.js +2 -0
  90. package/dist/component-scan.js.map +1 -1
  91. package/dist/contract.d.ts +2 -0
  92. package/dist/contract.d.ts.map +1 -1
  93. package/dist/contract.js +67 -33
  94. package/dist/contract.js.map +1 -1
  95. package/dist/cost.d.ts +18 -0
  96. package/dist/cost.d.ts.map +1 -1
  97. package/dist/cost.js +107 -12
  98. package/dist/cost.js.map +1 -1
  99. package/dist/coverage-presentation.d.ts +6 -0
  100. package/dist/coverage-presentation.d.ts.map +1 -0
  101. package/dist/coverage-presentation.js +34 -0
  102. package/dist/coverage-presentation.js.map +1 -0
  103. package/dist/custom-validation-prompt.js +3 -3
  104. package/dist/custom-validation-prompt.js.map +1 -1
  105. package/dist/custom-validation.d.ts.map +1 -1
  106. package/dist/custom-validation.js +30 -4
  107. package/dist/custom-validation.js.map +1 -1
  108. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  109. package/dist/deduplication/checkpointed-review.js +3 -1
  110. package/dist/deduplication/checkpointed-review.js.map +1 -1
  111. package/dist/deduplication/scan.d.ts.map +1 -1
  112. package/dist/deduplication/scan.js +7 -5
  113. package/dist/deduplication/scan.js.map +1 -1
  114. package/dist/endor-findings.d.ts +4 -3
  115. package/dist/endor-findings.d.ts.map +1 -1
  116. package/dist/endor-findings.js +16 -11
  117. package/dist/endor-findings.js.map +1 -1
  118. package/dist/external-findings-import.d.ts.map +1 -1
  119. package/dist/external-findings-import.js +13 -5
  120. package/dist/external-findings-import.js.map +1 -1
  121. package/dist/external-findings-local.d.ts.map +1 -1
  122. package/dist/external-findings-local.js +8 -1
  123. package/dist/external-findings-local.js.map +1 -1
  124. package/dist/external-findings-publish.d.ts +1 -1
  125. package/dist/external-findings-publish.d.ts.map +1 -1
  126. package/dist/external-findings-publish.js +11 -3
  127. package/dist/external-findings-publish.js.map +1 -1
  128. package/dist/external-findings-read.d.ts +11 -1
  129. package/dist/external-findings-read.d.ts.map +1 -1
  130. package/dist/external-findings-read.js +15 -6
  131. package/dist/external-findings-read.js.map +1 -1
  132. package/dist/external-import-contract.d.ts +3 -1
  133. package/dist/external-import-contract.d.ts.map +1 -1
  134. package/dist/external-import-contract.js +33 -25
  135. package/dist/external-import-contract.js.map +1 -1
  136. package/dist/external-imports-feature.d.ts +6 -0
  137. package/dist/external-imports-feature.d.ts.map +1 -0
  138. package/dist/external-imports-feature.js +51 -0
  139. package/dist/external-imports-feature.js.map +1 -0
  140. package/dist/finding-workflow.d.ts +22 -5
  141. package/dist/finding-workflow.d.ts.map +1 -1
  142. package/dist/finding-workflow.js +21 -9
  143. package/dist/finding-workflow.js.map +1 -1
  144. package/dist/github-advisories.d.ts.map +1 -1
  145. package/dist/github-advisories.js +3 -1
  146. package/dist/github-advisories.js.map +1 -1
  147. package/dist/github-findings.d.ts +4 -3
  148. package/dist/github-findings.d.ts.map +1 -1
  149. package/dist/github-findings.js +16 -14
  150. package/dist/github-findings.js.map +1 -1
  151. package/dist/hosted-remediation.d.ts.map +1 -1
  152. package/dist/hosted-remediation.js +19 -2
  153. package/dist/hosted-remediation.js.map +1 -1
  154. package/dist/hosted-scan.d.ts +1 -1
  155. package/dist/hosted-scan.d.ts.map +1 -1
  156. package/dist/hosted-scan.js +0 -5
  157. package/dist/hosted-scan.js.map +1 -1
  158. package/dist/import-scan.js +1 -1
  159. package/dist/import-scan.js.map +1 -1
  160. package/dist/index.d.ts +3 -3
  161. package/dist/index.d.ts.map +1 -1
  162. package/dist/index.js +1 -1
  163. package/dist/index.js.map +1 -1
  164. package/dist/knowledge-base.d.ts +1 -0
  165. package/dist/knowledge-base.d.ts.map +1 -1
  166. package/dist/knowledge-base.js +17 -8
  167. package/dist/knowledge-base.js.map +1 -1
  168. package/dist/models.d.ts +1 -0
  169. package/dist/models.d.ts.map +1 -1
  170. package/dist/models.js.map +1 -1
  171. package/dist/owner-evidence.d.ts +2 -0
  172. package/dist/owner-evidence.d.ts.map +1 -1
  173. package/dist/owner-evidence.js +2 -1
  174. package/dist/owner-evidence.js.map +1 -1
  175. package/dist/publish.d.ts +2 -0
  176. package/dist/publish.d.ts.map +1 -1
  177. package/dist/publish.js +1 -1
  178. package/dist/publish.js.map +1 -1
  179. package/dist/remediation.d.ts +1 -25
  180. package/dist/remediation.d.ts.map +1 -1
  181. package/dist/remediation.js +3 -24
  182. package/dist/remediation.js.map +1 -1
  183. package/dist/runtime.d.ts.map +1 -1
  184. package/dist/runtime.js +7 -7
  185. package/dist/runtime.js.map +1 -1
  186. package/dist/scan-dashboard.d.ts +5 -3
  187. package/dist/scan-dashboard.d.ts.map +1 -1
  188. package/dist/scan-dashboard.js +79 -26
  189. package/dist/scan-dashboard.js.map +1 -1
  190. package/dist/scan-history-renderer.d.ts.map +1 -1
  191. package/dist/scan-history-renderer.js +8 -2
  192. package/dist/scan-history-renderer.js.map +1 -1
  193. package/dist/scan-owner-suggestions.d.ts +1 -1
  194. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  195. package/dist/scan-owner-suggestions.js +4 -4
  196. package/dist/scan-owner-suggestions.js.map +1 -1
  197. package/dist/scan-usage-display.d.ts +8 -0
  198. package/dist/scan-usage-display.d.ts.map +1 -0
  199. package/dist/scan-usage-display.js +46 -0
  200. package/dist/scan-usage-display.js.map +1 -0
  201. package/dist/scanner-import.d.ts +1 -1
  202. package/dist/scanner-import.d.ts.map +1 -1
  203. package/dist/scanner-import.js +7 -3
  204. package/dist/scanner-import.js.map +1 -1
  205. package/dist/security-policy.d.ts.map +1 -1
  206. package/dist/security-policy.js +1 -20
  207. package/dist/security-policy.js.map +1 -1
  208. package/dist/semgrep-findings.d.ts +4 -3
  209. package/dist/semgrep-findings.d.ts.map +1 -1
  210. package/dist/semgrep-findings.js +9 -9
  211. package/dist/semgrep-findings.js.map +1 -1
  212. package/dist/skill-authentication.d.ts +18 -0
  213. package/dist/skill-authentication.d.ts.map +1 -0
  214. package/dist/skill-authentication.js +82 -0
  215. package/dist/skill-authentication.js.map +1 -0
  216. package/dist/snyk-findings.d.ts +5 -4
  217. package/dist/snyk-findings.d.ts.map +1 -1
  218. package/dist/snyk-findings.js +18 -17
  219. package/dist/snyk-findings.js.map +1 -1
  220. package/dist/suggest-owners.d.ts +4 -1
  221. package/dist/suggest-owners.d.ts.map +1 -1
  222. package/dist/suggest-owners.js +53 -21
  223. package/dist/suggest-owners.js.map +1 -1
  224. package/dist/targets.d.ts.map +1 -1
  225. package/dist/targets.js +4 -1
  226. package/dist/targets.js.map +1 -1
  227. package/dist/wiz-csv.d.ts +2 -1
  228. package/dist/wiz-csv.d.ts.map +1 -1
  229. package/dist/wiz-csv.js +3 -3
  230. package/dist/wiz-csv.js.map +1 -1
  231. package/dist/wiz-findings.d.ts +2 -1
  232. package/dist/wiz-findings.d.ts.map +1 -1
  233. package/dist/wiz-findings.js +27 -23
  234. package/dist/wiz-findings.js.map +1 -1
  235. package/docs/classify-severity-records.md +3 -4
  236. package/docs/cli.md +155 -38
  237. package/docs/findings-service.md +119 -118
  238. package/docs/hosted-remediation.md +19 -17
  239. package/docs/hosted-scans.md +37 -11
  240. package/package.json +8 -8
  241. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  242. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  243. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -59,9 +59,11 @@ def parse_args(description: str) -> argparse.Namespace:
59
59
 
60
60
  inspect_setup = add_command("inspect-setup", "--target-path", "--scope")
61
61
  inspect_setup.add_argument("--mode", choices=MODES, required=True)
62
+ inspect_setup.add_argument("--deep-scan-project-json")
62
63
 
63
64
  save_workspace = add_command("save-workspace", "--workspace-id", "--target-path", "--scope")
64
65
  save_workspace.add_argument("--mode", choices=MODES, required=True)
66
+ save_workspace.add_argument("--deep-scan-project-json")
65
67
  save_workspace.add_argument("--target-summary")
66
68
  add_user_context(save_workspace)
67
69
 
@@ -101,6 +103,7 @@ def parse_args(description: str) -> argparse.Namespace:
101
103
 
102
104
  get_scan = add_command("get-scan", "--scan-id")
103
105
  get_scan.add_argument("--occurrence-id")
106
+ get_scan.add_argument("--check-target", action="store_true")
104
107
 
105
108
  add_command("rename-scan", "--scan-id", "--name")
106
109
 
@@ -0,0 +1,479 @@
1
+ """Resolve accepted worker receipt references without changing their ownership."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import os
7
+ import re
8
+ from collections.abc import Callable, Sequence
9
+ from pathlib import Path, PurePosixPath
10
+ from typing import Any
11
+
12
+ from finalize_scan_contract import (
13
+ ContractError,
14
+ _require_portable_relative_path,
15
+ _require_str,
16
+ _validate_schema_node,
17
+ open_scan_local_file_descriptor,
18
+ path_within_scope,
19
+ )
20
+ from workbench.saved_coverage import _project_worker_coverage_row, _saved_coverage_id
21
+
22
+
23
+ def _checkpoint_head_directory(relative: str) -> Path | None:
24
+ path = Path(relative)
25
+ if path.name == "checkpoint-head.json":
26
+ return path.parent
27
+ if path.parent.name == "checkpoint-heads":
28
+ return path.parent.parent
29
+ return None
30
+
31
+
32
+ def _is_source_order_snapshot(relative: str) -> bool:
33
+ path = Path(relative)
34
+ return path.parent == Path("source-order") and bool(
35
+ re.fullmatch(r"[0-9a-f]{64}\.json", path.name)
36
+ )
37
+
38
+
39
+ def capture_receipt_checkpoints(
40
+ relative: str,
41
+ kind: str | None,
42
+ captured: dict[str, tuple[str, int]],
43
+ checkpoint_paths: Callable[[str], list[str]],
44
+ read_checkpoint: Callable[[str], tuple[dict[str, Any], str, int]],
45
+ ) -> dict[str, tuple[str, int]]:
46
+ """Bind a captured worker result to checkpoints visible after reading it."""
47
+ if kind == "discovery" and Path(relative).name == "result.json":
48
+ directory = (Path(relative).parent / "checkpoints").as_posix()
49
+ for path in checkpoint_paths(directory):
50
+ try:
51
+ _, digest, observed = read_checkpoint(path)
52
+ except (ContractError, OSError, ValueError):
53
+ continue
54
+ captured[path] = (digest, observed)
55
+ return captured
56
+
57
+
58
+ def receipt_checkpoints(
59
+ relative: str,
60
+ worker_id: str | None,
61
+ known: dict[str, str | None],
62
+ checkpoint_paths: Callable[[str], list[str]],
63
+ ) -> dict[str, str]:
64
+ """Capture host checkpoints written after enumeration but before result.json."""
65
+ if worker_id is None or Path(relative).name != "result.json":
66
+ return {}
67
+ directory = (Path(relative).parent / "checkpoints").as_posix()
68
+ added = {path: worker_id for path in checkpoint_paths(directory) if path not in known}
69
+ known.update(added)
70
+ return added
71
+
72
+
73
+ def retain_recorded_receipt_ownership(
74
+ sources: list[tuple[str, dict[str, Any], str | None]],
75
+ digest: Callable[[Any], str],
76
+ include_paths: Sequence[str],
77
+ finding_scope: Sequence[tuple[str, bool]] | None = None,
78
+ ) -> None:
79
+ # Checkpoints are written by the host tool; direct result files can be authored
80
+ # without it. Compare the entire payload within the same worker attempt.
81
+ def payload_digest(draft: dict[str, Any]) -> str:
82
+ return digest({key: value for key, value in draft.items() if key != "handoffClaimToken"})
83
+
84
+ scope = (
85
+ finding_scope if finding_scope is not None else [(path, False) for path in include_paths]
86
+ )
87
+ recorded: dict[Path, set[str]] = {}
88
+ for relative, draft, worker_id in sources:
89
+ directory = Path(relative).parent
90
+ if worker_id is not None and directory.name == "checkpoints":
91
+ payloads = recorded.setdefault(directory.parent, set())
92
+ payloads.add(payload_digest(draft))
93
+ if "." not in include_paths:
94
+ # Legacy writers saved the checkpoint before filtering inherited findings.
95
+ scoped = [
96
+ finding
97
+ for finding in draft["findings"]
98
+ if isinstance(finding, dict)
99
+ and isinstance(finding.get("locations"), list)
100
+ and any(
101
+ isinstance(location, dict)
102
+ and isinstance(location.get("path"), str)
103
+ and any(
104
+ PurePosixPath(location["path"]) == PurePosixPath(path)
105
+ if is_file
106
+ else path_within_scope(location["path"], path)
107
+ for path, is_file in scope
108
+ )
109
+ for location in finding["locations"]
110
+ )
111
+ ]
112
+ payloads.add(payload_digest({**draft, "findings": scoped}))
113
+ for relative, draft, worker_id in sources:
114
+ directory = Path(relative).parent
115
+ if worker_id is None or directory.name == "checkpoints":
116
+ continue
117
+ if payload_digest(draft) in recorded.get(directory, set()):
118
+ continue
119
+ surfaces = draft["coverage"].get("surfaces", [])
120
+ for surface in surfaces if isinstance(surfaces, list) else []:
121
+ if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):
122
+ surface["provenance"].pop("scanReceiptRefs", None)
123
+
124
+
125
+ def resolve_coverage_receipts(
126
+ scan_dir: Path, item: dict[str, Any], worker: Any, relative: str
127
+ ) -> Any:
128
+ refs = item.get("receiptRefs", [])
129
+ if not isinstance(refs, list):
130
+ return refs
131
+ directory = Path(relative).parent
132
+ if directory.name == "checkpoints":
133
+ directory = directory.parent
134
+ output = Path(worker["artifact_dir"]).relative_to(scan_dir)
135
+ worker_prefix = (output.parent if output.name == "output" else output).as_posix() + "/"
136
+ active_prefix = output.as_posix() + "/"
137
+ if directory != output:
138
+ refs = [
139
+ f"{directory.as_posix()}/{Path(ref).as_posix()[len(active_prefix) :]}"
140
+ if isinstance(ref, str) and Path(ref).as_posix().startswith(active_prefix)
141
+ else ref
142
+ for ref in refs
143
+ ]
144
+
145
+ def scan_receipt(ref: str) -> bool:
146
+ try:
147
+ descriptor = open_scan_local_file_descriptor(scan_dir, ref, "coverage receipt")
148
+ except (ContractError, OSError):
149
+ return False
150
+ os.close(descriptor)
151
+ return True
152
+
153
+ def qualified_receipt(ref: Any) -> Any:
154
+ if not isinstance(ref, str):
155
+ return ref
156
+ try:
157
+ normalized = _require_portable_relative_path(ref, "Worker coverage receipt")
158
+ except ContractError:
159
+ return ref # Leave malformed references to per-record recovery.
160
+ if not normalized.startswith("artifacts/"):
161
+ # A worker prefix must not make result.json a valid coverage receipt.
162
+ return ref
163
+ ref = normalized
164
+ provenance = item.get("provenance")
165
+ inherited_scan_refs = (
166
+ provenance.get("scanReceiptRefs", []) if isinstance(provenance, dict) else []
167
+ )
168
+ if ref.startswith(worker_prefix) or (
169
+ isinstance(inherited_scan_refs, list) and ref in inherited_scan_refs
170
+ ):
171
+ return ref
172
+ local_ref = Path(f"{directory}/{ref}").as_posix()
173
+ return local_ref if scan_receipt(local_ref) or not scan_receipt(ref) else ref
174
+
175
+ return [qualified_receipt(ref) for ref in refs]
176
+
177
+
178
+ def _deferred_candidate_id(
179
+ row: dict[str, Any],
180
+ owner: str | None,
181
+ ambiguous_deferred: set[tuple[str | None, str]],
182
+ ) -> str | None:
183
+ identity = row.get("candidateId") or row.get("id")
184
+ if not isinstance(identity, str):
185
+ return None
186
+ if (owner, identity) in ambiguous_deferred and not any(
187
+ key in row for key in ("candidateId", "candidate", "finding")
188
+ ):
189
+ return None
190
+ return identity
191
+
192
+
193
+ def _generic_surface_updates(
194
+ sources: list[tuple[str, dict[str, Any], str | None]],
195
+ closed_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]],
196
+ active_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]],
197
+ resolved_candidates: dict[tuple[str | None, str], str],
198
+ reopened_generic: set[tuple[str | None, str]],
199
+ surface_schema: dict[str, Any],
200
+ deferred_rows: dict[str, list[Any]],
201
+ ambiguous_deferred: set[tuple[str | None, str]],
202
+ record_source: Any,
203
+ record_order: Any,
204
+ surface_receipts: Any,
205
+ *,
206
+ canonical_rows: set[int] | None = None,
207
+ coverage_sources: dict[int, tuple[dict[str, Any], list[str]]] | None = None,
208
+ surface_is_retained: Any = None,
209
+ eligible_receipt_sources: set[str] | None = None,
210
+ receipt_root: Path | None = None,
211
+ receipt_warnings: list[str] | None = None,
212
+ fallback_surfaces: list[dict[str, Any]] | None = None,
213
+ ) -> tuple[set[int], list[tuple[str, str | None, dict[str, Any], dict[str, Any]]]]:
214
+ if not closed_deferred and not reopened_generic and receipt_root is None:
215
+ return set(), []
216
+
217
+ def receipt_error(ref: Any) -> ContractError | None:
218
+ if receipt_root is None or not isinstance(ref, str):
219
+ return ContractError("Saved coverage receipt is unavailable.")
220
+ try:
221
+ descriptor = open_scan_local_file_descriptor(
222
+ receipt_root, ref, "Saved coverage receipt"
223
+ )
224
+ os.close(descriptor)
225
+ except ContractError as exc:
226
+ return exc
227
+ return None
228
+
229
+ def record_key(field: str, owner: str | None, row: dict[str, Any]) -> tuple[str | None, Any]:
230
+ source_owner, original = record_source(field, owner, row)
231
+ identity = original.get("id")
232
+ return source_owner, identity if isinstance(identity, str) else None
233
+
234
+ def linked(row: dict[str, Any], identity: str | None, owner: str | None) -> bool:
235
+ _, row = record_source("deferred", owner, row)
236
+ surface_ids = row.get("surfaceIds", [])
237
+ return identity is not None and (
238
+ row.get("id") == identity or (isinstance(surface_ids, list) and identity in surface_ids)
239
+ )
240
+
241
+ saved_surfaces: dict[tuple[str | None, str], list[tuple[str, dict[str, Any]]]] = {}
242
+ for relative, draft, owner in sources:
243
+ rows = draft["coverage"].get("surfaces", [])
244
+ for row in rows if isinstance(rows, list) else []:
245
+ if isinstance(row, dict) and isinstance(row.get("id"), str):
246
+ saved_surfaces.setdefault(record_key("surfaces", owner, row), []).append(
247
+ (relative, row)
248
+ )
249
+ replaced: set[int] = set()
250
+ updates: list[tuple[str, str | None, dict[str, Any], dict[str, Any]]] = []
251
+ # Current selections across all surfaces take precedence over historical refs.
252
+ receipt_paths: dict[str, str] = {}
253
+ retained_surfaces: dict[tuple[str | None, str], dict[str, Any]] = {}
254
+ if receipt_root is not None:
255
+ receipt_surfaces: list[tuple[str | None, dict[str, Any]]] = []
256
+ for key, matches in saved_surfaces.items():
257
+ retained = [
258
+ match for match in matches if surface_is_retained(match[0], key[0], match[1])
259
+ ]
260
+ if not retained:
261
+ continue
262
+ latest_source, latest_surface = max(
263
+ retained, key=lambda match: record_order(match[0], key[0], match[1])
264
+ )
265
+ retained_surfaces[key] = latest_surface
266
+ receipt_surfaces.extend(
267
+ (key[0], row)
268
+ for relative, row in retained
269
+ if record_order(relative, key[0], row)
270
+ == record_order(latest_source, key[0], latest_surface)
271
+ )
272
+ for relative, draft, owner in sources:
273
+ rows = draft["coverage"].get("surfaces", [])
274
+ for row in rows if isinstance(rows, list) else []:
275
+ if (
276
+ isinstance(row, dict)
277
+ and "id" not in row
278
+ and surface_is_retained(relative, owner, row)
279
+ ):
280
+ receipt_surfaces.append((owner, row))
281
+ receipt_surfaces.extend((None, row) for row in fallback_surfaces or [])
282
+ for owner, latest_surface in receipt_surfaces:
283
+ # Recovery repairs disposition and receipts before validating row
284
+ # metadata. A row discarded there cannot reserve a receipt spelling.
285
+ metadata = _project_worker_coverage_row(latest_surface, owner, "surfaces")
286
+ metadata.setdefault("id", _saved_coverage_id(metadata))
287
+ metadata.update(disposition="needs_follow_up", receiptRefs=[])
288
+ try:
289
+ _require_str(metadata, "id", "coverage.surfaces")
290
+ _validate_schema_node(metadata, surface_schema, "coverage.surfaces")
291
+ except ContractError:
292
+ continue
293
+ refs = latest_surface.get("receiptRefs", [])
294
+ for ref in refs if isinstance(refs, list) else []:
295
+ if receipt_error(ref) is None:
296
+ normalized = _require_portable_relative_path(ref, "Saved coverage receipt")
297
+ receipt_paths.setdefault(normalized.lower(), normalized)
298
+ for relative, draft, owner in sources:
299
+ current = draft["coverage"].get("surfaces", [])
300
+ for surface in current if isinstance(current, list) else []:
301
+ if not isinstance(surface, dict):
302
+ continue
303
+ surface_owner, identity = record_key("surfaces", owner, surface)
304
+ closed_ids = {
305
+ identity
306
+ for (saved_owner, identity), (_, _, source) in closed_deferred.items()
307
+ if saved_owner == surface_owner and source == relative
308
+ }
309
+ reopened_ids = {
310
+ identity
311
+ for (saved_owner, identity), (_, _, source) in active_deferred.items()
312
+ if saved_owner == surface_owner
313
+ and source == relative
314
+ and (owner, identity) in reopened_generic
315
+ }
316
+ reopening = surface.get("disposition") == "needs_follow_up"
317
+ work_ids = reopened_ids if reopening else closed_ids
318
+ repair_only = not work_ids
319
+ if repair_only and receipt_root is None:
320
+ continue
321
+ if not isinstance(identity, str):
322
+ continue
323
+ matches = saved_surfaces[(surface_owner, identity)]
324
+ # Receipt repair alone cannot close or reopen a saved surface.
325
+ if repair_only and any(
326
+ row.get("disposition") != surface.get("disposition") for _, row in matches
327
+ ):
328
+ continue
329
+ # Older writers could assign one ID to distinct surfaces in a draft.
330
+ # A closure cannot identify which of those observations it replaces.
331
+ by_source = dict(matches)
332
+ if any(row != by_source[saved_path] for saved_path, row in matches):
333
+ continue
334
+ if any(
335
+ "candidateId" in row or "candidate" in row or "finding" in row for _, row in matches
336
+ ):
337
+ continue
338
+ if any(
339
+ row is not surface
340
+ and record_order(saved_path, surface_owner, row)
341
+ >= record_order(relative, surface_owner, surface)
342
+ and row.get("disposition") != surface.get("disposition")
343
+ for saved_path, row in matches
344
+ ):
345
+ continue
346
+
347
+ if not reopening and any(
348
+ saved_owner == surface_owner
349
+ and (
350
+ not isinstance(row.get("id") or row.get("candidateId"), str)
351
+ or (
352
+ isinstance(row.get("id"), str)
353
+ and (owner, row["id"]) in ambiguous_deferred
354
+ and not any(key in row for key in ("candidateId", "candidate", "finding"))
355
+ )
356
+ )
357
+ and linked(row, identity, saved_owner)
358
+ for saved_path, _, saved_owner in sources
359
+ for row in deferred_rows[saved_path]
360
+ if isinstance(row, dict)
361
+ ):
362
+ continue
363
+ if not reopening and any(
364
+ saved_owner == surface_owner
365
+ and (owner, deferred_id) not in closed_deferred
366
+ and (
367
+ (candidate_id := _deferred_candidate_id(row, owner, ambiguous_deferred)) is None
368
+ or (owner, candidate_id) not in resolved_candidates
369
+ )
370
+ and linked(row, identity, saved_owner)
371
+ for (saved_owner, deferred_id), (_, row, _) in active_deferred.items()
372
+ ):
373
+ continue
374
+ # An accepted checkpoint can update a saved surface by ID without
375
+ # optional surfaceIds links on its generic task.
376
+ receipt_matches = [
377
+ (saved_path, row)
378
+ for saved_path, row in matches
379
+ if receipt_root is None
380
+ or saved_path in eligible_receipt_sources
381
+ or surface_is_retained(saved_path, owner, row)
382
+ ]
383
+ if not receipt_matches:
384
+ continue
385
+ latest_relative, latest_surface = max(
386
+ receipt_matches, key=lambda match: record_order(match[0], surface_owner, match[1])
387
+ )
388
+ target = (
389
+ retained_surfaces.get((surface_owner, identity)) if repair_only else latest_surface
390
+ )
391
+ if target is None:
392
+ continue
393
+ update = copy.deepcopy(target)
394
+ # Historical evidence can repair a retained row without promoting
395
+ # an unselected observation's label, notes, or other metadata.
396
+ refs = copy.deepcopy(surface_receipts(latest_relative, latest_surface))
397
+ update["receiptRefs"] = refs
398
+ replaced_receipt = False
399
+ replacement_paths = dict(receipt_paths)
400
+ if isinstance(refs, list):
401
+ repaired = (
402
+ not reopening and bool(refs) and all(receipt_error(ref) is None for ref in refs)
403
+ )
404
+ if repaired:
405
+ for ref in refs:
406
+ normalized = _require_portable_relative_path(ref, "Saved coverage receipt")
407
+ key = normalized.lower()
408
+ if key in replacement_paths and replacement_paths[key] != normalized:
409
+ repaired = False
410
+ break
411
+ replacement_paths[key] = normalized
412
+ for saved_relative, row in receipt_matches:
413
+ previous_refs = surface_receipts(saved_relative, row)
414
+ for ref in previous_refs if isinstance(previous_refs, list) else []:
415
+ if ref not in refs:
416
+ failure = receipt_error(ref) if repaired else None
417
+ replaceable = failure is not None and isinstance(
418
+ failure.__cause__, FileNotFoundError
419
+ )
420
+ if repaired and isinstance(ref, str):
421
+ try:
422
+ normalized = _require_portable_relative_path(
423
+ ref, "Saved coverage receipt"
424
+ )
425
+ except ContractError as error:
426
+ failure = error
427
+ replaceable = True
428
+ else:
429
+ key = normalized.lower()
430
+ previous = replacement_paths.get(key)
431
+ if previous is not None and previous != normalized:
432
+ failure = ContractError(
433
+ f"Saved coverage receipt: duplicate artifact path: {previous} and {normalized}"
434
+ )
435
+ replaceable = True
436
+ elif not replaceable:
437
+ replacement_paths[key] = normalized
438
+ if replaceable:
439
+ replaced_receipt = True
440
+ if receipt_warnings is not None:
441
+ receipt_warnings.append(
442
+ f"Replaced invalid saved coverage receipt {ref}: {failure}"
443
+ )
444
+ continue
445
+ refs.append(ref)
446
+ if repair_only and not replaced_receipt:
447
+ continue
448
+ try:
449
+ _validate_schema_node(update, surface_schema, "coverage.surfaces")
450
+ except ContractError:
451
+ continue
452
+ replaced_sources = {
453
+ id(row)
454
+ for _, row in matches
455
+ if reopening
456
+ or row.get("disposition") in {"needs_follow_up", surface.get("disposition")}
457
+ }
458
+ replaced.update(replaced_sources)
459
+ entry = (latest_relative, surface_owner, latest_surface, update)
460
+ if entry not in updates:
461
+ receipt_paths.update(replacement_paths)
462
+ updates.append(entry)
463
+ retained = next(
464
+ entry[3]
465
+ for entry in updates
466
+ if entry[:3] == (latest_relative, surface_owner, latest_surface)
467
+ and entry[3] == update
468
+ )
469
+ if coverage_sources is not None:
470
+ from workbench.retained_coverage import _inherit_coverage_sources
471
+
472
+ _inherit_coverage_sources(
473
+ retained,
474
+ [latest_surface, *(row for _, row in matches if id(row) in replaced_sources)],
475
+ coverage_sources,
476
+ )
477
+ if canonical_rows is not None and id(latest_surface) in canonical_rows:
478
+ canonical_rows.add(id(retained))
479
+ return replaced, updates
@@ -43,6 +43,7 @@ import workbench_remediation as remediation_state
43
43
  import workbench_saved_results as saved_results
44
44
  import workbench_scan_history as scan_history
45
45
  import workbench_scan_usage as scan_usage
46
+ from deep_scan_config import resolve_deep_scan_setup
46
47
  from finalize_scan_contract import (
47
48
  PRODUCER_NAME,
48
49
  ContractError,
@@ -51,6 +52,7 @@ from finalize_scan_contract import (
51
52
  _write_prepared_scan_finalization,
52
53
  finalize_scan,
53
54
  finding_candidate_id,
55
+ manifest_is_sealed,
54
56
  open_scan_local_file_descriptor,
55
57
  write_scan_local_bytes,
56
58
  )
@@ -122,6 +124,7 @@ from workbench_target import (
122
124
  require_git_worktree_head,
123
125
  require_remediation_target,
124
126
  require_scan_target_identity,
127
+ require_scan_target_unchanged,
125
128
  restore_directory_junctions,
126
129
  scan_target_warning,
127
130
  worktree_content_digest,
@@ -739,10 +742,7 @@ def create_workspace(connection: sqlite3.Connection, args: argparse.Namespace) -
739
742
  return workspace_state(connection, workspace_id)
740
743
 
741
744
 
742
- def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
743
- workspace = require_workspace(connection, args.workspace_id)
744
- if workspace["active_scan_id"]:
745
- raise SystemExit("This workspace already has a scan. Open a new workspace to change setup.")
745
+ def inspect_selected_setup(args: argparse.Namespace) -> dict[str, Any]:
746
746
  inspected = inspect_setup_values(
747
747
  args.target_path,
748
748
  args.scope,
@@ -752,6 +752,20 @@ def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) ->
752
752
  args.diff_head_revision,
753
753
  args.diff_content_digest,
754
754
  )
755
+ if args.mode == "deep":
756
+ inspected["deepScanConfig"] = resolve_deep_scan_setup(
757
+ os.cpu_count() or 1, args.deep_scan_project_json
758
+ )
759
+ elif args.deep_scan_project_json is not None:
760
+ raise SystemExit("Project Deep Scan settings require Deep Scan mode.")
761
+ return inspected
762
+
763
+
764
+ def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
765
+ workspace = require_workspace(connection, args.workspace_id)
766
+ if workspace["active_scan_id"]:
767
+ raise SystemExit("This workspace already has a scan. Open a new workspace to change setup.")
768
+ inspected = inspect_selected_setup(args)
755
769
  target = Path(inspected["target"]["targetPath"])
756
770
  scope = inspected["scope"]
757
771
  target_path = str(target)
@@ -776,7 +790,7 @@ def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) ->
776
790
  SET target_id = ?, target_path = ?, target_title = ?, target_summary = ?, default_scope = ?,
777
791
  default_mode = ?, user_context = ?, diff_target_kind = ?,
778
792
  diff_base_revision = ?, diff_head_revision = ?, diff_content_digest = ?,
779
- submitted = 1, updated_at = ?
793
+ deep_scan_config_json = ?, submitted = 1, updated_at = ?
780
794
  WHERE id = ? AND active_scan_id IS NULL
781
795
  """,
782
796
  (
@@ -788,6 +802,7 @@ def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) ->
788
802
  args.mode,
789
803
  user_context_argument(args),
790
804
  *scan_diff_identity(diff_target or None),
805
+ json.dumps(inspected["deepScanConfig"]) if "deepScanConfig" in inspected else None,
791
806
  timestamp,
792
807
  workspace["id"],
793
808
  ),
@@ -1250,7 +1265,7 @@ def complete_budget_exhausted_scan(
1250
1265
  if run["manifest_path"] == str(scan_dir / "scan-manifest.json")
1251
1266
  else budget_exhausted_candidates(scan, scan_dir)
1252
1267
  )
1253
- warning = optional_text(args.message, maximum=2400)
1268
+ warning = optional_text(args.message)
1254
1269
  if warning is None:
1255
1270
  warning = (
1256
1271
  f"Deep Scan reached its cost limit after an estimated "
@@ -1364,7 +1379,7 @@ def budget_exhausted_draft(
1364
1379
  for key in ("surfaces", "explicitExclusions", "deferred"):
1365
1380
  if not isinstance(coverage.get(key), list):
1366
1381
  raise SystemExit("Budget-exhausted scan contains invalid canonical coverage.")
1367
- if manifest["scan"].get("sealedAt") is not None or manifest["scan"].get("artifacts"):
1382
+ if manifest_is_sealed(manifest["scan"]):
1368
1383
  raise SystemExit("Budget-exhausted scan cannot replace an already sealed scan draft.")
1369
1384
  else:
1370
1385
  contract = scan_contract(scan)
@@ -1529,10 +1544,7 @@ def complete_scan_locked(
1529
1544
  already_sealed = (
1530
1545
  current_manifest_path is not None
1531
1546
  and isinstance(current_manifest.get("scan"), dict)
1532
- and (
1533
- current_manifest["scan"].get("sealedAt") is not None
1534
- or current_manifest["scan"].get("artifacts") is not None
1535
- )
1547
+ and manifest_is_sealed(current_manifest["scan"])
1536
1548
  )
1537
1549
  completion_binding = workbench_completion_binding(scan, completion_timestamp, current_manifest)
1538
1550
  if scan["recipe_json"] is not None:
@@ -1575,6 +1587,7 @@ def complete_scan_locked(
1575
1587
  ).fetchall(),
1576
1588
  warnings,
1577
1589
  stopped=False,
1590
+ scan_mode=scan["mode"],
1578
1591
  reason="",
1579
1592
  )
1580
1593
  if merge_parent_draft
@@ -1978,6 +1991,12 @@ def parse_scan_recipe(value: str, repository: Path) -> dict[str, Any]:
1978
1991
  return recipe
1979
1992
 
1980
1993
 
1994
+ def coverage_summary_for_history(scan: sqlite3.Row) -> dict[str, Any]:
1995
+ return scan_history.coverage_summary_for_history(
1996
+ _WORKBENCH_DB_CONTEXT, scan, require_canonical_scan_directory
1997
+ )
1998
+
1999
+
1981
2000
  def coverage_for_comparison(scan: sqlite3.Row) -> dict[str, Any]:
1982
2001
  return saved_results.coverage_for_comparison(_WORKBENCH_DB_CONTEXT, scan)
1983
2002
 
@@ -2670,6 +2689,11 @@ def workspace_state(
2670
2689
  "mode": workspace["default_mode"],
2671
2690
  "scope": workspace["default_scope"],
2672
2691
  "setup": {"submitted": bool(workspace["submitted"])},
2692
+ **(
2693
+ {"deepScanConfig": json.loads(workspace["deep_scan_config_json"])}
2694
+ if workspace["deep_scan_config_json"] is not None
2695
+ else {}
2696
+ ),
2673
2697
  "setupValidation": {"error": None, "valid": bool(workspace["submitted"])},
2674
2698
  "targetPath": workspace["target_path"],
2675
2699
  "targetSummary": workspace["target_summary"],
@@ -2745,6 +2769,17 @@ def scan_context(
2745
2769
  return context
2746
2770
 
2747
2771
 
2772
+ def get_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
2773
+ result = scan_context(connection, args.scan_id, args.occurrence_id)
2774
+ if result["scan"]["progress"]["status"] != "running":
2775
+ scan = require_scan(connection, args.scan_id)
2776
+ try:
2777
+ result["scan"] = dict(result["scan"], coverage=coverage_summary_for_history(scan))
2778
+ except (OSError, RuntimeError, SystemExit):
2779
+ pass # Historical artifacts may no longer be available or verifiable.
2780
+ return result
2781
+
2782
+
2748
2783
  def list_findings(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
2749
2784
  scan = require_scan(connection, args.scan_id)
2750
2785
  backfill_legacy_finding_details(connection, scan)
@@ -3421,16 +3456,7 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:
3421
3456
  print(json.dumps(result, allow_nan=False, sort_keys=True))
3422
3457
  return
3423
3458
  if args.command == "inspect-setup":
3424
- result = inspect_setup_values(
3425
- args.target_path,
3426
- args.scope,
3427
- args.mode,
3428
- args.diff_target_kind,
3429
- args.diff_base_revision,
3430
- args.diff_head_revision,
3431
- args.diff_content_digest,
3432
- )
3433
- print(json.dumps(result, allow_nan=False, sort_keys=True))
3459
+ print(json.dumps(inspect_selected_setup(args), allow_nan=False, sort_keys=True))
3434
3460
  return
3435
3461
  if args.command in {"save-artifact", "read-artifact"}:
3436
3462
  print(json.dumps(saved_results.read_or_save_artifact(args)))
@@ -3448,6 +3474,7 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:
3448
3474
  "save-workspace": save_workspace,
3449
3475
  "start-scan": start_scan,
3450
3476
  "begin-deep-scan": deep_scan.begin_deep_scan,
3477
+ "acknowledge-deep-scan-result": deep_scan.acknowledge_deep_scan_result,
3451
3478
  "get-deep-scan": deep_scan.get_deep_scan,
3452
3479
  "claim-deep-scan-coordinator": deep_scan.claim_deep_scan_coordinator,
3453
3480
  "upsert-deep-scan-worker": deep_scan.upsert_deep_scan_worker,
@@ -3505,7 +3532,9 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:
3505
3532
  elif args.command == "start-headless-standard-scan":
3506
3533
  result = _start_prompt_driven_scan(connection, args, headless_standard=True)
3507
3534
  elif args.command == "get-scan":
3508
- result = scan_context(connection, args.scan_id, args.occurrence_id)
3535
+ if args.check_target:
3536
+ require_scan_target_unchanged(require_scan(connection, args.scan_id))
3537
+ result = get_scan(connection, args)
3509
3538
  elif args.command == "rename-scan":
3510
3539
  result = scan_history.rename_scan(
3511
3540
  connection, require_scan(connection, args.scan_id), args.name