@openai/codex-security 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (244) hide show
  1. package/README.md +45 -9
  2. package/_bundled_plugin/.codex-plugin/plugin.json +5 -5
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  6. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  7. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +13 -20
  8. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  9. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  10. package/_bundled_plugin/references/core-scan.md +2 -0
  11. package/_bundled_plugin/references/final-report.md +5 -1
  12. package/_bundled_plugin/references/investigation-time-budget.md +11 -0
  13. package/_bundled_plugin/references/sarif-adapter.md +1 -0
  14. package/_bundled_plugin/references/scan-prologue.md +2 -6
  15. package/_bundled_plugin/references/scan-runtime.md +15 -0
  16. package/_bundled_plugin/references/threat-model.md +2 -0
  17. package/_bundled_plugin/schemas/coverage.schema.json +45 -126
  18. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +5 -1
  19. package/_bundled_plugin/schemas/findings.schema.json +140 -427
  20. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +106 -119
  21. package/_bundled_plugin/schemas/scan-manifest.schema.json +73 -188
  22. package/_bundled_plugin/scripts/deep_scan_workbench.py +7 -0
  23. package/_bundled_plugin/scripts/finalize_scan_contract.py +87 -49
  24. package/_bundled_plugin/scripts/finding_preview.py +5 -3
  25. package/_bundled_plugin/scripts/generate_rank_input.py +26 -106
  26. package/_bundled_plugin/scripts/launch_codex_security_mcp +39 -4
  27. package/_bundled_plugin/scripts/report_projection.py +35 -13
  28. package/_bundled_plugin/scripts/snapshot_sqlite.py +7 -0
  29. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -1
  30. package/_bundled_plugin/scripts/workbench_cli.py +9 -9
  31. package/_bundled_plugin/scripts/workbench_constants.py +4 -0
  32. package/_bundled_plugin/scripts/workbench_db.py +103 -45
  33. package/_bundled_plugin/scripts/workbench_progress.py +0 -50
  34. package/_bundled_plugin/scripts/workbench_publication.py +216 -247
  35. package/_bundled_plugin/scripts/workbench_scan_history.py +3 -2
  36. package/_bundled_plugin/scripts/workbench_scan_start.py +12 -4
  37. package/_bundled_plugin/scripts/workbench_scan_usage.py +360 -37
  38. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  39. package/_bundled_plugin/scripts/workbench_source_excerpt.py +74 -51
  40. package/_bundled_plugin/scripts/workbench_source_scopes.py +388 -0
  41. package/_bundled_plugin/scripts/workbench_target.py +7 -5
  42. package/_bundled_plugin/scripts/workbench_validation.py +52 -2
  43. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -0
  44. package/_bundled_plugin/shared/workbench-migrations.json +22 -0
  45. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +1 -1
  46. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  47. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +4 -2
  48. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  49. package/_bundled_plugin/skills/security-scan/SKILL.md +4 -2
  50. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  51. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -3
  52. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +2 -0
  53. package/_bundled_plugin/skills/track-findings/SKILL.md +8 -4
  54. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  55. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +1 -1
  56. package/dist/api.d.ts +6 -2
  57. package/dist/api.d.ts.map +1 -1
  58. package/dist/api.js +266 -39
  59. package/dist/api.js.map +1 -1
  60. package/dist/artifact-export.d.ts +2 -1
  61. package/dist/artifact-export.d.ts.map +1 -1
  62. package/dist/artifact-export.js +38 -23
  63. package/dist/artifact-export.js.map +1 -1
  64. package/dist/classify-severity-records.d.ts +76 -0
  65. package/dist/classify-severity-records.d.ts.map +1 -0
  66. package/dist/classify-severity-records.js +141 -0
  67. package/dist/classify-severity-records.js.map +1 -0
  68. package/dist/classify-severity.d.ts +1 -23
  69. package/dist/classify-severity.d.ts.map +1 -1
  70. package/dist/classify-severity.js +3 -24
  71. package/dist/classify-severity.js.map +1 -1
  72. package/dist/cli-help.d.ts.map +1 -1
  73. package/dist/cli-help.js +2 -0
  74. package/dist/cli-help.js.map +1 -1
  75. package/dist/cli.d.ts +4 -2
  76. package/dist/cli.d.ts.map +1 -1
  77. package/dist/cli.js +148 -149
  78. package/dist/cli.js.map +1 -1
  79. package/dist/cloud-publish.js +1 -1
  80. package/dist/cloud-publish.js.map +1 -1
  81. package/dist/codex-sdk-environment.js +1 -1
  82. package/dist/codex-sdk-environment.js.map +1 -1
  83. package/dist/component-plan.js +1 -1
  84. package/dist/component-plan.js.map +1 -1
  85. package/dist/component-scan.d.ts.map +1 -1
  86. package/dist/component-scan.js +5 -4
  87. package/dist/component-scan.js.map +1 -1
  88. package/dist/config.d.ts +12 -0
  89. package/dist/config.d.ts.map +1 -1
  90. package/dist/config.js +10 -4
  91. package/dist/config.js.map +1 -1
  92. package/dist/contract.d.ts +6 -0
  93. package/dist/contract.d.ts.map +1 -1
  94. package/dist/contract.js +69 -20
  95. package/dist/contract.js.map +1 -1
  96. package/dist/cost-model.d.ts.map +1 -1
  97. package/dist/cost-model.js +7 -2
  98. package/dist/cost-model.js.map +1 -1
  99. package/dist/custom-validation-prompt.js +3 -3
  100. package/dist/custom-validation-prompt.js.map +1 -1
  101. package/dist/deduplication/codex-review.d.ts +1 -5
  102. package/dist/deduplication/codex-review.d.ts.map +1 -1
  103. package/dist/deduplication/codex-review.js +2 -2
  104. package/dist/deduplication/codex-review.js.map +1 -1
  105. package/dist/deduplication/deduplication-prompts.d.ts +1 -1
  106. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  107. package/dist/deduplication/deduplication-prompts.js +2 -2
  108. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  109. package/dist/deduplication/deduplication-reviewer.d.ts +1 -1
  110. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  111. package/dist/deduplication/deduplication-reviewer.js +1 -1
  112. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  113. package/dist/deduplication/records-protocol.d.ts +3 -8
  114. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  115. package/dist/deduplication/records-protocol.js +11 -171
  116. package/dist/deduplication/records-protocol.js.map +1 -1
  117. package/dist/deduplication/records.js +1 -1
  118. package/dist/deduplication/records.js.map +1 -1
  119. package/dist/deduplication/scan.d.ts.map +1 -1
  120. package/dist/deduplication/scan.js +10 -9
  121. package/dist/deduplication/scan.js.map +1 -1
  122. package/dist/deep-config.d.ts +4 -1
  123. package/dist/deep-config.d.ts.map +1 -1
  124. package/dist/deep-config.js +21 -1
  125. package/dist/deep-config.js.map +1 -1
  126. package/dist/deep-progress.d.ts +15 -1
  127. package/dist/deep-progress.d.ts.map +1 -1
  128. package/dist/deep-progress.js +15 -16
  129. package/dist/deep-progress.js.map +1 -1
  130. package/dist/executable-path.d.ts +2 -0
  131. package/dist/executable-path.d.ts.map +1 -0
  132. package/dist/executable-path.js +12 -0
  133. package/dist/executable-path.js.map +1 -0
  134. package/dist/feedback.d.ts +1 -4
  135. package/dist/feedback.d.ts.map +1 -1
  136. package/dist/feedback.js +1 -1
  137. package/dist/feedback.js.map +1 -1
  138. package/dist/findings-import.d.ts +1 -1
  139. package/dist/findings-import.d.ts.map +1 -1
  140. package/dist/findings-import.js +3 -3
  141. package/dist/findings-import.js.map +1 -1
  142. package/dist/git-remote.d.ts +10 -0
  143. package/dist/git-remote.d.ts.map +1 -0
  144. package/dist/git-remote.js +24 -0
  145. package/dist/git-remote.js.map +1 -0
  146. package/dist/github.d.ts.map +1 -1
  147. package/dist/github.js +5 -7
  148. package/dist/github.js.map +1 -1
  149. package/dist/host-protocol.d.ts +19 -0
  150. package/dist/host-protocol.d.ts.map +1 -0
  151. package/dist/host-protocol.js +270 -0
  152. package/dist/host-protocol.js.map +1 -0
  153. package/dist/host-records-protocol.d.ts +15 -0
  154. package/dist/host-records-protocol.d.ts.map +1 -0
  155. package/dist/host-records-protocol.js +15 -0
  156. package/dist/host-records-protocol.js.map +1 -0
  157. package/dist/hosted-scan-protocol.d.ts +4 -0
  158. package/dist/hosted-scan-protocol.d.ts.map +1 -0
  159. package/dist/hosted-scan-protocol.js +25 -0
  160. package/dist/hosted-scan-protocol.js.map +1 -0
  161. package/dist/hosted-scan.d.ts +112 -0
  162. package/dist/hosted-scan.d.ts.map +1 -0
  163. package/dist/hosted-scan.js +260 -0
  164. package/dist/hosted-scan.js.map +1 -0
  165. package/dist/index.d.ts +7 -0
  166. package/dist/index.d.ts.map +1 -1
  167. package/dist/index.js +3 -0
  168. package/dist/index.js.map +1 -1
  169. package/dist/knowledge-base.d.ts.map +1 -1
  170. package/dist/knowledge-base.js +87 -7
  171. package/dist/knowledge-base.js.map +1 -1
  172. package/dist/multiscan.d.ts.map +1 -1
  173. package/dist/multiscan.js +108 -36
  174. package/dist/multiscan.js.map +1 -1
  175. package/dist/patch-publication.d.ts +26 -0
  176. package/dist/patch-publication.d.ts.map +1 -0
  177. package/dist/patch-publication.js +105 -0
  178. package/dist/patch-publication.js.map +1 -0
  179. package/dist/patch-tui.d.ts.map +1 -1
  180. package/dist/patch-tui.js +4 -1
  181. package/dist/patch-tui.js.map +1 -1
  182. package/dist/project-config-schema.d.ts +2 -0
  183. package/dist/project-config-schema.d.ts.map +1 -1
  184. package/dist/project-config-schema.js +1 -0
  185. package/dist/project-config-schema.js.map +1 -1
  186. package/dist/project-config.d.ts +1 -0
  187. package/dist/project-config.d.ts.map +1 -1
  188. package/dist/project-config.js +16 -6
  189. package/dist/project-config.js.map +1 -1
  190. package/dist/publication-store.d.ts.map +1 -1
  191. package/dist/publication-store.js +73 -63
  192. package/dist/publication-store.js.map +1 -1
  193. package/dist/publication.d.ts +0 -2
  194. package/dist/publication.d.ts.map +1 -1
  195. package/dist/publication.js +135 -24
  196. package/dist/publication.js.map +1 -1
  197. package/dist/publish.d.ts.map +1 -1
  198. package/dist/publish.js +39 -25
  199. package/dist/publish.js.map +1 -1
  200. package/dist/runtime.d.ts +5 -2
  201. package/dist/runtime.d.ts.map +1 -1
  202. package/dist/runtime.js +86 -58
  203. package/dist/runtime.js.map +1 -1
  204. package/dist/scan-executor.d.ts +104 -0
  205. package/dist/scan-executor.d.ts.map +1 -0
  206. package/dist/scan-executor.js +62 -0
  207. package/dist/scan-executor.js.map +1 -0
  208. package/dist/scan-settings.d.ts +1 -0
  209. package/dist/scan-settings.d.ts.map +1 -1
  210. package/dist/scan-settings.js +7 -1
  211. package/dist/scan-settings.js.map +1 -1
  212. package/dist/scan-time-budget.d.ts +9 -0
  213. package/dist/scan-time-budget.d.ts.map +1 -0
  214. package/dist/scan-time-budget.js +16 -0
  215. package/dist/scan-time-budget.js.map +1 -0
  216. package/dist/severity-review.d.ts +29 -0
  217. package/dist/severity-review.d.ts.map +1 -0
  218. package/dist/severity-review.js +47 -0
  219. package/dist/severity-review.js.map +1 -0
  220. package/dist/targets.d.ts.map +1 -1
  221. package/dist/targets.js +17 -25
  222. package/dist/targets.js.map +1 -1
  223. package/dist/validation-records.d.ts +38 -0
  224. package/dist/validation-records.d.ts.map +1 -0
  225. package/dist/validation-records.js +76 -0
  226. package/dist/validation-records.js.map +1 -0
  227. package/dist/version.d.ts.map +1 -1
  228. package/dist/version.js +4 -2
  229. package/dist/version.js.map +1 -1
  230. package/dist/worker-progress.d.ts +43 -15
  231. package/dist/worker-progress.d.ts.map +1 -1
  232. package/dist/worker-progress.js +22 -80
  233. package/dist/worker-progress.js.map +1 -1
  234. package/docs/classify-severity-records.md +89 -0
  235. package/docs/cli.md +281 -35
  236. package/docs/hosted-scans.md +242 -0
  237. package/docs/validate-records.md +69 -0
  238. package/package.json +18 -14
  239. package/schemas/hosted-scan-v2.fixture.json +145 -0
  240. package/schemas/project-config.schema.json +7 -1
  241. package/_bundled_plugin/preflight/capability-profiles.toml +0 -76
  242. package/_bundled_plugin/references/config-preflight.md +0 -93
  243. package/_bundled_plugin/references/desktop-config-preflight.md +0 -11
  244. package/_bundled_plugin/scripts/config_preflight.py +0 -911
