@openai/codex-security 0.4.0 → 0.5.1

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 (290) hide show
  1. package/README.md +52 -9
  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/native/win32-arm64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  6. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +60 -9
  7. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  8. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  9. package/_bundled_plugin/references/core-scan.md +2 -0
  10. package/_bundled_plugin/references/final-report.md +5 -1
  11. package/_bundled_plugin/references/investigation-time-budget.md +11 -0
  12. package/_bundled_plugin/references/sarif-adapter.md +1 -0
  13. package/_bundled_plugin/references/scan-prologue.md +2 -6
  14. package/_bundled_plugin/references/scan-runtime.md +15 -0
  15. package/_bundled_plugin/references/threat-model.md +2 -0
  16. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +6 -2
  17. package/_bundled_plugin/scripts/deep_scan_workbench.py +7 -0
  18. package/_bundled_plugin/scripts/finalize_scan_contract.py +92 -44
  19. package/_bundled_plugin/scripts/finding_preview.py +5 -3
  20. package/_bundled_plugin/scripts/generate_in_scope_files.py +6 -6
  21. package/_bundled_plugin/scripts/generate_rank_input.py +13 -6
  22. package/_bundled_plugin/scripts/launch_codex_security_mcp +39 -4
  23. package/_bundled_plugin/scripts/report_projection.py +2 -1
  24. package/_bundled_plugin/scripts/snapshot_sqlite.py +7 -0
  25. package/_bundled_plugin/scripts/threat_model_projection.py +1 -3
  26. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -1
  27. package/_bundled_plugin/scripts/workbench/saved_coverage.py +234 -0
  28. package/_bundled_plugin/scripts/workbench_cli.py +5 -10
  29. package/_bundled_plugin/scripts/workbench_constants.py +4 -0
  30. package/_bundled_plugin/scripts/workbench_db.py +68 -39
  31. package/_bundled_plugin/scripts/workbench_native_indexes.py +10 -7
  32. package/_bundled_plugin/scripts/workbench_progress.py +0 -50
  33. package/_bundled_plugin/scripts/workbench_publication.py +4 -3
  34. package/_bundled_plugin/scripts/workbench_remediation.py +5 -1
  35. package/_bundled_plugin/scripts/workbench_saved_results.py +542 -148
  36. package/_bundled_plugin/scripts/workbench_scan_history.py +82 -80
  37. package/_bundled_plugin/scripts/workbench_scan_start.py +12 -4
  38. package/_bundled_plugin/scripts/workbench_scan_usage.py +246 -38
  39. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  40. package/_bundled_plugin/scripts/workbench_source_excerpt.py +74 -51
  41. package/_bundled_plugin/scripts/workbench_source_scopes.py +388 -0
  42. package/_bundled_plugin/scripts/workbench_target.py +28 -12
  43. package/_bundled_plugin/scripts/workbench_validation.py +52 -13
  44. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -0
  45. package/_bundled_plugin/shared/workbench-migrations.json +15 -0
  46. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
  47. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +4 -2
  48. package/_bundled_plugin/skills/security-scan/SKILL.md +3 -1
  49. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
  50. package/dist/api.d.ts +4 -3
  51. package/dist/api.d.ts.map +1 -1
  52. package/dist/api.js +215 -93
  53. package/dist/api.js.map +1 -1
  54. package/dist/artifact-export.d.ts +2 -1
  55. package/dist/artifact-export.d.ts.map +1 -1
  56. package/dist/artifact-export.js +38 -23
  57. package/dist/artifact-export.js.map +1 -1
  58. package/dist/classify-scan-severity.d.ts.map +1 -1
  59. package/dist/classify-scan-severity.js +16 -18
  60. package/dist/classify-scan-severity.js.map +1 -1
  61. package/dist/classify-severity-records.d.ts +76 -0
  62. package/dist/classify-severity-records.d.ts.map +1 -0
  63. package/dist/classify-severity-records.js +141 -0
  64. package/dist/classify-severity-records.js.map +1 -0
  65. package/dist/classify-severity.d.ts +1 -23
  66. package/dist/classify-severity.d.ts.map +1 -1
  67. package/dist/classify-severity.js +3 -24
  68. package/dist/classify-severity.js.map +1 -1
  69. package/dist/cli-daybreak.d.ts +5 -0
  70. package/dist/cli-daybreak.d.ts.map +1 -0
  71. package/dist/cli-daybreak.js +89 -0
  72. package/dist/cli-daybreak.js.map +1 -0
  73. package/dist/cli-help.d.ts.map +1 -1
  74. package/dist/cli-help.js +2 -0
  75. package/dist/cli-help.js.map +1 -1
  76. package/dist/cli.d.ts +9 -3
  77. package/dist/cli.d.ts.map +1 -1
  78. package/dist/cli.js +957 -738
  79. package/dist/cli.js.map +1 -1
  80. package/dist/cloud-publish.js +1 -1
  81. package/dist/cloud-publish.js.map +1 -1
  82. package/dist/codeowners.js +2 -2
  83. package/dist/codeowners.js.map +1 -1
  84. package/dist/codex-sdk-environment.js +1 -1
  85. package/dist/codex-sdk-environment.js.map +1 -1
  86. package/dist/component-plan.d.ts.map +1 -1
  87. package/dist/component-plan.js +3 -2
  88. package/dist/component-plan.js.map +1 -1
  89. package/dist/component-scan.js +2 -2
  90. package/dist/component-scan.js.map +1 -1
  91. package/dist/config.d.ts +12 -0
  92. package/dist/config.d.ts.map +1 -1
  93. package/dist/config.js +15 -5
  94. package/dist/config.js.map +1 -1
  95. package/dist/contract.d.ts +5 -0
  96. package/dist/contract.d.ts.map +1 -1
  97. package/dist/contract.js +65 -17
  98. package/dist/contract.js.map +1 -1
  99. package/dist/cost-model.d.ts.map +1 -1
  100. package/dist/cost-model.js +7 -2
  101. package/dist/cost-model.js.map +1 -1
  102. package/dist/cost.d.ts +2 -1
  103. package/dist/cost.d.ts.map +1 -1
  104. package/dist/cost.js +17 -8
  105. package/dist/cost.js.map +1 -1
  106. package/dist/custom-validation-prompt.js +3 -3
  107. package/dist/custom-validation-prompt.js.map +1 -1
  108. package/dist/custom-validation.d.ts.map +1 -1
  109. package/dist/custom-validation.js +2 -5
  110. package/dist/custom-validation.js.map +1 -1
  111. package/dist/deduplication/codex-review.d.ts.map +1 -1
  112. package/dist/deduplication/codex-review.js +8 -6
  113. package/dist/deduplication/codex-review.js.map +1 -1
  114. package/dist/deduplication/deduplication-prompts.d.ts +1 -1
  115. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  116. package/dist/deduplication/deduplication-prompts.js +2 -2
  117. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  118. package/dist/deduplication/local.d.ts.map +1 -1
  119. package/dist/deduplication/local.js +5 -2
  120. package/dist/deduplication/local.js.map +1 -1
  121. package/dist/deduplication/records.js +1 -1
  122. package/dist/deduplication/records.js.map +1 -1
  123. package/dist/deduplication/retry.d.ts.map +1 -1
  124. package/dist/deduplication/retry.js +5 -0
  125. package/dist/deduplication/retry.js.map +1 -1
  126. package/dist/deduplication/scan.d.ts.map +1 -1
  127. package/dist/deduplication/scan.js +15 -10
  128. package/dist/deduplication/scan.js.map +1 -1
  129. package/dist/deep-config.d.ts +4 -1
  130. package/dist/deep-config.d.ts.map +1 -1
  131. package/dist/deep-config.js +21 -1
  132. package/dist/deep-config.js.map +1 -1
  133. package/dist/deep-scan.d.ts +6 -0
  134. package/dist/deep-scan.d.ts.map +1 -1
  135. package/dist/deep-scan.js +8 -6
  136. package/dist/deep-scan.js.map +1 -1
  137. package/dist/findings-import.d.ts +1 -1
  138. package/dist/findings-import.d.ts.map +1 -1
  139. package/dist/findings-import.js +26 -6
  140. package/dist/findings-import.js.map +1 -1
  141. package/dist/git-remote.d.ts +10 -0
  142. package/dist/git-remote.d.ts.map +1 -0
  143. package/dist/git-remote.js +24 -0
  144. package/dist/git-remote.js.map +1 -0
  145. package/dist/github.d.ts.map +1 -1
  146. package/dist/github.js +5 -7
  147. package/dist/github.js.map +1 -1
  148. package/dist/host-protocol.d.ts +1 -0
  149. package/dist/host-protocol.d.ts.map +1 -1
  150. package/dist/host-protocol.js +2 -2
  151. package/dist/host-protocol.js.map +1 -1
  152. package/dist/host-records-protocol.d.ts +15 -0
  153. package/dist/host-records-protocol.d.ts.map +1 -0
  154. package/dist/host-records-protocol.js +15 -0
  155. package/dist/host-records-protocol.js.map +1 -0
  156. package/dist/hosted-remediation-protocol.d.ts +5 -0
  157. package/dist/hosted-remediation-protocol.d.ts.map +1 -0
  158. package/dist/hosted-remediation-protocol.js +26 -0
  159. package/dist/hosted-remediation-protocol.js.map +1 -0
  160. package/dist/hosted-remediation.d.ts +89 -0
  161. package/dist/hosted-remediation.d.ts.map +1 -0
  162. package/dist/hosted-remediation.js +122 -0
  163. package/dist/hosted-remediation.js.map +1 -0
  164. package/dist/hosted-scan.d.ts +1 -6
  165. package/dist/hosted-scan.d.ts.map +1 -1
  166. package/dist/hosted-scan.js +2 -2
  167. package/dist/hosted-scan.js.map +1 -1
  168. package/dist/import-scan.d.ts +1 -0
  169. package/dist/import-scan.d.ts.map +1 -1
  170. package/dist/import-scan.js +5 -1
  171. package/dist/import-scan.js.map +1 -1
  172. package/dist/index.d.ts +9 -1
  173. package/dist/index.d.ts.map +1 -1
  174. package/dist/index.js +4 -0
  175. package/dist/index.js.map +1 -1
  176. package/dist/knowledge-base.d.ts.map +1 -1
  177. package/dist/knowledge-base.js +87 -7
  178. package/dist/knowledge-base.js.map +1 -1
  179. package/dist/multiscan.d.ts.map +1 -1
  180. package/dist/multiscan.js +65 -29
  181. package/dist/multiscan.js.map +1 -1
  182. package/dist/patch-publication.d.ts +26 -0
  183. package/dist/patch-publication.d.ts.map +1 -0
  184. package/dist/patch-publication.js +105 -0
  185. package/dist/patch-publication.js.map +1 -0
  186. package/dist/patch-tui.d.ts.map +1 -1
  187. package/dist/patch-tui.js +4 -1
  188. package/dist/patch-tui.js.map +1 -1
  189. package/dist/project-config-schema.d.ts +2 -0
  190. package/dist/project-config-schema.d.ts.map +1 -1
  191. package/dist/project-config-schema.js +1 -0
  192. package/dist/project-config-schema.js.map +1 -1
  193. package/dist/project-config.d.ts +1 -0
  194. package/dist/project-config.d.ts.map +1 -1
  195. package/dist/project-config.js +29 -15
  196. package/dist/project-config.js.map +1 -1
  197. package/dist/publication.d.ts.map +1 -1
  198. package/dist/publication.js +135 -19
  199. package/dist/publication.js.map +1 -1
  200. package/dist/publish.d.ts +2 -0
  201. package/dist/publish.d.ts.map +1 -1
  202. package/dist/publish.js +48 -25
  203. package/dist/publish.js.map +1 -1
  204. package/dist/remediation.d.ts +63 -0
  205. package/dist/remediation.d.ts.map +1 -0
  206. package/dist/remediation.js +110 -0
  207. package/dist/remediation.js.map +1 -0
  208. package/dist/request-metadata.d.ts +17 -7
  209. package/dist/request-metadata.d.ts.map +1 -1
  210. package/dist/request-metadata.js +43 -8
  211. package/dist/request-metadata.js.map +1 -1
  212. package/dist/runtime.d.ts.map +1 -1
  213. package/dist/runtime.js +104 -36
  214. package/dist/runtime.js.map +1 -1
  215. package/dist/saved-scan-bootstrap.d.ts +1 -0
  216. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  217. package/dist/saved-scan-bootstrap.js +16 -4
  218. package/dist/saved-scan-bootstrap.js.map +1 -1
  219. package/dist/scan-activity.js +8 -8
  220. package/dist/scan-activity.js.map +1 -1
  221. package/dist/scan-comparison.d.ts.map +1 -1
  222. package/dist/scan-comparison.js +15 -9
  223. package/dist/scan-comparison.js.map +1 -1
  224. package/dist/scan-dashboard.d.ts.map +1 -1
  225. package/dist/scan-dashboard.js +12 -6
  226. package/dist/scan-dashboard.js.map +1 -1
  227. package/dist/scan-executor.d.ts +5 -1
  228. package/dist/scan-executor.d.ts.map +1 -1
  229. package/dist/scan-executor.js +9 -8
  230. package/dist/scan-executor.js.map +1 -1
  231. package/dist/{deep-progress.d.ts → scan-progress.d.ts} +15 -7
  232. package/dist/scan-progress.d.ts.map +1 -0
  233. package/dist/scan-progress.js +138 -0
  234. package/dist/scan-progress.js.map +1 -0
  235. package/dist/scan-settings.d.ts +1 -0
  236. package/dist/scan-settings.d.ts.map +1 -1
  237. package/dist/scan-settings.js +7 -1
  238. package/dist/scan-settings.js.map +1 -1
  239. package/dist/scan-time-budget.d.ts +9 -0
  240. package/dist/scan-time-budget.d.ts.map +1 -0
  241. package/dist/scan-time-budget.js +16 -0
  242. package/dist/scan-time-budget.js.map +1 -0
  243. package/dist/security-policy.js +1 -1
  244. package/dist/security-policy.js.map +1 -1
  245. package/dist/server/embeddings.d.ts.map +1 -1
  246. package/dist/server/embeddings.js +4 -0
  247. package/dist/server/embeddings.js.map +1 -1
  248. package/dist/server/sqlite-store.d.ts.map +1 -1
  249. package/dist/server/sqlite-store.js +14 -2
  250. package/dist/server/sqlite-store.js.map +1 -1
  251. package/dist/severity-review.d.ts +29 -0
  252. package/dist/severity-review.d.ts.map +1 -0
  253. package/dist/severity-review.js +47 -0
  254. package/dist/severity-review.js.map +1 -0
  255. package/dist/severity-store.js +4 -1
  256. package/dist/severity-store.js.map +1 -1
  257. package/dist/timestamps.d.ts +3 -0
  258. package/dist/timestamps.d.ts.map +1 -0
  259. package/dist/timestamps.js +14 -0
  260. package/dist/timestamps.js.map +1 -0
  261. package/dist/validation-records.d.ts +38 -0
  262. package/dist/validation-records.d.ts.map +1 -0
  263. package/dist/validation-records.js +76 -0
  264. package/dist/validation-records.js.map +1 -0
  265. package/dist/version.d.ts +1 -1
  266. package/dist/version.d.ts.map +1 -1
  267. package/dist/version.js +17 -4
  268. package/dist/version.js.map +1 -1
  269. package/dist/workbench-arguments.d.ts.map +1 -1
  270. package/dist/workbench-arguments.js +9 -3
  271. package/dist/workbench-arguments.js.map +1 -1
  272. package/dist/worker-progress.d.ts +13 -7
  273. package/dist/worker-progress.d.ts.map +1 -1
  274. package/dist/worker-progress.js +12 -44
  275. package/dist/worker-progress.js.map +1 -1
  276. package/docs/classify-severity-records.md +89 -0
  277. package/docs/cli.md +352 -45
  278. package/docs/findings-service.md +7 -2
  279. package/docs/hosted-remediation.md +117 -0
  280. package/docs/hosted-scans.md +8 -3
  281. package/docs/validate-records.md +69 -0
  282. package/package.json +13 -10
  283. package/schemas/project-config.schema.json +7 -1
  284. package/_bundled_plugin/preflight/capability-profiles.toml +0 -76
  285. package/_bundled_plugin/references/config-preflight.md +0 -93
  286. package/_bundled_plugin/references/desktop-config-preflight.md +0 -11
  287. package/_bundled_plugin/scripts/config_preflight.py +0 -911
  288. package/dist/deep-progress.d.ts.map +0 -1
  289. package/dist/deep-progress.js +0 -92
  290. package/dist/deep-progress.js.map +0 -1
