@openai/codex-security 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -2
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +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/permission-profile-preflight.mjs +60 -9
- 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/schemas/definitions/artifact-common.schema.json +1 -1
- package/_bundled_plugin/scripts/finalize_scan_contract.py +12 -1
- package/_bundled_plugin/scripts/generate_in_scope_files.py +6 -6
- package/_bundled_plugin/scripts/generate_rank_input.py +12 -6
- package/_bundled_plugin/scripts/report_projection.py +2 -1
- package/_bundled_plugin/scripts/threat_model_projection.py +1 -3
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +234 -0
- package/_bundled_plugin/scripts/workbench_cli.py +5 -7
- package/_bundled_plugin/scripts/workbench_db.py +12 -6
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +2 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +10 -7
- package/_bundled_plugin/scripts/workbench_publication.py +4 -3
- package/_bundled_plugin/scripts/workbench_remediation.py +5 -1
- package/_bundled_plugin/scripts/workbench_saved_results.py +542 -148
- package/_bundled_plugin/scripts/workbench_scan_history.py +79 -78
- package/_bundled_plugin/scripts/workbench_scan_usage.py +61 -13
- package/_bundled_plugin/scripts/workbench_target.py +21 -7
- package/_bundled_plugin/scripts/workbench_validation.py +21 -18
- package/_bundled_plugin/shared/workbench-migrations.json +26 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +16 -8
- package/_bundled_plugin/skills/publish-findings/SKILL.md +130 -0
- package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +6 -0
- package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
- package/dist/api.d.ts +4 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +233 -91
- package/dist/api.js.map +1 -1
- package/dist/classify-scan-severity.d.ts.map +1 -1
- package/dist/classify-scan-severity.js +16 -18
- package/dist/classify-scan-severity.js.map +1 -1
- package/dist/classify-severity-records.d.ts +5 -2
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +40 -34
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts +5 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +20 -30
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-daybreak.d.ts +5 -0
- package/dist/cli-daybreak.d.ts.map +1 -0
- package/dist/cli-daybreak.js +89 -0
- package/dist/cli-daybreak.js.map +1 -0
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +1 -0
- package/dist/cli-help.js.map +1 -1
- package/dist/cli.d.ts +12 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1224 -596
- package/dist/cli.js.map +1 -1
- package/dist/cloud-endpoint.d.ts +6 -0
- package/dist/cloud-endpoint.d.ts.map +1 -0
- package/dist/cloud-endpoint.js +51 -0
- package/dist/cloud-endpoint.js.map +1 -0
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +7 -5
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codeowners.js +2 -2
- package/dist/codeowners.js.map +1 -1
- package/dist/component-plan.d.ts.map +1 -1
- package/dist/component-plan.js +3 -2
- package/dist/component-plan.js.map +1 -1
- package/dist/component-scan.js +2 -2
- package/dist/component-scan.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +5 -1
- package/dist/config.js.map +1 -1
- package/dist/cost.d.ts +2 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +17 -8
- package/dist/cost.js.map +1 -1
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +2 -5
- package/dist/custom-validation.js.map +1 -1
- package/dist/deduplication/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js +8 -6
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/local.d.ts.map +1 -1
- package/dist/deduplication/local.js +5 -2
- package/dist/deduplication/local.js.map +1 -1
- package/dist/deduplication/retry.d.ts.map +1 -1
- package/dist/deduplication/retry.js +5 -0
- package/dist/deduplication/retry.js.map +1 -1
- package/dist/deduplication/scan.js +5 -1
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-scan.d.ts +6 -0
- package/dist/deep-scan.d.ts.map +1 -1
- package/dist/deep-scan.js +8 -6
- package/dist/deep-scan.js.map +1 -1
- package/dist/default-severity-rubric.d.ts +3 -0
- package/dist/default-severity-rubric.d.ts.map +1 -0
- package/dist/default-severity-rubric.js +67 -0
- package/dist/default-severity-rubric.js.map +1 -0
- package/dist/endor-findings.d.ts +7 -0
- package/dist/endor-findings.d.ts.map +1 -0
- package/dist/endor-findings.js +233 -0
- package/dist/endor-findings.js.map +1 -0
- package/dist/external-findings-import.d.ts +5 -0
- package/dist/external-findings-import.d.ts.map +1 -0
- package/dist/external-findings-import.js +38 -0
- package/dist/external-findings-import.js.map +1 -0
- package/dist/external-findings-local.d.ts +63 -0
- package/dist/external-findings-local.d.ts.map +1 -0
- package/dist/external-findings-local.js +337 -0
- package/dist/external-findings-local.js.map +1 -0
- package/dist/external-findings-publish.d.ts +73 -0
- package/dist/external-findings-publish.d.ts.map +1 -0
- package/dist/external-findings-publish.js +713 -0
- package/dist/external-findings-publish.js.map +1 -0
- package/dist/external-findings-read.d.ts +6 -0
- package/dist/external-findings-read.d.ts.map +1 -0
- package/dist/external-findings-read.js +88 -0
- package/dist/external-findings-read.js.map +1 -0
- package/dist/external-findings.d.ts +21 -0
- package/dist/external-findings.d.ts.map +1 -0
- package/dist/external-findings.js +2 -0
- package/dist/external-findings.js.map +1 -0
- package/dist/external-import-contract.d.ts +13 -0
- package/dist/external-import-contract.d.ts.map +1 -0
- package/dist/external-import-contract.js +254 -0
- package/dist/external-import-contract.js.map +1 -0
- package/dist/external-import-models.d.ts +362 -0
- package/dist/external-import-models.d.ts.map +1 -0
- package/dist/external-import-models.js +3 -0
- package/dist/external-import-models.js.map +1 -0
- package/dist/finding-workflow.d.ts +1 -1
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +2 -1
- package/dist/finding-workflow.js.map +1 -1
- package/dist/findings-import.d.ts.map +1 -1
- package/dist/findings-import.js +23 -3
- package/dist/findings-import.js.map +1 -1
- package/dist/github-advisories.d.ts +386 -0
- package/dist/github-advisories.d.ts.map +1 -0
- package/dist/github-advisories.js +131 -0
- package/dist/github-advisories.js.map +1 -0
- package/dist/github-findings.d.ts +10 -0
- package/dist/github-findings.d.ts.map +1 -0
- package/dist/github-findings.js +256 -0
- package/dist/github-findings.js.map +1 -0
- package/dist/host-protocol.d.ts +1 -0
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js +1 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/hosted-remediation-protocol.d.ts +6 -0
- package/dist/hosted-remediation-protocol.d.ts.map +1 -0
- package/dist/hosted-remediation-protocol.js +32 -0
- package/dist/hosted-remediation-protocol.js.map +1 -0
- package/dist/hosted-remediation.d.ts +93 -0
- package/dist/hosted-remediation.d.ts.map +1 -0
- package/dist/hosted-remediation.js +124 -0
- package/dist/hosted-remediation.js.map +1 -0
- package/dist/hosted-scan.d.ts +16 -0
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +14 -2
- package/dist/hosted-scan.js.map +1 -1
- package/dist/import-scan.d.ts +1 -0
- package/dist/import-scan.d.ts.map +1 -1
- package/dist/import-scan.js +5 -1
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +18 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -0
- package/dist/index.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +3 -1
- package/dist/multiscan.js.map +1 -1
- package/dist/project-config-schema.d.ts +2 -0
- package/dist/project-config-schema.d.ts.map +1 -1
- package/dist/project-config-schema.js +1 -0
- package/dist/project-config-schema.js.map +1 -1
- package/dist/project-config.d.ts +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +15 -9
- package/dist/project-config.js.map +1 -1
- package/dist/publish.d.ts +2 -0
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +9 -0
- package/dist/publish.js.map +1 -1
- package/dist/remediation.d.ts +69 -0
- package/dist/remediation.d.ts.map +1 -0
- package/dist/remediation.js +121 -0
- package/dist/remediation.js.map +1 -0
- package/dist/request-metadata.d.ts +17 -7
- package/dist/request-metadata.d.ts.map +1 -1
- package/dist/request-metadata.js +43 -8
- package/dist/request-metadata.js.map +1 -1
- package/dist/result.d.ts +4 -0
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +10 -0
- package/dist/result.js.map +1 -1
- package/dist/runtime.d.ts +1 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +24 -15
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan-bootstrap.d.ts +1 -0
- package/dist/saved-scan-bootstrap.d.ts.map +1 -1
- package/dist/saved-scan-bootstrap.js +16 -4
- package/dist/saved-scan-bootstrap.js.map +1 -1
- package/dist/scan-activity.js +8 -8
- package/dist/scan-activity.js.map +1 -1
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +15 -9
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +12 -6
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-executor.d.ts +5 -1
- package/dist/scan-executor.d.ts.map +1 -1
- package/dist/scan-executor.js +9 -8
- package/dist/scan-executor.js.map +1 -1
- package/dist/scan-owner-suggestions.d.ts +8 -0
- package/dist/scan-owner-suggestions.d.ts.map +1 -0
- package/dist/scan-owner-suggestions.js +33 -0
- package/dist/scan-owner-suggestions.js.map +1 -0
- package/dist/{deep-progress.d.ts → scan-progress.d.ts} +15 -7
- package/dist/scan-progress.d.ts.map +1 -0
- package/dist/scan-progress.js +138 -0
- package/dist/scan-progress.js.map +1 -0
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +4 -0
- package/dist/scan-settings.js.map +1 -1
- package/dist/scanner-import.d.ts +20 -0
- package/dist/scanner-import.d.ts.map +1 -0
- package/dist/scanner-import.js +204 -0
- package/dist/scanner-import.js.map +1 -0
- package/dist/security-policy-diff.d.ts +2 -0
- package/dist/security-policy-diff.d.ts.map +1 -0
- package/dist/security-policy-diff.js +197 -0
- package/dist/security-policy-diff.js.map +1 -0
- package/dist/security-policy.d.ts +7 -3
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +11 -57
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts +9 -0
- package/dist/semgrep-findings.d.ts.map +1 -0
- package/dist/semgrep-findings.js +293 -0
- package/dist/semgrep-findings.js.map +1 -0
- package/dist/server/embeddings.d.ts.map +1 -1
- package/dist/server/embeddings.js +4 -0
- package/dist/server/embeddings.js.map +1 -1
- package/dist/server/sqlite-store.d.ts.map +1 -1
- package/dist/server/sqlite-store.js +14 -2
- package/dist/server/sqlite-store.js.map +1 -1
- package/dist/severity-review.d.ts +3 -0
- package/dist/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +19 -0
- package/dist/severity-review.js.map +1 -1
- package/dist/severity-store.js +11 -3
- package/dist/severity-store.js.map +1 -1
- package/dist/snyk-findings.d.ts +9 -0
- package/dist/snyk-findings.d.ts.map +1 -0
- package/dist/snyk-findings.js +349 -0
- package/dist/snyk-findings.js.map +1 -0
- package/dist/targets.d.ts +2 -2
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +12 -2
- package/dist/targets.js.map +1 -1
- package/dist/timestamps.d.ts +3 -0
- package/dist/timestamps.d.ts.map +1 -0
- package/dist/timestamps.js +14 -0
- package/dist/timestamps.js.map +1 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +13 -2
- package/dist/version.js.map +1 -1
- package/dist/wiz-csv.d.ts +8 -0
- package/dist/wiz-csv.d.ts.map +1 -0
- package/dist/wiz-csv.js +116 -0
- package/dist/wiz-csv.js.map +1 -0
- package/dist/wiz-findings.d.ts +4 -0
- package/dist/wiz-findings.d.ts.map +1 -0
- package/dist/wiz-findings.js +460 -0
- package/dist/wiz-findings.js.map +1 -0
- package/dist/workbench-arguments.d.ts.map +1 -1
- package/dist/workbench-arguments.js +9 -3
- package/dist/workbench-arguments.js.map +1 -1
- package/dist/worker-progress.d.ts +11 -1
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +11 -1
- package/dist/worker-progress.js.map +1 -1
- package/docs/classify-severity-records.md +28 -10
- package/docs/cli.md +788 -46
- package/docs/findings-service.md +7 -2
- package/docs/hosted-remediation.md +134 -0
- package/docs/hosted-scans.md +20 -3
- package/package.json +9 -6
- package/schemas/external-findings.schema.json +1421 -0
- package/schemas/project-config.schema.json +4 -0
- package/dist/deep-progress.d.ts.map +0 -1
- package/dist/deep-progress.js +0 -92
- 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
|
|
304
|
-
and MCP, and uses only Codex's core shell environment.
|
|
305
|
-
|
|
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
|
|
@@ -337,7 +377,16 @@ try {
|
|
|
337
377
|
`preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied
|
|
338
378
|
in-memory draft and escapes terminal controls; editing its saved file does not
|
|
339
379
|
change that object. `securityPolicyDiff()` returns a raw diff for files and other
|
|
340
|
-
non-terminal uses
|
|
380
|
+
non-terminal uses. Both preview methods compute the diff in Node without
|
|
381
|
+
discovering or launching Python; `pythonPath` and `PYTHON` do not affect previews.
|
|
382
|
+
|
|
383
|
+
The optional second argument to `securityPolicyDiff(draft, python, signal)` is
|
|
384
|
+
deprecated. Interpreter paths, including paths returned by a resolver callback,
|
|
385
|
+
no longer select an executable or get validated. For compatibility, an explicitly
|
|
386
|
+
supplied resolver is still awaited when the draft changes, and any error it throws
|
|
387
|
+
propagates. Omit that argument for new code, or pass `undefined` when supplying a
|
|
388
|
+
cancellation signal. Source freshness is checked before and after computing the
|
|
389
|
+
diff.
|
|
341
390
|
|
|
342
391
|
`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
|
|
343
392
|
`maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives
|
|
@@ -351,14 +400,25 @@ codex-security scan .
|
|
|
351
400
|
codex-security scan . --path src --path tests
|
|
352
401
|
codex-security scan . --diff origin/main --json
|
|
353
402
|
codex-security scan . --working-tree
|
|
403
|
+
codex-security scan . --owner-suggestions
|
|
354
404
|
codex-security scan . --output-dir /path/outside/repository/results --dry-run
|
|
355
405
|
```
|
|
356
406
|
|
|
407
|
+
Whole-codebase and path scans also accept ordinary directories, including SVN
|
|
408
|
+
working copies. Their source inventories exclude `.git` and `.svn` metadata.
|
|
409
|
+
|
|
357
410
|
`--diff` scans committed changes; `--working-tree` scans staged and unstaged
|
|
358
|
-
changes. Deep scans support whole repositories and path scopes.
|
|
359
|
-
snapshots include untracked nested Git repositories. Initialized submodules must
|
|
411
|
+
changes. Both require Git. Deep scans support whole repositories and path scopes.
|
|
412
|
+
Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
|
|
360
413
|
be clean and at the commit recorded by the parent.
|
|
361
414
|
|
|
415
|
+
`--owner-suggestions` writes optional `owner-suggestions.json` after a completed
|
|
416
|
+
committed Git scan, using the same checkout, model, and reasoning effort. Owner
|
|
417
|
+
errors leave the base scan completed. The JSON result includes
|
|
418
|
+
`ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
|
|
419
|
+
manifest stay unchanged. This option is unsupported for working-tree and
|
|
420
|
+
directory snapshots, and is skipped with a warning when `--max-cost` is set.
|
|
421
|
+
|
|
362
422
|
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
363
423
|
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
364
424
|
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
@@ -547,6 +607,9 @@ Import needs no model calls or authentication. `--dry-run` validates without
|
|
|
547
607
|
saving; `--output-dir` and `--archive-existing` control output. `scans rerun`
|
|
548
608
|
reimports the retained input.
|
|
549
609
|
|
|
610
|
+
For vendor exports, use [local vendor import](#import-vendor-findings-locally)
|
|
611
|
+
instead. That flow retains unassessed source evidence without creating a scan.
|
|
612
|
+
|
|
550
613
|
### Generate mock scan results
|
|
551
614
|
|
|
552
615
|
```bash
|
|
@@ -613,7 +676,9 @@ codex-security scan-components . \
|
|
|
613
676
|
--output-dir /path/outside/project/results
|
|
614
677
|
```
|
|
615
678
|
|
|
616
|
-
Plans use repository-relative paths
|
|
679
|
+
Plans use literal repository-relative paths, so `~/src` selects a directory
|
|
680
|
+
named `~` inside the repository rather than expanding the home directory.
|
|
681
|
+
Existing absolute paths inside the repository are also accepted.
|
|
617
682
|
|
|
618
683
|
```json
|
|
619
684
|
{
|
|
@@ -646,7 +711,8 @@ or API-key auth. SDK-selected command providers retain their authentication.
|
|
|
646
711
|
|
|
647
712
|
From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
|
|
648
713
|
Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
|
|
649
|
-
planning and authentication choices.
|
|
714
|
+
planning and authentication choices. Custom `createSecurity` clients receive
|
|
715
|
+
absolute targets; saved plans and component receipts retain relative paths.
|
|
650
716
|
|
|
651
717
|
### Set investigation time
|
|
652
718
|
|
|
@@ -757,7 +823,7 @@ or Windows MCP launcher. Saved reports remain readable.
|
|
|
757
823
|
Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
|
|
758
824
|
|
|
759
825
|
`validate`, `patch`, and `verify-fix` limit native overrides to `model`,
|
|
760
|
-
`model_reasoning_effort`, `model_provider`, `model_providers`, and
|
|
826
|
+
`model_reasoning_effort`, `model_provider`, `model_providers`, `daybreak`, and
|
|
761
827
|
`analytics.enabled`. For a custom provider:
|
|
762
828
|
|
|
763
829
|
```bash
|
|
@@ -779,14 +845,28 @@ that command. Model, effort, and provider choices carry into patch-risk assessme
|
|
|
779
845
|
Model requests include Codex Security attribution in `responses_api_metadata`:
|
|
780
846
|
`codex_security_surface` (`cli` or `sdk`), `codex_security_command`,
|
|
781
847
|
`codex_security_package_version`, and `codex_security_plugin_version` when the
|
|
782
|
-
selected plugin declares a version.
|
|
783
|
-
|
|
784
|
-
|
|
848
|
+
selected plugin declares a version. The shared context adds
|
|
849
|
+
`codex_security_provider` for the configured provider family when the wrapper
|
|
850
|
+
selects a provider, and
|
|
851
|
+
`codex_security_scan_mode` for scans. Custom provider names use `custom`.
|
|
852
|
+
Provider attribution reflects the wrapper's selected profile or default;
|
|
853
|
+
native managed configuration may select a different provider before inference.
|
|
854
|
+
The GitHub Action supplies `codex_security_integration=github_action`;
|
|
855
|
+
Deep Scan workers retain the context and add `codex_security_worker_role`.
|
|
856
|
+
Caller metadata, including literal dotted keys, is preserved. Connected-app
|
|
857
|
+
publication uses the same request attribution; embedding requests identify
|
|
858
|
+
the package and version in their `User-Agent`.
|
|
859
|
+
|
|
860
|
+
These fields provide request attribution for supported inference providers, including
|
|
861
|
+
Bedrock. They do not create a separate telemetry collector, record command
|
|
862
|
+
starts or outcomes, or make another provider's traffic visible to OpenAI.
|
|
785
863
|
|
|
786
864
|
Disable Codex usage analytics and built-in metrics with
|
|
787
865
|
`--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
|
|
788
866
|
patch-risk assessment, and Deep Scan discovery and reducer workers, including
|
|
789
|
-
resumed workers.
|
|
867
|
+
resumed workers. Selected-profile settings take precedence over root settings.
|
|
868
|
+
Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
|
|
869
|
+
workers, including exporter choices and prompt-logging controls.
|
|
790
870
|
Model-request attribution metadata remains attached when analytics are disabled.
|
|
791
871
|
The setting does not control configured OpenTelemetry exporters, integrations,
|
|
792
872
|
authentication, or CLI update checks. Validation uses isolated configuration;
|
|
@@ -797,24 +877,26 @@ For filesystem and approval behavior, see the
|
|
|
797
877
|
|
|
798
878
|
### Environment variables
|
|
799
879
|
|
|
800
|
-
| Variable | Effect
|
|
801
|
-
| --------------------------------------------------------------------------- |
|
|
802
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence.
|
|
803
|
-
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts.
|
|
804
|
-
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it.
|
|
805
|
-
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`.
|
|
806
|
-
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers.
|
|
807
|
-
| `PYTHON` | Python interpreter unless an explicit option overrides it.
|
|
808
|
-
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output.
|
|
809
|
-
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank.
|
|
810
|
-
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination.
|
|
811
|
-
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key.
|
|
812
|
-
| `
|
|
813
|
-
| `
|
|
814
|
-
| `
|
|
815
|
-
| `
|
|
816
|
-
| `
|
|
817
|
-
| `
|
|
880
|
+
| Variable | Effect |
|
|
881
|
+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
882
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
|
|
883
|
+
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
|
|
884
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
|
|
885
|
+
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
|
|
886
|
+
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
|
|
887
|
+
| `PYTHON` | Python interpreter unless an explicit option overrides it. |
|
|
888
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
|
|
889
|
+
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
|
|
890
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
|
|
891
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
|
|
892
|
+
| `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
|
|
893
|
+
| `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
|
|
894
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
|
|
895
|
+
| `GH_HOST` | GitHub Enterprise host for bulk discovery. |
|
|
896
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
|
|
897
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
|
|
898
|
+
| `CI` | Disable interactive update notices. |
|
|
899
|
+
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
818
900
|
|
|
819
901
|
Custom Codex executables need thread source attribution for `exec` and
|
|
820
902
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -848,9 +930,12 @@ Preserve existing state, then choose a private `CODEX_SECURITY_STATE_DIR` outsid
|
|
|
848
930
|
the rejected ancestor and the repository, with a full ancestor chain that passes
|
|
849
931
|
the same checks. If the volume root is rejected, another directory on that
|
|
850
932
|
volume cannot resolve it; use a separately provisioned volume with trusted
|
|
851
|
-
ancestry.
|
|
852
|
-
`
|
|
853
|
-
|
|
933
|
+
ancestry. On Windows, local runtime bootstrap directories are created beside
|
|
934
|
+
`codex-home` in the state directory and removed when the SDK client closes.
|
|
935
|
+
They use the same trusted ancestry checks, so sandbox write permissions on
|
|
936
|
+
`TEMP` do not prevent runtime preparation. `TEMP`, `TMP`, and scan output
|
|
937
|
+
locations are unchanged. Do not change the system volume's owner or ACL to
|
|
938
|
+
make a scan run. If no suitable
|
|
854
939
|
location is available, this layout cannot provision credentials safely under
|
|
855
940
|
the current checks. Sign in again if needed; a new state directory has separate
|
|
856
941
|
scan history and does not migrate credentials or reports from the old state
|
|
@@ -1001,6 +1086,8 @@ codex-security bulk-scan repositories.csv \
|
|
|
1001
1086
|
```
|
|
1002
1087
|
|
|
1003
1088
|
Bulk scans use clean shallow checkouts and support repository/path scopes.
|
|
1089
|
+
CSV scopes are literal paths relative to each checkout, including names such
|
|
1090
|
+
as `~/src`.
|
|
1004
1091
|
Configured diff or working-tree scopes are rejected unless every affected row
|
|
1005
1092
|
overrides them with a path scope. `--output-dir` requires CSV input.
|
|
1006
1093
|
|
|
@@ -1108,8 +1195,466 @@ failure or incomplete/invalid output fails the scan. Deferred candidates remain
|
|
|
1108
1195
|
follow-up notes and do not fail the scan. An incompatible plugin stops the scan.
|
|
1109
1196
|
Supply the validation prompt again when rerunning.
|
|
1110
1197
|
|
|
1198
|
+
## Import vendor findings locally
|
|
1199
|
+
|
|
1200
|
+
Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
|
|
1201
|
+
reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
|
|
1202
|
+
inputs only for providers and report profiles that support them. A JSON API
|
|
1203
|
+
summary is not automatically a supported report; follow the provider's acquisition
|
|
1204
|
+
instructions and retain the original records. The readers detect supported input
|
|
1205
|
+
formats; `--format json` selects command output, not the input format.
|
|
1206
|
+
|
|
1207
|
+
Keep the acquisition format consistent across imports. Depending on the provider,
|
|
1208
|
+
switching formats can create separate records for the same vulnerability or
|
|
1209
|
+
replace a richer evidence snapshot with less detail. The importer does not merge
|
|
1210
|
+
evidence or deduplicate equivalent vulnerabilities across different source IDs.
|
|
1211
|
+
|
|
1212
|
+
Use the same vendor input and parser as Cloud publication, selecting a local
|
|
1213
|
+
repository path instead of a Cloud repository ID or URL. Supported inputs include
|
|
1214
|
+
Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
|
|
1215
|
+
[Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
|
|
1216
|
+
[Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
|
|
1217
|
+
and [saved GitHub alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
|
|
1218
|
+
|
|
1219
|
+
```bash
|
|
1220
|
+
codex-security publish findings selected-wiz.json \
|
|
1221
|
+
--to local --repository ./project --provider wiz \
|
|
1222
|
+
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
1223
|
+
```
|
|
1224
|
+
|
|
1225
|
+
Review the normalized evidence, repository, source namespace, and exclusions.
|
|
1226
|
+
Run the same command without `--dry-run` to confirm interactively, or add `--yes`
|
|
1227
|
+
after reviewing the preview. `--to` is required; there is no default destination.
|
|
1228
|
+
Local import uses the workbench SQLite database and requires no Cloud login,
|
|
1229
|
+
network connection, or model call. `--dry-run` does not write findings.
|
|
1230
|
+
|
|
1231
|
+
Read the saved evidence with:
|
|
1232
|
+
|
|
1233
|
+
```bash
|
|
1234
|
+
codex-security findings imported ./project --format json
|
|
1235
|
+
```
|
|
1236
|
+
|
|
1237
|
+
The repository argument defaults to the current directory. Local imports are
|
|
1238
|
+
separate from the assessed findings shown by `findings list`: they remain
|
|
1239
|
+
`not_assessed`, retain the original vendor evidence, and do not create a completed
|
|
1240
|
+
scan or automatically validate or patch findings. Missing revisions, locations,
|
|
1241
|
+
and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
|
|
1242
|
+
Git remotes, the URL must match one of those remotes; the importer does not
|
|
1243
|
+
substitute the checkout's current commit for an unknown scanner revision.
|
|
1244
|
+
|
|
1245
|
+
Repeated imports update the same record by repository, provider, source key, and
|
|
1246
|
+
source finding ID. The result reports created, updated, and unchanged counts.
|
|
1247
|
+
Keep the source key stable across exports. Records omitted from a later selection
|
|
1248
|
+
remain stored; omission does not resolve or delete a finding. Excluded records
|
|
1249
|
+
are reported, and an import with exclusions exits with status 1. The same
|
|
1250
|
+
supported vendor formats and evidence requirements apply locally and in Cloud.
|
|
1251
|
+
|
|
1252
|
+
`scan import --json` and `scan import --csv` remain separate commands for importing
|
|
1253
|
+
Codex Security's findings schema as a saved scan; they do not accept vendor
|
|
1254
|
+
exports.
|
|
1255
|
+
|
|
1256
|
+
## Import Endor Labs findings
|
|
1257
|
+
|
|
1258
|
+
For local or Cloud import, prefer complete native Finding JSON from authenticated
|
|
1259
|
+
`endorctl`, scoped to one project and context. Omit `--field-mask` and use
|
|
1260
|
+
`--list-all` to finish pagination:
|
|
1261
|
+
|
|
1262
|
+
```sh
|
|
1263
|
+
endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
|
|
1264
|
+
--filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
|
|
1265
|
+
--list-all --output-type json > endor-findings.json
|
|
1266
|
+
codex-security publish findings endor-findings.json --to local \
|
|
1267
|
+
--provider endor --repository ./project \
|
|
1268
|
+
--source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
|
|
1269
|
+
```
|
|
1270
|
+
|
|
1271
|
+
Replace the example namespace, project UUID and local repository with your selection.
|
|
1272
|
+
Review the preview, remove `--dry-run` to confirm, then read the stored evidence
|
|
1273
|
+
with `codex-security findings imported ./project --format json`. To publish to
|
|
1274
|
+
Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
|
|
1275
|
+
file, provider and source key. The official
|
|
1276
|
+
[Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
|
|
1277
|
+
can help with setup and investigation, but summaries, counts and field-masked
|
|
1278
|
+
results do not replace complete Finding objects. `endorctl` reads the Endor API;
|
|
1279
|
+
the importer reads the saved export without maintaining an API connection or
|
|
1280
|
+
writing changes back to Endor.
|
|
1281
|
+
|
|
1282
|
+
Native JSON retains severity, package and advisory data, primary SAST/AI SAST
|
|
1283
|
+
locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
|
|
1284
|
+
reports are a lossy compatibility format, retaining finding links and UUIDs;
|
|
1285
|
+
unavailable severity and revisions stay unknown. Both formats use the Endor UUID
|
|
1286
|
+
within the selected repository and stable source key as identity. Importing SARIF
|
|
1287
|
+
after native JSON for that UUID updates the same record by replacing its evidence
|
|
1288
|
+
snapshot, not merging it. Native detail absent from SARIF is removed from the
|
|
1289
|
+
snapshot. Use native JSON consistently for ongoing imports.
|
|
1290
|
+
|
|
1291
|
+
Local and Cloud records remain unassessed source evidence. Local imports use the
|
|
1292
|
+
SQLite readback described above; Cloud imports use the login, preview,
|
|
1293
|
+
confirmation and retry flow below.
|
|
1294
|
+
|
|
1111
1295
|
## Publish findings to Cloud
|
|
1112
1296
|
|
|
1297
|
+
### Import Snyk Open Source findings
|
|
1298
|
+
|
|
1299
|
+
Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
|
|
1300
|
+
SBOM results and platform backlog ingestion are outside this adapter.
|
|
1301
|
+
|
|
1302
|
+
Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
|
|
1303
|
+
with its `snyk-findings-export` skill to collect SCA findings from the repository's
|
|
1304
|
+
Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
|
|
1305
|
+
it does not retrieve existing platform project findings.
|
|
1306
|
+
|
|
1307
|
+
The same saved bundle supports [local import](#import-vendor-findings-locally)
|
|
1308
|
+
without a Cloud login:
|
|
1309
|
+
|
|
1310
|
+
```sh
|
|
1311
|
+
codex-security publish findings snyk-findings.json --to local \
|
|
1312
|
+
--provider snyk --repository ./project \
|
|
1313
|
+
--source-key github.com/example/project/main/root/plugin-sca --dry-run
|
|
1314
|
+
```
|
|
1315
|
+
|
|
1316
|
+
Or preview publication to a connected Cloud repository:
|
|
1317
|
+
|
|
1318
|
+
```sh
|
|
1319
|
+
codex-security publish findings snyk-findings.json --to cloud \
|
|
1320
|
+
--provider snyk --repository https://github.com/example/project \
|
|
1321
|
+
--source-key github.com/example/project/main/root/plugin-sca --dry-run
|
|
1322
|
+
```
|
|
1323
|
+
|
|
1324
|
+
Check the collection's scan outcomes and limitations. Only Open Source SCA
|
|
1325
|
+
vulnerabilities are imported; other products and licenses are explicit exclusions.
|
|
1326
|
+
The importer retains the selected finding, native MCP record and collection
|
|
1327
|
+
context. MCP may shorten descriptions and omit dependency paths. Plugin paths
|
|
1328
|
+
remain in original evidence because v1 lacks their offset from the Git root.
|
|
1329
|
+
|
|
1330
|
+
For automation, prefer native JSON from
|
|
1331
|
+
`snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
|
|
1332
|
+
stop on other nonzero exits before importing. The existing `--provider snyk`
|
|
1333
|
+
autodetects a single project object or an `--all-projects` array; any project error
|
|
1334
|
+
stops the import. Use default ungrouped output, without `--group-issues`.
|
|
1335
|
+
Native JSON preserves individual dependency paths and remediation fields. Its
|
|
1336
|
+
paths remain original evidence because it does not establish their Git-root offset.
|
|
1337
|
+
|
|
1338
|
+
Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
|
|
1339
|
+
for compatibility. Its target-relative manifest paths and synthetic line numbers
|
|
1340
|
+
remain original evidence, without being projected as repository locations or
|
|
1341
|
+
package manifest paths. All three formats accept either destination. Use a consistent
|
|
1342
|
+
format and stable source key per repository, branch and scan target, for example
|
|
1343
|
+
`github.com/example/project/main/root/native-sca` for native JSON. Their source
|
|
1344
|
+
identities differ: use separate keys when switching acquisition formats. Imports
|
|
1345
|
+
do not deduplicate across formats or remove earlier imported records.
|
|
1346
|
+
|
|
1347
|
+
Known repository claims must
|
|
1348
|
+
match the selected Cloud repository or, when available, a configured local Git
|
|
1349
|
+
remote. Unknown repository context still requires selecting the correct target;
|
|
1350
|
+
the importer does not infer provenance from the current checkout.
|
|
1351
|
+
|
|
1352
|
+
Remove `--dry-run` from the selected command to review and confirm the import, or
|
|
1353
|
+
use `--yes` after reviewing the preview. Read local records with
|
|
1354
|
+
`codex-security findings imported ./project --format json`. Imported source
|
|
1355
|
+
evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
|
|
1356
|
+
[Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
|
|
1357
|
+
acquisition details.
|
|
1358
|
+
|
|
1359
|
+
### Import Wiz findings
|
|
1360
|
+
|
|
1361
|
+
Import selected Wiz package vulnerabilities, SAST findings, repository secrets,
|
|
1362
|
+
and IaC findings without creating a scan. Imported records retain vendor evidence
|
|
1363
|
+
and remain **not assessed by Codex**, including when Wiz marks them resolved or
|
|
1364
|
+
reports an AI verdict. Workload secrets, cloud configuration findings, and external
|
|
1365
|
+
network findings are not supported by this repository importer. Cloud destinations
|
|
1366
|
+
currently support connected GitHub and GitHub Enterprise repositories, including
|
|
1367
|
+
custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
|
|
1368
|
+
|
|
1369
|
+
Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
|
|
1370
|
+
connection to acquire findings and save the supported native JSON. A configured
|
|
1371
|
+
plugin may provide that connection; an official Codex plugin is not a prerequisite.
|
|
1372
|
+
The publisher reads the saved records. It does not fetch from Wiz or require a
|
|
1373
|
+
manual website download. The acquisition path still needs validation against
|
|
1374
|
+
actual responses from an authorized Wiz tenant; local parser checks do not
|
|
1375
|
+
establish that qualification.
|
|
1376
|
+
|
|
1377
|
+
Inspect the connection's actual response before importing it. MCP summaries,
|
|
1378
|
+
Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
|
|
1379
|
+
this finding mapper. Keep the original occurrence IDs and evidence; use the
|
|
1380
|
+
named collections below when the response contains repository findings.
|
|
1381
|
+
|
|
1382
|
+
Before the first import:
|
|
1383
|
+
|
|
1384
|
+
1. Select an existing repository in Codex Security Cloud and copy its URL or
|
|
1385
|
+
Cloud repository ID. The repository needs an
|
|
1386
|
+
authorized environment, but does not need a completed native scan.
|
|
1387
|
+
2. Read the selected records through the authorized connection and save their
|
|
1388
|
+
JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
|
|
1389
|
+
`vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
|
|
1390
|
+
package, image, and source metadata. For SAST, repository secrets, and IaC,
|
|
1391
|
+
retain the named API collections and repository metadata described below.
|
|
1392
|
+
Complete the selected pages before importing; a summary or unfinished page
|
|
1393
|
+
is not a complete finding selection.
|
|
1394
|
+
3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
|
|
1395
|
+
for that Wiz tenant and finding class across exports. Do not create a new key
|
|
1396
|
+
for each project filter or import; that creates different source identities.
|
|
1397
|
+
4. Check the ChatGPT account used by your existing file-backed Codex Security
|
|
1398
|
+
login. API-key-only and keyring-only logins are not supported for Cloud
|
|
1399
|
+
publication. See the credential-storage instructions below.
|
|
1400
|
+
|
|
1401
|
+
Prefer the supported native JSON. Existing package-vulnerability CSV reports are
|
|
1402
|
+
accepted as a compatibility input. **CSV support covers repository package
|
|
1403
|
+
vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
|
|
1404
|
+
Wiz code-to-cloud coverage.** The named JSON readers described below handle their
|
|
1405
|
+
respective finding families separately.
|
|
1406
|
+
|
|
1407
|
+
When a UI report is needed, retain the repository and finding filters in Wiz
|
|
1408
|
+
**Vulnerability Findings**, choose **Save as → Report**, select **Repository
|
|
1409
|
+
Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
|
|
1410
|
+
report. CSV must use the columns described below and a comma delimiter. Plain and
|
|
1411
|
+
gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
|
|
1412
|
+
filename extension. **Raw Event** on Code & Build Scans contains scan metadata
|
|
1413
|
+
rather than findings.
|
|
1414
|
+
|
|
1415
|
+
For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
|
|
1416
|
+
API root before previewing or uploading, for example
|
|
1417
|
+
`https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
|
|
1418
|
+
HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
|
|
1419
|
+
`::1`). Use a login issued by that deployment and an isolated
|
|
1420
|
+
`CODEX_SECURITY_STATE_DIR` for testing. The endpoint
|
|
1421
|
+
does not change your login or sign you into another deployment. An invalid or
|
|
1422
|
+
empty configured URL stops the import before authentication or network requests.
|
|
1423
|
+
With the variable unset, the existing production endpoint remains the default.
|
|
1424
|
+
The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
|
|
1425
|
+
publication endpoint; it does not route vendor imports.
|
|
1426
|
+
|
|
1427
|
+
If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
|
|
1428
|
+
to the full Cloud app URL shown in the browser. The import handoff supplies both
|
|
1429
|
+
deployment settings. The preview and result include a repository-specific
|
|
1430
|
+
`cloudUrl`, and terminal completion prints the link. This setting only controls
|
|
1431
|
+
the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
|
|
1432
|
+
For custom API destinations without a configured app URL, completion retains
|
|
1433
|
+
the manual navigation guidance rather than guessing a UI host or port.
|
|
1434
|
+
|
|
1435
|
+
Preview the selection and destination:
|
|
1436
|
+
|
|
1437
|
+
```bash
|
|
1438
|
+
codex-security publish findings selected-wiz.json \
|
|
1439
|
+
--to cloud --repository https://github.com/example/project --provider wiz \
|
|
1440
|
+
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
1441
|
+
```
|
|
1442
|
+
|
|
1443
|
+
`--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
|
|
1444
|
+
destination and resume the same saved submission. This command reads the
|
|
1445
|
+
authorized destination and current source versions during
|
|
1446
|
+
preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
|
|
1447
|
+
repository needs an existing environment; no native scan is required. Review the
|
|
1448
|
+
Cloud API endpoint, account, repository, environments, findings, and exclusions,
|
|
1449
|
+
then rerun without
|
|
1450
|
+
`--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
|
|
1451
|
+
reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
|
|
1452
|
+
occurs. Existing source findings keep their Cloud environment; new findings use
|
|
1453
|
+
the repository’s current authorized default. Preview shows the environments that
|
|
1454
|
+
will receive the selected findings. The terminal preview summarizes severities,
|
|
1455
|
+
shows up to five finding IDs and titles, and identifies the evidence file and
|
|
1456
|
+
exclusions. `--dry-run --format json` retains all normalized findings and complete
|
|
1457
|
+
evidence for inspection. A prompt explicitly includes any records that will be
|
|
1458
|
+
skipped.
|
|
1459
|
+
|
|
1460
|
+
Native package input can be a Wiz JSON vulnerability report, a vulnerability
|
|
1461
|
+
finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
|
|
1462
|
+
with one package record per line. The repository package-vulnerability CSV
|
|
1463
|
+
profile below is also supported. Plain and gzip-compressed files are accepted.
|
|
1464
|
+
A response that advertises another page is rejected. Complete the requested pages
|
|
1465
|
+
or save only the explicitly selected records; retain the named collection for
|
|
1466
|
+
SAST, repository secrets, and IaC.
|
|
1467
|
+
|
|
1468
|
+
The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
|
|
1469
|
+
`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
|
|
1470
|
+
this profile; other Wiz report types use different fields.
|
|
1471
|
+
For repository imports, `CloudPlatform` must identify GitHub and
|
|
1472
|
+
`CloudProviderURL` must identify a repository branch. The repository URL must
|
|
1473
|
+
match the selected Cloud repository or, for local import, one of the checkout's
|
|
1474
|
+
Git remotes when configured. This also applies when the parsed findings are saved and
|
|
1475
|
+
read again as normalized JSONL. Other resource types are excluded.
|
|
1476
|
+
|
|
1477
|
+
CSV imports use `ID` as the occurrence identity and retain every parsed field,
|
|
1478
|
+
including unknown columns and quoted multiline values, in `source_data.row`.
|
|
1479
|
+
Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
|
|
1480
|
+
Vendor resolution status stays in the original evidence. The importer does not
|
|
1481
|
+
derive a branch or revision from a tree URL, or treat last-detected time as a
|
|
1482
|
+
record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
|
|
1483
|
+
and duplicate occurrence IDs among otherwise importable records stop the import.
|
|
1484
|
+
Review any excluded records in the preview before publishing.
|
|
1485
|
+
|
|
1486
|
+
Normalized JSONL is also accepted:
|
|
1487
|
+
|
|
1488
|
+
```json
|
|
1489
|
+
{
|
|
1490
|
+
"source_finding_id": "vendor-finding-42",
|
|
1491
|
+
"evidence": {
|
|
1492
|
+
"title": "Vulnerable example package",
|
|
1493
|
+
"severity": "high",
|
|
1494
|
+
"source_data": { "id": "vendor-finding-42" }
|
|
1495
|
+
}
|
|
1496
|
+
}
|
|
1497
|
+
```
|
|
1498
|
+
|
|
1499
|
+
Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
|
|
1500
|
+
exports; a selected project filter does not change the vendor namespace. Confirm
|
|
1501
|
+
that the selected assets or builds map to this repository. The raw Wiz adapter
|
|
1502
|
+
retains each record in `source_data`, uses reported severity, and leaves unknown
|
|
1503
|
+
branch/revision empty. Repository-branch findings retain their repository-relative
|
|
1504
|
+
file paths; container and other workload paths remain vendor evidence rather than
|
|
1505
|
+
source-code locations. It does not
|
|
1506
|
+
fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
|
|
1507
|
+
Findings from external network scans are excluded from this package vulnerability
|
|
1508
|
+
mapping.
|
|
1509
|
+
|
|
1510
|
+
For SAST, repository secrets, and IaC, save the documented JSON API collection:
|
|
1511
|
+
|
|
1512
|
+
| Finding family | Collection | Raw occurrence identity |
|
|
1513
|
+
| ------------------ | ---------------------------- | ----------------------- |
|
|
1514
|
+
| SAST | `data.sastFindings.nodes` | `sast:<id>` |
|
|
1515
|
+
| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
|
|
1516
|
+
| IaC | `data.iacFindings.nodes` | `iac:<id>` |
|
|
1517
|
+
|
|
1518
|
+
The collection identifies the mapping. Bare arrays of these raw findings are
|
|
1519
|
+
excluded because their overlapping fields do not identify a family. An export
|
|
1520
|
+
may contain multiple named collections. GraphQL errors and unfinished pages stop
|
|
1521
|
+
the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
|
|
1522
|
+
relationship to source code does not make it a repository secret.
|
|
1523
|
+
|
|
1524
|
+
Each new finding needs a verified source repository URL. Supply `repository.url`
|
|
1525
|
+
in the finding's repository metadata, or include the matching repository inventory
|
|
1526
|
+
in `data.versionControlResources.nodes`. For secrets, repository metadata is under
|
|
1527
|
+
`resource.typedProperties.repository`. The importer joins the inventory's
|
|
1528
|
+
`repository.id` to that source ID and uses `repository.url`; inventory node IDs,
|
|
1529
|
+
`providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
|
|
1530
|
+
must agree with the inventory and with the selected Cloud repository before any
|
|
1531
|
+
finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
|
|
1532
|
+
establishes case-insensitive repository matching on custom GitHub Enterprise
|
|
1533
|
+
hosts. Fresh imports preserve the reported branch name literally. Duplicate
|
|
1534
|
+
entries for one repository ID must agree on their platform and repository URL.
|
|
1535
|
+
For example, this synthetic selection supplies the inventory alongside its SAST
|
|
1536
|
+
collection:
|
|
1537
|
+
|
|
1538
|
+
```json
|
|
1539
|
+
{
|
|
1540
|
+
"data": {
|
|
1541
|
+
"sastFindings": {
|
|
1542
|
+
"nodes": [
|
|
1543
|
+
{
|
|
1544
|
+
"id": "finding-42",
|
|
1545
|
+
"name": "Untrusted query construction",
|
|
1546
|
+
"severity": "HIGH",
|
|
1547
|
+
"repository": { "id": "source-repository-1" },
|
|
1548
|
+
"filePath": "src/query.ts",
|
|
1549
|
+
"startLine": 10,
|
|
1550
|
+
"endLine": 12
|
|
1551
|
+
}
|
|
1552
|
+
]
|
|
1553
|
+
},
|
|
1554
|
+
"versionControlResources": {
|
|
1555
|
+
"nodes": [
|
|
1556
|
+
{
|
|
1557
|
+
"repository": {
|
|
1558
|
+
"id": "source-repository-1",
|
|
1559
|
+
"url": "https://github.com/example/project"
|
|
1560
|
+
}
|
|
1561
|
+
}
|
|
1562
|
+
]
|
|
1563
|
+
}
|
|
1564
|
+
}
|
|
1565
|
+
}
|
|
1566
|
+
```
|
|
1567
|
+
|
|
1568
|
+
The adapters preserve each selected raw node exactly in `source_data`. Typed
|
|
1569
|
+
`evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
|
|
1570
|
+
and family-specific evidence:
|
|
1571
|
+
|
|
1572
|
+
| Family | Evidence retained in typed fields |
|
|
1573
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1574
|
+
| SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
|
|
1575
|
+
| Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
|
|
1576
|
+
| IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
|
|
1577
|
+
|
|
1578
|
+
Vendor status and verdict remain separate from Codex assessment. A secret's
|
|
1579
|
+
introduced commit is not its scanned revision. Missing source revisions and scan
|
|
1580
|
+
IDs stay unknown. A logical IaC resource is retained in the original record and
|
|
1581
|
+
does not establish that it is deployed. Precise original timestamps remain in
|
|
1582
|
+
`source_data`; only an explicit record-update timestamp maps to the whole-second
|
|
1583
|
+
`source_updated_at` field. SAST creation time and IaC last-seen time are not update
|
|
1584
|
+
timestamps.
|
|
1585
|
+
|
|
1586
|
+
Native SAST and secret report downloads can be CSV, including gzip-compressed
|
|
1587
|
+
CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
|
|
1588
|
+
for its actual column headers into normalized JSONL, preserving each original row
|
|
1589
|
+
in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
|
|
1590
|
+
verifying the source repository. Use the same prefixed occurrence ID shown above
|
|
1591
|
+
so API and report imports update the same finding; normalized IDs are accepted
|
|
1592
|
+
exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
|
|
1593
|
+
for a vendor occurrence ID. Missing IDs or severity must be corrected at the
|
|
1594
|
+
source rather than invented.
|
|
1595
|
+
|
|
1596
|
+
For repository-secret reports, select `path` and `lineNumber` for source
|
|
1597
|
+
navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
|
|
1598
|
+
as the introduced commit. The standard secret metadata API does not supply a
|
|
1599
|
+
path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
|
|
1600
|
+
`rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
|
|
1601
|
+
repository/branch metadata. Preserve the original fields; source locations must
|
|
1602
|
+
be repository-relative, and an end line requires a start line. Keep credential
|
|
1603
|
+
values out of the metadata selection; the importer does not retrieve or test
|
|
1604
|
+
credentials or apply remediation instructions.
|
|
1605
|
+
|
|
1606
|
+
Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
|
|
1607
|
+
integer range is rejected; export those values as strings to preserve them
|
|
1608
|
+
exactly. Invalid records appear in `excluded` with their source ID and reason.
|
|
1609
|
+
|
|
1610
|
+
Requests contain at most 100 findings and respect the Cloud payload limits.
|
|
1611
|
+
Before uploading, the publisher saves request IDs and bodies privately under
|
|
1612
|
+
the configured Codex Security state directory. After an uncertain response,
|
|
1613
|
+
repeat the same command with unchanged input and Cloud API endpoint to resume those
|
|
1614
|
+
requests. Different deployments have separate saved submissions, including when
|
|
1615
|
+
their account and repository IDs match. The preview and result include
|
|
1616
|
+
`cloudApiUrl` so scripts can verify which API received the findings; this is an
|
|
1617
|
+
API endpoint, not a link to the Cloud UI. A reset
|
|
1618
|
+
retires the old request without republishing; review and explicitly approve a
|
|
1619
|
+
fresh invocation.
|
|
1620
|
+
|
|
1621
|
+
Results distinguish completion from partial or interrupted work:
|
|
1622
|
+
|
|
1623
|
+
| Status | Exit code | Meaning |
|
|
1624
|
+
| ------------- | --------- | -------------------------------------------------------------------------------------------------- |
|
|
1625
|
+
| `complete` | 0 | All selected records were acknowledged and their source records read back. |
|
|
1626
|
+
| `partial` | 1 | The import finished, but some records were excluded locally or rejected by Cloud. |
|
|
1627
|
+
| `interrupted` | 2 | Upload, verification, or receipt persistence stopped; acknowledged work is included in the result. |
|
|
1628
|
+
| `failed` | 2 | Preparation failed before uploading; structured output includes the error. |
|
|
1629
|
+
|
|
1630
|
+
For finding imports, `--full-output` requires `--format json` or `--format jsonl`.
|
|
1631
|
+
Failed and interrupted imports set the envelope's `ok` to `false`, with
|
|
1632
|
+
`error.code: "IMPORT_FAILED"`, while retaining available results, receipts, and
|
|
1633
|
+
counts under `data`. Other full-output format combinations are rejected before
|
|
1634
|
+
reading the input or contacting Cloud; omit `--full-output` to use those formats.
|
|
1635
|
+
|
|
1636
|
+
Ctrl-C and SIGTERM retain exit codes 130 and 143. Interrupted JSON output preserves
|
|
1637
|
+
`receipts`, `counts`, `failures` with vendor source IDs, `excluded`, `verified`, and
|
|
1638
|
+
`unacknowledged`. A lost response can mean unacknowledged findings were accepted;
|
|
1639
|
+
resume the saved submission rather than treating them as never uploaded. When
|
|
1640
|
+
available, `savedSubmission` identifies the checkpoint to resume by repeating the
|
|
1641
|
+
same command. Review `error` before retrying; a repository reset retires the old
|
|
1642
|
+
submission and requires fresh approval. Correct local exclusions or final source
|
|
1643
|
+
conflicts before preparing a new submission.
|
|
1644
|
+
|
|
1645
|
+
Counts are cumulative for the saved submission: a resumed result includes
|
|
1646
|
+
batches acknowledged by earlier invocations, not just the latest upload attempt.
|
|
1647
|
+
|
|
1648
|
+
Terminal progress reports preparation, acknowledged uploads, and verification
|
|
1649
|
+
on stderr; JSON results stay on stdout. Lookups and readback use at most four
|
|
1650
|
+
concurrent requests, while uploads remain sequential. Successful receipts are
|
|
1651
|
+
saved locally. Verification reads the imported source records and checks their
|
|
1652
|
+
identities and evidence against the receipts. This does not establish a Codex
|
|
1653
|
+
assessment or visibility in the shared Cloud Findings view.
|
|
1654
|
+
When available, `cloudUrl` links to the destination repository in Cloud.
|
|
1655
|
+
|
|
1656
|
+
### Publish completed scans
|
|
1657
|
+
|
|
1113
1658
|
Preview selected completed scans before uploading:
|
|
1114
1659
|
|
|
1115
1660
|
```bash
|
|
@@ -1218,16 +1763,31 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
|
|
|
1218
1763
|
codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
1219
1764
|
```
|
|
1220
1765
|
|
|
1221
|
-
For repository-free canonical records, use `classify-severity --records`
|
|
1766
|
+
For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
|
|
1222
1767
|
The [records protocol](classify-severity-records.md) accepts immutable Markdown and
|
|
1223
1768
|
report snapshots and delegates model execution to the host.
|
|
1224
1769
|
|
|
1225
1770
|
For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
|
|
1226
|
-
Omitting `--rubric`
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1771
|
+
Omitting `--rubric` runs classification with the [built-in severity rubric](../src/default-severity-rubric.ts).
|
|
1772
|
+
It evaluates attacker access, boundary crossing, additional harm, and evidence for
|
|
1773
|
+
Critical, High, Medium, Low, and Informational findings. Confidence remains separate
|
|
1774
|
+
from severity; missing proof alone does not justify a downgrade. An explicit
|
|
1775
|
+
`--rubric` replaces the default policy completely. Rubrics and repeatable
|
|
1776
|
+
`--knowledge-base` context accept text, PDF, DOCX, and directories.
|
|
1777
|
+
Each finding is classified three times by default. `--runs N` accepts
|
|
1778
|
+
an integer from 1 through 10; SDK options use `classificationRuns` with the same
|
|
1779
|
+
default and bounds. Each review runs in an independent read-only turn using the
|
|
1780
|
+
same report, rubric, and supplied context, without tools or source inspection.
|
|
1781
|
+
The most common normalized severity wins; the highest among tied top counts wins
|
|
1782
|
+
(`critical` > `high` > `medium` > `low` > `informational`). Exclusion is a separate
|
|
1783
|
+
vote: exclusions can win by count, but lose ties to assessed severities. The first answer matching the winner supplies its label, rationale,
|
|
1784
|
+
confidence, and review trigger. All requested reviews must succeed; failures or invalid
|
|
1785
|
+
answers fail that finding without saving a partial vote. This uses the requested number of model
|
|
1786
|
+
calls per uncached finding (three by default), including when no custom rubric is supplied, and
|
|
1787
|
+
requires the same Codex authentication and model access as custom classification.
|
|
1788
|
+
Codex retains usage for each independent turn. There is no fallback to scanner
|
|
1789
|
+
severity if classification fails.
|
|
1790
|
+
`--model` and `--effort` override Codex's configured model and the default medium effort.
|
|
1231
1791
|
|
|
1232
1792
|
Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,
|
|
1233
1793
|
the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
|
|
@@ -1235,10 +1795,17 @@ missing facts that could change the result. Exclusions have a null level.
|
|
|
1235
1795
|
Finding/occurrence IDs and input hashes bind each assessment to its evidence.
|
|
1236
1796
|
|
|
1237
1797
|
Successful assessments checkpoint immediately in local SQLite. Retries reuse
|
|
1238
|
-
matching evidence, rubric, and
|
|
1239
|
-
work.
|
|
1240
|
-
|
|
1241
|
-
|
|
1798
|
+
matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
|
|
1799
|
+
work. Default-rubric assessments use `source: "rubric"` and a content hash; former
|
|
1800
|
+
no-rubric inherited assessments have no rubric hash and are automatically
|
|
1801
|
+
reclassified on the next classification run. Changes to the bundled policy or
|
|
1802
|
+
switching between default and custom policies also invalidate matching checkpoints.
|
|
1803
|
+
The result and checkpoint record `classificationRuns`; changing the count, or
|
|
1804
|
+
reusing an older checkpoint with no recorded count, triggers fresh classification.
|
|
1805
|
+
Older results remain readable; publication does not silently run a model.
|
|
1806
|
+
Use `--reprocess` to replace assessments, including when changing only model
|
|
1807
|
+
or effort. A successful
|
|
1808
|
+
run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
|
|
1242
1809
|
unchanged.
|
|
1243
1810
|
|
|
1244
1811
|
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
|
|
@@ -1309,8 +1876,9 @@ await publishScan(scanDirectory, {
|
|
|
1309
1876
|
```
|
|
1310
1877
|
|
|
1311
1878
|
`classifySeverity()` accepts `findingId`, `title`, `summary`, and available
|
|
1312
|
-
evidence/metadata. Imported reports may lack severity or occurrence IDs;
|
|
1313
|
-
|
|
1879
|
+
evidence/metadata. Imported reports may lack severity or occurrence IDs; omitting
|
|
1880
|
+
`rubricPath` uses the built-in policy even when a scanner severity is present.
|
|
1881
|
+
Scan wrappers persist checkpoints (including for
|
|
1314
1882
|
external directories), accept `reprocess: true`, and treat `findingIds: []` as an
|
|
1315
1883
|
empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
|
|
1316
1884
|
publication. Older JSON-only assessments need reclassification once. All
|
|
@@ -1422,6 +1990,7 @@ least eight characters.
|
|
|
1422
1990
|
| `scans match --all` | Match completed scans across worktrees/clones. |
|
|
1423
1991
|
| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
|
|
1424
1992
|
| `findings list [REPOSITORY]` | List open findings. |
|
|
1993
|
+
| `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
|
|
1425
1994
|
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
|
|
1426
1995
|
|
|
1427
1996
|
Without an ID, `scans show` selects the latest completed scan, while `scans logs`
|
|
@@ -1451,6 +2020,9 @@ scan and custom-validation prompts when the original used them:
|
|
|
1451
2020
|
codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
|
|
1452
2021
|
```
|
|
1453
2022
|
|
|
2023
|
+
Saved path scopes remain relative to the repository. Names such as `~` and
|
|
2024
|
+
`~/source.ts` are replayed literally; they do not select the home directory.
|
|
2025
|
+
|
|
1454
2026
|
A rerun creates a new scan. When the original has saved input identities, the
|
|
1455
2027
|
rerun reports changes to the scan instructions or knowledge base. `scans show`
|
|
1456
2028
|
includes the saved scope, runtime and Deep Scan settings, instruction digest,
|
|
@@ -1704,6 +2276,158 @@ record absolute Node/CLI paths. If those change, back up and remove the verified
|
|
|
1704
2276
|
generated hook, then reinstall with the same threshold. Restore the backup if
|
|
1705
2277
|
installation fails. The installer respects `core.hooksPath`.
|
|
1706
2278
|
|
|
2279
|
+
## Import GitHub findings locally or to Cloud
|
|
2280
|
+
|
|
2281
|
+
Acquire code-scanning findings with the existing `import github` collector and
|
|
2282
|
+
save its complete JSON output. In Codex, the official
|
|
2283
|
+
[GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
|
|
2284
|
+
can help select the repository, alert numbers and ref through GitHub's MCP
|
|
2285
|
+
server; pass that selection to the collector. This integration reads
|
|
2286
|
+
code-scanning alerts and GHSA advisories. It does not import Dependabot or
|
|
2287
|
+
secret-scanning alerts or write back to GitHub. Preview local storage with a
|
|
2288
|
+
repository path:
|
|
2289
|
+
|
|
2290
|
+
```bash
|
|
2291
|
+
codex-security import github example/project --format json > /path/outside/repository/alerts.json
|
|
2292
|
+
codex-security publish findings /path/outside/repository/alerts.json \
|
|
2293
|
+
--to local --provider github --repository ./project \
|
|
2294
|
+
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
2295
|
+
```
|
|
2296
|
+
|
|
2297
|
+
Or preview publication to a connected Cloud repository:
|
|
2298
|
+
|
|
2299
|
+
```bash
|
|
2300
|
+
codex-security publish findings /path/outside/repository/alerts.json \
|
|
2301
|
+
--to cloud --provider github --repository https://github.com/example/project \
|
|
2302
|
+
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
2303
|
+
```
|
|
2304
|
+
|
|
2305
|
+
The importer fetches every page, retrieves alert details, and retains the selected
|
|
2306
|
+
ref's instance. It writes the saved input for publication; no website download or
|
|
2307
|
+
hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
|
|
2308
|
+
selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
|
|
2309
|
+
the default branch. MCP list calls are paginated separately, and raw MCP/API
|
|
2310
|
+
responses are not the saved import format accepted by `--provider github`.
|
|
2311
|
+
|
|
2312
|
+
The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
|
|
2313
|
+
the plugin's connection does not sign in `gh`. Reading alerts requires
|
|
2314
|
+
[code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
|
|
2315
|
+
**Code scanning alerts: read** for a fine-grained token, or `security_events` for
|
|
2316
|
+
a classic token (`public_repo` is sufficient for public repositories). The source
|
|
2317
|
+
repository must have code scanning available. For Cloud publication, the
|
|
2318
|
+
destination must be connected in the selected Cloud account. For local import,
|
|
2319
|
+
the source repository must match a configured Git remote when remotes are
|
|
2320
|
+
available; no Cloud login is required to store the acquired evidence.
|
|
2321
|
+
|
|
2322
|
+
Review the destination, source, exclusions and evidence in the preview. Repeat the
|
|
2323
|
+
selected command without `--dry-run` and confirm it, or add `--yes` for a
|
|
2324
|
+
previously reviewed input. Local persistence and readback follow the
|
|
2325
|
+
[local import flow](#import-vendor-findings-locally); use
|
|
2326
|
+
`codex-security findings imported ./project --format json` to read the records.
|
|
2327
|
+
Cloud authentication, batching, saved receipts, partial results and
|
|
2328
|
+
interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
|
|
2329
|
+
JSON, JSONL and gzip are supported. Save complete import output without field or
|
|
2330
|
+
token filters or `--full-output`.
|
|
2331
|
+
|
|
2332
|
+
Use a stable source key for the GitHub host, repository and finding family.
|
|
2333
|
+
Code-scanning identities include the selected ref, so branches retain separate
|
|
2334
|
+
evidence. The original alert, rule, scanner, location, revision and source state
|
|
2335
|
+
remain attached. An alert-wide dismissal takes precedence over the selected
|
|
2336
|
+
instance's open/fixed state. Missing security severity stays `unknown`;
|
|
2337
|
+
SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
|
|
2338
|
+
remains unassessed by Codex.
|
|
2339
|
+
|
|
2340
|
+
The SDK offers the same preview and publication boundary for Cloud:
|
|
2341
|
+
|
|
2342
|
+
```ts
|
|
2343
|
+
import {
|
|
2344
|
+
importGitHubCodeScanningAlerts,
|
|
2345
|
+
normalizeGitHubCodeScanningAlerts,
|
|
2346
|
+
prepareNormalizedExternalPublication,
|
|
2347
|
+
} from "@openai/codex-security";
|
|
2348
|
+
|
|
2349
|
+
const alerts = await importGitHubCodeScanningAlerts({
|
|
2350
|
+
repository: "example/project",
|
|
2351
|
+
});
|
|
2352
|
+
const prepared = await prepareNormalizedExternalPublication(
|
|
2353
|
+
normalizeGitHubCodeScanningAlerts(alerts),
|
|
2354
|
+
{
|
|
2355
|
+
provider: "github",
|
|
2356
|
+
repository: "https://github.com/example/project",
|
|
2357
|
+
sourceKey: "github.com/example/project/code-scanning",
|
|
2358
|
+
},
|
|
2359
|
+
);
|
|
2360
|
+
console.log(prepared.preview);
|
|
2361
|
+
// After reviewing the preview:
|
|
2362
|
+
const receipt = await prepared.publish();
|
|
2363
|
+
```
|
|
2364
|
+
|
|
2365
|
+
For local storage, pass the same normalized evidence to
|
|
2366
|
+
`prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
|
|
2367
|
+
its preview, and call `import()`. `prepareLocalExternalImport()` accepts the saved
|
|
2368
|
+
import file directly. Read records with `listLocalExternalFindings({ repository })`.
|
|
2369
|
+
|
|
2370
|
+
### Import GHSA advisories separately
|
|
2371
|
+
|
|
2372
|
+
**Importing a GHSA advisory does not establish an installed dependency or
|
|
2373
|
+
applicability to the destination repository.** Repository advisories are
|
|
2374
|
+
disclosures maintained by a repository; global advisories describe affected
|
|
2375
|
+
software in GitHub's public advisory database. Both are evidence for
|
|
2376
|
+
investigation, not Dependabot alerts. Check the repository’s dependency versions
|
|
2377
|
+
and applicability separately.
|
|
2378
|
+
|
|
2379
|
+
```bash
|
|
2380
|
+
# Read only published advisories for this repository.
|
|
2381
|
+
codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
|
|
2382
|
+
|
|
2383
|
+
# Select individual public database records without enumerating the database.
|
|
2384
|
+
codex-security import github-advisories example/project \
|
|
2385
|
+
--github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
|
|
2386
|
+
--format json > /path/outside/repository/advisories.json
|
|
2387
|
+
|
|
2388
|
+
codex-security publish findings /path/outside/repository/advisories.json \
|
|
2389
|
+
--to cloud --provider github --repository https://github.com/example/project \
|
|
2390
|
+
--source-key github.com/example/project/security-advisories --dry-run --format json
|
|
2391
|
+
```
|
|
2392
|
+
|
|
2393
|
+
For local storage, use the same advisory file, provider and source key with
|
|
2394
|
+
`--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
|
|
2395
|
+
to review, confirm and read the stored evidence.
|
|
2396
|
+
|
|
2397
|
+
`--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
|
|
2398
|
+
to select exact IDs from that API, regardless of advisory state. Repository
|
|
2399
|
+
lists default to `--github-state published`; `draft`, `triage`, and `closed`
|
|
2400
|
+
require explicit selection. A nondefault state cannot be combined with exact
|
|
2401
|
+
IDs. Global selection requires at least one ID and never lists the advisory
|
|
2402
|
+
database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
|
|
2403
|
+
the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
|
|
2404
|
+
[repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
|
|
2405
|
+
require **Repository security advisories: read**, or the classic `repo` or
|
|
2406
|
+
`repository_advisories:read` scope, plus access to the advisory. Public records
|
|
2407
|
+
need no additional advisory permission.
|
|
2408
|
+
|
|
2409
|
+
Review the saved evidence before local import or Cloud publication, including any
|
|
2410
|
+
selected private advisories. Acquisition failure returns no partial selection.
|
|
2411
|
+
Both destinations report invalid records as exclusions. Cloud publication retains
|
|
2412
|
+
acknowledged receipts if a later batch or readback fails.
|
|
2413
|
+
|
|
2414
|
+
Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
|
|
2415
|
+
patched versions, source status and original JSON. It does not infer an installed
|
|
2416
|
+
version or source location. Global advisories omit a source repository; the
|
|
2417
|
+
explicit local or Cloud destination binds the import for investigation. Repository
|
|
2418
|
+
advisories retain their source repository and check it against the Cloud target
|
|
2419
|
+
or configured local Git remotes when available. Withdrawal remains vendor
|
|
2420
|
+
state, and all imported evidence remains not assessed by Codex. Use a separate
|
|
2421
|
+
source key from code-scanning alerts; shared advisory IDs do not combine source
|
|
2422
|
+
records from different providers.
|
|
2423
|
+
|
|
2424
|
+
In the SDK, call `importGitHubAdvisories()` and `normalizeGitHubAdvisories()`
|
|
2425
|
+
with `prepareNormalizedExternalPublication()` for Cloud or
|
|
2426
|
+
`prepareNormalizedLocalImport()` for local storage as described above.
|
|
2427
|
+
`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
|
|
2428
|
+
`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
|
|
2429
|
+
records. Both forms require `repository: "OWNER/REPO"` as source or target context.
|
|
2430
|
+
|
|
1707
2431
|
## Import alerts from the CLI
|
|
1708
2432
|
|
|
1709
2433
|
```bash
|
|
@@ -1768,6 +2492,9 @@ validation, and `patch` still fixes and verifies findings. Both commands accept
|
|
|
1768
2492
|
or literal text and work in the current directory. Saved finding/occurrence IDs
|
|
1769
2493
|
select their original repository for patching.
|
|
1770
2494
|
|
|
2495
|
+
Basic patching also works in ordinary directories and Git worktrees before their
|
|
2496
|
+
first commit. Directory change tracking excludes `.git` and `.svn` metadata.
|
|
2497
|
+
|
|
1771
2498
|
```bash
|
|
1772
2499
|
codex-security validate "Possible SQL injection" --effort high
|
|
1773
2500
|
codex-security validate findings.json --knowledge-base ./context --context "Check the tenant boundary."
|
|
@@ -1897,6 +2624,18 @@ text/files, and Linear inputs. Paths resolve from the invocation directory, even
|
|
|
1897
2624
|
when the finding belongs to another repository. The file must be nonempty and
|
|
1898
2625
|
regular, is read before patching, and cannot combine with `--resume-pr`.
|
|
1899
2626
|
|
|
2627
|
+
Use `--verification-mode static` to assess a patch from source and diff evidence
|
|
2628
|
+
without installing dependencies or running builds, tests, reproducers, or the
|
|
2629
|
+
application. Validation instructions become questions for that source review.
|
|
2630
|
+
The default is `standard`, which retains the existing verification checks.
|
|
2631
|
+
Static results identify the evidence and state that runtime checks were not
|
|
2632
|
+
performed; material proof gaps can still block verification.
|
|
2633
|
+
|
|
2634
|
+
```bash
|
|
2635
|
+
codex-security patch finding.md --verification-mode static
|
|
2636
|
+
codex-security verify-fix finding.md --verification-mode static
|
|
2637
|
+
```
|
|
2638
|
+
|
|
1900
2639
|
`--assess-patch-risk` runs an advisory assessment after patching. Human-readable
|
|
1901
2640
|
output prints its report; saved-finding JSON includes `patchRisk.report`.
|
|
1902
2641
|
With `--create-pr`, the draft description includes the concise Markdown summary.
|
|
@@ -1960,6 +2699,9 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
|
|
|
1960
2699
|
finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
|
|
1961
2700
|
filter for completed Linear issues to check a finished backlog.
|
|
1962
2701
|
|
|
2702
|
+
`--verification-mode static` selects source-only assessment, as described above
|
|
2703
|
+
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
2704
|
+
|
|
1963
2705
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
1964
2706
|
`--json` returns structured output. Exit codes are `0` when all findings are
|
|
1965
2707
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|