@@ -0,0 +1,242 @@
1
+ # Hosted Standard scans (protocol v2)
2
+
3
+ `codex-security scan --host` runs one scan using newline-delimited JSON-RPC on
4
+ stdin/stdout. Use the flag alone. It performs no login, update check, local
5
+ inference, or model fallback. Ordinary local scans keep their existing behavior.
6
+
7
+ ## Public executor API
8
+
9
+ Use the standalone `runHostedScan(input, { executor, signal, onEvent })`
10
+ function to run one hosted Standard scan. `CodexSecurity.run()` retains its local
11
+ scan behavior; it does not accept a hosted executor. The CLI command is a thin
12
+ JSON-RPC adapter around the same standalone function.
13
+
14
+ The CLI owns scan registration, plugin lifecycle, target checks, finalization,
15
+ report generation and sealed artifact validation. The host owns authorization,
16
+ frozen checkout, execution, durable run state, replay, reconciliation, usage,
17
+ billing and cleanup. It collects authoritative usage before cleanup and persists
18
+ accepted output independently from inference. Findings ingestion and
19
+ deduplication consume that accepted output separately. CLI workbench state
20
+ remains scan-domain state; there is no hosted-attempt replay store.
21
+
22
+ ```ts
23
+ import { runHostedScan, type ScanExecutor } from "@openai/codex-security";
24
+
25
+ const executor: ScanExecutor = {
26
+ async run(request, { signal, onEvent }) {
27
+ // Persist the request identity before dispatch. Mount the matching plugin,
28
+ // checkout, scan state and output directory in the remote executor.
29
+ return await host.executeOnce(request, { signal, onEvent });
30
+ },
31
+ };
32
+ const result = await runHostedScan(
33
+ {
34
+ version: 2,
35
+ repository: "/workspace/repository",
36
+ revision: "0123456789012345678901234567890123456789",
37
+ scope: { paths: ["services/api", "services/web"] },
38
+ outputDirectory: "/scan/output",
39
+ stateDirectory: "/scan/state",
40
+ model: "gpt-5.6-sol",
41
+ reasoningEffort: "high",
42
+ identity: {
43
+ runId: "run-1",
44
+ attemptId: "attempt-1",
45
+ buildId: "runtime-build",
46
+ },
47
+ },
48
+ {
49
+ executor,
50
+ onEvent(event) {
51
+ console.error(event);
52
+ },
53
+ },
54
+ );
55
+
56
+ // These host methods are application code, outside the CLI.
57
+ await host.persistReceipt(result);
58
+ if (result.status === "completed") {
59
+ // Check the frozen identity/scope and artifact paths, hashes, sizes and seals.
60
+ await host.verifyAndAcceptArtifacts(result);
61
+ } else if (result.status === "acceptance_unknown") {
62
+ // Look up the existing attempt/session; do not call runHostedScan again.
63
+ await host.reconcileExecution(result.identity, result.execution);
64
+ }
65
+ // Failed and canceled receipts remain recorded but are not accepted
66
+ // completed scans. Persistence retries reuse this receipt without more inference.
67
+ ```
68
+
69
+ The function creates and closes its scan client internally, reusing the ordinary
70
+ Standard scan lifecycle. Omit `scope` for the entire repository, or pass literal
71
+ repository-relative folders/files. Model settings come from the frozen input;
72
+ local profiles and other local scan options are not accepted.
73
+
74
+ `ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
75
+ `{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
76
+ uses the existing `ScanProgress` type; activity uses `ScanActivity`. Observer
77
+ failures cannot stop execution. Aborting waits for the executor to settle; the
78
+ host must cancel remote work and return its recorded outcome.
79
+
80
+ Preparation errors throw before execution. Execution and finalization return a
81
+ `HostedScanResult` receipt with status `completed`, `failed`,
82
+ `canceled`, or `acceptance_unknown`. The receipt retains the executor's outcome, session
83
+ identity, usage, message and structured error even if artifact finalization
84
+ fails. Only validated artifacts receive hashes and sizes. Repeated invocations
85
+ are separate scans; the host decides whether a new invocation is allowed.
86
+
87
+ Temporary runtime cleanup failures preserve the terminal receipt, including
88
+ its execution outcome, session identity, usage, and validated artifacts. They
89
+ are reported separately through `onEvent` as a failed message activity with
90
+ ID `runtime.cleanup` (a `scan.progress` notification over JSON-RPC). A cleanup
91
+ failure does not change the scan status or require another execution attempt.
92
+
93
+ ## Wire contract
94
+
95
+ Send `{"jsonrpc":"2.0","id":"run","method":"run","params":...}` with the
96
+ parameters below. IDs are strings or safe integers from -9007199254740991 through
97
+ 9007199254740991; send larger numeric identifiers as strings.
98
+
99
+ ```json
100
+ {
101
+ "version": 2,
102
+ "repository": "/workspace/repository",
103
+ "revision": "0123456789012345678901234567890123456789",
104
+ "scope": { "paths": ["services/api", "services/web"] },
105
+ "outputDirectory": "/scan/output",
106
+ "stateDirectory": "/scan/state",
107
+ "model": "gpt-5.6-sol",
108
+ "reasoningEffort": "high",
109
+ "identity": {
110
+ "runId": "example-run",
111
+ "attemptId": "example-attempt",
112
+ "buildId": "exact-runtime-build"
113
+ }
114
+ }
115
+ ```
116
+
117
+ Omit `scope` to scan the entire repository, matching the local CLI default.
118
+ `{"paths":["."]}` also means the repository. An explicit empty list is invalid;
119
+ root cannot be mixed with narrower paths. Each entry is one literal filename or
120
+ directory: `app/[slug]/page.tsx` and `reports/a,b.ts` are not patterns or lists.
121
+ Significant whitespace is preserved; `" service "` and `" "` do not select
122
+ `"service"` or the repository. An explicit empty string is invalid. Paths use the
123
+ ordinary CLI target resolver's filename semantics, with repository-relative
124
+ paths required here. They are normalized, deduplicated and sorted without
125
+ changing filename characters. Preparation also checks the existing output
126
+ contract: scope paths must be valid UTF-8 and cannot contain control characters,
127
+ backslashes, or start with a drive prefix such as `C:`. Incompatible filenames
128
+ fail before executor dispatch, including on POSIX where those files may exist.
129
+ Every selected path must exist and remain inside
130
+ the repository at the frozen revision before any execution request. Missing paths fail the whole
131
+ request; the CLI never skips them or broadens the scope. Canonical path aliases
132
+ are rejected with an actionable correction. Diff, Deep, resume, mock, local
133
+ workflow and post-scan execution are unsupported in this hosted Standard API.
134
+
135
+ The CLI verifies HEAD before path existence, registers the scan with its bundled
136
+ workbench, and sends one `execution.run` request. Its JSON-RPC ID equals the
137
+ required `params.requestId`. Params contain `version: 2`, normalized
138
+ `repository`, `revision`, `scope`, `identity`, registered `scanId`, `prompt`,
139
+ `model`, `reasoningEffort`, and `runtime`:
140
+
141
+ - `pluginRoot` and `pluginVersion`: the matching bundled plugin.
142
+ - `stateDirectory` and `outputDirectory`: writable paths outside the repository.
143
+ - `environment`: explicit runtime paths and interpreter settings, never host
144
+ inference credentials.
145
+
146
+ The CLI and executor must share these filesystem paths or explicitly transfer
147
+ the same state. This includes:
148
+
149
+ - The frozen checkout and matching `pluginRoot` tree, including its executable
150
+ helpers, skills, and MCP server.
151
+ - The whole `stateDirectory`, including the registered workbench database,
152
+ journals, and scan inputs; a live database file alone is not a consistent copy.
153
+ - `outputDirectory`, where the executor records its draft and the CLI later
154
+ writes the validated manifest, findings, coverage, and report.
155
+ - The temporary files named by `CODEX_SECURITY_CONFIG_PATH` and, for path scans,
156
+ `CODEX_SECURITY_TARGET_PATHS_FILE` in `runtime.environment`. These are required
157
+ by preflight and scope binding, even though they can live outside the state
158
+ and output directories. The supplied interpreter paths must also resolve.
159
+
160
+ Keep these paths available throughout the invocation. The CLI removes its
161
+ temporary config/scope files when the invocation closes; caller-owned state
162
+ and output directories remain available. If remote work may outlive an
163
+ `acceptance_unknown` return, the host must preserve the files that work still
164
+ needs before returning that outcome. Use shared mounts or a coordinated transfer
165
+ that preserves the supplied path bindings, not independent copies of mutable
166
+ workbench state.
167
+
168
+ Run the plugin stdio server from
169
+ `pluginRoot/scripts/launch_codex_security_mcp --stdio` with the supplied
170
+ environment. The executor needs the target files, plugin skills and registered
171
+ artifacts, and must expose `record_codex_security_scan_draft`. CLI workbench
172
+ finalization follows the turn. Merely returning model text is insufficient.
173
+ Separately provisioned executors must receive the exact frozen runtime/plugin
174
+ build and preserve state; do not interpret plugin schemas as strict Structured
175
+ Outputs schemas.
176
+
177
+ The execution response `result` has:
178
+
179
+ - Required `requestId` matching the execution request, and `status`:
180
+ `completed`, `failed`, `canceled`, or `acceptance_unknown`.
181
+ - `sessionId`, required for completed execution and optional for other outcomes.
182
+ - Optional `finalResponse`, `message`, and structured `error` with numeric `code`,
183
+ string `message` and optional `data`.
184
+ - Optional opaque host `usage`. Absence means unknown, never zero. The host collects
185
+ it for diagnostics; these observations do not replace authoritative accounting.
186
+
187
+ A transport failure or mismatched receipt is not proof of non-acceptance. The
188
+ CLI stops without resubmitting and leaves reconciliation to the host. The terminal
189
+ result retains `execution` even when scanning fails or is canceled. The runtime's
190
+ `hostProtocolVersion` identifies this protocol as version 2.
191
+ A package-exported example is available at
192
+ `@openai/codex-security/schemas/hosted-scan-v2.fixture.json`. Its `response` is
193
+ the executor's reply; `terminal` is the separate final scan receipt. The example
194
+ hashes and sizes are illustrative and do not validate any real files.
195
+
196
+ | Final scan status | Host handling |
197
+ | ---------------------- | ------------------------------------------------------------------------------------------------ |
198
+ | `completed` | Verify artifact receipts and seals before accepting output. |
199
+ | `failed` or `canceled` | Retain identity, diagnostics and any execution/usage receipt. |
200
+ | `acceptance_unknown` | Reconcile the existing remote attempt and collect usage before cleanup; do not resubmit blindly. |
201
+
202
+ Reconciliation uses the host's durable attempt/session identifiers and provider
203
+ status. Preserve state and output for inspection, and cancel or join remote work
204
+ before releasing resources it still uses. The hosted API has no replay store,
205
+ resume, or finalize-only operation: calling `runHostedScan` again registers a new
206
+ scan. A provider reporting execution completion does not substitute for a
207
+ validated, sealed scan receipt.
208
+
209
+ ## Progress, cancellation and artifacts
210
+
211
+ The host sends `execution.progress` notifications with `{requestId, event}`.
212
+ The CLI forwards valid progress/activity through `scan.progress` notifications
213
+ with `{id: <original run RPC id>, event}`. Invalid optional event payloads are
214
+ ignored; mismatched request IDs are rejected. Stdout contains JSON-RPC only.
215
+
216
+ Send `{"jsonrpc":"2.0","method":"cancel","params":{"id":"run"}}` with the
217
+ original run request ID. The CLI aborts its executor signal, emits
218
+ `execution.cancel` with `{requestId}`, and waits for the host's outcome/usage
219
+ before returning a canceled result. The host must continue reading notifications
220
+ while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with
221
+ blocked output terminate the transport even while a write callback is stuck.
222
+ Input EOF before the terminal response fails the run; EOF while that response is
223
+ flushing waits for the write callback. A selected successful result is not a
224
+ successful delivery. Hosts own deadlines and independently cancel remote work
225
+ and reconcile known execution identities after transport failure.
226
+
227
+ Preparation failures include typed `error.data.reason` for missing, escaping,
228
+ aliased or syntactically invalid paths and revision mismatch. Other failures
229
+ must not be presented as missing paths.
230
+
231
+ The terminal run result includes `version: 2`, `status`, frozen
232
+ identity/revision/normalized scope, output directory, scan ID when registered,
233
+ plugin version when known, `provenance` (CLI/plugin/build identity), optional `execution`,
234
+ and `artifacts`. Each artifact is `{path, sha256, bytes}` over its exact bytes.
235
+ Receipts cover canonical outputs, sealed supplemental files, and preserved
236
+ source files bound by the manifest. Coverage limitations remain diagnostics in
237
+ completed scans; required-output failures return `failed`, and unvalidated files
238
+ never receive artifact receipts. `acceptance_unknown`, failed
239
+ and canceled results are not accepted completed scans.
240
+
241
+ The host verifies receipt paths, hashes, sizes, scope, revision and seals before
242
+ accepting output.
@@ -0,0 +1,69 @@
1
+ # Host-provided standalone validation (protocol v1)
2
+
3
+ Run `codex-security validate --records` with that flag alone. It uses the
4
+ standalone validation instructions to assess existing findings against source
5
+ evidence. The host runs the model; the CLI does not start Codex, authenticate,
6
+ read scan history, or save results. Existing `validate` commands are unchanged.
7
+
8
+ Use the same JSON-RPC transport as [records deduplication](dedupe-records.md):
9
+ one JSON object per line, one `run` request, and `review.run` requests answered
10
+ by the host. Keep stdin open until the final response. Cancellation, disconnects,
11
+ and host errors terminate the invocation without retrying the review.
12
+
13
+ The `run` request's `params` has this shape:
14
+
15
+ ```json
16
+ {
17
+ "version": 1,
18
+ "findings": [
19
+ {
20
+ "id": "finding-1",
21
+ "finding": { "title": "Example candidate", "evidence": "..." }
22
+ }
23
+ ],
24
+ "context": "Optional deployment facts or reviewer feedback.",
25
+ "knowledgeBasePath": "/validation/context",
26
+ "outputSchema": {
27
+ "type": "object",
28
+ "properties": { "rationale": { "type": "string" } },
29
+ "required": ["rationale"],
30
+ "additionalProperties": false
31
+ }
32
+ }
33
+ ```
34
+
35
+ Provide at least one finding with a unique, nonempty host ID. The `finding`
36
+ value preserves the caller's candidate format. Supply enough source locations
37
+ and evidence to assess it. `context` and `knowledgeBasePath` are optional.
38
+ The directory must already exist in the host's review environment; this mode
39
+ does not copy files. Context and notes are evidence to check against source,
40
+ not instructions or automatic dismissal rules.
41
+
42
+ `outputSchema` is required. It controls the returned structured answer; it does
43
+ not define a standard disposition or product status model. The host must verify
44
+ finding ID coverage and any application-specific conditions before changing
45
+ published findings. Optional `model` and `effort` override the SDK's default
46
+ model configuration. Local configuration files and CLI model flags are not read.
47
+
48
+ The CLI emits one `review.run` request containing `requestId`, `model`, `effort`,
49
+ `trustedInstructions`, `prompt`, and `schema`. The host supplies the authorized
50
+ source checkout and context directory, executes the review, and returns its
51
+ structured answer. The CLI checks that answer against `outputSchema` before
52
+ returning `{ "status": "completed", "result": <assessment> }` as the final
53
+ JSON-RPC `result`. Success exits with code 0; invalid input, invalid output, or
54
+ execution failure exits with code 2. SIGINT and SIGTERM
55
+ retain exit codes 130 and 143.
56
+
57
+ The host owns repository authorization, credentials, model accounting,
58
+ cancellation of remote work, and cleanup. It selects and enforces the review
59
+ environment's isolation and permissions.
60
+ The review instructions require source-only assessment: no builds, tests, PoCs,
61
+ target execution, or network investigation. This mode does not configure a local
62
+ Codex sandbox; regular `validate` retains its existing read-only sandbox. A
63
+ protocol success only proves that the answer matched the schema; it does not
64
+ establish assessment quality.
65
+
66
+ The SDK equivalent is `validateRecords(input, { reviewRunner, signal })`, exported
67
+ from `@openai/codex-security`. The runner's `run(request, { signal })` method returns
68
+ the structured answer. `ValidateRecordsInput`, `ValidateRecordsOptions`, and
69
+ `ValidationReviewRequest` are exported types.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openai/codex-security",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "TypeScript SDK and CLI for Codex Security",
5
5
  "license": "Apache-2.0",
6
6
  "author": "OpenAI",
@@ -28,7 +28,8 @@
28
28
  "import": "./dist/index.js",
29
29
  "default": "./dist/index.js"
30
30
  },
