@openai/codex-security 0.1.27 → 0.1.29

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 (214) hide show
  1. package/README.md +328 -59
  2. package/_bundled_plugin/examples/completed-scan/report.md +0 -1
  3. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/references/artifact-storage.md +56 -0
  8. package/_bundled_plugin/references/config-preflight.md +7 -1
  9. package/_bundled_plugin/references/final-report.md +2 -0
  10. package/_bundled_plugin/references/scan-artifacts.md +6 -14
  11. package/_bundled_plugin/references/scan-prologue.md +2 -0
  12. package/_bundled_plugin/references/security-guidance.md +2 -0
  13. package/_bundled_plugin/scripts/deep_scan_config.py +10 -8
  14. package/_bundled_plugin/scripts/deep_scan_defaults.json +8 -0
  15. package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -0
  16. package/_bundled_plugin/scripts/generate_in_scope_files.py +12 -2
  17. package/_bundled_plugin/scripts/generate_rank_input.py +1 -6
  18. package/_bundled_plugin/scripts/rank_preview.py +8 -7
  19. package/_bundled_plugin/scripts/report_projection.py +0 -1
  20. package/_bundled_plugin/scripts/reserved_artifact_paths.json +6 -0
  21. package/_bundled_plugin/scripts/windows_scan_local_files.py +1 -3
  22. package/_bundled_plugin/scripts/workbench/storage.py +18 -0
  23. package/_bundled_plugin/scripts/workbench_cli.py +13 -0
  24. package/_bundled_plugin/scripts/workbench_dashboard.py +24 -3
  25. package/_bundled_plugin/scripts/workbench_db.py +13 -13
  26. package/_bundled_plugin/scripts/workbench_saved_results.py +77 -1
  27. package/_bundled_plugin/scripts/workbench_scan_usage.py +23 -10
  28. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +2 -0
  29. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +2 -0
  30. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -1
  31. package/_bundled_plugin/skills/finding-discovery/SKILL.md +2 -0
  32. package/_bundled_plugin/skills/fix-finding/SKILL.md +3 -1
  33. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +1 -1
  34. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +2 -0
  35. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +5 -1
  36. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -0
  37. package/_bundled_plugin/skills/validation/SKILL.md +2 -0
  38. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +2 -0
  39. package/dist/api.d.ts +7 -23
  40. package/dist/api.d.ts.map +1 -1
  41. package/dist/api.js +109 -113
  42. package/dist/api.js.map +1 -1
  43. package/dist/auth.d.ts.map +1 -1
  44. package/dist/auth.js.map +1 -1
  45. package/dist/bulk-scan-discovery.d.ts +1 -1
  46. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  47. package/dist/bulk-scan-discovery.js +2 -2
  48. package/dist/bulk-scan-discovery.js.map +1 -1
  49. package/dist/classify-scan-severity.js.map +1 -1
  50. package/dist/classify-severity.d.ts.map +1 -1
  51. package/dist/classify-severity.js.map +1 -1
  52. package/dist/cli-scan-logs-json.d.ts +3 -0
  53. package/dist/cli-scan-logs-json.d.ts.map +1 -0
  54. package/dist/cli-scan-logs-json.js +22 -0
  55. package/dist/cli-scan-logs-json.js.map +1 -0
  56. package/dist/cli.d.ts +6 -2
  57. package/dist/cli.d.ts.map +1 -1
  58. package/dist/cli.js +802 -394
  59. package/dist/cli.js.map +1 -1
  60. package/dist/cloud-publish.js.map +1 -1
  61. package/dist/component-plan.js.map +1 -1
  62. package/dist/component-scan.d.ts +4 -2
  63. package/dist/component-scan.d.ts.map +1 -1
  64. package/dist/component-scan.js +7 -1
  65. package/dist/component-scan.js.map +1 -1
  66. package/dist/config-path.d.ts +6 -0
  67. package/dist/config-path.d.ts.map +1 -0
  68. package/dist/config-path.js +6 -0
  69. package/dist/config-path.js.map +1 -0
  70. package/dist/config.d.ts +2 -0
  71. package/dist/config.d.ts.map +1 -1
  72. package/dist/config.js +13 -3
  73. package/dist/config.js.map +1 -1
  74. package/dist/contract.js.map +1 -1
  75. package/dist/cost-model.d.ts +20 -6
  76. package/dist/cost-model.d.ts.map +1 -1
  77. package/dist/cost-model.js +73 -8
  78. package/dist/cost-model.js.map +1 -1
  79. package/dist/cost.d.ts.map +1 -1
  80. package/dist/custom-publish.js.map +1 -1
  81. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  82. package/dist/deduplication/checkpointed-review.js.map +1 -1
  83. package/dist/deduplication/codex-review.d.ts.map +1 -1
  84. package/dist/deduplication/codex-review.js +26 -4
  85. package/dist/deduplication/codex-review.js.map +1 -1
  86. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  87. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  88. package/dist/deduplication/deduplication.d.ts +12 -1
  89. package/dist/deduplication/deduplication.d.ts.map +1 -1
  90. package/dist/deduplication/deduplication.js +41 -7
  91. package/dist/deduplication/deduplication.js.map +1 -1
  92. package/dist/deduplication/refusal.d.ts +3 -0
  93. package/dist/deduplication/refusal.d.ts.map +1 -0
  94. package/dist/deduplication/refusal.js +16 -0
  95. package/dist/deduplication/refusal.js.map +1 -0
  96. package/dist/deduplication/scan.d.ts.map +1 -1
  97. package/dist/deduplication/scan.js.map +1 -1
  98. package/dist/deep-config.d.ts +17 -0
  99. package/dist/deep-config.d.ts.map +1 -0
  100. package/dist/deep-config.js +145 -0
  101. package/dist/deep-config.js.map +1 -0
  102. package/dist/deep-progress.d.ts.map +1 -1
  103. package/dist/deep-scan-defaults.d.ts +9 -0
  104. package/dist/deep-scan-defaults.d.ts.map +1 -0
  105. package/dist/deep-scan-defaults.js +10 -0
  106. package/dist/deep-scan-defaults.js.map +1 -0
  107. package/dist/errors.d.ts +1 -1
  108. package/dist/errors.d.ts.map +1 -1
  109. package/dist/errors.js +2 -2
  110. package/dist/errors.js.map +1 -1
  111. package/dist/feedback.d.ts.map +1 -1
  112. package/dist/feedback.js +21 -7
  113. package/dist/feedback.js.map +1 -1
  114. package/dist/finding-catalogue.js.map +1 -1
  115. package/dist/finding-workflow.d.ts.map +1 -1
  116. package/dist/finding-workflow.js.map +1 -1
  117. package/dist/findings-client.d.ts.map +1 -1
  118. package/dist/findings-client.js.map +1 -1
  119. package/dist/findings-import.d.ts +6 -6
  120. package/dist/github.d.ts +625 -7
  121. package/dist/github.d.ts.map +1 -1
  122. package/dist/github.js.map +1 -1
  123. package/dist/import-scan.js.map +1 -1
  124. package/dist/index.d.ts +6 -0
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +1 -0
  127. package/dist/index.js.map +1 -1
  128. package/dist/knowledge-base.d.ts.map +1 -1
  129. package/dist/knowledge-base.js +17 -6
  130. package/dist/knowledge-base.js.map +1 -1
  131. package/dist/models.d.ts.map +1 -1
  132. package/dist/models.js.map +1 -1
  133. package/dist/multiscan.d.ts +6 -6
  134. package/dist/multiscan.d.ts.map +1 -1
  135. package/dist/multiscan.js +69 -4
  136. package/dist/multiscan.js.map +1 -1
  137. package/dist/patch-tui.d.ts.map +1 -1
  138. package/dist/patch-tui.js.map +1 -1
  139. package/dist/project-config-schema.d.ts +191 -0
  140. package/dist/project-config-schema.d.ts.map +1 -0
  141. package/dist/project-config-schema.js +85 -0
  142. package/dist/project-config-schema.js.map +1 -0
  143. package/dist/project-config.d.ts +50 -0
  144. package/dist/project-config.d.ts.map +1 -0
  145. package/dist/project-config.js +220 -0
  146. package/dist/project-config.js.map +1 -0
  147. package/dist/prompt-files.d.ts +13 -0
  148. package/dist/prompt-files.d.ts.map +1 -0
  149. package/dist/prompt-files.js +74 -0
  150. package/dist/prompt-files.js.map +1 -0
  151. package/dist/publication-events.d.ts.map +1 -1
  152. package/dist/publication-events.js.map +1 -1
  153. package/dist/publish.d.ts.map +1 -1
  154. package/dist/publish.js +1 -1
  155. package/dist/publish.js.map +1 -1
  156. package/dist/result.d.ts +2 -1
  157. package/dist/result.d.ts.map +1 -1
  158. package/dist/result.js +5 -0
  159. package/dist/result.js.map +1 -1
  160. package/dist/runtime.js +4 -4
  161. package/dist/runtime.js.map +1 -1
  162. package/dist/scan-comparison.d.ts.map +1 -1
  163. package/dist/scan-comparison.js.map +1 -1
  164. package/dist/scan-dashboard.d.ts +1 -0
  165. package/dist/scan-dashboard.d.ts.map +1 -1
  166. package/dist/scan-dashboard.js +34 -22
  167. package/dist/scan-dashboard.js.map +1 -1
  168. package/dist/scan-history-renderer.d.ts.map +1 -1
  169. package/dist/scan-history-renderer.js.map +1 -1
  170. package/dist/scan-logs.d.ts +12 -5
  171. package/dist/scan-logs.d.ts.map +1 -1
  172. package/dist/scan-logs.js +76 -19
  173. package/dist/scan-logs.js.map +1 -1
  174. package/dist/scan-modes.d.ts +3 -0
  175. package/dist/scan-modes.d.ts.map +1 -0
  176. package/dist/scan-modes.js +2 -0
  177. package/dist/scan-modes.js.map +1 -0
  178. package/dist/scan-settings.d.ts +81 -0
  179. package/dist/scan-settings.d.ts.map +1 -0
  180. package/dist/scan-settings.js +123 -0
  181. package/dist/scan-settings.js.map +1 -0
  182. package/dist/security-policy-cli.js +2 -2
  183. package/dist/security-policy-cli.js.map +1 -1
  184. package/dist/security-policy.d.ts.map +1 -1
  185. package/dist/security-policy.js.map +1 -1
  186. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +3 -3
  187. package/dist/server/dashboard/app.css +1 -1
  188. package/dist/server/dashboard/app.js +7 -7
  189. package/dist/server/dashboard-types.d.ts +4 -1
  190. package/dist/server/dashboard-types.d.ts.map +1 -1
  191. package/dist/server/dashboard-types.js.map +1 -1
  192. package/dist/server/dashboard.d.ts.map +1 -1
  193. package/dist/server/dashboard.js +18 -4
  194. package/dist/server/dashboard.js.map +1 -1
  195. package/dist/server/embeddings.d.ts.map +1 -1
  196. package/dist/server/embeddings.js.map +1 -1
  197. package/dist/server/errors.d.ts.map +1 -1
  198. package/dist/server/errors.js.map +1 -1
  199. package/dist/server/findings-service.d.ts.map +1 -1
  200. package/dist/server/findings-service.js.map +1 -1
  201. package/dist/server/serve.js.map +1 -1
  202. package/dist/server/sqlite-store.d.ts.map +1 -1
  203. package/dist/server/sqlite-store.js.map +1 -1
  204. package/dist/severity-store.js.map +1 -1
  205. package/dist/targets.d.ts +2 -1
  206. package/dist/targets.d.ts.map +1 -1
  207. package/dist/targets.js +4 -4
  208. package/dist/targets.js.map +1 -1
  209. package/dist/thread-source.d.ts.map +1 -1
  210. package/dist/version.js.map +1 -1
  211. package/dist/worker-progress.d.ts.map +1 -1
  212. package/dist/worker-progress.js.map +1 -1
  213. package/package.json +31 -28
  214. package/schemas/project-config.schema.json +211 -0
