@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
package/README.md CHANGED
@@ -36,10 +36,6 @@ are unavailable when reading saved activity or attaching scan logs to feedback,
36
36
  scans whose original session is compressed cannot resume. Plain `.jsonl` logs
37
37
  work on all supported runtimes.
38
38
 
39
- `LocalPluginBootstrapError` identifies local plugin setup failures and extends
40
- `PluginBootstrapError`, so existing catches keep working. Knowledge-base
41
- preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
42
-
43
39
  ### Install the CLI
44
40
 
45
41
  Install the CLI globally:
@@ -187,13 +183,17 @@ directory must be private to you (`chmod 700`).
187
183
  | --------------------------------- | ---------------------------------------------------------------- |
188
184
  | `findings.findings` | Findings from this scan. |
189
185
  | `reportPath` | Path to the Markdown report. |
190
- | `coverage` | What the scan assessed and any coverage gaps. |
186
+ | `review` | Additional excluded paths. This is not file coverage. |
191
187
  | `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
192
188
  | `sarifPath` | SARIF export path, or `null`. |
193
189
  | `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
194
190
  | `cost` | Estimated model usage cost, or `null` when unavailable. |
195
191
 
196
- Review coverage alongside findings. A report with no findings does not establish
192
+ Review the requested paths and exclusions alongside the execution outcome.
193
+ `reviewState.deferred` records unfinished requested work, while
194
+ `reviewState.openQuestions` records optional follow-up separately.
195
+
196
+ Review the scan status and scope alongside findings. A report with no findings does not establish
197
197
  that the repository is secure. Reports and logs can contain source code,
198
198
  vulnerability details, and credentials; review them before sharing.
199
199
 
@@ -243,9 +243,12 @@ files can set `scan.owner_suggestions: true`. The report uses the scan's finding
243
243
  IDs and frozen revision; it does not change the sealed findings or assign users.
244
244
  Owner failures leave the base scan completed and appear as
245
245
  `result.ownerSuggestionsError`; successful reports set `result.ownerSuggestionsPath`.
246
- Owner inference uses the scan's model and reasoning effort. Owner enrichment is
247
- skipped with a warning when `maxCostUsd` is set, because its inference cannot yet
248
- share the scan cost limit. Working-tree and directory snapshots are unsupported.
246
+ The scan records optional owner hints within its existing session and budget.
247
+ Report finalization applies CODEOWNERS and validates Git evidence without another
248
+ model call, including when `maxCostUsd` is set. Missing hints abstain and invalid
249
+ hints produce per-finding errors. Working-tree and directory snapshots are
250
+ unsupported. Explicit owner-only analysis remains available through `suggestOwners`
251
+ and `suggest-owners`, sharing the same evidence validation and report code.
249
252
 
250
253
  ### Scan a diff
251
254
 
