@openai/codex-security 0.5.0 → 0.6.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 (299) hide show
  1. package/README.md +93 -2
  2. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  3. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +60 -9
  6. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  7. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  8. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +1 -1
  9. package/_bundled_plugin/scripts/finalize_scan_contract.py +12 -1
  10. package/_bundled_plugin/scripts/generate_in_scope_files.py +6 -6
  11. package/_bundled_plugin/scripts/generate_rank_input.py +12 -6
  12. package/_bundled_plugin/scripts/report_projection.py +2 -1
  13. package/_bundled_plugin/scripts/threat_model_projection.py +1 -3
  14. package/_bundled_plugin/scripts/workbench/saved_coverage.py +234 -0
  15. package/_bundled_plugin/scripts/workbench_cli.py +5 -7
  16. package/_bundled_plugin/scripts/workbench_db.py +12 -6
  17. package/_bundled_plugin/scripts/workbench_finding_workflows.py +2 -0
  18. package/_bundled_plugin/scripts/workbench_native_indexes.py +10 -7
  19. package/_bundled_plugin/scripts/workbench_publication.py +4 -3
  20. package/_bundled_plugin/scripts/workbench_remediation.py +5 -1
  21. package/_bundled_plugin/scripts/workbench_saved_results.py +542 -148
  22. package/_bundled_plugin/scripts/workbench_scan_history.py +79 -78
  23. package/_bundled_plugin/scripts/workbench_scan_usage.py +61 -13
  24. package/_bundled_plugin/scripts/workbench_target.py +21 -7
  25. package/_bundled_plugin/scripts/workbench_validation.py +21 -18
  26. package/_bundled_plugin/shared/workbench-migrations.json +26 -0
  27. package/_bundled_plugin/skills/fix-finding/SKILL.md +16 -8
  28. package/_bundled_plugin/skills/publish-findings/SKILL.md +130 -0
  29. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +6 -0
  30. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  31. package/dist/api.d.ts +4 -1
  32. package/dist/api.d.ts.map +1 -1
  33. package/dist/api.js +233 -91
  34. package/dist/api.js.map +1 -1
  35. package/dist/classify-scan-severity.d.ts.map +1 -1
  36. package/dist/classify-scan-severity.js +16 -18
  37. package/dist/classify-scan-severity.js.map +1 -1
  38. package/dist/classify-severity-records.d.ts +5 -2
  39. package/dist/classify-severity-records.d.ts.map +1 -1
  40. package/dist/classify-severity-records.js +40 -34
  41. package/dist/classify-severity-records.js.map +1 -1
  42. package/dist/classify-severity.d.ts +5 -1
  43. package/dist/classify-severity.d.ts.map +1 -1
  44. package/dist/classify-severity.js +20 -30
  45. package/dist/classify-severity.js.map +1 -1
  46. package/dist/cli-daybreak.d.ts +5 -0
  47. package/dist/cli-daybreak.d.ts.map +1 -0
  48. package/dist/cli-daybreak.js +89 -0
  49. package/dist/cli-daybreak.js.map +1 -0
  50. package/dist/cli-help.d.ts.map +1 -1
  51. package/dist/cli-help.js +1 -0
  52. package/dist/cli-help.js.map +1 -1
  53. package/dist/cli.d.ts +12 -1
  54. package/dist/cli.d.ts.map +1 -1
  55. package/dist/cli.js +1224 -596
  56. package/dist/cli.js.map +1 -1
  57. package/dist/cloud-endpoint.d.ts +6 -0
  58. package/dist/cloud-endpoint.d.ts.map +1 -0
  59. package/dist/cloud-endpoint.js +51 -0
  60. package/dist/cloud-endpoint.js.map +1 -0
  61. package/dist/cloud-publish.d.ts.map +1 -1
  62. package/dist/cloud-publish.js +7 -5
  63. package/dist/cloud-publish.js.map +1 -1
  64. package/dist/codeowners.js +2 -2
  65. package/dist/codeowners.js.map +1 -1
  66. package/dist/component-plan.d.ts.map +1 -1
  67. package/dist/component-plan.js +3 -2
  68. package/dist/component-plan.js.map +1 -1
  69. package/dist/component-scan.js +2 -2
  70. package/dist/component-scan.js.map +1 -1
  71. package/dist/config.d.ts.map +1 -1
  72. package/dist/config.js +5 -1
  73. package/dist/config.js.map +1 -1
  74. package/dist/cost.d.ts +2 -1
  75. package/dist/cost.d.ts.map +1 -1
  76. package/dist/cost.js +17 -8
  77. package/dist/cost.js.map +1 -1
  78. package/dist/custom-validation.d.ts.map +1 -1
  79. package/dist/custom-validation.js +2 -5
  80. package/dist/custom-validation.js.map +1 -1
  81. package/dist/deduplication/codex-review.d.ts.map +1 -1
  82. package/dist/deduplication/codex-review.js +8 -6
  83. package/dist/deduplication/codex-review.js.map +1 -1
  84. package/dist/deduplication/local.d.ts.map +1 -1
  85. package/dist/deduplication/local.js +5 -2
  86. package/dist/deduplication/local.js.map +1 -1
  87. package/dist/deduplication/retry.d.ts.map +1 -1
  88. package/dist/deduplication/retry.js +5 -0
  89. package/dist/deduplication/retry.js.map +1 -1
  90. package/dist/deduplication/scan.js +5 -1
  91. package/dist/deduplication/scan.js.map +1 -1
  92. package/dist/deep-scan.d.ts +6 -0
  93. package/dist/deep-scan.d.ts.map +1 -1
  94. package/dist/deep-scan.js +8 -6
  95. package/dist/deep-scan.js.map +1 -1
  96. package/dist/default-severity-rubric.d.ts +3 -0
  97. package/dist/default-severity-rubric.d.ts.map +1 -0
  98. package/dist/default-severity-rubric.js +67 -0
  99. package/dist/default-severity-rubric.js.map +1 -0
  100. package/dist/endor-findings.d.ts +7 -0
  101. package/dist/endor-findings.d.ts.map +1 -0
  102. package/dist/endor-findings.js +233 -0
  103. package/dist/endor-findings.js.map +1 -0
  104. package/dist/external-findings-import.d.ts +5 -0
  105. package/dist/external-findings-import.d.ts.map +1 -0
  106. package/dist/external-findings-import.js +38 -0
  107. package/dist/external-findings-import.js.map +1 -0
  108. package/dist/external-findings-local.d.ts +63 -0
  109. package/dist/external-findings-local.d.ts.map +1 -0
  110. package/dist/external-findings-local.js +337 -0
  111. package/dist/external-findings-local.js.map +1 -0
  112. package/dist/external-findings-publish.d.ts +73 -0
  113. package/dist/external-findings-publish.d.ts.map +1 -0
  114. package/dist/external-findings-publish.js +713 -0
  115. package/dist/external-findings-publish.js.map +1 -0
  116. package/dist/external-findings-read.d.ts +6 -0
  117. package/dist/external-findings-read.d.ts.map +1 -0
  118. package/dist/external-findings-read.js +88 -0
  119. package/dist/external-findings-read.js.map +1 -0
  120. package/dist/external-findings.d.ts +21 -0
  121. package/dist/external-findings.d.ts.map +1 -0
  122. package/dist/external-findings.js +2 -0
  123. package/dist/external-findings.js.map +1 -0
  124. package/dist/external-import-contract.d.ts +13 -0
  125. package/dist/external-import-contract.d.ts.map +1 -0
  126. package/dist/external-import-contract.js +254 -0
  127. package/dist/external-import-contract.js.map +1 -0
  128. package/dist/external-import-models.d.ts +362 -0
  129. package/dist/external-import-models.d.ts.map +1 -0
  130. package/dist/external-import-models.js +3 -0
  131. package/dist/external-import-models.js.map +1 -0
  132. package/dist/finding-workflow.d.ts +1 -1
  133. package/dist/finding-workflow.d.ts.map +1 -1
  134. package/dist/finding-workflow.js +2 -1
  135. package/dist/finding-workflow.js.map +1 -1
  136. package/dist/findings-import.d.ts.map +1 -1
  137. package/dist/findings-import.js +23 -3
  138. package/dist/findings-import.js.map +1 -1
  139. package/dist/github-advisories.d.ts +386 -0
  140. package/dist/github-advisories.d.ts.map +1 -0
  141. package/dist/github-advisories.js +131 -0
  142. package/dist/github-advisories.js.map +1 -0
  143. package/dist/github-findings.d.ts +10 -0
  144. package/dist/github-findings.d.ts.map +1 -0
  145. package/dist/github-findings.js +256 -0
  146. package/dist/github-findings.js.map +1 -0
  147. package/dist/host-protocol.d.ts +1 -0
  148. package/dist/host-protocol.d.ts.map +1 -1
  149. package/dist/host-protocol.js +1 -1
  150. package/dist/host-protocol.js.map +1 -1
  151. package/dist/hosted-remediation-protocol.d.ts +6 -0
  152. package/dist/hosted-remediation-protocol.d.ts.map +1 -0
  153. package/dist/hosted-remediation-protocol.js +32 -0
  154. package/dist/hosted-remediation-protocol.js.map +1 -0
  155. package/dist/hosted-remediation.d.ts +93 -0
  156. package/dist/hosted-remediation.d.ts.map +1 -0
  157. package/dist/hosted-remediation.js +124 -0
  158. package/dist/hosted-remediation.js.map +1 -0
  159. package/dist/hosted-scan.d.ts +16 -0
  160. package/dist/hosted-scan.d.ts.map +1 -1
  161. package/dist/hosted-scan.js +14 -2
  162. package/dist/hosted-scan.js.map +1 -1
  163. package/dist/import-scan.d.ts +1 -0
  164. package/dist/import-scan.d.ts.map +1 -1
  165. package/dist/import-scan.js +5 -1
  166. package/dist/import-scan.js.map +1 -1
  167. package/dist/index.d.ts +18 -1
  168. package/dist/index.d.ts.map +1 -1
  169. package/dist/index.js +10 -0
  170. package/dist/index.js.map +1 -1
  171. package/dist/multiscan.d.ts.map +1 -1
  172. package/dist/multiscan.js +3 -1
  173. package/dist/multiscan.js.map +1 -1
  174. package/dist/project-config-schema.d.ts +2 -0
  175. package/dist/project-config-schema.d.ts.map +1 -1
  176. package/dist/project-config-schema.js +1 -0
  177. package/dist/project-config-schema.js.map +1 -1
  178. package/dist/project-config.d.ts +1 -0
  179. package/dist/project-config.d.ts.map +1 -1
  180. package/dist/project-config.js +15 -9
  181. package/dist/project-config.js.map +1 -1
  182. package/dist/publish.d.ts +2 -0
  183. package/dist/publish.d.ts.map +1 -1
  184. package/dist/publish.js +9 -0
  185. package/dist/publish.js.map +1 -1
  186. package/dist/remediation.d.ts +69 -0
  187. package/dist/remediation.d.ts.map +1 -0
  188. package/dist/remediation.js +121 -0
  189. package/dist/remediation.js.map +1 -0
  190. package/dist/request-metadata.d.ts +17 -7
  191. package/dist/request-metadata.d.ts.map +1 -1
  192. package/dist/request-metadata.js +43 -8
  193. package/dist/request-metadata.js.map +1 -1
  194. package/dist/result.d.ts +4 -0
  195. package/dist/result.d.ts.map +1 -1
  196. package/dist/result.js +10 -0
  197. package/dist/result.js.map +1 -1
  198. package/dist/runtime.d.ts +1 -0
  199. package/dist/runtime.d.ts.map +1 -1
  200. package/dist/runtime.js +24 -15
  201. package/dist/runtime.js.map +1 -1
  202. package/dist/saved-scan-bootstrap.d.ts +1 -0
  203. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  204. package/dist/saved-scan-bootstrap.js +16 -4
  205. package/dist/saved-scan-bootstrap.js.map +1 -1
  206. package/dist/scan-activity.js +8 -8
  207. package/dist/scan-activity.js.map +1 -1
  208. package/dist/scan-comparison.d.ts.map +1 -1
  209. package/dist/scan-comparison.js +15 -9
  210. package/dist/scan-comparison.js.map +1 -1
  211. package/dist/scan-dashboard.d.ts.map +1 -1
  212. package/dist/scan-dashboard.js +12 -6
  213. package/dist/scan-dashboard.js.map +1 -1
  214. package/dist/scan-executor.d.ts +5 -1
  215. package/dist/scan-executor.d.ts.map +1 -1
  216. package/dist/scan-executor.js +9 -8
  217. package/dist/scan-executor.js.map +1 -1
  218. package/dist/scan-owner-suggestions.d.ts +8 -0
  219. package/dist/scan-owner-suggestions.d.ts.map +1 -0
  220. package/dist/scan-owner-suggestions.js +33 -0
  221. package/dist/scan-owner-suggestions.js.map +1 -0
  222. package/dist/{deep-progress.d.ts → scan-progress.d.ts} +15 -7
  223. package/dist/scan-progress.d.ts.map +1 -0
  224. package/dist/scan-progress.js +138 -0
  225. package/dist/scan-progress.js.map +1 -0
  226. package/dist/scan-settings.d.ts +1 -0
  227. package/dist/scan-settings.d.ts.map +1 -1
  228. package/dist/scan-settings.js +4 -0
  229. package/dist/scan-settings.js.map +1 -1
  230. package/dist/scanner-import.d.ts +20 -0
  231. package/dist/scanner-import.d.ts.map +1 -0
  232. package/dist/scanner-import.js +204 -0
  233. package/dist/scanner-import.js.map +1 -0
  234. package/dist/security-policy-diff.d.ts +2 -0
  235. package/dist/security-policy-diff.d.ts.map +1 -0
  236. package/dist/security-policy-diff.js +197 -0
  237. package/dist/security-policy-diff.js.map +1 -0
  238. package/dist/security-policy.d.ts +7 -3
  239. package/dist/security-policy.d.ts.map +1 -1
  240. package/dist/security-policy.js +11 -57
  241. package/dist/security-policy.js.map +1 -1
  242. package/dist/semgrep-findings.d.ts +9 -0
  243. package/dist/semgrep-findings.d.ts.map +1 -0
  244. package/dist/semgrep-findings.js +293 -0
  245. package/dist/semgrep-findings.js.map +1 -0
  246. package/dist/server/embeddings.d.ts.map +1 -1
  247. package/dist/server/embeddings.js +4 -0
  248. package/dist/server/embeddings.js.map +1 -1
  249. package/dist/server/sqlite-store.d.ts.map +1 -1
  250. package/dist/server/sqlite-store.js +14 -2
  251. package/dist/server/sqlite-store.js.map +1 -1
  252. package/dist/severity-review.d.ts +3 -0
  253. package/dist/severity-review.d.ts.map +1 -1
  254. package/dist/severity-review.js +19 -0
  255. package/dist/severity-review.js.map +1 -1
  256. package/dist/severity-store.js +11 -3
  257. package/dist/severity-store.js.map +1 -1
  258. package/dist/snyk-findings.d.ts +9 -0
  259. package/dist/snyk-findings.d.ts.map +1 -0
  260. package/dist/snyk-findings.js +349 -0
  261. package/dist/snyk-findings.js.map +1 -0
  262. package/dist/targets.d.ts +2 -2
  263. package/dist/targets.d.ts.map +1 -1
  264. package/dist/targets.js +12 -2
  265. package/dist/targets.js.map +1 -1
  266. package/dist/timestamps.d.ts +3 -0
  267. package/dist/timestamps.d.ts.map +1 -0
  268. package/dist/timestamps.js +14 -0
  269. package/dist/timestamps.js.map +1 -0
  270. package/dist/version.d.ts +1 -1
  271. package/dist/version.d.ts.map +1 -1
  272. package/dist/version.js +13 -2
  273. package/dist/version.js.map +1 -1
  274. package/dist/wiz-csv.d.ts +8 -0
  275. package/dist/wiz-csv.d.ts.map +1 -0
  276. package/dist/wiz-csv.js +116 -0
  277. package/dist/wiz-csv.js.map +1 -0
  278. package/dist/wiz-findings.d.ts +4 -0
  279. package/dist/wiz-findings.d.ts.map +1 -0
  280. package/dist/wiz-findings.js +460 -0
  281. package/dist/wiz-findings.js.map +1 -0
  282. package/dist/workbench-arguments.d.ts.map +1 -1
  283. package/dist/workbench-arguments.js +9 -3
  284. package/dist/workbench-arguments.js.map +1 -1
  285. package/dist/worker-progress.d.ts +11 -1
  286. package/dist/worker-progress.d.ts.map +1 -1
  287. package/dist/worker-progress.js +11 -1
  288. package/dist/worker-progress.js.map +1 -1
  289. package/docs/classify-severity-records.md +28 -10
  290. package/docs/cli.md +788 -46
  291. package/docs/findings-service.md +7 -2
  292. package/docs/hosted-remediation.md +134 -0
  293. package/docs/hosted-scans.md +20 -3
  294. package/package.json +9 -6
  295. package/schemas/external-findings.schema.json +1421 -0
  296. package/schemas/project-config.schema.json +4 -0
  297. package/dist/deep-progress.d.ts.map +0 -1
  298. package/dist/deep-progress.js +0 -92
  299. package/dist/deep-progress.js.map +0 -1