31
- "./schemas/project-config.schema.json": "./schemas/project-config.schema.json"
31
+ "./schemas/project-config.schema.json": "./schemas/project-config.schema.json",
32
+ "./schemas/hosted-scan-v2.fixture.json": "./schemas/hosted-scan-v2.fixture.json"
32
33
  },
33
34
  "bin": {
34
35
  "codex-security": "./bin/codex-security.mjs",
@@ -43,7 +44,10 @@
43
44
  "README.md",
44
45
  "docs/cli.md",
45
46
  "docs/findings-service.md",
46
- "docs/dedupe-records.md"
47
+ "docs/dedupe-records.md",
48
+ "docs/classify-severity-records.md",
49
+ "docs/hosted-scans.md",
50
+ "docs/validate-records.md"
47
51
  ],
48
52
  "publishConfig": {
49
53
  "access": "public",
@@ -53,10 +57,10 @@
53
57
  },
54
58
  "dependencies": {
55
59
  "@inquirer/prompts": "8.7.3",
56
- "@linear/sdk": "97.0.0",
60
+ "@linear/sdk": "97.1.0",
57
61
  "@octokit/core": "7.0.8",
58
- "@openai/codex": "0.162.1",
59
- "@openai/codex-sdk": "0.162.1",
62
+ "@openai/codex": "0.163.0",
63
+ "@openai/codex-sdk": "0.163.0",
60
64
  "ajv": "8.20.0",
61
65
  "fflate": "0.8.3",
62
66
  "incur": "0.7.0",
@@ -65,18 +69,19 @@
65
69
  "papaparse": "5.7.0",
66
70
  "pdfjs-dist": "6.4.299",
67
71
  "react": "19.3.0",
72
+ "saxes": "6.0.0",
68
73
  "semver": "7.8.5",
69
- "smol-toml": "1.9.0",
74
+ "smol-toml": "1.9.1",
70
75
  "string-width": "8.3.0",
71
76
  "strip-ansi": "7.2.0",
72
77
  "yaml": "2.9.1",
73
78
  "yauzl": "3.4.0",
74
- "zod": "4.6.5"
79
+ "zod": "4.6.6"
75
80
  },
