@openai/codex-security 0.5.0 → 0.5.1

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 (169) hide show
  1. package/README.md +7 -0
  2. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  3. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  4. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  5. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +60 -9
  6. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  7. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  8. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +1 -1
  9. package/_bundled_plugin/scripts/finalize_scan_contract.py +12 -1
  10. package/_bundled_plugin/scripts/generate_in_scope_files.py +6 -6
  11. package/_bundled_plugin/scripts/generate_rank_input.py +12 -6
  12. package/_bundled_plugin/scripts/report_projection.py +2 -1
  13. package/_bundled_plugin/scripts/threat_model_projection.py +1 -3
  14. package/_bundled_plugin/scripts/workbench/saved_coverage.py +234 -0
  15. package/_bundled_plugin/scripts/workbench_cli.py +5 -7
  16. package/_bundled_plugin/scripts/workbench_db.py +12 -6
  17. package/_bundled_plugin/scripts/workbench_native_indexes.py +10 -7
  18. package/_bundled_plugin/scripts/workbench_publication.py +4 -3
  19. package/_bundled_plugin/scripts/workbench_remediation.py +5 -1
  20. package/_bundled_plugin/scripts/workbench_saved_results.py +542 -148
  21. package/_bundled_plugin/scripts/workbench_scan_history.py +79 -78
  22. package/_bundled_plugin/scripts/workbench_scan_usage.py +61 -13
  23. package/_bundled_plugin/scripts/workbench_target.py +21 -7
  24. package/_bundled_plugin/scripts/workbench_validation.py +21 -18
  25. package/_bundled_plugin/shared/workbench-migrations.json +10 -0
  26. package/dist/api.d.ts +1 -1
  27. package/dist/api.d.ts.map +1 -1
  28. package/dist/api.js +161 -57
  29. package/dist/api.js.map +1 -1
  30. package/dist/classify-scan-severity.d.ts.map +1 -1
  31. package/dist/classify-scan-severity.js +16 -18
  32. package/dist/classify-scan-severity.js.map +1 -1
  33. package/dist/cli-daybreak.d.ts +5 -0
  34. package/dist/cli-daybreak.d.ts.map +1 -0
  35. package/dist/cli-daybreak.js +89 -0
  36. package/dist/cli-daybreak.js.map +1 -0
  37. package/dist/cli.d.ts +5 -1
  38. package/dist/cli.d.ts.map +1 -1
  39. package/dist/cli.js +821 -591
  40. package/dist/cli.js.map +1 -1
  41. package/dist/codeowners.js +2 -2
  42. package/dist/codeowners.js.map +1 -1
  43. package/dist/component-plan.d.ts.map +1 -1
  44. package/dist/component-plan.js +3 -2
  45. package/dist/component-plan.js.map +1 -1
  46. package/dist/component-scan.js +2 -2
  47. package/dist/component-scan.js.map +1 -1
  48. package/dist/config.d.ts.map +1 -1
  49. package/dist/config.js +5 -1
  50. package/dist/config.js.map +1 -1
  51. package/dist/cost.d.ts +2 -1
  52. package/dist/cost.d.ts.map +1 -1
  53. package/dist/cost.js +17 -8
  54. package/dist/cost.js.map +1 -1
  55. package/dist/custom-validation.d.ts.map +1 -1
  56. package/dist/custom-validation.js +2 -5
  57. package/dist/custom-validation.js.map +1 -1
  58. package/dist/deduplication/codex-review.d.ts.map +1 -1
  59. package/dist/deduplication/codex-review.js +8 -6
  60. package/dist/deduplication/codex-review.js.map +1 -1
  61. package/dist/deduplication/local.d.ts.map +1 -1
  62. package/dist/deduplication/local.js +5 -2
  63. package/dist/deduplication/local.js.map +1 -1
  64. package/dist/deduplication/retry.d.ts.map +1 -1
  65. package/dist/deduplication/retry.js +5 -0
  66. package/dist/deduplication/retry.js.map +1 -1
  67. package/dist/deduplication/scan.js +5 -1
  68. package/dist/deduplication/scan.js.map +1 -1
  69. package/dist/deep-scan.d.ts +6 -0
  70. package/dist/deep-scan.d.ts.map +1 -1
  71. package/dist/deep-scan.js +8 -6
  72. package/dist/deep-scan.js.map +1 -1
  73. package/dist/findings-import.d.ts.map +1 -1
  74. package/dist/findings-import.js +23 -3
  75. package/dist/findings-import.js.map +1 -1
  76. package/dist/host-protocol.d.ts +1 -0
  77. package/dist/host-protocol.d.ts.map +1 -1
  78. package/dist/host-protocol.js +1 -1
  79. package/dist/host-protocol.js.map +1 -1
  80. package/dist/hosted-remediation-protocol.d.ts +5 -0
  81. package/dist/hosted-remediation-protocol.d.ts.map +1 -0
  82. package/dist/hosted-remediation-protocol.js +26 -0
  83. package/dist/hosted-remediation-protocol.js.map +1 -0
  84. package/dist/hosted-remediation.d.ts +89 -0
  85. package/dist/hosted-remediation.d.ts.map +1 -0
  86. package/dist/hosted-remediation.js +122 -0
  87. package/dist/hosted-remediation.js.map +1 -0
  88. package/dist/import-scan.d.ts +1 -0
  89. package/dist/import-scan.d.ts.map +1 -1
  90. package/dist/import-scan.js +5 -1
  91. package/dist/import-scan.js.map +1 -1
  92. package/dist/index.d.ts +5 -1
  93. package/dist/index.d.ts.map +1 -1
  94. package/dist/index.js +2 -0
  95. package/dist/index.js.map +1 -1
  96. package/dist/multiscan.d.ts.map +1 -1
  97. package/dist/multiscan.js +3 -1
  98. package/dist/multiscan.js.map +1 -1
  99. package/dist/project-config.d.ts.map +1 -1
  100. package/dist/project-config.js +13 -9
  101. package/dist/project-config.js.map +1 -1
  102. package/dist/publish.d.ts +2 -0
  103. package/dist/publish.d.ts.map +1 -1
  104. package/dist/publish.js +9 -0
  105. package/dist/publish.js.map +1 -1
  106. package/dist/remediation.d.ts +63 -0
  107. package/dist/remediation.d.ts.map +1 -0
  108. package/dist/remediation.js +110 -0
  109. package/dist/remediation.js.map +1 -0
  110. package/dist/request-metadata.d.ts +17 -7
  111. package/dist/request-metadata.d.ts.map +1 -1
  112. package/dist/request-metadata.js +43 -8
  113. package/dist/request-metadata.js.map +1 -1
  114. package/dist/runtime.d.ts.map +1 -1
  115. package/dist/runtime.js +21 -14
  116. package/dist/runtime.js.map +1 -1
  117. package/dist/saved-scan-bootstrap.d.ts +1 -0
  118. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  119. package/dist/saved-scan-bootstrap.js +16 -4
  120. package/dist/saved-scan-bootstrap.js.map +1 -1
  121. package/dist/scan-activity.js +8 -8
  122. package/dist/scan-activity.js.map +1 -1
  123. package/dist/scan-comparison.d.ts.map +1 -1
  124. package/dist/scan-comparison.js +15 -9
  125. package/dist/scan-comparison.js.map +1 -1
  126. package/dist/scan-dashboard.d.ts.map +1 -1
  127. package/dist/scan-dashboard.js +12 -6
  128. package/dist/scan-dashboard.js.map +1 -1
  129. package/dist/scan-executor.d.ts +5 -1
  130. package/dist/scan-executor.d.ts.map +1 -1
  131. package/dist/scan-executor.js +9 -8
  132. package/dist/scan-executor.js.map +1 -1
  133. package/dist/{deep-progress.d.ts → scan-progress.d.ts} +15 -7
  134. package/dist/scan-progress.d.ts.map +1 -0
  135. package/dist/scan-progress.js +138 -0
  136. package/dist/scan-progress.js.map +1 -0
  137. package/dist/security-policy.js +1 -1
  138. package/dist/security-policy.js.map +1 -1
  139. package/dist/server/embeddings.d.ts.map +1 -1
  140. package/dist/server/embeddings.js +4 -0
  141. package/dist/server/embeddings.js.map +1 -1
  142. package/dist/server/sqlite-store.d.ts.map +1 -1
  143. package/dist/server/sqlite-store.js +14 -2
  144. package/dist/server/sqlite-store.js.map +1 -1
  145. package/dist/severity-store.js +4 -1
  146. package/dist/severity-store.js.map +1 -1
  147. package/dist/timestamps.d.ts +3 -0
  148. package/dist/timestamps.d.ts.map +1 -0
  149. package/dist/timestamps.js +14 -0
  150. package/dist/timestamps.js.map +1 -0
  151. package/dist/version.d.ts +1 -1
  152. package/dist/version.d.ts.map +1 -1
  153. package/dist/version.js +13 -2
  154. package/dist/version.js.map +1 -1
  155. package/dist/workbench-arguments.d.ts.map +1 -1
  156. package/dist/workbench-arguments.js +9 -3
  157. package/dist/workbench-arguments.js.map +1 -1
  158. package/dist/worker-progress.d.ts +11 -1
  159. package/dist/worker-progress.d.ts.map +1 -1
  160. package/dist/worker-progress.js +11 -1
  161. package/dist/worker-progress.js.map +1 -1
  162. package/docs/cli.md +86 -15
  163. package/docs/findings-service.md +7 -2
  164. package/docs/hosted-remediation.md +117 -0
  165. package/docs/hosted-scans.md +8 -3
  166. package/package.json +5 -4
  167. package/dist/deep-progress.d.ts.map +0 -1
  168. package/dist/deep-progress.js +0 -92
  169. package/dist/deep-progress.js.map +0 -1
