@openai/codex-security 0.1.25 → 0.1.27
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.
- package/README.md +616 -34
- package/_bundled_plugin/.app.json +0 -5
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/.mcp.json +2 -0
- package/_bundled_plugin/mcp/helpers.mjs +24 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/native/COPYRIGHT-library.html +5556 -0
- package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +5989 -0
- package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/licenses/Apache-2.0.txt +73 -0
- package/_bundled_plugin/mcp/native/licenses/BSD-2-Clause.txt +9 -0
- package/_bundled_plugin/mcp/native/licenses/MIT.txt +9 -0
- package/_bundled_plugin/mcp/native/licenses/Unicode-3.0.txt +39 -0
- package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/references/config-preflight.md +4 -2
- package/_bundled_plugin/references/core-scan.md +1 -1
- package/_bundled_plugin/references/final-report.md +5 -3
- package/_bundled_plugin/references/scan-artifacts.md +5 -1
- package/_bundled_plugin/references/scan-contract.md +42 -38
- package/_bundled_plugin/references/security-guidance.md +7 -1
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +27 -1
- package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
- package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -5
- package/_bundled_plugin/scripts/generate_in_scope_files.py +2 -2
- package/_bundled_plugin/scripts/generate_rank_input.py +8 -1
- package/_bundled_plugin/scripts/launch_codex_security_mcp +6 -0
- package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +43 -9
- package/_bundled_plugin/scripts/rank_preview.py +4 -1
- package/_bundled_plugin/scripts/report_projection.py +1 -1
- package/_bundled_plugin/scripts/workbench_cli.py +7 -0
- package/_bundled_plugin/scripts/workbench_db.py +44 -31
- package/_bundled_plugin/scripts/workbench_saved_results.py +41 -22
- package/_bundled_plugin/scripts/workbench_scan_history.py +117 -2
- package/_bundled_plugin/scripts/workbench_scan_usage.py +7 -6
- package/_bundled_plugin/scripts/workbench_schema.py +31 -0
- package/_bundled_plugin/scripts/workbench_severity.py +119 -0
- package/_bundled_plugin/scripts/workbench_validation.py +4 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -3
- package/_bundled_plugin/skills/define-security-policy/SKILL.md +3 -3
- package/_bundled_plugin/skills/verify-fix/SKILL.md +5 -1
- package/dist/api.d.ts +7 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +485 -65
- package/dist/api.js.map +1 -1
- package/dist/auth.js +10 -0
- package/dist/auth.js.map +1 -1
- package/dist/classify-scan-severity.d.ts +16 -0
- package/dist/classify-scan-severity.d.ts.map +1 -0
- package/dist/classify-scan-severity.js +96 -0
- package/dist/classify-scan-severity.js.map +1 -0
- package/dist/classify-severity.d.ts +38 -0
- package/dist/classify-severity.d.ts.map +1 -0
- package/dist/classify-severity.js +185 -0
- package/dist/classify-severity.js.map +1 -0
- package/dist/cli.d.ts +23 -4
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1277 -357
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +2 -207
- package/dist/cloud-publish.js.map +1 -1
- package/dist/component-plan.d.ts.map +1 -1
- package/dist/component-plan.js +116 -32
- package/dist/component-plan.js.map +1 -1
- package/dist/config.d.ts +1 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +17 -2
- package/dist/config.js.map +1 -1
- package/dist/contract.d.ts +5 -10
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js.map +1 -1
- package/dist/cost-model.d.ts +16 -0
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +57 -3
- package/dist/cost-model.js.map +1 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +38 -9
- package/dist/cost.js.map +1 -1
- package/dist/custom-validation-prompt.js +1 -1
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/codex-review.d.ts +6 -1
- package/dist/deduplication/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js +72 -17
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/deduplication-reviewer.js +1 -1
- package/dist/deduplication/deduplication-reviewer.js.map +1 -1
- package/dist/deduplication/deduplication.d.ts +2 -0
- package/dist/deduplication/deduplication.d.ts.map +1 -1
- package/dist/deduplication/deduplication.js +99 -26
- package/dist/deduplication/deduplication.js.map +1 -1
- package/dist/deduplication/retry.d.ts +3 -0
- package/dist/deduplication/retry.d.ts.map +1 -0
- package/dist/deduplication/retry.js +15 -0
- package/dist/deduplication/retry.js.map +1 -0
- package/dist/deduplication/scan.d.ts +2 -0
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +4 -2
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/feedback.d.ts +20 -0
- package/dist/feedback.d.ts.map +1 -0
- package/dist/feedback.js +121 -0
- package/dist/feedback.js.map +1 -0
- package/dist/finding-catalogue.d.ts +11 -0
- package/dist/finding-catalogue.d.ts.map +1 -0
- package/dist/finding-catalogue.js +150 -0
- package/dist/finding-catalogue.js.map +1 -0
- package/dist/findings-client.d.ts +7 -1
- package/dist/findings-client.d.ts.map +1 -1
- package/dist/findings-client.js +55 -10
- package/dist/findings-client.js.map +1 -1
- package/dist/findings-import.d.ts +44 -0
- package/dist/findings-import.d.ts.map +1 -0
- package/dist/findings-import.js +302 -0
- package/dist/findings-import.js.map +1 -0
- package/dist/import-scan.d.ts +27 -0
- package/dist/import-scan.d.ts.map +1 -0
- package/dist/import-scan.js +236 -0
- package/dist/import-scan.js.map +1 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +2 -2
- package/dist/knowledge-base.js.map +1 -1
- package/dist/multiscan.d.ts +2 -0
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +144 -52
- package/dist/multiscan.js.map +1 -1
- package/dist/patch-tui.js +1 -1
- package/dist/patch-tui.js.map +1 -1
- package/dist/publication-events.d.ts.map +1 -1
- package/dist/publication-events.js +7 -2
- package/dist/publication-events.js.map +1 -1
- package/dist/publication-store.d.ts.map +1 -1
- package/dist/publication-store.js +9 -4
- package/dist/publication-store.js.map +1 -1
- package/dist/publication.d.ts +9 -0
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +45 -5
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts +4 -2
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +2 -2
- package/dist/publish.js.map +1 -1
- package/dist/runtime.d.ts +5 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +8 -2
- package/dist/runtime.js.map +1 -1
- package/dist/scan-comparison.d.ts +42 -37
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +535 -161
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +19 -6
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +5 -0
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-logs.d.ts +29 -0
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +36 -5
- package/dist/scan-logs.js.map +1 -1
- package/dist/security-policy-cli.d.ts +39 -0
- package/dist/security-policy-cli.d.ts.map +1 -0
- package/dist/security-policy-cli.js +193 -0
- package/dist/security-policy-cli.js.map +1 -0
- package/dist/security-policy.d.ts +80 -0
- package/dist/security-policy.d.ts.map +1 -0
- package/dist/security-policy.js +672 -0
- package/dist/security-policy.js.map +1 -0
- package/dist/severity-store.d.ts +2 -0
- package/dist/severity-store.d.ts.map +1 -0
- package/dist/severity-store.js +111 -0
- package/dist/severity-store.js.map +1 -0
- package/dist/targets.d.ts +8 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +243 -14
- package/dist/targets.js.map +1 -1
- package/dist/thread-source.d.ts +1 -0
- package/dist/thread-source.d.ts.map +1 -1
- package/dist/thread-source.js +1 -0
- package/dist/thread-source.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/package.json +10 -6
- package/_bundled_plugin/scripts/resolve_security_md.py +0 -158
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ npx @openai/codex-security --version
|
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Use Node.js 22.13.0+ (22.x), 24.x, or 26.x on macOS, Linux, or Windows.
|
|
16
|
-
|
|
16
|
+
Policy drafting, scans, exports, scan history, and saved findings also need Python 3.10+
|
|
17
17
|
(plus `tomli` on Python 3.10).
|
|
18
18
|
|
|
19
19
|
## Run a scan from TypeScript
|
|
@@ -40,7 +40,7 @@ try {
|
|
|
40
40
|
|
|
41
41
|
`result.findings` contains this scan's findings; `repositoryFindings` also
|
|
42
42
|
includes earlier open findings when available. Matching earlier findings can
|
|
43
|
-
make
|
|
43
|
+
make extra model calls; see [Progress and cost](#progress-and-cost).
|
|
44
44
|
|
|
45
45
|
Keep results outside the repository and restrict access: reports can contain
|
|
46
46
|
source code, vulnerability details, and reproduction steps.
|
|
@@ -69,6 +69,10 @@ Pass literal text or a JSON-serializable object as `finding`, not a file path.
|
|
|
69
69
|
Validation uses the client's settings and credentials without changing
|
|
70
70
|
repository files or adding a scan to history.
|
|
71
71
|
|
|
72
|
+
To disable Codex usage analytics and built-in metrics, create the client with
|
|
73
|
+
`new CodexSecurity({ codexOverrides: { analytics: { enabled: false } } })`.
|
|
74
|
+
This setting also applies to scans run by the same client.
|
|
75
|
+
|
|
72
76
|
Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,
|
|
73
77
|
or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.
|
|
74
78
|
`reportable` may rely on static analysis; `deferred` means insufficient evidence.
|
|
@@ -182,7 +186,7 @@ For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin
|
|
|
182
186
|
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
|
|
183
187
|
```
|
|
184
188
|
|
|
185
|
-
Environment API keys apply to the current
|
|
189
|
+
Environment API keys apply to the current command; only `login --with-api-key`
|
|
186
190
|
saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
|
|
187
191
|
Access-token environment variables are not scan API keys.
|
|
188
192
|
|
|
@@ -215,6 +219,15 @@ credentials, and the default AWS credential chain. Set `AWS_REGION` and choose
|
|
|
215
219
|
a Bedrock model with `--model`; OpenAI models such as `openai.gpt-5.6-luna`
|
|
216
220
|
support `--max-cost`.
|
|
217
221
|
|
|
222
|
+
Bedrock scans, including Deep Scan workers, default to
|
|
223
|
+
`model_reasoning_summary = "none"` because some Bedrock models reject
|
|
224
|
+
`reasoning.summary`. This leaves reasoning effort unchanged. Explicit summary
|
|
225
|
+
settings in `--codex` overrides or the selected Codex profile take precedence.
|
|
226
|
+
For standard scans on older CLI versions, append
|
|
227
|
+
`--codex 'model_reasoning_summary="none"'` to your scan command if Bedrock
|
|
228
|
+
reports that `reasoning.summary` is unsupported. Deep scans require a CLI
|
|
229
|
+
version that forwards this setting to workers.
|
|
230
|
+
|
|
218
231
|
On Windows, set the API key in PowerShell:
|
|
219
232
|
|
|
220
233
|
```powershell
|
|
@@ -222,11 +235,23 @@ $env:OPENAI_API_KEY = "<your-api-key>"
|
|
|
222
235
|
npx @openai/codex-security scan C:\code\repository
|
|
223
236
|
```
|
|
224
237
|
|
|
225
|
-
Login, logout, and
|
|
238
|
+
Login, logout, scans, validation, patching, and fix verification share a private
|
|
239
|
+
credential home for stored OpenAI credentials, including custom providers with
|
|
240
|
+
`requires_openai_auth = true`:
|
|
226
241
|
`$CODEX_SECURITY_STATE_DIR/codex-home`, or
|
|
227
|
-
`$CODEX_HOME/state/plugins/codex-security/codex-home`.
|
|
228
|
-
|
|
229
|
-
|
|
242
|
+
`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this credential
|
|
243
|
+
home outside the target directory and every enclosing Git worktree, including
|
|
244
|
+
when running a command from a subdirectory. Codex carries
|
|
245
|
+
`cli_auth_credentials_store`, `forced_login_method`, and
|
|
246
|
+
`forced_chatgpt_workspace_id` from the ambient configuration into this home,
|
|
247
|
+
including removing settings that are no longer present in the ambient configuration.
|
|
248
|
+
Each command carries its selected provider into this home. Patching and fix
|
|
249
|
+
verification also synchronize the ambient home's project-trust decisions and
|
|
250
|
+
project-root markers, preserving which project configuration Codex loads.
|
|
251
|
+
They hold the credential-home lock until the app-server thread is ready,
|
|
252
|
+
then release it before model execution.
|
|
253
|
+
Managed-device policies still apply. If this home has no credentials, it imports
|
|
254
|
+
an existing file-based Codex sign-in. Logout disables
|
|
230
255
|
imports until you log in again.
|
|
231
256
|
|
|
232
257
|
Finish operations using older versions before upgrading. Runtime preparation
|
|
@@ -251,19 +276,167 @@ npx @openai/codex-security scan . --auth chatgpt
|
|
|
251
276
|
npx @openai/codex-security scan . --auth api-key
|
|
252
277
|
```
|
|
253
278
|
|
|
279
|
+
`--auth` also works with `validate`, `patch`, and `verify-fix`. These commands
|
|
280
|
+
use the same stored login as `scan`, including a sign-in created with
|
|
281
|
+
`codex-security login --device-auth`:
|
|
282
|
+
|
|
283
|
+
```bash
|
|
284
|
+
npx @openai/codex-security patch OCCURRENCE_ID --auth chatgpt
|
|
285
|
+
npx @openai/codex-security verify-fix OCCURRENCE_ID --auth api-key
|
|
286
|
+
```
|
|
287
|
+
|
|
254
288
|
`--auth chatgpt` ignores environment API keys. `--auth api-key` requires
|
|
255
|
-
`OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`;
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
289
|
+
`OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; noninteractive
|
|
290
|
+
commands prefer `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
|
|
291
|
+
Patch follow-up assessment uses the same selection, and `scan --patch` keeps
|
|
292
|
+
the scan's choice. Environment API keys do not replace the saved login.
|
|
293
|
+
The SDK uses the same `auth` option on `run`, `validate`, and `preflight`.
|
|
294
|
+
Codex may still need ChatGPT credentials to load workspace-managed policies
|
|
295
|
+
when using an API key.
|
|
259
296
|
|
|
260
297
|
Some cybersecurity requests and protected findings require Trusted Access for
|
|
261
298
|
Cyber approval. Apply or check your access at
|
|
262
299
|
[chatgpt.com/cyber](https://chatgpt.com/cyber).
|
|
263
300
|
|
|
301
|
+
## Generate a security policy
|
|
302
|
+
|
|
303
|
+
`policy` drafts `SECURITY.md` guidance for future scans. It does not run a
|
|
304
|
+
vulnerability scan, change application settings, or install the draft in the
|
|
305
|
+
checkout. It uses the scan runtime and authentication, requesting read-only
|
|
306
|
+
access to the selected repository or component and required tools. Network access,
|
|
307
|
+
web search, apps, and MCP servers are disabled. Drafts stay outside the checkout.
|
|
308
|
+
The host resolves inherited guidance once and includes each checked descendant
|
|
309
|
+
policy separately. Descendant policy links must stay within the selected component.
|
|
310
|
+
Inherited and reporting-policy links may also resolve to ancestor `SECURITY.md`
|
|
311
|
+
files or the checkout's `.github/SECURITY.md` and `docs/SECURITY.md`.
|
|
312
|
+
The model cannot read sibling components or Git metadata. Policy turns deny
|
|
313
|
+
access to the resolved Git metadata and markers, including those inside the
|
|
314
|
+
selected source tree, nested bare repositories, and associated alternate object
|
|
315
|
+
stores.
|
|
316
|
+
Policy shell tools inherit only Codex's core environment; custom shell environment
|
|
317
|
+
settings, login shells, and shell snapshots are disabled for these turns.
|
|
318
|
+
Knowledge-base text stays with the private review artifacts during generation
|
|
319
|
+
and is removed afterward.
|
|
320
|
+
|
|
321
|
+
Known limitation: policy preflight and generation currently fail on Unix
|
|
322
|
+
directories with non-UTF-8 names.
|
|
323
|
+
|
|
324
|
+
On macOS, the pinned Codex runtime does not fully enforce write restrictions
|
|
325
|
+
under `/tmp` (including `/private/tmp`). Keep the repository and artifacts outside
|
|
326
|
+
that tree when read-only enforcement is required. See the
|
|
327
|
+
[upstream sandbox limitation](https://github.com/openai/codex/issues/32395).
|
|
328
|
+
|
|
329
|
+
```bash
|
|
330
|
+
npx @openai/codex-security policy .
|
|
331
|
+
npx @openai/codex-security policy . --path services/api
|
|
332
|
+
npx @openai/codex-security policy . --knowledge-base architecture.md --model gpt-5.6-terra --effort high
|
|
333
|
+
npx @openai/codex-security policy . --dry-run --json
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
The repository defaults to the current directory. `--path` selects a component,
|
|
337
|
+
which inherits policies from its Git root, with the closest policy taking
|
|
338
|
+
precedence. Linked worktrees and initialized submodules use their own roots.
|
|
339
|
+
Targets and policy links must stay in the selected checkout, outside Git
|
|
340
|
+
metadata; ancestor links cannot widen a component policy's scope.
|
|
341
|
+
|
|
342
|
+
For an intentional separate Git directory, set `core.worktree` to the checkout's
|
|
343
|
+
absolute path. Use `git worktree repair` for moved linked worktrees.
|
|
344
|
+
|
|
345
|
+
Generation uses three Codex stages: describe the system, build a threat model,
|
|
346
|
+
then draft the policy. The first two documents support review; they are not
|
|
347
|
+
additional approval steps or policies to install.
|
|
348
|
+
In a terminal, it asks about facts the source cannot establish and shows the
|
|
349
|
+
exact diff. If both ChatGPT and API-key credentials are available, it asks which
|
|
350
|
+
to use; `--auth chatgpt` or `--auth api-key` selects one explicitly.
|
|
351
|
+
|
|
352
|
+
| Invocation | Calls Codex? | Result |
|
|
353
|
+
| ---------------------------- | ------------ | ----------------------------------------------------------------------- |
|
|
354
|
+
| `policy .` | Yes | Ask owner questions, save documents, and preview the draft. |
|
|
355
|
+
| `policy . --headless --json` | Yes | Save documents without prompts and return their paths and review notes. |
|
|
356
|
+
| `policy . --format md` | Yes | Generate a draft and write its Markdown to stdout. |
|
|
357
|
+
| `policy . --dry-run --json` | No | Check local inputs and show the resolved target and settings. |
|
|
358
|
+
|
|
359
|
+
None of these commands installs `SECURITY.md` in the repository. Output formats
|
|
360
|
+
change presentation; they do not turn generation into a saved-draft read.
|
|
361
|
+
|
|
362
|
+
### Review the draft
|
|
363
|
+
|
|
364
|
+
Review the saved `SECURITY.md` before copying it to the reported target. Check
|
|
365
|
+
links from `.github/SECURITY.md` or `docs/SECURITY.md`: copying can change their
|
|
366
|
+
guidance too. Preserve reporting instructions and obtain owner approval for
|
|
367
|
+
exclusions, accepted risks, and severity decisions. Later scans read this policy.
|
|
368
|
+
|
|
369
|
+
Generation and preview check for changes to the selected or inherited policies.
|
|
370
|
+
If governing guidance changes during generation, completed documents remain for
|
|
371
|
+
inspection, but no completed-draft manifest is written. Other source files are not
|
|
372
|
+
frozen; regenerate if relevant source or neighboring policies change.
|
|
373
|
+
A failed terminal preview reports a warning and the saved draft paths. Explicit
|
|
374
|
+
output formats return the draft directly without running a diff preview.
|
|
375
|
+
|
|
376
|
+
Use `--headless` or an explicit output format to skip questions. Unanswered
|
|
377
|
+
questions remain in the review notes. Drafts default to the Codex Security state
|
|
378
|
+
directory; `--output-dir` selects an empty directory outside every enclosing
|
|
379
|
+
Git checkout and its Git metadata.
|
|
380
|
+
|
|
381
|
+
```bash
|
|
382
|
+
npx @openai/codex-security policy . --path services/api \
|
|
383
|
+
--headless --output-dir /path/outside/repository/api-policy --json
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
The artifact directory contains:
|
|
387
|
+
|
|
388
|
+
| File | Purpose |
|
|
389
|
+
| ---------------------- | --------------------------------------------------------- |
|
|
390
|
+
| `SECURITY.md` | Editable policy draft. |
|
|
391
|
+
| `THREAT_MODEL.md` | Detailed threat model with source references. |
|
|
392
|
+
| `project-spec.md` | System description and security boundaries. |
|
|
393
|
+
| `previous-SECURITY.md` | Original policy used for the diff. |
|
|
394
|
+
| `policy-draft.json` | Target, policy hashes, revision, model, and review notes. |
|
|
395
|
+
|
|
396
|
+
Keep supporting documents private until reviewed for disclosure. A generated
|
|
397
|
+
threat scenario is neither owner approval nor a confirmed vulnerability.
|
|
398
|
+
|
|
399
|
+
`--format md` writes the draft to stdout. `--json` returns paths, review notes,
|
|
400
|
+
status, and estimated cost. Global filters and token options work with these
|
|
401
|
+
formats. Progress goes to stderr. `--full-output` reports failures with
|
|
402
|
+
`ok: false`. `--max-cost` applies to the whole generation. If a stage cannot
|
|
403
|
+
inspect required source evidence, generation stops and preserves completed
|
|
404
|
+
documents. Fix the reported problem and use a new output directory to retry.
|
|
405
|
+
|
|
406
|
+
### Generate a policy from TypeScript
|
|
407
|
+
|
|
408
|
+
```ts
|
|
409
|
+
import { CodexSecurity } from "@openai/codex-security";
|
|
410
|
+
|
|
411
|
+
const security = new CodexSecurity();
|
|
412
|
+
try {
|
|
413
|
+
const draft = await security.generatePolicy("/path/to/repository", {
|
|
414
|
+
path: "services/api",
|
|
415
|
+
knowledgeBasePaths: ["/path/to/architecture.md"],
|
|
416
|
+
onStage: (stage) => console.error(stage),
|
|
417
|
+
});
|
|
418
|
+
|
|
419
|
+
console.log(await security.previewPolicy(draft));
|
|
420
|
+
// Open draft.draftPath in an editor to review the saved policy.
|
|
421
|
+
} finally {
|
|
422
|
+
await security.close();
|
|
423
|
+
}
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
`preflightPolicy()` checks local inputs without starting Codex.
|
|
427
|
+
`previewPolicy()` previews the supplied in-memory draft, uses the client's Python
|
|
428
|
+
setting, and makes terminal control characters visible. Editing the saved file
|
|
429
|
+
does not change that object. The standalone `securityPolicyDiff()` returns a raw diff
|
|
430
|
+
for files or other non-terminal uses; pass an interpreter explicitly if needed.
|
|
431
|
+
`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
|
|
432
|
+
`maxCostUsd`, `signal`, and progress and cost callbacks. An optional
|
|
433
|
+
`answerQuestions` callback receives each group of up to three owner questions
|
|
434
|
+
and a cancellation signal. Without it, the questions remain unresolved.
|
|
435
|
+
|
|
264
436
|
## CLI
|
|
265
437
|
|
|
266
438
|
```bash
|
|
439
|
+
npx @openai/codex-security policy . --path services/api
|
|
267
440
|
npx @openai/codex-security scan .
|
|
268
441
|
npx @openai/codex-security scan /path/to/repository --path src --path tests
|
|
269
442
|
npx @openai/codex-security scan /path/to/repository --diff origin/main --json
|
|
@@ -299,6 +472,39 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
|
|
|
299
472
|
`1` if a completed scan finds high or critical issues. Incomplete scans exit
|
|
300
473
|
with `2`, writing available results to stdout and a coverage warning to stderr.
|
|
301
474
|
|
|
475
|
+
### Import findings as a saved scan
|
|
476
|
+
|
|
477
|
+
Import an existing findings CSV or JSON file into local scan history and SQLite:
|
|
478
|
+
|
|
479
|
+
```bash
|
|
480
|
+
codex-security scan import --csv /path/to/findings.csv
|
|
481
|
+
codex-security scan import --json /path/to/findings.json --format json
|
|
482
|
+
codex-security scan import --csv /path/to/findings.csv --dry-run
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
Supply exactly one of `--csv PATH` or `--json PATH`. CSV uses the existing
|
|
486
|
+
[findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv),
|
|
487
|
+
including the optional `candidate_id` column. JSON accepts a complete
|
|
488
|
+
`codex-security.findings` document or `{ "findings": [...] }`, with each finding
|
|
489
|
+
matching the existing findings schema. On `scan import`, `--json` selects the
|
|
490
|
+
input file; use `--format json` for JSON output. Other commands retain their
|
|
491
|
+
existing `--json` output flag. The selected input must be a regular file, and its
|
|
492
|
+
path must not traverse symbolic links or directory junctions. Use the direct
|
|
493
|
+
filesystem path when the file or a parent directory is linked.
|
|
494
|
+
|
|
495
|
+
Each import creates one completed scan using the configured
|
|
496
|
+
`CODEX_SECURITY_STATE_DIR`. The target is a retained copy of the input dataset,
|
|
497
|
+
independent of the current repository. Every source occurrence remains a separate
|
|
498
|
+
finding, including duplicate reports. Original identifiers are preserved in
|
|
499
|
+
`extensions.import`; the original file is sealed under `artifacts/import/`.
|
|
500
|
+
JSON writeup paths are retained as source metadata without reading external files.
|
|
501
|
+
|
|
502
|
+
Completion means the import finished. Coverage is unknown and the report states
|
|
503
|
+
that no security analysis was performed. Importing requires no model calls or
|
|
504
|
+
authentication. `--dry-run` validates without saving a scan. `--output-dir` and
|
|
505
|
+
`--archive-existing` control saved output, and `scans rerun SCAN_ID` reimports the
|
|
506
|
+
retained input.
|
|
507
|
+
|
|
302
508
|
### Generate mock scan results
|
|
303
509
|
|
|
304
510
|
Use `--mock` to populate a Standard scan with synthetic test data in seconds,
|
|
@@ -380,6 +586,14 @@ npx @openai/codex-security scan-components /path/to/project \
|
|
|
380
586
|
--output-dir /path/outside/project/results
|
|
381
587
|
```
|
|
382
588
|
|
|
589
|
+
For large repositories, automatic planning splits inventories into separate calls
|
|
590
|
+
that fit Codex's input character limit. It preserves directory boundaries where
|
|
591
|
+
possible and subdivides oversized packages and flat directories as needed. Each
|
|
592
|
+
call uses a fresh context and can select only paths within its batch. Omitted
|
|
593
|
+
files are retained in `Other files` components within those same boundaries.
|
|
594
|
+
Large repositories can therefore require more planning calls and produce more
|
|
595
|
+
components. Review or edit the saved plan before scanning with `--components-file`.
|
|
596
|
+
|
|
383
597
|
Components use repository-relative paths:
|
|
384
598
|
|
|
385
599
|
```json
|
|
@@ -476,7 +690,7 @@ approvals_reviewer = "auto_review"
|
|
|
476
690
|
cli_auth_credentials_store = "auto"
|
|
477
691
|
model = "gpt-5.6-sol"
|
|
478
692
|
model_reasoning_effort = "xhigh"
|
|
479
|
-
model_reasoning_summary = "detailed"
|
|
693
|
+
model_reasoning_summary = "detailed" # "none" for amazon-bedrock
|
|
480
694
|
show_raw_agent_reasoning = true
|
|
481
695
|
|
|
482
696
|
[features]
|
|
@@ -515,8 +729,32 @@ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
|
|
|
515
729
|
stay enabled: `agents.max_threads` and
|
|
516
730
|
`features.multi_agent_v2.enabled=false` are rejected.
|
|
517
731
|
|
|
518
|
-
`validate` and `
|
|
519
|
-
`model_reasoning_effort` keys in `--codex`, but no
|
|
732
|
+
`validate`, `patch`, and `verify-fix` accept `--auth`, `--effort`, and the `model`,
|
|
733
|
+
`model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
|
|
734
|
+
other runtime overrides.
|
|
735
|
+
|
|
736
|
+
Use `--codex 'analytics.enabled=false'` to disable Codex usage analytics and
|
|
737
|
+
built-in metrics for a command:
|
|
738
|
+
|
|
739
|
+
```bash
|
|
740
|
+
npx @openai/codex-security validate "Candidate finding" --codex 'analytics.enabled=false'
|
|
741
|
+
npx @openai/codex-security patch "Security issue" --codex 'analytics.enabled=false'
|
|
742
|
+
npx @openai/codex-security verify-fix "Security issue" --codex 'analytics.enabled=false'
|
|
743
|
+
```
|
|
744
|
+
|
|
745
|
+
The same setting works for `scan` and `bulk-scan`. An explicit setting is
|
|
746
|
+
preserved when `scan --patch` starts remediation and when
|
|
747
|
+
`patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
|
|
748
|
+
is also accepted; omitting the setting preserves the command's existing
|
|
749
|
+
configuration and Codex defaults. Validation ignores user configuration.
|
|
750
|
+
For stored OpenAI credentials, patching and verification read configuration
|
|
751
|
+
from the shared credential home. API-key commands and custom providers that use their own credentials retain
|
|
752
|
+
their ambient Codex configuration. Patching and verification preserve project trust from the
|
|
753
|
+
ambient home; explicit `--codex` settings apply to the command and its
|
|
754
|
+
patch-risk assessment.
|
|
755
|
+
|
|
756
|
+
This setting does not control explicitly configured OpenTelemetry log or trace
|
|
757
|
+
exporters, authentication, integrations, or CLI update checks.
|
|
520
758
|
|
|
521
759
|
See [Local security model](#local-security-model) for approval and filesystem
|
|
522
760
|
restrictions.
|
|
@@ -557,10 +795,28 @@ Interactive scans show full-screen progress; CI, redirected output, and
|
|
|
557
795
|
diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for
|
|
558
796
|
sensitive information before sharing them.
|
|
559
797
|
|
|
798
|
+
The token summary shows uncached input, cache reads, cache writes, output,
|
|
799
|
+
and total tokens. Total tokens include all input plus output; cache reads and
|
|
800
|
+
writes are subsets of input, not extra tokens. When cache-write usage is missing,
|
|
801
|
+
the summary shows uncached input and cache writes as unavailable.
|
|
802
|
+
The final summary preserves missing-data information from a matching session log.
|
|
803
|
+
If the Codex runtime converts an omitted count to zero before recording it, the
|
|
804
|
+
CLI cannot distinguish that zero from reported usage.
|
|
805
|
+
|
|
560
806
|
JSON results, scan history, and bulk-scan receipts record the model, tokens,
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
807
|
+
estimated cost, and `cost.pricing`: the price source, verification date, processing
|
|
808
|
+
tier, context category, and rates in USD per million tokens. Estimates use
|
|
809
|
+
[standard, short-context API prices](https://developers.openai.com/api/docs/pricing),
|
|
810
|
+
including cache reads and writes. They exclude long-context and other processing
|
|
811
|
+
tier adjustments, fees, and surcharges. GPT-5.5 and GPT-6 Astra are supported;
|
|
812
|
+
models without known prices show an unavailable estimate.
|
|
813
|
+
|
|
814
|
+
For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
|
|
815
|
+
`cacheWriteInputTokensReported: false` means at least one included usage record
|
|
816
|
+
did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
|
|
817
|
+
In that case, the estimate prices unclassified input at the ordinary input rate;
|
|
818
|
+
it may undercount cache-write charges. Older saved records lack this distinction
|
|
819
|
+
and the saved pricing basis.
|
|
564
820
|
|
|
565
821
|
`--max-cost USD` stops the scan and its workers when estimated cost exceeds
|
|
566
822
|
the limit, though in-flight requests can finish above it. If deep-scan
|
|
@@ -568,6 +824,10 @@ discovery has finished, the scan returns a sealed partial report without more
|
|
|
568
824
|
model calls and lists unvalidated candidates as follow-up work. Bulk scans
|
|
569
825
|
apply the limit per repository attempt.
|
|
570
826
|
|
|
827
|
+
With `--max-cost`, automatic finding-history matching makes at most one extra
|
|
828
|
+
model call. If it needs more context, the completed scan is kept and a warning
|
|
829
|
+
directs you to run `scans match --all` explicitly.
|
|
830
|
+
|
|
571
831
|
For a single scan in the interactive dashboard, reaching 80% of the limit
|
|
572
832
|
offers a higher **total** USD limit. Enter a larger amount to approve it, or
|
|
573
833
|
press Enter with an empty input or Escape to keep the current limit. The scan
|
|
@@ -618,8 +878,45 @@ even after a failed or incomplete scan, but not after cancellation or a
|
|
|
618
878
|
cost-limit stop.
|
|
619
879
|
|
|
620
880
|
`--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending
|
|
621
|
-
repository per invocation.
|
|
622
|
-
|
|
881
|
+
repository per invocation. Rerunning the command continues the campaign, skips
|
|
882
|
+
completed results, and starts new attempts for pending repositories. If an
|
|
883
|
+
attempt directory is occupied, that repository stops before replacing its
|
|
884
|
+
checkout and the command recommends `--recover`.
|
|
885
|
+
|
|
886
|
+
#### Recovering failed or interrupted bulk scans
|
|
887
|
+
|
|
888
|
+
Use the original CSV, output directory, and campaign options with `--recover`:
|
|
889
|
+
|
|
890
|
+
```bash
|
|
891
|
+
npx @openai/codex-security bulk-scan repositories.csv \
|
|
892
|
+
--output-dir /path/outside/repositories/security-scans --recover
|
|
893
|
+
```
|
|
894
|
+
|
|
895
|
+
Recovery requires an existing campaign with a matching manifest. It skips
|
|
896
|
+
completed results, including partial coverage, and repositories never started.
|
|
897
|
+
For each failed or interrupted repository, it checks the latest attempt:
|
|
898
|
+
|
|
899
|
+
- A sealed scan is recorded in `results.jsonl` without scanning again.
|
|
900
|
+
- An eligible running Deep Scan resumes its original session, keeping its scan
|
|
901
|
+
ID, completed workers, artifacts, saved settings, and accumulated cost.
|
|
902
|
+
- A failed, canceled, or otherwise unavailable scan starts a new attempt at the
|
|
903
|
+
CSV's pinned revision. Attempt numbers account for both receipts and existing
|
|
904
|
+
directories. Old artifacts and checkouts are preserved; new attempts use
|
|
905
|
+
`recovery-checkouts/<id>/attempt-<n>`.
|
|
906
|
+
|
|
907
|
+
`--workers` still defaults to `4`; `--max-attempts` defaults to one recovery or
|
|
908
|
+
new attempt per repository. A resume connection failure stops that repository
|
|
909
|
+
for this invocation instead of starting another scan. Other repositories
|
|
910
|
+
continue. Failed and interrupted recovery checkouts remain available for a later
|
|
911
|
+
`--recover`; fresh completed checkouts are removed after recording the result.
|
|
912
|
+
If a reboot interrupted a receipt write, its unfinished tail is saved beside
|
|
913
|
+
`results.jsonl` as `results.jsonl.interrupted-<id>` before appending valid records.
|
|
914
|
+
|
|
915
|
+
Same-scan resume requires the original checkout, session logs, and Codex Security
|
|
916
|
+
state directory. Recovery does not reconstruct deleted checkpoints or fix the
|
|
917
|
+
underlying cause of execution failures. New attempts incur new scan costs.
|
|
918
|
+
Any remaining failures or partial coverage keep exit code `2`.
|
|
919
|
+
`bulk-scan --help` lists all options.
|
|
623
920
|
|
|
624
921
|
### Custom validation
|
|
625
922
|
|
|
@@ -826,6 +1123,158 @@ Options include `projectId`, `skipExisting`, `linearApiKey` for direct API
|
|
|
826
1123
|
publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts
|
|
827
1124
|
the same destination options for a read-only check.
|
|
828
1125
|
|
|
1126
|
+
### Classify finding severity
|
|
1127
|
+
|
|
1128
|
+
Classify findings after a scan or dedupe without repeating discovery or changing
|
|
1129
|
+
the original severity, evidence, or sealed scan artifacts:
|
|
1130
|
+
|
|
1131
|
+
```bash
|
|
1132
|
+
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md --json
|
|
1133
|
+
codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
|
|
1134
|
+
codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
1135
|
+
```
|
|
1136
|
+
|
|
1137
|
+
`--scan` accepts a saved scan ID, unique prefix, or `latest` for the current
|
|
1138
|
+
repository, matching `dedupe` and `publish scan`. `--scan-dir` accepts an external
|
|
1139
|
+
completed scan without requiring local history. Supply exactly one selector.
|
|
1140
|
+
Omitting `--rubric` inherits each finding's existing severity without a model call.
|
|
1141
|
+
|
|
1142
|
+
`--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
|
|
1143
|
+
to provide supporting architecture, deployment, or business context. Both accept
|
|
1144
|
+
the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
|
|
1145
|
+
Rubric classification uses the full supplied report and context in a separate
|
|
1146
|
+
read-only Codex turn per finding, without source inspection, tools, or new
|
|
1147
|
+
validation. `--model` and `--effort` select the classification model and reasoning
|
|
1148
|
+
effort; otherwise Codex's configured model and the helper's medium effort apply.
|
|
1149
|
+
|
|
1150
|
+
The result contains one assessment per selected finding:
|
|
1151
|
+
|
|
1152
|
+
- `decision`: `assessed` or `excluded`; policy exclusions do not become Low.
|
|
1153
|
+
- `level`: `critical`, `high`, `medium`, `low`, or `informational`; null for exclusions.
|
|
1154
|
+
- `rubricLabel`: the policy's original label, such as `URGENT`, normalized to
|
|
1155
|
+
`critical`; null for inherited severity or exclusions.
|
|
1156
|
+
- `rationale`, separate `confidence`, and `reviewTrigger` describing a missing
|
|
1157
|
+
fact that would change the classification. Inherited severity has no new
|
|
1158
|
+
classification-confidence judgment.
|
|
1159
|
+
- `findingId`, `occurrenceId`, and `inputSha256` binding the assessment to the
|
|
1160
|
+
report. Top-level metadata includes `assessedAt`, `rubricSha256`, and
|
|
1161
|
+
`knowledgeBaseSha256` for the supplied policy and context snapshots.
|
|
1162
|
+
|
|
1163
|
+
Scan classification saves each successful finding immediately in the local
|
|
1164
|
+
workbench SQLite database. Rerunning skips assessments with matching finding
|
|
1165
|
+
evidence, rubric, and knowledge-base hashes, including exclusions, and returns
|
|
1166
|
+
both reused and newly generated assessments. Changed inputs are classified again.
|
|
1167
|
+
Use `--reprocess` to rerun every selected finding regardless of its saved
|
|
1168
|
+
assessment; each row is replaced only after its new assessment succeeds. A failed
|
|
1169
|
+
or canceled run keeps completed checkpoints, so a normal retry resumes missing
|
|
1170
|
+
work. Changing only the model or effort requires `--reprocess`.
|
|
1171
|
+
|
|
1172
|
+
SQLite is authoritative. A successful run also exports the complete selected
|
|
1173
|
+
result to `severity-classification.json` alongside the sealed artifacts. The file
|
|
1174
|
+
is replaced atomically and is not read for reuse or publication. The scan's
|
|
1175
|
+
original findings and severity are unchanged. The database stores the requested
|
|
1176
|
+
selection and policy/context hashes; publication rejects an incomplete selection
|
|
1177
|
+
or assessments whose inputs no longer match. Rubric documents are read at
|
|
1178
|
+
classification time, not again at publication time.
|
|
1179
|
+
|
|
1180
|
+
```bash
|
|
1181
|
+
codex-security classify-severity --scan latest --rubric /path/to/policy.md --reprocess
|
|
1182
|
+
```
|
|
1183
|
+
|
|
1184
|
+
Use repeatable `--finding-id ID` to classify a selected set, such as the
|
|
1185
|
+
`uniqueFindingIds` returned by dedupe. With a saved classification, Linear
|
|
1186
|
+
publication defaults to that selection, omits excluded records, and uses assessed
|
|
1187
|
+
severity for issue priority and title. The description retains original scan
|
|
1188
|
+
severity and adds classification reasoning. Without a saved classification,
|
|
1189
|
+
publication retains its existing severity mapping and selection behavior.
|
|
1190
|
+
Publication rejects assessments whose IDs or evidence hashes no longer match.
|
|
1191
|
+
|
|
1192
|
+
```bash
|
|
1193
|
+
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
|
|
1194
|
+
--finding-id FINDING_ID --json
|
|
1195
|
+
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
|
|
1196
|
+
--dry-run --json
|
|
1197
|
+
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
|
|
1198
|
+
--skip-existing --json
|
|
1199
|
+
```
|
|
1200
|
+
|
|
1201
|
+
`publish scan --to linear` also accepts repeatable `--finding-id ID` to select a
|
|
1202
|
+
subset directly. If a classification exists, every explicitly selected finding
|
|
1203
|
+
must have an assessment. Classification does not change existing Linear tickets;
|
|
1204
|
+
`--skip-existing` preserves recorded tickets and any human priority edits. It
|
|
1205
|
+
retains the existing limitations around unrecorded or concurrent publications.
|
|
1206
|
+
|
|
1207
|
+
The SDK exposes the same operations:
|
|
1208
|
+
|
|
1209
|
+
```ts
|
|
1210
|
+
import {
|
|
1211
|
+
classifySeverity,
|
|
1212
|
+
classifyScanSeverity,
|
|
1213
|
+
classifyScanDirectorySeverity,
|
|
1214
|
+
publishScan,
|
|
1215
|
+
} from "@openai/codex-security";
|
|
1216
|
+
|
|
1217
|
+
// Supplied reports from any source: returns an assessment without writing files.
|
|
1218
|
+
const classification = await classifySeverity(findings, {
|
|
1219
|
+
rubricPath: "/path/to/policy.md",
|
|
1220
|
+
knowledgeBasePaths: ["/path/to/context.md"],
|
|
1221
|
+
});
|
|
1222
|
+
|
|
1223
|
+
// Saved IDs (including prefixes/latest), or sealed directories; saves an assessment.
|
|
1224
|
+
await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
|
|
1225
|
+
await classifyScanDirectorySeverity(scanDirectory, {
|
|
1226
|
+
rubricPath: "/path/to/policy.md",
|
|
1227
|
+
findingIds: dedupeResult.uniqueFindingIds,
|
|
1228
|
+
});
|
|
1229
|
+
|
|
1230
|
+
await publishScan(scanDirectory, {
|
|
1231
|
+
destination: "linear",
|
|
1232
|
+
teamId: "TEAM_ID",
|
|
1233
|
+
skipExisting: true,
|
|
1234
|
+
});
|
|
1235
|
+
|
|
1236
|
+
// Alternatively supply a classification directly, without a saved assessment.
|
|
1237
|
+
await publishScan(scanDirectory, {
|
|
1238
|
+
destination: "linear",
|
|
1239
|
+
teamId: "TEAM_ID",
|
|
1240
|
+
classification,
|
|
1241
|
+
findingIds: classification.assessments.map(({ findingId }) => findingId),
|
|
1242
|
+
dryRun: true,
|
|
1243
|
+
});
|
|
1244
|
+
```
|
|
1245
|
+
|
|
1246
|
+
`classifySeverity` accepts reports with `findingId`, `title`, and `summary`, plus
|
|
1247
|
+
their available evidence and metadata. Original `severity` and `occurrenceId`
|
|
1248
|
+
may be absent for imported reports; reports without severity require a rubric.
|
|
1249
|
+
`classifySeverity` remains an in-memory operation without database persistence.
|
|
1250
|
+
The scan wrappers use the local state database (also for external scan
|
|
1251
|
+
directories), accept `reprocess: true`, and accept `findingIds: []` as an
|
|
1252
|
+
intentionally empty selection. Rows outside the selected set are retained.
|
|
1253
|
+
Use the same `CODEX_SECURITY_STATE_DIR` for classification and publication.
|
|
1254
|
+
JSON exports from versions without database checkpoints must be reclassified
|
|
1255
|
+
once before they can be reused.
|
|
1256
|
+
Pass `signal` to cancel any classification operation. Keep human overrides in the
|
|
1257
|
+
calling workflow or issue tracker; assessments remain separate recommendations.
|
|
1258
|
+
|
|
1259
|
+
### Feedback
|
|
1260
|
+
|
|
1261
|
+
Send a problem report to OpenAI and share the returned feedback ID with support:
|
|
1262
|
+
|
|
1263
|
+
```sh
|
|
1264
|
+
codex-security feedback --reason "The scan stopped before it finished"
|
|
1265
|
+
codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs
|
|
1266
|
+
```
|
|
1267
|
+
|
|
1268
|
+
Without an ID, `feedback` selects the most recently started scan in the current
|
|
1269
|
+
repository, including active or failed scans. If there are no saved scans, it sends
|
|
1270
|
+
a general report. The report includes your description, version details, and the selected
|
|
1271
|
+
scan and session IDs. Add `--json` for structured output.
|
|
1272
|
+
|
|
1273
|
+
Logs are off by default. `--include-logs` uploads Codex diagnostics and saved scan
|
|
1274
|
+
and worker activity. These can contain source code, prompts, findings, tool
|
|
1275
|
+
output, and other sensitive data. Only include logs you can share with OpenAI.
|
|
1276
|
+
The command uses Codex's feedback service and respects `feedback.enabled = false`.
|
|
1277
|
+
|
|
829
1278
|
### Scan history and reruns
|
|
830
1279
|
|
|
831
1280
|
Commands default to the current repository. Select scans by full ID or a
|
|
@@ -836,6 +1285,7 @@ unique prefix of at least eight characters.
|
|
|
836
1285
|
| `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
|
|
837
1286
|
| `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |
|
|
838
1287
|
| `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |
|
|
1288
|
+
| `scans resume SCAN_ID` | Resume an interrupted Deep Scan in its original session and output directory. |
|
|
839
1289
|
| `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |
|
|
840
1290
|
| `scans match BEFORE AFTER` | Link findings with the same root cause. |
|
|
841
1291
|
| `scans match --all` | Match completed scans across the repository's worktrees and clones. |
|
|
@@ -843,12 +1293,87 @@ unique prefix of at least eight characters.
|
|
|
843
1293
|
| `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |
|
|
844
1294
|
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |
|
|
845
1295
|
|
|
1296
|
+
#### Resuming an interrupted Deep Scan
|
|
1297
|
+
|
|
1298
|
+
After the CLI process or host stops unexpectedly, find the scan and rejoin it:
|
|
1299
|
+
|
|
1300
|
+
```bash
|
|
1301
|
+
npx @openai/codex-security scans list --scan-root /path/to/security-scans
|
|
1302
|
+
npx @openai/codex-security scans resume SCAN_ID
|
|
1303
|
+
```
|
|
1304
|
+
|
|
1305
|
+
The scan must still be `running`, with its original checkout, output directory,
|
|
1306
|
+
and owning Codex session available in the same Codex Security state directory.
|
|
1307
|
+
The checkout's identity, revision, and contents must match the saved target.
|
|
1308
|
+
Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
|
|
1309
|
+
|
|
1310
|
+
Resume uses the saved configuration and instructions with the installed plugin.
|
|
1311
|
+
New scans save the explicit safety identifier and post-scan prompt contents.
|
|
1312
|
+
Single-scan resume restores them even if the prompt file changes or disappears.
|
|
1313
|
+
Older records that did not save these values cannot reconstruct them. Bulk
|
|
1314
|
+
recovery still requires matching campaign inputs and options; it uses the supplied
|
|
1315
|
+
post-scan prompt when the scan has no saved prompt.
|
|
1316
|
+
It keeps the scan ID, completed workers, artifacts, and accumulated session cost.
|
|
1317
|
+
The existing coordinator recovers interrupted workers after its lease expires.
|
|
1318
|
+
If discovery finished before the interruption, resume completes and seals the
|
|
1319
|
+
same scan. No archiving or new attempt directory is needed. A failed connection
|
|
1320
|
+
leaves the existing scan available for another resume attempt.
|
|
1321
|
+
|
|
1322
|
+
Compatible saved scans can resume after a plugin update. Already-sealed results
|
|
1323
|
+
keep their original producer version and contents when completion is recorded.
|
|
1324
|
+
Unsupported or invalid sealed artifacts are rejected before resuming, preserving
|
|
1325
|
+
the saved scan state and files.
|
|
1326
|
+
|
|
1327
|
+
For bulk campaigns, use [`bulk-scan --recover`](#recovering-failed-or-interrupted-bulk-scans)
|
|
1328
|
+
to recover eligible attempts and update `results.jsonl`. Individual `scans resume`
|
|
1329
|
+
does not update campaign receipts.
|
|
1330
|
+
|
|
1331
|
+
#### Matching saved scans
|
|
1332
|
+
|
|
846
1333
|
Matching requires sealed artifacts and reuses saved matches unless you pass
|
|
847
1334
|
`--force`. Comparisons classify findings as new, persisting, reopened, resolved,
|
|
848
1335
|
or unknown. Missing findings aren't resolved if the later scan is incomplete
|
|
849
1336
|
or excludes their original scope. With one ID, `scans compare` compares it
|
|
850
1337
|
to the latest completed scan.
|
|
851
1338
|
|
|
1339
|
+
Use `scans match --all --force` to rebuild comparisons chronologically while
|
|
1340
|
+
retaining stable finding identities. Ctrl-C keeps comparisons already saved.
|
|
1341
|
+
Only high-confidence duplicates are grouped; uncertain and independently
|
|
1342
|
+
related findings stay separate. Matching preserves triage and sealed artifacts.
|
|
1343
|
+
|
|
1344
|
+
Codex is called only when a new decision is needed, using existing authentication.
|
|
1345
|
+
Scans without sealed artifacts are skipped, but their confirmed links can still
|
|
1346
|
+
be reused. Older custom plugins save confirmed and uncertain matches; use the
|
|
1347
|
+
bundled plugin for related links and large comparisons.
|
|
1348
|
+
|
|
1349
|
+
SDK callers can compare findings without saving a workbench comparison:
|
|
1350
|
+
|
|
1351
|
+
```ts
|
|
1352
|
+
import { readFile } from "node:fs/promises";
|
|
1353
|
+
import {
|
|
1354
|
+
matchScanFindings,
|
|
1355
|
+
type FindingsDocument,
|
|
1356
|
+
} from "@openai/codex-security";
|
|
1357
|
+
|
|
1358
|
+
const before = JSON.parse(
|
|
1359
|
+
await readFile("/path/to/earlier-scan/findings.json", "utf8"),
|
|
1360
|
+
) as FindingsDocument;
|
|
1361
|
+
const after = JSON.parse(
|
|
1362
|
+
await readFile("/path/to/later-scan/findings.json", "utf8"),
|
|
1363
|
+
) as FindingsDocument;
|
|
1364
|
+
|
|
1365
|
+
const comparison = await matchScanFindings(
|
|
1366
|
+
{ before: before.findings, after: after.findings },
|
|
1367
|
+
{ workingDirectory: "/path/to/repository" },
|
|
1368
|
+
);
|
|
1369
|
+
console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
|
|
1370
|
+
```
|
|
1371
|
+
|
|
1372
|
+
Pass `knownFindingGroups` to reuse confirmed groups of stable `findingId` values
|
|
1373
|
+
from your store. Results identify the original `occurrenceId` values. Options
|
|
1374
|
+
include model, reasoning effort, `AbortSignal`, and an optional `onProgress`
|
|
1375
|
+
callback whose errors do not interrupt matching.
|
|
1376
|
+
|
|
852
1377
|
History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
853
1378
|
`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and
|
|
854
1379
|
workbench maintain the database and its journal files as the current user.
|
|
@@ -928,8 +1453,8 @@ assessment skill once on the completed patch. The assessment is advisory and
|
|
|
928
1453
|
does not change the patch or its merge state. Human-readable commands print the
|
|
929
1454
|
report after the patch results; saved-finding JSON output returns it as
|
|
930
1455
|
`patchRisk.report` in the same result object. When combined with `--create-pr`,
|
|
931
|
-
the draft pull request body includes only the concise Markdown
|
|
932
|
-
assessment; the validated JSON remains in the command result.
|
|
1456
|
+
the draft pull request or merge request body includes only the concise Markdown
|
|
1457
|
+
summary from the assessment; the validated JSON remains in the command result.
|
|
933
1458
|
|
|
934
1459
|
```bash
|
|
935
1460
|
npx @openai/codex-security validate "Possible SQL injection" --effort high
|
|
@@ -951,11 +1476,25 @@ to select findings and add patch instructions. Results include a `patches`
|
|
|
951
1476
|
entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
|
|
952
1477
|
Verified and already-fixed findings no longer fail `--fail-on-severity`.
|
|
953
1478
|
|
|
954
|
-
`--create-pr` commits generated patch files and opens a draft
|
|
955
|
-
|
|
1479
|
+
`--create-pr` commits generated patch files and opens a draft GitHub pull request
|
|
1480
|
+
with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
|
|
1481
|
+
the appropriate CLI first (`gh auth login` or `glab auth login`). GitLab.com is
|
|
1482
|
+
selected from the `origin` push URL, including SSH URLs and subgroup projects.
|
|
1483
|
+
For self-hosted GitLab, set `GITLAB_HOST` to the host in that URL and authenticate
|
|
1484
|
+
with `glab auth login --hostname HOST`. The existing `GITLAB_URI` and `GL_HOST`
|
|
1485
|
+
aliases are also accepted, in that order after `GITLAB_HOST`. Other hosts retain
|
|
1486
|
+
the GitHub workflow.
|
|
1487
|
+
|
|
1488
|
+
```bash
|
|
1489
|
+
GITLAB_HOST=gitlab.example.com npx @openai/codex-security patch --scan SCAN_ID --create-pr
|
|
1490
|
+
```
|
|
1491
|
+
|
|
1492
|
+
Both providers use the existing `pullRequest: { branch, url }` JSON result.
|
|
1493
|
+
Supplied-issue requests require a clean working tree before patching so
|
|
956
1494
|
existing work is never included. If publication fails, run the printed
|
|
957
1495
|
`patch --resume-pr BRANCH` command in the same repository. It reuses the saved
|
|
958
1496
|
commit without rerunning Codex, but refuses to publish if the branch changed.
|
|
1497
|
+
Use the same GitLab host setting when resuming a self-hosted merge request.
|
|
959
1498
|
|
|
960
1499
|
To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
|
|
961
1500
|
`--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
|
|
@@ -1017,7 +1556,9 @@ checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
|
|
|
1017
1556
|
defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
|
|
1018
1557
|
version, `sha-<commit>` tag, or digest for repeatable deployments.
|
|
1019
1558
|
|
|
1020
|
-
To build from a source checkout
|
|
1559
|
+
To build from a source checkout, first prepare the
|
|
1560
|
+
[universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
|
|
1561
|
+
for that checkout. Then run from the repository root:
|
|
1021
1562
|
|
|
1022
1563
|
```bash
|
|
1023
1564
|
docker build --target scanner -t codex-security:local .
|
|
@@ -1188,14 +1729,32 @@ change scan artifacts.
|
|
|
1188
1729
|
codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
|
|
1189
1730
|
```
|
|
1190
1731
|
|
|
1732
|
+
Deduplication runs up to 8 jobs concurrently by default. Set `--concurrency N`
|
|
1733
|
+
to choose a positive integer, or `--concurrency 1` for serial execution. The SDK
|
|
1734
|
+
equivalent is `concurrency: N`. Candidate neighborhoods are fetched first, with
|
|
1735
|
+
the same concurrency limit. Luna screenings and ready Sol pair reviews then use
|
|
1736
|
+
two queues sharing one worker pool, with at most 8 jobs running in total by
|
|
1737
|
+
default. Each available worker takes a ready job as soon as its current job
|
|
1738
|
+
finishes; it does not wait for a batch to finish.
|
|
1739
|
+
|
|
1740
|
+
A Sol pair review becomes ready once every Luna screening covering that pair
|
|
1741
|
+
has finished and none voted `DISTINCT`. It can run while unrelated Luna
|
|
1742
|
+
screenings continue. Results are combined in input order so completion timing
|
|
1743
|
+
does not change the groups.
|
|
1744
|
+
|
|
1745
|
+
If a job fails after its retries, queued jobs stop and already running jobs
|
|
1746
|
+
finish before the command reports the failure. No groups are posted from an
|
|
1747
|
+
incomplete review. To retain completed reviews across runs, use a
|
|
1748
|
+
`--workflow-id` as described below.
|
|
1749
|
+
|
|
1191
1750
|
The default scope is the saved scan's repository, identified by
|
|
1192
1751
|
`scan.target.targetId` in its manifest. Add `--all-repositories` to search the
|
|
1193
1752
|
entire stored corpus explicitly; the flag defaults to false. The SDK has the
|
|
1194
1753
|
equivalent optional `allRepositories: true` setting. This narrows the previous
|
|
1195
1754
|
preview's implicit all-repository behavior.
|
|
1196
1755
|
|
|
1197
|
-
|
|
1198
|
-
URL. As with `publish scan --scan`, the selector accepts a full ID, unique
|
|
1756
|
+
Provide `--findings-url` and either `--scan` or `--workflow-id`, with no implicit
|
|
1757
|
+
scan or service URL. As with `publish scan --scan`, the scan selector accepts a full ID, unique
|
|
1199
1758
|
prefix, or `latest` for the current repository. The saved scan must be complete
|
|
1200
1759
|
and its sealed artifacts must be available.
|
|
1201
1760
|
|
|
@@ -1204,6 +1763,7 @@ import { deduplicateScan } from "@openai/codex-security";
|
|
|
1204
1763
|
|
|
1205
1764
|
const result = await deduplicateScan("scan_example_001", {
|
|
1206
1765
|
findingsUrl: "http://127.0.0.1:3000",
|
|
1766
|
+
// concurrency: 8, // Shared worker limit for Luna and Sol; use 1 for serial.
|
|
1207
1767
|
// allRepositories: true, // Omit to search only this scan's repository.
|
|
1208
1768
|
// signal: controller.signal,
|
|
1209
1769
|
});
|
|
@@ -1219,6 +1779,7 @@ import { deduplicateScanDirectory } from "@openai/codex-security";
|
|
|
1219
1779
|
const result = await deduplicateScanDirectory("/path/to/completed-scan", {
|
|
1220
1780
|
repository: "/path/to/repository",
|
|
1221
1781
|
findingsUrl: "http://127.0.0.1:3000",
|
|
1782
|
+
// concurrency: 8,
|
|
1222
1783
|
// expectedScanId: "scan_example_001",
|
|
1223
1784
|
// allRepositories: true,
|
|
1224
1785
|
// signal: controller.signal,
|
|
@@ -1301,8 +1862,9 @@ scan. Existing output-directory and archive safeguards still apply to scan retri
|
|
|
1301
1862
|
|
|
1302
1863
|
Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
|
|
1303
1864
|
scan selector must identify that same scan. A workflow can also begin at custom
|
|
1304
|
-
publication of a completed scan.
|
|
1305
|
-
the approved source checkout
|
|
1865
|
+
publication of a completed scan. The CLI and `deduplicateScan` require local scan
|
|
1866
|
+
history to locate the approved source checkout; `deduplicateScanDirectory` uses
|
|
1867
|
+
the supplied repository. For a workflow, dedupe first completes publication
|
|
1306
1868
|
if its receipt is missing. `--all-repositories` retains its existing default of
|
|
1307
1869
|
false. Changing a workflow's scan, destination, or bound scope is an error: choose
|
|
1308
1870
|
a different workflow ID. Use one coordinating process per workflow.
|
|
@@ -1322,6 +1884,12 @@ A completed `dedupe --workflow-id` returns its saved result without repeating
|
|
|
1322
1884
|
reviews or group writes. A publication whose acknowledgement was lost is retried
|
|
1323
1885
|
using the service's existing idempotent upsert.
|
|
1324
1886
|
|
|
1887
|
+
Concurrent jobs save their validated reviews independently. Resuming with the
|
|
1888
|
+
same workflow ID reuses completed reviews and retries unfinished jobs. The
|
|
1889
|
+
concurrency setting is not part of a review's checkpoint identity, so it is safe
|
|
1890
|
+
to change `--concurrency` when resuming. Cancellation stops active reviews and
|
|
1891
|
+
leaves their completed checkpoints available for the next run.
|
|
1892
|
+
|
|
1325
1893
|
Each validated screening and pair review is checkpointed locally,
|
|
1326
1894
|
including DISTINCT decisions. Screening checkpoints retain pair recommendations
|
|
1327
1895
|
and rationales under host-assigned pair slots bound to the original records.
|
|
@@ -1331,8 +1899,17 @@ must satisfy the Finding schema and preserve the canonical finding ID. Validatio
|
|
|
1331
1899
|
still happens through `review_validator.submit_decisions`; invalid submissions
|
|
1332
1900
|
are corrected in the same review conversation. A completed turn without an
|
|
1333
1901
|
accepted submission receives one corrective turn in that same conversation.
|
|
1334
|
-
|
|
1335
|
-
|
|
1902
|
+
If formatting remains invalid, the job retries in a fresh review session.
|
|
1903
|
+
Explicit transient Codex failures and unexpected process exits also retry, with
|
|
1904
|
+
at most three fresh sessions per review. Transient findings-service failures, including
|
|
1905
|
+
rate limits and network errors, receive up to three request attempts. Retries use
|
|
1906
|
+
exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to retry
|
|
1907
|
+
occupies the job's concurrency slot.
|
|
1908
|
+
|
|
1909
|
+
Cancellation, authentication or configuration errors, permanent HTTP errors, and
|
|
1910
|
+
required-source-access blockers are not retried. Exhausted retries fail deduplication;
|
|
1911
|
+
invalid or unfinished reviews are not cached. Completed checkpoints remain
|
|
1912
|
+
available when the workflow resumes.
|
|
1336
1913
|
|
|
1337
1914
|
Checkpoints bind to the exact original records and ordering, approved source path,
|
|
1338
1915
|
Git revision and current file contents (including ignored files), repository scope,
|
|
@@ -1356,12 +1933,15 @@ use another workflow ID for a fresh review rather than changing that saved resul
|
|
|
1356
1933
|
1. For each distinct finding ID in the scan, request
|
|
1357
1934
|
`/v1/finding/{id}/potential-duplicates` with the selected repository or
|
|
1358
1935
|
explicit all-repository scope. Use the complete stored anchor and
|
|
1359
|
-
candidates returned by that request.
|
|
1936
|
+
candidates returned by that request. Fetch all neighborhoods before starting
|
|
1937
|
+
reviews so every pair's screening dependencies are known.
|
|
1360
1938
|
2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
|
|
1361
1939
|
effort. The review covers every anchor-neighbor pair; nominations between
|
|
1362
1940
|
neighbors are rejected.
|
|
1363
|
-
3. Independently review each nominated pair once with `gpt-5.6-sol` at `
|
|
1364
|
-
reasoning effort
|
|
1941
|
+
3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
|
|
1942
|
+
reasoning effort after all Luna screenings covering that pair finish without
|
|
1943
|
+
a `DISTINCT` decision. Luna and ready Sol jobs share the configured worker
|
|
1944
|
+
pool and can run together. Only accepted pairs contribute to duplicate groups.
|
|
1365
1945
|
4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
|
|
1366
1946
|
decision contradicts the resulting component. Contradicted components are
|
|
1367
1947
|
split deterministically, preferring legal subgroups that preserve more
|
|
@@ -1564,7 +2144,9 @@ Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
|
|
|
1564
2144
|
Startup and listing need no key. The service does not load `.env` or authenticate
|
|
1565
2145
|
requests; keep it on loopback or behind an authenticated TLS proxy.
|
|
1566
2146
|
|
|
1567
|
-
|
|
2147
|
+
For a source build, first prepare the
|
|
2148
|
+
[universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
|
|
2149
|
+
for that checkout. Then run from its `sdk/typescript` directory:
|
|
1568
2150
|
|
|
1569
2151
|
```bash
|
|
1570
2152
|
pnpm install --frozen-lockfile
|