@@ -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
  ```
@@ -3,6 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
+ import json
6
7
  import math
7
8
  import os
8
9
  from pathlib import Path
@@ -13,12 +14,15 @@ try:
13
14
  except ModuleNotFoundError: # pragma: no cover - Python 3.10 only
14
15
  import tomli as tomllib
15
16
 
16
- DEFAULT_WORKERS = 4
17
- DEFAULT_SUBAGENTS = 3
18
- DEFAULT_STOP_AFTER_NO_NEW = 4
19
- DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS = 3
20
- DEFAULT_MAX_DISCOVERY_RUNS = 40
21
- DEFAULT_MAX_TIME_HOURS = 96
17
+ DEFAULTS = json.loads(
18
+ Path(__file__).with_name("deep_scan_defaults.json").read_text(encoding="utf-8")
19
+ )
20
+ DEFAULT_WORKERS = DEFAULTS["workers"]
21
+ DEFAULT_SUBAGENTS = DEFAULTS["subagents"]
22
+ DEFAULT_STOP_AFTER_NO_NEW = DEFAULTS["stopAfterNoNew"]
23
+ DEFAULT_STOP_AFTER_CONSECUTIVE_ERRORS = DEFAULTS["stopAfterConsecutiveErrors"]
24
+ DEFAULT_MAX_DISCOVERY_RUNS = DEFAULTS["maxDiscoveryRuns"]
25
+ DEFAULT_MAX_TIME_HOURS = DEFAULTS["maxTimeHours"]
22
26
  MAX_TIME_HOURS = 96
23
27
  CONFIG_KEYS = {
24
28
  "workers",
@@ -130,8 +134,6 @@ def main() -> None:
130
134
  parser = argparse.ArgumentParser(description=__doc__)
131
135
  parser.add_argument("--available-parallelism", type=int, required=True)
132
136
  args = parser.parse_args()
133
- import json
134
-
135
137
  print(json.dumps(resolve_deep_scan_config(args.available_parallelism), sort_keys=True))
136
138
 
137
139
 
@@ -0,0 +1,8 @@
1
+ {
2
+ "workers": 4,
3
+ "subagents": 3,
4
+ "stopAfterNoNew": 4,
5
+ "stopAfterConsecutiveErrors": 3,
6
+ "maxDiscoveryRuns": 40,
7
+ "maxTimeHours": 96
8
+ }
@@ -2679,6 +2679,8 @@ def _prepare_scan_finalization(
2679
2679
  else _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2680
2680
  )
2681
2681
  scan = _require_dict(manifest, "scan", "manifest")
2682
+ if scan.get("sealedAt") is None and scan.get("artifacts") == []:
2683
+ del scan["artifacts"]
2682
2684
  was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
2683
2685
  if not was_sealed:
2684
2686
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
@@ -86,6 +86,7 @@ def generate_in_scope_files(repository: Path, scope: str, output: Path) -> int:
86
86
  command = [
87
87
  "rg",
88
88
  "--files",
89
+ "--null",
89
90
  "--hidden",
90
91
  "--path-separator",
91
92
  "/",
@@ -138,10 +139,19 @@ def generate_in_scope_files(repository: Path, scope: str, output: Path) -> int:
138
139
  for path in tracked.stdout.split(b"\0"):
139
140
  candidate = repository / os.fsdecode(path)
140
141
  if path and candidate.is_file() and not candidate.is_symlink():
141
- inventory.write(prefix + path + b"\n")
142
+ inventory.write(prefix + path + b"\0")
142
143
 
143
144
  inventory.seek(0)
144
- rows = sorted(inventory)
145
+ rows: list[bytes] = []
146
+ for path in inventory.read().split(b"\0"):
147
+ if not path:
148
+ continue
149
+ if b"\n" in path or b"\r" in path:
150
+ raise InventoryError(
151
+ "Repository contains a path that cannot fit in the file inventory"
152
+ )
153
+ rows.append(path + b"\n")
154
+ rows.sort()
145
155
 
146
156
  return write_inventory(output, rows)
147
157
 
@@ -124,7 +124,6 @@ EXCLUDED_FILENAMES = {
124
124
  SHARD_INPUT_GLOB = "rank-shard-*.input.jsonl"
125
125
  SHARD_OUTPUT_GLOB = "rank-shard-*.output.jsonl"
126
126
  SHARD_INPUT_PATTERN = re.compile(r"^rank-shard-([0-9]{4,})\.input\.jsonl$")
127
- DIRECT_SCOPE_PREVIEW_READ_BYTES = 64 * 1024
128
127
  RANK_POOL_PLAN_SCHEMA_VERSION = 1
129
128
  RANK_POOL_STRATEGY = "round_robin"
130
129
  RANK_POOL_WORKER_CAP = 6
@@ -507,11 +506,7 @@ def make_repo_rank_input(args: argparse.Namespace) -> None:
507
506
  ):
508
507
  preview = ""
509
508
  else:
510
- preview, is_binary = preview_for(
511
- path,
512
- args.preview_bytes,
513
- max_read_bytes=DIRECT_SCOPE_PREVIEW_READ_BYTES if directly_requested else None,
514
- )
509
+ preview, is_binary = preview_for(path, args.preview_bytes)
515
510
  if is_binary and not directly_requested:
516
511
  continue
517
512
  rows_by_path.setdefault(
@@ -9,6 +9,7 @@ import re
9
9
  from pathlib import Path
10
10
 
11
11
  DEFAULT_PREVIEW_BYTES = 1024
12
+ DEFAULT_PREVIEW_READ_BYTES = 64 * 1024
12
13
  PREVIEW_HEAD_LINES = 12
13
14
  PREVIEW_SAMPLE_LINES = 10
14
15
  _UTF16_BOMS = (b"\xff\xfe", b"\xfe\xff")
@@ -56,6 +57,7 @@ TEXT_CODE_EXTENSIONS = {
56
57
  ".sh",
57
58
  ".sql",
58
59
  ".swift",
60
+ ".tf",
59
61
  ".toml",
60
62
  ".ts",
61
63
  ".tsx",
@@ -948,18 +950,17 @@ def structural_outline(path: Path, text: str) -> list[str]:
948
950
 
949
951
 
950
952
  def preview_for(
951
- path: Path, preview_bytes: int, *, max_read_bytes: int | None = None
953
+ path: Path, preview_bytes: int, *, max_read_bytes: int = DEFAULT_PREVIEW_READ_BYTES
952
954
  ) -> tuple[str, bool]:
955
+ """Preview the first 64 KiB by default, including the binary-detection sample."""
956
+ if max_read_bytes <= 0:
957
+ raise ValueError("max_read_bytes must be positive")
953
958
  try:
954
959
  with path.open("rb") as source:
955
- sample = source.read(4096)
960
+ sample = source.read(min(4096, max_read_bytes))
956
961
  if is_binary_sample(sample):
957
962
  return "", True
958
- remaining = (
959
- source.read()
960
- if max_read_bytes is None
961
- else source.read(max(0, max_read_bytes - len(sample)))
962
- )
963
+ remaining = source.read(max_read_bytes - len(sample))
963
964
  data = sample + remaining
964
965
  except OSError:
965
966
  return "", True
@@ -822,7 +822,6 @@ def build_report_markdown(
822
822
  f"- Inventory strategy: {coverage['inventoryStrategy']}",
823
823
  f"- Included paths: {', '.join(include_paths) or 'none'}",
824
824
  f"- Excluded paths: {', '.join(exclude_paths) or 'none'}",
825
- f"- Runtime or test status: {_text(scope.get('runtimeStatus'), 'not recorded')}",
826
825
  ]
827
826
  artifacts_reviewed = _strings(scope.get("artifactsReviewed"))
828
827
  if artifacts_reviewed:
@@ -0,0 +1,6 @@
1
+ [
2
+ "artifacts/01_context/false_positive_feedback.json",
3
+ "artifacts/02_discovery/candidate_ledger.jsonl",
4
+ "artifacts/02_discovery/in_scope_files.txt",
5
+ "artifacts/deep_discovery"
6
+ ]
@@ -465,7 +465,7 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
465
465
  flags=_FILE_FLAG_OPEN_REPARSE_POINT,
466
466
  )
467
467
  assert handle is not None and handle.value is not None
468
- try:
468
+ with handle:
469
469
  _verify_regular_file(handle.value, path)
470
470
  raw_handle = handle.detach()
471
471
  try:
@@ -474,8 +474,6 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
474
474
  except BaseException:
475
475
  _close_handle(raw_handle)
476
476
  raise
477
- finally:
478
- handle.close()
479
477
  except WindowsScanLocalFileError as exc:
480
478
  raise WindowsScanLocalFileError(
481
479
  exc.errno,
@@ -0,0 +1,18 @@
1
+ """Storage paths shared by workbench persistence and MCP artifact selection."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from pathlib import Path
7
+
8
+
9
+ def state_dir() -> Path:
10
+ state_dir = os.environ.get("CODEX_SECURITY_STATE_DIR")
11
+ if state_dir:
12
+ return Path(state_dir).expanduser().resolve()
13
+ codex_home = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
14
+ return (codex_home / "state" / "plugins" / "codex-security").resolve()
15
+
16
+
17
+ def resolve_scan_root(scan_root: str | None) -> Path:
18
+ return Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"
@@ -34,6 +34,9 @@ def parse_args(description: str) -> argparse.Namespace:
34
34
  parser = argparse.ArgumentParser(description=description)
35
35
  subparsers = parser.add_subparsers(dest="command", required=True)
36
36
 
37
+ resolve_scan_root = subparsers.add_parser("resolve-scan-root")
38
+ resolve_scan_root.add_argument("--scan-root")
39
+
37
40
  create_workspace = subparsers.add_parser("create-workspace")
38
41
  create_workspace.add_argument("--workspace-id", required=True)
39
42
  create_workspace.add_argument("--thread-id")
@@ -271,6 +274,16 @@ def parse_args(description: str) -> argparse.Namespace:
271
274
  write_scan_draft.add_argument("--expected-draft-digest")
272
275
  write_scan_draft.add_argument("--claim-token")
273
276
 
277
+ save_scan_artifact = subparsers.add_parser("save-scan-artifact")
278
+ save_scan_artifact.add_argument("--scan-id", required=True)
279
+ save_scan_artifact.add_argument("--artifact-path", required=True)
280
+ save_scan_artifact.add_argument("--claim-token")
281
+
282
+ for command in ("save-artifact", "read-artifact"):
283
+ artifact = subparsers.add_parser(command)
284
+ artifact.add_argument("--artifact-root", required=True)
285
+ artifact.add_argument("--artifact-path", required=True)
286
+
274
287
  mark_handoff_delivered = subparsers.add_parser("mark-handoff-delivered")
275
288
  mark_handoff_delivered.add_argument("--scan-id", required=True)
276
289
  mark_handoff_delivered.add_argument("--claim-token", required=True)
@@ -40,10 +40,24 @@ RECORDS = {
40
40
  "groups": GROUP_RECORDS,
41
41
  }
42
42
 
43
+ SORT_COLUMNS = {
44
+ "activity": "updatedAt",
45
+ "newest": "createdAt",
46
+ "title": "casefold(title)",
47
+ "repository": "casefold(repository_label(repositoryIds))",
48
+ "severity": "CASE severity WHEN 'informational' THEN 0 WHEN 'low' THEN 1 "
49
+ "WHEN 'medium' THEN 2 WHEN 'high' THEN 3 WHEN 'critical' THEN 4 END",
50
+ "members": "memberCount",
51
+ }
52
+
53
+
54
+ def repository_ids(value: str) -> list[str]:
55
+ return sorted(json.loads(value), key=lambda name: (name.casefold(), name))
56
+
43
57
 
44
58
  def item(row: sqlite3.Row) -> dict[str, Any]:
45
59
  result = dict(row)
46
- result["repositoryIds"] = json.loads(result["repositoryIds"])
60
+ result["repositoryIds"] = repository_ids(result["repositoryIds"])
47
61
  return result
48
62
 
49
63
 
@@ -77,10 +91,13 @@ def dashboard(connection: sqlite3.Connection, query: dict[str, Any]) -> dict[str
77
91
  """One snapshot, no artifact reads, model calls, or writes."""
78
92
  view = query["view"]
79
93
  records = RECORDS[view]
94
+ connection.create_function("casefold", 1, str.casefold, deterministic=True)
95
+ connection.create_function(
96
+ "repository_label", 1, lambda value: ", ".join(repository_ids(value)), deterministic=True
97
+ )
80
98
  clauses: list[str] = []
81
99
  values: list[Any] = []
82
100
  if query.get("query"):
83
- connection.create_function("casefold", 1, str.casefold, deterministic=True)
84
101
  columns = ["id", "title", "repositoryIds"]
85
102
  clauses.append(
86
103
  "("
@@ -92,7 +109,11 @@ def dashboard(connection: sqlite3.Connection, query: dict[str, Any]) -> dict[str
92
109
  clauses.append("EXISTS (SELECT 1 FROM json_each(repositoryIds) WHERE value = ?)")
93
110
  values.append(query["repository"])
94
111
  where = " WHERE " + " AND ".join(clauses) if clauses else ""
95
- order = "createdAt DESC, id" if query["sort"] == "newest" else "updatedAt DESC, id"
112
+ direction = {"asc": "ASC", "desc": "DESC"}[query.get("direction", "desc")]
113
+ order = f"{SORT_COLUMNS[query['sort']]} {direction}"
114
+ if view == "findings" and query["sort"] == "activity":
115
+ order += f", {SORT_COLUMNS['severity']} DESC"
116
+ order += ", id"
96
117
  connection.execute("BEGIN")
97
118
  with connection:
98
119
  repositories = connection.execute("""
@@ -60,6 +60,7 @@ from finalize_scan_contract import (
60
60
  )
61
61
  from finding_preview import bounded_finding_details
62
62
  from workbench import handoff
63
+ from workbench.storage import resolve_scan_root, state_dir
63
64
  from workbench_cli import parse_args
64
65
  from workbench_constants import (
65
66
  ARTIFACTS,
@@ -149,7 +150,6 @@ from workbench_validation import (
149
150
  FINDING_ARTIFACT_DIRECTORIES_LIMIT = 80
150
151
  FINDING_ARTIFACTS_LIMIT = 40
151
152
  FINDING_WRITEUP_REPORT_PATH = re.compile(r"^findings/([a-z0-9][a-z0-9._-]*)/\1\.md$")
152
- SCAN_RECIPE_MAX_BYTES = 256 * 1024
153
153
 
154
154
 
155
155
  def now() -> str:
@@ -162,14 +162,6 @@ def stale_claim_before(seconds: int = CLAIM_LEASE_SECONDS) -> str:
162
162
  )
163
163
 
164
164
 
165
- def state_dir() -> Path:
166
- state_dir = os.environ.get("CODEX_SECURITY_STATE_DIR")
167
- if state_dir:
168
- return Path(state_dir).expanduser().resolve()
169
- codex_home = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
170
- return (codex_home / "state" / "plugins" / "codex-security").resolve()
171
-
172
-
173
165
  def database_path() -> Path:
174
166
  return state_dir() / "workbench.sqlite3"
175
167
 
@@ -809,7 +801,7 @@ def save_workspace(connection: sqlite3.Connection, args: argparse.Namespace) ->
809
801
 
810
802
 
811
803
  def scan_target_root(scan_root: str | None, target: Path) -> Path:
812
- root = Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"
804
+ root = resolve_scan_root(scan_root)
813
805
  target_root = (root / safe_segment(target.name)).resolve()
814
806
  if target_root == target or target in target_root.parents:
815
807
  raise SystemExit("The scan artifact directory must be outside the selected target.")
@@ -1820,8 +1812,6 @@ def set_scan_cost_limit(connection: sqlite3.Connection, args: argparse.Namespace
1820
1812
 
1821
1813
 
1822
1814
  def parse_scan_recipe(value: str, repository: Path) -> dict[str, Any]:
1823
- if len(value.encode("utf-8")) > SCAN_RECIPE_MAX_BYTES:
1824
- raise SystemExit("Scan launch recipe must be no larger than 256 KiB.")
1825
1815
  try:
1826
1816
  recipe = json.loads(value, parse_constant=reject_non_finite_json)
1827
1817
  except (TypeError, UnicodeError, ValueError) as exc:
@@ -2496,7 +2486,7 @@ def require_reviewed_patch_applied(
2496
2486
  checkout = checkout_root
2497
2487
  copy_directory_excluding(target, checkout, excluded)
2498
2488
  else:
2499
- checkout = copy_git_worktree_files(target, checkout_root, excluded)
2489
+ copy_git_worktree_files(target, checkout_root, excluded)
2500
2490
  arguments = ["apply", "--reverse", "--whitespace=nowarn"]
2501
2491
  if unversioned:
2502
2492
  arguments.append("--no-index")
@@ -2849,6 +2839,8 @@ def scan_result(
2849
2839
  **scan_usage.stored_scan_cost_fields(scan["cost_json"]),
2850
2840
  "contract": scan_contract(scan),
2851
2841
  "continuationThreadId": scan["continuation_thread_id"],
2842
+ "threadIds": scan_usage._scan_root_thread_ids(connection, scan, None),
2843
+ "executionThreadIds": scan_usage._scan_execution_thread_ids(connection, scan),
2852
2844
  "failureMessage": scan["failure_message"],
2853
2845
  "findings": [
2854
2846
  finding_result(connection, scan, row, related=relations.get(row["id"], []))
@@ -3432,6 +3424,9 @@ def main() -> None:
3432
3424
  preserve_stopped_results=preserve_stopped_results_after_transition,
3433
3425
  )
3434
3426
  )
3427
+ if args.command == "resolve-scan-root":
3428
+ print(json.dumps({"scanRoot": str(resolve_scan_root(args.scan_root))}))
3429
+ return
3435
3430
  if args.command == "inspect-target":
3436
3431
  result = inspect_target(args.target_path)
3437
3432
  print(json.dumps(result, allow_nan=False, sort_keys=True))
@@ -3440,6 +3435,9 @@ def main() -> None:
3440
3435
  result = inspect_setup(args)
3441
3436
  print(json.dumps(result, allow_nan=False, sort_keys=True))
3442
3437
  return
3438
+ if args.command in {"save-artifact", "read-artifact"}:
3439
+ print(json.dumps(saved_results.read_or_save_artifact(args)))
3440
+ return
3443
3441
  if args.command == "read-severity-classification":
3444
3442
  result = severity.read_classification(database_path(), args.scan_id)
3445
3443
  print(json.dumps(result, allow_nan=False, sort_keys=True))
@@ -3567,6 +3565,8 @@ def main() -> None:
3567
3565
  result = recover_scan_results(connection, args)
3568
3566
  elif args.command == "write-scan-draft":
3569
3567
  result = write_scan_draft(connection, args)
3568
+ elif args.command == "save-scan-artifact":
3569
+ result = saved_results.save_scan_artifact(_WORKBENCH_DB_CONTEXT, connection, args)
3570
3570
  elif args.command == "mark-handoff-delivered":
3571
3571
  result = handoff.mark_handoff_delivered(
3572
3572
  connection,