@openai/codex-security 0.1.27 → 0.1.28

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 (187) hide show
  1. package/README.md +250 -55
  2. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  3. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/references/artifact-storage.md +56 -0
  7. package/_bundled_plugin/references/config-preflight.md +7 -1
  8. package/_bundled_plugin/references/final-report.md +2 -0
  9. package/_bundled_plugin/references/scan-artifacts.md +6 -14
  10. package/_bundled_plugin/references/scan-prologue.md +2 -0
  11. package/_bundled_plugin/references/security-guidance.md +2 -0
  12. package/_bundled_plugin/scripts/deep_scan_config.py +10 -8
  13. package/_bundled_plugin/scripts/deep_scan_defaults.json +8 -0
  14. package/_bundled_plugin/scripts/reserved_artifact_paths.json +6 -0
  15. package/_bundled_plugin/scripts/windows_scan_local_files.py +1 -3
  16. package/_bundled_plugin/scripts/workbench/storage.py +18 -0
  17. package/_bundled_plugin/scripts/workbench_cli.py +13 -0
  18. package/_bundled_plugin/scripts/workbench_db.py +13 -13
  19. package/_bundled_plugin/scripts/workbench_saved_results.py +72 -1
  20. package/_bundled_plugin/scripts/workbench_scan_usage.py +23 -10
  21. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +2 -0
  22. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +2 -0
  23. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -1
  24. package/_bundled_plugin/skills/finding-discovery/SKILL.md +2 -0
  25. package/_bundled_plugin/skills/fix-finding/SKILL.md +3 -1
  26. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +1 -1
  27. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +2 -0
  28. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +5 -1
  29. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -0
  30. package/_bundled_plugin/skills/validation/SKILL.md +2 -0
  31. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +2 -0
  32. package/dist/api.d.ts +7 -23
  33. package/dist/api.d.ts.map +1 -1
  34. package/dist/api.js +109 -113
  35. package/dist/api.js.map +1 -1
  36. package/dist/auth.d.ts.map +1 -1
  37. package/dist/auth.js.map +1 -1
  38. package/dist/bulk-scan-discovery.d.ts +1 -1
  39. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  40. package/dist/bulk-scan-discovery.js +2 -2
  41. package/dist/bulk-scan-discovery.js.map +1 -1
  42. package/dist/classify-scan-severity.js.map +1 -1
  43. package/dist/classify-severity.d.ts.map +1 -1
  44. package/dist/classify-severity.js.map +1 -1
  45. package/dist/cli.d.ts +6 -2
  46. package/dist/cli.d.ts.map +1 -1
  47. package/dist/cli.js +646 -365
  48. package/dist/cli.js.map +1 -1
  49. package/dist/cloud-publish.js.map +1 -1
  50. package/dist/component-plan.js.map +1 -1
  51. package/dist/component-scan.d.ts +4 -2
  52. package/dist/component-scan.d.ts.map +1 -1
  53. package/dist/component-scan.js +7 -1
  54. package/dist/component-scan.js.map +1 -1
  55. package/dist/config-path.d.ts +6 -0
  56. package/dist/config-path.d.ts.map +1 -0
  57. package/dist/config-path.js +6 -0
  58. package/dist/config-path.js.map +1 -0
  59. package/dist/config.d.ts +2 -0
  60. package/dist/config.d.ts.map +1 -1
  61. package/dist/config.js +13 -3
  62. package/dist/config.js.map +1 -1
  63. package/dist/contract.js.map +1 -1
  64. package/dist/cost-model.d.ts +20 -6
  65. package/dist/cost-model.d.ts.map +1 -1
  66. package/dist/cost-model.js +73 -8
  67. package/dist/cost-model.js.map +1 -1
  68. package/dist/cost.d.ts.map +1 -1
  69. package/dist/custom-publish.js.map +1 -1
  70. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  71. package/dist/deduplication/checkpointed-review.js.map +1 -1
  72. package/dist/deduplication/codex-review.d.ts.map +1 -1
  73. package/dist/deduplication/codex-review.js.map +1 -1
  74. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  75. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  76. package/dist/deduplication/deduplication.js.map +1 -1
  77. package/dist/deduplication/scan.d.ts.map +1 -1
  78. package/dist/deduplication/scan.js.map +1 -1
  79. package/dist/deep-config.d.ts +17 -0
  80. package/dist/deep-config.d.ts.map +1 -0
  81. package/dist/deep-config.js +145 -0
  82. package/dist/deep-config.js.map +1 -0
  83. package/dist/deep-progress.d.ts.map +1 -1
  84. package/dist/deep-scan-defaults.d.ts +9 -0
  85. package/dist/deep-scan-defaults.d.ts.map +1 -0
  86. package/dist/deep-scan-defaults.js +10 -0
  87. package/dist/deep-scan-defaults.js.map +1 -0
  88. package/dist/errors.d.ts.map +1 -1
  89. package/dist/errors.js +2 -2
  90. package/dist/errors.js.map +1 -1
  91. package/dist/feedback.d.ts.map +1 -1
  92. package/dist/feedback.js +21 -7
  93. package/dist/feedback.js.map +1 -1
  94. package/dist/finding-catalogue.js.map +1 -1
  95. package/dist/finding-workflow.d.ts.map +1 -1
  96. package/dist/finding-workflow.js.map +1 -1
  97. package/dist/findings-client.d.ts.map +1 -1
  98. package/dist/findings-client.js.map +1 -1
  99. package/dist/findings-import.d.ts +6 -6
  100. package/dist/github.d.ts +625 -7
  101. package/dist/github.d.ts.map +1 -1
  102. package/dist/github.js.map +1 -1
  103. package/dist/import-scan.js.map +1 -1
  104. package/dist/index.d.ts +5 -0
  105. package/dist/index.d.ts.map +1 -1
  106. package/dist/index.js +1 -0
  107. package/dist/index.js.map +1 -1
  108. package/dist/knowledge-base.d.ts.map +1 -1
  109. package/dist/knowledge-base.js +17 -6
  110. package/dist/knowledge-base.js.map +1 -1
  111. package/dist/models.d.ts.map +1 -1
  112. package/dist/models.js.map +1 -1
  113. package/dist/multiscan.d.ts +6 -6
  114. package/dist/multiscan.d.ts.map +1 -1
  115. package/dist/multiscan.js +69 -4
  116. package/dist/multiscan.js.map +1 -1
  117. package/dist/patch-tui.d.ts.map +1 -1
  118. package/dist/patch-tui.js.map +1 -1
  119. package/dist/project-config-schema.d.ts +191 -0
  120. package/dist/project-config-schema.d.ts.map +1 -0
  121. package/dist/project-config-schema.js +85 -0
  122. package/dist/project-config-schema.js.map +1 -0
  123. package/dist/project-config.d.ts +50 -0
  124. package/dist/project-config.d.ts.map +1 -0
  125. package/dist/project-config.js +220 -0
  126. package/dist/project-config.js.map +1 -0
  127. package/dist/prompt-files.d.ts +13 -0
  128. package/dist/prompt-files.d.ts.map +1 -0
  129. package/dist/prompt-files.js +74 -0
  130. package/dist/prompt-files.js.map +1 -0
  131. package/dist/publication-events.d.ts.map +1 -1
  132. package/dist/publication-events.js.map +1 -1
  133. package/dist/publish.d.ts.map +1 -1
  134. package/dist/publish.js +1 -1
  135. package/dist/publish.js.map +1 -1
  136. package/dist/result.d.ts +2 -1
  137. package/dist/result.d.ts.map +1 -1
  138. package/dist/result.js +5 -0
  139. package/dist/result.js.map +1 -1
  140. package/dist/runtime.js +4 -4
  141. package/dist/runtime.js.map +1 -1
  142. package/dist/scan-comparison.d.ts.map +1 -1
  143. package/dist/scan-comparison.js.map +1 -1
  144. package/dist/scan-dashboard.d.ts +1 -0
  145. package/dist/scan-dashboard.d.ts.map +1 -1
  146. package/dist/scan-dashboard.js +34 -22
  147. package/dist/scan-dashboard.js.map +1 -1
  148. package/dist/scan-history-renderer.d.ts.map +1 -1
  149. package/dist/scan-history-renderer.js.map +1 -1
  150. package/dist/scan-logs.d.ts +12 -5
  151. package/dist/scan-logs.d.ts.map +1 -1
  152. package/dist/scan-logs.js +49 -18
  153. package/dist/scan-logs.js.map +1 -1
  154. package/dist/scan-modes.d.ts +3 -0
  155. package/dist/scan-modes.d.ts.map +1 -0
  156. package/dist/scan-modes.js +2 -0
  157. package/dist/scan-modes.js.map +1 -0
  158. package/dist/scan-settings.d.ts +81 -0
  159. package/dist/scan-settings.d.ts.map +1 -0
  160. package/dist/scan-settings.js +123 -0
  161. package/dist/scan-settings.js.map +1 -0
  162. package/dist/security-policy-cli.js +2 -2
  163. package/dist/security-policy-cli.js.map +1 -1
  164. package/dist/security-policy.d.ts.map +1 -1
  165. package/dist/security-policy.js.map +1 -1
  166. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +2 -2
  167. package/dist/server/dashboard/app.js +2 -2
  168. package/dist/server/dashboard.js.map +1 -1
  169. package/dist/server/embeddings.d.ts.map +1 -1
  170. package/dist/server/embeddings.js.map +1 -1
  171. package/dist/server/errors.d.ts.map +1 -1
  172. package/dist/server/errors.js.map +1 -1
  173. package/dist/server/findings-service.d.ts.map +1 -1
  174. package/dist/server/findings-service.js.map +1 -1
  175. package/dist/server/serve.js.map +1 -1
  176. package/dist/server/sqlite-store.d.ts.map +1 -1
  177. package/dist/server/sqlite-store.js.map +1 -1
  178. package/dist/severity-store.js.map +1 -1
  179. package/dist/targets.d.ts +2 -1
  180. package/dist/targets.d.ts.map +1 -1
  181. package/dist/targets.js.map +1 -1
  182. package/dist/thread-source.d.ts.map +1 -1
  183. package/dist/version.js.map +1 -1
  184. package/dist/worker-progress.d.ts.map +1 -1
  185. package/dist/worker-progress.js.map +1 -1
  186. package/package.json +31 -28
  187. package/schemas/project-config.schema.json +211 -0
