@openai/codex-security 0.6.0 → 0.8.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 (308) hide show
  1. package/README.md +76 -39
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  4. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  6. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  9. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  11. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  12. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  13. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  20. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  23. package/_bundled_plugin/references/access-advisory.md +11 -0
  24. package/_bundled_plugin/references/core-scan.md +30 -77
  25. package/_bundled_plugin/references/final-report.md +50 -184
  26. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  27. package/_bundled_plugin/references/scan-contract.md +12 -12
  28. package/_bundled_plugin/references/scan-prologue.md +1 -1
  29. package/_bundled_plugin/references/scan-runtime.md +1 -5
  30. package/_bundled_plugin/references/threat-model.md +33 -41
  31. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  32. package/_bundled_plugin/schemas/scan-manifest.schema.json +37 -11
  33. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  34. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  35. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  36. package/_bundled_plugin/scripts/deep_scan_workbench.py +146 -86
  37. package/_bundled_plugin/scripts/finalize_scan_contract.py +249 -76
  38. package/_bundled_plugin/scripts/report_projection.py +49 -17
  39. package/_bundled_plugin/scripts/review_state.py +68 -0
  40. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  41. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  43. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3230 -0
  44. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  45. package/_bundled_plugin/scripts/workbench/saved_coverage.py +651 -8
  46. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  47. package/_bundled_plugin/scripts/workbench/saved_sources.py +730 -0
  48. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  49. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  50. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  51. package/_bundled_plugin/scripts/workbench_db.py +55 -171
  52. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  53. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  54. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  55. package/_bundled_plugin/scripts/workbench_saved_results.py +808 -2389
  56. package/_bundled_plugin/scripts/workbench_scan_history.py +77 -7
  57. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  58. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  59. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  60. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  61. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  62. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  63. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  64. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  65. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  66. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  67. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  68. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  69. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  70. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  71. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  72. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  73. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  74. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -24
  75. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  76. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  77. package/_bundled_plugin/skills/security-scan/SKILL.md +29 -17
  78. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  79. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  80. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  81. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  82. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  83. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  84. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  85. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  86. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  87. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  88. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  89. package/dist/api.d.ts +5 -3
  90. package/dist/api.d.ts.map +1 -1
  91. package/dist/api.js +359 -53
  92. package/dist/api.js.map +1 -1
  93. package/dist/auth.d.ts.map +1 -1
  94. package/dist/auth.js +4 -1
  95. package/dist/auth.js.map +1 -1
  96. package/dist/cli.d.ts +2 -2
  97. package/dist/cli.d.ts.map +1 -1
  98. package/dist/cli.js +696 -430
  99. package/dist/cli.js.map +1 -1
  100. package/dist/cloud-publish.d.ts.map +1 -1
  101. package/dist/cloud-publish.js +2 -23
  102. package/dist/cloud-publish.js.map +1 -1
  103. package/dist/component-scan.d.ts +8 -2
  104. package/dist/component-scan.d.ts.map +1 -1
  105. package/dist/component-scan.js +2 -0
  106. package/dist/component-scan.js.map +1 -1
  107. package/dist/contract.d.ts +5 -2
  108. package/dist/contract.d.ts.map +1 -1
  109. package/dist/contract.js +93 -45
  110. package/dist/contract.js.map +1 -1
  111. package/dist/cost.d.ts +18 -0
  112. package/dist/cost.d.ts.map +1 -1
  113. package/dist/cost.js +107 -12
  114. package/dist/cost.js.map +1 -1
  115. package/dist/coverage-presentation.d.ts +6 -0
  116. package/dist/coverage-presentation.d.ts.map +1 -0
  117. package/dist/coverage-presentation.js +34 -0
  118. package/dist/coverage-presentation.js.map +1 -0
  119. package/dist/custom-publish.js +2 -2
  120. package/dist/custom-publish.js.map +1 -1
  121. package/dist/custom-validation-prompt.js +5 -5
  122. package/dist/custom-validation-prompt.js.map +1 -1
  123. package/dist/custom-validation.d.ts.map +1 -1
  124. package/dist/custom-validation.js +47 -19
  125. package/dist/custom-validation.js.map +1 -1
  126. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  127. package/dist/deduplication/checkpointed-review.js +3 -1
  128. package/dist/deduplication/checkpointed-review.js.map +1 -1
  129. package/dist/deduplication/codex-review.d.ts.map +1 -1
  130. package/dist/deduplication/codex-review.js +2 -2
  131. package/dist/deduplication/codex-review.js.map +1 -1
  132. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  133. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  134. package/dist/deduplication/deduplication-prompts.js +3 -0
  135. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  136. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  137. package/dist/deduplication/records-protocol.js +21 -1
  138. package/dist/deduplication/records-protocol.js.map +1 -1
  139. package/dist/deduplication/scan.d.ts.map +1 -1
  140. package/dist/deduplication/scan.js +9 -7
  141. package/dist/deduplication/scan.js.map +1 -1
  142. package/dist/endor-findings.d.ts +4 -3
  143. package/dist/endor-findings.d.ts.map +1 -1
  144. package/dist/endor-findings.js +16 -11
  145. package/dist/endor-findings.js.map +1 -1
  146. package/dist/external-findings-import.d.ts.map +1 -1
  147. package/dist/external-findings-import.js +13 -5
  148. package/dist/external-findings-import.js.map +1 -1
  149. package/dist/external-findings-local.d.ts +1 -0
  150. package/dist/external-findings-local.d.ts.map +1 -1
  151. package/dist/external-findings-local.js +14 -3
  152. package/dist/external-findings-local.js.map +1 -1
  153. package/dist/external-findings-publish.d.ts +2 -1
  154. package/dist/external-findings-publish.d.ts.map +1 -1
  155. package/dist/external-findings-publish.js +64 -28
  156. package/dist/external-findings-publish.js.map +1 -1
  157. package/dist/external-findings-read.d.ts +12 -1
  158. package/dist/external-findings-read.d.ts.map +1 -1
  159. package/dist/external-findings-read.js +25 -6
  160. package/dist/external-findings-read.js.map +1 -1
  161. package/dist/external-findings.d.ts +2 -0
  162. package/dist/external-findings.d.ts.map +1 -1
  163. package/dist/external-findings.js.map +1 -1
  164. package/dist/external-import-contract.d.ts +7 -1
  165. package/dist/external-import-contract.d.ts.map +1 -1
  166. package/dist/external-import-contract.js +63 -31
  167. package/dist/external-import-contract.js.map +1 -1
  168. package/dist/external-imports-feature.d.ts +6 -0
  169. package/dist/external-imports-feature.d.ts.map +1 -0
  170. package/dist/external-imports-feature.js +51 -0
  171. package/dist/external-imports-feature.js.map +1 -0
  172. package/dist/finding-workflow.d.ts +24 -5
  173. package/dist/finding-workflow.d.ts.map +1 -1
  174. package/dist/finding-workflow.js +24 -9
  175. package/dist/finding-workflow.js.map +1 -1
  176. package/dist/github-advisories.d.ts.map +1 -1
  177. package/dist/github-advisories.js +3 -1
  178. package/dist/github-advisories.js.map +1 -1
  179. package/dist/github-findings.d.ts +4 -3
  180. package/dist/github-findings.d.ts.map +1 -1
  181. package/dist/github-findings.js +16 -14
  182. package/dist/github-findings.js.map +1 -1
  183. package/dist/host-protocol.d.ts +1 -1
  184. package/dist/host-protocol.d.ts.map +1 -1
  185. package/dist/host-protocol.js +2 -2
  186. package/dist/host-protocol.js.map +1 -1
  187. package/dist/hosted-remediation.d.ts.map +1 -1
  188. package/dist/hosted-remediation.js +19 -2
  189. package/dist/hosted-remediation.js.map +1 -1
  190. package/dist/hosted-scan.d.ts +1 -1
  191. package/dist/hosted-scan.d.ts.map +1 -1
  192. package/dist/hosted-scan.js +0 -6
  193. package/dist/hosted-scan.js.map +1 -1
  194. package/dist/import-scan.js +17 -17
  195. package/dist/import-scan.js.map +1 -1
  196. package/dist/index.d.ts +4 -3
  197. package/dist/index.d.ts.map +1 -1
  198. package/dist/index.js +2 -1
  199. package/dist/index.js.map +1 -1
  200. package/dist/knowledge-base.d.ts +1 -0
  201. package/dist/knowledge-base.d.ts.map +1 -1
  202. package/dist/knowledge-base.js +20 -8
  203. package/dist/knowledge-base.js.map +1 -1
  204. package/dist/mock-scan.d.ts +1 -2
  205. package/dist/mock-scan.d.ts.map +1 -1
  206. package/dist/mock-scan.js +12 -17
  207. package/dist/mock-scan.js.map +1 -1
  208. package/dist/models.d.ts +10 -1
  209. package/dist/models.d.ts.map +1 -1
  210. package/dist/models.js.map +1 -1
  211. package/dist/multiscan.d.ts.map +1 -1
  212. package/dist/multiscan.js +1 -6
  213. package/dist/multiscan.js.map +1 -1
  214. package/dist/native-json-findings.d.ts +30 -0
  215. package/dist/native-json-findings.d.ts.map +1 -0
  216. package/dist/native-json-findings.js +114 -0
  217. package/dist/native-json-findings.js.map +1 -0
  218. package/dist/opengrep-findings.d.ts +10 -0
  219. package/dist/opengrep-findings.d.ts.map +1 -0
  220. package/dist/opengrep-findings.js +198 -0
  221. package/dist/opengrep-findings.js.map +1 -0
  222. package/dist/owner-evidence.d.ts +2 -0
  223. package/dist/owner-evidence.d.ts.map +1 -1
  224. package/dist/owner-evidence.js +2 -1
  225. package/dist/owner-evidence.js.map +1 -1
  226. package/dist/patch-tui.d.ts.map +1 -1
  227. package/dist/patch-tui.js +2 -0
  228. package/dist/patch-tui.js.map +1 -1
  229. package/dist/publication.js +1 -2
  230. package/dist/publication.js.map +1 -1
  231. package/dist/publish.d.ts +2 -0
  232. package/dist/publish.d.ts.map +1 -1
  233. package/dist/publish.js +1 -1
  234. package/dist/publish.js.map +1 -1
  235. package/dist/record.d.ts +1 -0
  236. package/dist/record.d.ts.map +1 -1
  237. package/dist/record.js +10 -0
  238. package/dist/record.js.map +1 -1
  239. package/dist/remediation.d.ts +1 -25
  240. package/dist/remediation.d.ts.map +1 -1
  241. package/dist/remediation.js +3 -24
  242. package/dist/remediation.js.map +1 -1
  243. package/dist/result.d.ts +5 -3
  244. package/dist/result.d.ts.map +1 -1
  245. package/dist/result.js +9 -6
  246. package/dist/result.js.map +1 -1
  247. package/dist/runtime.d.ts.map +1 -1
  248. package/dist/runtime.js +7 -7
  249. package/dist/runtime.js.map +1 -1
  250. package/dist/scan-dashboard.d.ts +5 -3
  251. package/dist/scan-dashboard.d.ts.map +1 -1
  252. package/dist/scan-dashboard.js +79 -26
  253. package/dist/scan-dashboard.js.map +1 -1
  254. package/dist/scan-history-renderer.d.ts.map +1 -1
  255. package/dist/scan-history-renderer.js +9 -3
  256. package/dist/scan-history-renderer.js.map +1 -1
  257. package/dist/scan-owner-suggestions.d.ts +1 -1
  258. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  259. package/dist/scan-owner-suggestions.js +4 -4
  260. package/dist/scan-owner-suggestions.js.map +1 -1
  261. package/dist/scan-usage-display.d.ts +8 -0
  262. package/dist/scan-usage-display.d.ts.map +1 -0
  263. package/dist/scan-usage-display.js +46 -0
  264. package/dist/scan-usage-display.js.map +1 -0
  265. package/dist/scanner-import.d.ts +1 -1
  266. package/dist/scanner-import.d.ts.map +1 -1
  267. package/dist/scanner-import.js +7 -3
  268. package/dist/scanner-import.js.map +1 -1
  269. package/dist/security-policy.d.ts.map +1 -1
  270. package/dist/security-policy.js +17 -22
  271. package/dist/security-policy.js.map +1 -1
  272. package/dist/semgrep-findings.d.ts +4 -3
  273. package/dist/semgrep-findings.d.ts.map +1 -1
  274. package/dist/semgrep-findings.js +22 -89
  275. package/dist/semgrep-findings.js.map +1 -1
  276. package/dist/skill-authentication.d.ts +18 -0
  277. package/dist/skill-authentication.d.ts.map +1 -0
  278. package/dist/skill-authentication.js +82 -0
  279. package/dist/skill-authentication.js.map +1 -0
  280. package/dist/snyk-findings.d.ts +5 -4
  281. package/dist/snyk-findings.d.ts.map +1 -1
  282. package/dist/snyk-findings.js +18 -17
  283. package/dist/snyk-findings.js.map +1 -1
  284. package/dist/suggest-owners.d.ts +4 -1
  285. package/dist/suggest-owners.d.ts.map +1 -1
  286. package/dist/suggest-owners.js +53 -21
  287. package/dist/suggest-owners.js.map +1 -1
  288. package/dist/targets.d.ts.map +1 -1
  289. package/dist/targets.js +4 -1
  290. package/dist/targets.js.map +1 -1
  291. package/dist/wiz-csv.d.ts +2 -1
  292. package/dist/wiz-csv.d.ts.map +1 -1
  293. package/dist/wiz-csv.js +3 -3
  294. package/dist/wiz-csv.js.map +1 -1
  295. package/dist/wiz-findings.d.ts +2 -1
  296. package/dist/wiz-findings.d.ts.map +1 -1
  297. package/dist/wiz-findings.js +27 -23
  298. package/dist/wiz-findings.js.map +1 -1
  299. package/docs/classify-severity-records.md +3 -4
  300. package/docs/cli.md +171 -41
  301. package/docs/dedupe-records.md +15 -1
  302. package/docs/findings-service.md +119 -118
  303. package/docs/hosted-remediation.md +19 -17
  304. package/docs/hosted-scans.md +37 -11
  305. package/package.json +9 -9
  306. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  307. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  308. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -20,21 +20,44 @@ DISPOSITION_LABELS = {
20
20
  "needs_follow_up": "Needs follow-up",
21
21
  }