76
81
  "devDependencies": {
77
82
  "@stryker-mutator/core": "10.0.0",
78
- "@types/bun": "1.4.2",
79
- "@types/node": "26.6.4",
83
+ "@types/bun": "1.4.3",
84
+ "@types/node": "26.6.5",
80
85
  "@types/papaparse": "5.5.2",
81
86
  "@types/react": "19.3.0",
82
87
  "@types/semver": "7.8.0",
@@ -87,11 +92,10 @@
87
92
  "json-schema-to-typescript": "16.0.0",
88
93
  "json5": "2.2.3",
89
94
  "minimatch": "10.2.6",
90
- "prettier": "3.9.9",
91
- "saxes": "6.0.0",
95
+ "prettier": "3.9.10",
92
96
  "typescript": "7.0.2"
93
97
  },
94
- "gitHead": "5c5239dd8062a7d00916c4bc0d5aeaa3ed0c5477",
98
+ "gitHead": "03414ad84e91a8638bde85af08c47fe957dc9323",
95
99
  "scripts": {
96
100
  "audit:prod": "pnpm audit --prod --audit-level high",
97
101
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -102,7 +106,7 @@
102
106
  "build:plugin": "node scripts/build-plugin.mjs",
103
107
  "check:plugin-source": "node scripts/check-plugin-source.mjs",
104
108
  "check:package": "node scripts/check-package.mjs",
105
- "format": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore \"**/*.{cjs,mjs,js,ts,mts,tsx,json}\" \"../../.github/scripts/*.mts\" \"../../examples/custom-validation/*.mts\" \"../../plugins/codex-security/native/*.mts\" \"../../evals/{deep-reducer,secret-discovery}/*.mts\" \"../../evals/triage-finding/{assertions,scripts,sastbench/assertions,sastbench/scripts}/*.mts\" \"../../evals/triage-finding/types.ts\" \"../../evals/tsconfig.json\" && node scripts/check-markdown.mjs",
109
+ "format": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore \"**/*.{cjs,mjs,js,ts,mts,tsx,json}\" \"../../.github/scripts/*.mts\" \"../../examples/custom-validation/*.mts\" \"../../plugins/codex-security/native/*.mts\" \"../../evals/{deep-reducer,secret-discovery,workflow-routing}/*.mts\" \"../../evals/triage-finding/{assertions,scripts,sastbench/assertions,sastbench/scripts}/*.mts\" \"../../evals/triage-finding/types.ts\" \"../../evals/tsconfig.json\" && node scripts/check-markdown.mjs",
106
110
  "generate:models": "node scripts/generate-models.cjs",
107
111
  "generate:models:check": "node scripts/generate-models.cjs --check",
108
112
  "lint": "tsc --noEmit",
@@ -0,0 +1,145 @@
1
+ {
2
+ "run": {
3
+ "jsonrpc": "2.0",
4
+ "id": "run",
5
+ "method": "run",
6
+ "params": {
7
+ "version": 2,
8
+ "repository": "/workspace/repository",
9
+ "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
10
+ "scope": {
11
+ "paths": ["service-a", "service-b"]
12
+ },
13
+ "outputDirectory": "/scan/output",
14
+ "stateDirectory": "/scan/state",
15
+ "model": "fixture-model",
16
+ "reasoningEffort": "medium",
17
+ "identity": {
18
+ "runId": "run-1",
19
+ "attemptId": "attempt-1",
20
+ "buildId": "fixture-build"
21
+ }
22
+ }
23
+ },
24
+ "execution": {
25
+ "jsonrpc": "2.0",
26
+ "id": "request-1",
27
+ "method": "execution.run",
28
+ "params": {
29
+ "version": 2,
30
+ "repository": "/workspace/repository",
31
+ "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32
+ "scope": {
33
+ "paths": ["service-a", "service-b"]
34
+ },
35
+ "identity": {
36
+ "runId": "run-1",
37
+ "attemptId": "attempt-1",
38
+ "buildId": "fixture-build"
39
+ },
40
+ "model": "fixture-model",
41
+ "reasoningEffort": "medium",
42
+ "requestId": "request-1",
43
+ "scanId": "scan-1",
44
+ "prompt": "Scan the selected paths.",
45
+ "runtime": {
46
+ "pluginRoot": "/opt/runtime/cli/_bundled_plugin",
47
+ "pluginVersion": "0.1.95",
48
+ "stateDirectory": "/scan/state",
49
+ "outputDirectory": "/scan/output",
50
+ "environment": {
51
+ "CODEX_SECURITY_STATE_DIR": "/scan/state",
52
+ "CODEX_SECURITY_CONFIG_PATH": "/scan/tmp/config-preflight.toml",
53
+ "CODEX_SECURITY_TARGET_PATHS_FILE": "/scan/tmp/target-paths.json"
54
+ }
55
+ }
56
+ }
57
+ },
58
+ "progress": {
59
+ "jsonrpc": "2.0",
60
+ "method": "execution.progress",
61
+ "params": {
62
+ "requestId": "request-1",
63
+ "event": {
64
+ "type": "progress",
65
+ "progress": {
66
+ "phase": "discovery",
67
+ "filesCompleted": 1,
68
+ "filesTotal": 2
69
+ }
70
+ }
71
+ }
72
+ },
73
+ "response": {
74
+ "jsonrpc": "2.0",
75
+ "id": "request-1",
76
+ "result": {
77
+ "requestId": "request-1",
78
+ "status": "completed",
79
+ "sessionId": "session-1",
80
+ "usage": {
81
+ "input_tokens": 12,
82
+ "output_tokens": 6,
83
+ "cached_input_tokens": 0
84
+ }
85
+ }
86
+ },
87
+ "terminal": {
88
+ "jsonrpc": "2.0",
89
+ "id": "run",
90
+ "result": {
91
+ "version": 2,
92
+ "repository": "/workspace/repository",
93
+ "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
94
+ "scope": {
95
+ "paths": ["service-a", "service-b"]
96
+ },
97
+ "identity": {
98
+ "runId": "run-1",
99
+ "attemptId": "attempt-1",
100
+ "buildId": "fixture-build"
101
+ },
102
+ "outputDirectory": "/scan/output",
103
+ "status": "completed",
104
+ "scanId": "scan-1",
105
+ "pluginVersion": "0.1.95",
106
+ "provenance": {
107
+ "cliVersion": "0.2.0",
108
+ "pluginVersion": "0.1.95",
109
+ "buildId": "fixture-build"
110
+ },
111
+ "execution": {
112
+ "requestId": "request-1",
113
+ "status": "completed",
114
+ "sessionId": "session-1",
115
+ "usage": {
116
+ "input_tokens": 12,
117
+ "output_tokens": 6,
118
+ "cached_input_tokens": 0
119
+ }
120
+ },
121
+ "artifacts": [
122
+ {
123
+ "path": "scan-manifest.json",
124
+ "sha256": "1111111111111111111111111111111111111111111111111111111111111111",
125
+ "bytes": 1024
126
+ },
127
+ {
128
+ "path": "findings.json",
129
+ "sha256": "2222222222222222222222222222222222222222222222222222222222222222",
130
+ "bytes": 256
131
+ },
132
+ {
133
+ "path": "coverage.json",
134
+ "sha256": "3333333333333333333333333333333333333333333333333333333333333333",
135
+ "bytes": 512
136
+ },
137
+ {
138
+ "path": "report.md",
139
+ "sha256": "4444444444444444444444444444444444444444444444444444444444444444",
140
+ "bytes": 768
141
+ }
142
+ ]
143
+ }
144
+ }
145
+ }
@@ -21,6 +21,11 @@
21
21
  "type": "string",
22
22
  "enum": ["standard", "deep"]
23
23
  },