package/README.md CHANGED
@@ -139,21 +139,25 @@ Constructor options:
139
139
  Options for `security.run(repository, options)` and
140
140
  `security.preflight(repository, options)`:
141
141
 
142
- | Option | Description |
143
- | ----------------------- | ------------------------------------------------------------------------------ |
144
- | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
- | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
- | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
- | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
- | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
- | `outputDir` | Artifact directory outside the enclosing Git worktree. |
150
- | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
151
- | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
152
- | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
153
- | `failureSeverity` | Finding-severity policy to record in the saved scan recipe. |
154
- | `parentScanId` | Parent scan ID for a rerun. |
155
- | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
156
- | `signal` | `AbortSignal` to cancel a scan. |
142
+ | Option | Description |
143
+ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
144
+ | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
+ | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
+ | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
+ | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
+ | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
+ | `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |
150
+ | `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |
151
+ | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |
152
+ | `outputDir` | Artifact directory outside the enclosing Git worktree. |
153
+ | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
154
+ | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
155
+ | `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |
156
+ | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
157
+ | `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |
158
+ | `parentScanId` | Parent scan ID for a rerun. |
159
+ | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
160
+ | `signal` | `AbortSignal` to cancel a scan. |
157
161
 
158
162
  Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
159
163
  saved events with thread IDs and worker numbers. Deep scans can additionally use