22
22
  WRITEUP_REPORT_PATH_RE = re.compile(r"^findings/([a-z0-9][a-z0-9._-]*)/\1\.md$")
23
+ INLINE_CODE_RE = r"(?<!`)`[^`\n]+`(?!`)"
24
+ ENTITY_AMP_RE = r"&(?=(?:#[0-9]+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]*);)"
25
+ WWW_LINK_RE = r"(?<![^\s*_~(])(?i:www)\.[^\s<>]+"
23
26
 
24
27
 
25
28
  class ReportProjectionError(ValueError):
26
29
  """Raised when a canonical scan cannot be projected into a valid report."""
27
30
 
28
31
 
32
+ def _escape_markdown(value: str) -> str:
33
+ # Locate whole URLs before matching code spans: a URL can contain backticks.
34
+ urls = [match.span() for match in re.finditer(WWW_LINK_RE, value)]
35
+ # Preserve protocol-relative and fuzzy links without a domain/TLD table.
36
+ for match in re.finditer(r"[^\s<>]+", value):
37
+ token = match[0]
38
+ dot = token.split("/", 1)[0].find(".")
39
+ if "//" in token or (dot >= 0 and re.search(r"[/?#]", token[dot + 1 :])):
40
+ urls.append(match.span())
41
+ punctuation = r"[\\`*_\[\]<>]|" + ENTITY_AMP_RE
42
+ pattern = f"(?P<code>{INLINE_CODE_RE})|{punctuation}"
43
+
44
+ def escape(match: re.Match[str]) -> str:
45
+ if match.lastgroup == "code":
46
+ return match[0]
47
+ # GFM autolinks retain backslashes literally, including in query strings.
48
+ if match[0] == "&" and any(start <= match.start() < end for start, end in urls):
49
+ return "&"
50
+ return "\\" + match[0]
51
+
52
+ return re.sub(pattern, escape, value)
53
+
54
+
29
55
  def _text(value: Any, fallback: str) -> str:
