@openai/codex-security 0.3.0 → 0.5.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 (244) hide show
  1. package/README.md +45 -9
  2. package/_bundled_plugin/.codex-plugin/plugin.json +5 -5
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  6. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  7. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +13 -20
  8. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  9. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  10. package/_bundled_plugin/references/core-scan.md +2 -0
  11. package/_bundled_plugin/references/final-report.md +5 -1
  12. package/_bundled_plugin/references/investigation-time-budget.md +11 -0
  13. package/_bundled_plugin/references/sarif-adapter.md +1 -0
  14. package/_bundled_plugin/references/scan-prologue.md +2 -6
  15. package/_bundled_plugin/references/scan-runtime.md +15 -0
  16. package/_bundled_plugin/references/threat-model.md +2 -0
  17. package/_bundled_plugin/schemas/coverage.schema.json +45 -126
  18. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +5 -1
  19. package/_bundled_plugin/schemas/findings.schema.json +140 -427
  20. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +106 -119
  21. package/_bundled_plugin/schemas/scan-manifest.schema.json +73 -188
  22. package/_bundled_plugin/scripts/deep_scan_workbench.py +7 -0
  23. package/_bundled_plugin/scripts/finalize_scan_contract.py +87 -49
  24. package/_bundled_plugin/scripts/finding_preview.py +5 -3
  25. package/_bundled_plugin/scripts/generate_rank_input.py +26 -106
  26. package/_bundled_plugin/scripts/launch_codex_security_mcp +39 -4
  27. package/_bundled_plugin/scripts/report_projection.py +35 -13
  28. package/_bundled_plugin/scripts/snapshot_sqlite.py +7 -0
  29. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -1
  30. package/_bundled_plugin/scripts/workbench_cli.py +9 -9
  31. package/_bundled_plugin/scripts/workbench_constants.py +4 -0
  32. package/_bundled_plugin/scripts/workbench_db.py +103 -45
  33. package/_bundled_plugin/scripts/workbench_progress.py +0 -50
  34. package/_bundled_plugin/scripts/workbench_publication.py +216 -247
  35. package/_bundled_plugin/scripts/workbench_scan_history.py +3 -2
  36. package/_bundled_plugin/scripts/workbench_scan_start.py +12 -4
  37. package/_bundled_plugin/scripts/workbench_scan_usage.py +360 -37
  38. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  39. package/_bundled_plugin/scripts/workbench_source_excerpt.py +74 -51
  40. package/_bundled_plugin/scripts/workbench_source_scopes.py +388 -0
  41. package/_bundled_plugin/scripts/workbench_target.py +7 -5
  42. package/_bundled_plugin/scripts/workbench_validation.py +52 -2
  43. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -0
  44. package/_bundled_plugin/shared/workbench-migrations.json +22 -0
  45. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
  46. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  47. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +4 -2
  48. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  49. package/_bundled_plugin/skills/security-scan/SKILL.md +4 -2
  50. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  51. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -3
  52. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +2 -0
  53. package/_bundled_plugin/skills/track-findings/SKILL.md +8 -4
  54. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  55. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +1 -1
  56. package/dist/api.d.ts +6 -2
  57. package/dist/api.d.ts.map +1 -1
  58. package/dist/api.js +266 -39
  59. package/dist/api.js.map +1 -1
  60. package/dist/artifact-export.d.ts +2 -1
  61. package/dist/artifact-export.d.ts.map +1 -1
  62. package/dist/artifact-export.js +38 -23
  63. package/dist/artifact-export.js.map +1 -1
  64. package/dist/classify-severity-records.d.ts +76 -0
  65. package/dist/classify-severity-records.d.ts.map +1 -0
  66. package/dist/classify-severity-records.js +141 -0
  67. package/dist/classify-severity-records.js.map +1 -0
  68. package/dist/classify-severity.d.ts +1 -23
  69. package/dist/classify-severity.d.ts.map +1 -1
  70. package/dist/classify-severity.js +3 -24
  71. package/dist/classify-severity.js.map +1 -1
  72. package/dist/cli-help.d.ts.map +1 -1
  73. package/dist/cli-help.js +2 -0
  74. package/dist/cli-help.js.map +1 -1
  75. package/dist/cli.d.ts +4 -2
  76. package/dist/cli.d.ts.map +1 -1
  77. package/dist/cli.js +148 -149
  78. package/dist/cli.js.map +1 -1
  79. package/dist/cloud-publish.js +1 -1
  80. package/dist/cloud-publish.js.map +1 -1
  81. package/dist/codex-sdk-environment.js +1 -1
  82. package/dist/codex-sdk-environment.js.map +1 -1
  83. package/dist/component-plan.js +1 -1
  84. package/dist/component-plan.js.map +1 -1
  85. package/dist/component-scan.d.ts.map +1 -1
  86. package/dist/component-scan.js +5 -4
  87. package/dist/component-scan.js.map +1 -1
  88. package/dist/config.d.ts +12 -0
  89. package/dist/config.d.ts.map +1 -1
  90. package/dist/config.js +10 -4
  91. package/dist/config.js.map +1 -1
  92. package/dist/contract.d.ts +6 -0
  93. package/dist/contract.d.ts.map +1 -1
  94. package/dist/contract.js +69 -20
  95. package/dist/contract.js.map +1 -1
  96. package/dist/cost-model.d.ts.map +1 -1
  97. package/dist/cost-model.js +7 -2
  98. package/dist/cost-model.js.map +1 -1
  99. package/dist/custom-validation-prompt.js +3 -3
  100. package/dist/custom-validation-prompt.js.map +1 -1
  101. package/dist/deduplication/codex-review.d.ts +1 -5
  102. package/dist/deduplication/codex-review.d.ts.map +1 -1
  103. package/dist/deduplication/codex-review.js +2 -2
  104. package/dist/deduplication/codex-review.js.map +1 -1
  105. package/dist/deduplication/deduplication-prompts.d.ts +1 -1
  106. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  107. package/dist/deduplication/deduplication-prompts.js +2 -2
  108. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  109. package/dist/deduplication/deduplication-reviewer.d.ts +1 -1
  110. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  111. package/dist/deduplication/deduplication-reviewer.js +1 -1
  112. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  113. package/dist/deduplication/records-protocol.d.ts +3 -8
  114. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  115. package/dist/deduplication/records-protocol.js +11 -171
  116. package/dist/deduplication/records-protocol.js.map +1 -1
  117. package/dist/deduplication/records.js +1 -1
  118. package/dist/deduplication/records.js.map +1 -1
  119. package/dist/deduplication/scan.d.ts.map +1 -1
  120. package/dist/deduplication/scan.js +10 -9
  121. package/dist/deduplication/scan.js.map +1 -1
  122. package/dist/deep-config.d.ts +4 -1
  123. package/dist/deep-config.d.ts.map +1 -1
  124. package/dist/deep-config.js +21 -1
  125. package/dist/deep-config.js.map +1 -1
  126. package/dist/deep-progress.d.ts +15 -1
  127. package/dist/deep-progress.d.ts.map +1 -1
  128. package/dist/deep-progress.js +15 -16
  129. package/dist/deep-progress.js.map +1 -1
  130. package/dist/executable-path.d.ts +2 -0
  131. package/dist/executable-path.d.ts.map +1 -0
  132. package/dist/executable-path.js +12 -0
  133. package/dist/executable-path.js.map +1 -0
  134. package/dist/feedback.d.ts +1 -4
  135. package/dist/feedback.d.ts.map +1 -1
  136. package/dist/feedback.js +1 -1
  137. package/dist/feedback.js.map +1 -1
  138. package/dist/findings-import.d.ts +1 -1
  139. package/dist/findings-import.d.ts.map +1 -1
  140. package/dist/findings-import.js +3 -3
  141. package/dist/findings-import.js.map +1 -1
  142. package/dist/git-remote.d.ts +10 -0
  143. package/dist/git-remote.d.ts.map +1 -0
  144. package/dist/git-remote.js +24 -0
  145. package/dist/git-remote.js.map +1 -0
  146. package/dist/github.d.ts.map +1 -1
  147. package/dist/github.js +5 -7
  148. package/dist/github.js.map +1 -1
  149. package/dist/host-protocol.d.ts +19 -0
  150. package/dist/host-protocol.d.ts.map +1 -0
  151. package/dist/host-protocol.js +270 -0
  152. package/dist/host-protocol.js.map +1 -0
  153. package/dist/host-records-protocol.d.ts +15 -0
  154. package/dist/host-records-protocol.d.ts.map +1 -0
  155. package/dist/host-records-protocol.js +15 -0
  156. package/dist/host-records-protocol.js.map +1 -0
  157. package/dist/hosted-scan-protocol.d.ts +4 -0
  158. package/dist/hosted-scan-protocol.d.ts.map +1 -0
  159. package/dist/hosted-scan-protocol.js +25 -0
  160. package/dist/hosted-scan-protocol.js.map +1 -0
  161. package/dist/hosted-scan.d.ts +112 -0
  162. package/dist/hosted-scan.d.ts.map +1 -0
  163. package/dist/hosted-scan.js +260 -0
  164. package/dist/hosted-scan.js.map +1 -0
  165. package/dist/index.d.ts +7 -0
  166. package/dist/index.d.ts.map +1 -1
  167. package/dist/index.js +3 -0
  168. package/dist/index.js.map +1 -1
  169. package/dist/knowledge-base.d.ts.map +1 -1
  170. package/dist/knowledge-base.js +87 -7
  171. package/dist/knowledge-base.js.map +1 -1
  172. package/dist/multiscan.d.ts.map +1 -1
  173. package/dist/multiscan.js +108 -36
  174. package/dist/multiscan.js.map +1 -1
  175. package/dist/patch-publication.d.ts +26 -0
  176. package/dist/patch-publication.d.ts.map +1 -0
  177. package/dist/patch-publication.js +105 -0
  178. package/dist/patch-publication.js.map +1 -0
  179. package/dist/patch-tui.d.ts.map +1 -1
  180. package/dist/patch-tui.js +4 -1
  181. package/dist/patch-tui.js.map +1 -1
  182. package/dist/project-config-schema.d.ts +2 -0
  183. package/dist/project-config-schema.d.ts.map +1 -1
  184. package/dist/project-config-schema.js +1 -0
  185. package/dist/project-config-schema.js.map +1 -1
  186. package/dist/project-config.d.ts +1 -0
  187. package/dist/project-config.d.ts.map +1 -1
  188. package/dist/project-config.js +16 -6
  189. package/dist/project-config.js.map +1 -1
  190. package/dist/publication-store.d.ts.map +1 -1
  191. package/dist/publication-store.js +73 -63
  192. package/dist/publication-store.js.map +1 -1
  193. package/dist/publication.d.ts +0 -2
  194. package/dist/publication.d.ts.map +1 -1
  195. package/dist/publication.js +135 -24
  196. package/dist/publication.js.map +1 -1
  197. package/dist/publish.d.ts.map +1 -1
  198. package/dist/publish.js +39 -25
  199. package/dist/publish.js.map +1 -1
  200. package/dist/runtime.d.ts +5 -2
  201. package/dist/runtime.d.ts.map +1 -1
  202. package/dist/runtime.js +86 -58
  203. package/dist/runtime.js.map +1 -1
  204. package/dist/scan-executor.d.ts +104 -0
  205. package/dist/scan-executor.d.ts.map +1 -0
  206. package/dist/scan-executor.js +62 -0
  207. package/dist/scan-executor.js.map +1 -0
  208. package/dist/scan-settings.d.ts +1 -0
  209. package/dist/scan-settings.d.ts.map +1 -1
  210. package/dist/scan-settings.js +7 -1
  211. package/dist/scan-settings.js.map +1 -1
  212. package/dist/scan-time-budget.d.ts +9 -0
  213. package/dist/scan-time-budget.d.ts.map +1 -0
  214. package/dist/scan-time-budget.js +16 -0
  215. package/dist/scan-time-budget.js.map +1 -0
  216. package/dist/severity-review.d.ts +29 -0
  217. package/dist/severity-review.d.ts.map +1 -0
  218. package/dist/severity-review.js +47 -0
  219. package/dist/severity-review.js.map +1 -0
  220. package/dist/targets.d.ts.map +1 -1
  221. package/dist/targets.js +17 -25
  222. package/dist/targets.js.map +1 -1
  223. package/dist/validation-records.d.ts +38 -0
  224. package/dist/validation-records.d.ts.map +1 -0
  225. package/dist/validation-records.js +76 -0
  226. package/dist/validation-records.js.map +1 -0
  227. package/dist/version.d.ts.map +1 -1
  228. package/dist/version.js +4 -2
  229. package/dist/version.js.map +1 -1
  230. package/dist/worker-progress.d.ts +43 -15
  231. package/dist/worker-progress.d.ts.map +1 -1
  232. package/dist/worker-progress.js +22 -80
  233. package/dist/worker-progress.js.map +1 -1
  234. package/docs/classify-severity-records.md +89 -0
  235. package/docs/cli.md +281 -35
  236. package/docs/hosted-scans.md +242 -0
  237. package/docs/validate-records.md +69 -0
  238. package/package.json +18 -14
  239. package/schemas/hosted-scan-v2.fixture.json +145 -0
  240. package/schemas/project-config.schema.json +7 -1
  241. package/_bundled_plugin/preflight/capability-profiles.toml +0 -76
  242. package/_bundled_plugin/references/config-preflight.md +0 -93
  243. package/_bundled_plugin/references/desktop-config-preflight.md +0 -11
  244. package/_bundled_plugin/scripts/config_preflight.py +0 -911
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:
@@ -169,6 +176,9 @@ codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
169
176
 