@@ -164,6 +168,46 @@ and `maximum`. The maximum is a configured cap, not a percentage denominator.
164
168
  `preflight` and CLI `--dry-run` check local inputs without starting Codex or
165
169
  using the network. They don't authenticate, verify model access, resolve Python,
166
170
  inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.
171
+ Deep preflight includes all six resolved deep settings and their origins in
172
+ `deepScanSources`. Applicable legacy deep configuration is validated during
173
+ preflight rather than after runtime startup.
174
+
175
+ `ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,
176
+ cancellation, workflow, and runtime controls. Load the same project file used by
177
+ `scan -c` through the SDK:
178
+
179
+ ```ts
180
+ import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
181
+
182
+ const { config, options } = await loadProjectConfig("codex-security.yaml");
183
+ await using security = new CodexSecurity(config);
184
+ const result = await security.run(repository, options);
185
+ if (
186
+ options.failureSeverity !== undefined &&
187
+ result.hasFindingsAtOrAbove(options.failureSeverity)
188
+ ) {
189
+ process.exitCode = 1;
190
+ }
191
+ ```
192
+
193
+ `resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`
194
+ object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,
195
+ options }` pair and an immutable `sources` map. Resolved context, prompt, and output
196
+ paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file
197
+ from `directory`, which defaults to the current directory; paths inside the file
198
+ are relative to that file. Object paths are relative to the supplied directory.
199
+ Scope paths remain relative to the selected repository. Neither helper starts a
200
+ scan, reads prompt contents, or discovers another configuration file. `preflight`
201
+ and `run` apply the existing local checks and remaining legacy deep defaults.
202
+ Project-file keys follow Codex's configuration convention; SDK options keep their
203
+ existing `camelCase` names, and CLI flags keep `kebab-case`.
204
+
205
+ Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add
206
+ callbacks there. Direct SDK prompt-file paths use the current directory; inline
207
+ text takes precedence over its matching file. Files use the same regular-file
208
+ protections as the CLI. The SDK records `failureSeverity` without throwing or
209
+ changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering
210
+ and leaves the findings unchanged.
167
211
 
168
212
  ## Authentication
169
213
 
@@ -446,7 +490,73 @@ npx @openai/codex-security scan /path/to/repository --dry-run
446
490
 
447
491
  Use `scan --help` for options, `--version` for the installed version, and
448
492
  `info --json` for package, plugin, runtime, and model details. `--dry-run`
449
- runs local preflight checks.
493
+ runs local preflight checks. `info -c FILE --json` inspects resolved configuration
494
+ and its sources without a repository or runtime.
495
+
496
+ ### Project files
497
+
498
+ Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:
499
+
500
+ ```bash
501
+ codex-security scan . -c codex-security.yaml --dry-run --json
502
+ codex-security scan . -c codex-security.json --model gpt-5.6-terra
503
+ codex-security init
504
+ codex-security info -c codex-security.yaml --json
505
+ ```
506
+
507
+ Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,
508
+ and `info` accept `-c`. They also accept an operator-set
509
+ `CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is
510
+ loaded or discovered. The repository still comes from the command's target
511
+ selection. SDK `run()` and saved reruns do not load project files automatically.
512
+
513
+ The selected file is trusted like CLI options and SDK `codexOverrides`. Native
514
+ settings can start configured MCP server processes and select model-service destinations. Do not
515
+ select configuration controlled by an untrusted repository or pull request; keep
516
+ CI scanner configuration outside the checkout being assessed.
517
+
518
+ `init [file]` writes `codex-security.yaml` by default and never overwrites an
519
+ existing file. YAML starters show defaults as comments; JSON starters contain the
520
+ editor schema hint, relative to the chosen file and the invocation directory's
521
+ local package installation. `info` reports effective model details and native key sources
522
+ without dumping raw native values.
523
+
524
+ ```yaml
525
+ # yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json
526
+ scan:
527
+ mode: standard
528
+ scope:
529
+ paths: [src]
530
+ codex:
531
+ model: gpt-5.6-sol
532
+ model_reasoning_effort: xhigh
533
+ policy:
534
+ fail_on_severity: high
535
+ ```
536
+
537
+ All settings are optional; `{}` uses the existing defaults. JSON files can use a
538
+ root `$schema` string pointing to the same packaged schema. Schema hints are for
539
+ editors; the CLI uses its bundled validator without fetching URLs, coercing values,
540
+ or dropping unknown keys. Native `codex` settings retain their existing checks and
541
+ profile semantics. CLI `scan --schema --json` describes command arguments.
542
+
543
+ Settings use built-in defaults, applicable legacy deep defaults, the file, then
544
+ explicit CLI values. Lists and scope variants are replaced. `--head` can refine
545
+ a file diff and `--base` a file working-tree scope. A selected native profile can
546
+ still override root model/effort values. Existing native alias-conflict checks
547
+ and the behavior of `--provider openai` are unchanged.
548
+
549
+ File context, instruction, validation, and output paths resolve from the file's
550
+ directory. CLI file paths resolve from the invocation directory; scope paths
551
+ resolve from the repository. The file cannot select a different repository or
552
+ enable automatic patching/publication. The loader does not evaluate code,
553
+ interpolate environment values, include remote files, or merge multiple files.
554
+
555
+ Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected
556
+ prompt paths, and the finding policy without dumping raw native configuration.
557
+ Missing or invalid selected files exit `2`. Help, version, and command schema
558
+ output do not load project files. Existing scan and finding-policy exit codes
559
+ remain unchanged.
450
560
 
451
561
  ### Scan options and output
452
562
 
@@ -454,13 +564,18 @@ runs local preflight checks.
454
564
  and `--working-tree` scans staged and unstaged changes. Deep scans support
455
565
  repository and path targets.
456
566
 
567
+ Bulk scans use clean, shallow checkouts and support repository or path scopes.
568
+ They reject configured diff or working-tree scopes before starting unless each
569
+ affected CSV row supplies its own path scope.
570
+
457
571
  Working-tree snapshots include files from untracked nested Git repositories.
458
572
  Initialized submodules must be clean and checked out at the commit recorded by
459
573
  the parent repository.
460
574
 
461
- Repeat `--knowledge-base PATH` for Markdown, text, PDF, or Word (`.docx`) files.
462
- Directories are searched recursively. Bulk scans share these documents with
463
- every repository.
575
+ Repeat `--knowledge-base PATH` for UTF-8 text files with any extension (including
576
+ JSON and SARIF), PDF, or Word (`.docx`) files. Directories are searched recursively,
577
+ skipping other binary files. Explicitly supplied unsupported binary files are rejected.
578
+ Bulk scans share these documents with every repository.
464
579
 
465
580
  Use an empty output directory outside the scanned directory and enclosing Git
466
581
  worktree. On macOS/Linux, existing directories must be private to you
@@ -567,7 +682,7 @@ runtime or plugin compatibility. Older versions may omit the ID.
567
682
  ### Scan project components
568
683
 
569
684
  `scan --path` runs one scan across selected paths. To scan each local project
570
- component separately in standard mode, use `scan-components`:
685
+ component separately (standard mode by default), use `scan-components`:
571
686
 
572
687
  ```bash