30
56
  candidate = value if isinstance(value, str) and value.strip() else fallback
31
57
  normalized = " ".join(candidate.split())
32
58
  if re.match(r"^(?:#{1,6}\s|[-*+]\s|>\s|```|~~~|\d+[.)]\s|\|)", normalized):
33
59
  normalized = f"Text: {normalized}"
34
- return "".join(
35
- part if index % 2 else re.sub(r"([\\`*_\[\]<>])", r"\\\1", part)
36
- for index, part in enumerate(re.split(r"((?<!`)`[^`\n]+`(?!`))", normalized))
37
- )
60
+ return _escape_markdown(normalized)
38
61
 
39
62
 
40
63
  def _strings(value: Any) -> list[str]:
@@ -45,18 +68,19 @@ def _strings(value: Any) -> list[str]:
45
68
  return [text for item in value if (text := _text(item, ""))]
46
69
 
47
70
 
48
- def _path_label(value: str) -> str:
71
+ def _path_label(value: str, *, ensure_ascii: bool = False) -> str:
49
72
  if "," in value or value != " ".join(value.split()) or any(ord(c) < 32 for c in value):
50
- quoted = json.dumps(value, ensure_ascii=False)
73
+ quoted = json.dumps(value, ensure_ascii=ensure_ascii)
51
74
  return "".join(c if c.isprintable() else json.dumps(c)[1:-1] for c in quoted)