170
177
  export FIREWORKS_API_KEY="<your-fireworks-api-key>"
171
178
  codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
179
+
180
+ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
181
+ codex-security scan . --provider cheaperinference --model gpt-5.4
172
182
  ```
173
183
 
174
184
  ### Amazon Bedrock
@@ -354,11 +364,15 @@ SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
354
364
  explicit unsupported binary files are rejected. Bulk scans share this context
355
365
  with every repository.
356
366
 
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`).
367
+ Use `--output-dir DIR` to choose where a scan saves its results. The directory
368
+ must be empty and outside the scanned directory and enclosing Git worktree. On
369
+ macOS/Linux, existing directories must be private (`chmod 700`).
359
370
  `--archive-existing` moves earlier output to
360
371
  `<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
361
- SARIF, when produced, is saved at `<scan-dir>/exports/results.sarif`.
372
+
373
+ Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
374
+ optional export fails, the scan can still complete. Use the
375
+ [export command](#export-findings) to write or retry SARIF from the saved results.
362
376
 
363
377
  Completed scans exit with `0` by default. Configure `--fail-on-severity high`
364
378
  to return `1` for high or critical findings. Scope exclusions, skipped files, and follow-up notes
@@ -371,6 +385,13 @@ Legacy completeness values affect neither.
371
385
  Bulk and component summaries report completed and failed scans without an
372
386
  `incomplete` count. Component matching errors have status `failed`.
373
387
 
388
+ Usage coverage is separate from execution status. A recorded interruption or a
389
+ closed turn without a numeric usage receipt makes usage coverage `partial`, even
390
+ if a later turn succeeds. Recorded numeric zero is distinct from a missing
391
+ receipt. These checks describe available local records; they cannot reconstruct
392
+ requests whose usage was never persisted locally or prove an exhaustive billing
393
+ total.
394
+
374
395
  New drafts use the current finding schema: `codeEvidence`, `rootCause`,
375
396
  `attackPath.dataflow`, and `evidenceRefs`. Source snippets belong in
376
397
  `codeEvidence`; `rootCause.evidenceRefs` links to them. Legacy aliases and
@@ -406,6 +427,82 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
406
427
  its successful output and failure codes.
407
428
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
408
429
 
430
+ ### Understand scan scope and follow-up work
431
+
432
+ A completed scan means the requested workflow finished. It does not mean every
433
+ file or possible vulnerability was examined. A scan can finish with intentional
434
+ exclusions, deferred review work, or unanswered questions.
435
+
436
+ To investigate a particular run, use its scan ID explicitly:
437
+
438
+ ```bash
439
+ codex-security scans show SCAN_ID --json
440
+ codex-security scans logs SCAN_ID
441
+ ```
442
+
443
+ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
444
+ fail after registration but before writing its artifacts; investigate those
445
+ failures through its history record and any available logs. When artifacts were
446
+ retained, use the saved results directory returned by `scans show` to inspect
447
+ whichever of these files are present:
448
+
449
+ | File | What to check |
450
+ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
451
+ | `scan-manifest.json` | `scan.status`, the target snapshot, and any recorded `scan.scope` limitations. |
452
+ | `report.md` | Scope, reviewed surfaces, and open questions or follow-up work. |
453
+ | `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`. |
454
+
455
+ Deferred items can identify affected `paths` or `surfaceIds`. Surface
456
+ `receiptRefs` link to retained evidence under `artifacts/` when available.
457
+ Deep Scan summaries retain coverage from accepted worker reviews, including
458
+ worker-specific deferred work. Check those details as well as the final findings.
459
+
460
+ These records describe what the scan recorded, not an exhaustive file-by-file
461
+ audit. A retained source inventory, when present, lists inputs rather than
462
+ proving that each file was reviewed. An absent path in a surface summary does not
463
+ establish whether it was read, and the scan ID cannot reconstruct evidence that
464
+ was never saved.
465
+ Session logs can help explain failures and tool activity, but do not prove
466
+ complete review either.
467
+
468
+ For a local plugin scan, ask Codex to open the saved scan and explain its scope,
469
+ exclusions, deferred work, and follow-up questions. CLI history can also locate
470
+ that scan when it uses the same Codex home and state directory on the machine
471
+ where the scan ran. A scan ID alone does not download another machine's or
472
+ Cloud's artifacts. Preserve the saved results directory with the ID.
473
+
474
+ Choose the next step from the recorded reason:
475
+
476
+ - **The run completed and its scope matches your intent:** analyze the findings.
477
+ Record any remaining limitations; an exclusion or follow-up note alone is not
478
+ an execution failure.
479
+ - **An important path or security question remains unreviewed:** run a focused
480
+ scan with `--path`, adding relevant context with `--knowledge-base` or specific
481
+ instructions with `--scan-prompt-file`. Address missing access or context first.
482
+ Repeating the same scan does not guarantee that an omission will be resolved.
483
+ - **The run failed or was canceled:** inspect its logs and address the cause.
484
+ Use `scans rerun SCAN_ID` when the scan has a saved launch recipe; otherwise,
485
+ start a new scan with the intended scope, including for plugin scans without
486
+ a recipe. Retained findings can still be reviewed, but absence of findings
487
+ from a stopped run is inconclusive.
488
+ - **A Deep Scan was interrupted and is still recorded as `running`:** it may
489
+ support [resume](#resuming-an-interrupted-deep-scan) with the original checkout,
490
+ artifacts, and session. Completed, failed, and canceled scans cannot resume.
491
+
492
+ For example, after identifying an omitted API directory:
493
+
494
+ ```bash
495
+ codex-security scan . --path services/api --knowledge-base architecture.md
496
+ ```
497
+
498
+ Replace the path and context file with those for your repository. A new scan
499
+ reviews the current checkout; it does not amend the original saved report.
500
+
501
+ Older reports may still contain `coverage.completeness: "partial"` or
502
+ `"unknown"`. Read their scope and follow-up details to understand the limitation.
503
+ Current reports omit that field, and current commands do not use legacy
504
+ completeness values to determine scan status or exit codes.
505
+
409
506
  ### Project files
410
507
 
411
508
  ```bash