573
688
  npx @openai/codex-security scan-components /path/to/project \
@@ -575,6 +690,12 @@ npx @openai/codex-security scan-components /path/to/project \
575
690
  --workers 4 --output-dir /path/outside/project/results
576
691
  ```
577
692
 
693
+ Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt
694
+ files, per-scan deep workers, cost limits, and severity policy. Component plans
695
+ override the file's scope. `output.directory` supplies the results directory when
696
+ `--output-dir` is omitted. A configured severity threshold returns exit `1` after
697
+ completed scans; failures or incomplete results return `2`.
698
+
578
699
  Use `--auto` instead of `--component` for a proposed split. Save a plan to
579
700
  review or edit, then run it with a new output directory:
580
701
 
@@ -651,6 +772,7 @@ await security.run("/path/to/repository", {
651
772
  workers: 2,
652
773
  subagents: 0,
653
774
  stopAfterNoNew: 3,
775
+ stopAfterConsecutiveErrors: 2,
654
776
  maxDiscoveryRuns: 10,
655
777
  maxTimeHours: 1.5,
656
778
  });
@@ -668,8 +790,10 @@ max_discovery_runs = 40
668
790
  max_time_hours = 96
669
791
  ```
670
792
 
671
- CLI and SDK options override these defaults. Set `stop_after_consecutive_errors`
672
- in the file; `--codex` cannot configure this section. Worker and run counts must
793
+ CLI and SDK options override these defaults. Project files can use
794
+ `scan.deep.stop_after_consecutive_errors`, and SDK calls can use
795
+ `stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot
796
+ configure this section. Worker and run counts must
673
797
  be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
674
798
  four workers. Unknown keys are rejected.
675
799
 
@@ -679,6 +803,12 @@ At the deadline, discovery stops; the scan combines and returns completed findin
679
803
  `scan --workers` controls discovery workers within one deep scan;
680
804
  `bulk-scan --workers` controls how many repositories are scanned concurrently.
681
805
 
806
+ The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI
807
+ `subagents` setting. A valid deep block can remain inactive in standard mode;
808
+ explicit deep CLI options require deep mode. All six active values are resolved
809
+ before runtime preparation and saved in new recipes. Complete saved values are
810
+ independent of later changes to the legacy TOML file.
811
+
682
812
  ### Runtime configuration and worker limits
683
813
 
684
814
  Scans use these isolated Codex defaults instead of your user or repository
@@ -761,23 +891,24 @@ restrictions.
761
891
 
762
892
  ### Environment variables
763
893
 
764
- | Variable | Effect |
765
- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
766
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
767
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
768
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
769
- | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
770
- | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
771
- | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
772
- | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
773
- | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
774
- | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
775
- | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
776
- | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
777
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
778
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
779
- | `CI` | Disables interactive update notices. |
780
- | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
894
+ | Variable | Effect |
895
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
896
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
897
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
898
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
899
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
900
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
901
+ | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
902
+ | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
903
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |
904
+ | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
905
+ | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
906
+ | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
907
+ | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
908
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
909
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
910
+ | `CI` | Disables interactive update notices. |
911
+ | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
781
912
 
782
913
  Custom Codex executables need thread source attribution for `exec` and
783
914
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -803,20 +934,32 @@ The final summary preserves missing-data information from a matching session log
803
934
  If the Codex runtime converts an omitted count to zero before recording it, the
804
935
  CLI cannot distinguish that zero from reported usage.
805
936
 
806
- JSON results, scan history, and bulk-scan receipts record the model, tokens,
807
- estimated cost, and `cost.pricing`: the price source, verification date, processing
808
- tier, context category, and rates in USD per million tokens. Estimates use
809
- [standard, short-context API prices](https://developers.openai.com/api/docs/pricing),
810
- including cache reads and writes. They exclude long-context and other processing
811
- tier adjustments, fees, and surcharges. GPT-5.5 and GPT-6 Astra are supported;
812
- models without known prices show an unavailable estimate.
937
+ Cost displays show a range using
938
+ [standard API prices](https://developers.openai.com/api/docs/pricing), because
939
+ runtime usage does not identify which requests received long-context pricing.
940
+ The minimum assumes short-context pricing; the maximum assumes long-context
941
+ pricing. These are token-cost estimates for the observed usage, excluding other
942
+ processing tiers, fees, surcharges, and account-specific pricing.
943
+
944
+ JSON results, scan history, and bulk-scan receipts preserve
945
+ `cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum
946
+ means an upper estimate is unavailable, including models without verified
947
+ long-context rates. `cost.pricing` records the price source, verification date,
948
+ processing tier, short-context rates, and verified long-context rates when known.
949
+ Models without known short-context prices still have no cost estimate.
813
950
 