24
+ "max_time_minutes": {
25
+ "description": "Investigation minutes: advisory in Standard (default: unset); enforced Deep discovery limit (default and maximum: 5760). Scans may finish early; reporting may run longer.",
26
+ "type": "number",
27
+ "exclusiveMinimum": 0
28
+ },
24
29
  "cyber_access_program": {
25
30
  "description": "Experimental Cyber access program for scan turns (OpenAI provider only). Omit to preserve Codex defaults.",
26
31
  "type": "string",
@@ -138,7 +143,8 @@
138
143
  },
139
144
  "max_time_hours": {
140
145
  "default": 96,
141
- "description": "Maximum deep-scan discovery hours (default: 96; maximum: 96).",
146
+ "deprecated": true,
147
+ "description": "Deprecated Deep-only alias for maxTimeMinutes / --max-time, in hours (default: 96; maximum: 96).",
142
148
  "type": "number",
143
149
  "exclusiveMinimum": 0,
144
150
  "maximum": 96
@@ -1,76 +0,0 @@
1
- version = 1
2
-
3
- [capabilities.delegated_workers]
4
- kind = "runtime"
5
- check = "delegation_available"
6
-
7
- [capabilities.goal_tools]
8
- kind = "runtime"
9
- check = "goal_tools_available"
10
-
11
- [capabilities.usable_worker_slots_6]
12
- kind = "multi_agent_capacity"
13
- op = ">="
14
- value = 6
15
- v1_default = 6
16
-
17
- [capabilities.goals_enabled]
18
- kind = "config"
19
- path = "features.goals"
20
- op = "=="
21
- value = true
22
- default = true
23
-
24
- [profiles.security_diff_scan]
25
- description = "Capabilities for Git-backed Codex Security diff scans."
26
-
27
- [[profiles.security_diff_scan.requirements]]
28
- capability = "delegated_workers"
29
- severity = "warn"
30
- reason = "Large diff scans may use discovery workers when available; otherwise the parent reviews every changed file."
31
-
32
- [[profiles.security_diff_scan.requirements]]
33
- capability = "goal_tools"
34
- severity = "suggest"
35
- reason = "Goal tools help long diff scans preserve completion criteria across many steps."
36
-
37
- [[profiles.security_diff_scan.requirements]]
38
- capability = "goals_enabled"
39
- severity = "suggest"
40
- reason = "Enabling goals makes long diff scans easier to resume and audit."
41
-
42
- [profiles.security_scan]
43
- description = "Capabilities for repository-wide or scoped-path Codex Security scans."
44
-
45
- [[profiles.security_scan.requirements]]
46
- capability = "delegated_workers"
47
- severity = "warn"
48
- reason = "Standard scans use an independent baseline auditor and focused investigation workers when delegation is available."
49
-
50
- [[profiles.security_scan.requirements]]
51
- capability = "usable_worker_slots_6"
52
- severity = "warn"
53
- reason = "A six-thread cap provides room for an independent baseline and parallel investigators; it does not require six running workers."
54
-
55
- [profiles.deep_security_scan]
56
- description = "Capabilities for deep repository-wide Codex Security scans."
57
- requirements = []
58
-
59
- [profiles.security_diff_scan.remediation]
60
- summary = "Recommended Codex config for longer diff scans."
61
-
62
- [[profiles.security_diff_scan.remediation.patches]]
63
- path = "features.goals"
64
- value = true
65
-
66
- [[routes]]
67
- skill = "security-diff-scan"
68
- profile = "security_diff_scan"
69
-
70
- [[routes]]
71
- skill = "security-scan"
72
- profile = "security_scan"
73
-
74
- [[routes]]
75
- skill = "deep-security-scan"
76
- profile = "deep_security_scan"