@@ -551,6 +648,29 @@ From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
551
648
  Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
552
649
  planning and authentication choices.
553
650
 
651
+ ### Set investigation time
652
+
653
+ ```bash
654
+ codex-security scan . --max-time 15
655
+ codex-security scan . --diff origin/main --max-time 15
656
+ codex-security scan . --mode deep --max-time 90
657
+ ```
658
+
659
+ `--max-time` accepts positive fractional **minutes**. Standard scans have no
660
+ time allowance by default. When selected, it is advisory: spend the available
661
+ time on useful investigation and validation, finish early if no worthwhile work
662
+ remains, and stop starting investigations at the deadline. Reporting can run
663
+ longer. This is not a hard timeout or a minimum runtime. The allowance covers
664
+ repository, path, diff, and working-tree scans; standalone custom validation and
665
+ post-scan instructions are outside it. Existing `--max-cost` and cancellation
666
+ behavior are unchanged.
667
+
668
+ The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
669
+ Each launched scan or rerun gets its own allowance after setup, and reconnects
670
+ do not reset it. Standard scans still do not support resume. For batch and
671
+ component scans, the project setting applies separately to each scan attempt,
672
+ not to planning, result matching, or the total campaign.
673
+
554
674
  ### Configure deep scans
555
675
 
556
676
  ```ts
@@ -561,19 +681,27 @@ await security.run("/path/to/repository", {
561
681
  stopAfterNoNew: 3,
562
682
  stopAfterConsecutiveErrors: 2,
563
683
  maxDiscoveryRuns: 10,
564
- maxTimeHours: 1.5,
684
+ maxTimeMinutes: 90,
565
685
  });
566
686
  ```