package/docs/cli.md CHANGED
@@ -105,6 +105,40 @@ changed; otherwise run `logout`, then `login`.
105
105
  Some cybersecurity requests and protected findings require
106
106
  [Trusted Access for Cyber](https://chatgpt.com/cyber).
107
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
+
108
142
  ### Daybreak Blue with an API key
109
143
 
110
144
  The [Responses API defaults](https://developers.openai.com/api/docs/guides/daybreak#understand-defaults-when-omitted)
@@ -300,9 +334,15 @@ and keeps completed documents. Fix the problem and retry in a new directory.
300
334
  ### Source access and restrictions
301
335
 
302
336
  The command uses scan authentication and read-only access to the selected source.
303
- It denies Git metadata and sibling-component access, disables network, web, apps,
304
- and MCP, and uses only Codex's core shell environment. Knowledge-base text stays
305
- 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.
306
346
 
307
347
  Targets and links stay within the checkout and outside Git metadata. Linked
308
348
  worktrees and initialized submodules use their own roots. For a separate Git
@@ -337,7 +377,16 @@ try {
337
377
  `preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied
338
378
  in-memory draft and escapes terminal controls; editing its saved file does not
339
379
  change that object. `securityPolicyDiff()` returns a raw diff for files and other
340
- non-terminal uses, with an optional Python interpreter.
380
+ non-terminal uses. Both preview methods compute the diff in Node without
381
+ discovering or launching Python; `pythonPath` and `PYTHON` do not affect previews.
382
+
383
+ The optional second argument to `securityPolicyDiff(draft, python, signal)` is
384
+ deprecated. Interpreter paths, including paths returned by a resolver callback,
385
+ no longer select an executable or get validated. For compatibility, an explicitly
386
+ supplied resolver is still awaited when the draft changes, and any error it throws
387
+ propagates. Omit that argument for new code, or pass `undefined` when supplying a
388
+ cancellation signal. Source freshness is checked before and after computing the
389
+ diff.
341
390
 
342
391
  `generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
343
392
  `maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives
@@ -351,14 +400,25 @@ codex-security scan .
351
400
  codex-security scan . --path src --path tests
352
401
  codex-security scan . --diff origin/main --json
353
402
  codex-security scan . --working-tree
403
+ codex-security scan . --owner-suggestions
354
404
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
355
405
  ```
356
406
 
407
+ Whole-codebase and path scans also accept ordinary directories, including SVN
408
+ working copies. Their source inventories exclude `.git` and `.svn` metadata.
409
+
357
410
  `--diff` scans committed changes; `--working-tree` scans staged and unstaged
358
- changes. Deep scans support whole repositories and path scopes. Working-tree
359
- snapshots include untracked nested Git repositories. Initialized submodules must
411
+ changes. Both require Git. Deep scans support whole repositories and path scopes.
412
+ Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
360
413
  be clean and at the commit recorded by the parent.
361
414
 
415
+ `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
416
+ committed Git scan, using the same checkout, model, and reasoning effort. Owner
417
+ errors leave the base scan completed. The JSON result includes
418
+ `ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
419
+ manifest stay unchanged. This option is unsupported for working-tree and
420
+ directory snapshots, and is skipped with a warning when `--max-cost` is set.
421
+
362
422
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
363
423
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
364
424
  explicit unsupported binary files are rejected. Bulk scans share this context
@@ -547,6 +607,9 @@ Import needs no model calls or authentication. `--dry-run` validates without
547
607
  saving; `--output-dir` and `--archive-existing` control output. `scans rerun`
548
608
  reimports the retained input.
549
609
 
610
+ For vendor exports, use [local vendor import](#import-vendor-findings-locally)
611
+ instead. That flow retains unassessed source evidence without creating a scan.
612
+
550
613
  ### Generate mock scan results
551
614
 
552
615
  ```bash
@@ -613,7 +676,9 @@ codex-security scan-components . \
613
676
  --output-dir /path/outside/project/results
614
677
  ```
615
678
 
616
- Plans use repository-relative paths:
679
+ Plans use literal repository-relative paths, so `~/src` selects a directory
680
+ named `~` inside the repository rather than expanding the home directory.
681
+ Existing absolute paths inside the repository are also accepted.
617
682
 
618
683
  ```json
619
684
  {
@@ -646,7 +711,8 @@ or API-key auth. SDK-selected command providers retain their authentication.
646
711
 
647
712
  From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
648
713
  Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
649
- planning and authentication choices.
714
+ planning and authentication choices. Custom `createSecurity` clients receive
715
+ absolute targets; saved plans and component receipts retain relative paths.
650
716
 
651
717
  ### Set investigation time
652
718
 
@@ -757,7 +823,7 @@ or Windows MCP launcher. Saved reports remain readable.
757
823
  Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
758
824
 
759
825
  `validate`, `patch`, and `verify-fix` limit native overrides to `model`,
760
- `model_reasoning_effort`, `model_provider`, `model_providers`, and
826
+ `model_reasoning_effort`, `model_provider`, `model_providers`, `daybreak`, and
761
827
  `analytics.enabled`. For a custom provider:
762
828
 
763
829
  ```bash
@@ -779,14 +845,28 @@ that command. Model, effort, and provider choices carry into patch-risk assessme
779
845
  Model requests include Codex Security attribution in `responses_api_metadata`:
780
846
  `codex_security_surface` (`cli` or `sdk`), `codex_security_command`,
781
847
  `codex_security_package_version`, and `codex_security_plugin_version` when the
782
- selected plugin declares a version. These fields identify the workflow and
783
- versions producing a model request; they do not record command starts,
784
- completions, or failures.
848
+ selected plugin declares a version. The shared context adds
849
+ `codex_security_provider` for the configured provider family when the wrapper
850
+ selects a provider, and
851
+ `codex_security_scan_mode` for scans. Custom provider names use `custom`.
852
+ Provider attribution reflects the wrapper's selected profile or default;
853
+ native managed configuration may select a different provider before inference.
854
+ The GitHub Action supplies `codex_security_integration=github_action`;
855
+ Deep Scan workers retain the context and add `codex_security_worker_role`.
856
+ Caller metadata, including literal dotted keys, is preserved. Connected-app
857
+ publication uses the same request attribution; embedding requests identify
858
+ the package and version in their `User-Agent`.
859
+
860
+ These fields provide request attribution for supported inference providers, including
861
+ Bedrock. They do not create a separate telemetry collector, record command
862
+ starts or outcomes, or make another provider's traffic visible to OpenAI.
785
863
 
786
864
  Disable Codex usage analytics and built-in metrics with
787
865
  `--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
788
866
  patch-risk assessment, and Deep Scan discovery and reducer workers, including
789
- resumed workers. Deep Scan workers also preserve the scan's request metadata.
867
+ resumed workers. Selected-profile settings take precedence over root settings.
868
+ Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
869
+ workers, including exporter choices and prompt-logging controls.
790
870
  Model-request attribution metadata remains attached when analytics are disabled.
791
871
  The setting does not control configured OpenTelemetry exporters, integrations,
792
872
  authentication, or CLI update checks. Validation uses isolated configuration;
@@ -797,24 +877,26 @@ For filesystem and approval behavior, see the
797
877
 
798
878
  ### Environment variables
799
879
 
800
- | Variable | Effect |
801
- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
802
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
803
- | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
804
- | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
805
- | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
806
- | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
807
- | `PYTHON` | Python interpreter unless an explicit option overrides it. |
808
- | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
809
- | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
810
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
811
- | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
812
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
813
- | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
814
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
815
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
816
- | `CI` | Disable interactive update notices. |
817
- | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
880
+ | Variable | Effect |
881
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
882
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
883
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
884
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
885
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
886
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
887
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
888
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
889
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
890
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
891
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
892
+ | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
893
+ | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
894
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
895
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
896
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
897
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
898
+ | `CI` | Disable interactive update notices. |
899
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
818
900
 
819
901
  Custom Codex executables need thread source attribution for `exec` and
820
902
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -848,9 +930,12 @@ Preserve existing state, then choose a private `CODEX_SECURITY_STATE_DIR` outsid
848
930
  the rejected ancestor and the repository, with a full ancestor chain that passes
849
931
  the same checks. If the volume root is rejected, another directory on that
850
932
  volume cannot resolve it; use a separately provisioned volume with trusted
851
- ancestry. Temporary bootstrap homes also need trusted ancestry: set `TEMP` and
852
- `TMP` to a private directory on that volume before launching the CLI. Do not
853
- change the system volume's owner or ACL to make a scan run. If no suitable
933
+ ancestry. On Windows, local runtime bootstrap directories are created beside
934
+ `codex-home` in the state directory and removed when the SDK client closes.
935
+ They use the same trusted ancestry checks, so sandbox write permissions on
936
+ `TEMP` do not prevent runtime preparation. `TEMP`, `TMP`, and scan output
937
+ locations are unchanged. Do not change the system volume's owner or ACL to
938
+ make a scan run. If no suitable
854
939
  location is available, this layout cannot provision credentials safely under
855
940
  the current checks. Sign in again if needed; a new state directory has separate
856
941
  scan history and does not migrate credentials or reports from the old state
@@ -1001,6 +1086,8 @@ codex-security bulk-scan repositories.csv \
1001
1086
  ```
1002
1087
 
1003
1088
  Bulk scans use clean shallow checkouts and support repository/path scopes.
1089
+ CSV scopes are literal paths relative to each checkout, including names such
1090
+ as `~/src`.
1004
1091
  Configured diff or working-tree scopes are rejected unless every affected row
1005
1092
  overrides them with a path scope. `--output-dir` requires CSV input.
1006
1093
 
@@ -1108,8 +1195,466 @@ failure or incomplete/invalid output fails the scan. Deferred candidates remain
1108
1195
  follow-up notes and do not fail the scan. An incompatible plugin stops the scan.
1109
1196
  Supply the validation prompt again when rerunning.
1110
1197
 
1198
+ ## Import vendor findings locally
1199
+
1200
+ Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
1201
+ reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
1202
+ inputs only for providers and report profiles that support them. A JSON API
1203
+ summary is not automatically a supported report; follow the provider's acquisition
1204
+ instructions and retain the original records. The readers detect supported input
1205
+ formats; `--format json` selects command output, not the input format.
1206
+
1207
+ Keep the acquisition format consistent across imports. Depending on the provider,
1208
+ switching formats can create separate records for the same vulnerability or
1209
+ replace a richer evidence snapshot with less detail. The importer does not merge
1210
+ evidence or deduplicate equivalent vulnerabilities across different source IDs.
1211
+
1212
+ Use the same vendor input and parser as Cloud publication, selecting a local
1213
+ repository path instead of a Cloud repository ID or URL. Supported inputs include
1214
+ Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
1215
+ [Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
1216
+ [Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
1217
+ and [saved GitHub alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
1218
+
1219
+ ```bash
1220
+ codex-security publish findings selected-wiz.json \
1221
+ --to local --repository ./project --provider wiz \
1222
+ --source-key TENANT_ID/vulnerability-finding --dry-run --format json
1223
+ ```
1224
+
1225
+ Review the normalized evidence, repository, source namespace, and exclusions.
1226
+ Run the same command without `--dry-run` to confirm interactively, or add `--yes`
1227
+ after reviewing the preview. `--to` is required; there is no default destination.
1228
+ Local import uses the workbench SQLite database and requires no Cloud login,
1229
+ network connection, or model call. `--dry-run` does not write findings.
1230
+
1231
+ Read the saved evidence with:
1232
+
1233
+ ```bash
1234
+ codex-security findings imported ./project --format json
1235
+ ```
1236
+
1237
+ The repository argument defaults to the current directory. Local imports are
1238
+ separate from the assessed findings shown by `findings list`: they remain
1239
+ `not_assessed`, retain the original vendor evidence, and do not create a completed
1240
+ scan or automatically validate or patch findings. Missing revisions, locations,
1241
+ and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
1242
+ Git remotes, the URL must match one of those remotes; the importer does not
1243
+ substitute the checkout's current commit for an unknown scanner revision.
1244
+
1245
+ Repeated imports update the same record by repository, provider, source key, and
1246
+ source finding ID. The result reports created, updated, and unchanged counts.
1247
+ Keep the source key stable across exports. Records omitted from a later selection
1248
+ remain stored; omission does not resolve or delete a finding. Excluded records
1249
+ are reported, and an import with exclusions exits with status 1. The same
1250
+ supported vendor formats and evidence requirements apply locally and in Cloud.
1251
+
1252
+ `scan import --json` and `scan import --csv` remain separate commands for importing
1253
+ Codex Security's findings schema as a saved scan; they do not accept vendor
1254
+ exports.
1255
+
1256
+ ## Import Endor Labs findings
1257
+
1258
+ For local or Cloud import, prefer complete native Finding JSON from authenticated
1259
+ `endorctl`, scoped to one project and context. Omit `--field-mask` and use
1260
+ `--list-all` to finish pagination:
1261
+
1262
+ ```sh
1263
+ endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
1264
+ --filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
1265
+ --list-all --output-type json > endor-findings.json
1266
+ codex-security publish findings endor-findings.json --to local \
1267
+ --provider endor --repository ./project \
1268
+ --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
1269
+ ```
1270
+
1271
+ Replace the example namespace, project UUID and local repository with your selection.
1272
+ Review the preview, remove `--dry-run` to confirm, then read the stored evidence
1273
+ with `codex-security findings imported ./project --format json`. To publish to
1274
+ Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
1275
+ file, provider and source key. The official
1276
+ [Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
1277
+ can help with setup and investigation, but summaries, counts and field-masked
1278
+ results do not replace complete Finding objects. `endorctl` reads the Endor API;
1279
+ the importer reads the saved export without maintaining an API connection or
1280
+ writing changes back to Endor.
1281
+
1282
+ Native JSON retains severity, package and advisory data, primary SAST/AI SAST
1283
+ locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
1284
+ reports are a lossy compatibility format, retaining finding links and UUIDs;
1285
+ unavailable severity and revisions stay unknown. Both formats use the Endor UUID
1286
+ within the selected repository and stable source key as identity. Importing SARIF
1287
+ after native JSON for that UUID updates the same record by replacing its evidence
1288
+ snapshot, not merging it. Native detail absent from SARIF is removed from the
1289
+ snapshot. Use native JSON consistently for ongoing imports.
1290
+
1291
+ Local and Cloud records remain unassessed source evidence. Local imports use the
1292
+ SQLite readback described above; Cloud imports use the login, preview,
1293
+ confirmation and retry flow below.
1294
+
1111
1295
  ## Publish findings to Cloud
1112
1296
 
1297
+ ### Import Snyk Open Source findings
1298
+
1299
+ Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
1300
+ SBOM results and platform backlog ingestion are outside this adapter.
1301
+
1302
+ Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
1303
+ with its `snyk-findings-export` skill to collect SCA findings from the repository's
1304
+ Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
1305
+ it does not retrieve existing platform project findings.
1306
+
1307
+ The same saved bundle supports [local import](#import-vendor-findings-locally)
1308
+ without a Cloud login:
1309
+
1310
+ ```sh
1311
+ codex-security publish findings snyk-findings.json --to local \
1312
+ --provider snyk --repository ./project \
1313
+ --source-key github.com/example/project/main/root/plugin-sca --dry-run
1314
+ ```
1315
+
1316
+ Or preview publication to a connected Cloud repository:
1317
+
1318
+ ```sh
1319
+ codex-security publish findings snyk-findings.json --to cloud \
1320
+ --provider snyk --repository https://github.com/example/project \
1321
+ --source-key github.com/example/project/main/root/plugin-sca --dry-run
1322
+ ```
1323
+
1324
+ Check the collection's scan outcomes and limitations. Only Open Source SCA
1325
+ vulnerabilities are imported; other products and licenses are explicit exclusions.
1326
+ The importer retains the selected finding, native MCP record and collection
1327
+ context. MCP may shorten descriptions and omit dependency paths. Plugin paths
1328
+ remain in original evidence because v1 lacks their offset from the Git root.
1329
+
1330
+ For automation, prefer native JSON from
1331
+ `snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
1332
+ stop on other nonzero exits before importing. The existing `--provider snyk`
1333
+ autodetects a single project object or an `--all-projects` array; any project error
1334
+ stops the import. Use default ungrouped output, without `--group-issues`.
1335
+ Native JSON preserves individual dependency paths and remediation fields. Its
1336
+ paths remain original evidence because it does not establish their Git-root offset.
1337
+
1338
+ Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
1339
+ for compatibility. Its target-relative manifest paths and synthetic line numbers
1340
+ remain original evidence, without being projected as repository locations or
1341
+ package manifest paths. All three formats accept either destination. Use a consistent
1342
+ format and stable source key per repository, branch and scan target, for example
1343
+ `github.com/example/project/main/root/native-sca` for native JSON. Their source
1344
+ identities differ: use separate keys when switching acquisition formats. Imports
1345
+ do not deduplicate across formats or remove earlier imported records.
1346
+
1347
+ Known repository claims must
1348
+ match the selected Cloud repository or, when available, a configured local Git
1349
+ remote. Unknown repository context still requires selecting the correct target;
1350
+ the importer does not infer provenance from the current checkout.
1351
+
1352
+ Remove `--dry-run` from the selected command to review and confirm the import, or
1353
+ use `--yes` after reviewing the preview. Read local records with
1354
+ `codex-security findings imported ./project --format json`. Imported source
1355
+ evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
1356
+ [Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
1357
+ acquisition details.
1358
+
1359
+ ### Import Wiz findings
1360
+
1361
+ Import selected Wiz package vulnerabilities, SAST findings, repository secrets,
1362
+ and IaC findings without creating a scan. Imported records retain vendor evidence
1363
+ and remain **not assessed by Codex**, including when Wiz marks them resolved or
1364
+ reports an AI verdict. Workload secrets, cloud configuration findings, and external
1365
+ network findings are not supported by this repository importer. Cloud destinations
1366
+ currently support connected GitHub and GitHub Enterprise repositories, including
1367
+ custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
1368
+
1369
+ Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
1370
+ connection to acquire findings and save the supported native JSON. A configured
1371
+ plugin may provide that connection; an official Codex plugin is not a prerequisite.
1372
+ The publisher reads the saved records. It does not fetch from Wiz or require a
1373
+ manual website download. The acquisition path still needs validation against
1374
+ actual responses from an authorized Wiz tenant; local parser checks do not
1375
+ establish that qualification.
1376
+
1377
+ Inspect the connection's actual response before importing it. MCP summaries,
1378
+ Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
1379
+ this finding mapper. Keep the original occurrence IDs and evidence; use the
1380
+ named collections below when the response contains repository findings.
1381
+
1382
+ Before the first import:
1383
+
1384
+ 1. Select an existing repository in Codex Security Cloud and copy its URL or
1385
+ Cloud repository ID. The repository needs an
1386
+ authorized environment, but does not need a completed native scan.
1387
+ 2. Read the selected records through the authorized connection and save their
1388
+ JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
1389
+ `vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
1390
+ package, image, and source metadata. For SAST, repository secrets, and IaC,
1391
+ retain the named API collections and repository metadata described below.
1392
+ Complete the selected pages before importing; a summary or unfinished page
1393
+ is not a complete finding selection.
1394
+ 3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
1395
+ for that Wiz tenant and finding class across exports. Do not create a new key
1396
+ for each project filter or import; that creates different source identities.
1397
+ 4. Check the ChatGPT account used by your existing file-backed Codex Security
1398
+ login. API-key-only and keyring-only logins are not supported for Cloud
1399
+ publication. See the credential-storage instructions below.
1400
+
1401
+ Prefer the supported native JSON. Existing package-vulnerability CSV reports are
1402
+ accepted as a compatibility input. **CSV support covers repository package
1403
+ vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
1404
+ Wiz code-to-cloud coverage.** The named JSON readers described below handle their
1405
+ respective finding families separately.
1406
+
1407
+ When a UI report is needed, retain the repository and finding filters in Wiz
1408
+ **Vulnerability Findings**, choose **Save as → Report**, select **Repository
1409
+ Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
1410
+ report. CSV must use the columns described below and a comma delimiter. Plain and
1411
+ gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
1412
+ filename extension. **Raw Event** on Code & Build Scans contains scan metadata
1413
+ rather than findings.
1414
+
1415
+ For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
1416
+ API root before previewing or uploading, for example
1417
+ `https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
1418
+ HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
1419
+ `::1`). Use a login issued by that deployment and an isolated
1420
+ `CODEX_SECURITY_STATE_DIR` for testing. The endpoint
1421
+ does not change your login or sign you into another deployment. An invalid or
1422
+ empty configured URL stops the import before authentication or network requests.
1423
+ With the variable unset, the existing production endpoint remains the default.
1424
+ The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
1425
+ publication endpoint; it does not route vendor imports.
1426
+
1427
+ If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
1428
+ to the full Cloud app URL shown in the browser. The import handoff supplies both
1429
+ deployment settings. The preview and result include a repository-specific
1430
+ `cloudUrl`, and terminal completion prints the link. This setting only controls
1431
+ the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
1432
+ For custom API destinations without a configured app URL, completion retains
1433
+ the manual navigation guidance rather than guessing a UI host or port.
1434
+
1435
+ Preview the selection and destination:
1436
+
1437
+ ```bash
1438
+ codex-security publish findings selected-wiz.json \
1439
+ --to cloud --repository https://github.com/example/project --provider wiz \
1440
+ --source-key TENANT_ID/vulnerability-finding --dry-run --format json
1441
+ ```
1442
+
1443
+ `--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
1444
+ destination and resume the same saved submission. This command reads the
1445
+ authorized destination and current source versions during
1446
+ preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
1447
+ repository needs an existing environment; no native scan is required. Review the
1448
+ Cloud API endpoint, account, repository, environments, findings, and exclusions,
1449
+ then rerun without
1450
+ `--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
1451
+ reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
1452
+ occurs. Existing source findings keep their Cloud environment; new findings use
1453
+ the repository’s current authorized default. Preview shows the environments that
1454
+ will receive the selected findings. The terminal preview summarizes severities,
1455
+ shows up to five finding IDs and titles, and identifies the evidence file and
1456
+ exclusions. `--dry-run --format json` retains all normalized findings and complete
1457
+ evidence for inspection. A prompt explicitly includes any records that will be
1458
+ skipped.
1459
+
1460
+ Native package input can be a Wiz JSON vulnerability report, a vulnerability
1461
+ finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
1462
+ with one package record per line. The repository package-vulnerability CSV
1463
+ profile below is also supported. Plain and gzip-compressed files are accepted.
1464
+ A response that advertises another page is rejected. Complete the requested pages
1465
+ or save only the explicitly selected records; retain the named collection for
1466
+ SAST, repository secrets, and IaC.
1467
+
1468
+ The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
1469
+ `CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
1470
+ this profile; other Wiz report types use different fields.
1471
+ For repository imports, `CloudPlatform` must identify GitHub and
1472
+ `CloudProviderURL` must identify a repository branch. The repository URL must
1473
+ match the selected Cloud repository or, for local import, one of the checkout's
1474
+ Git remotes when configured. This also applies when the parsed findings are saved and
1475
+ read again as normalized JSONL. Other resource types are excluded.
1476
+
1477
+ CSV imports use `ID` as the occurrence identity and retain every parsed field,
1478
+ including unknown columns and quoted multiline values, in `source_data.row`.
1479
+ Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
1480
+ Vendor resolution status stays in the original evidence. The importer does not
1481
+ derive a branch or revision from a tree URL, or treat last-detected time as a
1482
+ record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
1483
+ and duplicate occurrence IDs among otherwise importable records stop the import.
1484
+ Review any excluded records in the preview before publishing.
1485
+
1486
+ Normalized JSONL is also accepted:
1487
+
1488
+ ```json
1489
+ {
1490
+ "source_finding_id": "vendor-finding-42",
1491
+ "evidence": {
1492
+ "title": "Vulnerable example package",
1493
+ "severity": "high",
1494
+ "source_data": { "id": "vendor-finding-42" }
1495
+ }
1496
+ }
1497
+ ```
1498
+
1499
+ Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
1500
+ exports; a selected project filter does not change the vendor namespace. Confirm
1501
+ that the selected assets or builds map to this repository. The raw Wiz adapter
1502
+ retains each record in `source_data`, uses reported severity, and leaves unknown
1503
+ branch/revision empty. Repository-branch findings retain their repository-relative
1504
+ file paths; container and other workload paths remain vendor evidence rather than
1505
+ source-code locations. It does not
1506
+ fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
1507
+ Findings from external network scans are excluded from this package vulnerability
1508
+ mapping.
1509
+
1510
+ For SAST, repository secrets, and IaC, save the documented JSON API collection:
1511
+
1512
+ | Finding family | Collection | Raw occurrence identity |
1513
+ | ------------------ | ---------------------------- | ----------------------- |
1514
+ | SAST | `data.sastFindings.nodes` | `sast:<id>` |
1515
+ | Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
1516
+ | IaC | `data.iacFindings.nodes` | `iac:<id>` |
1517
+
1518
+ The collection identifies the mapping. Bare arrays of these raw findings are
1519
+ excluded because their overlapping fields do not identify a family. An export
1520
+ may contain multiple named collections. GraphQL errors and unfinished pages stop
1521
+ the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
1522
+ relationship to source code does not make it a repository secret.
1523
+
1524
+ Each new finding needs a verified source repository URL. Supply `repository.url`
1525
+ in the finding's repository metadata, or include the matching repository inventory
1526
+ in `data.versionControlResources.nodes`. For secrets, repository metadata is under
1527
+ `resource.typedProperties.repository`. The importer joins the inventory's
1528
+ `repository.id` to that source ID and uses `repository.url`; inventory node IDs,
1529
+ `providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
1530
+ must agree with the inventory and with the selected Cloud repository before any
1531
+ finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
1532
+ establishes case-insensitive repository matching on custom GitHub Enterprise
1533
+ hosts. Fresh imports preserve the reported branch name literally. Duplicate
1534
+ entries for one repository ID must agree on their platform and repository URL.
1535
+ For example, this synthetic selection supplies the inventory alongside its SAST
1536
+ collection:
1537
+
1538
+ ```json
1539
+ {
1540
+ "data": {
1541
+ "sastFindings": {
1542
+ "nodes": [
1543
+ {
1544
+ "id": "finding-42",
1545
+ "name": "Untrusted query construction",
1546
+ "severity": "HIGH",
1547
+ "repository": { "id": "source-repository-1" },
1548
+ "filePath": "src/query.ts",
1549
+ "startLine": 10,
1550
+ "endLine": 12
1551
+ }
1552
+ ]
1553
+ },
1554
+ "versionControlResources": {
1555
+ "nodes": [
1556
+ {
1557
+ "repository": {
1558
+ "id": "source-repository-1",
1559
+ "url": "https://github.com/example/project"
1560
+ }
1561
+ }
1562
+ ]
1563
+ }
1564
+ }
1565
+ }
1566
+ ```
1567
+
1568
+ The adapters preserve each selected raw node exactly in `source_data`. Typed
1569
+ `evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
1570
+ and family-specific evidence:
1571
+
1572
+ | Family | Evidence retained in typed fields |
1573
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
1574
+ | SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
1575
+ | Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
1576
+ | IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
1577
+
1578
+ Vendor status and verdict remain separate from Codex assessment. A secret's
1579
+ introduced commit is not its scanned revision. Missing source revisions and scan
1580
+ IDs stay unknown. A logical IaC resource is retained in the original record and
1581
+ does not establish that it is deployed. Precise original timestamps remain in
1582
+ `source_data`; only an explicit record-update timestamp maps to the whole-second
1583
+ `source_updated_at` field. SAST creation time and IaC last-seen time are not update
1584
+ timestamps.
1585
+
1586
+ Native SAST and secret report downloads can be CSV, including gzip-compressed
1587
+ CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
1588
+ for its actual column headers into normalized JSONL, preserving each original row
1589
+ in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
1590
+ verifying the source repository. Use the same prefixed occurrence ID shown above
1591
+ so API and report imports update the same finding; normalized IDs are accepted
1592
+ exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
1593
+ for a vendor occurrence ID. Missing IDs or severity must be corrected at the
1594
+ source rather than invented.
1595
+
1596
+ For repository-secret reports, select `path` and `lineNumber` for source
1597
+ navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
1598
+ as the introduced commit. The standard secret metadata API does not supply a
1599
+ path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
1600
+ `rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
1601
+ repository/branch metadata. Preserve the original fields; source locations must
1602
+ be repository-relative, and an end line requires a start line. Keep credential
1603
+ values out of the metadata selection; the importer does not retrieve or test
1604
+ credentials or apply remediation instructions.
1605
+
1606
+ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1607
+ integer range is rejected; export those values as strings to preserve them
1608
+ exactly. Invalid records appear in `excluded` with their source ID and reason.
1609
+
1610
+ Requests contain at most 100 findings and respect the Cloud payload limits.
1611
+ Before uploading, the publisher saves request IDs and bodies privately under
1612
+ the configured Codex Security state directory. After an uncertain response,
1613
+ repeat the same command with unchanged input and Cloud API endpoint to resume those
1614
+ requests. Different deployments have separate saved submissions, including when
1615
+ their account and repository IDs match. The preview and result include
1616
+ `cloudApiUrl` so scripts can verify which API received the findings; this is an
1617
+ API endpoint, not a link to the Cloud UI. A reset
1618
+ retires the old request without republishing; review and explicitly approve a
1619
+ fresh invocation.
1620
+
1621
+ Results distinguish completion from partial or interrupted work:
1622
+
1623
+ | Status | Exit code | Meaning |
1624
+ | ------------- | --------- | -------------------------------------------------------------------------------------------------- |
1625
+ | `complete` | 0 | All selected records were acknowledged and their source records read back. |
1626
+ | `partial` | 1 | The import finished, but some records were excluded locally or rejected by Cloud. |
1627
+ | `interrupted` | 2 | Upload, verification, or receipt persistence stopped; acknowledged work is included in the result. |
1628
+ | `failed` | 2 | Preparation failed before uploading; structured output includes the error. |
1629
+
1630
+ For finding imports, `--full-output` requires `--format json` or `--format jsonl`.
1631
+ Failed and interrupted imports set the envelope's `ok` to `false`, with
1632
+ `error.code: "IMPORT_FAILED"`, while retaining available results, receipts, and
1633
+ counts under `data`. Other full-output format combinations are rejected before
1634
+ reading the input or contacting Cloud; omit `--full-output` to use those formats.
1635
+
1636
+ Ctrl-C and SIGTERM retain exit codes 130 and 143. Interrupted JSON output preserves
1637
+ `receipts`, `counts`, `failures` with vendor source IDs, `excluded`, `verified`, and
1638
+ `unacknowledged`. A lost response can mean unacknowledged findings were accepted;
1639
+ resume the saved submission rather than treating them as never uploaded. When
1640
+ available, `savedSubmission` identifies the checkpoint to resume by repeating the
1641
+ same command. Review `error` before retrying; a repository reset retires the old
1642
+ submission and requires fresh approval. Correct local exclusions or final source
1643
+ conflicts before preparing a new submission.
1644
+
1645
+ Counts are cumulative for the saved submission: a resumed result includes
1646
+ batches acknowledged by earlier invocations, not just the latest upload attempt.
1647
+
1648
+ Terminal progress reports preparation, acknowledged uploads, and verification
1649
+ on stderr; JSON results stay on stdout. Lookups and readback use at most four
1650
+ concurrent requests, while uploads remain sequential. Successful receipts are
1651
+ saved locally. Verification reads the imported source records and checks their
1652
+ identities and evidence against the receipts. This does not establish a Codex
1653
+ assessment or visibility in the shared Cloud Findings view.
1654
+ When available, `cloudUrl` links to the destination repository in Cloud.
1655
+
1656
+ ### Publish completed scans
1657
+
1113
1658
  Preview selected completed scans before uploading:
1114
1659
 
1115
1660
  ```bash
@@ -1218,16 +1763,31 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
1218
1763
  codex-security classify-severity --scan-dir /path/to/completed-scan --json
1219
1764
  ```
1220
1765
 
1221
- For repository-free canonical records, use `classify-severity --records` alone.
1766
+ For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
1222
1767
  The [records protocol](classify-severity-records.md) accepts immutable Markdown and
1223
1768
  report snapshots and delegates model execution to the host.
1224
1769
 
1225
1770
  For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1226
- Omitting `--rubric` inherits original severity without model calls. Rubrics and
1227
- repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
1228
- Each finding is classified in a separate read-only turn using its report and
1229
- supplied context, without tools or source inspection. `--model` and `--effort`
1230
- override Codex's configured model and the default medium effort.
1771
+ Omitting `--rubric` runs classification with the [built-in severity rubric](../src/default-severity-rubric.ts).
1772
+ It evaluates attacker access, boundary crossing, additional harm, and evidence for
1773
+ Critical, High, Medium, Low, and Informational findings. Confidence remains separate
1774
+ from severity; missing proof alone does not justify a downgrade. An explicit
1775
+ `--rubric` replaces the default policy completely. Rubrics and repeatable
1776
+ `--knowledge-base` context accept text, PDF, DOCX, and directories.
1777
+ Each finding is classified three times by default. `--runs N` accepts
1778
+ an integer from 1 through 10; SDK options use `classificationRuns` with the same
1779
+ default and bounds. Each review runs in an independent read-only turn using the
1780
+ same report, rubric, and supplied context, without tools or source inspection.
1781
+ The most common normalized severity wins; the highest among tied top counts wins
1782
+ (`critical` > `high` > `medium` > `low` > `informational`). Exclusion is a separate
1783
+ vote: exclusions can win by count, but lose ties to assessed severities. The first answer matching the winner supplies its label, rationale,
1784
+ confidence, and review trigger. All requested reviews must succeed; failures or invalid
1785
+ answers fail that finding without saving a partial vote. This uses the requested number of model
1786
+ calls per uncached finding (three by default), including when no custom rubric is supplied, and
1787
+ requires the same Codex authentication and model access as custom classification.
1788
+ Codex retains usage for each independent turn. There is no fallback to scanner
1789
+ severity if classification fails.
1790
+ `--model` and `--effort` override Codex's configured model and the default medium effort.
1231
1791
 
1232
1792
  Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,
1233
1793
  the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
@@ -1235,10 +1795,17 @@ missing facts that could change the result. Exclusions have a null level.
1235
1795
  Finding/occurrence IDs and input hashes bind each assessment to its evidence.
1236
1796
 
1237
1797
  Successful assessments checkpoint immediately in local SQLite. Retries reuse
1238
- matching evidence, rubric, and context hashes; failed/canceled runs keep completed
1239
- work. Use `--reprocess` to replace assessments, including when changing only model
1240
- or effort. A successful run also writes `severity-classification.json`, but
1241
- publication reads the database. Original findings and sealed artifacts remain
1798
+ matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
1799
+ work. Default-rubric assessments use `source: "rubric"` and a content hash; former
1800
+ no-rubric inherited assessments have no rubric hash and are automatically
1801
+ reclassified on the next classification run. Changes to the bundled policy or
1802
+ switching between default and custom policies also invalidate matching checkpoints.
1803
+ The result and checkpoint record `classificationRuns`; changing the count, or
1804
+ reusing an older checkpoint with no recorded count, triggers fresh classification.
1805
+ Older results remain readable; publication does not silently run a model.
1806
+ Use `--reprocess` to replace assessments, including when changing only model
1807
+ or effort. A successful
1808
+ run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
1242
1809
  unchanged.
1243
1810
 
1244
1811
  Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
@@ -1309,8 +1876,9 @@ await publishScan(scanDirectory, {
1309
1876
  ```
1310
1877
 
1311
1878
  `classifySeverity()` accepts `findingId`, `title`, `summary`, and available
1312
- evidence/metadata. Imported reports may lack severity or occurrence IDs; missing
1313
- severity requires a rubric. Scan wrappers persist checkpoints (including for
1879
+ evidence/metadata. Imported reports may lack severity or occurrence IDs; omitting
1880
+ `rubricPath` uses the built-in policy even when a scanner severity is present.
1881
+ Scan wrappers persist checkpoints (including for
1314
1882
  external directories), accept `reprocess: true`, and treat `findingIds: []` as an
1315
1883
  empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
1316
1884
  publication. Older JSON-only assessments need reclassification once. All
@@ -1422,6 +1990,7 @@ least eight characters.
1422
1990
  | `scans match --all` | Match completed scans across worktrees/clones. |
1423
1991
  | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
1424
1992
  | `findings list [REPOSITORY]` | List open findings. |
1993
+ | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
1425
1994
  | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
1426
1995
 
1427
1996
  Without an ID, `scans show` selects the latest completed scan, while `scans logs`
@@ -1451,6 +2020,9 @@ scan and custom-validation prompts when the original used them:
1451
2020
  codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
1452
2021
  ```
1453
2022
 
2023
+ Saved path scopes remain relative to the repository. Names such as `~` and
2024
+ `~/source.ts` are replayed literally; they do not select the home directory.
2025
+
1454
2026
  A rerun creates a new scan. When the original has saved input identities, the
1455
2027
  rerun reports changes to the scan instructions or knowledge base. `scans show`
1456
2028
  includes the saved scope, runtime and Deep Scan settings, instruction digest,
@@ -1704,6 +2276,158 @@ record absolute Node/CLI paths. If those change, back up and remove the verified
1704
2276
  generated hook, then reinstall with the same threshold. Restore the backup if
1705
2277
  installation fails. The installer respects `core.hooksPath`.
1706
2278
 
2279
+ ## Import GitHub findings locally or to Cloud
2280
+
2281
+ Acquire code-scanning findings with the existing `import github` collector and
2282
+ save its complete JSON output. In Codex, the official
2283
+ [GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
2284
+ can help select the repository, alert numbers and ref through GitHub's MCP
2285
+ server; pass that selection to the collector. This integration reads
2286
+ code-scanning alerts and GHSA advisories. It does not import Dependabot or
2287
+ secret-scanning alerts or write back to GitHub. Preview local storage with a
2288
+ repository path:
2289
+
2290
+ ```bash
2291
+ codex-security import github example/project --format json > /path/outside/repository/alerts.json
2292
+ codex-security publish findings /path/outside/repository/alerts.json \
2293
+ --to local --provider github --repository ./project \
2294
+ --source-key github.com/example/project/code-scanning --dry-run --format json
2295
+ ```
2296
+
2297
+ Or preview publication to a connected Cloud repository:
2298
+
2299
+ ```bash
2300
+ codex-security publish findings /path/outside/repository/alerts.json \
2301
+ --to cloud --provider github --repository https://github.com/example/project \
2302
+ --source-key github.com/example/project/code-scanning --dry-run --format json
2303
+ ```
2304
+
2305
+ The importer fetches every page, retrieves alert details, and retains the selected
2306
+ ref's instance. It writes the saved input for publication; no website download or
2307
+ hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
2308
+ selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
2309
+ the default branch. MCP list calls are paginated separately, and raw MCP/API
2310
+ responses are not the saved import format accepted by `--provider github`.
2311
+
2312
+ The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
2313
+ the plugin's connection does not sign in `gh`. Reading alerts requires
2314
+ [code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
2315
+ **Code scanning alerts: read** for a fine-grained token, or `security_events` for
2316
+ a classic token (`public_repo` is sufficient for public repositories). The source
2317
+ repository must have code scanning available. For Cloud publication, the
2318
+ destination must be connected in the selected Cloud account. For local import,
2319
+ the source repository must match a configured Git remote when remotes are
2320
+ available; no Cloud login is required to store the acquired evidence.
2321
+
2322
+ Review the destination, source, exclusions and evidence in the preview. Repeat the
2323
+ selected command without `--dry-run` and confirm it, or add `--yes` for a
2324
+ previously reviewed input. Local persistence and readback follow the
2325
+ [local import flow](#import-vendor-findings-locally); use
2326
+ `codex-security findings imported ./project --format json` to read the records.
2327
+ Cloud authentication, batching, saved receipts, partial results and
2328
+ interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
2329
+ JSON, JSONL and gzip are supported. Save complete import output without field or
2330
+ token filters or `--full-output`.
2331
+
2332
+ Use a stable source key for the GitHub host, repository and finding family.
2333
+ Code-scanning identities include the selected ref, so branches retain separate
2334
+ evidence. The original alert, rule, scanner, location, revision and source state
2335
+ remain attached. An alert-wide dismissal takes precedence over the selected
2336
+ instance's open/fixed state. Missing security severity stays `unknown`;
2337
+ SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
2338
+ remains unassessed by Codex.
2339
+
2340
+ The SDK offers the same preview and publication boundary for Cloud:
2341
+
2342
+ ```ts
2343
+ import {
2344
+ importGitHubCodeScanningAlerts,
2345
+ normalizeGitHubCodeScanningAlerts,
2346
+ prepareNormalizedExternalPublication,
2347
+ } from "@openai/codex-security";
2348
+
2349
+ const alerts = await importGitHubCodeScanningAlerts({
2350
+ repository: "example/project",
2351
+ });
2352
+ const prepared = await prepareNormalizedExternalPublication(
2353
+ normalizeGitHubCodeScanningAlerts(alerts),
2354
+ {
2355
+ provider: "github",
2356
+ repository: "https://github.com/example/project",
2357
+ sourceKey: "github.com/example/project/code-scanning",
2358
+ },
2359
+ );
2360
+ console.log(prepared.preview);
2361
+ // After reviewing the preview:
2362
+ const receipt = await prepared.publish();
2363
+ ```
2364
+
2365
+ For local storage, pass the same normalized evidence to
2366
+ `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
2367
+ its preview, and call `import()`. `prepareLocalExternalImport()` accepts the saved
2368
+ import file directly. Read records with `listLocalExternalFindings({ repository })`.
2369
+
2370
+ ### Import GHSA advisories separately
2371
+
2372
+ **Importing a GHSA advisory does not establish an installed dependency or
2373
+ applicability to the destination repository.** Repository advisories are
2374
+ disclosures maintained by a repository; global advisories describe affected
2375
+ software in GitHub's public advisory database. Both are evidence for
2376
+ investigation, not Dependabot alerts. Check the repository’s dependency versions
2377
+ and applicability separately.
2378
+
2379
+ ```bash
2380
+ # Read only published advisories for this repository.
2381
+ codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
2382
+
2383
+ # Select individual public database records without enumerating the database.
2384
+ codex-security import github-advisories example/project \
2385
+ --github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
2386
+ --format json > /path/outside/repository/advisories.json
2387
+
2388
+ codex-security publish findings /path/outside/repository/advisories.json \
2389
+ --to cloud --provider github --repository https://github.com/example/project \
2390
+ --source-key github.com/example/project/security-advisories --dry-run --format json
2391
+ ```
2392
+
2393
+ For local storage, use the same advisory file, provider and source key with
2394
+ `--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
2395
+ to review, confirm and read the stored evidence.
2396
+
2397
+ `--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
2398
+ to select exact IDs from that API, regardless of advisory state. Repository
2399
+ lists default to `--github-state published`; `draft`, `triage`, and `closed`
2400
+ require explicit selection. A nondefault state cannot be combined with exact
2401
+ IDs. Global selection requires at least one ID and never lists the advisory
2402
+ database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
2403
+ the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
2404
+ [repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
2405
+ require **Repository security advisories: read**, or the classic `repo` or
2406
+ `repository_advisories:read` scope, plus access to the advisory. Public records
2407
+ need no additional advisory permission.
2408
+
2409
+ Review the saved evidence before local import or Cloud publication, including any
2410
+ selected private advisories. Acquisition failure returns no partial selection.
2411
+ Both destinations report invalid records as exclusions. Cloud publication retains
2412
+ acknowledged receipts if a later batch or readback fails.
2413
+
2414
+ Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
2415
+ patched versions, source status and original JSON. It does not infer an installed
2416
+ version or source location. Global advisories omit a source repository; the
2417
+ explicit local or Cloud destination binds the import for investigation. Repository
2418
+ advisories retain their source repository and check it against the Cloud target
2419
+ or configured local Git remotes when available. Withdrawal remains vendor
2420
+ state, and all imported evidence remains not assessed by Codex. Use a separate
2421
+ source key from code-scanning alerts; shared advisory IDs do not combine source
2422
+ records from different providers.
2423
+
2424
+ In the SDK, call `importGitHubAdvisories()` and `normalizeGitHubAdvisories()`
2425
+ with `prepareNormalizedExternalPublication()` for Cloud or
2426
+ `prepareNormalizedLocalImport()` for local storage as described above.
2427
+ `importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
2428
+ `{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
2429
+ records. Both forms require `repository: "OWNER/REPO"` as source or target context.
2430
+
1707
2431
  ## Import alerts from the CLI
1708
2432
 
1709
2433
  ```bash
@@ -1768,6 +2492,9 @@ validation, and `patch` still fixes and verifies findings. Both commands accept
1768
2492
  or literal text and work in the current directory. Saved finding/occurrence IDs
1769
2493
  select their original repository for patching.
1770
2494
 
2495
+ Basic patching also works in ordinary directories and Git worktrees before their
2496
+ first commit. Directory change tracking excludes `.git` and `.svn` metadata.
2497
+
1771
2498
  ```bash
1772
2499
  codex-security validate "Possible SQL injection" --effort high
1773
2500
  codex-security validate findings.json --knowledge-base ./context --context "Check the tenant boundary."
@@ -1897,6 +2624,18 @@ text/files, and Linear inputs. Paths resolve from the invocation directory, even
1897
2624
  when the finding belongs to another repository. The file must be nonempty and
1898
2625
  regular, is read before patching, and cannot combine with `--resume-pr`.
1899
2626
 
2627
+ Use `--verification-mode static` to assess a patch from source and diff evidence
2628
+ without installing dependencies or running builds, tests, reproducers, or the
2629
+ application. Validation instructions become questions for that source review.
2630
+ The default is `standard`, which retains the existing verification checks.
2631
+ Static results identify the evidence and state that runtime checks were not
2632
+ performed; material proof gaps can still block verification.
2633
+
2634
+ ```bash
2635
+ codex-security patch finding.md --verification-mode static
2636
+ codex-security verify-fix finding.md --verification-mode static
2637
+ ```
2638
+
1900
2639
  `--assess-patch-risk` runs an advisory assessment after patching. Human-readable
1901
2640
  output prints its report; saved-finding JSON includes `patchRisk.report`.
1902
2641
  With `--create-pr`, the draft description includes the concise Markdown summary.
@@ -1960,6 +2699,9 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
1960
2699
  finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
1961
2700
  filter for completed Linear issues to check a finished backlog.
1962
2701
 
2702
+ `--verification-mode static` selects source-only assessment, as described above
2703
+ for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2704
+
1963
2705
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
1964
2706
  `--json` returns structured output. Exit codes are `0` when all findings are
1965
2707
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.