package/docs/cli.md CHANGED
@@ -105,6 +105,40 @@ changed; otherwise run `logout`, then `login`.
105
105
  Some cybersecurity requests and protected findings require
106
106
  [Trusted Access for Cyber](https://chatgpt.com/cyber).
107
107
 
108
+ ### Daybreak opt-in
109
+
110
+ Codex 0.163.0 and later default the Daybreak toggle to off. Enable it through
111
+ the existing native configuration override:
112
+
113
+ ```bash
114
+ codex-security scan . --codex daybreak=true
115
+ codex-security scan . --mode deep --codex daybreak=true
116
+ ```
117
+
118
+ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
119
+ In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
120
+ to explicitly turn it off.
121
+ The setting carries through saved scan recipes, resumed scans, Deep Scan
122
+ discovery and reducer workers, and `scan --patch`. Standalone `validate`,
123
+ `patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
124
+ Threads created by these commands retain the setting when resumed in Codex.
125
+ Scans use isolated configuration, so set it on the CLI, SDK client, or project
126
+ file even if it is enabled in your personal Codex configuration.
127
+
128
+ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
129
+ an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
130
+ or set top-level `daybreak = true` in the configuration loaded by the runner.
131
+ Deep Scan inherits the active turn's effective access program from its saved
132
+ Codex session, including an explicit Standard selection. Discovery and reducer
133
+ workers retain that selection when resumed. If the host does not supply a
134
+ persisted turn context, workers use their runner configuration; CLI and SDK scans
135
+ use the explicit scan settings above.
136
+
137
+ Daybreak requires the built-in OpenAI provider and compatible account or API
138
+ project access. Codex selects the available program; this setting does not
139
+ grant access. An explicit [Cyber access program](#select-a-cyber-access-program)
140
+ takes precedence over the toggle for that turn.
141
+
108
142
  ### Daybreak Blue with an API key
109
143
 
110
144
  The [Responses API defaults](https://developers.openai.com/api/docs/guides/daybreak#understand-defaults-when-omitted)
@@ -300,9 +334,15 @@ and keeps completed documents. Fix the problem and retry in a new directory.
300
334
  ### Source access and restrictions
301
335
 
302
336
  The command uses scan authentication and read-only access to the selected source.
303
- It denies Git metadata and sibling-component access, disables network, web, apps,
304
- and MCP, and uses only Codex's core shell environment. Knowledge-base text stays
305
- in private review artifacts during generation and is removed afterward.
337
+ It denies Git metadata, the credential home, and private runtime configuration,
338
+ disables network, web, apps, and MCP, and uses only Codex's core shell environment.
339
+ On Unix, filesystem reads are limited to the selected source, runtime files, and
340
+ review artifacts. Windows' elevated sandbox requires broader local read access,
341
+ including sibling components, while keeping those explicit denials and read-only
342
+ permissions. Ambient Codex authentication and provider-profile files remain
343
+ excluded; Windows resolves file-pattern denials when each sandboxed command
344
+ starts. Knowledge-base text stays in private review artifacts during
345
+ generation and is removed afterward.
306
346
 
307
347
  Targets and links stay within the checkout and outside Git metadata. Linked
308
348
  worktrees and initialized submodules use their own roots. For a separate Git
@@ -354,9 +394,12 @@ codex-security scan . --working-tree
354
394
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
355
395
  ```
356
396
 
397
+ Whole-codebase and path scans also accept ordinary directories, including SVN
398
+ working copies. Their source inventories exclude `.git` and `.svn` metadata.
399
+
357
400
  `--diff` scans committed changes; `--working-tree` scans staged and unstaged
358
- changes. Deep scans support whole repositories and path scopes. Working-tree
359
- snapshots include untracked nested Git repositories. Initialized submodules must
401
+ changes. Both require Git. Deep scans support whole repositories and path scopes.
402
+ Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
360
403
  be clean and at the commit recorded by the parent.
361
404
 
362
405
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
@@ -613,7 +656,9 @@ codex-security scan-components . \
613
656
  --output-dir /path/outside/project/results
614
657
  ```
615
658
 
616
- Plans use repository-relative paths:
659
+ Plans use literal repository-relative paths, so `~/src` selects a directory
660
+ named `~` inside the repository rather than expanding the home directory.
661
+ Existing absolute paths inside the repository are also accepted.
617
662
 
618
663
  ```json
619
664
  {
@@ -646,7 +691,8 @@ or API-key auth. SDK-selected command providers retain their authentication.
646
691
 
647
692
  From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
648
693
  Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
649
- planning and authentication choices.
694
+ planning and authentication choices. Custom `createSecurity` clients receive
695
+ absolute targets; saved plans and component receipts retain relative paths.
650
696
 
651
697
  ### Set investigation time
652
698
 
@@ -757,7 +803,7 @@ or Windows MCP launcher. Saved reports remain readable.
757
803
  Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
758
804
 
759
805
  `validate`, `patch`, and `verify-fix` limit native overrides to `model`,
760
- `model_reasoning_effort`, `model_provider`, `model_providers`, and
806
+ `model_reasoning_effort`, `model_provider`, `model_providers`, `daybreak`, and
761
807
  `analytics.enabled`. For a custom provider:
762
808
 
763
809
  ```bash
@@ -779,14 +825,28 @@ that command. Model, effort, and provider choices carry into patch-risk assessme
779
825
  Model requests include Codex Security attribution in `responses_api_metadata`:
780
826
  `codex_security_surface` (`cli` or `sdk`), `codex_security_command`,
781
827
  `codex_security_package_version`, and `codex_security_plugin_version` when the
782
- selected plugin declares a version. These fields identify the workflow and
783
- versions producing a model request; they do not record command starts,
784
- completions, or failures.
828
+ selected plugin declares a version. The shared context adds
829
+ `codex_security_provider` for the configured provider family when the wrapper
830
+ selects a provider, and
831
+ `codex_security_scan_mode` for scans. Custom provider names use `custom`.
832
+ Provider attribution reflects the wrapper's selected profile or default;
833
+ native managed configuration may select a different provider before inference.
834
+ The GitHub Action supplies `codex_security_integration=github_action`;
835
+ Deep Scan workers retain the context and add `codex_security_worker_role`.
836
+ Caller metadata, including literal dotted keys, is preserved. Connected-app
837
+ publication uses the same request attribution; embedding requests identify
838
+ the package and version in their `User-Agent`.
839
+
840
+ These fields provide request attribution for supported inference providers, including
841
+ Bedrock. They do not create a separate telemetry collector, record command
842
+ starts or outcomes, or make another provider's traffic visible to OpenAI.
785
843
 
786
844
  Disable Codex usage analytics and built-in metrics with
787
845
  `--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
788
846
  patch-risk assessment, and Deep Scan discovery and reducer workers, including
789
- resumed workers. Deep Scan workers also preserve the scan's request metadata.
847
+ resumed workers. Selected-profile settings take precedence over root settings.
848
+ Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
849
+ workers, including exporter choices and prompt-logging controls.
790
850
  Model-request attribution metadata remains attached when analytics are disabled.
791
851
  The setting does not control configured OpenTelemetry exporters, integrations,
792
852
  authentication, or CLI update checks. Validation uses isolated configuration;
@@ -848,9 +908,12 @@ Preserve existing state, then choose a private `CODEX_SECURITY_STATE_DIR` outsid
848
908
  the rejected ancestor and the repository, with a full ancestor chain that passes
849
909
  the same checks. If the volume root is rejected, another directory on that
850
910
  volume cannot resolve it; use a separately provisioned volume with trusted
851
- ancestry. Temporary bootstrap homes also need trusted ancestry: set `TEMP` and
852
- `TMP` to a private directory on that volume before launching the CLI. Do not
853
- change the system volume's owner or ACL to make a scan run. If no suitable
911
+ ancestry. On Windows, local runtime bootstrap directories are created beside
912
+ `codex-home` in the state directory and removed when the SDK client closes.
913
+ They use the same trusted ancestry checks, so sandbox write permissions on
914
+ `TEMP` do not prevent runtime preparation. `TEMP`, `TMP`, and scan output
915
+ locations are unchanged. Do not change the system volume's owner or ACL to
916
+ make a scan run. If no suitable
854
917
  location is available, this layout cannot provision credentials safely under
855
918
  the current checks. Sign in again if needed; a new state directory has separate
856
919
  scan history and does not migrate credentials or reports from the old state
@@ -1001,6 +1064,8 @@ codex-security bulk-scan repositories.csv \
1001
1064
  ```
1002
1065
 
1003
1066
  Bulk scans use clean shallow checkouts and support repository/path scopes.
1067
+ CSV scopes are literal paths relative to each checkout, including names such
1068
+ as `~/src`.
1004
1069
  Configured diff or working-tree scopes are rejected unless every affected row
1005
1070
  overrides them with a path scope. `--output-dir` requires CSV input.
1006
1071
 
@@ -1451,6 +1516,9 @@ scan and custom-validation prompts when the original used them:
1451
1516
  codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
1452
1517
  ```
1453
1518
 
1519
+ Saved path scopes remain relative to the repository. Names such as `~` and
1520
+ `~/source.ts` are replayed literally; they do not select the home directory.
1521
+
1454
1522
  A rerun creates a new scan. When the original has saved input identities, the
1455
1523
  rerun reports changes to the scan instructions or knowledge base. `scans show`
1456
1524
  includes the saved scope, runtime and Deep Scan settings, instruction digest,
@@ -1768,6 +1836,9 @@ validation, and `patch` still fixes and verifies findings. Both commands accept
1768
1836
  or literal text and work in the current directory. Saved finding/occurrence IDs
1769
1837
  select their original repository for patching.
1770
1838
 
1839
+ Basic patching also works in ordinary directories and Git worktrees before their
1840
+ first commit. Directory change tracking excludes `.git` and `.svn` metadata.
1841
+
1771
1842
  ```bash
1772
1843
  codex-security validate "Possible SQL injection" --effort high
1773
1844
  codex-security validate findings.json --knowledge-base ./context --context "Check the tenant boundary."
@@ -25,6 +25,8 @@ deployments; local deduplication uses the database selected by
25
25
  For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
26
26
  static key or `() => string | Promise<string>` as its first argument. It calls
27
27
  the callback before each HTTP batch; the caller handles token acquisition.
28
+ Cancellation prevents a new callback or HTTP request. Direct embedder callers
29
+ still await a key callback that has already started.
28
30
  Pass `fetch` as the second argument and the full endpoint URL as the third.
29
31
  By default, the saved-scan deduplication APIs use environment credentials. A
30
32
  custom SDK `embedding` binding can supply an adapter with its own credentials,
@@ -185,7 +187,8 @@ console.log(result.duplicateGroups);
185
187
  For a different embedding provider or model, both saved-scan SDK methods accept
186
188
  an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
187
189
  `{ model, vector }` per input finding, in input order. The adapter owns its
188
- credentials, tokenization, chunking, and provider request format.
190
+ credentials, tokenization, chunking, and provider request format. Cancellation
191
+ stops the SDK's wait for embeddings; the adapter owns cleanup of its ongoing work.
189
192
 
190
193
  ```typescript
191
194
  import { deduplicateScan, type FindingEmbedder } from "@openai/codex-security";
@@ -314,7 +317,9 @@ required-source-access blockers are not retried. Refusals are not retried or
314
317
  sent to another model. If candidate retrieval or review still fails, the
315
318
  operation fails without posting groups.
316
319
  A failed group-write request may already have committed; resubmitting the same
317
- memberships does not create duplicate groups. Non-cancellation review failures
320
+ memberships does not create duplicate groups. Cancellation can also arrive after
321
+ a write completes; it does not mean that remote findings are unchanged. Completed
322
+ workflow stages remain saved even when cancellation is reported. Non-cancellation review failures
318
323
  throw `DeduplicationReviewError`, with diagnostic text and `metadata` for the
319
324
  stage, model, category, attempt count, and reason.
320
325
 
@@ -0,0 +1,117 @@
1
+ # Hosted patching and fix verification
2
+
3
+ `runHostedRemediation(input, { executor, signal, onEvent })` runs one patch or
4
+ verification using the same skills, prompts, and result schemas as the local
5
+ CLI. It requires a host executor and never starts local inference. This API is
6
+ separate from the Standard scan API and does not create scan/workbench state.
7
+
8
+ The host prepares an isolated checkout, freezes its HEAD, supplies the original
9
+ finding evidence and repository instructions, and enforces the requested
10
+ sandbox. For verification, the host must first apply the exact candidate patch
11
+ to its recorded base. The API does not apply a patch or infer a branch from the
12
+ finding. It checks HEAD before and after execution; the host owns checking the
13
+ candidate's bytes/digest and verifying that verification did not change them.
14
+
15
+ ```ts
16
+ const result = await runHostedRemediation(
17
+ {
18
+ version: 1,
19
+ operation: "verify", // or "patch"
20
+ repository: "/workspace/repository",
21
+ revision: "0123456789012345678901234567890123456789",
22
+ finding: {
23
+ id: "finding-1",
24
+ context:
25
+ "Original vulnerability, source evidence, reproducer, and controls.",
26
+ },
27
+ instructions: "Preserve existing repository conventions.",
28
+ validationInstructions:
29
+ "Run the focused reproduction and legitimate control.",
30
+ model: "your-model",
31
+ reasoningEffort: "high",
32
+ identity: {
33
+ runId: "run-1",
34
+ attemptId: "attempt-1",
35
+ buildId: "runtime-build",
36
+ },
37
+ },
38
+ { executor },
39
+ );
40
+ ```
41
+
42
+ Both instruction fields are optional and are distinct from finding data.
43
+ Reasoning effort is passed through unchanged so the selected model and provider
44
+ determine which values they support.
45
+ Verification remains read-only even when validation instructions request setup:
46
+ a required check that cannot run without repository changes is a proof gap,
47
+ not permission to edit. Generation's ordinary skill checks and standalone
48
+ verification are separate operations.
49
+
50
+ The executor receives one request with a unique `requestId`, operation,
51
+ repository/revision, identity, finding ID, prompt, model, reasoning effort,
52
+ `sandbox` (`workspace-write` for patch, `read-only` for verify), and
53
+ `runtime: { pluginRoot, pluginVersion }`. Its receipt contains the same
54
+ `requestId`, `status` (`completed`, `failed`, `canceled`, or
55
+ `acceptance_unknown`), `sessionId` (required for completed execution), and
56
+ optional `finalResponse`, opaque `usage`, `message`, and `error`.
57
+
58
+ The returned result retains that receipt, runtime provenance and request
59
+ identity even when parsing fails. `status: "completed"` means execution and
60
+ result validation finished; it does not imply that a patch fixed the finding:
61
+
62
+ - `patch` contains `occurrenceId`, `status` (`verified`, `no_change`, `blocked`,
63
+ or `failed`), `files`, and optional `verification`/`reason`. Verified and
64
+ no-change outcomes require verification evidence; blocked and failed outcomes
65
+ require a reason. The host must inspect the actual changes, collect the
66
+ canonical diff, and run separate verification.
67
+ - `verification` contains `id`, `status` (`fixed`, `still_vulnerable`, or
68
+ `inconclusive`), nonempty `evidence`, and a nonempty `checks` array. Each check
69
+ contains a nonempty `name`, `status` (`passed`, `failed`, or `not_run`),
70
+ nonempty `evidence`, and optional `command`. Names and evidence distinguish
71
+ static assessment from executed tests; `command` records an actual attempted
72
+ command, not a suggestion. A required check that could not be completed is
73
+ `not_run` with its blocker in `evidence`. An inconclusive result is preserved
74
+ as an assessment outcome rather than converted to execution failure.
75
+
76
+ Hosted verification requests these checks explicitly and rejects a result with
77
+ missing or empty checks, or a `fixed` verdict with a failed or unrun check. The
78
+ model must report the required vulnerability and legitimate-behavior checks;
79
+ the SDK does not reconstruct checks from prose. A malformed result retains the
80
+ execution receipt and returns `status: "failed"` with `INVALID_RESULT`, rather
81
+ than claiming verification succeeded. Shared result types keep `checks`
82
+ optional for older and local results; the local CLI command and result contract
83
+ are unchanged.
84
+
85
+ The host owns durable attempts, cancellation/reconciliation, usage, artifact
86
+ storage and publication. No operation publishes a pull request or marks a
87
+ finding closed. Retrying persistence must not resubmit execution.
88
+
89
+ ## JSON-RPC launcher
90
+
91
+ The SDK exports `runHostedRemediationProtocol`. An installed npm package can run it
92
+ without adding any public CLI flag:
93
+
94
+ ```sh
95
+ node --input-type=module -e '
96
+ import { runHostedRemediationProtocol } from "@openai/codex-security";
97
+ process.exitCode = await runHostedRemediationProtocol(process.stdin, process.stdout);
98
+ '
99
+ ```
100
+
101
+ Use the existing newline-delimited host transport: send one `run` request whose
102
+ `params` are the input above; respond to `execution.run` with the executor
103
+ receipt. `execution.progress` notifications use `{ requestId, event }` and are
104
+ forwarded as `remediation.progress` with `{ id: originalRunId, event }`. Send
105
+ `cancel` with `{ id: originalRunId }` to receive `execution.cancel`; then return
106
+ the final execution receipt so usage and session identity survive cancellation.
107
+ The transport emits one terminal result. Preparation failures are JSON-RPC
108
+ errors; a mismatched HEAD includes `error.data.reason: "revision_mismatch"`.
109
+
110
+ Run the deterministic installed-package smoke check without model credentials:
111
+
112
+ ```sh
113
+ node scripts/smoke-hosted-remediation.mjs /path/to/node_modules/@openai/codex-security
114
+ ```
115
+
116
+ It uses a fake executor over real pipes, prepares a synthetic candidate, and
117
+ checks both operation contracts. It does not evaluate actual model fixes.
@@ -4,6 +4,9 @@
4
4
  stdin/stdout. Use the flag alone. It performs no login, update check, local
5
5
  inference, or model fallback. Ordinary local scans keep their existing behavior.
6
6
 
7
+ For hosted patch generation and verification, use the separate
8
+ [hosted remediation API](hosted-remediation.md).
9
+
7
10
  ## Public executor API
8
11
 
9
12
  Use the standalone `runHostedScan(input, { executor, signal, onEvent })`
@@ -73,9 +76,11 @@ local profiles and other local scan options are not accepted.
73
76
 
74
77
  `ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
75
78
  `{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
+ uses the existing `ScanProgress` type; activity uses `ScanActivity`. Progress may
80
+ include `reviewItems: { completed, total }` for saved reviews, counted separately
81
+ from files. Observer failures cannot stop execution. Aborting waits for the
82
+ executor to settle; the host must cancel remote work and return its recorded
83
+ outcome.
79
84
 
80
85
  Preparation errors throw before execution. Execution and finalization return a
81
86
  `HostedScanResult` receipt with status `completed`, `failed`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openai/codex-security",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "TypeScript SDK and CLI for Codex Security",
5
5
  "license": "Apache-2.0",
6
6
  "author": "OpenAI",
@@ -47,7 +47,8 @@
47
47
  "docs/dedupe-records.md",
48
48
  "docs/classify-severity-records.md",
49
49
  "docs/hosted-scans.md",
50
- "docs/validate-records.md"
50
+ "docs/validate-records.md",
51
+ "docs/hosted-remediation.md"
51
52
  ],
52
53
  "publishConfig": {
53
54
  "access": "public",
@@ -76,7 +77,7 @@
76
77
  "strip-ansi": "7.2.0",
77
78
  "yaml": "2.9.1",
78
79
  "yauzl": "3.4.0",
79
- "zod": "4.6.6"
80
+ "zod": "4.6.7"
80
81
  },
81
82
  "devDependencies": {
82
83
  "@stryker-mutator/core": "10.0.0",
@@ -95,7 +96,7 @@
95
96
  "prettier": "3.9.10",
96
97
  "typescript": "7.0.2"
97
98
  },
98
- "gitHead": "03414ad84e91a8638bde85af08c47fe957dc9323",
99
+ "gitHead": "b2fa51576d81cda5e311e7eb89131ffb13daad8b",
99
100
  "scripts": {
100
101
  "audit:prod": "pnpm audit --prod --audit-level high",
101
102
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -1 +0,0 @@
1
- {"version":3,"file":"deep-progress.d.ts","sourceRoot":"","sources":["../src/deep-progress.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;GAUf,CAAC;AAEN,MAAM,WAAW,gBAAiB,SAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC;IACvE,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,UAAU,8BAA8B;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,UAAU,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAID,qBAAa,uBAAuB;;IAOlC,YAAmB,OAAO,EAAE,8BAA8B,EAEzD;IAEM,KAAK,IAAI,IAAI,CAUnB;IAEY,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CA+BpC;IAEM,IAAI,IAAI,IAAI,CAKlB;CACF;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,GACd,gBAAgB,GAAG,IAAI,CAWzB"}
@@ -1,92 +0,0 @@
1
- import { isRecord } from "./record.js";
2
- import { z } from "zod";
3
- const progressSchema = z
4
- .object({
5
- completed: z.int().nonnegative(),
6
- active: z.int().nonnegative(),
7
- maximum: z.int().positive(),
8
- consolidating: z.boolean().optional(),
9
- })
10
- .transform(({ consolidating, ...counts }) => ({
11
- ...counts,
12
- ...(consolidating === undefined ? {} : { consolidating }),
13
- }));
14
- const DEEP_PROGRESS_POLL_INTERVAL_MS = 5_000;
15
- export class DeepScanProgressTracker {
16
- #options;
17
- #timer = null;
18
- #pending = null;
19
- #abortController = new AbortController();
20
- #lastProgress = null;
21
- constructor(options) {
22
- this.#options = options;
23
- }
24
- start() {
25
- if (this.#timer !== null || this.#abortController.signal.aborted)
26
- return;
27
- const poll = () => {
28
- void this.refresh().catch((error) => {
29
- this.#options.onError?.(error);
30
- });
31
- };
32
- this.#timer = setInterval(poll, DEEP_PROGRESS_POLL_INTERVAL_MS);
33
- this.#timer.unref();
34
- poll();
35
- }
36
- async refresh() {
37
- if (this.#abortController.signal.aborted)
38
- return;
39
- if (this.#pending !== null)
40
- return await this.#pending;
41
- const abortController = this.#abortController;
42
- let update = null;
43
- update = (async () => {
44
- try {
45
- const progress = deepScanProgressFromWorkbench(await this.#options.read(abortController.signal));
46
- if (abortController.signal.aborted ||
47
- progress === null ||
48
- (progress.completed === this.#lastProgress?.completed &&
49
- progress.active === this.#lastProgress?.active &&
50
- progress.maximum === this.#lastProgress?.maximum &&
51
- progress.consolidating === this.#lastProgress?.consolidating)) {
52
- return;
53
- }
54
- this.#lastProgress = progress;
55
- this.#options.onProgress(progress);
56
- }
57
- catch (error) {
58
- if (abortController.signal.aborted)
59
- return;
60
- throw error;
61
- }
62
- finally {
63
- if (this.#pending === update)
64
- this.#pending = null;
65
- }
66
- })();
67
- this.#pending = update;
68
- await update;
69
- }
70
- stop() {
71
- if (this.#abortController.signal.aborted)
72
- return;
73
- clearInterval(this.#timer ?? undefined);
74
- this.#timer = null;
75
- this.#abortController.abort();
76
- }
77
- }
78
- export function deepScanProgressFromWorkbench(result) {
79
- if (!isRecord(result) || !isRecord(result["scan"]))
80
- return null;
81
- const progress = result["scan"]["progress"];
82
- if (!isRecord(progress))
83
- return null;
84
- const independentReviews = progress["independentReviews"];
85
- if (independentReviews === undefined)
86
- return null;
87
- const parsed = progressSchema.safeParse(independentReviews);
88
- if (parsed.success)
89
- return parsed.data;
90
- throw new Error("Codex Security workbench returned invalid Deep Scan progress.");
91
- }
92
- //# sourceMappingURL=deep-progress.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"deep-progress.js","sourceRoot":"","sources":["../src/deep-progress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAChC,MAAM,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC7B,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC3B,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC;KACD,SAAS,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5C,GAAG,MAAM;IACT,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC;CAC1D,CAAC,CAAC,CAAC;AAaN,MAAM,8BAA8B,GAAG,KAAK,CAAC;AAE7C,MAAM,OAAO,uBAAuB;IACzB,QAAQ,CAAiC;IAClD,MAAM,GAA0B,IAAI,CAAC;IACrC,QAAQ,GAAyB,IAAI,CAAC;IAC7B,gBAAgB,GAAG,IAAI,eAAe,EAAE,CAAC;IAClD,aAAa,GAA4B,IAAI,CAAC;IAE9C,YAAmB,OAAuC;QACxD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAEM,KAAK;QACV,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACzE,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC3C,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,EAAE,CAAC;IACT,CAAC;IAEM,KAAK,CAAC,OAAO;QAClB,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACjD,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YAAE,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC;QACvD,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAC9C,IAAI,MAAM,GAAyB,IAAI,CAAC;QACxC,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACnB,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,6BAA6B,CAC5C,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CACjD,CAAC;gBACF,IACE,eAAe,CAAC,MAAM,CAAC,OAAO;oBAC9B,QAAQ,KAAK,IAAI;oBACjB,CAAC,QAAQ,CAAC,SAAS,KAAK,IAAI,CAAC,aAAa,EAAE,SAAS;wBACnD,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,aAAa,EAAE,MAAM;wBAC9C,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC,aAAa,EAAE,OAAO;wBAChD,QAAQ,CAAC,aAAa,KAAK,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,EAC/D,CAAC;oBACD,OAAO;gBACT,CAAC;gBACD,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;gBAC9B,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,eAAe,CAAC,MAAM,CAAC,OAAO;oBAAE,OAAO;gBAC3C,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,IAAI,IAAI,CAAC,QAAQ,KAAK,MAAM;oBAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACrD,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QACL,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;QACvB,MAAM,MAAM,CAAC;IACf,CAAC;IAEM,IAAI;QACT,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACjD,aAAa,CAAC,IAAI,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAChC,CAAC;CACF;AAED,MAAM,UAAU,6BAA6B,CAC3C,MAAe;IAEf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IAC1D,IAAI,kBAAkB,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACvC,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE,CAAC;AACJ,CAAC","sourcesContent":["import { isRecord } from \"./record.js\";\nimport { z } from \"zod\";\n\nconst progressSchema = z\n .object({\n completed: z.int().nonnegative(),\n active: z.int().nonnegative(),\n maximum: z.int().positive(),\n consolidating: z.boolean().optional(),\n })\n .transform(({ consolidating, ...counts }) => ({\n ...counts,\n ...(consolidating === undefined ? {} : { consolidating }),\n }));\n\nexport interface DeepScanProgress extends z.output<typeof progressSchema> {\n /** Whether the coordinator is reducing results or has finished. */\n consolidating?: boolean;\n}\n\ninterface DeepScanProgressTrackerOptions {\n read: (signal: AbortSignal) => Promise<unknown>;\n onProgress: (progress: DeepScanProgress) => void;\n onError?: (error: unknown) => void;\n}\n\nconst DEEP_PROGRESS_POLL_INTERVAL_MS = 5_000;\n\nexport class DeepScanProgressTracker {\n readonly #options: DeepScanProgressTrackerOptions;\n #timer: NodeJS.Timeout | null = null;\n #pending: Promise<void> | null = null;\n readonly #abortController = new AbortController();\n #lastProgress: DeepScanProgress | null = null;\n\n public constructor(options: DeepScanProgressTrackerOptions) {\n this.#options = options;\n }\n\n public start(): void {\n if (this.#timer !== null || this.#abortController.signal.aborted) return;\n const poll = () => {\n void this.refresh().catch((error: unknown) => {\n this.#options.onError?.(error);\n });\n };\n this.#timer = setInterval(poll, DEEP_PROGRESS_POLL_INTERVAL_MS);\n this.#timer.unref();\n poll();\n }\n\n public async refresh(): Promise<void> {\n if (this.#abortController.signal.aborted) return;\n if (this.#pending !== null) return await this.#pending;\n const abortController = this.#abortController;\n let update: Promise<void> | null = null;\n update = (async () => {\n try {\n const progress = deepScanProgressFromWorkbench(\n await this.#options.read(abortController.signal),\n );\n if (\n abortController.signal.aborted ||\n progress === null ||\n (progress.completed === this.#lastProgress?.completed &&\n progress.active === this.#lastProgress?.active &&\n progress.maximum === this.#lastProgress?.maximum &&\n progress.consolidating === this.#lastProgress?.consolidating)\n ) {\n return;\n }\n this.#lastProgress = progress;\n this.#options.onProgress(progress);\n } catch (error) {\n if (abortController.signal.aborted) return;\n throw error;\n } finally {\n if (this.#pending === update) this.#pending = null;\n }\n })();\n this.#pending = update;\n await update;\n }\n\n public stop(): void {\n if (this.#abortController.signal.aborted) return;\n clearInterval(this.#timer ?? undefined);\n this.#timer = null;\n this.#abortController.abort();\n }\n}\n\nexport function deepScanProgressFromWorkbench(\n result: unknown,\n): DeepScanProgress | null {\n if (!isRecord(result) || !isRecord(result[\"scan\"])) return null;\n const progress = result[\"scan\"][\"progress\"];\n if (!isRecord(progress)) return null;\n const independentReviews = progress[\"independentReviews\"];\n if (independentReviews === undefined) return null;\n const parsed = progressSchema.safeParse(independentReviews);\n if (parsed.success) return parsed.data;\n throw new Error(\n \"Codex Security workbench returned invalid Deep Scan progress.\",\n );\n}\n"]}