@@ -278,6 +281,7 @@ const security = new CodexSecurity({
278
281
  Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.
279
282
  The bundled runtime and plugin are used by default. `pythonPath` overrides the
280
283
  `PYTHON` environment variable. To choose a model, set `codexOverrides.model`.
284
+ For a custom `pluginPath`, check [custom plugin compatibility](#custom-plugins).
281
285
 
282
286
  To enable Daybreak on Codex 0.163.0 or later, set `codexOverrides.daybreak: true`.
283
287
  The toggle defaults off; an explicit `false` keeps it off. The setting reaches
@@ -286,21 +290,8 @@ isolated configuration, so a desktop toggle or personal Codex configuration does
286
290
  not configure an SDK scan. See [Daybreak opt-in](docs/cli.md#daybreak-opt-in) for
287
291
  CLI, project-file, and direct plugin configuration.
288
292
 
289
- New and resumed Deep Scans require a current plugin with
290
- `directDeepScanEngine: 1`, `workerProviderSnapshot: 4`, and isolated worker
291
- configuration support. Older custom plugins fail before scan execution; update
292
- the plugin or omit `pluginPath` to use the bundled version. Discovery, reducer,
293
- and resumed workers inherit per-scan provider, authentication, environment, and
294
- executable settings, with their existing read-only permissions. Reading saved
295
- reports does not require these execution capabilities.
296
-
297
- The SDK no longer adapts the older `node ./mcp/server.mjs` MCP entrypoint; use
298
- the current shell or Windows launcher for runtime-root routing.
299
-
300
- Custom plugins must support the current workbench protocol for scan comparison
301
- and archival. Update an older custom plugin or omit `pluginPath` to use the
302
- bundled version. The SDK no longer adapts payloads or archives scan directories
303
- on behalf of older workbench implementations.
293
+ Deep Scan discovery, reducer, and resumed workers inherit per-scan provider,
294
+ authentication, environment, and executable settings with read-only permissions.
304
295
 
305
296
  Scans use an isolated Codex configuration. See
306
297
  [runtime configuration](docs/cli.md#runtime-configuration-and-worker-limits)
@@ -394,6 +385,10 @@ Deep discovery retains its enforced deadline, with a default and maximum of
394
385
  ### Progress and cost
395
386
 
396
387
  Use `onProgress` for scan progress and `onCost` for cost updates.
388
+ Use `onUsageObservation` for the last reported token measurement time
389
+ (`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
390
+ Each reading includes its own `observedAt` timestamp and the percentage used in
391
+ each reported window. A limit-only update can arrive before any token measurement.
397
392
 
398
393
  Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
399
394
  persisted worker sessions discovered by the SDK's existing session tracker,
@@ -423,19 +418,15 @@ or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or
423
418
  stopping the scan.
424
419
 
425
420
  `onWorkerStatus` reports **best-effort** phase dispatch counts from model-emitted
426
- text markers. The former helper-derived `kind: "preflight"` event is retired;
427
- scans use available runtime tools and parent fallback without a capability registry.
428
- The plugin's `config_preflight.py` helper and custom capability registries are no
429
- longer supported, including the `preflightChecks` progress-tool input and workbench
430
- `--preflight-issues-json` / `--preflight-issues-json-stdin` arguments. Saved preflight
431
- history remains readable. Local `preflight()` input checks, authentication,
432
- sandbox enforcement, and Deep worker configuration still apply. A missing
433
- dispatch status does not mean delegation was skipped. `onSessionEvent` receives
434
- saved events with thread IDs and worker numbers and can contain source code or
435
- credentials. Deep scans additionally expose durable independent-review counts
436
- through `onDeepProgress`: `completed`, `active`, and `maximum`. The maximum is a
437
- configured cap, not a percentage denominator. The optional `consolidating` flag
438
- reports when results are being combined or the coordinator has finished.
421
+ text markers. A missing dispatch status does not mean delegation was skipped.
422
+ For retired progress hooks, see [older progress integrations](#older-progress-integrations).
423
+
424
+ `onSessionEvent` receives saved events with thread IDs and worker numbers and can
425
+ contain source code or credentials. Deep scans additionally expose durable
426
+ independent-review counts through `onDeepProgress`: `completed`, `active`, and
427
+ `maximum`. The maximum is a configured cap, not a percentage denominator. The
428
+ optional `consolidating` flag reports when results are being combined or the
429
+ coordinator has finished.
439
430
  `ScanOptions` lists all callbacks.
440
431
 
441
432
  Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
@@ -653,6 +644,14 @@ grant Cloud access. See [Cloud publication](docs/cli.md#publish-findings-to-clou
653
644
  for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)
654
645
  for issue creation.
655
646
 
647
+ External vendor imports are opt-in. Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`
648
+ to enable `publish findings`, `findings imported`, `import github-advisories`, and
649
+ the SDK's external publication, local import/readback, and advisory acquisition
650
+ APIs. They are disabled otherwise; CLI commands are hidden from help and schemas.
651
+ SDK callers can supply the flag through the existing per-call
652
+ `dependencies.environment`. Pure normalizers and file readers remain available.
653
+ This does not affect scan publishing or the existing GitHub alert collector.
654
+
656
655
  The SDK also exposes `prepareExternalPublication(file, options)` for supported
657
656
  vendor exports and `prepareNormalizedExternalPublication(findings, options)` for
658
657
  normalized external evidence from any provider in the Cloud import contract.
@@ -668,6 +667,12 @@ options where supported, and changing formats can change record identities or
668
667
  replace richer evidence with less detail. See the
669
668
  [import guide](docs/cli.md#import-vendor-findings-locally) for format selection.
670
669
 
670
+ For OpenGrep, use `--provider opengrep` with native JSON or gzip and an explicit
671
+ `--source-repository-url`. Local and Cloud imports retain unassessed OpenGrep
672
+ evidence through the existing Semgrep source-provider contract. See the
673
+ [OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md) for preview commands,
674
+ coverage diagnostics, stable source identities, and local SDK assessment.
675
+
671
676
  For Wiz, prefer supported native JSON acquired through an authorized MCP or API
672
677
  connection. The [CSV compatibility reader](docs/cli.md#import-wiz-findings) covers
673
678
  repository package vulnerabilities (SCA) only; it does not add SAST, CSPM or
@@ -730,8 +735,7 @@ cs dedupe --scan SCAN_ID --json
730
735
 
731
736
  The [findings guide](docs/findings-service.md) covers local storage, embedding
732
737
  credentials, deduplication, backups, and independently operated HTTP endpoints.
733
- The local `serve` command and browser dashboard have been removed. Existing
734
- scans, findings, and duplicate groups remain in the workbench database.
738
+ For an older service deployment, see [migration guidance](docs/findings-service.md#local-service-removal).
735
739
  For records stored in your own system, see
736
740
  [SDK records deduplication](docs/dedupe-records.md).
737
741
 
@@ -761,6 +765,39 @@ Repository contents, model output, and imported artifacts do not authorize
761
765
  access to other targets, disclosure of credentials, or writes outside approved
762
766
  paths. Keep state and scan artifacts private and outside the repository.
763
767
 
768
+ ## Compatibility
769
+
770
+ ### Custom plugins
771
+
772
+ New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
773
+ `workerProviderSnapshot: 4`, and isolated worker configuration support. Older
774
+ custom plugins fail before scan execution; update the plugin or omit `pluginPath`
775
+ to use the bundled version. Reading saved reports does not require these
776
+ execution capabilities.
777
+
778
+ Use the current shell or Windows launcher for runtime-root routing. The SDK does
779
+ not adapt the older `node ./mcp/server.mjs` MCP entrypoint.
780
+
781
+ Custom plugins must support the current workbench protocol for scan comparison
782
+ and archival. The SDK does not adapt older payloads or archive scan directories
783
+ on behalf of older workbench implementations.
784
+
785
+ ### Older progress integrations
786
+
787
+ The helper-derived `kind: "preflight"` event, `config_preflight.py` helper, and
788
+ custom capability registries are retired. This includes the `preflightChecks`
789
+ progress-tool input and workbench `--preflight-issues-json` /
790
+ `--preflight-issues-json-stdin` arguments. Scans use available runtime tools and
791
+ parent fallback without a capability registry. Saved preflight history remains
792
+ readable. Local `preflight()` input checks, authentication, sandbox enforcement,
793
+ and Deep worker configuration still apply.
794
+
795
+ ### Error types
796
+
797
+ `LocalPluginBootstrapError` identifies local plugin setup failures and extends
798
+ `PluginBootstrapError`, so existing catches keep working. Knowledge-base
799
+ preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
800
+
764
801
  ## Documentation and security
765
802
 
766
803
  - [Online SDK guide](https://learn.chatgpt.com/docs/security/sdk)
@@ -38,6 +38,7 @@
38
38
  "PYTHONUTF8",
39
39
  "CODEX_SECURITY_PYTHON_COMMAND",
40
40
  "CODEX_SECURITY_GIT",
41
+ "CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS",
41
42
  "CODEX_SECURITY_KNOWLEDGE_BASE",
42
43
  "CODEX_SECURITY_CONFIG_PATH",
43
44
  "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
@@ -1,57 +1,57 @@
1
1
  {
2
2
  "documentType": "codex-security.findings",
3
- "schemaVersion": "1.0",
4
- "scanId": "scan_example_001",
5
3
  "findings": [
6
4
  {
7
- "findingId": "csf_852f90d6e1177502ff113d4a",
8
- "occurrenceId": "occ_e79cb19591e696572a1c22be",
9
- "ruleId": "path-traversal.archive-extraction",
10
- "identity": {
11
- "anchor": "archive-entry-write-without-containment"
5
+ "attackPath": null,
6
+ "confidence": {
7
+ "level": "high",
8
+ "rationale": "Direct source trace reaches the filesystem write without a containment check."
12
9
  },
10
+ "extensions": {},
11
+ "findingId": "csf_852f90d6e1177502ff113d4a",
13
12
  "fingerprints": {
14
13
  "algorithm": "codex-security/v1",
15
14
  "primary": "codex-security/v1:sha256:990a4a6a2ec18440dd47eac4d7256c0ee2c02db1b43104720cab3cbe9db706ca"
16
15
  },
17
- "title": "Unsafe archive extraction can escape the output directory",
18
- "summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
19
- "severity": {
20
- "level": "high",
21
- "score": 8.1,
22
- "scoringSystem": "CVSS:3.1"
23
- },
24
- "confidence": {
25
- "level": "high",
26
- "rationale": "Direct source trace reaches the filesystem write without a containment check."
27
- },
28
- "taxonomy": {
29
- "category": "path-traversal",
30
- "cwe": [
31
- "CWE-22"
32
- ]
16
+ "identity": {
17
+ "anchor": "archive-entry-write-without-containment"
33
18
  },
34
19
  "locations": [
35
20
  {
36
- "path": "src/extract.py",
37
- "startLine": 41,
38
21
  "endLine": 44,
39
- "role": "sink"
22
+ "path": "src/extract.py",
23
+ "role": "sink",
24
+ "startLine": 41
40
25
  }
41
26
  ],
42
- "remediation": "Normalize destinations and reject entries that escape the extraction root.",
43
- "validation": null,
44
- "attackPath": null,
45
- "remediationTests": [
46
- "Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
47
- ],
27
+ "occurrenceId": "occ_e79cb19591e696572a1c22be",
48
28
  "preventiveControls": [
49
29
  "Route all archive extraction through one helper that normalizes and validates destination paths."
50
30
  ],
51
31
  "provenance": {
52
32
  "source": "local_plugin"
53
33
  },
54
- "extensions": {}
34
+ "remediation": "Normalize destinations and reject entries that escape the extraction root.",
35
+ "remediationTests": [
36
+ "Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
37
+ ],
38
+ "ruleId": "path-traversal.archive-extraction",
39
+ "severity": {
40
+ "level": "high",
41
+ "score": 8.1,
42
+ "scoringSystem": "CVSS:3.1"
43
+ },
44
+ "summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
45
+ "taxonomy": {
46
+ "category": "path-traversal",
47
+ "cwe": [
48
+ "CWE-22"
49
+ ]
50
+ },
51
+ "title": "Unsafe archive extraction can escape the output directory",
52
+ "validation": null
55
53
  }
56
- ]
54
+ ],
55
+ "scanId": "scan_example_001",
56
+ "schemaVersion": "1.0"
57
57
  }
@@ -9,21 +9,20 @@ The scan was configured for the include paths and exclusions listed below.
9
9
  - Target ID: target\_sha256\_example
10
10
  - Revision: deadbeef
11
11
  - Snapshot digest: codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb
12
- - Inventory strategy: repository
13
12
  - Included paths: .
14
13
  - Excluded paths: none
15
14
 
16
15
  ### Scan Summary
17
16
 
18
- | Field | Value |
19
- | ------------------- | ------------ |
20
- | Scan outcome | completed |
21
- | Reportable findings | 1 |
22
- | Severity mix | high: 1 |
23
- | Confidence mix | high: 1 |
24
- | Validation mode | not recorded |
17
+ | Field | Value |
18
+ | --- | --- |
19
+ | Scan outcome | completed |
20
+ | Reportable findings | 1 |
21
+ | Severity mix | high: 1 |
22
+ | Confidence mix | high: 1 |
23
+ | Validation mode | not recorded |
25
24
 
26
- Canonical artifacts: `scan-manifest.json`, `findings.json`, and `coverage.json`. This report is a deterministic projection of those files.
25
+ Canonical artifacts: `scan-manifest.json` and `findings.json`. This report is a deterministic projection of those files.
27
26
 
28
27
  ## Threat Model
29
28
 
@@ -31,30 +30,30 @@ No explicit canonical threat-model summary was recorded.
31
30
 
32
31
  ## Findings
33
32
 
34
- | Finding | Severity | Confidence | Detailed write-up |
35
- | ----------------------------------------------------------------------- | -------- | ---------- | ----------------- |
36
- | [Unsafe archive extraction can escape the output directory](#finding-1) | high | high | inline below |
33
+ | Finding | Severity | Confidence | Detailed write-up |
34
+ | --- | --- | --- | --- |
35
+ | [Unsafe archive extraction can escape the output directory](#finding-1) | high | high | inline below |
37
36
 
38
37
  ### Confidence Scale
39
38
 
40
- | Label | Meaning |
41
- | ------ | ---------------------------------------------------------------------------------------- |
42
- | high | Direct evidence supports the finding with no material unresolved blocker. |
39
+ | Label | Meaning |
40
+ | --- | --- |
41
+ | high | Direct evidence supports the finding with no material unresolved blocker. |
43
42
  | medium | Evidence supports a plausible issue, but material runtime or reachability proof remains. |
44
- | low | Evidence is incomplete and the item is retained only for explicit follow-up. |
43
+ | low | Evidence is incomplete and the item is retained only for explicit follow-up. |
45
44
 
46
45
  <a id="finding-1"></a>
47
46
 
48
47
  ### [1] Unsafe archive extraction can escape the output directory
49
48
 
50
- | Field | Value |
51
- | -------------------- | ----------------------------------------------------------------------------- |
52
- | Severity | high |
53
- | Confidence | high |
49
+ | Field | Value |
50
+ | --- | --- |
51
+ | Severity | high |
52
+ | Confidence | high |
54
53
  | Confidence rationale | Direct source trace reaches the filesystem write without a containment check. |
55
- | Category | path-traversal |
56
- | CWE | CWE-22 |
57
- | Affected lines | src/extract.py:41-44 |
54
+ | Category | path-traversal |
55
+ | CWE | CWE-22 |
56
+ | Affected lines | src/extract.py:41-44 |
58
57
 
59
58
  #### Summary
60
59
 
@@ -83,15 +82,7 @@ Additional runtime or deployment evidence could raise or lower this severity.
83
82
  Normalize destinations and reject entries that escape the extraction root.
84
83
 
85
84
  Tests:
86
-
87
85
  - Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root.
88
86
 
89
87
  Preventive controls:
90
-
91
88
  - Route all archive extraction through one helper that normalizes and validates destination paths.
92
-
93
- ## Reviewed Surfaces
94
-
95
- | Surface | Risk Area | Outcome | Notes |
96
- | ------------------ | ------------ | -------- | -------------------------------------------- |
97
- | Archive extraction | not recorded | Reported | No additional canonical notes were recorded. |
@@ -1,43 +1,41 @@
1
1
  {
2
2
  "documentType": "codex-security.scan-manifest",
3
- "schemaVersion": "1.0",
4
3
  "scan": {
4
+ "artifacts": [
5
+ {
6
+ "mediaType": "application/json",
7
+ "path": "findings.json",
8
+ "sha256": "fea40b4d1f0b92090f1c0a06f43fa03da5bdf4e7f8bdf8e8a7953ae626600d5b"
9
+ }
10
+ ],
11
+ "completedAt": "2026-05-31T18:09:00Z",
12
+ "findingsRef": "findings.json",
5
13
  "id": "scan_example_001",
14
+ "mode": "repository",
6
15
  "producer": {
7
16
  "name": "codex-security-plugin",
8
17
  "version": "0.1.0"
9
18
  },
10
- "status": "completed",
11
- "startedAt": "2026-05-31T18:00:00Z",
12
- "completedAt": "2026-05-31T18:09:00Z",
13
- "sealedAt": "2026-05-31T18:09:00Z",
14
- "target": {
15
- "kind": "git_worktree",
16
- "targetId": "target_sha256_example",
17
- "displayName": "example/repo",
18
- "remote": "https://github.com/example/repo",
19
- "revision": "deadbeef",
20
- "snapshotDigest": "codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb"
19
+ "review": {
20
+ "excludedPaths": []
21
21
  },
22
22
  "scope": {
23
+ "excludePaths": [],
23
24
  "includePaths": [
24
25
  "."
25
- ],
26
- "excludePaths": []
26
+ ]
27
27
  },
28
- "coverageRef": "coverage.json",
29
- "findingsRef": "findings.json",
30
- "artifacts": [
31
- {
32
- "path": "findings.json",
33
- "sha256": "a6dc4521d6478828224fbafc33585401a47bfeb0e56e07b5d2886e8a29937f2f",
34
- "mediaType": "application/json"
35
- },
36
- {
37
- "path": "coverage.json",
38
- "sha256": "afc715d401f8d28e7cfb0626c89a929b065a97749de70d453973b147e1748651",
39
- "mediaType": "application/json"
40
- }
41
- ]
42
- }
28
+ "sealedAt": "2026-05-31T18:09:00Z",
29
+ "startedAt": "2026-05-31T18:00:00Z",
30
+ "status": "completed",
31
+ "target": {
32
+ "displayName": "example/repo",
33
+ "kind": "git_worktree",
34
+ "remote": "https://github.com/example/repo",
35
+ "revision": "deadbeef",
36
+ "snapshotDigest": "codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb",
37
+ "targetId": "target_sha256_example"
38
+ }
39
+ },
40
+ "schemaVersion": "1.0"
43
41
  }
@@ -3,6 +3,7 @@
3
3
  "schemaVersion": "1.0",
4
4
  "scanId": "scan_example_001",
5
5
  "mode": "repository",
6
+ "completeness": "complete",
6
7
  "inventoryStrategy": "repository",
7
8
  "includePaths": [
8
9
  "."
@@ -0,0 +1,57 @@
1
+ {
2
+ "documentType": "codex-security.findings",
3
+ "schemaVersion": "1.0",
4
+ "scanId": "scan_example_001",
5
+ "findings": [
6
+ {
7
+ "findingId": "csf_852f90d6e1177502ff113d4a",
8
+ "occurrenceId": "occ_e79cb19591e696572a1c22be",
9
+ "ruleId": "path-traversal.archive-extraction",
10
+ "identity": {
11
+ "anchor": "archive-entry-write-without-containment"
12
+ },
13
+ "fingerprints": {
14
+ "algorithm": "codex-security/v1",
15
+ "primary": "codex-security/v1:sha256:990a4a6a2ec18440dd47eac4d7256c0ee2c02db1b43104720cab3cbe9db706ca"
16
+ },
17
+ "title": "Unsafe archive extraction can escape the output directory",
18
+ "summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
19
+ "severity": {
20
+ "level": "high",
21
+ "score": 8.1,
22
+ "scoringSystem": "CVSS:3.1"
23
+ },
24
+ "confidence": {
25
+ "level": "high",
26
+ "rationale": "Direct source trace reaches the filesystem write without a containment check."
27
+ },
28
+ "taxonomy": {
29
+ "category": "path-traversal",
30
+ "cwe": [
31
+ "CWE-22"
32
+ ]
33
+ },
34
+ "locations": [
35
+ {
36
+ "path": "src/extract.py",
37
+ "startLine": 41,
38
+ "endLine": 44,
39
+ "role": "sink"
40
+ }
41
+ ],
42
+ "remediation": "Normalize destinations and reject entries that escape the extraction root.",
43
+ "validation": null,
44
+ "attackPath": null,
45
+ "remediationTests": [
46
+ "Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root."
47
+ ],
48
+ "preventiveControls": [
49
+ "Route all archive extraction through one helper that normalizes and validates destination paths."
50
+ ],
51
+ "provenance": {
52
+ "source": "local_plugin"
53
+ },
54
+ "extensions": {}
55
+ }
56
+ ]
57
+ }
@@ -0,0 +1,98 @@
1
+ # Security Review: example/repo
2
+
3
+ ## Scope
4
+
5
+ The scan was configured for the include paths and exclusions listed below.
6
+
7
+ - Scan mode: repository
8
+ - Target kind: git\_worktree
9
+ - Target ID: target\_sha256\_example
10
+ - Revision: deadbeef
11
+ - Snapshot digest: codex-security-snapshot/v1:sha256:ed88f96a4c1a06603a41b3f261f59c3de2555c367ef6ad3bb8b9e483495d34eb
12
+ - Inventory strategy: repository
13
+ - Included paths: .
14
+ - Excluded paths: none
15
+
16
+ ### Scan Summary
17
+
18
+ | Field | Value |
19
+ | ------------------- | ------------ |
20
+ | Scan outcome | completed |
21
+ | Reportable findings | 1 |
22
+ | Severity mix | high: 1 |
23
+ | Confidence mix | high: 1 |
24
+ | Coverage | complete |
25
+ | Validation mode | not recorded |
26
+
27
+ Canonical artifacts: `scan-manifest.json`, `findings.json`, and `coverage.json`. This report is a deterministic projection of those files.
28
+
29
+ ## Threat Model
30
+
31
+ No explicit canonical threat-model summary was recorded.
32
+
33
+ ## Findings
34
+
35
+ | Finding | Severity | Confidence | Detailed write-up |
36
+ | ----------------------------------------------------------------------- | -------- | ---------- | ----------------- |
37
+ | [Unsafe archive extraction can escape the output directory](#finding-1) | high | high | inline below |
38
+
39
+ ### Confidence Scale
40
+
41
+ | Label | Meaning |
42
+ | ------ | ---------------------------------------------------------------------------------------- |
43
+ | high | Direct evidence supports the finding with no material unresolved blocker. |
44
+ | medium | Evidence supports a plausible issue, but material runtime or reachability proof remains. |
45
+ | low | Evidence is incomplete and the item is retained only for explicit follow-up. |
46
+
47
+ <a id="finding-1"></a>
48
+
49
+ ### [1] Unsafe archive extraction can escape the output directory
50
+
51
+ | Field | Value |
52
+ | -------------------- | ----------------------------------------------------------------------------- |
53
+ | Severity | high |
54
+ | Confidence | high |
55
+ | Confidence rationale | Direct source trace reaches the filesystem write without a containment check. |
56
+ | Category | path-traversal |
57
+ | CWE | CWE-22 |
58
+ | Affected lines | src/extract.py:41-44 |
59
+
60
+ #### Summary
61
+
62
+ An attacker-controlled path reaches a filesystem write without containment validation.
63
+
64
+ #### Validation
65
+
66
+ Direct source trace reaches the filesystem write without a containment check. Validation details were not recorded separately.
67
+
68
+ #### Dataflow
69
+
70
+ The canonical finding records the affected path at src/extract.py:41-44, but no expanded source-to-sink narrative was recorded.
71
+
72
+ #### Reachability
73
+
74
+ Reachability was not recorded beyond the canonical finding summary and affected locations.
75
+
76
+ #### Severity
77
+
78
+ **High** — The scan assigned high severity; no separate canonical severity rationale was recorded.
79
+
80
+ Additional runtime or deployment evidence could raise or lower this severity.
81
+
82
+ #### Remediation
83
+
84
+ Normalize destinations and reject entries that escape the extraction root.
85
+
86
+ Tests:
87
+
88
+ - Assert that extracting an archive entry named `../escape.txt` fails without writing outside the extraction root.
89
+
90
+ Preventive controls:
91
+
92
+ - Route all archive extraction through one helper that normalizes and validates destination paths.
93
+
94
+ ## Reviewed Surfaces
95
+
96
+ | Surface | Risk Area | Outcome | Notes |
97
+ | ------------------ | ------------ | -------- | -------------------------------------------- |
98
+ | Archive extraction | not recorded | Reported | No additional canonical notes were recorded. |