package/docs/cli.md CHANGED
@@ -16,6 +16,13 @@ codex-security info --json
16
16
  `info --json` reports package, plugin, runtime, and model details.
17
17
  `scans` and `findings` default to their `list` subcommands.
18
18
 
19
+ To retrieve GitHub code scanning alerts without an MCP server, use
20
+ [`import github`](#import-alerts-from-the-cli). To save an existing CSV or JSON
21
+ findings file in local scan history, use
22
+ [`scan import`](#import-findings-as-a-saved-scan). These are separate workflows:
23
+ GitHub import returns upstream alerts for validation; file import saves findings
24
+ without running security analysis.
25
+
19
26
  ## Authentication
20
27
 
21
28
  Sign in with ChatGPT, or supply an API key for CI:
@@ -98,6 +105,40 @@ changed; otherwise run `logout`, then `login`.
98
105
  Some cybersecurity requests and protected findings require
99
106
  [Trusted Access for Cyber](https://chatgpt.com/cyber).
100
107
 
108
+ ### Daybreak opt-in
109
+
110
+ Codex 0.163.0 and later default the Daybreak toggle to off. Enable it through
111
+ the existing native configuration override:
112
+
113
+ ```bash
114
+ codex-security scan . --codex daybreak=true
115
+ codex-security scan . --mode deep --codex daybreak=true
116
+ ```
117
+
118
+ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
119
+ In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
120
+ to explicitly turn it off.
121
+ The setting carries through saved scan recipes, resumed scans, Deep Scan
122
+ discovery and reducer workers, and `scan --patch`. Standalone `validate`,
123
+ `patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
124
+ Threads created by these commands retain the setting when resumed in Codex.
125
+ Scans use isolated configuration, so set it on the CLI, SDK client, or project
126
+ file even if it is enabled in your personal Codex configuration.
127
+
128
+ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
129
+ an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
130
+ or set top-level `daybreak = true` in the configuration loaded by the runner.
131
+ Deep Scan inherits the active turn's effective access program from its saved
132
+ Codex session, including an explicit Standard selection. Discovery and reducer
133
+ workers retain that selection when resumed. If the host does not supply a
134
+ persisted turn context, workers use their runner configuration; CLI and SDK scans
135
+ use the explicit scan settings above.
136
+
137
+ Daybreak requires the built-in OpenAI provider and compatible account or API
138
+ project access. Codex selects the available program; this setting does not
139
+ grant access. An explicit [Cyber access program](#select-a-cyber-access-program)
140
+ takes precedence over the toggle for that turn.
141
+
101
142
  ### Daybreak Blue with an API key
102
143
 
103
144
  The [Responses API defaults](https://developers.openai.com/api/docs/guides/daybreak#understand-defaults-when-omitted)
@@ -169,6 +210,9 @@ codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
169
210
 
170
211
  export FIREWORKS_API_KEY="<your-fireworks-api-key>"
171
212
  codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
213
+
214
+ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
215
+ codex-security scan . --provider cheaperinference --model gpt-5.4
172
216
  ```
173
217
 
174
218
  ### Amazon Bedrock
@@ -290,9 +334,15 @@ and keeps completed documents. Fix the problem and retry in a new directory.
290
334
  ### Source access and restrictions
291
335
 
292
336
  The command uses scan authentication and read-only access to the selected source.
293
- It denies Git metadata and sibling-component access, disables network, web, apps,
294
- and MCP, and uses only Codex's core shell environment. Knowledge-base text stays
295
- in private review artifacts during generation and is removed afterward.
337
+ It denies Git metadata, the credential home, and private runtime configuration,
338
+ disables network, web, apps, and MCP, and uses only Codex's core shell environment.
339
+ On Unix, filesystem reads are limited to the selected source, runtime files, and
340
+ review artifacts. Windows' elevated sandbox requires broader local read access,
341
+ including sibling components, while keeping those explicit denials and read-only
342
+ permissions. Ambient Codex authentication and provider-profile files remain
343
+ excluded; Windows resolves file-pattern denials when each sandboxed command
344
+ starts. Knowledge-base text stays in private review artifacts during
345
+ generation and is removed afterward.
296
346
 
297
347
  Targets and links stay within the checkout and outside Git metadata. Linked
298
348
  worktrees and initialized submodules use their own roots. For a separate Git
@@ -344,9 +394,12 @@ codex-security scan . --working-tree
344
394
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
345
395
  ```
346
396
 
397
+ Whole-codebase and path scans also accept ordinary directories, including SVN
398
+ working copies. Their source inventories exclude `.git` and `.svn` metadata.
399
+
347
400
  `--diff` scans committed changes; `--working-tree` scans staged and unstaged
348
- changes. Deep scans support whole repositories and path scopes. Working-tree
349
- snapshots include untracked nested Git repositories. Initialized submodules must
401
+ changes. Both require Git. Deep scans support whole repositories and path scopes.
402
+ Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
350
403
  be clean and at the commit recorded by the parent.
351
404
 
352
405
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
@@ -354,11 +407,15 @@ SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
354
407
  explicit unsupported binary files are rejected. Bulk scans share this context
355
408
  with every repository.
356
409
 
357
- Output directories must be empty and outside the scanned directory and enclosing
358
- Git worktree. On macOS/Linux, existing directories must be private (`chmod 700`).
410
+ Use `--output-dir DIR` to choose where a scan saves its results. The directory
411
+ must be empty and outside the scanned directory and enclosing Git worktree. On
412
+ macOS/Linux, existing directories must be private (`chmod 700`).
359
413
  `--archive-existing` moves earlier output to
360
414
  `<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
361
- SARIF, when produced, is saved at `<scan-dir>/exports/results.sarif`.
415
+
416
+ Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
417
+ optional export fails, the scan can still complete. Use the
418
+ [export command](#export-findings) to write or retry SARIF from the saved results.
362
419
 
363
420
  Completed scans exit with `0` by default. Configure `--fail-on-severity high`
364
421
  to return `1` for high or critical findings. Scope exclusions, skipped files, and follow-up notes
@@ -371,6 +428,13 @@ Legacy completeness values affect neither.
371
428
  Bulk and component summaries report completed and failed scans without an
372
429
  `incomplete` count. Component matching errors have status `failed`.
373
430
 
431
+ Usage coverage is separate from execution status. A recorded interruption or a
432
+ closed turn without a numeric usage receipt makes usage coverage `partial`, even
433
+ if a later turn succeeds. Recorded numeric zero is distinct from a missing
434
+ receipt. These checks describe available local records; they cannot reconstruct
435
+ requests whose usage was never persisted locally or prove an exhaustive billing
436
+ total.
437
+
374
438
  New drafts use the current finding schema: `codeEvidence`, `rootCause`,
375
439
  `attackPath.dataflow`, and `evidenceRefs`. Source snippets belong in
376
440
  `codeEvidence`; `rootCause.evidenceRefs` links to them. Legacy aliases and
@@ -406,6 +470,82 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
406
470
  its successful output and failure codes.
407
471
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
408
472
 
473
+ ### Understand scan scope and follow-up work
474
+
475
+ A completed scan means the requested workflow finished. It does not mean every
476
+ file or possible vulnerability was examined. A scan can finish with intentional
477
+ exclusions, deferred review work, or unanswered questions.
478
+
479
+ To investigate a particular run, use its scan ID explicitly:
480
+
481
+ ```bash
482
+ codex-security scans show SCAN_ID --json
483
+ codex-security scans logs SCAN_ID
484
+ ```
485
+
486
+ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
487
+ fail after registration but before writing its artifacts; investigate those
488
+ failures through its history record and any available logs. When artifacts were
489
+ retained, use the saved results directory returned by `scans show` to inspect
490
+ whichever of these files are present:
491
+
492
+ | File | What to check |
493
+ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
494
+ | `scan-manifest.json` | `scan.status`, the target snapshot, and any recorded `scan.scope` limitations. |
495
+ | `report.md` | Scope, reviewed surfaces, and open questions or follow-up work. |
496
+ | `coverage.json` | `includePaths` and `excludePaths` for scope boundaries; `explicitExclusions` for recorded exclusion reasons; `surfaces` for reviewed areas; `deferred` for unfinished review work; and optional `openQuestions`. |
497
+
498
+ Deferred items can identify affected `paths` or `surfaceIds`. Surface
499
+ `receiptRefs` link to retained evidence under `artifacts/` when available.
500
+ Deep Scan summaries retain coverage from accepted worker reviews, including
501
+ worker-specific deferred work. Check those details as well as the final findings.
502
+
503
+ These records describe what the scan recorded, not an exhaustive file-by-file
504
+ audit. A retained source inventory, when present, lists inputs rather than
505
+ proving that each file was reviewed. An absent path in a surface summary does not
506
+ establish whether it was read, and the scan ID cannot reconstruct evidence that
507
+ was never saved.
508
+ Session logs can help explain failures and tool activity, but do not prove
509
+ complete review either.
510
+
511
+ For a local plugin scan, ask Codex to open the saved scan and explain its scope,
512
+ exclusions, deferred work, and follow-up questions. CLI history can also locate
513
+ that scan when it uses the same Codex home and state directory on the machine
514
+ where the scan ran. A scan ID alone does not download another machine's or
515
+ Cloud's artifacts. Preserve the saved results directory with the ID.
516
+
517
+ Choose the next step from the recorded reason:
518
+
519
+ - **The run completed and its scope matches your intent:** analyze the findings.
520
+ Record any remaining limitations; an exclusion or follow-up note alone is not
521
+ an execution failure.
522
+ - **An important path or security question remains unreviewed:** run a focused
523
+ scan with `--path`, adding relevant context with `--knowledge-base` or specific
524
+ instructions with `--scan-prompt-file`. Address missing access or context first.
525
+ Repeating the same scan does not guarantee that an omission will be resolved.
526
+ - **The run failed or was canceled:** inspect its logs and address the cause.
527
+ Use `scans rerun SCAN_ID` when the scan has a saved launch recipe; otherwise,
528
+ start a new scan with the intended scope, including for plugin scans without
529
+ a recipe. Retained findings can still be reviewed, but absence of findings
530
+ from a stopped run is inconclusive.
531
+ - **A Deep Scan was interrupted and is still recorded as `running`:** it may
532
+ support [resume](#resuming-an-interrupted-deep-scan) with the original checkout,
533
+ artifacts, and session. Completed, failed, and canceled scans cannot resume.
534
+
535
+ For example, after identifying an omitted API directory:
536
+
537
+ ```bash
538
+ codex-security scan . --path services/api --knowledge-base architecture.md
539
+ ```
540
+
541
+ Replace the path and context file with those for your repository. A new scan
542
+ reviews the current checkout; it does not amend the original saved report.
543
+
544
+ Older reports may still contain `coverage.completeness: "partial"` or
545
+ `"unknown"`. Read their scope and follow-up details to understand the limitation.
546
+ Current reports omit that field, and current commands do not use legacy
547
+ completeness values to determine scan status or exit codes.
548
+
409
549
  ### Project files
410
550
 
411
551
  ```bash
@@ -516,7 +656,9 @@ codex-security scan-components . \
516
656
  --output-dir /path/outside/project/results
517
657
  ```
518
658
 
519
- Plans use repository-relative paths:
659
+ Plans use literal repository-relative paths, so `~/src` selects a directory
660
+ named `~` inside the repository rather than expanding the home directory.
661
+ Existing absolute paths inside the repository are also accepted.
520
662
 
521
663
  ```json
522
664
  {
@@ -549,7 +691,31 @@ or API-key auth. SDK-selected command providers retain their authentication.
549
691
 
550
692
  From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
551
693
  Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
552
- planning and authentication choices.
694
+ planning and authentication choices. Custom `createSecurity` clients receive
695
+ absolute targets; saved plans and component receipts retain relative paths.
696
+
697
+ ### Set investigation time
698
+
699
+ ```bash
700
+ codex-security scan . --max-time 15
701
+ codex-security scan . --diff origin/main --max-time 15
702
+ codex-security scan . --mode deep --max-time 90
703
+ ```
704
+
705
+ `--max-time` accepts positive fractional **minutes**. Standard scans have no
706
+ time allowance by default. When selected, it is advisory: spend the available
707
+ time on useful investigation and validation, finish early if no worthwhile work
708
+ remains, and stop starting investigations at the deadline. Reporting can run
709
+ longer. This is not a hard timeout or a minimum runtime. The allowance covers
710
+ repository, path, diff, and working-tree scans; standalone custom validation and
711
+ post-scan instructions are outside it. Existing `--max-cost` and cancellation
712
+ behavior are unchanged.
713
+
714
+ The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
715
+ Each launched scan or rerun gets its own allowance after setup, and reconnects
716
+ do not reset it. Standard scans still do not support resume. For batch and
717
+ component scans, the project setting applies separately to each scan attempt,
718
+ not to planning, result matching, or the total campaign.
553
719
 
554
720
  ### Configure deep scans
555
721
 
@@ -561,19 +727,27 @@ await security.run("/path/to/repository", {
561
727
  stopAfterNoNew: 3,
562
728
  stopAfterConsecutiveErrors: 2,
563
729
  maxDiscoveryRuns: 10,
564
- maxTimeHours: 1.5,
730
+ maxTimeMinutes: 90,
565
731
  });
566
732
  ```
567
733
 
568
734
  For `scan --mode deep`, `--workers` controls discovery concurrency and
569
735
  `--subagents` controls subagents per worker. `--stop-after-no-new`,
570
- `--max-discovery-runs`, and `--max-time-hours` stop discovery by novelty, count,
736
+ `--max-discovery-runs`, and `--max-time` stop discovery by novelty, count,
571
737
  or duration. At the deadline, discovery stops; the scan then combines and returns
572
738
  completed findings.
573
739
 
574
740
  Use project-file `scan.deep` settings or legacy
575
741
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
576
- that `subagents` can be zero. Time accepts positive fractional hours up to 96.
742
+ that `subagents` can be zero. Discovery time accepts positive fractional minutes;
743
+ its default and maximum remain 5760 minutes (96 hours). Unlike Standard's
744
+ advisory allowance, this existing Deep discovery limit is enforced. Resuming a
745
+ Deep scan keeps its original deadline; rerunning starts a new scan.
746
+ `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
747
+ legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
748
+ hours. Explicit settings override lower-priority configuration across units.
749
+ At the winning source, conflicting minute/hour durations are errors; equivalent
750
+ durations are accepted.
577
751
  `stopAfterConsecutiveErrors` is an SDK/project-file setting, with no CLI flag.
578
752
  `--codex` does not configure deep-scan settings. See
579
753
  [Deep settings and limits](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md#deep-settings-and-limits).
@@ -629,7 +803,7 @@ or Windows MCP launcher. Saved reports remain readable.
629
803
  Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
630
804
 
631
805
  `validate`, `patch`, and `verify-fix` limit native overrides to `model`,
632
- `model_reasoning_effort`, `model_provider`, `model_providers`, and
806
+ `model_reasoning_effort`, `model_provider`, `model_providers`, `daybreak`, and
633
807
  `analytics.enabled`. For a custom provider:
634
808
 
635
809
  ```bash
@@ -651,14 +825,28 @@ that command. Model, effort, and provider choices carry into patch-risk assessme
651
825
  Model requests include Codex Security attribution in `responses_api_metadata`:
652
826
  `codex_security_surface` (`cli` or `sdk`), `codex_security_command`,
653
827
  `codex_security_package_version`, and `codex_security_plugin_version` when the
654
- selected plugin declares a version. These fields identify the workflow and
655
- versions producing a model request; they do not record command starts,
656
- completions, or failures.
828
+ selected plugin declares a version. The shared context adds
829
+ `codex_security_provider` for the configured provider family when the wrapper
830
+ selects a provider, and
831
+ `codex_security_scan_mode` for scans. Custom provider names use `custom`.
832
+ Provider attribution reflects the wrapper's selected profile or default;
833
+ native managed configuration may select a different provider before inference.
834
+ The GitHub Action supplies `codex_security_integration=github_action`;
835
+ Deep Scan workers retain the context and add `codex_security_worker_role`.
836
+ Caller metadata, including literal dotted keys, is preserved. Connected-app
837
+ publication uses the same request attribution; embedding requests identify
838
+ the package and version in their `User-Agent`.
839
+
840
+ These fields provide request attribution for supported inference providers, including
841
+ Bedrock. They do not create a separate telemetry collector, record command
842
+ starts or outcomes, or make another provider's traffic visible to OpenAI.
657
843
 
658
844
  Disable Codex usage analytics and built-in metrics with
659
845
  `--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
660
846
  patch-risk assessment, and Deep Scan discovery and reducer workers, including
661
- resumed workers. Deep Scan workers also preserve the scan's request metadata.
847
+ resumed workers. Selected-profile settings take precedence over root settings.
848
+ Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
849
+ workers, including exporter choices and prompt-logging controls.
662
850
  Model-request attribution metadata remains attached when analytics are disabled.
663
851
  The setting does not control configured OpenTelemetry exporters, integrations,
664
852
  authentication, or CLI update checks. Validation uses isolated configuration;
@@ -709,10 +897,27 @@ Finish older-version operations before upgrading. Never remove
709
897
  `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
710
898
  credential home before manually removing an old `.codex-security-scan.lock`.
711
899
 
712
- On Windows, an older sandboxed run can leave invalid ACLs on a credential-home
713
- ancestor. Preserve that state, then select a new private `CODEX_SECURITY_STATE_DIR`
714
- outside the old state and repository. Sign in again if needed; the new directory
715
- has separate scan history.
900
+ On Windows, credential-home checks require trusted ownership and permissions
901
+ through every ancestor, including the volume root. Codex Security can repair
902
+ the credential home and its descendants; it does not change ancestor ownership
903
+ or ACLs. An error identifies the rejected ancestor and its underlying ACL
904
+ problem. A volume root owned by `Everyone` (`S-1-1-0`) is unsupported, even when
905
+ the credential home itself is private.
906
+
907
+ Preserve existing state, then choose a private `CODEX_SECURITY_STATE_DIR` outside
908
+ the rejected ancestor and the repository, with a full ancestor chain that passes
909
+ the same checks. If the volume root is rejected, another directory on that
910
+ volume cannot resolve it; use a separately provisioned volume with trusted
911
+ ancestry. On Windows, local runtime bootstrap directories are created beside
912
+ `codex-home` in the state directory and removed when the SDK client closes.
913
+ They use the same trusted ancestry checks, so sandbox write permissions on
914
+ `TEMP` do not prevent runtime preparation. `TEMP`, `TMP`, and scan output
915
+ locations are unchanged. Do not change the system volume's owner or ACL to
916
+ make a scan run. If no suitable
917
+ location is available, this layout cannot provision credentials safely under
918
+ the current checks. Sign in again if needed; a new state directory has separate
919
+ scan history and does not migrate credentials or reports from the old state
920
+ directory.
716
921
 
717
922
  ### Progress and cost
718
923
 
@@ -726,6 +931,19 @@ input. Missing cache-write usage makes the uncached/cache-write breakdown
726
931
  unavailable. The CLI cannot recover missing information already recorded as zero
727
932
  by the runtime.
728
933
 
934
+ Completed scan history also saves rollout observations under `usage`, alongside
935
+ any `cost` estimate. `byRole` separates parent tokens from combined worker tokens.
936
+ `window` bounds the counted events, `observedAt` records collection time, and
937
+ `tokensUpdatedAt` records the newest token receipt. Partial coverage means some
938
+ work could not be measured, including in-flight turns or missing earlier attempts.
939
+ The parent can continue after report completion, so final CLI tokens can exceed
940
+ the saved measurement window.
941
+
942
+ `usage.accountRateLimits` saves the latest observed account-wide readings with
943
+ their own timestamps, window durations, and reset times. These are historical
944
+ observations, not a live allowance check or scan-only consumption. Empty readings
945
+ mean allowance was unavailable. There is no token-to-allowance conversion here.
946
+
729
947
  Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
730
948
  and show a short/long-context range. They estimate model usage, excluding other
731
949
  tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
@@ -846,6 +1064,8 @@ codex-security bulk-scan repositories.csv \
846
1064
  ```
847
1065
 
848
1066
  Bulk scans use clean shallow checkouts and support repository/path scopes.
1067
+ CSV scopes are literal paths relative to each checkout, including names such
1068
+ as `~/src`.
849
1069
  Configured diff or working-tree scopes are rejected unless every affected row
850
1070
  overrides them with a path scope. `--output-dir` requires CSV input.
851
1071
 
@@ -858,6 +1078,10 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
858
1078
  attempt per pending repository per invocation. Repeating the command continues
859
1079
  the campaign, skips completed results, and starts pending attempts. Occupied
860
1080
  attempt directories stop that repository and suggest `--recover`.
1081
+ Completed results are skipped only when their saved contract and seal are valid
1082
+ and the manifest records a completed scan. Damaged or unsuccessful results get a
1083
+ new attempt, including with `--recover`, while the old artifacts remain available.
1084
+ Missing or invalid plugin schemas stop resume without starting another scan.
861
1085
  Changes to project configuration, extracted knowledge-base text, staged document
862
1086
  filenames, direct Codex overrides, or explicit `--plugin-path`/`--python` selections
863
1087
  require a new output directory. Version 1 manifests also require a new directory
@@ -1059,7 +1283,11 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
1059
1283
  codex-security classify-severity --scan-dir /path/to/completed-scan --json
1060
1284
  ```
1061
1285
 
1062
- Use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1286
+ For repository-free canonical records, use `classify-severity --records` alone.
1287
+ The [records protocol](classify-severity-records.md) accepts immutable Markdown and
1288
+ report snapshots and delegates model execution to the host.
1289
+
1290
+ For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1063
1291
  Omitting `--rubric` inherits original severity without model calls. Rubrics and
1064
1292
  repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
1065
1293
  Each finding is classified in a separate read-only turn using its report and
@@ -1288,6 +1516,9 @@ scan and custom-validation prompts when the original used them:
1288
1516
  codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
1289
1517
  ```
1290
1518
 
1519
+ Saved path scopes remain relative to the repository. Names such as `~` and
1520
+ `~/source.ts` are replayed literally; they do not select the home directory.
1521
+
1291
1522
  A rerun creates a new scan. When the original has saved input identities, the
1292
1523
  rerun reports changes to the scan instructions or knowledge base. `scans show`
1293
1524
  includes the saved scope, runtime and Deep Scan settings, instruction digest,
@@ -1381,31 +1612,80 @@ Progress callback failures do not stop matching.
1381
1612
 
1382
1613
  ## Exports and CI
1383
1614
 
1384
- `export` reads saved results without Codex or credentials. It defaults to the
1385
- current repository's latest completed scan. Choose either a positional result
1386
- directory or `--scan ID`. Findings require sealed results and support
1387
- `--export-format csv|json|sarif` (default SARIF). `--source-root PATH` adds SARIF
1388
- source-line fingerprints.
1615
+ Export saved findings and threat models without rerunning a scan or signing in.
1616
+
1617
+ ### Export findings
1618
+
1619
+ To save a completed scan's findings as SARIF, run:
1620
+
1621
+ ```bash
1622
+ codex-security export /path/to/scan-results --output results.sarif
1623
+ ```
1624
+
1625
+ Replace `/path/to/scan-results` with the results directory printed by `scan`.
1626
+ The command writes `results.sarif` in the current directory. The output directory
1627
+ must already exist.
1628
+
1629
+ SARIF is the default format, and `./results.sarif` is the default output path.
1630
+ Use `--export-format json` or `--export-format csv` to choose another format.
1631
+ To select a saved scan by its ID and export JSON, run:
1389
1632
 
1390
1633
  ```bash
1391
1634
  codex-security export --scan SCAN_ID --export-format json --output findings.json
1392
- codex-security export --artifact threat-model --output docs/threatmodel.md
1393
- codex-security export /path/to/policy-results --artifact threat-model --output -
1394
1635
  ```
1395
1636
 
1396
- Threat-model exports use Markdown and default to `./threatmodel.md`. Standard,
1397
- Deep, Diff, and policy workflows retain models when available; component/bulk
1398
- runs save one per child. Explicit results may expose a model before completion
1399
- or after later failure. Missing models return an error rather than generating
1400
- or substituting one. Historical models in sealed scans need a matching manifest
1401
- digest.
1637
+ Replace `SCAN_ID` with the ID printed by `scan`. If you omit both the results
1638
+ directory and `--scan`, `export` uses the current repository's latest completed
1639
+ scan.
1640
+
1641
+ JSON preserves the saved findings. CSV marks them open, omits local triage state,
1642
+ and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
1643
+ leading apostrophes; import removes the escape. Use JSON to recover ambiguous
1644
+ apostrophes from older CSV exports.
1645
+
1646
+ For SARIF, `--source-root` adds source-line fingerprints that help tools match
1647
+ findings across scans. Before changing the scanned files or applying patches,
1648
+ run the export from the scanned repository's root:
1649
+
1650
+ ```bash
1651
+ codex-security export /path/to/scan-results --source-root . --output results.sarif
1652
+ ```
1653
+
1654
+ The `.` selects the current directory as the source root. Its source files must
1655
+ be unchanged since the scan. `--source-root` is supported only for SARIF.
1656
+
1657
+ If export fails, it exits with `2`. Fix the reported error and rerun the export;
1658
+ the saved scan remains available, so you don't need to run another scan.
1659
+
1660
+ ### Export a threat model
1661
+
1662
+ To save a scan's threat model as Markdown, run:
1663
+
1664
+ ```bash
1665
+ codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md
1666
+ ```
1667
+
1668
+ Threat-model exports default to `./threatmodel.md`. Standard, Deep, Diff, and
1669
+ policy workflows retain models when available; component/bulk runs save one per
1670
+ child. With an explicit results directory, you can export a saved threat model
1671
+ even if the workflow has not completed or later failed. Missing models return
1672
+ an error rather than generating or substituting one. Historical models in sealed
1673
+ scans need a matching manifest digest.
1674
+
1675
+ To print a policy workflow's saved threat model, pass its results directory and
1676
+ `--output -`:
1677
+
1678
+ ```bash
1679
+ codex-security export /path/to/policy-results --artifact threat-model --output -
1680
+ ```
1402
1681
 
1403
1682
  `--output -` emits only artifact content, with diagnostics on stderr. Markdown
1404
1683
  and CSV stdout cannot combine with JSON command output. Exporting into a checkout
1405
1684
  does not make the model scan input; pass it with `--knowledge-base`.
1406
1685
 
1407
- `ScanResult.threatModel` and `threatModelPath` expose the retained model and
1408
- document, or null. Export still works if the document could not be written.
1686
+ ### Export with the SDK
1687
+
1688
+ Use `exportArtifact()` to export saved results from TypeScript:
1409
1689
 
1410
1690
  ```ts
1411
1691
  import { exportArtifact } from "@openai/codex-security";
@@ -1422,12 +1702,12 @@ Use `artifact: "findings"` with `format: "csv" | "json" | "sarif"` for findings.
1422
1702
  `output: "-"` streams stdout and returns null path/provenance. `pythonPath`
1423
1703
  selects an interpreter; `signal` cancels.
1424
1704
 
1425
- JSON preserves sealed findings. CSV marks them open, omits local triage state,
1426
- and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
1427
- leading apostrophes; import removes the escape. Use JSON to recover ambiguous
1428
- apostrophes from older CSV exports.
1705
+ `ScanResult.threatModel` and `threatModelPath` expose the retained model and
1706
+ document, or null. Export still works if the document could not be written.
1707
+
1708
+ ### Use exports in CI
1429
1709
 
1430
- For CI, place output outside the checkout and set a severity threshold:
1710
+ Save each scan's results outside the checkout and set a severity threshold:
1431
1711
 
1432
1712
  ```bash
1433
1713
  SCAN_ROOT="$(mktemp -d)"
@@ -1443,6 +1723,21 @@ codex-security scan . --diff origin/main \
1443
1723
  | `2` | Invalid input, runtime error, target change, or required-output failure. |
1444
1724
  | `130` / `143` | Interrupt / termination. |
1445
1725
 
1726
+ If the scan exits with `2`, `130`, or `143`, skip export and upload. After a scan
1727
+ exits with `0` or `1`, use these steps:
1728
+
1729
+ 1. Export from that run's results directory. Using the explicit directory keeps
1730
+ concurrent scans from changing which results are selected:
1731
+
1732
+ ```bash
1733
+ codex-security export "$SCAN_ROOT/results" --source-root . \
1734
+ --output "$SCAN_ROOT/results.sarif"
1735
+ ```
1736
+
1737
+ 2. If export succeeds, upload the SARIF file.
1738
+ 3. If the scan exited with `1`, keep the CI job failed so the severity threshold
1739
+ remains enforced.
1740
+
1446
1741
  JSON scans have no interactive controls. `validate`, `login`, and `logout` reject
1447
1742
  `--json`. Use `validate --output-schema FILE` for a schema-checked JSON assessment.
1448
1743
  For GitHub Actions setup, see the
@@ -1530,6 +1825,10 @@ The token needs code-scanning read access; access failures reject the import.
1530
1825
 
1531
1826
  ## Validate and patch findings
1532
1827
 
1828
+ Hosts that manage their own model execution can use `codex-security validate --records`.
1829
+ This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
1830
+ See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
1831
+
1533
1832
  `validate` assesses candidates from local source evidence without building the
1534
1833
  target, executing application code, running tests or PoCs, or contacting services.
1535
1834
  It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
@@ -1537,6 +1836,9 @@ validation, and `patch` still fixes and verifies findings. Both commands accept
1537
1836
  or literal text and work in the current directory. Saved finding/occurrence IDs
1538
1837
  select their original repository for patching.
1539
1838
 
1839
+ Basic patching also works in ordinary directories and Git worktrees before their
1840
+ first commit. Directory change tracking excludes `.git` and `.svn` metadata.
1841
+
1540
1842
  ```bash
1541
1843
  codex-security validate "Possible SQL injection" --effort high
1542
1844
  codex-security validate findings.json --knowledge-base ./context --context "Check the tenant boundary."
@@ -1657,6 +1959,8 @@ Both candidate IDs remain in the output, including the unresolved claim.
1657
1959
  `--scan latest` uses the current repository's latest completed scan. Patching
1658
1960
  supports JSON for saved findings, literal text, and files. Each finding gets a
1659
1961
  saved Codex desktop task. `--model` and `--effort` control the model.
1962
+ Saved-scan patching and fix verification use the complete sealed finding evidence
1963
+ and exclude findings that are currently closed in triage.
1660
1964
 
1661
1965
  `--validation-prompt-file PATH` supplies setup, authorized targets, expected
1662
1966
  results, and cleanup for dynamic validation. It works with saved findings,
@@ -1737,8 +2041,11 @@ Use `--llms` for the command manifest, `scan --schema --format json` for its
1737
2041
  schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
1738
2042
  `--format toon|json|yaml|jsonl` and `--full-output`.
1739
2043
 
1740
- `skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
1741
- MCP exposes only read-only `info`, because the transport cannot cancel scans.
2044
+ `skills add` syncs generated CLI command guidance; it does not install the full
2045
+ Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
2046
+ only read-only `info` because the transport cannot cancel scans. For the plugin's
2047
+ scan, triage, patch, and verification workflows, see the
2048
+ [agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
1742
2049
 
1743
2050
  For local findings storage, deduplication, and custom endpoints, see the
1744
2051
  [findings guide](findings-service.md).
@@ -25,6 +25,8 @@ deployments; local deduplication uses the database selected by
25
25
  For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
26
26
  static key or `() => string | Promise<string>` as its first argument. It calls
27
27
  the callback before each HTTP batch; the caller handles token acquisition.
28
+ Cancellation prevents a new callback or HTTP request. Direct embedder callers
29
+ still await a key callback that has already started.
28
30
  Pass `fetch` as the second argument and the full endpoint URL as the third.
29
31
  By default, the saved-scan deduplication APIs use environment credentials. A
30
32
  custom SDK `embedding` binding can supply an adapter with its own credentials,
@@ -185,7 +187,8 @@ console.log(result.duplicateGroups);
185
187
  For a different embedding provider or model, both saved-scan SDK methods accept
186
188
  an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
187
189
  `{ model, vector }` per input finding, in input order. The adapter owns its
188
- credentials, tokenization, chunking, and provider request format.
190
+ credentials, tokenization, chunking, and provider request format. Cancellation
191
+ stops the SDK's wait for embeddings; the adapter owns cleanup of its ongoing work.
189
192
 
190
193
  ```typescript
191
194
  import { deduplicateScan, type FindingEmbedder } from "@openai/codex-security";
@@ -314,7 +317,9 @@ required-source-access blockers are not retried. Refusals are not retried or
314
317
  sent to another model. If candidate retrieval or review still fails, the
315
318
  operation fails without posting groups.
316
319
  A failed group-write request may already have committed; resubmitting the same
317
- memberships does not create duplicate groups. Non-cancellation review failures
320
+ memberships does not create duplicate groups. Cancellation can also arrive after
321
+ a write completes; it does not mean that remote findings are unchanged. Completed
322
+ workflow stages remain saved even when cancellation is reported. Non-cancellation review failures
318
323
  throw `DeduplicationReviewError`, with diagnostic text and `metadata` for the
319
324
  stage, model, category, attempt count, and reason.
320
325