814
951
  For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
815
952
  `cacheWriteInputTokensReported: false` means at least one included usage record
816
953
  did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
817
- In that case, the estimate prices unclassified input at the ordinary input rate;
818
- it may undercount cache-write charges. Older saved records lack this distinction
819
- and the saved pricing basis.
954
+ In that case, the range minimum prices unclassified input as ordinary input,
955
+ and the maximum allows it to be cache writes. Token counts remain unchanged.
956
+ Older saved records remain readable and display a labeled legacy estimate;
957
+ they are not repriced using current rates.
958
+
959
+ For compatibility, `cost.estimatedUsd` retains the short-context baseline used
960
+ by existing spending limits. `cost.pricing.context: "short"` describes that
961
+ baseline, not observed request contexts. Use `estimatedUsdRange` for cost
962
+ reporting. This change does not change when spending limits stop scans.
820
963
 
821
964
  `--max-cost USD` stops the scan and its workers when estimated cost exceeds
822
965
  the limit, though in-flight requests can finish above it. If deep-scan
@@ -873,6 +1016,11 @@ npx @openai/codex-security bulk-scan repositories.csv \
873
1016
 
874
1017
  `--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
875
1018
  repository's CSV `prompt` follows the shared instructions.
1019
+ `-c FILE` shares config with single scans: CSV mode/scope override file defaults,
1020
+ and deep settings apply only to deep rows. `output.directory` can supply the
1021
+ results directory. `fail_on_severity` returns exit `1` without retrying completed
1022
+ scans, including when resuming saved results. A changed project configuration
1023
+ requires a new campaign output directory.
876
1024
  `--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
877
1025
  even after a failed or incomplete scan, but not after cancellation or a
878
1026
  cost-limit stop.
@@ -927,7 +1075,8 @@ file. Source review still runs; discovery workers do not receive this prompt.
927
1075
  npx @openai/codex-security scan . --validation-prompt-file validation.md
928
1076
  ```
929
1077
 
930
- The SDK accepts the same text as `validationPrompt`:
1078
+ The SDK accepts the same file as `validationPromptFile`, or inline text as
1079
+ `validationPrompt`:
931
1080
 
932
1081
  ```ts