567
687
 
568
688
  For `scan --mode deep`, `--workers` controls discovery concurrency and
569
689
  `--subagents` controls subagents per worker. `--stop-after-no-new`,
570
- `--max-discovery-runs`, and `--max-time-hours` stop discovery by novelty, count,
690
+ `--max-discovery-runs`, and `--max-time` stop discovery by novelty, count,
571
691
  or duration. At the deadline, discovery stops; the scan then combines and returns
572
692
  completed findings.
573
693
 
574
694
  Use project-file `scan.deep` settings or legacy
575
695
  `$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.
696
+ that `subagents` can be zero. Discovery time accepts positive fractional minutes;
697
+ its default and maximum remain 5760 minutes (96 hours). Unlike Standard's
698
+ advisory allowance, this existing Deep discovery limit is enforced. Resuming a
699
+ Deep scan keeps its original deadline; rerunning starts a new scan.
700
+ `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
701
+ legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
702
+ hours. Explicit settings override lower-priority configuration across units.
703
+ At the winning source, conflicting minute/hour durations are errors; equivalent
704
+ durations are accepted.
577
705
  `stopAfterConsecutiveErrors` is an SDK/project-file setting, with no CLI flag.
578
706
  `--codex` does not configure deep-scan settings. See
579
707
  [Deep settings and limits](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md#deep-settings-and-limits).
@@ -709,10 +837,24 @@ Finish older-version operations before upgrading. Never remove
709
837
  `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
710
838
  credential home before manually removing an old `.codex-security-scan.lock`.
711
839
 
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.
840
+ On Windows, credential-home checks require trusted ownership and permissions
841
+ through every ancestor, including the volume root. Codex Security can repair
842
+ the credential home and its descendants; it does not change ancestor ownership
843
+ or ACLs. An error identifies the rejected ancestor and its underlying ACL
844
+ problem. A volume root owned by `Everyone` (`S-1-1-0`) is unsupported, even when
845
+ the credential home itself is private.
846
+
847
+ Preserve existing state, then choose a private `CODEX_SECURITY_STATE_DIR` outside
848
+ the rejected ancestor and the repository, with a full ancestor chain that passes
849
+ the same checks. If the volume root is rejected, another directory on that
850
+ 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
854
+ location is available, this layout cannot provision credentials safely under
855
+ the current checks. Sign in again if needed; a new state directory has separate
856
+ scan history and does not migrate credentials or reports from the old state
857
+ directory.
716
858
 
717
859
  ### Progress and cost
718
860
 
@@ -726,6 +868,19 @@ input. Missing cache-write usage makes the uncached/cache-write breakdown
726
868
  unavailable. The CLI cannot recover missing information already recorded as zero
727
869
  by the runtime.
728
870
 
871
+ Completed scan history also saves rollout observations under `usage`, alongside
872
+ any `cost` estimate. `byRole` separates parent tokens from combined worker tokens.
873
+ `window` bounds the counted events, `observedAt` records collection time, and
874
+ `tokensUpdatedAt` records the newest token receipt. Partial coverage means some
875
+ work could not be measured, including in-flight turns or missing earlier attempts.
876
+ The parent can continue after report completion, so final CLI tokens can exceed
877
+ the saved measurement window.
878
+
879
+ `usage.accountRateLimits` saves the latest observed account-wide readings with
880
+ their own timestamps, window durations, and reset times. These are historical
881
+ observations, not a live allowance check or scan-only consumption. Empty readings
882
+ mean allowance was unavailable. There is no token-to-allowance conversion here.
883
+
729
884
  Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
730
885
  and show a short/long-context range. They estimate model usage, excluding other
731
886
  tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
@@ -858,6 +1013,10 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
858
1013
  attempt per pending repository per invocation. Repeating the command continues
859
1014
  the campaign, skips completed results, and starts pending attempts. Occupied
860
1015
  attempt directories stop that repository and suggest `--recover`.
1016
+ Completed results are skipped only when their saved contract and seal are valid
1017
+ and the manifest records a completed scan. Damaged or unsuccessful results get a
1018
+ new attempt, including with `--recover`, while the old artifacts remain available.
1019
+ Missing or invalid plugin schemas stop resume without starting another scan.
861
1020
  Changes to project configuration, extracted knowledge-base text, staged document
862
1021
  filenames, direct Codex overrides, or explicit `--plugin-path`/`--python` selections
863
1022
  require a new output directory. Version 1 manifests also require a new directory
@@ -1023,10 +1182,16 @@ creation; connected-app access is reported as `not-checked`.
1023
1182
 
1024
1183
  Each finding becomes an issue with severity, source, evidence, and remediation.
1025
1184
  Choose a destination authorized to receive that content. Local history records
1026
- successful issue IDs separately from sealed artifacts.
1185
+ successful issue IDs separately from sealed artifacts. The CLI and the plugin's
1186
+ finding-tracking workflow share these records when using the same Codex Security
1187
+ state directory. Accepted writes remain recorded even if a later issue read fails.
1188
+ The shared-history migration preserves existing Linear receipts and replaces their
1189
+ old table. Upgrade CLI and plugin installations together when they share state;
1190
+ older publishers cannot write to the migrated database.
1027
1191
 
1028
1192
  Republishing creates duplicates unless `--skip-existing` finds a recorded success
1029
- for that occurrence, team, and project. It does not check remote issues or cover
1193
+ for that occurrence, team, and project, including issues created or reused through
1194
+ the plugin. It does not check remote issues or cover
1030
1195
  unrecorded/concurrent publication. After interruption, inspect the handoff,
1031
1196
  evidence, and destination before retrying.
1032
1197
 
@@ -1053,7 +1218,11 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
1053
1218
  codex-security classify-severity --scan-dir /path/to/completed-scan --json
1054
1219
  ```
1055
1220
 
1056
- Use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1221
+ For repository-free canonical records, use `classify-severity --records` alone.
1222
+ The [records protocol](classify-severity-records.md) accepts immutable Markdown and
1223
+ report snapshots and delegates model execution to the host.
1224
+
1225
+ For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1057
1226
  Omitting `--rubric` inherits original severity without model calls. Rubrics and
1058
1227
  repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
1059
1228
  Each finding is classified in a separate read-only turn using its report and
@@ -1375,31 +1544,80 @@ Progress callback failures do not stop matching.
1375
1544
 
1376
1545
  ## Exports and CI
1377
1546
 
1378
- `export` reads saved results without Codex or credentials. It defaults to the
1379
- current repository's latest completed scan. Choose either a positional result
1380
- directory or `--scan ID`. Findings require sealed results and support
1381
- `--export-format csv|json|sarif` (default SARIF). `--source-root PATH` adds SARIF
1382
- source-line fingerprints.
1547
+ Export saved findings and threat models without rerunning a scan or signing in.
1548
+
1549
+ ### Export findings
1550
+
1551
+ To save a completed scan's findings as SARIF, run:
1552
+
1553
+ ```bash
1554
+ codex-security export /path/to/scan-results --output results.sarif
1555
+ ```
1556
+
1557
+ Replace `/path/to/scan-results` with the results directory printed by `scan`.
1558
+ The command writes `results.sarif` in the current directory. The output directory
1559
+ must already exist.
1560
+
1561
+ SARIF is the default format, and `./results.sarif` is the default output path.
1562
+ Use `--export-format json` or `--export-format csv` to choose another format.
1563
+ To select a saved scan by its ID and export JSON, run:
1383
1564
 
1384
1565
  ```bash
1385
1566
  codex-security export --scan SCAN_ID --export-format json --output findings.json
1386
- codex-security export --artifact threat-model --output docs/threatmodel.md
1387
- codex-security export /path/to/policy-results --artifact threat-model --output -
1388
1567
  ```
1389
1568
 
1390
- Threat-model exports use Markdown and default to `./threatmodel.md`. Standard,
1391
- Deep, Diff, and policy workflows retain models when available; component/bulk
1392
- runs save one per child. Explicit results may expose a model before completion
1393
- or after later failure. Missing models return an error rather than generating
1394
- or substituting one. Historical models in sealed scans need a matching manifest
1395
- digest.
1569
+ Replace `SCAN_ID` with the ID printed by `scan`. If you omit both the results
1570
+ directory and `--scan`, `export` uses the current repository's latest completed
1571
+ scan.
1572
+
1573
+ JSON preserves the saved findings. CSV marks them open, omits local triage state,
1574
+ and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
1575
+ leading apostrophes; import removes the escape. Use JSON to recover ambiguous
1576
+ apostrophes from older CSV exports.
1577
+
1578
+ For SARIF, `--source-root` adds source-line fingerprints that help tools match
1579
+ findings across scans. Before changing the scanned files or applying patches,
1580
+ run the export from the scanned repository's root:
1581
+
1582
+ ```bash
1583
+ codex-security export /path/to/scan-results --source-root . --output results.sarif
1584
+ ```
1585
+
1586
+ The `.` selects the current directory as the source root. Its source files must
1587
+ be unchanged since the scan. `--source-root` is supported only for SARIF.
1588
+
1589
+ If export fails, it exits with `2`. Fix the reported error and rerun the export;
1590
+ the saved scan remains available, so you don't need to run another scan.
1591
+
1592
+ ### Export a threat model
1593
+
1594
+ To save a scan's threat model as Markdown, run:
1595
+
1596
+ ```bash
1597
+ codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md
1598
+ ```
1599
+
1600
+ Threat-model exports default to `./threatmodel.md`. Standard, Deep, Diff, and
1601
+ policy workflows retain models when available; component/bulk runs save one per
1602
+ child. With an explicit results directory, you can export a saved threat model
1603
+ even if the workflow has not completed or later failed. Missing models return
1604
+ an error rather than generating or substituting one. Historical models in sealed
1605
+ scans need a matching manifest digest.
1606
+
1607
+ To print a policy workflow's saved threat model, pass its results directory and
1608
+ `--output -`:
1609
+
1610
+ ```bash
1611
+ codex-security export /path/to/policy-results --artifact threat-model --output -
1612
+ ```
1396
1613
 
1397
1614
  `--output -` emits only artifact content, with diagnostics on stderr. Markdown
1398
1615
  and CSV stdout cannot combine with JSON command output. Exporting into a checkout
1399
1616
  does not make the model scan input; pass it with `--knowledge-base`.
1400
1617
 
1401
- `ScanResult.threatModel` and `threatModelPath` expose the retained model and
1402
- document, or null. Export still works if the document could not be written.
1618
+ ### Export with the SDK
1619
+
1620
+ Use `exportArtifact()` to export saved results from TypeScript:
1403
1621
 
1404
1622
  ```ts
1405
1623
  import { exportArtifact } from "@openai/codex-security";
@@ -1416,12 +1634,12 @@ Use `artifact: "findings"` with `format: "csv" | "json" | "sarif"` for findings.
1416
1634
  `output: "-"` streams stdout and returns null path/provenance. `pythonPath`
1417
1635
  selects an interpreter; `signal` cancels.
1418
1636
 
1419
- JSON preserves sealed findings. CSV marks them open, omits local triage state,
1420
- and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
1421
- leading apostrophes; import removes the escape. Use JSON to recover ambiguous
1422
- apostrophes from older CSV exports.
1637
+ `ScanResult.threatModel` and `threatModelPath` expose the retained model and
1638
+ document, or null. Export still works if the document could not be written.
1423
1639
 
1424
- For CI, place output outside the checkout and set a severity threshold:
1640
+ ### Use exports in CI
1641
+
1642
+ Save each scan's results outside the checkout and set a severity threshold:
1425
1643
 
1426
1644
  ```bash
1427
1645
  SCAN_ROOT="$(mktemp -d)"
@@ -1437,6 +1655,21 @@ codex-security scan . --diff origin/main \
1437
1655
  | `2` | Invalid input, runtime error, target change, or required-output failure. |
1438
1656
  | `130` / `143` | Interrupt / termination. |
1439
1657
 
1658
+ If the scan exits with `2`, `130`, or `143`, skip export and upload. After a scan
1659
+ exits with `0` or `1`, use these steps:
1660
+
1661
+ 1. Export from that run's results directory. Using the explicit directory keeps
1662
+ concurrent scans from changing which results are selected:
1663
+
1664
+ ```bash
1665
+ codex-security export "$SCAN_ROOT/results" --source-root . \
1666
+ --output "$SCAN_ROOT/results.sarif"
1667
+ ```
1668
+
1669
+ 2. If export succeeds, upload the SARIF file.
1670
+ 3. If the scan exited with `1`, keep the CI job failed so the severity threshold
1671
+ remains enforced.
1672
+
1440
1673
  JSON scans have no interactive controls. `validate`, `login`, and `logout` reject
1441
1674
  `--json`. Use `validate --output-schema FILE` for a schema-checked JSON assessment.
1442
1675
  For GitHub Actions setup, see the
@@ -1524,6 +1757,10 @@ The token needs code-scanning read access; access failures reject the import.
1524
1757
 
1525
1758
  ## Validate and patch findings
1526
1759
 
1760
+ Hosts that manage their own model execution can use `codex-security validate --records`.
1761
+ This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
1762
+ See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
1763
+
1527
1764
  `validate` assesses candidates from local source evidence without building the
1528
1765
  target, executing application code, running tests or PoCs, or contacting services.
1529
1766
  It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
@@ -1651,6 +1888,8 @@ Both candidate IDs remain in the output, including the unresolved claim.
1651
1888
  `--scan latest` uses the current repository's latest completed scan. Patching
1652
1889
  supports JSON for saved findings, literal text, and files. Each finding gets a
1653
1890
  saved Codex desktop task. `--model` and `--effort` control the model.
1891
+ Saved-scan patching and fix verification use the complete sealed finding evidence
1892
+ and exclude findings that are currently closed in triage.
1654
1893
 
1655
1894
  `--validation-prompt-file PATH` supplies setup, authorized targets, expected
1656
1895
  results, and cleanup for dynamic validation. It works with saved findings,
@@ -1731,8 +1970,11 @@ Use `--llms` for the command manifest, `scan --schema --format json` for its
1731
1970
  schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
1732
1971
  `--format toon|json|yaml|jsonl` and `--full-output`.
1733
1972
 
1734
- `skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
1735
- MCP exposes only read-only `info`, because the transport cannot cancel scans.
1973
+ `skills add` syncs generated CLI command guidance; it does not install the full
1974
+ Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
1975
+ only read-only `info` because the transport cannot cancel scans. For the plugin's
1976
+ scan, triage, patch, and verification workflows, see the
1977
+ [agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
1736
1978
 
1737
1979
  For local findings storage, deduplication, and custom endpoints, see the
1738
1980
  [findings guide](findings-service.md).
@@ -1776,3 +2018,7 @@ capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested us
1776
2018
  namespaces do not need it. The legacy Landlock fallback is unsupported.
1777
2019
  See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
1778
2020
  for deployment and source-build instructions.
2021
+
2022
+ ### Hosted Standard scan
2023
+
2024
+ `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.