@openai/codex-security 0.9.1 → 0.10.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 +37 -788
- package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
- package/_bundled_plugin/.mcp.json +2 -0
- package/_bundled_plugin/mcp/helpers.mjs.br +0 -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/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 +0 -0
- package/_bundled_plugin/references/artifact-storage.md +1 -1
- package/_bundled_plugin/references/baseline-auditor.md +18 -0
- package/_bundled_plugin/references/core-scan.md +5 -42
- package/_bundled_plugin/references/final-report.md +1 -1
- package/_bundled_plugin/references/focused-investigator.md +13 -0
- package/_bundled_plugin/references/scan-prologue.md +2 -2
- package/_bundled_plugin/references/scan-runtime.md +4 -2
- package/_bundled_plugin/references/security-guidance.md +14 -1
- package/_bundled_plugin/references/validate-scan-findings.md +3 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +29 -12
- package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +29 -3
- package/_bundled_plugin/scripts/launch_codex_security_mcp +54 -16
- package/_bundled_plugin/scripts/posix_scan_local_files.py +26 -1
- package/_bundled_plugin/scripts/snapshot_sqlite.py +8 -2
- package/_bundled_plugin/scripts/windows_scan_local_files.py +216 -25
- package/_bundled_plugin/scripts/workbench/handoff.py +55 -25
- package/_bundled_plugin/scripts/workbench/storage.py +25 -5
- package/_bundled_plugin/scripts/workbench_cli.py +24 -2
- package/_bundled_plugin/scripts/workbench_constants.py +2 -0
- package/_bundled_plugin/scripts/workbench_db.py +244 -217
- package/_bundled_plugin/scripts/workbench_feedback.py +49 -4
- package/_bundled_plugin/scripts/workbench_native_indexes.py +226 -29
- package/_bundled_plugin/scripts/workbench_progress.py +159 -3
- package/_bundled_plugin/scripts/workbench_publication.py +2 -3
- package/_bundled_plugin/scripts/workbench_remediation.py +142 -2
- package/_bundled_plugin/scripts/workbench_saved_results.py +48 -8
- package/_bundled_plugin/scripts/workbench_scan_history.py +281 -119
- package/_bundled_plugin/scripts/workbench_scan_start.py +143 -9
- package/_bundled_plugin/scripts/workbench_scan_usage.py +36 -10
- package/_bundled_plugin/scripts/workbench_schema.py +220 -14
- package/_bundled_plugin/scripts/workbench_setup.py +1 -1
- package/_bundled_plugin/scripts/workbench_target.py +471 -84
- package/_bundled_plugin/scripts/workbench_target_state.py +1108 -22
- package/_bundled_plugin/shared/workbench-history-repairs.json +60 -14
- package/_bundled_plugin/shared/workbench-migrations.json +66 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -0
- package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -160
- package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +2 -2
- package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +3 -58
- package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
- package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
- package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
- package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
- package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
- package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
- package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
- package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
- package/bin/codex-security.mjs +2 -2
- package/dist/api.d.ts +6 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +437 -154
- package/dist/api.js.map +1 -1
- package/dist/armorcode-findings.d.ts +9 -0
- package/dist/armorcode-findings.d.ts.map +1 -0
- package/dist/armorcode-findings.js +145 -0
- package/dist/armorcode-findings.js.map +1 -0
- package/dist/artifact-export.d.ts +2 -0
- package/dist/artifact-export.d.ts.map +1 -1
- package/dist/artifact-export.js +29 -13
- package/dist/artifact-export.js.map +1 -1
- package/dist/auth.d.ts +6 -2
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +33 -12
- package/dist/auth.js.map +1 -1
- package/dist/batch-cost.d.ts +18 -0
- package/dist/batch-cost.d.ts.map +1 -0
- package/dist/batch-cost.js +41 -0
- package/dist/batch-cost.js.map +1 -0
- package/dist/blackduck-findings.d.ts +1 -1
- package/dist/blackduck-findings.d.ts.map +1 -1
- package/dist/blackduck-findings.js +5 -18
- package/dist/blackduck-findings.js.map +1 -1
- package/dist/bundled-plugin.d.ts +4 -0
- package/dist/bundled-plugin.d.ts.map +1 -0
- package/dist/bundled-plugin.js +23 -0
- package/dist/bundled-plugin.js.map +1 -0
- package/dist/classify-scan-severity.d.ts +1 -1
- package/dist/classify-scan-severity.d.ts.map +1 -1
- package/dist/classify-scan-severity.js +11 -3
- package/dist/classify-scan-severity.js.map +1 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +9 -6
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-argument.d.ts +4 -0
- package/dist/cli-argument.d.ts.map +1 -0
- package/dist/cli-argument.js +17 -0
- package/dist/cli-argument.js.map +1 -0
- package/dist/cli-help.d.ts +1 -1
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +71 -29
- package/dist/cli-help.js.map +1 -1
- package/dist/cli-hook.d.ts +3 -0
- package/dist/cli-hook.d.ts.map +1 -0
- package/dist/cli-hook.js +87 -0
- package/dist/cli-hook.js.map +1 -0
- package/dist/cli-integrations.d.ts +13 -0
- package/dist/cli-integrations.d.ts.map +1 -0
- package/dist/cli-integrations.js +333 -0
- package/dist/cli-integrations.js.map +1 -0
- package/dist/cli-mcp.d.ts +15 -0
- package/dist/cli-mcp.d.ts.map +1 -0
- package/dist/cli-mcp.js +178 -0
- package/dist/cli-mcp.js.map +1 -0
- package/dist/cli-token-view.d.ts +10 -0
- package/dist/cli-token-view.d.ts.map +1 -0
- package/dist/cli-token-view.js +41 -0
- package/dist/cli-token-view.js.map +1 -0
- package/dist/cli.d.ts +5 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1763 -894
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +33 -31
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codex-sdk-environment.d.ts +6 -0
- package/dist/codex-sdk-environment.d.ts.map +1 -1
- package/dist/codex-sdk-environment.js +19 -0
- package/dist/codex-sdk-environment.js.map +1 -1
- package/dist/command-words.d.ts +3 -0
- package/dist/command-words.d.ts.map +1 -0
- package/dist/command-words.js +46 -0
- package/dist/command-words.js.map +1 -0
- package/dist/component-scan.d.ts +3 -1
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +40 -7
- package/dist/component-scan.js.map +1 -1
- package/dist/config.d.ts +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +30 -1
- package/dist/config.js.map +1 -1
- package/dist/continuum-findings.d.ts +1 -1
- package/dist/continuum-findings.d.ts.map +1 -1
- package/dist/continuum-findings.js +93 -31
- package/dist/continuum-findings.js.map +1 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +1 -45
- package/dist/cost.js.map +1 -1
- package/dist/custom-validation-prompt.d.ts +1 -1
- package/dist/custom-validation-prompt.d.ts.map +1 -1
- package/dist/custom-validation-prompt.js +29 -19
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/local.d.ts +3 -1
- package/dist/deduplication/local.d.ts.map +1 -1
- package/dist/deduplication/local.js +8 -1
- package/dist/deduplication/local.js.map +1 -1
- package/dist/deduplication/refusal.d.ts.map +1 -1
- package/dist/deduplication/refusal.js +2 -1
- package/dist/deduplication/refusal.js.map +1 -1
- package/dist/deduplication/scan.d.ts +2 -0
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +24 -7
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-scan.d.ts.map +1 -1
- package/dist/deep-scan.js +16 -15
- package/dist/deep-scan.js.map +1 -1
- package/dist/endor-findings.d.ts +2 -2
- package/dist/endor-findings.d.ts.map +1 -1
- package/dist/endor-findings.js +6 -23
- package/dist/endor-findings.js.map +1 -1
- package/dist/errors.d.ts +3 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +7 -3
- package/dist/errors.js.map +1 -1
- package/dist/executable-path.d.ts +3 -0
- package/dist/executable-path.d.ts.map +1 -1
- package/dist/executable-path.js +26 -0
- package/dist/executable-path.js.map +1 -1
- package/dist/external-findings-import.d.ts.map +1 -1
- package/dist/external-findings-import.js +12 -1
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts +66 -4
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +234 -53
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +6 -1
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +326 -1633
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +1 -0
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +31 -51
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +1 -1
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js +12 -1
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +3 -11
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +29 -176
- package/dist/external-import-contract.js.map +1 -1
- package/dist/external-import-models.d.ts +1 -1
- package/dist/external-import-models.d.ts.map +1 -1
- package/dist/external-import-models.js.map +1 -1
- package/dist/finding-prompt.d.ts.map +1 -1
- package/dist/finding-prompt.js +2 -2
- package/dist/finding-prompt.js.map +1 -1
- package/dist/github-dependabot-findings.d.ts.map +1 -1
- package/dist/github-dependabot-findings.js +3 -4
- package/dist/github-dependabot-findings.js.map +1 -1
- package/dist/github-findings.d.ts.map +1 -1
- package/dist/github-findings.js +19 -287
- package/dist/github-findings.js.map +1 -1
- package/dist/hosted-remediation.d.ts +1 -0
- package/dist/hosted-remediation.d.ts.map +1 -1
- package/dist/hosted-remediation.js +23 -3
- package/dist/hosted-remediation.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/inspector-findings.d.ts.map +1 -1
- package/dist/inspector-findings.js +19 -35
- package/dist/inspector-findings.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 +34 -27
- package/dist/knowledge-base.js.map +1 -1
- package/dist/linear.d.ts +11 -0
- package/dist/linear.d.ts.map +1 -1
- package/dist/linear.js.map +1 -1
- package/dist/local-git-metadata.d.ts +5 -2
- package/dist/local-git-metadata.d.ts.map +1 -1
- package/dist/local-git-metadata.js +8 -4
- package/dist/local-git-metadata.js.map +1 -1
- package/dist/multiscan.d.ts +4 -0
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +79 -37
- package/dist/multiscan.js.map +1 -1
- package/dist/opengrep-findings.d.ts +4 -2
- package/dist/opengrep-findings.d.ts.map +1 -1
- package/dist/opengrep-findings.js +39 -22
- package/dist/opengrep-findings.js.map +1 -1
- package/dist/private-finding-import.d.ts +8 -13
- package/dist/private-finding-import.d.ts.map +1 -1
- package/dist/private-finding-import.js +69 -129
- package/dist/private-finding-import.js.map +1 -1
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +53 -13
- package/dist/project-config.js.map +1 -1
- package/dist/prompt-files.d.ts +7 -2
- package/dist/prompt-files.d.ts.map +1 -1
- package/dist/prompt-files.js +42 -20
- package/dist/prompt-files.js.map +1 -1
- package/dist/provider-profile.d.ts.map +1 -1
- package/dist/provider-profile.js +4 -9
- package/dist/provider-profile.js.map +1 -1
- package/dist/publication.d.ts +1 -1
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js.map +1 -1
- package/dist/record.d.ts +1 -5
- package/dist/record.d.ts.map +1 -1
- package/dist/record.js +3 -51
- package/dist/record.js.map +1 -1
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +3 -1
- package/dist/remediation.js.map +1 -1
- package/dist/runtime.d.ts +35 -7
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +778 -153
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan-bootstrap.d.ts +6 -1
- package/dist/saved-scan-bootstrap.d.ts.map +1 -1
- package/dist/saved-scan-bootstrap.js +267 -115
- package/dist/saved-scan-bootstrap.js.map +1 -1
- package/dist/scan-archive-path.d.ts +2 -0
- package/dist/scan-archive-path.d.ts.map +1 -0
- package/dist/scan-archive-path.js +5 -0
- package/dist/scan-archive-path.js.map +1 -0
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +6 -2
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +1 -0
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +18 -2
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-executor.d.ts.map +1 -1
- package/dist/scan-executor.js +4 -2
- package/dist/scan-executor.js.map +1 -1
- package/dist/scan-history-renderer.d.ts +1 -0
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +25 -9
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +28 -4
- package/dist/scan-logs.js.map +1 -1
- package/dist/scanner-import.d.ts +5 -11
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +16 -89
- package/dist/scanner-import.js.map +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +26 -6
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts.map +1 -1
- package/dist/semgrep-findings.js +14 -48
- package/dist/semgrep-findings.js.map +1 -1
- package/dist/semgrep-platform-findings.d.ts +20 -70
- package/dist/semgrep-platform-findings.d.ts.map +1 -1
- package/dist/semgrep-platform-findings.js +116 -333
- package/dist/semgrep-platform-findings.js.map +1 -1
- package/dist/snyk-findings.d.ts +2 -0
- package/dist/snyk-findings.d.ts.map +1 -1
- package/dist/snyk-findings.js +5 -8
- package/dist/snyk-findings.js.map +1 -1
- package/dist/snyk-rest-findings.d.ts +3 -20
- package/dist/snyk-rest-findings.d.ts.map +1 -1
- package/dist/snyk-rest-findings.js +45 -217
- package/dist/snyk-rest-findings.js.map +1 -1
- package/dist/sonar-findings.d.ts +1 -1
- package/dist/sonar-findings.d.ts.map +1 -1
- package/dist/sonar-findings.js +2 -4
- package/dist/sonar-findings.js.map +1 -1
- package/dist/sonar-import.d.ts +3 -0
- package/dist/sonar-import.d.ts.map +1 -1
- package/dist/sonar-import.js +28 -30
- package/dist/sonar-import.js.map +1 -1
- package/dist/stored-finding-projection.d.ts +6 -0
- package/dist/stored-finding-projection.d.ts.map +1 -0
- package/dist/stored-finding-projection.js +104 -0
- package/dist/stored-finding-projection.js.map +1 -0
- package/dist/stored-findings-publication.d.ts +23 -0
- package/dist/stored-findings-publication.d.ts.map +1 -0
- package/dist/stored-findings-publication.js +169 -0
- package/dist/stored-findings-publication.js.map +1 -0
- package/dist/targets.d.ts +6 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +76 -23
- package/dist/targets.js.map +1 -1
- package/dist/tenable-findings.d.ts +1 -4
- package/dist/tenable-findings.d.ts.map +1 -1
- package/dist/tenable-findings.js.map +1 -1
- package/dist/trivy-findings.d.ts.map +1 -1
- package/dist/trivy-findings.js +0 -11
- package/dist/trivy-findings.js.map +1 -1
- package/dist/trusted-executable.d.ts +6 -0
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +140 -37
- package/dist/trusted-executable.js.map +1 -1
- package/dist/veracode-findings.d.ts +1 -3
- package/dist/veracode-findings.d.ts.map +1 -1
- package/dist/veracode-findings.js +13 -38
- package/dist/veracode-findings.js.map +1 -1
- package/dist/version.d.ts +3 -1
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +184 -32
- package/dist/version.js.map +1 -1
- package/dist/wiz-findings.d.ts +2 -2
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +14 -92
- package/dist/wiz-findings.js.map +1 -1
- package/docs/cli.md +373 -106
- package/docs/findings-service.md +22 -9
- package/docs/hosted-remediation.md +13 -4
- package/docs/sdk.md +903 -0
- package/package.json +10 -6
- package/schemas/external-findings.schema.json +2 -1
- package/dist/hosted-scanner-v1.d.ts +0 -6
- package/dist/hosted-scanner-v1.d.ts.map +0 -1
- package/dist/hosted-scanner-v1.js +0 -60
- package/dist/hosted-scanner-v1.js.map +0 -1
- package/dist/reader-selection.d.ts +0 -15
- package/dist/reader-selection.d.ts.map +0 -1
- package/dist/reader-selection.js +0 -89
- package/dist/reader-selection.js.map +0 -1
- package/dist/semgrep-platform-v1.d.ts +0 -6
- package/dist/semgrep-platform-v1.d.ts.map +0 -1
- package/dist/semgrep-platform-v1.js +0 -83
- package/dist/semgrep-platform-v1.js.map +0 -1
- package/dist/snyk-rest-v1.d.ts +0 -28
- package/dist/snyk-rest-v1.d.ts.map +0 -1
- package/dist/snyk-rest-v1.js +0 -132
- package/dist/snyk-rest-v1.js.map +0 -1
package/docs/cli.md
CHANGED
|
@@ -14,7 +14,10 @@ codex-security info --json
|
|
|
14
14
|
|
|
15
15
|
`--help` lists commands by task; `<command> --help` lists its options.
|
|
16
16
|
`info --json` reports package, plugin, runtime, and model details.
|
|
17
|
-
`scans` and `findings` default to their `list` subcommands.
|
|
17
|
+
`scans` and `findings` default to their `list` subcommands. Global output options
|
|
18
|
+
can appear around a subcommand, for example `cs scans --json show`. Use `--`
|
|
19
|
+
after the command to pass the remaining words as literal positional arguments,
|
|
20
|
+
including file names that begin with a dash.
|
|
18
21
|
|
|
19
22
|
## Find a workflow
|
|
20
23
|
|
|
@@ -37,6 +40,26 @@ codex-security info --json
|
|
|
37
40
|
- [Use a hosted executor](#hosted-standard-scan) or
|
|
38
41
|
[run bulk scans in containers](#containerized-bulk-scans).
|
|
39
42
|
|
|
43
|
+
## Updating the CLI
|
|
44
|
+
|
|
45
|
+
Run `cs update` to update an npm global installation managed by the running
|
|
46
|
+
Node distribution. It uses Node’s bundled npm, the public npm registry, and
|
|
47
|
+
disabled lifecycle scripts. If you use a custom registry or proxy, run your
|
|
48
|
+
package manager’s update command directly.
|
|
49
|
+
|
|
50
|
+
The legacy `cs --update` spelling also works. Invoke the updater or the stdio
|
|
51
|
+
server (`cs --mcp`) on its own.
|
|
52
|
+
|
|
53
|
+
For a project dependency, `cs update` prints the package-manager command for
|
|
54
|
+
you to run in the declaring project. For other global installations it prints
|
|
55
|
+
the corresponding package-manager command and installation location. For npx,
|
|
56
|
+
use `npx @openai/codex-security@latest` on the next run. For a standalone
|
|
57
|
+
release, download and extract the latest release.
|
|
58
|
+
|
|
59
|
+
Interactive update notices use the same installation detection. Set
|
|
60
|
+
`CODEX_SECURITY_NO_UPDATE_NOTICE=1` to disable these notices. Explicit updates
|
|
61
|
+
are available with notifications disabled.
|
|
62
|
+
|
|
40
63
|
## Authentication
|
|
41
64
|
|
|
42
65
|
Sign in with ChatGPT, or supply an API key for CI:
|
|
@@ -139,6 +162,8 @@ If Codex Security reports that the refresh token was already used, run
|
|
|
139
162
|
`codex-security logout`, then `codex-security login`. If your Codex CLI or app
|
|
140
163
|
reports that error, sign out and sign back in there.
|
|
141
164
|
|
|
165
|
+
Use `codex-security login status --json` in automation. Its stdout reports `authenticated`, the effective authentication `method`, and the environment variable name when an API key takes precedence. When an API key takes precedence, stderr names the variable that configures it. This offline status check also labels the separate stored sign-in diagnostic. The command keeps the exit status of the human-readable status check.
|
|
166
|
+
|
|
142
167
|
For other refresh errors, check `codex-security login status`. Retry if the
|
|
143
168
|
sign-in recently changed. Otherwise run `codex-security logout`, then
|
|
144
169
|
`codex-security login`.
|
|
@@ -384,11 +409,11 @@ Add context with `--knowledge-base`:
|
|
|
384
409
|
codex-security policy . --knowledge-base architecture.md
|
|
385
410
|
```
|
|
386
411
|
|
|
387
|
-
| Invocation
|
|
388
|
-
|
|
|
389
|
-
| `policy . --
|
|
390
|
-
| `policy . --format md`
|
|
391
|
-
| `policy . --dry-run --json`
|
|
412
|
+
| Invocation | Result |
|
|
413
|
+
| --------------------------- | -------------------------------------------------------- |
|
|
414
|
+
| `policy . --json` | Generate without prompts; return paths and review notes. |
|
|
415
|
+
| `policy . --format md` | Generate and write the draft to stdout. |
|
|
416
|
+
| `policy . --dry-run --json` | Check local inputs without calling Codex. |
|
|
392
417
|
|
|
393
418
|
`--headless` leaves unanswered questions in the review notes. By default, files
|
|
394
419
|
go in the Codex Security state directory. To choose a location, use an empty
|
|
@@ -494,6 +519,10 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
|
|
|
494
519
|
requested work separately from optional `coverage.openQuestions` follow-up.
|
|
495
520
|
Human-readable output quotes ambiguous paths, while JSON retains their original strings.
|
|
496
521
|
|
|
522
|
+
A dry run reports `stateDirectory`, the root for saved scan state. It checks the
|
|
523
|
+
storage location without creating a scan directory. Pass boolean scan options
|
|
524
|
+
as bare flags or use lowercase `=true` or `=false`.
|
|
525
|
+
|
|
497
526
|
When a cost limit is configured, `scan --dry-run` shows the resolved
|
|
498
527
|
`maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
|
|
499
528
|
against the limit and why in-flight requests can exceed it.
|
|
@@ -509,7 +538,8 @@ be clean and at the commit recorded by the parent.
|
|
|
509
538
|
Committed-diff scans require a clean, full checkout at the requested head
|
|
510
539
|
revision, including when using `--validate`. A different checkout revision or
|
|
511
540
|
local changes are rejected before scanning; check out the requested head and
|
|
512
|
-
commit or stash local changes before retrying.
|
|
541
|
+
commit or stash local changes before retrying. The check also verifies tracked
|
|
542
|
+
files marked `assume-unchanged` and preserves their Git index flags.
|
|
513
543
|
|
|
514
544
|
`--owner-suggestions` writes optional `owner-suggestions.json` after a completed
|
|
515
545
|
committed Git scan, using the same checkout, model, and reasoning effort. Owner
|
|
@@ -524,7 +554,9 @@ Use the separate `suggest-owners` command for explicit owner-only jobs.
|
|
|
524
554
|
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
525
555
|
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
526
556
|
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
527
|
-
with every repository.
|
|
557
|
+
with every repository. Select external documents directly. Links in a checkout
|
|
558
|
+
must stay inside it. For bulk scans with bare or separate Git storage, use
|
|
559
|
+
canonical paths for shared documents and prompt files.
|
|
528
560
|
|
|
529
561
|
Use `--output-dir DIR` to choose where a scan saves its results. The directory
|
|
530
562
|
must be empty and outside the scanned directory and enclosing Git worktree.
|
|
@@ -538,7 +570,9 @@ through inheritance. Other users must not have permission to set reparse data
|
|
|
538
570
|
on the destination directory itself.
|
|
539
571
|
`--archive-existing` moves earlier output to a sibling directory with a unique
|
|
540
572
|
suffix, such as `results.previous-ab12cd34` for an output directory named
|
|
541
|
-
`results`.
|
|
573
|
+
`results`. If adding the suffix exceeds the filesystem's filename limit on POSIX,
|
|
574
|
+
the archive uses a short sibling name starting with `.previous-` and a hash of the
|
|
575
|
+
original filename. Use `--dry-run` to preview the move.
|
|
542
576
|
|
|
543
577
|
Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
|
|
544
578
|
optional export fails, the scan can still complete. Use the
|
|
@@ -595,8 +629,13 @@ available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an importe
|
|
|
595
629
|
scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
|
|
596
630
|
on stderr without `--full-output`, or when retained results are unavailable.
|
|
597
631
|
|
|
598
|
-
|
|
599
|
-
|
|
632
|
+
Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
|
|
633
|
+
envelope with `error.code` and `error.message`. Command schema validation errors
|
|
634
|
+
with JSON or JSONL retain their field details and name missing or invalid
|
|
635
|
+
options by their CLI flags. Diagnostics stay on stderr.
|
|
636
|
+
`scan --schema --format json` describes optional caller inputs before defaults
|
|
637
|
+
and the fields returned by preflight, completed scans, and execution failures,
|
|
638
|
+
including sealed results recovered after an interruption.
|
|
600
639
|
See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
601
640
|
|
|
602
641
|
### Follow-up finding validation
|
|
@@ -685,8 +724,8 @@ Choose the next step from the recorded reason:
|
|
|
685
724
|
start a new scan with the intended scope, including for plugin scans without
|
|
686
725
|
a recipe. Retained findings can still be reviewed, but absence of findings
|
|
687
726
|
from a stopped run is inconclusive.
|
|
688
|
-
- **A Deep Scan was interrupted and is still recorded as `running`:** it may
|
|
689
|
-
support [resume](#resuming-an-interrupted-
|
|
727
|
+
- **A Standard or Deep Scan was interrupted and is still recorded as `running`:** it may
|
|
728
|
+
support [resume](#resuming-an-interrupted-scan) with the original checkout,
|
|
690
729
|
artifacts, and session. Completed, failed, and canceled scans cannot resume.
|
|
691
730
|
|
|
692
731
|
For example, after identifying an omitted API directory:
|
|
@@ -731,16 +770,18 @@ from the config directory; scope paths resolve from the repository.
|
|
|
731
770
|
### Import findings as a saved scan
|
|
732
771
|
|
|
733
772
|
```bash
|
|
734
|
-
codex-security scan import
|
|
735
|
-
codex-security scan import
|
|
736
|
-
codex-security scan import
|
|
773
|
+
codex-security scan import /path/to/findings.csv
|
|
774
|
+
codex-security scan import /path/to/findings.json --json
|
|
775
|
+
codex-security scan import /path/to/report --input-format csv --dry-run
|
|
737
776
|
```
|
|
738
777
|
|
|
739
778
|
Supply exactly one input. CSV follows the
|
|
740
779
|
[findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
|
|
741
780
|
JSON accepts a complete `codex-security.findings` document or
|
|
742
|
-
`{ "findings": [...] }` matching the findings schema.
|
|
743
|
-
|
|
781
|
+
`{ "findings": [...] }` matching the findings schema. The CLI infers the format from a `.csv` or `.json` suffix.
|
|
782
|
+
Use `--input-format csv|json` to override it. Put `--json` after the filename
|
|
783
|
+
to request JSON output. Existing scripts using `--csv FILE` or `--json FILE`
|
|
784
|
+
can continue to select the input that way. The input must be a
|
|
744
785
|
regular file with no symlinks or directory junctions in its path.
|
|
745
786
|
|
|
746
787
|
Each import creates a completed scan in local history, retains the input under
|
|
@@ -821,6 +862,13 @@ codex-security scan-components . \
|
|
|
821
862
|
--output-dir /path/outside/project/results
|
|
822
863
|
```
|
|
823
864
|
|
|
865
|
+
`--plan-only` with `--component` or `--components-file` validates local paths
|
|
866
|
+
without signing in. The CLI prints a command to scan the saved plan into a fresh
|
|
867
|
+
`results` directory inside the plan directory. Running that command starts scans.
|
|
868
|
+
Run it from the original working directory to reuse relative paths. The command
|
|
869
|
+
includes the selected project configuration and scan flags. Reapply any inline
|
|
870
|
+
`--codex` overrides yourself, since these can contain credentials.
|
|
871
|
+
|
|
824
872
|
Plans use literal repository-relative paths, so `~/src` selects a directory
|
|
825
873
|
named `~` inside the repository rather than expanding the home directory.
|
|
826
874
|
Existing absolute paths inside the repository are also accepted.
|
|
@@ -850,9 +898,15 @@ failed matching return `2`; severity-policy violations return `1`. Retry with
|
|
|
850
898
|
The retry report covers only those components. Each registered component keeps its
|
|
851
899
|
scan ID in the summary, including when the scan fails.
|
|
852
900
|
|
|
853
|
-
`--max-cost` applies per component, excluding planning and matching.
|
|
854
|
-
|
|
855
|
-
|
|
901
|
+
`--max-cost` applies per component, excluding planning and matching.
|
|
902
|
+
Use `--max-total-cost USD` with explicit components to split one estimated
|
|
903
|
+
budget among them. The smaller of each component's share and its per-scan
|
|
904
|
+
limit applies. Findings stay separate because model-based matching is skipped.
|
|
905
|
+
The total limit also skips owner suggestions, including when enabled in project configuration.
|
|
906
|
+
Automatic planning and post-scan prompts must run separately.
|
|
907
|
+
|
|
908
|
+
`--model` and `--effort` also apply to matching. `--auth` applies throughout.
|
|
909
|
+
Planning and matching reject ambient command providers that conflict with explicit ChatGPT
|
|
856
910
|
or API-key auth. SDK-selected command providers retain their authentication.
|
|
857
911
|
|
|
858
912
|
From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
|
|
@@ -877,6 +931,7 @@ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
|
|
|
877
931
|
`markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
|
|
878
932
|
Markdown. A supplied snapshot takes precedence over a file.
|
|
879
933
|
|
|
934
|
+
A dry run reads and validates an explicit rubric before reporting a successful preflight.
|
|
880
935
|
The scan saves the rubric text in its local launch recipe. Retrying a Standard
|
|
881
936
|
scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
|
|
882
937
|
with a saved rubric reuses that copy even if the remote default or file changes.
|
|
@@ -901,7 +956,7 @@ behavior are unchanged.
|
|
|
901
956
|
|
|
902
957
|
The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
|
|
903
958
|
Each launched scan or rerun gets its own allowance after setup, and reconnects
|
|
904
|
-
do not reset it. Standard scans
|
|
959
|
+
do not reset it. [Resumed Standard scans](#resuming-an-interrupted-scan) keep the original deadline. For batch and
|
|
905
960
|
component scans, the project setting applies separately to each scan attempt,
|
|
906
961
|
not to planning, result matching, or the total campaign.
|
|
907
962
|
|
|
@@ -925,7 +980,7 @@ completed scans that added no findings. `--max-discovery-runs` caps the total
|
|
|
925
980
|
number started, including failures. `--max-time` stops discovery and returns
|
|
926
981
|
the findings from completed scans.
|
|
927
982
|
|
|
928
|
-
For TypeScript, see the [SDK Deep Scan example](
|
|
983
|
+
For TypeScript, see the [SDK Deep Scan example](sdk.md#configure-deep-scans).
|
|
929
984
|
|
|
930
985
|
Use project-file `scan.deep` settings or legacy
|
|
931
986
|
`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
|
|
@@ -981,7 +1036,9 @@ credentials, and workflow resume behavior.
|
|
|
981
1036
|
For `dedupe --scan latest`, matching across worktrees or clones requires a Git
|
|
982
1037
|
executable outside all saved scan targets. If a historical target includes the
|
|
983
1038
|
available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
|
|
984
|
-
explicit saved scan ID. Exact-path `latest` lookup
|
|
1039
|
+
explicit saved scan ID. Exact-path `latest` lookup works without Git for non-Git
|
|
1040
|
+
scan targets; recorded Git generations require a trusted Git executable to verify
|
|
1041
|
+
that the checkout still owns its saved history.
|
|
985
1042
|
|
|
986
1043
|
Repeat `--codex KEY=VALUE` for supported native settings. For example,
|
|
987
1044
|
`--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
|
|
@@ -1078,7 +1135,7 @@ client during the scan, or receiving a canceled hosted execution records
|
|
|
1078
1135
|
Applications can choose how to collect and export these observations.
|
|
1079
1136
|
|
|
1080
1137
|
For filesystem and approval behavior, see the
|
|
1081
|
-
[local security model](
|
|
1138
|
+
[local security model](sdk.md#local-security-model).
|
|
1082
1139
|
|
|
1083
1140
|
### Environment variables
|
|
1084
1141
|
|
|
@@ -1111,6 +1168,10 @@ Python lookup: `--python` on commands that expose interpreter selection or SDK
|
|
|
1111
1168
|
`pythonPath`, then
|
|
1112
1169
|
`PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
|
|
1113
1170
|
works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
|
|
1171
|
+
On POSIX, `CODEX_CLI_PATH` and `PYTHON` preserve trailing whitespace in an
|
|
1172
|
+
explicit path that selects an executable. Use an absolute path or a `./`
|
|
1173
|
+
prefix for filenames beginning or ending in whitespace. Bare command names
|
|
1174
|
+
are trimmed before lookup.
|
|
1114
1175
|
|
|
1115
1176
|
### Troubleshooting
|
|
1116
1177
|
|
|
@@ -1140,6 +1201,11 @@ and does not migrate existing credentials or reports.
|
|
|
1140
1201
|
Sandbox startup errors include the native diagnostic followed by a command to
|
|
1141
1202
|
reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
|
|
1142
1203
|
|
|
1204
|
+
If Windows Application Control blocks `windows.node` while validating a scan
|
|
1205
|
+
output directory, look for the module's block event in Event Viewer under
|
|
1206
|
+
Applications and Services Logs → Microsoft → Windows → CodeIntegrity → Operational.
|
|
1207
|
+
[Microsoft's App Control event reference](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/operations/event-id-explanations)
|
|
1208
|
+
|
|
1143
1209
|
On Windows, credential-home checks require trusted ownership and permissions
|
|
1144
1210
|
through every ancestor, including the volume root. Codex Security can repair
|
|
1145
1211
|
the credential home and its descendants; it does not change ancestor ownership
|
|
@@ -1219,8 +1285,9 @@ work is needed, the scan is preserved and you can run `scans match --all`.
|
|
|
1219
1285
|
|
|
1220
1286
|
A scan with a cost limit requires complete token usage for its recorded scan,
|
|
1221
1287
|
worker, and custom validation sessions before the SDK returns a completed result.
|
|
1222
|
-
|
|
1223
|
-
`backports.zstd`
|
|
1288
|
+
The workbench reads compressed `.jsonl.zst` sessions with `compression.zstd`
|
|
1289
|
+
(Python 3.14+) or `backports.zstd` when available. Otherwise it uses the
|
|
1290
|
+
Node.js decoder bundled with the plugin.
|
|
1224
1291
|
Missing or unreadable usage fails budget verification. Without a limit, usage
|
|
1225
1292
|
reporting remains best effort.
|
|
1226
1293
|
|
|
@@ -1314,7 +1381,8 @@ the campaign a joint source review across repositories. For that workflow, use
|
|
|
1314
1381
|
|
|
1315
1382
|
Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
|
|
1316
1383
|
selection. It lists repositories pushed in the last 90 days, excluding forks
|
|
1317
|
-
and archives, asks
|
|
1384
|
+
and archives, asks where to save results, and saves the selection as `repositories.csv`.
|
|
1385
|
+
Pass `--output-dir DIR` to set the initial answer in the wizard.
|
|
1318
1386
|
Private checkouts use your GitHub CLI login.
|
|
1319
1387
|
|
|
1320
1388
|
For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
|
|
@@ -1330,7 +1398,32 @@ codex-security bulk-scan repositories.csv \
|
|
|
1330
1398
|
--output-dir /path/outside/repositories/results --workers 4
|
|
1331
1399
|
```
|
|
1332
1400
|
|
|
1401
|
+
`--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
|
|
1402
|
+
estimated limit among the pending repositories and their possible attempts for
|
|
1403
|
+
this invocation, including recovery. For example, a $12 limit with three pending
|
|
1404
|
+
repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
|
|
1405
|
+
overrun reduces the remaining budget for queued attempts. In-flight work can
|
|
1406
|
+
exceed a limit. The total limit skips model-based matching and owner suggestions,
|
|
1407
|
+
including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
|
|
1408
|
+
limit and includes prior recorded usage in its cost estimate.
|
|
1409
|
+
|
|
1333
1410
|
Bulk scans use clean shallow checkouts and support repository/path scopes.
|
|
1411
|
+
Bulk checkout, scan, and recovery processes select host tools outside every local
|
|
1412
|
+
source and campaign checkout. Inventory uses an external ripgrep executable or
|
|
1413
|
+
the copy shipped with the selected Codex installation.
|
|
1414
|
+
|
|
1415
|
+
On POSIX, campaign processes and script-based inventory tools search readable
|
|
1416
|
+
tool directories. Launchers must be readable so their shebang interpreters can
|
|
1417
|
+
be checked. Use an absolute interpreter path for campaign scripts, including
|
|
1418
|
+
`#!/usr/bin/env sh`, because workers run in different directories. If a directory
|
|
1419
|
+
contains an ineligible executable, its other tools remain available through a
|
|
1420
|
+
temporary PATH. Scripts using the system `/bin/sh` or `/usr/bin/env` run from
|
|
1421
|
+
their installed location when the packaged dispatcher can start. Keep other
|
|
1422
|
+
prefix-sensitive tools, including Python virtual environments, in directories
|
|
1423
|
+
where every entry can be used. On Windows, the campaign omits a tool directory
|
|
1424
|
+
from the child PATH if its Git, ripgrep, or Node executable link passes through a
|
|
1425
|
+
selected source.
|
|
1426
|
+
|
|
1334
1427
|
CSV scopes are literal paths relative to each checkout, including names such
|
|
1335
1428
|
as `~/src`.
|
|
1336
1429
|
Configured diff or working-tree scopes are rejected unless every affected row
|
|
@@ -1361,6 +1454,12 @@ require a new output directory. Version 1 manifests also require a new directory
|
|
|
1361
1454
|
because their original knowledge inputs and direct overrides cannot be verified.
|
|
1362
1455
|
Worker and retry counts can change when resuming.
|
|
1363
1456
|
|
|
1457
|
+
On POSIX, local repository paths retain `..` components in the campaign manifest
|
|
1458
|
+
so distinct symlink traversals remain distinct sources. Older campaigns may have
|
|
1459
|
+
recorded a normalized absolute path instead. Use that recorded path to resume the
|
|
1460
|
+
previously selected source; it can differ from the physical target selected by
|
|
1461
|
+
the original traversal. Use a new output directory to scan the corrected target.
|
|
1462
|
+
|
|
1364
1463
|
### Recovering failed or interrupted bulk scans
|
|
1365
1464
|
|
|
1366
1465
|
Use the original CSV, output directory, and options:
|
|
@@ -1514,7 +1613,7 @@ SARIF compatibility, and the local preview.
|
|
|
1514
1613
|
|
|
1515
1614
|
## Import SonarQube Cloud issues
|
|
1516
1615
|
|
|
1517
|
-
`import sonar --dry-run` writes a private
|
|
1616
|
+
`import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
|
|
1518
1617
|
that capture for the intended destination before confirming. A Cloud confirmation
|
|
1519
1618
|
saves the issues locally and publishes them. Use `--full-output` with
|
|
1520
1619
|
`--format json` or `--format jsonl` for a structured result.
|
|
@@ -1564,9 +1663,13 @@ Enterprise repository URL or its Cloud ID. Either works for retries. If
|
|
|
1564
1663
|
several connectors share the URL, use the ID. You can import before the
|
|
1565
1664
|
repository's first native scan.
|
|
1566
1665
|
|
|
1567
|
-
Cloud requires a file-backed ChatGPT login.
|
|
1568
|
-
|
|
1569
|
-
|
|
1666
|
+
Cloud requires a file-backed ChatGPT login. Codex Security signs in with the
|
|
1667
|
+
`cli_auth_credentials_store` set in your Codex `config.toml`
|
|
1668
|
+
(`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Without it, the login
|
|
1669
|
+
can be saved in the system keyring. To publish, set
|
|
1670
|
+
`cli_auth_credentials_store = "file"` there, then run `codex-security login`
|
|
1671
|
+
with the ChatGPT account you want to use. `codex-security login status`
|
|
1672
|
+
checks the current sign-in without changing credential storage.
|
|
1570
1673
|
|
|
1571
1674
|
### Review the Cloud destination
|
|
1572
1675
|
|
|
@@ -1577,11 +1680,10 @@ Run the command with `--dry-run --format json`. Check `accountId`,
|
|
|
1577
1680
|
- **Private findings inbox.** If the preview includes `privateImport`, the
|
|
1578
1681
|
report goes to your inbox. The repository and connector identify the
|
|
1579
1682
|
suggested assessment target. Check `format`, `bytes` and `sha256` in
|
|
1580
|
-
`privateImport` to identify the upload.
|
|
1581
|
-
`
|
|
1582
|
-
|
|
1583
|
-
|
|
1584
|
-
Findings, use `security.findings.v1`.
|
|
1683
|
+
`privateImport` to identify the upload. The CLI and SDK encode the reviewed
|
|
1684
|
+
occurrences as `security.findings.v1` when it fits. For Wiz and Endor, an
|
|
1685
|
+
inbox that requires native records or has a smaller upload limit can receive
|
|
1686
|
+
native records that reproduce the reviewed evidence.
|
|
1585
1687
|
- **Repository publisher.** Check `repository.environment_id` in each entry
|
|
1586
1688
|
of `requests`. The publisher checks the current source versions. Existing
|
|
1587
1689
|
records keep their environment. New records use the repository's authorized
|
|
@@ -1610,10 +1712,10 @@ instructions. API requests always use the API root. The older
|
|
|
1610
1712
|
### Resume interrupted imports
|
|
1611
1713
|
|
|
1612
1714
|
If the result includes `savedSubmission`, keep that checkpoint. Rerun the
|
|
1613
|
-
original command with `--dry-run --format json` using the same input, account,
|
|
1715
|
+
original command with `--dry-run --format json` using the same build, input, account,
|
|
1614
1716
|
destination, API endpoint and state directory. Check `cloudApiUrl`. If
|
|
1615
1717
|
`resumed` is true, confirm to continue the saved submission. If it's false,
|
|
1616
|
-
review the new submission before confirming.
|
|
1718
|
+
review the new submission before confirming. Finish older-format pending submissions with the client that created them. If a response was lost, check the inbox job or repository records before starting a fresh upload.
|
|
1617
1719
|
|
|
1618
1720
|
- **Private inbox.** The CLI checks the report digest and reuses its saved
|
|
1619
1721
|
request IDs. It can read an accepted job even if the deployment has since
|
|
@@ -1699,7 +1801,10 @@ The provider guide describes [package JSON and CSV](https://github.com/openai/co
|
|
|
1699
1801
|
|
|
1700
1802
|
### Publish completed scans
|
|
1701
1803
|
|
|
1702
|
-
|
|
1804
|
+
The public `publish scan --help` menu describes Linear and custom publication
|
|
1805
|
+
from saved scans. The CSV input below belongs to Cloud publication.
|
|
1806
|
+
The following workflow is available to installations with Cloud publication access.
|
|
1807
|
+
Preview selected completed scans locally before uploading them.
|
|
1703
1808
|
|
|
1704
1809
|
```bash
|
|
1705
1810
|
codex-security publish scan --to cloud --dry-run --json
|
|
@@ -1713,12 +1818,15 @@ prefix of at least eight characters, or `latest` for the current repository.
|
|
|
1713
1818
|
Local sealed artifacts are required. Dry runs need no login or network access.
|
|
1714
1819
|
|
|
1715
1820
|
Uploads require ChatGPT credentials saved to a file. Set
|
|
1716
|
-
`cli_auth_credentials_store = "file"` in Codex `config.toml`, then
|
|
1717
|
-
|
|
1718
|
-
|
|
1719
|
-
|
|
1720
|
-
|
|
1721
|
-
|
|
1821
|
+
`cli_auth_credentials_store = "file"` in Codex `config.toml`, then run
|
|
1822
|
+
`codex-security login` again. Login, scans and other commands use that setting
|
|
1823
|
+
for the Codex Security sign-in.
|
|
1824
|
+
A dedicated login using automatic storage can publish if Codex Security
|
|
1825
|
+
recorded the native file fallback. An unverified file can belong to another
|
|
1826
|
+
account, so Cloud publication requires an explicit file store for an ambient login.
|
|
1827
|
+
|
|
1828
|
+
Use `publish scan DIR --to cloud` for one directory outside history. For
|
|
1829
|
+
multiple directories, repeat `--scan-dir PATH`. Each must contain one completed sealed scan, not a bulk-run
|
|
1722
1830
|
directory or `results.jsonl`. Do not mix directories with `--scan`.
|
|
1723
1831
|
Cloud also accepts exported CSV:
|
|
1724
1832
|
|
|
@@ -1750,7 +1858,8 @@ Select one completed scan by ID, prefix, `latest`, or directory; omit the select
|
|
|
1750
1858
|
for the picker. Live publication and `--skip-existing` require local history.
|
|
1751
1859
|
A directory-only dry run does not.
|
|
1752
1860
|
|
|
1753
|
-
`--linear-project PROJECT_ID`
|
|
1861
|
+
`--linear-project PROJECT_ID` selects a project. Existing scripts using the deprecated
|
|
1862
|
+
`--project PROJECT_ID` spelling continue to work. Flags override
|
|
1754
1863
|
`CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
|
|
1755
1864
|
previews titles offline; `--json` returns structured output.
|
|
1756
1865
|
|
|
@@ -1762,10 +1871,10 @@ Keys are omitted from saved results; diagnostic messages remain unchanged.
|
|
|
1762
1871
|
|
|
1763
1872
|
```bash
|
|
1764
1873
|
codex-security publish check /path/to/completed-scan \
|
|
1765
|
-
--
|
|
1874
|
+
--linear-team TEAM_ID --json
|
|
1766
1875
|
```
|
|
1767
1876
|
|
|
1768
|
-
`publish check` verifies artifacts and recorded publications. With an API key,
|
|
1877
|
+
`publish check` verifies scan artifacts and recorded Linear publications. With an API key,
|
|
1769
1878
|
it also checks authentication and destination access. It does not test issue
|
|
1770
1879
|
creation; connected-app access is reported as `not-checked`.
|
|
1771
1880
|
|
|
@@ -1824,7 +1933,9 @@ request. It sends the config name without findings or account identifiers.
|
|
|
1824
1933
|
If the request fails, times out, or returns an invalid rubric, the built-in
|
|
1825
1934
|
rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
|
|
1826
1935
|
uses your policy for every review. Rubrics and repeatable `--knowledge-base`
|
|
1827
|
-
context accept text, PDF, DOCX, and directories.
|
|
1936
|
+
context accept text, PDF, DOCX, and directories. Select external documents directly.
|
|
1937
|
+
Links in the artifact directory or a saved checkout must stay inside their source.
|
|
1938
|
+
When `--scan` cannot verify the saved checkout, use the document's canonical path.
|
|
1828
1939
|
|
|
1829
1940
|
Each finding is classified three times by default. `--runs N` accepts
|
|
1830
1941
|
an integer from 1 through 10; SDK options use `classificationRuns` with the same
|
|
@@ -1866,15 +1977,17 @@ or effort. A successful
|
|
|
1866
1977
|
run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
|
|
1867
1978
|
unchanged.
|
|
1868
1979
|
|
|
1869
|
-
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe
|
|
1870
|
-
`
|
|
1871
|
-
|
|
1980
|
+
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe returns
|
|
1981
|
+
`scanRepresentativeFindingIds` for this selection, in the same order as its
|
|
1982
|
+
corpus-wide `uniqueFindingIds`.
|
|
1872
1983
|
Linear publication defaults to saved classification selection, omits exclusions,
|
|
1873
1984
|
and uses assessed severity for title and priority. Descriptions retain original
|
|
1874
1985
|
severity and add the classification rationale. Publication rejects incomplete or
|
|
1875
1986
|
stale assessments. It never reclassifies or rereads the rubric at publication time.
|
|
1876
1987
|
|
|
1877
1988
|
```bash
|
|
1989
|
+
# List the IDs you can pass to --finding-id.
|
|
1990
|
+
codex-security dedupe --scan SCAN_ID --json | jq -r '.scanRepresentativeFindingIds[]'
|
|
1878
1991
|
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
|
|
1879
1992
|
--finding-id FINDING_ID
|
|
1880
1993
|
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
|
|
@@ -1889,46 +2002,32 @@ import {
|
|
|
1889
2002
|
classifySeverity,
|
|
1890
2003
|
classifyScanSeverity,
|
|
1891
2004
|
classifyScanDirectorySeverity,
|
|
2005
|
+
deduplicateScanDirectory,
|
|
1892
2006
|
publishScan,
|
|
1893
|
-
type FindingsDocument,
|
|
1894
2007
|
} from "@openai/codex-security";
|
|
1895
|
-
import { readFile } from "node:fs/promises";
|
|
1896
|
-
import { join } from "node:path";
|
|
1897
2008
|
|
|
1898
2009
|
// Assess supplied reports in memory.
|
|
1899
|
-
|
|
2010
|
+
await classifySeverity(findings, {
|
|
1900
2011
|
rubricPath: "/path/to/policy.md",
|
|
1901
2012
|
knowledgeBasePaths: ["/path/to/context.md"],
|
|
1902
2013
|
});
|
|
1903
2014
|
|
|
1904
2015
|
// Save assessments for a scan ID or sealed directory.
|
|
1905
2016
|
await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
|
|
1906
|
-
const
|
|
1907
|
-
|
|
1908
|
-
await readFile(join(scanDirectory, "findings.json"), "utf8"),
|
|
1909
|
-
) as FindingsDocument
|
|
1910
|
-
).findings;
|
|
1911
|
-
const scanFindingIds = new Set(
|
|
1912
|
-
scanFindings.map((finding) => finding.findingId),
|
|
1913
|
-
);
|
|
1914
|
-
// dedupeResult was produced by deduplicating this same scan.
|
|
1915
|
-
const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
|
|
1916
|
-
if (scanFindingIds.has(representative)) return representative;
|
|
1917
|
-
return dedupeResult.duplicateGroups
|
|
1918
|
-
.find((group) => group.includes(representative))!
|
|
1919
|
-
.find((member) => scanFindingIds.has(member))!;
|
|
2017
|
+
const dedupeResult = await deduplicateScanDirectory(scanDirectory, {
|
|
2018
|
+
repository: "/path/to/repository",
|
|
1920
2019
|
});
|
|
1921
|
-
await classifyScanDirectorySeverity(scanDirectory, {
|
|
2020
|
+
const classification = await classifyScanDirectorySeverity(scanDirectory, {
|
|
1922
2021
|
rubricPath: "/path/to/policy.md",
|
|
1923
|
-
findingIds:
|
|
2022
|
+
findingIds: dedupeResult.scanRepresentativeFindingIds,
|
|
1924
2023
|
});
|
|
1925
2024
|
|
|
1926
|
-
//
|
|
2025
|
+
// Preview Linear publication for those same findings using their assessments.
|
|
1927
2026
|
await publishScan(scanDirectory, {
|
|
1928
2027
|
destination: "linear",
|
|
1929
2028
|
teamId: "TEAM_ID",
|
|
1930
2029
|
classification,
|
|
1931
|
-
findingIds:
|
|
2030
|
+
findingIds: dedupeResult.scanRepresentativeFindingIds,
|
|
1932
2031
|
dryRun: true,
|
|
1933
2032
|
});
|
|
1934
2033
|
```
|
|
@@ -2035,24 +2134,41 @@ attach only their owner's session. Unrecorded earlier retry sessions may be abse
|
|
|
2035
2134
|
## Scan history and reruns
|
|
2036
2135
|
|
|
2037
2136
|
Commands default to the current repository. IDs accept unique prefixes of at
|
|
2038
|
-
least eight characters.
|
|
2039
|
-
|
|
2040
|
-
|
|
2041
|
-
|
|
2042
|
-
|
|
2043
|
-
|
|
2044
|
-
|
|
2045
|
-
|
|
2046
|
-
|
|
2047
|
-
|
|
2048
|
-
|
|
2049
|
-
|
|
2050
|
-
|
|
|
2051
|
-
|
|
|
2052
|
-
| `
|
|
2053
|
-
|
|
2054
|
-
|
|
2055
|
-
|
|
2137
|
+
least eight characters. Reading empty history leaves the workbench database uninitialized.
|
|
2138
|
+
|
|
2139
|
+
Linked Git worktrees share scans, findings, and reviewer decisions when their
|
|
2140
|
+
scans record the same repository generation in the selected state database.
|
|
2141
|
+
Older scans without this evidence remain target-local. Removed worktrees retain
|
|
2142
|
+
their recorded history; a reused checkout path does not inherit its previous
|
|
2143
|
+
owner's history. Separately verified clones can still be compared explicitly,
|
|
2144
|
+
but their finding histories remain separate.
|
|
2145
|
+
|
|
2146
|
+
Finding confirmation and automatic post-scan matching follow completion order
|
|
2147
|
+
in the workbench, without changing sealed report timestamps.
|
|
2148
|
+
|
|
2149
|
+
| Command | Purpose |
|
|
2150
|
+
| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
2151
|
+
| `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
|
|
2152
|
+
| `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
|
|
2153
|
+
| `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
|
|
2154
|
+
| `scans resume SCAN_ID` | Continue an interrupted Standard or Deep Scan. |
|
|
2155
|
+
| `scans rerun [SCAN_ID]` | Rerun a saved recipe in its checkout. |
|
|
2156
|
+
| `scans match --all` | Match completed scans in this repository generation, including linked worktrees. |
|
|
2157
|
+
| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
|
|
2158
|
+
| `findings list [REPOSITORY]` | List open findings. |
|
|
2159
|
+
| `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
|
|
2160
|
+
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
|
|
2161
|
+
|
|
2162
|
+
In the terminal, `findings list` shows the occurrence ID for each open finding.
|
|
2163
|
+
Copy that ID into `findings false-positive` with your reason. Subsequent scans can
|
|
2164
|
+
use the explanation while it applies. In `scans show SCAN_ID --json`, each
|
|
2165
|
+
displayed occurrence has its saved rationale in `triage.note` after dismissal. The list identifies
|
|
2166
|
+
a repository with no saved scan history separately from one with zero open findings.
|
|
2167
|
+
From an unregistered Git subdirectory with no scan history of its own, it uses the worktree root.
|
|
2168
|
+
|
|
2169
|
+
With an omitted ID or the literal `latest`, `scans show` selects the latest completed scan, while `scans logs`
|
|
2170
|
+
selects the latest scan of any status. Both prefer a scan in the current
|
|
2171
|
+
worktree when one qualifies. After a successful scan followed by a
|
|
2056
2172
|
failed or active scan, these defaults refer to different runs. Human output
|
|
2057
2173
|
identifies the selected run, labels its saved update time, and gives matching
|
|
2058
2174
|
commands with its full scan ID:
|
|
@@ -2070,7 +2186,10 @@ history. Inspect its saved status before choosing resume or rerun, and supply
|
|
|
2070
2186
|
the original custom prompt files for reruns. Structured history and log output
|
|
2071
2187
|
and command selection defaults are unchanged.
|
|
2072
2188
|
|
|
2073
|
-
|
|
2189
|
+
Without an ID, rerun selects the latest completed scan in the current worktree.
|
|
2190
|
+
If only a related checkout has a completed scan, rerun shows its ID, path, and
|
|
2191
|
+
revision. Pass that ID to run the saved recipe using the files currently at its
|
|
2192
|
+
saved checkout and context paths. Reruns do not reload project files.
|
|
2074
2193
|
The readable scan recipe records your authentication choice. A separate private
|
|
2075
2194
|
replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
|
|
2076
2195
|
`model_providers` settings, including any credentials written directly in
|
|
@@ -2106,6 +2225,17 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
|
2106
2225
|
writable, and outside the target repository. Session logs may contain sensitive
|
|
2107
2226
|
data even though scan recipes do not store credentials.
|
|
2108
2227
|
|
|
2228
|
+
Keep the same state directory across linked worktrees. Changing it selects
|
|
2229
|
+
separate history, artifacts, and a dedicated Codex sign-in. `--scan-root`
|
|
2230
|
+
filters recorded artifact paths; it does not import another directory's scans.
|
|
2231
|
+
|
|
2232
|
+
The workbench records the outer checkout directory when it registers a target.
|
|
2233
|
+
A later nested checkout cannot make tools from that directory eligible for
|
|
2234
|
+
automatic discovery. When an older saved target lacks a recorded checkout
|
|
2235
|
+
directory, set `CODEX_SECURITY_GIT` to the absolute path of a trusted Git
|
|
2236
|
+
executable outside the checkouts. If you use a system Python instead of the
|
|
2237
|
+
Codex managed runtime, set `PYTHON` to the absolute path of your interpreter.
|
|
2238
|
+
|
|
2109
2239
|
Saved scan logs retain the finishing turn, including its final response, and
|
|
2110
2240
|
exclude later turns once the scan records a completion boundary. Older scans
|
|
2111
2241
|
retain the full history of their attributed sessions and keep their existing
|
|
@@ -2117,19 +2247,42 @@ work on all supported Node.js versions, including logs, feedback attachments,
|
|
|
2117
2247
|
usage accounting, and saved-session discovery for resume. A bundled decoder
|
|
2118
2248
|
reads concatenated frames and reports truncated streams as collection errors.
|
|
2119
2249
|
|
|
2120
|
-
### Resuming an interrupted
|
|
2250
|
+
### Resuming an interrupted scan
|
|
2121
2251
|
|
|
2122
2252
|
```bash
|
|
2123
2253
|
codex-security scans list --scan-root /path/to/security-scans
|
|
2124
2254
|
codex-security scans resume SCAN_ID
|
|
2125
2255
|
```
|
|
2126
2256
|
|
|
2257
|
+
The terminal list shows the full scan ID and labels the last activity of a
|
|
2258
|
+
`running` scan after 24 hours without an update. For a Standard or Deep Scan with a saved
|
|
2259
|
+
launch recipe and its original session, it also shows the resume command to use after interruption.
|
|
2260
|
+
|
|
2127
2261
|
The scan must still be `running`, with its original checkout, output directory,
|
|
2128
2262
|
and Codex session in the same state directory. Checkout identity, revision, and
|
|
2129
2263
|
contents must match. Completed, failed, and canceled scans need a rerun instead.
|
|
2130
2264
|
|
|
2131
|
-
|
|
2132
|
-
|
|
2265
|
+
On Windows, keep the protected `.codex-security-resume` directory in the scan
|
|
2266
|
+
output. It lets the workbench verify the original output even before the first
|
|
2267
|
+
checkpoint. If an older scan stopped with an empty output, start a new scan with
|
|
2268
|
+
`codex-security scans rerun SCAN_ID`.
|
|
2269
|
+
|
|
2270
|
+
New Windows Standard and Deep Scans also record the checkout's native volume and file ID
|
|
2271
|
+
when the filesystem supplies them. Validation and remediation verify the same
|
|
2272
|
+
checkout identity. An older scan can resume across Python
|
|
2273
|
+
versions when its saved checkout identity can be verified. If the workbench
|
|
2274
|
+
cannot verify it, resume with the Python runtime that started the scan or use
|
|
2275
|
+
`codex-security scans rerun SCAN_ID` to start a new scan.
|
|
2276
|
+
|
|
2277
|
+
Resume keeps the scan ID, saved settings and instructions, completed workers, artifacts,
|
|
2278
|
+
and accumulated cost. A Standard scan continues in its original Codex session with
|
|
2279
|
+
the same `--max-cost` limit and `--max-time` deadline. Only one CLI or SDK call
|
|
2280
|
+
can run it at a time. If the connection fails after the session is saved, the CLI
|
|
2281
|
+
prints the resume command. Work since the last checkpoint may need to be repeated.
|
|
2282
|
+
Use `scans rerun` for canceled or failed scans, including authentication failures.
|
|
2283
|
+
For custom validation, rerun with the original validation instructions.
|
|
2284
|
+
|
|
2285
|
+
Knowledge-bearing scans save their extracted documents in
|
|
2133
2286
|
the private `.scan-knowledge.json` continuation file beside the scan artifacts.
|
|
2134
2287
|
Resume verifies and uses that snapshot even if the original files changed or were
|
|
2135
2288
|
deleted. Preserve it with the scan directory; canonical reports do not embed its
|
|
@@ -2147,7 +2300,10 @@ to update campaign receipts. Individual resume does not update `results.jsonl`.
|
|
|
2147
2300
|
|
|
2148
2301
|
### Matching saved scans
|
|
2149
2302
|
|
|
2150
|
-
|
|
2303
|
+
Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the model
|
|
2304
|
+
and save its matching decisions. Pass `--force` to recompute saved matches.
|
|
2305
|
+
The older `scans match BEFORE AFTER` spelling is also supported.
|
|
2306
|
+
Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
|
|
2151
2307
|
Comparisons classify findings as new, persisting, reopened, not observed, resolved,
|
|
2152
2308
|
or unknown. An absent finding in the later scope is not observed; absence alone
|
|
2153
2309
|
does not verify remediation. A finding is resolved only after it was explicitly
|
|
@@ -2214,6 +2370,10 @@ must already exist.
|
|
|
2214
2370
|
|
|
2215
2371
|
SARIF is the default format, and `./results.sarif` is the default output path.
|
|
2216
2372
|
Use `--export-format json` or `--export-format csv` to choose another format.
|
|
2373
|
+
An existing default output file is preserved. Pass `--output FILE` to choose
|
|
2374
|
+
a filename or explicitly replace it. Use `--output -` to pipe the complete
|
|
2375
|
+
artifact. Response filters, token controls, and `--full-output` require a
|
|
2376
|
+
command that returns a formatted response.
|
|
2217
2377
|
To select a saved scan by its ID and export JSON, run:
|
|
2218
2378
|
|
|
2219
2379
|
```bash
|
|
@@ -2385,10 +2545,11 @@ codex-security install-hook /path/to/repository
|
|
|
2385
2545
|
|
|
2386
2546
|
To migrate an existing generated hook, verify it is a regular file used only by
|
|
2387
2547
|
this repository and contains only the generated commands. Rerun `install-hook`
|
|
2388
|
-
with `--fail-on-severity`
|
|
2389
|
-
`npx` hook and
|
|
2390
|
-
paths.
|
|
2391
|
-
|
|
2548
|
+
with the desired `--fail-on-severity` level to change the threshold. The installer
|
|
2549
|
+
recognizes the legacy `npx` hook and earlier generated templates with matching
|
|
2550
|
+
absolute Node and CLI paths. It refuses to replace a hand-edited hook.
|
|
2551
|
+
On POSIX, reinstalling a recognized hook restores its owner execute bit if Git
|
|
2552
|
+
could not execute it. The installer checks that the resulting hook is executable.
|
|
2392
2553
|
The installer uses host Git for the selected repository and respects
|
|
2393
2554
|
`core.hooksPath`.
|
|
2394
2555
|
|
|
@@ -2417,6 +2578,14 @@ codex-security patch --scan SCAN_ID --severity high --json
|
|
|
2417
2578
|
codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
|
|
2418
2579
|
```
|
|
2419
2580
|
|
|
2581
|
+
For `validate`, `patch`, and `verify-fix`, an explicit local file URL such as
|
|
2582
|
+
`file:///home/reviewer/finding.md` (Windows: `file:///C:/reviews/finding.md`)
|
|
2583
|
+
requires the file to exist. A missing file stops the command before the model
|
|
2584
|
+
runs. Use `pathToFileURL(absolutePath).href` in Node to encode spaces and
|
|
2585
|
+
special characters correctly. Absolute paths and paths starting with `~/`, `./`, or `../`
|
|
2586
|
+
also require an existing file. Use `text:/path is exposed` to pass path-shaped
|
|
2587
|
+
prose verbatim, or `text:text:example` for a finding that starts with `text:`.
|
|
2588
|
+
|
|
2420
2589
|
Context inputs are optional and can be combined:
|
|
2421
2590
|
|
|
2422
2591
|
- `--context TEXT` adds inline security context or reviewer feedback.
|
|
@@ -2424,6 +2593,7 @@ Context inputs are optional and can be combined:
|
|
|
2424
2593
|
- Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
|
|
2425
2594
|
document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
|
|
2426
2595
|
are searched recursively; binary files, symlinks, and Git metadata are skipped.
|
|
2596
|
+
When validating from a Git checkout, select external documents directly.
|
|
2427
2597
|
|
|
2428
2598
|
Inline and file context are included in the prompt. Knowledge-base documents are
|
|
2429
2599
|
prepared in a temporary directory for Codex to read during the assessment, then
|
|
@@ -2574,7 +2744,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
|
|
|
2574
2744
|
task. The container must provide it. There is no automatic fallback; optional
|
|
2575
2745
|
patch-risk assessment still uses its read-only sandbox.
|
|
2576
2746
|
|
|
2577
|
-
`scan --patch` runs after a complete scan
|
|
2747
|
+
`scan --patch` runs after a complete scan without a cost limit. A cost-limited
|
|
2748
|
+
scan saves the findings and skips the interactive patch offer. Use
|
|
2749
|
+
`codex-security patch --scan SCAN_ID` to patch separately.
|
|
2750
|
+
`--patch-severity` defaults to `low`;
|
|
2578
2751
|
`high` selects high and critical findings. Interactive users can select findings
|
|
2579
2752
|
and add instructions. The interactive finding browser lists critical, high,
|
|
2580
2753
|
medium, then low findings, preserving scan order within each severity.
|
|
@@ -2641,7 +2814,10 @@ SDK's local `validate()` and `patch()` methods use the same fallback.
|
|
|
2641
2814
|
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
2642
2815
|
|
|
2643
2816
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
2644
|
-
|
|
2817
|
+
Without output options, each finding prints a verdict and its evidence.
|
|
2818
|
+
Explicit output formats, field selection and token controls operate on the
|
|
2819
|
+
structured result containing `repository`, optional `scanId`, and `results`.
|
|
2820
|
+
Exit codes are `0` when all findings are
|
|
2645
2821
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|
|
2646
2822
|
With `--json` or `--format jsonl`, authentication and execution failures return
|
|
2647
2823
|
`status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
|
|
@@ -2654,21 +2830,112 @@ retain exit codes `130` and `143` without a result.
|
|
|
2654
2830
|
|
|
2655
2831
|
## Command discovery and integrations
|
|
2656
2832
|
|
|
2657
|
-
|
|
2658
|
-
|
|
2833
|
+
Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.
|
|
2834
|
+
|
|
2835
|
+
Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Add `--json` to return the generated script as a JSON string. The same option returns the menu text when an omitted command or subcommand displays help. With `--full-output`, the text is in `data`. Scan output supports
|
|
2659
2836
|
`--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
|
|
2660
2837
|
`--filter-output`, `--token-limit`, and `--token-offset` options accept either
|
|
2661
2838
|
`--option value` or `--option=value`.
|
|
2662
2839
|
|
|
2840
|
+
`--token-limit` and `--token-offset` take nonnegative integers and select a
|
|
2841
|
+
text view of the formatted result. Truncated JSON and JSONL views are returned
|
|
2842
|
+
as a JSON string containing the excerpt and its token range. With
|
|
2843
|
+
`--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
|
|
2844
|
+
the next page when more tokens are available. `--token-count` returns the
|
|
2845
|
+
estimated size instead. A failed full-output JSON or JSONL response always
|
|
2846
|
+
retains its error code and message. If the failure carries result data,
|
|
2847
|
+
`--token-count` reports its size in `meta.tokenCount`.
|
|
2848
|
+
|
|
2663
2849
|
`skills add` syncs generated CLI command guidance; it does not install the full
|
|
2664
2850
|
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
|
|
2665
2851
|
only read-only `info` because the transport cannot cancel scans. For the plugin's
|
|
2666
2852
|
scan, triage, patch, and verification workflows, see the
|
|
2667
2853
|
[agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
|
|
2668
2854
|
|
|
2855
|
+
Both installers default to `--scope user`. Use `--scope project` for the current
|
|
2856
|
+
directory. Existing scripts can continue using `--no-global` for project scope.
|
|
2857
|
+
Inspect either command with `--help`, `--schema`, or `--version` before installing.
|
|
2858
|
+
|
|
2859
|
+
`skills add --depth 0` creates a single skill. The default depth of 1 groups
|
|
2860
|
+
guidance by top-level command. To check the installed files, use the same
|
|
2861
|
+
depth with `skills list`, for example `skills list --depth 0 --json`. Each
|
|
2862
|
+
entry includes its canonical `SKILL.md` locations in the current project and
|
|
2863
|
+
user profile.
|
|
2864
|
+
|
|
2865
|
+
`mcp add` registers detected compatible clients. If it finds none in the
|
|
2866
|
+
selected scope, choose a client with `--agent NAME` (repeatable), or register
|
|
2867
|
+
every compatible client with `--all`. For example, `mcp add --scope project
|
|
2868
|
+
--agent cursor` writes Cursor's project configuration. In user scope, Codex
|
|
2869
|
+
detection and registration use `CODEX_HOME` when set. Amp supports user
|
|
2870
|
+
registration only.
|
|
2871
|
+
|
|
2872
|
+
The default launcher runs `npx --yes @openai/codex-security --mcp`. To register
|
|
2873
|
+
an installed executable, use its name or path with `--exec` and repeat
|
|
2874
|
+
`--arg=VALUE` for each argument. Each value is stored literally, including
|
|
2875
|
+
spaces, empty arguments, and leading dashes. To run an npm package, select
|
|
2876
|
+
`--package NAME`. The existing `--command` accepts a command line or HTTP(S)
|
|
2877
|
+
URL. Quotes group command-line words, and backslashes are literal. A bare
|
|
2878
|
+
executable name is stored directly. Use `--exec` for a path with
|
|
2879
|
+
spaces, including when the executable will be installed on another machine.
|
|
2880
|
+
|
|
2881
|
+
```bash
|
|
2882
|
+
codex-security mcp add --agent cursor --exec "/opt/My Tools/server" --arg=--mcp
|
|
2883
|
+
codex-security mcp add --agent cursor --package @openai/codex-security --arg=--mcp
|
|
2884
|
+
```
|
|
2885
|
+
|
|
2886
|
+
`mcp doctor` checks the current CLI's server startup and tool catalog. To
|
|
2887
|
+
verify a registered launcher, connect from the client where it was registered.
|
|
2888
|
+
|
|
2669
2889
|
For local findings storage, deduplication, and custom endpoints, see the
|
|
2670
2890
|
[findings guide](findings-service.md).
|
|
2671
2891
|
|
|
2892
|
+
### Shell completions
|
|
2893
|
+
|
|
2894
|
+
The generated scripts register both `codex-security` and `cs`. Choose your shell
|
|
2895
|
+
and open a new session after saving the setup.
|
|
2896
|
+
|
|
2897
|
+
**Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:
|
|
2898
|
+
|
|
2899
|
+
```bash
|
|
2900
|
+
source <(codex-security completions bash)
|
|
2901
|
+
```
|
|
2902
|
+
|
|
2903
|
+
**Zsh.** In `~/.zshrc`, load the generated script after your completion system
|
|
2904
|
+
calls `compinit`. If you initialize completions yourself, use:
|
|
2905
|
+
|
|
2906
|
+
```zsh
|
|
2907
|
+
autoload -Uz compinit
|
|
2908
|
+
compinit
|
|
2909
|
+
source <(codex-security completions zsh)
|
|
2910
|
+
```
|
|
2911
|
+
|
|
2912
|
+
**Fish.** Add this line to `~/.config/fish/config.fish`:
|
|
2913
|
+
|
|
2914
|
+
```fish
|
|
2915
|
+
codex-security completions fish | source
|
|
2916
|
+
```
|
|
2917
|
+
|
|
2918
|
+
**Nushell.** Save the generated closures alongside `config.nu`:
|
|
2919
|
+
|
|
2920
|
+
```nu
|
|
2921
|
+
codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)
|
|
2922
|
+
```
|
|
2923
|
+
|
|
2924
|
+
In `config.nu`, source the file and dispatch the two names to their completers:
|
|
2925
|
+
|
|
2926
|
+
```nu
|
|
2927
|
+
source codex-security-completions.nu
|
|
2928
|
+
let previous_completer = $env.config.completions.external.completer?
|
|
2929
|
+
$env.config.completions.external.enable = true
|
|
2930
|
+
$env.config.completions.external.completer = {|spans|
|
|
2931
|
+
match $spans.0 {
|
|
2932
|
+
"codex-security" => { do $_incur_complete_codex_security $spans }
|
|
2933
|
+
"cs" => { do $_incur_complete_cs $spans }
|
|
2934
|
+
_ => { if $previous_completer != null { do $previous_completer $spans } }
|
|
2935
|
+
}
|
|
2936
|
+
}
|
|
2937
|
+
```
|
|
2938
|
+
|
|
2672
2939
|
### Hosted Standard scan
|
|
2673
2940
|
|
|
2674
2941
|
`codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
|