52
75
  return value
53
76
 
54
77
 
55
- def _path_text(value: str) -> str:
56
- label = _path_label(value)
57
- if label != value:
78
+ def _path_text(value: str, *, ensure_ascii: bool = False) -> str:
79
+ label = _path_label(value, ensure_ascii=ensure_ascii)
80
+ if label != value or re.search(ENTITY_AMP_RE, value):
58
81
  marker = _code_fence(label, minimum=1)
59
- return f"{marker}{label}{marker}"
82
+ padding = " " if label.startswith("`") or label.endswith("`") else ""
83
+ return f"{marker}{padding}{label}{padding}{marker}"
60
84
  return re.sub(r"([\\`*_\[\]<>])", r"\\\1", value)
61
85
 
62
86
 
@@ -763,6 +787,10 @@ def build_report_markdown(
763
787
  manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]
764
788
  ) -> str:
765
789
  scan = manifest["scan"]
790
+ if "review" in scan and "coverageRef" not in scan:
791
+ from review_state import review_state
792
+
793
+ coverage = review_state(scan)
766
794
  target = scan["target"]
767
795
  scope = scan["scope"]
768
796
  threat_model = scan.get("threatModel") if isinstance(scan.get("threatModel"), dict) else {}
@@ -808,7 +836,6 @@ def build_report_markdown(
808
836
  "",
809
837
  f"- Scan mode: {coverage['mode']}",
810
838
  *_target_scope_lines(target),
811
- f"- Inventory strategy: {coverage['inventoryStrategy']}",
812
839
  f"- Included paths: {', '.join(include_paths) or 'none'}",
813
840
  f"- Excluded paths: {', '.join(exclude_paths) or 'none'}",
814
841
  ]
