@openai/codex-security 0.9.1 → 0.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -788
- package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
- package/_bundled_plugin/.mcp.json +3 -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/access-advisory.md +1 -1
- 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/threat-model.md +1 -0
- package/_bundled_plugin/references/validate-scan-findings.md +3 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +30 -12
- package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +47 -9
- package/_bundled_plugin/scripts/launch_codex_security_mcp +54 -16
- package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +2 -0
- 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 +257 -268
- 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 +291 -134
- package/_bundled_plugin/scripts/workbench_scan_start.py +208 -11
- 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_source_scopes.py +8 -0
- package/_bundled_plugin/scripts/workbench_target.py +486 -85
- package/_bundled_plugin/scripts/workbench_target_state.py +1108 -22
- package/_bundled_plugin/shared/workbench-history-repairs.json +64 -14
- package/_bundled_plugin/shared/workbench-migrations.json +66 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -2
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +2 -2
- package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -0
- package/_bundled_plugin/skills/publish-findings/SKILL.md +26 -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/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 +7 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +459 -157
- 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-diagnostics.d.ts +10 -0
- package/dist/classify-severity-diagnostics.d.ts.map +1 -0
- package/dist/classify-severity-diagnostics.js +57 -0
- package/dist/classify-severity-diagnostics.js.map +1 -0
- package/dist/classify-severity-records.d.ts +4 -0
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +35 -8
- package/dist/classify-severity-records.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 +8 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1860 -903
- 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-plan.d.ts.map +1 -1
- package/dist/component-plan.js +3 -3
- package/dist/component-plan.js.map +1 -1
- 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-aws.d.ts +6 -0
- package/dist/continuum-aws.d.ts.map +1 -0
- package/dist/continuum-aws.js +202 -0
- package/dist/continuum-aws.js.map +1 -0
- package/dist/continuum-collector.d.ts +44 -0
- package/dist/continuum-collector.d.ts.map +1 -0
- package/dist/continuum-collector.js +266 -0
- package/dist/continuum-collector.js.map +1 -0
- package/dist/continuum-findings.d.ts +31 -2
- package/dist/continuum-findings.d.ts.map +1 -1
- package/dist/continuum-findings.js +497 -59
- package/dist/continuum-findings.js.map +1 -1
- package/dist/contract.d.ts +1 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +3 -0
- package/dist/contract.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/crowdstrike-findings.d.ts +7 -0
- package/dist/crowdstrike-findings.d.ts.map +1 -0
- package/dist/crowdstrike-findings.js +210 -0
- package/dist/crowdstrike-findings.js.map +1 -0
- 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 +258 -59
- 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 +330 -1633
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +11 -2
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +56 -53
- 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 +6 -11
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +35 -177
- 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/host-protocol.d.ts +6 -0
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js +11 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/host-records-protocol.d.ts +2 -0
- package/dist/host-records-protocol.d.ts.map +1 -1
- package/dist/host-records-protocol.js +4 -0
- package/dist/host-records-protocol.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 +5 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -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 +83 -39
- 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-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 +56 -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 +782 -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 +20 -2
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +26 -5
- 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/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +1 -0
- package/dist/scan-settings.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/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +1 -0
- package/dist/severity-review.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 +129 -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 +8 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +103 -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 +7 -0
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +148 -37
- package/dist/trusted-executable.js.map +1 -1
- package/dist/value.js +3 -1
- package/dist/value.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/classify-severity-records.md +30 -0
- package/docs/cli.md +537 -124
- package/docs/findings-service.md +22 -9
- package/docs/hosted-remediation.md +13 -4
- package/docs/sdk.md +918 -0
- package/package.json +15 -6
- package/schemas/external-findings.schema.json +2 -1
- package/schemas/project-config.schema.json +5 -0
- 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`.
|
|
@@ -239,6 +264,27 @@ comparisons, and deduplication preserve that selection. Relative helper paths an
|
|
|
239
264
|
`auth.cwd` resolve from `CODEX_HOME` (default `~/.codex`). Comparisons and reviews
|
|
240
265
|
also honor the selected command provider in that home's `config.toml`.
|
|
241
266
|
|
|
267
|
+
For OrcaRouter, save this profile in `$CODEX_HOME/orcarouter.config.toml`
|
|
268
|
+
(default `~/.codex/orcarouter.config.toml`), then run
|
|
269
|
+
`codex-security scan . --codex 'profile="orcarouter"'`. Sign in to the 1Password CLI and
|
|
270
|
+
replace the secret reference below with the one for your router key.
|
|
271
|
+
|
|
272
|
+
```toml
|
|
273
|
+
model = "orcarouter/fusion"
|
|
274
|
+
model_provider = "orcarouter"
|
|
275
|
+
|
|
276
|
+
[model_providers.orcarouter]
|
|
277
|
+
name = "OrcaRouter"
|
|
278
|
+
base_url = "https://api.orcarouter.ai/v1"
|
|
279
|
+
wire_api = "responses"
|
|
280
|
+
|
|
281
|
+
[model_providers.orcarouter.auth]
|
|
282
|
+
command = "op"
|
|
283
|
+
args = ["read", "op://Private/OrcaRouter/credential"]
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
This profile was tested up to the outgoing Responses request using a local service.
|
|
287
|
+
|
|
242
288
|
For other providers, set their key and select a model the provider supports:
|
|
243
289
|
|
|
244
290
|
```bash
|
|
@@ -252,6 +298,88 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
|
|
|
252
298
|
codex-security scan . --provider cheaperinference --model gpt-5.4
|
|
253
299
|
```
|
|
254
300
|
|
|
301
|
+
For Opper, save this profile in `$CODEX_HOME/opper.config.toml`
|
|
302
|
+
(default `~/.codex/opper.config.toml`). Opper requires `web_search = "disabled"`.
|
|
303
|
+
|
|
304
|
+
```toml
|
|
305
|
+
model_provider = "opper"
|
|
306
|
+
model = "anthropic/claude-sonnet-4-6"
|
|
307
|
+
web_search = "disabled"
|
|
308
|
+
|
|
309
|
+
[model_providers.opper]
|
|
310
|
+
name = "Opper"
|
|
311
|
+
base_url = "https://api.opper.ai/v3/compat"
|
|
312
|
+
wire_api = "responses"
|
|
313
|
+
env_key = "OPPER_API_KEY"
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
Set `OPPER_API_KEY` in your environment and run
|
|
317
|
+
`codex-security scan . --codex 'profile="opper"'`. Choose a model that supports
|
|
318
|
+
tool calling and streaming. Verification covered profile loading and a request to
|
|
319
|
+
a local Responses endpoint.
|
|
320
|
+
See [Opper's Codex setup guide](https://docs.opper.ai/integrations/coding-agents/codex).
|
|
321
|
+
|
|
322
|
+
### xAI Responses API through a local gateway
|
|
323
|
+
|
|
324
|
+
Codex 0.167.0 sends collaboration and Codex Security MCP tools as `namespace`
|
|
325
|
+
declarations. A direct scan against xAI can pass `--dry-run` and then fail with
|
|
326
|
+
HTTP 422 on the first model request. CLIProxyAPI's xAI adapter exposes each
|
|
327
|
+
namespace member to xAI as a plain function and restores the namespace when
|
|
328
|
+
Codex receives a tool call. Both connections use the Responses API.
|
|
329
|
+
[Direct xAI provider support](https://github.com/openai/codex-security/issues/2412)
|
|
330
|
+
|
|
331
|
+
Install CLIProxyAPI v8.0.59 and save this gateway config outside the scanned
|
|
332
|
+
repository in a file readable only by the gateway user. Replace the placeholders
|
|
333
|
+
with a private client key of your choice and your xAI API key.
|
|
334
|
+
[CLIProxyAPI release](https://github.com/router-for-me/CLIProxyAPI/releases/tag/v8.0.59)
|
|
335
|
+
|
|
336
|
+
```yaml
|
|
337
|
+
config-version: 8
|
|
338
|
+
server:
|
|
339
|
+
host: "127.0.0.1"
|
|
340
|
+
port: 8317
|
|
341
|
+
access:
|
|
342
|
+
api-keys: ["<gateway-client-key>"]
|
|
343
|
+
api-keys:
|
|
344
|
+
xai:
|
|
345
|
+
- name: scan
|
|
346
|
+
base-url: "https://api.x.ai/v1"
|
|
347
|
+
models:
|
|
348
|
+
- name: "grok-4.7"
|
|
349
|
+
keys:
|
|
350
|
+
- api-key: "<xai-api-key>"
|
|
351
|
+
oauth:
|
|
352
|
+
auth-dir: "~/.cli-proxy-api-xai"
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
Start the gateway in one shell.
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
cli-proxy-api -config /path/to/private/config.yaml -local-model
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
In a second shell on the same machine or in the same container, set
|
|
362
|
+
`CODEX_API_KEY` to the client key from `access.api-keys` and run the scan.
|
|
363
|
+
|
|
364
|
+
```bash
|
|
365
|
+
codex-security scan . --auth api-key --model grok-4.7 --effort low \
|
|
366
|
+
--codex "model_provider='xai'" \
|
|
367
|
+
--codex "model_providers.xai.name='xAI'" \
|
|
368
|
+
--codex "model_providers.xai.base_url='http://127.0.0.1:8317/v1'" \
|
|
369
|
+
--codex "model_providers.xai.wire_api='responses'" \
|
|
370
|
+
--codex "model_providers.xai.env_key='CODEX_API_KEY'" \
|
|
371
|
+
--codex 'features.multi_agent_v2.max_concurrent_threads_per_session=1'
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
The one-thread setting keeps Standard scans from spawning subagents. Without it,
|
|
375
|
+
the gateway can forward a subagent's `agent_message` on a later request, which
|
|
376
|
+
xAI rejects with HTTP 422. A contributor completed a live Standard scan with
|
|
377
|
+
this setting. Deep Scan workers have separate concurrency settings and remain
|
|
378
|
+
unverified with this gateway.
|
|
379
|
+
|
|
380
|
+
The SDK has no built-in price for `grok-4.7`, so it rejects `--max-cost` for this
|
|
381
|
+
model before starting a scan.
|
|
382
|
+
|
|
255
383
|
### Hugging Face compatibility
|
|
256
384
|
|
|
257
385
|
In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
|
|
@@ -384,11 +512,11 @@ Add context with `--knowledge-base`:
|
|
|
384
512
|
codex-security policy . --knowledge-base architecture.md
|
|
385
513
|
```
|
|
386
514
|
|
|
387
|
-
| Invocation
|
|
388
|
-
|
|
|
389
|
-
| `policy . --
|
|
390
|
-
| `policy . --format md`
|
|
391
|
-
| `policy . --dry-run --json`
|
|
515
|
+
| Invocation | Result |
|
|
516
|
+
| --------------------------- | -------------------------------------------------------- |
|
|
517
|
+
| `policy . --json` | Generate without prompts; return paths and review notes. |
|
|
518
|
+
| `policy . --format md` | Generate and write the draft to stdout. |
|
|
519
|
+
| `policy . --dry-run --json` | Check local inputs without calling Codex. |
|
|
392
520
|
|
|
393
521
|
`--headless` leaves unanswered questions in the review notes. By default, files
|
|
394
522
|
go in the Codex Security state directory. To choose a location, use an empty
|
|
@@ -483,17 +611,29 @@ callback, questions remain unresolved.
|
|
|
483
611
|
```bash
|
|
484
612
|
codex-security scan .
|
|
485
613
|
codex-security scan . --path src --path tests
|
|
614
|
+
codex-security scan . --exclude-path examples/
|
|
486
615
|
codex-security scan . --diff origin/main --json
|
|
487
616
|
codex-security scan . --working-tree
|
|
488
617
|
codex-security scan . --owner-suggestions
|
|
489
618
|
codex-security scan . --output-dir /path/outside/repository/results --dry-run
|
|
490
619
|
```
|
|
491
620
|
|
|
492
|
-
`--path` selects files or directories.
|
|
621
|
+
`--path` selects files or directories. Repeat `--exclude-path` to exclude literal
|
|
622
|
+
repository-relative files or directories, including all descendants of a directory.
|
|
623
|
+
Exclusions take precedence over `--path`, also apply to diff and Deep scans, and
|
|
624
|
+
default to none. For persistent exclusions, set `scan.exclude_paths` in a selected
|
|
625
|
+
project config. CLI exclusions replace that configured list. Excluded files remain
|
|
626
|
+
readable as context, but findings whose locations are all excluded are removed
|
|
627
|
+
from scan results.
|
|
628
|
+
The scan summary and saved scan details
|
|
493
629
|
show requested paths and exclusions. `coverage.deferred` records unfinished
|
|
494
630
|
requested work separately from optional `coverage.openQuestions` follow-up.
|
|
495
631
|
Human-readable output quotes ambiguous paths, while JSON retains their original strings.
|
|
496
632
|
|
|
633
|
+
A dry run reports `stateDirectory`, the root for saved scan state. It checks the
|
|
634
|
+
storage location without creating a scan directory. Pass boolean scan options
|
|
635
|
+
as bare flags or use lowercase `=true` or `=false`.
|
|
636
|
+
|
|
497
637
|
When a cost limit is configured, `scan --dry-run` shows the resolved
|
|
498
638
|
`maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
|
|
499
639
|
against the limit and why in-flight requests can exceed it.
|
|
@@ -509,7 +649,8 @@ be clean and at the commit recorded by the parent.
|
|
|
509
649
|
Committed-diff scans require a clean, full checkout at the requested head
|
|
510
650
|
revision, including when using `--validate`. A different checkout revision or
|
|
511
651
|
local changes are rejected before scanning; check out the requested head and
|
|
512
|
-
commit or stash local changes before retrying.
|
|
652
|
+
commit or stash local changes before retrying. The check also verifies tracked
|
|
653
|
+
files marked `assume-unchanged` and preserves their Git index flags.
|
|
513
654
|
|
|
514
655
|
`--owner-suggestions` writes optional `owner-suggestions.json` after a completed
|
|
515
656
|
committed Git scan, using the same checkout, model, and reasoning effort. Owner
|
|
@@ -524,7 +665,9 @@ Use the separate `suggest-owners` command for explicit owner-only jobs.
|
|
|
524
665
|
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
525
666
|
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
526
667
|
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
527
|
-
with every repository.
|
|
668
|
+
with every repository. Select external documents directly. Links in a checkout
|
|
669
|
+
must stay inside it. For bulk scans with bare or separate Git storage, use
|
|
670
|
+
canonical paths for shared documents and prompt files.
|
|
528
671
|
|
|
529
672
|
Use `--output-dir DIR` to choose where a scan saves its results. The directory
|
|
530
673
|
must be empty and outside the scanned directory and enclosing Git worktree.
|
|
@@ -538,7 +681,9 @@ through inheritance. Other users must not have permission to set reparse data
|
|
|
538
681
|
on the destination directory itself.
|
|
539
682
|
`--archive-existing` moves earlier output to a sibling directory with a unique
|
|
540
683
|
suffix, such as `results.previous-ab12cd34` for an output directory named
|
|
541
|
-
`results`.
|
|
684
|
+
`results`. If adding the suffix exceeds the filesystem's filename limit on POSIX,
|
|
685
|
+
the archive uses a short sibling name starting with `.previous-` and a hash of the
|
|
686
|
+
original filename. Use `--dry-run` to preview the move.
|
|
542
687
|
|
|
543
688
|
Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
|
|
544
689
|
optional export fails, the scan can still complete. Use the
|
|
@@ -595,8 +740,13 @@ available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an importe
|
|
|
595
740
|
scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
|
|
596
741
|
on stderr without `--full-output`, or when retained results are unavailable.
|
|
597
742
|
|
|
598
|
-
|
|
599
|
-
|
|
743
|
+
Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
|
|
744
|
+
envelope with `error.code` and `error.message`. Command schema validation errors
|
|
745
|
+
with JSON or JSONL retain their field details and name missing or invalid
|
|
746
|
+
options by their CLI flags. Diagnostics stay on stderr.
|
|
747
|
+
`scan --schema --format json` describes optional caller inputs before defaults
|
|
748
|
+
and the fields returned by preflight, completed scans, and execution failures,
|
|
749
|
+
including sealed results recovered after an interruption.
|
|
600
750
|
See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
601
751
|
|
|
602
752
|
### Follow-up finding validation
|
|
@@ -685,8 +835,8 @@ Choose the next step from the recorded reason:
|
|
|
685
835
|
start a new scan with the intended scope, including for plugin scans without
|
|
686
836
|
a recipe. Retained findings can still be reviewed, but absence of findings
|
|
687
837
|
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-
|
|
838
|
+
- **A Standard or Deep Scan was interrupted and is still recorded as `running`:** it may
|
|
839
|
+
support [resume](#resuming-an-interrupted-scan) with the original checkout,
|
|
690
840
|
artifacts, and session. Completed, failed, and canceled scans cannot resume.
|
|
691
841
|
|
|
692
842
|
For example, after identifying an omitted API directory:
|
|
@@ -731,16 +881,18 @@ from the config directory; scope paths resolve from the repository.
|
|
|
731
881
|
### Import findings as a saved scan
|
|
732
882
|
|
|
733
883
|
```bash
|
|
734
|
-
codex-security scan import
|
|
735
|
-
codex-security scan import
|
|
736
|
-
codex-security scan import
|
|
884
|
+
codex-security scan import /path/to/findings.csv
|
|
885
|
+
codex-security scan import /path/to/findings.json --json
|
|
886
|
+
codex-security scan import /path/to/report --input-format csv --dry-run
|
|
737
887
|
```
|
|
738
888
|
|
|
739
889
|
Supply exactly one input. CSV follows the
|
|
740
890
|
[findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
|
|
741
891
|
JSON accepts a complete `codex-security.findings` document or
|
|
742
|
-
`{ "findings": [...] }` matching the findings schema.
|
|
743
|
-
|
|
892
|
+
`{ "findings": [...] }` matching the findings schema. The CLI infers the format from a `.csv` or `.json` suffix.
|
|
893
|
+
Use `--input-format csv|json` to override it. Put `--json` after the filename
|
|
894
|
+
to request JSON output. Existing scripts using `--csv FILE` or `--json FILE`
|
|
895
|
+
can continue to select the input that way. The input must be a
|
|
744
896
|
regular file with no symlinks or directory junctions in its path.
|
|
745
897
|
|
|
746
898
|
Each import creates a completed scan in local history, retains the input under
|
|
@@ -821,6 +973,13 @@ codex-security scan-components . \
|
|
|
821
973
|
--output-dir /path/outside/project/results
|
|
822
974
|
```
|
|
823
975
|
|
|
976
|
+
`--plan-only` with `--component` or `--components-file` validates local paths
|
|
977
|
+
without signing in. The CLI prints a command to scan the saved plan into a fresh
|
|
978
|
+
`results` directory inside the plan directory. Running that command starts scans.
|
|
979
|
+
Run it from the original working directory to reuse relative paths. The command
|
|
980
|
+
includes the selected project configuration and scan flags. Reapply any inline
|
|
981
|
+
`--codex` overrides yourself, since these can contain credentials.
|
|
982
|
+
|
|
824
983
|
Plans use literal repository-relative paths, so `~/src` selects a directory
|
|
825
984
|
named `~` inside the repository rather than expanding the home directory.
|
|
826
985
|
Existing absolute paths inside the repository are also accepted.
|
|
@@ -850,9 +1009,15 @@ failed matching return `2`; severity-policy violations return `1`. Retry with
|
|
|
850
1009
|
The retry report covers only those components. Each registered component keeps its
|
|
851
1010
|
scan ID in the summary, including when the scan fails.
|
|
852
1011
|
|
|
853
|
-
`--max-cost` applies per component, excluding planning and matching.
|
|
854
|
-
|
|
855
|
-
|
|
1012
|
+
`--max-cost` applies per component, excluding planning and matching.
|
|
1013
|
+
Use `--max-total-cost USD` with explicit components to split one estimated
|
|
1014
|
+
budget among them. The smaller of each component's share and its per-scan
|
|
1015
|
+
limit applies. Findings stay separate because model-based matching is skipped.
|
|
1016
|
+
The total limit also skips owner suggestions, including when enabled in project configuration.
|
|
1017
|
+
Automatic planning and post-scan prompts must run separately.
|
|
1018
|
+
|
|
1019
|
+
`--model` and `--effort` also apply to matching. `--auth` applies throughout.
|
|
1020
|
+
Planning and matching reject ambient command providers that conflict with explicit ChatGPT
|
|
856
1021
|
or API-key auth. SDK-selected command providers retain their authentication.
|
|
857
1022
|
|
|
858
1023
|
From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
|
|
@@ -877,6 +1042,7 @@ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
|
|
|
877
1042
|
`markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
|
|
878
1043
|
Markdown. A supplied snapshot takes precedence over a file.
|
|
879
1044
|
|
|
1045
|
+
A dry run reads and validates an explicit rubric before reporting a successful preflight.
|
|
880
1046
|
The scan saves the rubric text in its local launch recipe. Retrying a Standard
|
|
881
1047
|
scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
|
|
882
1048
|
with a saved rubric reuses that copy even if the remote default or file changes.
|
|
@@ -901,7 +1067,7 @@ behavior are unchanged.
|
|
|
901
1067
|
|
|
902
1068
|
The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
|
|
903
1069
|
Each launched scan or rerun gets its own allowance after setup, and reconnects
|
|
904
|
-
do not reset it. Standard scans
|
|
1070
|
+
do not reset it. [Resumed Standard scans](#resuming-an-interrupted-scan) keep the original deadline. For batch and
|
|
905
1071
|
component scans, the project setting applies separately to each scan attempt,
|
|
906
1072
|
not to planning, result matching, or the total campaign.
|
|
907
1073
|
|
|
@@ -925,7 +1091,7 @@ completed scans that added no findings. `--max-discovery-runs` caps the total
|
|
|
925
1091
|
number started, including failures. `--max-time` stops discovery and returns
|
|
926
1092
|
the findings from completed scans.
|
|
927
1093
|
|
|
928
|
-
For TypeScript, see the [SDK Deep Scan example](
|
|
1094
|
+
For TypeScript, see the [SDK Deep Scan example](sdk.md#configure-deep-scans).
|
|
929
1095
|
|
|
930
1096
|
Use project-file `scan.deep` settings or legacy
|
|
931
1097
|
`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
|
|
@@ -981,7 +1147,9 @@ credentials, and workflow resume behavior.
|
|
|
981
1147
|
For `dedupe --scan latest`, matching across worktrees or clones requires a Git
|
|
982
1148
|
executable outside all saved scan targets. If a historical target includes the
|
|
983
1149
|
available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
|
|
984
|
-
explicit saved scan ID. Exact-path `latest` lookup
|
|
1150
|
+
explicit saved scan ID. Exact-path `latest` lookup works without Git for non-Git
|
|
1151
|
+
scan targets; recorded Git generations require a trusted Git executable to verify
|
|
1152
|
+
that the checkout still owns its saved history.
|
|
985
1153
|
|
|
986
1154
|
Repeat `--codex KEY=VALUE` for supported native settings. For example,
|
|
987
1155
|
`--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
|
|
@@ -1078,7 +1246,7 @@ client during the scan, or receiving a canceled hosted execution records
|
|
|
1078
1246
|
Applications can choose how to collect and export these observations.
|
|
1079
1247
|
|
|
1080
1248
|
For filesystem and approval behavior, see the
|
|
1081
|
-
[local security model](
|
|
1249
|
+
[local security model](sdk.md#local-security-model).
|
|
1082
1250
|
|
|
1083
1251
|
### Environment variables
|
|
1084
1252
|
|
|
@@ -1111,6 +1279,10 @@ Python lookup: `--python` on commands that expose interpreter selection or SDK
|
|
|
1111
1279
|
`pythonPath`, then
|
|
1112
1280
|
`PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
|
|
1113
1281
|
works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
|
|
1282
|
+
On POSIX, `CODEX_CLI_PATH` and `PYTHON` preserve trailing whitespace in an
|
|
1283
|
+
explicit path that selects an executable. Use an absolute path or a `./`
|
|
1284
|
+
prefix for filenames beginning or ending in whitespace. Bare command names
|
|
1285
|
+
are trimmed before lookup.
|
|
1114
1286
|
|
|
1115
1287
|
### Troubleshooting
|
|
1116
1288
|
|
|
@@ -1140,6 +1312,11 @@ and does not migrate existing credentials or reports.
|
|
|
1140
1312
|
Sandbox startup errors include the native diagnostic followed by a command to
|
|
1141
1313
|
reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
|
|
1142
1314
|
|
|
1315
|
+
If Windows Application Control blocks `windows.node` while validating a scan
|
|
1316
|
+
output directory, look for the module's block event in Event Viewer under
|
|
1317
|
+
Applications and Services Logs → Microsoft → Windows → CodeIntegrity → Operational.
|
|
1318
|
+
[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)
|
|
1319
|
+
|
|
1143
1320
|
On Windows, credential-home checks require trusted ownership and permissions
|
|
1144
1321
|
through every ancestor, including the volume root. Codex Security can repair
|
|
1145
1322
|
the credential home and its descendants; it does not change ancestor ownership
|
|
@@ -1219,8 +1396,9 @@ work is needed, the scan is preserved and you can run `scans match --all`.
|
|
|
1219
1396
|
|
|
1220
1397
|
A scan with a cost limit requires complete token usage for its recorded scan,
|
|
1221
1398
|
worker, and custom validation sessions before the SDK returns a completed result.
|
|
1222
|
-
|
|
1223
|
-
`backports.zstd`
|
|
1399
|
+
The workbench reads compressed `.jsonl.zst` sessions with `compression.zstd`
|
|
1400
|
+
(Python 3.14+) or `backports.zstd` when available. Otherwise it uses the
|
|
1401
|
+
Node.js decoder bundled with the plugin.
|
|
1224
1402
|
Missing or unreadable usage fails budget verification. Without a limit, usage
|
|
1225
1403
|
reporting remains best effort.
|
|
1226
1404
|
|
|
@@ -1314,7 +1492,8 @@ the campaign a joint source review across repositories. For that workflow, use
|
|
|
1314
1492
|
|
|
1315
1493
|
Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
|
|
1316
1494
|
selection. It lists repositories pushed in the last 90 days, excluding forks
|
|
1317
|
-
and archives, asks
|
|
1495
|
+
and archives, asks where to save results, and saves the selection as `repositories.csv`.
|
|
1496
|
+
Pass `--output-dir DIR` to set the initial answer in the wizard.
|
|
1318
1497
|
Private checkouts use your GitHub CLI login.
|
|
1319
1498
|
|
|
1320
1499
|
For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
|
|
@@ -1330,7 +1509,32 @@ codex-security bulk-scan repositories.csv \
|
|
|
1330
1509
|
--output-dir /path/outside/repositories/results --workers 4
|
|
1331
1510
|
```
|
|
1332
1511
|
|
|
1512
|
+
`--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
|
|
1513
|
+
estimated limit among the pending repositories and their possible attempts for
|
|
1514
|
+
this invocation, including recovery. For example, a $12 limit with three pending
|
|
1515
|
+
repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
|
|
1516
|
+
overrun reduces the remaining budget for queued attempts. In-flight work can
|
|
1517
|
+
exceed a limit. The total limit skips model-based matching and owner suggestions,
|
|
1518
|
+
including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
|
|
1519
|
+
limit and includes prior recorded usage in its cost estimate.
|
|
1520
|
+
|
|
1333
1521
|
Bulk scans use clean shallow checkouts and support repository/path scopes.
|
|
1522
|
+
Bulk checkout, scan, and recovery processes select host tools outside every local
|
|
1523
|
+
source and campaign checkout. Inventory uses an external ripgrep executable or
|
|
1524
|
+
the copy shipped with the selected Codex installation.
|
|
1525
|
+
|
|
1526
|
+
On POSIX, campaign processes and script-based inventory tools search readable
|
|
1527
|
+
tool directories. Launchers must be readable so their shebang interpreters can
|
|
1528
|
+
be checked. Use an absolute interpreter path for campaign scripts, including
|
|
1529
|
+
`#!/usr/bin/env sh`, because workers run in different directories. If a directory
|
|
1530
|
+
contains an ineligible executable, its other tools remain available through a
|
|
1531
|
+
temporary PATH. Scripts using the system `/bin/sh` or `/usr/bin/env` run from
|
|
1532
|
+
their installed location when the packaged dispatcher can start. Keep other
|
|
1533
|
+
prefix-sensitive tools, including Python virtual environments, in directories
|
|
1534
|
+
where every entry can be used. On Windows, the campaign omits a tool directory
|
|
1535
|
+
from the child PATH if its Git, ripgrep, or Node executable link passes through a
|
|
1536
|
+
selected source.
|
|
1537
|
+
|
|
1334
1538
|
CSV scopes are literal paths relative to each checkout, including names such
|
|
1335
1539
|
as `~/src`.
|
|
1336
1540
|
Configured diff or working-tree scopes are rejected unless every affected row
|
|
@@ -1341,10 +1545,10 @@ Use `-c FILE` for shared settings; CSV mode/scope override file values.
|
|
|
1341
1545
|
`--post-scan-prompt-file` runs a follow-up even after failure, but not after
|
|
1342
1546
|
cancellation or a cost stop.
|
|
1343
1547
|
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
attempt
|
|
1548
|
+
By default, `bulk-scan` runs up to four repositories concurrently and tries each
|
|
1549
|
+
unfinished CSV row once per run. With `--max-attempts 2`, a row that fails
|
|
1550
|
+
attempts 1 and 2 gets up to two more attempts (3 and 4) on the next run.
|
|
1551
|
+
An occupied attempt directory stops that row and prompts for `--recover`.
|
|
1348
1552
|
If an ordinary attempt finds its checkout path already occupied, it stops before
|
|
1349
1553
|
fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
|
|
1350
1554
|
existing checkout before an ordinary retry.
|
|
@@ -1361,6 +1565,12 @@ require a new output directory. Version 1 manifests also require a new directory
|
|
|
1361
1565
|
because their original knowledge inputs and direct overrides cannot be verified.
|
|
1362
1566
|
Worker and retry counts can change when resuming.
|
|
1363
1567
|
|
|
1568
|
+
On POSIX, local repository paths retain `..` components in the campaign manifest
|
|
1569
|
+
so distinct symlink traversals remain distinct sources. Older campaigns may have
|
|
1570
|
+
recorded a normalized absolute path instead. Use that recorded path to resume the
|
|
1571
|
+
previously selected source; it can differ from the physical target selected by
|
|
1572
|
+
the original traversal. Use a new output directory to scan the corrected target.
|
|
1573
|
+
|
|
1364
1574
|
### Recovering failed or interrupted bulk scans
|
|
1365
1575
|
|
|
1366
1576
|
Use the original CSV, output directory, and options:
|
|
@@ -1381,7 +1591,7 @@ failed or interrupted attempt:
|
|
|
1381
1591
|
revision, preserving old artifacts and checkouts.
|
|
1382
1592
|
|
|
1383
1593
|
Each nonempty committed line in `results.jsonl` must be valid JSON with a string
|
|
1384
|
-
task ID and a positive safe integer attempt number.
|
|
1594
|
+
task ID from the manifest and a positive safe integer attempt number. For an invalid line,
|
|
1385
1595
|
the command reports its line number and preserves the ledger. Restore a complete
|
|
1386
1596
|
ledger backup that includes every committed attempt, or start a separate campaign
|
|
1387
1597
|
in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
|
|
@@ -1457,13 +1667,13 @@ Supply the validation prompt again when rerunning.
|
|
|
1457
1667
|
|
|
1458
1668
|
Choose the command by what you want to keep. [Scanner guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) list the accepted vendor formats.
|
|
1459
1669
|
|
|
1460
|
-
| Input and goal | Command
|
|
1461
|
-
| ------------------------------------------------------------ |
|
|
1462
|
-
| Save vendor evidence for a checkout | `publish findings FILE --to local`
|
|
1463
|
-
| Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud)
|
|
1464
|
-
| Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
|
|
1465
|
-
| Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues)
|
|
1466
|
-
| Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan)
|
|
1670
|
+
| Input and goal | Command | Service contacted | Where to find the result |
|
|
1671
|
+
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
1672
|
+
| Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
|
|
1673
|
+
| Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
|
|
1674
|
+
| Collect upstream records to a file | `import continuum`, `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
|
|
1675
|
+
| Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
|
|
1676
|
+
| Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
|
|
1467
1677
|
|
|
1468
1678
|
For `publish findings`, `--to` is required. With `--to local`, `--repository`
|
|
1469
1679
|
takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
|
|
@@ -1480,8 +1690,13 @@ codex-security publish findings /private/path/endor-findings.json --provider end
|
|
|
1480
1690
|
After reviewing the findings and exclusions, rerun the command without
|
|
1481
1691
|
`--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
|
|
1482
1692
|
|
|
1693
|
+
When you pass `--source-repository-url` to `publish findings`, the command warns
|
|
1694
|
+
on stderr to verify that every finding belongs to the repository you specify.
|
|
1695
|
+
|
|
1483
1696
|
For Tenable One Code Repository findings, use `--provider tenable --to local` and set `--source-repository-url` to the checkout’s verified HTTPS remote. [Tenable export and import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/tenable.md)
|
|
1484
1697
|
|
|
1698
|
+
For CrowdStrike FCS CLI 4.x IaC reports, use `--provider crowdstrike --to local` and select the directory where FCS ran with `--repository`. It does not need to be a Git checkout, but each scanned file must be unchanged since the scan. Add `--source-repository-url` to record the repository; it must match a fetch remote when the directory is a Git checkout. A `git::https://` report names its repository, and a different `--source-repository-url` stops the import. [CrowdStrike import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/crowdstrike.md)
|
|
1699
|
+
|
|
1485
1700
|
Local readback uses `findings imported [PATH]`. The path defaults to the current
|
|
1486
1701
|
directory. Each imported record starts as `not_assessed`. Unknown revisions and
|
|
1487
1702
|
locations stay unknown. Repository-scoped sources are checked against comparable
|
|
@@ -1512,9 +1727,36 @@ Use `--provider endor` for one Endor project and context. The
|
|
|
1512
1727
|
[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
|
|
1513
1728
|
SARIF compatibility, and the local preview.
|
|
1514
1729
|
|
|
1730
|
+
## Collect AWS Continuum issues
|
|
1731
|
+
|
|
1732
|
+
`import continuum ENVIRONMENT_ID --format json` writes one report to standard
|
|
1733
|
+
output after collecting every issue page and fetching each issue's linked
|
|
1734
|
+
findings, prevalidation signals (`EVIDENCE`), and validation results
|
|
1735
|
+
(`VALIDATION_EVIDENCE`). Install AWS CLI v2.38.5 or later outside the checkout.
|
|
1736
|
+
The command requires exactly one configured Git repository and records it in the
|
|
1737
|
+
report. It collects patches when Git is the only source.
|
|
1738
|
+
S3 sources are allowed alongside that repository.
|
|
1739
|
+
Collection covers the whole environment. Pass the short
|
|
1740
|
+
Continuum environment ID. Optional
|
|
1741
|
+
`--aws-profile PROFILE` and `--aws-region REGION` override the AWS CLI's
|
|
1742
|
+
credential and Region selection. Preview and import the report separately
|
|
1743
|
+
with `publish findings FILE --provider continuum`. Pass
|
|
1744
|
+
`--source-repository-url URL` when the report has no saved repository URL.
|
|
1745
|
+
|
|
1746
|
+
For one finding, its matching validation evidence, and its generated patches, add `--finding-id FINDING_ID` and
|
|
1747
|
+
`--source-root CHECKOUT` with the absolute checkout path. The CLI uses
|
|
1748
|
+
`GetEnvironment` to verify that the environment has exactly one Git repository
|
|
1749
|
+
and no S3 sources before including unnamed patches. Pass
|
|
1750
|
+
`--repository-name AWS_SOURCE_NAME` for other environments to keep patches
|
|
1751
|
+
with that exact AWS source name. Validation is matched by AWS finding ID. When a
|
|
1752
|
+
validation artifact has no per-finding breakdown, the CLI uses `GetCodeIssue` to
|
|
1753
|
+
check that the issue covers just the selected finding. This mode accepts the same AWS profile and
|
|
1754
|
+
Region overrides and writes the finding-based JSON format for `publish findings`.
|
|
1755
|
+
[Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
|
|
1756
|
+
|
|
1515
1757
|
## Import SonarQube Cloud issues
|
|
1516
1758
|
|
|
1517
|
-
`import sonar --dry-run` writes a private
|
|
1759
|
+
`import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
|
|
1518
1760
|
that capture for the intended destination before confirming. A Cloud confirmation
|
|
1519
1761
|
saves the issues locally and publishes them. Use `--full-output` with
|
|
1520
1762
|
`--format json` or `--format jsonl` for a structured result.
|
|
@@ -1564,9 +1806,13 @@ Enterprise repository URL or its Cloud ID. Either works for retries. If
|
|
|
1564
1806
|
several connectors share the URL, use the ID. You can import before the
|
|
1565
1807
|
repository's first native scan.
|
|
1566
1808
|
|
|
1567
|
-
Cloud requires a file-backed ChatGPT login.
|
|
1568
|
-
|
|
1569
|
-
|
|
1809
|
+
Cloud requires a file-backed ChatGPT login. Codex Security signs in with the
|
|
1810
|
+
`cli_auth_credentials_store` set in your Codex `config.toml`
|
|
1811
|
+
(`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Without it, the login
|
|
1812
|
+
can be saved in the system keyring. To publish, set
|
|
1813
|
+
`cli_auth_credentials_store = "file"` there, then run `codex-security login`
|
|
1814
|
+
with the ChatGPT account you want to use. `codex-security login status`
|
|
1815
|
+
checks the current sign-in without changing credential storage.
|
|
1570
1816
|
|
|
1571
1817
|
### Review the Cloud destination
|
|
1572
1818
|
|
|
@@ -1577,11 +1823,10 @@ Run the command with `--dry-run --format json`. Check `accountId`,
|
|
|
1577
1823
|
- **Private findings inbox.** If the preview includes `privateImport`, the
|
|
1578
1824
|
report goes to your inbox. The repository and connector identify the
|
|
1579
1825
|
suggested assessment target. Check `format`, `bytes` and `sha256` in
|
|
1580
|
-
`privateImport` to identify the upload.
|
|
1581
|
-
`
|
|
1582
|
-
|
|
1583
|
-
|
|
1584
|
-
Findings, use `security.findings.v1`.
|
|
1826
|
+
`privateImport` to identify the upload. The CLI and SDK encode the reviewed
|
|
1827
|
+
occurrences as `security.findings.v1` when it fits. For Wiz and Endor, an
|
|
1828
|
+
inbox that requires native records or has a smaller upload limit can receive
|
|
1829
|
+
native records that reproduce the reviewed evidence.
|
|
1585
1830
|
- **Repository publisher.** Check `repository.environment_id` in each entry
|
|
1586
1831
|
of `requests`. The publisher checks the current source versions. Existing
|
|
1587
1832
|
records keep their environment. New records use the repository's authorized
|
|
@@ -1610,10 +1855,10 @@ instructions. API requests always use the API root. The older
|
|
|
1610
1855
|
### Resume interrupted imports
|
|
1611
1856
|
|
|
1612
1857
|
If the result includes `savedSubmission`, keep that checkpoint. Rerun the
|
|
1613
|
-
original command with `--dry-run --format json` using the same input, account,
|
|
1858
|
+
original command with `--dry-run --format json` using the same build, input, account,
|
|
1614
1859
|
destination, API endpoint and state directory. Check `cloudApiUrl`. If
|
|
1615
1860
|
`resumed` is true, confirm to continue the saved submission. If it's false,
|
|
1616
|
-
review the new submission before confirming.
|
|
1861
|
+
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
1862
|
|
|
1618
1863
|
- **Private inbox.** The CLI checks the report digest and reuses its saved
|
|
1619
1864
|
request IDs. It can read an accepted job even if the deployment has since
|
|
@@ -1699,7 +1944,10 @@ The provider guide describes [package JSON and CSV](https://github.com/openai/co
|
|
|
1699
1944
|
|
|
1700
1945
|
### Publish completed scans
|
|
1701
1946
|
|
|
1702
|
-
|
|
1947
|
+
The public `publish scan --help` menu describes Linear and custom publication
|
|
1948
|
+
from saved scans. The CSV input below belongs to Cloud publication.
|
|
1949
|
+
The following workflow is available to installations with Cloud publication access.
|
|
1950
|
+
Preview selected completed scans locally before uploading them.
|
|
1703
1951
|
|
|
1704
1952
|
```bash
|
|
1705
1953
|
codex-security publish scan --to cloud --dry-run --json
|
|
@@ -1713,12 +1961,15 @@ prefix of at least eight characters, or `latest` for the current repository.
|
|
|
1713
1961
|
Local sealed artifacts are required. Dry runs need no login or network access.
|
|
1714
1962
|
|
|
1715
1963
|
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
|
-
|
|
1964
|
+
`cli_auth_credentials_store = "file"` in Codex `config.toml`, then run
|
|
1965
|
+
`codex-security login` again. Login, scans and other commands use that setting
|
|
1966
|
+
for the Codex Security sign-in.
|
|
1967
|
+
A dedicated login using automatic storage can publish if Codex Security
|
|
1968
|
+
recorded the native file fallback. An unverified file can belong to another
|
|
1969
|
+
account, so Cloud publication requires an explicit file store for an ambient login.
|
|
1970
|
+
|
|
1971
|
+
Use `publish scan DIR --to cloud` for one directory outside history. For
|
|
1972
|
+
multiple directories, repeat `--scan-dir PATH`. Each must contain one completed sealed scan, not a bulk-run
|
|
1722
1973
|
directory or `results.jsonl`. Do not mix directories with `--scan`.
|
|
1723
1974
|
Cloud also accepts exported CSV:
|
|
1724
1975
|
|
|
@@ -1750,7 +2001,8 @@ Select one completed scan by ID, prefix, `latest`, or directory; omit the select
|
|
|
1750
2001
|
for the picker. Live publication and `--skip-existing` require local history.
|
|
1751
2002
|
A directory-only dry run does not.
|
|
1752
2003
|
|
|
1753
|
-
`--linear-project PROJECT_ID`
|
|
2004
|
+
`--linear-project PROJECT_ID` selects a project. Existing scripts using the deprecated
|
|
2005
|
+
`--project PROJECT_ID` spelling continue to work. Flags override
|
|
1754
2006
|
`CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
|
|
1755
2007
|
previews titles offline; `--json` returns structured output.
|
|
1756
2008
|
|
|
@@ -1762,10 +2014,10 @@ Keys are omitted from saved results; diagnostic messages remain unchanged.
|
|
|
1762
2014
|
|
|
1763
2015
|
```bash
|
|
1764
2016
|
codex-security publish check /path/to/completed-scan \
|
|
1765
|
-
--
|
|
2017
|
+
--linear-team TEAM_ID --json
|
|
1766
2018
|
```
|
|
1767
2019
|
|
|
1768
|
-
`publish check` verifies artifacts and recorded publications. With an API key,
|
|
2020
|
+
`publish check` verifies scan artifacts and recorded Linear publications. With an API key,
|
|
1769
2021
|
it also checks authentication and destination access. It does not test issue
|
|
1770
2022
|
creation; connected-app access is reported as `not-checked`.
|
|
1771
2023
|
|
|
@@ -1809,6 +2061,7 @@ codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
|
1809
2061
|
```
|
|
1810
2062
|
|
|
1811
2063
|
For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
|
|
2064
|
+
A records host can opt in to the CLI’s structured diagnostic records on its existing JSON-RPC connection. See the [records diagnostic protocol](classify-severity-records.md#cli-diagnostic-records).
|
|
1812
2065
|
The [records protocol](classify-severity-records.md) accepts immutable Markdown and
|
|
1813
2066
|
report snapshots and delegates model execution to the host.
|
|
1814
2067
|
|
|
@@ -1824,7 +2077,9 @@ request. It sends the config name without findings or account identifiers.
|
|
|
1824
2077
|
If the request fails, times out, or returns an invalid rubric, the built-in
|
|
1825
2078
|
rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
|
|
1826
2079
|
uses your policy for every review. Rubrics and repeatable `--knowledge-base`
|
|
1827
|
-
context accept text, PDF, DOCX, and directories.
|
|
2080
|
+
context accept text, PDF, DOCX, and directories. Select external documents directly.
|
|
2081
|
+
Links in the artifact directory or a saved checkout must stay inside their source.
|
|
2082
|
+
When `--scan` cannot verify the saved checkout, use the document's canonical path.
|
|
1828
2083
|
|
|
1829
2084
|
Each finding is classified three times by default. `--runs N` accepts
|
|
1830
2085
|
an integer from 1 through 10; SDK options use `classificationRuns` with the same
|
|
@@ -1866,15 +2121,17 @@ or effort. A successful
|
|
|
1866
2121
|
run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
|
|
1867
2122
|
unchanged.
|
|
1868
2123
|
|
|
1869
|
-
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe
|
|
1870
|
-
`
|
|
1871
|
-
|
|
2124
|
+
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe returns
|
|
2125
|
+
`scanRepresentativeFindingIds` for this selection, in the same order as its
|
|
2126
|
+
corpus-wide `uniqueFindingIds`.
|
|
1872
2127
|
Linear publication defaults to saved classification selection, omits exclusions,
|
|
1873
2128
|
and uses assessed severity for title and priority. Descriptions retain original
|
|
1874
2129
|
severity and add the classification rationale. Publication rejects incomplete or
|
|
1875
2130
|
stale assessments. It never reclassifies or rereads the rubric at publication time.
|
|
1876
2131
|
|
|
1877
2132
|
```bash
|
|
2133
|
+
# List the IDs you can pass to --finding-id.
|
|
2134
|
+
codex-security dedupe --scan SCAN_ID --json | jq -r '.scanRepresentativeFindingIds[]'
|
|
1878
2135
|
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
|
|
1879
2136
|
--finding-id FINDING_ID
|
|
1880
2137
|
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
|
|
@@ -1889,46 +2146,32 @@ import {
|
|
|
1889
2146
|
classifySeverity,
|
|
1890
2147
|
classifyScanSeverity,
|
|
1891
2148
|
classifyScanDirectorySeverity,
|
|
2149
|
+
deduplicateScanDirectory,
|
|
1892
2150
|
publishScan,
|
|
1893
|
-
type FindingsDocument,
|
|
1894
2151
|
} from "@openai/codex-security";
|
|
1895
|
-
import { readFile } from "node:fs/promises";
|
|
1896
|
-
import { join } from "node:path";
|
|
1897
2152
|
|
|
1898
2153
|
// Assess supplied reports in memory.
|
|
1899
|
-
|
|
2154
|
+
await classifySeverity(findings, {
|
|
1900
2155
|
rubricPath: "/path/to/policy.md",
|
|
1901
2156
|
knowledgeBasePaths: ["/path/to/context.md"],
|
|
1902
2157
|
});
|
|
1903
2158
|
|
|
1904
2159
|
// Save assessments for a scan ID or sealed directory.
|
|
1905
2160
|
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))!;
|
|
2161
|
+
const dedupeResult = await deduplicateScanDirectory(scanDirectory, {
|
|
2162
|
+
repository: "/path/to/repository",
|
|
1920
2163
|
});
|
|
1921
|
-
await classifyScanDirectorySeverity(scanDirectory, {
|
|
2164
|
+
const classification = await classifyScanDirectorySeverity(scanDirectory, {
|
|
1922
2165
|
rubricPath: "/path/to/policy.md",
|
|
1923
|
-
findingIds:
|
|
2166
|
+
findingIds: dedupeResult.scanRepresentativeFindingIds,
|
|
1924
2167
|
});
|
|
1925
2168
|
|
|
1926
|
-
//
|
|
2169
|
+
// Preview Linear publication for those same findings using their assessments.
|
|
1927
2170
|
await publishScan(scanDirectory, {
|
|
1928
2171
|
destination: "linear",
|
|
1929
2172
|
teamId: "TEAM_ID",
|
|
1930
2173
|
classification,
|
|
1931
|
-
findingIds:
|
|
2174
|
+
findingIds: dedupeResult.scanRepresentativeFindingIds,
|
|
1932
2175
|
dryRun: true,
|
|
1933
2176
|
});
|
|
1934
2177
|
```
|
|
@@ -2035,24 +2278,41 @@ attach only their owner's session. Unrecorded earlier retry sessions may be abse
|
|
|
2035
2278
|
## Scan history and reruns
|
|
2036
2279
|
|
|
2037
2280
|
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
|
-
|
|
2281
|
+
least eight characters. Reading empty history leaves the workbench database uninitialized.
|
|
2282
|
+
|
|
2283
|
+
Linked Git worktrees share scans, findings, and reviewer decisions when their
|
|
2284
|
+
scans record the same repository generation in the selected state database.
|
|
2285
|
+
Older scans without this evidence remain target-local. Removed worktrees retain
|
|
2286
|
+
their recorded history; a reused checkout path does not inherit its previous
|
|
2287
|
+
owner's history. Separately verified clones can still be compared explicitly,
|
|
2288
|
+
but their finding histories remain separate.
|
|
2289
|
+
|
|
2290
|
+
Finding confirmation and automatic post-scan matching follow completion order
|
|
2291
|
+
in the workbench, without changing sealed report timestamps.
|
|
2292
|
+
|
|
2293
|
+
| Command | Purpose |
|
|
2294
|
+
| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
2295
|
+
| `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
|
|
2296
|
+
| `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
|
|
2297
|
+
| `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
|
|
2298
|
+
| `scans resume SCAN_ID` | Continue an interrupted Standard or Deep Scan. |
|
|
2299
|
+
| `scans rerun [SCAN_ID]` | Rerun a saved recipe in its checkout. |
|
|
2300
|
+
| `scans match --all` | Match completed scans in this repository generation, including linked worktrees. |
|
|
2301
|
+
| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
|
|
2302
|
+
| `findings list [REPOSITORY]` | List open findings. |
|
|
2303
|
+
| `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
|
|
2304
|
+
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
|
|
2305
|
+
|
|
2306
|
+
In the terminal, `findings list` shows the occurrence ID for each open finding.
|
|
2307
|
+
Copy that ID into `findings false-positive` with your reason. Subsequent scans can
|
|
2308
|
+
use the explanation while it applies. In `scans show SCAN_ID --json`, each
|
|
2309
|
+
displayed occurrence has its saved rationale in `triage.note` after dismissal. The list identifies
|
|
2310
|
+
a repository with no saved scan history separately from one with zero open findings.
|
|
2311
|
+
From an unregistered Git subdirectory with no scan history of its own, it uses the worktree root.
|
|
2312
|
+
|
|
2313
|
+
With an omitted ID or the literal `latest`, `scans show` selects the latest completed scan, while `scans logs`
|
|
2314
|
+
selects the latest scan of any status. Both prefer a scan in the current
|
|
2315
|
+
worktree when one qualifies. After a successful scan followed by a
|
|
2056
2316
|
failed or active scan, these defaults refer to different runs. Human output
|
|
2057
2317
|
identifies the selected run, labels its saved update time, and gives matching
|
|
2058
2318
|
commands with its full scan ID:
|
|
@@ -2070,7 +2330,10 @@ history. Inspect its saved status before choosing resume or rerun, and supply
|
|
|
2070
2330
|
the original custom prompt files for reruns. Structured history and log output
|
|
2071
2331
|
and command selection defaults are unchanged.
|
|
2072
2332
|
|
|
2073
|
-
|
|
2333
|
+
Without an ID, rerun selects the latest completed scan in the current worktree.
|
|
2334
|
+
If only a related checkout has a completed scan, rerun shows its ID, path, and
|
|
2335
|
+
revision. Pass that ID to run the saved recipe using the files currently at its
|
|
2336
|
+
saved checkout and context paths. Reruns do not reload project files.
|
|
2074
2337
|
The readable scan recipe records your authentication choice. A separate private
|
|
2075
2338
|
replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
|
|
2076
2339
|
`model_providers` settings, including any credentials written directly in
|
|
@@ -2106,6 +2369,17 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
|
2106
2369
|
writable, and outside the target repository. Session logs may contain sensitive
|
|
2107
2370
|
data even though scan recipes do not store credentials.
|
|
2108
2371
|
|
|
2372
|
+
Keep the same state directory across linked worktrees. Changing it selects
|
|
2373
|
+
separate history, artifacts, and a dedicated Codex sign-in. `--scan-root`
|
|
2374
|
+
filters recorded artifact paths; it does not import another directory's scans.
|
|
2375
|
+
|
|
2376
|
+
The workbench records the outer checkout directory when it registers a target.
|
|
2377
|
+
A later nested checkout cannot make tools from that directory eligible for
|
|
2378
|
+
automatic discovery. When an older saved target lacks a recorded checkout
|
|
2379
|
+
directory, set `CODEX_SECURITY_GIT` to the absolute path of a trusted Git
|
|
2380
|
+
executable outside the checkouts. If you use a system Python instead of the
|
|
2381
|
+
Codex managed runtime, set `PYTHON` to the absolute path of your interpreter.
|
|
2382
|
+
|
|
2109
2383
|
Saved scan logs retain the finishing turn, including its final response, and
|
|
2110
2384
|
exclude later turns once the scan records a completion boundary. Older scans
|
|
2111
2385
|
retain the full history of their attributed sessions and keep their existing
|
|
@@ -2117,19 +2391,42 @@ work on all supported Node.js versions, including logs, feedback attachments,
|
|
|
2117
2391
|
usage accounting, and saved-session discovery for resume. A bundled decoder
|
|
2118
2392
|
reads concatenated frames and reports truncated streams as collection errors.
|
|
2119
2393
|
|
|
2120
|
-
### Resuming an interrupted
|
|
2394
|
+
### Resuming an interrupted scan
|
|
2121
2395
|
|
|
2122
2396
|
```bash
|
|
2123
2397
|
codex-security scans list --scan-root /path/to/security-scans
|
|
2124
2398
|
codex-security scans resume SCAN_ID
|
|
2125
2399
|
```
|
|
2126
2400
|
|
|
2401
|
+
The terminal list shows the full scan ID and labels the last activity of a
|
|
2402
|
+
`running` scan after 24 hours without an update. For a Standard or Deep Scan with a saved
|
|
2403
|
+
launch recipe and its original session, it also shows the resume command to use after interruption.
|
|
2404
|
+
|
|
2127
2405
|
The scan must still be `running`, with its original checkout, output directory,
|
|
2128
2406
|
and Codex session in the same state directory. Checkout identity, revision, and
|
|
2129
2407
|
contents must match. Completed, failed, and canceled scans need a rerun instead.
|
|
2130
2408
|
|
|
2131
|
-
|
|
2132
|
-
|
|
2409
|
+
On Windows, keep the protected `.codex-security-resume` directory in the scan
|
|
2410
|
+
output. It lets the workbench verify the original output even before the first
|
|
2411
|
+
checkpoint. If an older scan stopped with an empty output, start a new scan with
|
|
2412
|
+
`codex-security scans rerun SCAN_ID`.
|
|
2413
|
+
|
|
2414
|
+
New Windows Standard and Deep Scans also record the checkout's native volume and file ID
|
|
2415
|
+
when the filesystem supplies them. Validation and remediation verify the same
|
|
2416
|
+
checkout identity. An older scan can resume across Python
|
|
2417
|
+
versions when its saved checkout identity can be verified. If the workbench
|
|
2418
|
+
cannot verify it, resume with the Python runtime that started the scan or use
|
|
2419
|
+
`codex-security scans rerun SCAN_ID` to start a new scan.
|
|
2420
|
+
|
|
2421
|
+
Resume keeps the scan ID, saved settings and instructions, completed workers, artifacts,
|
|
2422
|
+
and accumulated cost. A Standard scan continues in its original Codex session with
|
|
2423
|
+
the same `--max-cost` limit and `--max-time` deadline. Only one CLI or SDK call
|
|
2424
|
+
can run it at a time. If the connection fails after the session is saved, the CLI
|
|
2425
|
+
prints the resume command. Work since the last checkpoint may need to be repeated.
|
|
2426
|
+
Use `scans rerun` for canceled or failed scans, including authentication failures.
|
|
2427
|
+
For custom validation, rerun with the original validation instructions.
|
|
2428
|
+
|
|
2429
|
+
Knowledge-bearing scans save their extracted documents in
|
|
2133
2430
|
the private `.scan-knowledge.json` continuation file beside the scan artifacts.
|
|
2134
2431
|
Resume verifies and uses that snapshot even if the original files changed or were
|
|
2135
2432
|
deleted. Preserve it with the scan directory; canonical reports do not embed its
|
|
@@ -2147,7 +2444,11 @@ to update campaign receipts. Individual resume does not update `results.jsonl`.
|
|
|
2147
2444
|
|
|
2148
2445
|
### Matching saved scans
|
|
2149
2446
|
|
|
2150
|
-
|
|
2447
|
+
Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the model
|
|
2448
|
+
and save its matching decisions. Pass `--force` to recompute saved matches.
|
|
2449
|
+
The older `scans match BEFORE AFTER` spelling is also supported.
|
|
2450
|
+
Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
|
|
2451
|
+
The SDK accepts matching plans with inline findings and asks compatible workbenches to send each scan’s findings once.
|
|
2151
2452
|
Comparisons classify findings as new, persisting, reopened, not observed, resolved,
|
|
2152
2453
|
or unknown. An absent finding in the later scope is not observed; absence alone
|
|
2153
2454
|
does not verify remediation. A finding is resolved only after it was explicitly
|
|
@@ -2158,11 +2459,12 @@ One comparison ID is compared with the latest completed scan.
|
|
|
2158
2459
|
codex-security scans match --all --force --model gpt-6.1-sol --effort high
|
|
2159
2460
|
```
|
|
2160
2461
|
|
|
2161
|
-
|
|
2162
|
-
|
|
2163
|
-
|
|
2164
|
-
|
|
2165
|
-
|
|
2462
|
+
Standard and Deep scans can identify matching candidates in a single target or
|
|
2463
|
+
corresponding paths in linked worktrees with the same saved repository
|
|
2464
|
+
generation. When the revision and snapshot digest agree, matching flags findings
|
|
2465
|
+
with different anchors that share a unique rule, first displayed source range,
|
|
2466
|
+
and optional instance. Matching preserves the case of saved paths. Codex can
|
|
2467
|
+
request the saved evidence to distinguish separate causes at that site. Automatic matching
|
|
2166
2468
|
under a cost limit keeps its single comparison call.
|
|
2167
2469
|
|
|
2168
2470
|
Only high-confidence root-cause matches are grouped. Uncertain and related
|
|
@@ -2214,6 +2516,10 @@ must already exist.
|
|
|
2214
2516
|
|
|
2215
2517
|
SARIF is the default format, and `./results.sarif` is the default output path.
|
|
2216
2518
|
Use `--export-format json` or `--export-format csv` to choose another format.
|
|
2519
|
+
An existing default output file is preserved. Pass `--output FILE` to choose
|
|
2520
|
+
a filename or explicitly replace it. Use `--output -` to pipe the complete
|
|
2521
|
+
artifact. Response filters, token controls, and `--full-output` require a
|
|
2522
|
+
command that returns a formatted response.
|
|
2217
2523
|
To select a saved scan by its ID and export JSON, run:
|
|
2218
2524
|
|
|
2219
2525
|
```bash
|
|
@@ -2385,10 +2691,11 @@ codex-security install-hook /path/to/repository
|
|
|
2385
2691
|
|
|
2386
2692
|
To migrate an existing generated hook, verify it is a regular file used only by
|
|
2387
2693
|
this repository and contains only the generated commands. Rerun `install-hook`
|
|
2388
|
-
with `--fail-on-severity`
|
|
2389
|
-
`npx` hook and
|
|
2390
|
-
paths.
|
|
2391
|
-
|
|
2694
|
+
with the desired `--fail-on-severity` level to change the threshold. The installer
|
|
2695
|
+
recognizes the legacy `npx` hook and earlier generated templates with matching
|
|
2696
|
+
absolute Node and CLI paths. It refuses to replace a hand-edited hook.
|
|
2697
|
+
On POSIX, reinstalling a recognized hook restores its owner execute bit if Git
|
|
2698
|
+
could not execute it. The installer checks that the resulting hook is executable.
|
|
2392
2699
|
The installer uses host Git for the selected repository and respects
|
|
2393
2700
|
`core.hooksPath`.
|
|
2394
2701
|
|
|
@@ -2417,6 +2724,14 @@ codex-security patch --scan SCAN_ID --severity high --json
|
|
|
2417
2724
|
codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
|
|
2418
2725
|
```
|
|
2419
2726
|
|
|
2727
|
+
For `validate`, `patch`, and `verify-fix`, an explicit local file URL such as
|
|
2728
|
+
`file:///home/reviewer/finding.md` (Windows: `file:///C:/reviews/finding.md`)
|
|
2729
|
+
requires the file to exist. A missing file stops the command before the model
|
|
2730
|
+
runs. Use `pathToFileURL(absolutePath).href` in Node to encode spaces and
|
|
2731
|
+
special characters correctly. Absolute paths and paths starting with `~/`, `./`, or `../`
|
|
2732
|
+
also require an existing file. Use `text:/path is exposed` to pass path-shaped
|
|
2733
|
+
prose verbatim, or `text:text:example` for a finding that starts with `text:`.
|
|
2734
|
+
|
|
2420
2735
|
Context inputs are optional and can be combined:
|
|
2421
2736
|
|
|
2422
2737
|
- `--context TEXT` adds inline security context or reviewer feedback.
|
|
@@ -2424,6 +2739,7 @@ Context inputs are optional and can be combined:
|
|
|
2424
2739
|
- Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
|
|
2425
2740
|
document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
|
|
2426
2741
|
are searched recursively; binary files, symlinks, and Git metadata are skipped.
|
|
2742
|
+
When validating from a Git checkout, select external documents directly.
|
|
2427
2743
|
|
|
2428
2744
|
Inline and file context are included in the prompt. Knowledge-base documents are
|
|
2429
2745
|
prepared in a temporary directory for Codex to read during the assessment, then
|
|
@@ -2574,7 +2890,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
|
|
|
2574
2890
|
task. The container must provide it. There is no automatic fallback; optional
|
|
2575
2891
|
patch-risk assessment still uses its read-only sandbox.
|
|
2576
2892
|
|
|
2577
|
-
`scan --patch` runs after a complete scan
|
|
2893
|
+
`scan --patch` runs after a complete scan without a cost limit. A cost-limited
|
|
2894
|
+
scan saves the findings and skips the interactive patch offer. Use
|
|
2895
|
+
`codex-security patch --scan SCAN_ID` to patch separately.
|
|
2896
|
+
`--patch-severity` defaults to `low`;
|
|
2578
2897
|
`high` selects high and critical findings. Interactive users can select findings
|
|
2579
2898
|
and add instructions. The interactive finding browser lists critical, high,
|
|
2580
2899
|
medium, then low findings, preserving scan order within each severity.
|
|
@@ -2641,7 +2960,10 @@ SDK's local `validate()` and `patch()` methods use the same fallback.
|
|
|
2641
2960
|
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
2642
2961
|
|
|
2643
2962
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
2644
|
-
|
|
2963
|
+
Without output options, each finding prints a verdict and its evidence.
|
|
2964
|
+
Explicit output formats, field selection and token controls operate on the
|
|
2965
|
+
structured result containing `repository`, optional `scanId`, and `results`.
|
|
2966
|
+
Exit codes are `0` when all findings are
|
|
2645
2967
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|
|
2646
2968
|
With `--json` or `--format jsonl`, authentication and execution failures return
|
|
2647
2969
|
`status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
|
|
@@ -2654,21 +2976,112 @@ retain exit codes `130` and `143` without a result.
|
|
|
2654
2976
|
|
|
2655
2977
|
## Command discovery and integrations
|
|
2656
2978
|
|
|
2657
|
-
|
|
2658
|
-
|
|
2979
|
+
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.
|
|
2980
|
+
|
|
2981
|
+
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
2982
|
`--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
|
|
2660
2983
|
`--filter-output`, `--token-limit`, and `--token-offset` options accept either
|
|
2661
2984
|
`--option value` or `--option=value`.
|
|
2662
2985
|
|
|
2986
|
+
`--token-limit` and `--token-offset` take nonnegative integers and select a
|
|
2987
|
+
text view of the formatted result. Truncated JSON and JSONL views are returned
|
|
2988
|
+
as a JSON string containing the excerpt and its token range. With
|
|
2989
|
+
`--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
|
|
2990
|
+
the next page when more tokens are available. `--token-count` returns the
|
|
2991
|
+
estimated size instead. A failed full-output JSON or JSONL response always
|
|
2992
|
+
retains its error code and message. If the failure carries result data,
|
|
2993
|
+
`--token-count` reports its size in `meta.tokenCount`.
|
|
2994
|
+
|
|
2663
2995
|
`skills add` syncs generated CLI command guidance; it does not install the full
|
|
2664
2996
|
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
|
|
2665
2997
|
only read-only `info` because the transport cannot cancel scans. For the plugin's
|
|
2666
2998
|
scan, triage, patch, and verification workflows, see the
|
|
2667
2999
|
[agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
|
|
2668
3000
|
|
|
3001
|
+
Both installers default to `--scope user`. Use `--scope project` for the current
|
|
3002
|
+
directory. Existing scripts can continue using `--no-global` for project scope.
|
|
3003
|
+
Inspect either command with `--help`, `--schema`, or `--version` before installing.
|
|
3004
|
+
|
|
3005
|
+
`skills add --depth 0` creates a single skill. The default depth of 1 groups
|
|
3006
|
+
guidance by top-level command. To check the installed files, use the same
|
|
3007
|
+
depth with `skills list`, for example `skills list --depth 0 --json`. Each
|
|
3008
|
+
entry includes its canonical `SKILL.md` locations in the current project and
|
|
3009
|
+
user profile.
|
|
3010
|
+
|
|
3011
|
+
`mcp add` registers detected compatible clients. If it finds none in the
|
|
3012
|
+
selected scope, choose a client with `--agent NAME` (repeatable), or register
|
|
3013
|
+
every compatible client with `--all`. For example, `mcp add --scope project
|
|
3014
|
+
--agent cursor` writes Cursor's project configuration. In user scope, Codex
|
|
3015
|
+
detection and registration use `CODEX_HOME` when set. Amp supports user
|
|
3016
|
+
registration only.
|
|
3017
|
+
|
|
3018
|
+
The default launcher runs `npx --yes @openai/codex-security --mcp`. To register
|
|
3019
|
+
an installed executable, use its name or path with `--exec` and repeat
|
|
3020
|
+
`--arg=VALUE` for each argument. Each value is stored literally, including
|
|
3021
|
+
spaces, empty arguments, and leading dashes. To run an npm package, select
|
|
3022
|
+
`--package NAME`. The existing `--command` accepts a command line or HTTP(S)
|
|
3023
|
+
URL. Quotes group command-line words, and backslashes are literal. A bare
|
|
3024
|
+
executable name is stored directly. Use `--exec` for a path with
|
|
3025
|
+
spaces, including when the executable will be installed on another machine.
|
|
3026
|
+
|
|
3027
|
+
```bash
|
|
3028
|
+
codex-security mcp add --agent cursor --exec "/opt/My Tools/server" --arg=--mcp
|
|
3029
|
+
codex-security mcp add --agent cursor --package @openai/codex-security --arg=--mcp
|
|
3030
|
+
```
|
|
3031
|
+
|
|
3032
|
+
`mcp doctor` checks the current CLI's server startup and tool catalog. To
|
|
3033
|
+
verify a registered launcher, connect from the client where it was registered.
|
|
3034
|
+
|
|
2669
3035
|
For local findings storage, deduplication, and custom endpoints, see the
|
|
2670
3036
|
[findings guide](findings-service.md).
|
|
2671
3037
|
|
|
3038
|
+
### Shell completions
|
|
3039
|
+
|
|
3040
|
+
The generated scripts register both `codex-security` and `cs`. Choose your shell
|
|
3041
|
+
and open a new session after saving the setup.
|
|
3042
|
+
|
|
3043
|
+
**Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:
|
|
3044
|
+
|
|
3045
|
+
```bash
|
|
3046
|
+
source <(codex-security completions bash)
|
|
3047
|
+
```
|
|
3048
|
+
|
|
3049
|
+
**Zsh.** In `~/.zshrc`, load the generated script after your completion system
|
|
3050
|
+
calls `compinit`. If you initialize completions yourself, use:
|
|
3051
|
+
|
|
3052
|
+
```zsh
|
|
3053
|
+
autoload -Uz compinit
|
|
3054
|
+
compinit
|
|
3055
|
+
source <(codex-security completions zsh)
|
|
3056
|
+
```
|
|
3057
|
+
|
|
3058
|
+
**Fish.** Add this line to `~/.config/fish/config.fish`:
|
|
3059
|
+
|
|
3060
|
+
```fish
|
|
3061
|
+
codex-security completions fish | source
|
|
3062
|
+
```
|
|
3063
|
+
|
|
3064
|
+
**Nushell.** Save the generated closures alongside `config.nu`:
|
|
3065
|
+
|
|
3066
|
+
```nu
|
|
3067
|
+
codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)
|
|
3068
|
+
```
|
|
3069
|
+
|
|
3070
|
+
In `config.nu`, source the file and dispatch the two names to their completers:
|
|
3071
|
+
|
|
3072
|
+
```nu
|
|
3073
|
+
source codex-security-completions.nu
|
|
3074
|
+
let previous_completer = $env.config.completions.external.completer?
|
|
3075
|
+
$env.config.completions.external.enable = true
|
|
3076
|
+
$env.config.completions.external.completer = {|spans|
|
|
3077
|
+
match $spans.0 {
|
|
3078
|
+
"codex-security" => { do $_incur_complete_codex_security $spans }
|
|
3079
|
+
"cs" => { do $_incur_complete_cs $spans }
|
|
3080
|
+
_ => { if $previous_completer != null { do $previous_completer $spans } }
|
|
3081
|
+
}
|
|
3082
|
+
}
|
|
3083
|
+
```
|
|
3084
|
+
|
|
2672
3085
|
### Hosted Standard scan
|
|
2673
3086
|
|
|
2674
3087
|
`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.
|