933
1082
  const result = await security.run(repository, {
@@ -1141,7 +1290,7 @@ Omitting `--rubric` inherits each finding's existing severity without a model ca
1141
1290
 
1142
1291
  `--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
1143
1292
  to provide supporting architecture, deployment, or business context. Both accept
1144
- the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
1293
+ the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.
1145
1294
  Rubric classification uses the full supplied report and context in a separate
1146
1295
  read-only Codex turn per finding, without source inspection, tools, or new
1147
1296
  validation. `--model` and `--effort` select the classification model and reasoning
@@ -1275,11 +1424,35 @@ and worker activity. These can contain source code, prompts, findings, tool
1275
1424
  output, and other sensitive data. Only include logs you can share with OpenAI.
1276
1425
  The command uses Codex's feedback service and respects `feedback.enabled = false`.
1277
1426
 
1427
+ For scans started through the Desktop plugin, run the command on the machine
1428
+ where the scan ran, using the same Codex home and Codex Security state directory.
1429
+ It searches active and archived sessions in both that Codex home and the CLI's
1430
+ managed home, and attaches available worker logs even if the parent log is missing.
1431
+ Earlier retries that started separate sessions may be missing when their session
1432
+ IDs are no longer recorded.
1433
+
1434
+ Standard scans run inside an existing Codex conversation attach only the owner's
1435
+ saved session; they do not record which subagents belong to the scan. Deep Scans
1436
+ and scans launched by `codex-security` also attach their recorded execution
1437
+ threads and descendants, without following unrelated children of the owner.
1438
+
1278
1439
  ### Scan history and reruns
1279
1440
 
1280
1441
  Commands default to the current repository. Select scans by full ID or a
1281
1442
  unique prefix of at least eight characters.
1282
1443
 
1444
+ New recipes retain resolved settings and the authentication choice, not
1445
+ credentials. Reruns do not reload project files; complete saved deep settings do
1446
+ not use current legacy defaults. Older partial recipes retain their previous
1447
+ fallback behavior. Context paths and the current checkout are not immutable input
1448
+ snapshots.
1449
+
1450
+ Reruns require replacement scan instructions when the original scan used them.
1451
+ New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use
1452
+ `scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.
1453
+ Replacement files resolve from the invocation directory. Custom validation keeps its existing
1454
+ `scans rerun --validation-prompt-file` requirement.
1455
+
1283
1456
  | Command | Purpose |
1284
1457
  | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
1285
1458
  | `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
@@ -1308,8 +1481,10 @@ The checkout's identity, revision, and contents must match the saved target.
1308
1481
  Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
1309
1482
 
1310
1483
  Resume uses the saved configuration and instructions with the installed plugin.
1311
- New scans save the explicit safety identifier and post-scan prompt contents.
1312
- Single-scan resume restores them even if the prompt file changes or disappears.
1484
+ New scans save the selected authentication mode, explicit safety identifier, and
1485
+ post-scan prompt contents. Resume restores the authentication choice without
1486
+ saving credentials. Single-scan resume restores the prompt even if its original
1487
+ file changes or disappears.
1313
1488
  Older records that did not save these values cannot reconstruct them. Bulk
1314
1489
  recovery still requires matching campaign inputs and options; it uses the supplied
1315
1490
  post-scan prompt when the scan has no saved prompt.
@@ -1465,11 +1640,31 @@ npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
1465
1640
  npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
1466
1641
  ```
1467
1642
 
1468
- `--scan latest` selects the current repository's latest scan. Saved-finding
1469
- patch commands support `--json`; literal-text and file inputs don't. Change
1643
+ `--scan latest` selects the current repository's latest scan. Patch commands
1644
+ support `--json`, including literal-text and file inputs. Change
1470
1645
  the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
1471
1646
  Each finding gets its own saved Codex desktop task.
1472
1647
 
1648
+ Before patching, the CLI runs a command with the task's sandbox policy. If the
1649
+ sandbox cannot start, the command exits with a nonzero status and reports
1650
+ `SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response
1651
+ with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,
1652
+ `filesChanged`, and `files`; existing local changes do not count as patch changes.
1653
+ These fields report file changes, not proof that the security issue is fixed.
1654
+ Saved findings still require a verified result from the patch task.
1655
+
1656
+ For a controlled container that provides its own isolation, explicitly opt in:
1657
+
1658
+ ```bash
1659
+ npx @openai/codex-security patch "Security issue" --external-sandbox --json
1660
+ ```
1661
+
1662
+ `--external-sandbox` defaults to false. It uses Codex's external-sandbox policy
1663
+ and prints a warning: Codex does not enforce filesystem or network isolation for
1664
+ the patch task. The container must enforce those boundaries. The CLI never
1665
+ falls back to this mode automatically. Optional patch-risk assessment still uses
1666
+ its read-only Codex sandbox.
1667
+
1473
1668
  `scan --patch` patches after a complete scan. `--patch-severity` defaults to
1474
1669
  `low`; `high` selects high and critical findings. Use the interactive browser
1475
1670
  to select findings and add patch instructions. Results include a `patches`
@@ -0,0 +1,56 @@
1
+ # Artifact Storage
2
+
3
+ Apply this policy to plugin-managed scans and standalone artifact-producing skills. An explicitly SDK-owned workflow keeps its SDK-provided directories and existing artifact-writing and completion behavior; follow its existing instructions instead of this policy. Bound Deep workers keep their existing narrow artifact tools and read-only execution profile.
4
+
5
+ ## Scan ownership
6
+
7
+ For a full scan, obtain the authoritative `scanId` before creating artifacts. Standard uses `start_codex_security_standard_scan`; a headless Diff without a scan uses `start_codex_security_prompt_only_scan` with its exact target, `mode: "diff"`, `scope: "."` and `diffTarget`. Deep uses its existing coordinator. Preserve an existing scan and handoff token. If the required MCP is unavailable or the selected baseline is unsupported, report the blocker; do not fall back to shell-authored canonical files. These rules take precedence over older terminal file-authoring fallbacks.
8
+
9
+ Keep structured outputs on their existing tools: inventories, candidate discovery, validation, attack paths, semantic drafts, checkpoints and completion. Canonical results and recovery checkpoints are persistent even while a scan is running. Never use the supplemental file tool to replace them or generate `report.md`.
10
+
11
+ ## Supplemental files
12
+
13
+ Use the existing plugin MCP's `save_codex_security_artifact` and `read_codex_security_artifact` for Markdown, optional finding write-ups, hardening documents/diagrams, validation evidence and retained helper output. Do not write these retained files with shell redirection, `apply_patch`, Python or other ordinary file-writing tools.
14
+
15
+ Identify the owner with exactly one of:
16
+
17
+ - `scanId` and the current `handoffClaimToken` when required, for a running scan;
18
+ - `targetPath`, for a standalone phase or a derived document requested after a scan completes. Use the authorized repository or input-document directory. This creates a target-bound artifact collection without starting a scan. Never invent a scan ID.
19
+
20
+ Select `storage` explicitly:
21
+
22
+ - `persistent`: retained documents/evidence under the authoritative scan directory or standalone collection. The default root is `$CODEX_SECURITY_STATE_DIR/scans`, or `$CODEX_HOME/state/plugins/codex-security/scans` when no state override is set; `CODEX_HOME` defaults to `~/.codex`. The existing `CODEX_SECURITY_SCAN_ROOT` override still takes precedence for plugin-created output. If the default workbench state is unwritable, retained artifacts follow its temporary fallback state's `scans` directory and can be removed by OS temporary-directory cleanup. Preserve an existing scan's saved path, including older temporary paths.
23
+ - `temporary`: disposable staging and execution output in a context-specific OS temporary directory. Standalone temporary saves and reads do not create or require the persistent collection. It is not part of the completed result and must not be referenced from canonical findings or coverage. It can disappear independently of retained files.
24
+
25
+ Relative storage overrides resolve from the plugin directory, matching the workbench, regardless of the MCP launch directory.
26
+
27
+ Omit `path`, `content` and `sourcePath` to prepare the selected directory. Use the returned `directory`; never construct or guess the physical path. A save with a file requires `path` plus exactly one of `content` or `sourcePath`.
28
+
29
+ Example for a running scan:
30
+
31
+ ```text
32
+ save_codex_security_artifact({ scanId, handoffClaimToken?, storage: "persistent", path: "artifacts/01_context/threat_model.md", content: "<exact Markdown>" })
33
+ save_codex_security_artifact({ scanId, handoffClaimToken?, storage: "temporary" })
34
+ save_codex_security_artifact({ scanId, handoffClaimToken?, storage: "persistent", path: "artifacts/02_discovery/validation_artifacts/<candidate_id>/poc.bin", sourcePath: "<returned temporary directory>/poc.bin" })
35
+ ```
36
+
37
+ `path` is a portable relative filename under `artifacts/`, `findings/` or `hardening/`; `report_validation.md` is also supported. Standalone collections additionally support `threat_model.md`. Use the existing relative artifact layouts for each phase. The tool returns the physical `path`, canonical `relativePath` and content digest. Use the persistent relative path in scan evidence references. Read with the same identity, `storage` and relative `path`; request `encoding: "base64"` only for binary content.
38
+
39
+ Source/configuration edits and external-publication request bodies are separate from scan artifacts and retain their existing tools and authorization. Explicit user instructions still take precedence. If a required output destination cannot be represented by managed storage, explain that limitation instead of silently substituting a different destination or claiming it was written.
40
+
41
+ ## Generated evidence and legacy helpers
42
+
43
+ PoC execution and builds can create files. Prepare `temporary` storage first and run authorized build/test/generation commands only in that workspace or its disposable repository copy. Author PoC source/input files with the save tool using `storage: "temporary"`. Tools that generate inventories, normalization output or other files must receive temporary output paths. Import each file needed in the final record with `storage: "persistent"` and `sourcePath` inside the same returned temporary directory. Import the actual bytes, not a model transcription of binary output or logs. Do not retain entire dependency/build trees without a reason.
44
+
45
+ For standalone/legacy mutable ledgers, use the save tool to replace their complete contents, or import a helper-produced temporary file. Do not append directly into the retained scan directory. Current Standard and Deep scans do not introduce legacy inventories or ledgers.
46
+
47
+ ## Threat-model cache and completed results
48
+
49
+ For the shared repository threat model, use `targetPath: <repo_root>`, `storage: "persistent"`, `path: "threat_model.md"`. Read that collection's cached file only when the threat-model workflow allows cache reuse and its exact repository/version footer matches. Save the exact selected text into `artifacts/01_context/threat_model.md` with the running scan's `scanId`. Preserve the workflow's conditions that forbid reading or replacing the shared cache; the storage tool does not authorize a cache update.
50
+
51
+ End each shared threat model with these two lines:
52
+
53
+ - `Repository: <stable target identity from scan-contract.md>`
54
+ - `Version: <revision for an immutable Git tree; snapshot digest otherwise>`
55
+
56
+ Completed/sealed scan files cannot be edited through the save tool. For later write-ups or hardening requests, use the standalone target collection and link those returned files separately. Preserve the original result and its references. Temporary cleanup must not remove retained files or recovery checkpoints. The save tool publishes running-scan files under the same completion lock as finalization; surface a stopped/sealed-scan rejection and preserve existing output.
@@ -2,6 +2,8 @@
2
2
 
3
3
  Codex Security Standard and diff scan skills should run the read-only helper before substantive scan work. Deep scans have no parent capability requirements and do not run this helper.
4
4
 
5
+ The top-level parent reads `artifact-storage.md` once before preflight and follows its scan-ownership rules, including for terminal Diff scans.
6
+
5
7
  Load `desktop-config-preflight.md` only after the host explicitly identifies itself as the Codex desktop app.
6
8
 
7
9
  Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in POSIX shells or `& "$env:PYTHON"` in PowerShell), otherwise use `python` on Windows and `python3` on Unix-like hosts. Before constructing the first helper command, inspect the current tool surface once and use that discovery result for both the runtime checks and `<verified-multi-agent-runtime-arguments>`. Do not omit active runtime facts from the first invocation and wait for an `incomplete` result before supplying them. The command is written on one line so it works in PowerShell, Command Prompt, and POSIX shells:
@@ -88,4 +90,8 @@ Codex CLI and other hosts use the same prompt-based preflight before substantive
88
90
 
89
91
  ## Daybreak Access Advisory
90
92
 
91
- After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool exactly once when available as the automatic pre-scan advisory. ChatGPT-authenticated desktop and CLI sessions both support this advisory; API-key-only sessions cannot verify account access. For Deep Security Scan, make this call immediately before `start_codex_security_deep_scan`. If this scan already performed the automatic advisory in an earlier continuation, reuse that result instead of calling it again. Report its exact `status` and available Daybreak programs. When `status` is `not_granted`, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link; if that field is absent, use `https://chatgpt.com/cyber`. Do not bury this warning in a routine status summary. When `status` is `unknown`, `stale` is `true`, or the tool is unavailable or fails, instead warn that Daybreak access could not be verified and protected scan outputs may not be displayable. Then continue regardless. This result is advisory and must never authorize or gate the scan. Do not poll it or repeat it between scan phases. If the user explicitly asks to re-check after an account or Daybreak access change, call the tool again when available for a fresh result; this user-requested refresh is the only repeat.
93
+ After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool once only if it is available in the current session. If the tool is unavailable, skip the advisory silently: do not attempt a call, probe for it, or use a replacement access tool or connector. ChatGPT-authenticated desktop and CLI sessions support this advisory; skip it silently in known API-key-only sessions, which cannot verify account access. For Deep Security Scan, make the call immediately before `start_codex_security_deep_scan`. Reuse an existing result when continuing the same scan.
94
+
95
+ If the call fails, returns `status: "unknown"`, or returns `stale: true`, continue silently. Do not expose the unavailable check, unknown status, empty program list, or a speculative protected-output warning in progress messages or the final response. For a fresh `granted` result, report the exact status and available Daybreak programs. For a fresh `not_granted` result, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link, falling back to `https://chatgpt.com/cyber` when absent.
96
+
97
+ Continue regardless: this advisory never authorizes or gates the scan. Do not retry, poll, or repeat it between phases. If the user explicitly asks about Daybreak access, report the result or explain that it could not be verified; an unavailable or unknown result does not establish that access is denied. Recheck only when the user explicitly requests a fresh result after an account or Daybreak access change, and only when the tool is available.
@@ -1,5 +1,7 @@
1
1
  # Final Report and Codex Review Directives
2
2
 
3
+ Follow `artifact-storage.md` for storing canonical results, supplementary documents and `report_validation.md`.
4
+
3
5
  Use this guidance when authoring canonical report semantics and returning the generated Codex Security report and review directives.
4
6
 
5
7
  ## Final Outputs
@@ -2,15 +2,15 @@
2
2
 
3
3
  Use these shared path conventions for Codex Security scan workflows unless the user explicitly provides different input or output paths.
4
4
 
5
+ Follow `artifact-storage.md` for storage selection, file authoring and shared threat-model cache rules.
6
+
5
7
  ## Base Paths
6
8
 
7
9
  - `plugin_dir=<codex-security plugin root>`
8
- - `repo_name=<basename of repo_root>`
9
10
  - `target_id=<stable scan target identity from references/scan-contract.md>`
10
- - `system_temp_dir=<platform temporary directory>`
11
- - `security_scans_dir=<system_temp_dir>/codex-security-scans/<repo_name>`
12
- - `scan_id=<commit>_<scan timestamp>`
13
- - `scan_dir=<security_scans_dir>/<scan_id>`
11
+ - `scan_id=<scanId returned by the MCP scan context, or CODEX_SECURITY_SCAN_ID when provided>`
12
+ - `scan_dir=<scanDir returned by the MCP scan context>`; when `CODEX_SECURITY_SCAN_DIR` is provided, use that existing SDK-owned directory. Never derive a scan directory from a repository name, revision, timestamp or temporary-directory formula.
13
+ - For a standalone phase, use the `directory` returned by `save_codex_security_artifact` for the selected `targetPath` and `storage`, as described in `artifact-storage.md`.
14
14
  - `target_paths_file=<CODEX_SECURITY_TARGET_PATHS_FILE>` for SDK scoped-path scans; reference it as `"$CODEX_SECURITY_TARGET_PATHS_FILE"` in POSIX shells or `"$env:CODEX_SECURITY_TARGET_PATHS_FILE"` in PowerShell. This read-only scope input lives in the isolated Codex home outside the model-writable scan directory. Pass it directly to `make-repo-scope-input --scopes-file` and `bind-repo-scopes --scopes-file` before finalization, and do not print, evaluate, modify, or treat its contents as shell syntax.
15
15
  - `artifacts_dir=<scan_dir>/artifacts`
16
16
  - `context_dir=<artifacts_dir>/01_context`
@@ -19,22 +19,14 @@ Use these shared path conventions for Codex Security scan workflows unless the u
19
19
  - `reconciliation_dir=<artifacts_dir>/04_reconciliation`
20
20
  - `findings_dir=<artifacts_dir>/05_findings`
21
21
 
22
- The plugin resolves the platform temporary directory automatically. For a manual workflow, use the active process temporary directory (for example, `%TEMP%` on Windows or `$TMPDIR` when configured on Unix-like hosts) instead of hardcoding `/tmp`.
23
-
24
22
  Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in POSIX shells or `& "$env:PYTHON"` in PowerShell), otherwise use `python` on Windows and `python3` on Unix-like hosts.
25
23
 
26
24
  ## Threat Model (Phase 1) Paths
27
25
 
28
26
  - Resolved SECURITY.md guidance: `<context_dir>/security_guidance.md`
29
- - Repository-scoped threat model: `<security_scans_dir>/threat_model.md`
27
+ - Repository-scoped threat model: use the shared cache policy in `artifact-storage.md`.
30
28
  - Per-scan threat model copy: `<context_dir>/threat_model.md`
31
29
  - Later scan phases should treat `<context_dir>/threat_model.md` as the source of truth.
32
- - When a repository-scoped threat model already exists, copy it to `<context_dir>/threat_model.md` without alteration for auditability.
33
-
34
- End each repository-scoped threat model with these two lines:
35
-
36
- - `Repository: <target_id>`
37
- - `Version: <revision for an immutable Git tree; snapshot digest otherwise>`
38
30
 
39
31
  ## Finding Discovery (Phase 2) Paths
40
32
 
@@ -4,6 +4,8 @@ Apply this guidance once when a Standard or Deep Security Scan owns the top-leve
4
4
 
5
5
  ## Setup and Scan Ownership
6
6
 
7
+ Read `artifact-storage.md` before choosing artifact paths and follow its scan-ownership and storage rules.
8
+
7
9
  Follow the active scan mode's existing direct-start, native-continuation, SDK-owned, or headless-launch path. Codex CLI, evaluation harnesses, automation, and other headless hosts never open or wait for a desktop workspace. An explicitly identified desktop host retains its documented app continuation and authoritative scan context.
8
10
 
9
11
  When an existing native continuation provides a `scanId`, load `get_codex_security_scan_context` once with its `handoffClaimToken` when present; preserve the returned scan identity, directory, target, scope, mode, exact `userContext`, and handoff token. If required context is missing, malformed, or belongs to another mode, follow the active entrypoint's existing error or routing behavior instead of inventing an identifier, creating a replacement scan, or widening the target. An SDK-owned scan preserves its SDK-provided scan identity and directory without creating or finalizing another scan.
@@ -4,6 +4,8 @@
4
4
 
5
5
  ## Resolve
6
6
 
7
+ Read `artifact-storage.md` for the applicable storage rules. When using its artifact MCP, request `--out -`, consume the result directly, and save the exact output as `security_guidance.md` through `save_codex_security_artifact` if required; do not pass the persistent artifact path to the helper.
8
+
7
9
  Compile the full `SECURITY.md` policy for a file or directory with:
8
10
 
9
11
  ```