@@ -850,7 +877,7 @@ def build_report_markdown(
850
877
  *summary_count_lines,
851
878
  f"| Validation mode | {_cell(scope.get('validationMode', 'not recorded'))} |",
852
879
  "",
853
- "Canonical artifacts: `scan-manifest.json`, `findings.json`, and `coverage.json`. This report is a deterministic projection of those files.",
880
+ "Canonical artifacts: `scan-manifest.json` and `findings.json`. This report is a deterministic projection of those files.",
854
881
  "",
855
882
  "## Threat Model",
856
883
  "",
@@ -988,10 +1015,10 @@ def build_report_markdown(
988
1015
  + " |"
989
1016
  )
990
1017
  open_questions = coverage.get("openQuestions", [])
991
- questions = list(open_questions) if isinstance(open_questions, list) else []
1018
+ deferred_questions = []
992
1019
  deferred = coverage.get("deferred", [])
993
1020
  if isinstance(deferred, list):
994
- questions.extend(
1021
+ deferred_questions = [
995
1022
  {
996
1023
  "question": item.get("reason", "Deferred review requires follow-up."),
997
1024
  "followUpPrompt": " ".join(
@@ -1008,9 +1035,14 @@ def build_report_markdown(
1008
1035
  }
1009
1036
  for item in deferred
1010
1037
  if isinstance(item, dict)
1011
- )
1012
- if questions:
1013
- lines.extend(["", "## Open Questions And Follow Up", ""])
1038
+ ]
1039
+ for heading, questions in (
1040
+ ("Deferred Requested Work", deferred_questions),
1041
+ ("Open Questions And Follow Up", open_questions),
1042
+ ):
1043
+ if not isinstance(questions, list) or not questions:
1044
+ continue
1045
+ lines.extend(["", f"## {heading}", ""])
1014
1046
  for question in questions:
1015
1047
  if not isinstance(question, dict):
1016
1048
  continue
@@ -0,0 +1,68 @@
1
+ """Keep review bookkeeping separate from published scan results."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import copy
7
+ from typing import Any
8
+
9
+
10
+ def uses_legacy_review(scan: dict[str, Any]) -> bool:
11
+ return "coverageRef" in scan or ("reviewState" not in scan and "review" not in scan)
12
+
13
+
14
+ def review_summary(state: dict[str, Any]) -> dict[str, Any]:
15
+ return {
16
+ "excludedPaths": [item["pattern"] for item in state.get("explicitExclusions", [])],
17
+ }
18
+
19
+
20
+ def review_state(scan: dict[str, Any]) -> dict[str, Any]:
21
+ """Read new manifest metadata using the recovery code's existing representation."""
22
+ summary = scan.get("review", {})
23
+ state = copy.deepcopy(scan.get("reviewState", {}))
24
+ mode = scan.get("mode", "repository")
25
+ state.setdefault("surfaces", [])
26
+ state.setdefault("deferred", [])
27
+ state.setdefault(
28
+ "explicitExclusions",
29
+ [
30
+ {"pattern": path, "reason": "Excluded from review"}
31
+ for path in summary.get("excludedPaths", [])
32
+ ],
33
+ )
34
+ state.update(
35
+ documentType="codex-security.coverage",
36
+ schemaVersion="1.0",
37
+ scanId=scan.get("id"),
38
+ mode=mode,
39
+ inventoryStrategy="scoped_path"
40
+ if mode == "scoped_path"
41
+ else "diff"
42
+ if mode in {"diff", "commit", "branch_diff", "working_tree"}
43
+ else "repository",
44
+ includePaths=copy.deepcopy(scan.get("scope", {}).get("includePaths", [])),
45
+ excludePaths=copy.deepcopy(scan.get("scope", {}).get("excludePaths", [])),
46
+ )
47
+ return state
48
+
49
+
50
+ def checkpoint_review_state(state: dict[str, Any]) -> dict[str, Any]:
51
+ """Retain unfinished work and candidate outcomes, without a coverage report."""
52
+ return {
53
+ "surfaces": [
54
+ {key: copy.deepcopy(value) for key, value in item.items() if key != "riskArea"}
55
+ for item in state.get("surfaces", [])
56
+ ],
57
+ "explicitExclusions": copy.deepcopy(state.get("explicitExclusions", [])),
58
+ "deferred": copy.deepcopy(state.get("deferred", [])),
59
+ **{
60
+ key: copy.deepcopy(state[key])
61
+ for key in ("resolvedDeferred", "openQuestions", "reviews")
62
+ if key in state
63
+ },
64
+ }
65
+
66
+
67
+ if __name__ == "__main__":
68
+ argparse.ArgumentParser(description=__doc__).parse_args()
@@ -101,10 +101,12 @@ def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> lis
101
101
  included = scope.get("includePaths") if isinstance(scope, dict) else None
102
102
  if not isinstance(included, list) or not all(isinstance(path, str) for path in included):
103
103
  return [f"- {label}: not recorded"]
104
- lines = [f"- {label}: {text(', '.join(included), 'none')}"]
104
+ included_text = ", ".join(report._path_text(path, ensure_ascii=True) for path in included)
105
+ lines = [f"- {label}: {included_text or 'none'}"]
105
106
  excluded = scope.get("excludePaths")
106
107
  if isinstance(excluded, list) and excluded and all(isinstance(path, str) for path in excluded):
107
- lines.append(f"- {label} exclusions: {text(', '.join(excluded), 'none')}")
108
+ excluded_text = ", ".join(report._path_text(path, ensure_ascii=True) for path in excluded)
109
+ lines.append(f"- {label} exclusions: {excluded_text or 'none'}")
108
110
  summary = scope.get("summary")
109
111
  if isinstance(summary, str) and summary:
110
112
  lines.append(f"- {label} description: {text(summary, 'not recorded')}")
@@ -41,7 +41,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:
41
41
  "scanDir": str(scan_dir),
42
42
  "manifest": manifest,
43
43
  "findings": findings,
44
- "coverage": coverage,
44
+ "review": FINALIZER.review_summary(coverage),
45
45
  }
46
46
 
47
47
 
@@ -53,7 +53,6 @@ def receipt(validated: dict[str, Any]) -> dict[str, Any]:
53
53
  "scanDir": str(scan_dir),
54
54
  "manifestPath": str(scan_dir / "scan-manifest.json"),
55
55
  "findingsPath": str(scan_dir / scan["findingsRef"]),
56
- "coveragePath": str(scan_dir / scan["coverageRef"]),
57
56
  "reportPath": str(scan_dir / "report.md"),
58
57
  }
59
58
 
@@ -40,6 +40,10 @@ class WindowsScanLocalFileError(OSError):
40
40
  """Raised when a scan-local operation cannot be completed securely."""
41
41
 
42
42
 
43
+ class WindowsScanLocalPathError(WindowsScanLocalFileError):
44
+ """Raised when a scan-local path fails an integrity check."""
45
+
46
+
43
47
  # CreateFile access and sharing flags.
44
48
  _DELETE = 0x00010000
45
49
  _FILE_READ_ATTRIBUTES = 0x00000080
@@ -73,6 +77,7 @@ _ERROR_LOCK_VIOLATION = 33
73
77
  _ERROR_FILE_EXISTS = 80
74
78
  _ERROR_INSUFFICIENT_BUFFER = 122
75
79
  _ERROR_ALREADY_EXISTS = 183
80
+ _ERROR_DIRECTORY = 267
76
81
  _DACL_SECURITY_INFORMATION = 0x00000004
77
82
  _MISSING_ERRORS = {_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND}
78
83
  _COLLISION_ERRORS = {_ERROR_FILE_EXISTS, _ERROR_ALREADY_EXISTS}
@@ -261,8 +266,8 @@ def _raise_last_error(operation: str, path: Path | None = None) -> None:
261
266
  raise WindowsScanLocalFileError(error, f"{operation}{target}: {detail}", str(path or ""))
262
267
 
263
268
 
264
- def _invalid_path(path: Path | str, reason: str) -> WindowsScanLocalFileError:
265
- return WindowsScanLocalFileError(errno.EINVAL, reason, str(path))
269
+ def _invalid_path(path: Path | str, reason: str) -> WindowsScanLocalPathError:
270
+ return WindowsScanLocalPathError(errno.EINVAL, reason, str(path))
266
271
 
267
272
 
268
273
  def _validated_parts(relative_path: str) -> tuple[str, ...]:
@@ -429,21 +434,32 @@ def _canonical_scan_directory(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
429
434
  expected = absolute.lstat()
430
435
  canonical = absolute.resolve(strict=True)
431
436
  except OSError as exc:
437
+ if exc.errno not in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
438
+ raise
432
439
  raise _invalid_path(scan_dir, "expected an existing scan directory") from exc
433
440
  if _normalized_windows_path(absolute) != _normalized_windows_path(canonical):
434
441
  raise _invalid_path(scan_dir, "scan directory must be canonical and non-reparse")
435
442
  return canonical, (expected.st_dev, expected.st_ino)
436
443
 
437
444
 
438
- def _open_directory(path: Path, *, missing_ok: bool = False) -> _OwnedHandle | None:
439
- handle = _create_file(
440
- path,
441
- access=_FILE_READ_ATTRIBUTES,
442
- share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
443
- disposition=_OPEN_EXISTING,
444
- flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
445
- missing_ok=missing_ok,
446
- )
445
+ def _open_directory(
446
+ path: Path, *, missing_ok: bool = False, missing_is_path_error: bool = True
447
+ ) -> _OwnedHandle | None:
448
+ try:
449
+ handle = _create_file(
450
+ path,
451
+ access=_FILE_READ_ATTRIBUTES,
452
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
453
+ disposition=_OPEN_EXISTING,
454
+ flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
455
+ missing_ok=missing_ok,
456
+ )
457
+ except WindowsScanLocalFileError as exc:
458
+ if exc.errno != _ERROR_DIRECTORY and not (
459
+ missing_is_path_error and exc.errno in _MISSING_ERRORS
460
+ ):
461
+ raise
462
+ raise _invalid_path(path, f"could not open scan-local directory: {exc}") from exc
447
463
  if handle is not None:
448
464
  try:
449
465
  assert handle.value is not None
@@ -489,6 +505,7 @@ def _locked_parent(
489
505
  relative_path: str,
490
506
  *,
491
507
  create: bool,
508
+ missing_is_path_error: bool = True,
492
509
  expected_root_identity: tuple[int, int] | None = None,
493
510
  ) -> Iterator[tuple[Path, str]]:
494
511
  """Hold non-deletable handles for every directory in the absolute target path."""
@@ -507,7 +524,14 @@ def _locked_parent(
507
524
  directory_handle = _open_directory(directory_path)
508
525
  assert directory_handle is not None
509
526
  handles.append(directory_handle)
510
- current_root = root_path.lstat()
527
+ try:
528
+ current_root = root_path.lstat()
529
+ except OSError as exc:
530
+ if exc.errno not in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
531
+ raise
532
+ raise _invalid_path(
533
+ scan_dir, f"scan directory changed while it was being opened: {exc}"
534
+ ) from exc
511
535
  current_root_identity = (current_root.st_dev, current_root.st_ino)
512
536
  if current_root_identity != observed_root_identity or (
513
537
  expected_root_identity is not None and current_root_identity != expected_root_identity
@@ -516,7 +540,9 @@ def _locked_parent(
516
540
  current_path = root_path
517
541
  for component in parts[:-1]:
518
542
  current_path /= component
519
- child_handle = _open_directory(current_path, missing_ok=create)
543
+ child_handle = _open_directory(
544
+ current_path, missing_ok=create, missing_is_path_error=missing_is_path_error
545
+ )
520
546
  if child_handle is None:
521
547
  _create_directory(current_path)
522
548
  child_handle = _open_directory(current_path)
@@ -546,7 +572,10 @@ def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) ->
546
572
  """Return the descriptor and its filename while the verified parents are held."""
547
573
 
548
574
  try:
549
- with _locked_parent(scan_dir, relative_path, create=False) as (parent_path, leaf_name):
575
+ with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (
576
+ parent_path,
577
+ leaf_name,
578
+ ):
550
579
  path = parent_path / leaf_name
551
580
  handle = _create_file(
552
581
  path,