@openai/codex-security 0.8.3 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -746
- package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
- package/_bundled_plugin/.mcp.json +7 -1
- package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
- package/_bundled_plugin/examples/completed-scan/report.md +11 -8
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
- package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
- package/_bundled_plugin/mcp/helpers.mjs +2 -11
- package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
- package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
- 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/package.json +1 -0
- package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
- package/_bundled_plugin/mcp/server.mjs +2 -11
- package/_bundled_plugin/mcp/server.mjs.br +0 -0
- package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
- package/_bundled_plugin/references/artifact-storage.md +1 -1
- package/_bundled_plugin/references/baseline-auditor.md +18 -0
- package/_bundled_plugin/references/core-scan.md +5 -42
- package/_bundled_plugin/references/default-severity-rubric.md +9 -4
- package/_bundled_plugin/references/final-report.md +5 -3
- package/_bundled_plugin/references/finding-detail-fields.md +18 -18
- package/_bundled_plugin/references/focused-investigator.md +13 -0
- package/_bundled_plugin/references/sarif-adapter.md +8 -2
- package/_bundled_plugin/references/scan-artifacts.md +21 -12
- package/_bundled_plugin/references/scan-contract.md +27 -33
- package/_bundled_plugin/references/scan-prologue.md +2 -2
- package/_bundled_plugin/references/scan-runtime.md +4 -2
- package/_bundled_plugin/references/security-guidance.md +14 -1
- package/_bundled_plugin/references/validate-scan-findings.md +3 -0
- package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
- package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
- package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
- package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
- package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
- package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
- package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
- package/_bundled_plugin/scripts/finding_preview.py +20 -0
- package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
- package/_bundled_plugin/scripts/legacy_findings.py +148 -0
- package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
- package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
- package/_bundled_plugin/scripts/report_projection.py +81 -43
- package/_bundled_plugin/scripts/review_state.py +8 -2
- package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
- package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
- package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
- package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
- package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
- package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
- package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
- package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
- package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
- package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
- package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
- package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
- package/_bundled_plugin/scripts/workbench/storage.py +91 -7
- package/_bundled_plugin/scripts/workbench_cli.py +54 -14
- package/_bundled_plugin/scripts/workbench_constants.py +12 -0
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
- package/_bundled_plugin/scripts/workbench_db.py +562 -303
- package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
- package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
- package/_bundled_plugin/scripts/workbench_progress.py +169 -4
- package/_bundled_plugin/scripts/workbench_publication.py +16 -13
- package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
- package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
- package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
- package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
- package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
- package/_bundled_plugin/scripts/workbench_schema.py +258 -63
- package/_bundled_plugin/scripts/workbench_setup.py +14 -2
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
- package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
- package/_bundled_plugin/scripts/workbench_target.py +594 -136
- package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
- package/_bundled_plugin/scripts/workbench_validation.py +43 -3
- package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
- package/_bundled_plugin/shared/workbench-migrations.json +100 -0
- package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
- package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
- package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
- package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
- package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
- package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
- package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
- package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
- package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
- package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
- package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
- package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
- package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
- package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
- package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
- package/bin/codex-security.mjs +2 -2
- package/dist/api.d.ts +45 -5
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +1192 -427
- 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 +37 -18
- 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/bedrock-oss-pricing.d.ts +6 -0
- package/dist/bedrock-oss-pricing.d.ts.map +1 -0
- package/dist/bedrock-oss-pricing.js +58 -0
- package/dist/bedrock-oss-pricing.js.map +1 -0
- package/dist/bedrock-pricing.d.ts +15 -0
- package/dist/bedrock-pricing.d.ts.map +1 -0
- package/dist/bedrock-pricing.js +117 -0
- package/dist/bedrock-pricing.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 +24 -22
- package/dist/blackduck-findings.js.map +1 -1
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +4 -4
- package/dist/bulk-scan-discovery.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/checkmarx-evidence.d.ts +19 -0
- package/dist/checkmarx-evidence.d.ts.map +1 -0
- package/dist/checkmarx-evidence.js +36 -0
- package/dist/checkmarx-evidence.js.map +1 -0
- package/dist/checkmarx-findings.d.ts +4 -0
- package/dist/checkmarx-findings.d.ts.map +1 -0
- package/dist/checkmarx-findings.js +27 -0
- package/dist/checkmarx-findings.js.map +1 -0
- package/dist/checkmarx-one.d.ts +4 -0
- package/dist/checkmarx-one.d.ts.map +1 -0
- package/dist/checkmarx-one.js +53 -0
- package/dist/checkmarx-one.js.map +1 -0
- package/dist/checkmarx-repository.d.ts +12 -0
- package/dist/checkmarx-repository.d.ts.map +1 -0
- package/dist/checkmarx-repository.js +181 -0
- package/dist/checkmarx-repository.js.map +1 -0
- package/dist/checkmarx-xml.d.ts +12 -0
- package/dist/checkmarx-xml.d.ts.map +1 -0
- package/dist/checkmarx-xml.js +196 -0
- package/dist/checkmarx-xml.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-records.d.ts +1 -9
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +3 -13
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +11 -10
- 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 +16 -8
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +3382 -2017
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +35 -33
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codex-sdk-environment.d.ts +6 -0
- package/dist/codex-sdk-environment.d.ts.map +1 -1
- package/dist/codex-sdk-environment.js +19 -0
- package/dist/codex-sdk-environment.js.map +1 -1
- package/dist/command-words.d.ts +3 -0
- package/dist/command-words.d.ts.map +1 -0
- package/dist/command-words.js +46 -0
- package/dist/command-words.js.map +1 -0
- package/dist/component-scan.d.ts +19 -4
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +67 -9
- 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 +130 -67
- package/dist/config.js.map +1 -1
- package/dist/continuum-findings.d.ts +1 -1
- package/dist/continuum-findings.d.ts.map +1 -1
- package/dist/continuum-findings.js +149 -19
- package/dist/continuum-findings.js.map +1 -1
- package/dist/contract-values.d.ts +2 -0
- package/dist/contract-values.d.ts.map +1 -1
- package/dist/contract-values.js +12 -9
- package/dist/contract-values.js.map +1 -1
- package/dist/cost-model.d.ts +13 -1
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +66 -112
- package/dist/cost-model.js.map +1 -1
- package/dist/cost.d.ts +42 -3
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +484 -149
- package/dist/cost.js.map +1 -1
- package/dist/custom-publish.d.ts +4 -0
- package/dist/custom-publish.d.ts.map +1 -1
- package/dist/custom-publish.js +40 -3
- package/dist/custom-publish.js.map +1 -1
- package/dist/custom-validation-prompt.d.ts +1 -1
- package/dist/custom-validation-prompt.d.ts.map +1 -1
- package/dist/custom-validation-prompt.js +29 -19
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/local.d.ts +4 -2
- package/dist/deduplication/local.d.ts.map +1 -1
- package/dist/deduplication/local.js +9 -2
- package/dist/deduplication/local.js.map +1 -1
- package/dist/deduplication/refusal.d.ts.map +1 -1
- package/dist/deduplication/refusal.js +26 -5
- package/dist/deduplication/refusal.js.map +1 -1
- package/dist/deduplication/scan.d.ts +5 -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-config.d.ts +0 -1
- package/dist/deep-config.d.ts.map +1 -1
- package/dist/deep-config.js +22 -33
- package/dist/deep-config.js.map +1 -1
- package/dist/deep-scan-defaults.d.ts +2 -0
- package/dist/deep-scan-defaults.d.ts.map +1 -1
- package/dist/deep-scan-defaults.js +28 -1
- package/dist/deep-scan-defaults.js.map +1 -1
- package/dist/deep-scan.d.ts +2 -0
- package/dist/deep-scan.d.ts.map +1 -1
- package/dist/deep-scan.js +44 -19
- package/dist/deep-scan.js.map +1 -1
- package/dist/default-severity-rubric.d.ts +1 -1
- package/dist/default-severity-rubric.d.ts.map +1 -1
- package/dist/default-severity-rubric.js +1 -1
- package/dist/default-severity-rubric.js.map +1 -1
- package/dist/endor-findings.d.ts +3 -1
- package/dist/endor-findings.d.ts.map +1 -1
- package/dist/endor-findings.js +86 -45
- package/dist/endor-findings.js.map +1 -1
- package/dist/errors.d.ts +4 -2
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +15 -4
- 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 +5 -3
- package/dist/external-findings-import.d.ts.map +1 -1
- package/dist/external-findings-import.js +19 -7
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts +69 -5
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +537 -108
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +13 -6
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +895 -1142
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +21 -2
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +130 -68
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +15 -3
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js +54 -2
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +8 -12
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +51 -184
- 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/feedback.d.ts.map +1 -1
- package/dist/feedback.js +5 -4
- package/dist/feedback.js.map +1 -1
- package/dist/finding-prompt.d.ts +5 -0
- package/dist/finding-prompt.d.ts.map +1 -0
- package/dist/finding-prompt.js +32 -0
- package/dist/finding-prompt.js.map +1 -0
- package/dist/findings-client.d.ts +1 -0
- package/dist/findings-client.d.ts.map +1 -1
- package/dist/findings-client.js +27 -3
- package/dist/findings-client.js.map +1 -1
- package/dist/github-advisories.d.ts.map +1 -1
- package/dist/github-advisories.js +0 -2
- package/dist/github-advisories.js.map +1 -1
- package/dist/github-dependabot-findings.d.ts.map +1 -1
- package/dist/github-dependabot-findings.js +18 -8
- package/dist/github-dependabot-findings.js.map +1 -1
- package/dist/github-findings.d.ts +4 -1
- package/dist/github-findings.d.ts.map +1 -1
- package/dist/github-findings.js +73 -316
- package/dist/github-findings.js.map +1 -1
- package/dist/hosted-git-remotes.d.ts +5 -0
- package/dist/hosted-git-remotes.d.ts.map +1 -0
- package/dist/hosted-git-remotes.js +285 -0
- package/dist/hosted-git-remotes.js.map +1 -0
- package/dist/hosted-git-repository.d.ts +28 -0
- package/dist/hosted-git-repository.d.ts.map +1 -0
- package/dist/hosted-git-repository.js +222 -0
- package/dist/hosted-git-repository.js.map +1 -0
- 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/hosted-scan-protocol.js +2 -2
- package/dist/hosted-scan-protocol.js.map +1 -1
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +16 -11
- package/dist/hosted-scan.js.map +1 -1
- package/dist/hosted-scanner-http.d.ts +21 -0
- package/dist/hosted-scanner-http.d.ts.map +1 -0
- package/dist/hosted-scanner-http.js +204 -0
- package/dist/hosted-scanner-http.js.map +1 -0
- package/dist/import-scan.d.ts.map +1 -1
- package/dist/import-scan.js +3 -0
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +21 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +12 -3
- package/dist/index.js.map +1 -1
- package/dist/inspector-findings.d.ts.map +1 -1
- package/dist/inspector-findings.js +52 -86
- 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 +102 -32
- 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 -5
- package/dist/local-git-metadata.js.map +1 -1
- package/dist/multiscan.d.ts +10 -4
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +217 -102
- package/dist/multiscan.js.map +1 -1
- package/dist/native-json-findings.d.ts +2 -1
- package/dist/native-json-findings.d.ts.map +1 -1
- package/dist/native-json-findings.js +12 -2
- package/dist/native-json-findings.js.map +1 -1
- package/dist/opengrep-findings.d.ts +5 -2
- package/dist/opengrep-findings.d.ts.map +1 -1
- package/dist/opengrep-findings.js +54 -33
- package/dist/opengrep-findings.js.map +1 -1
- package/dist/operation-telemetry.d.ts +104 -0
- package/dist/operation-telemetry.d.ts.map +1 -0
- package/dist/operation-telemetry.js +293 -0
- package/dist/operation-telemetry.js.map +1 -0
- package/dist/plugin-python-probe.d.ts +4 -0
- package/dist/plugin-python-probe.d.ts.map +1 -0
- package/dist/plugin-python-probe.js +10 -0
- package/dist/plugin-python-probe.js.map +1 -0
- package/dist/private-finding-import.d.ts +99 -9
- package/dist/private-finding-import.d.ts.map +1 -1
- package/dist/private-finding-import.js +116 -152
- package/dist/private-finding-import.js.map +1 -1
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +53 -13
- package/dist/project-config.js.map +1 -1
- package/dist/prompt-files.d.ts +7 -2
- package/dist/prompt-files.d.ts.map +1 -1
- package/dist/prompt-files.js +42 -20
- package/dist/prompt-files.js.map +1 -1
- package/dist/provider-profile.d.ts +1 -1
- package/dist/provider-profile.d.ts.map +1 -1
- package/dist/provider-profile.js +12 -10
- package/dist/provider-profile.js.map +1 -1
- package/dist/publication-telemetry.d.ts +45 -0
- package/dist/publication-telemetry.d.ts.map +1 -0
- package/dist/publication-telemetry.js +50 -0
- package/dist/publication-telemetry.js.map +1 -0
- package/dist/publication.d.ts +1 -1
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts +4 -0
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +42 -2
- package/dist/publish.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 +1 -4
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +6 -8
- package/dist/remediation.js.map +1 -1
- package/dist/request-metadata.d.ts +3 -0
- package/dist/request-metadata.d.ts.map +1 -1
- package/dist/request-metadata.js +9 -0
- package/dist/request-metadata.js.map +1 -1
- package/dist/result.d.ts +4 -0
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +1 -1
- package/dist/result.js.map +1 -1
- package/dist/retry-windows-rename.d.ts +8 -0
- package/dist/retry-windows-rename.d.ts.map +1 -0
- package/dist/retry-windows-rename.js +24 -0
- package/dist/retry-windows-rename.js.map +1 -0
- package/dist/runtime.d.ts +54 -6
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +1084 -256
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan-bootstrap.d.ts +7 -1
- package/dist/saved-scan-bootstrap.d.ts.map +1 -1
- package/dist/saved-scan-bootstrap.js +269 -114
- package/dist/saved-scan-bootstrap.js.map +1 -1
- package/dist/scan-activity.d.ts.map +1 -1
- package/dist/scan-activity.js +141 -56
- package/dist/scan-activity.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 +10 -5
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +66 -17
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +7 -6
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +92 -43
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-executor.d.ts +10 -1
- package/dist/scan-executor.d.ts.map +1 -1
- package/dist/scan-executor.js +24 -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 +34 -28
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-logs.d.ts +12 -0
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +131 -78
- package/dist/scan-logs.js.map +1 -1
- package/dist/scan-measurement.d.ts +26 -0
- package/dist/scan-measurement.d.ts.map +1 -0
- package/dist/scan-measurement.js +77 -0
- package/dist/scan-measurement.js.map +1 -0
- package/dist/scan-progress.d.ts +1 -0
- package/dist/scan-progress.d.ts.map +1 -1
- package/dist/scan-progress.js +3 -0
- package/dist/scan-progress.js.map +1 -1
- package/dist/scan-sessions.d.ts.map +1 -1
- package/dist/scan-sessions.js +4 -1
- package/dist/scan-sessions.js.map +1 -1
- package/dist/scan-settings.d.ts +1 -1
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +1 -24
- package/dist/scan-settings.js.map +1 -1
- package/dist/scanner-import.d.ts +25 -13
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +216 -97
- package/dist/scanner-import.js.map +1 -1
- package/dist/scanner-repository-url.d.ts +4 -1
- package/dist/scanner-repository-url.d.ts.map +1 -1
- package/dist/scanner-repository-url.js +10 -6
- package/dist/scanner-repository-url.js.map +1 -1
- package/dist/security-policy.d.ts +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 +6 -3
- package/dist/semgrep-findings.d.ts.map +1 -1
- package/dist/semgrep-findings.js +72 -42
- package/dist/semgrep-findings.js.map +1 -1
- package/dist/semgrep-guardian-findings.d.ts +38 -0
- package/dist/semgrep-guardian-findings.d.ts.map +1 -0
- package/dist/semgrep-guardian-findings.js +165 -0
- package/dist/semgrep-guardian-findings.js.map +1 -0
- package/dist/semgrep-platform-collector.d.ts +26 -0
- package/dist/semgrep-platform-collector.d.ts.map +1 -0
- package/dist/semgrep-platform-collector.js +108 -0
- package/dist/semgrep-platform-collector.js.map +1 -0
- package/dist/semgrep-platform-findings.d.ts +157 -6
- package/dist/semgrep-platform-findings.d.ts.map +1 -1
- package/dist/semgrep-platform-findings.js +766 -103
- package/dist/semgrep-platform-findings.js.map +1 -1
- package/dist/server/api.d.ts +1 -1
- package/dist/server/api.d.ts.map +1 -1
- package/dist/server/api.js.map +1 -1
- package/dist/server/embedding-tokenizer.cdx.json +33 -0
- package/dist/server/embedding-tokenizer.d.ts +2 -0
- package/dist/server/embedding-tokenizer.d.ts.map +1 -0
- package/dist/server/embedding-tokenizer.js +322 -0
- package/dist/server/embedding-tokenizer.js.map +6 -0
- package/dist/server/embeddings.d.ts +16 -2
- package/dist/server/embeddings.d.ts.map +1 -1
- package/dist/server/embeddings.js +35 -5
- package/dist/server/embeddings.js.map +1 -1
- package/dist/session-lines.d.ts +5 -0
- package/dist/session-lines.d.ts.map +1 -0
- package/dist/session-lines.js +60 -0
- package/dist/session-lines.js.map +1 -0
- package/dist/severity-review.d.ts +3 -1
- package/dist/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +3 -2
- package/dist/severity-review.js.map +1 -1
- package/dist/skill-authentication.d.ts +1 -0
- package/dist/skill-authentication.d.ts.map +1 -1
- package/dist/skill-authentication.js +1 -0
- package/dist/skill-authentication.js.map +1 -1
- package/dist/snyk-findings.d.ts +9 -2
- package/dist/snyk-findings.d.ts.map +1 -1
- package/dist/snyk-findings.js +90 -70
- package/dist/snyk-findings.js.map +1 -1
- package/dist/snyk-rest-findings.d.ts +59 -0
- package/dist/snyk-rest-findings.d.ts.map +1 -0
- package/dist/snyk-rest-findings.js +879 -0
- package/dist/snyk-rest-findings.js.map +1 -0
- package/dist/snyk-token-origin.d.ts +4 -0
- package/dist/snyk-token-origin.d.ts.map +1 -0
- package/dist/snyk-token-origin.js +82 -0
- package/dist/snyk-token-origin.js.map +1 -0
- package/dist/sonar-collector.d.ts.map +1 -1
- package/dist/sonar-collector.js +0 -3
- package/dist/sonar-collector.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 +30 -34
- package/dist/sonar-import.js.map +1 -1
- package/dist/stored-finding-projection.d.ts +6 -0
- package/dist/stored-finding-projection.d.ts.map +1 -0
- package/dist/stored-finding-projection.js +104 -0
- package/dist/stored-finding-projection.js.map +1 -0
- package/dist/stored-findings-publication.d.ts +23 -0
- package/dist/stored-findings-publication.d.ts.map +1 -0
- package/dist/stored-findings-publication.js +169 -0
- package/dist/stored-findings-publication.js.map +1 -0
- package/dist/target-drift.d.ts +9 -0
- package/dist/target-drift.d.ts.map +1 -0
- package/dist/target-drift.js +27 -0
- package/dist/target-drift.js.map +1 -0
- package/dist/targets.d.ts +8 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +131 -42
- package/dist/targets.js.map +1 -1
- package/dist/tenable-findings.d.ts +6 -0
- package/dist/tenable-findings.d.ts.map +1 -0
- package/dist/tenable-findings.js +122 -0
- package/dist/tenable-findings.js.map +1 -0
- package/dist/terminal-stream.d.ts +13 -0
- package/dist/terminal-stream.d.ts.map +1 -0
- package/dist/terminal-stream.js +35 -0
- package/dist/terminal-stream.js.map +1 -0
- package/dist/trivy-findings.d.ts +19 -0
- package/dist/trivy-findings.d.ts.map +1 -0
- package/dist/trivy-findings.js +424 -0
- package/dist/trivy-findings.js.map +1 -0
- package/dist/trivy-import.d.ts +19 -0
- package/dist/trivy-import.d.ts.map +1 -0
- package/dist/trivy-import.js +151 -0
- package/dist/trivy-import.js.map +1 -0
- package/dist/trusted-executable.d.ts +6 -0
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +140 -37
- package/dist/trusted-executable.js.map +1 -1
- package/dist/validation-records.js +1 -1
- package/dist/validation-records.js.map +1 -1
- package/dist/veracode-findings.d.ts +1 -1
- package/dist/veracode-findings.d.ts.map +1 -1
- package/dist/veracode-findings.js +19 -6
- 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/vertex-pricing.d.ts +8 -0
- package/dist/vertex-pricing.d.ts.map +1 -0
- package/dist/vertex-pricing.js +20 -0
- package/dist/vertex-pricing.js.map +1 -0
- package/dist/windows-path.d.ts +1 -0
- package/dist/windows-path.d.ts.map +1 -1
- package/dist/windows-path.js +26 -1
- package/dist/windows-path.js.map +1 -1
- package/dist/wiz-findings.d.ts +6 -2
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +65 -89
- package/dist/wiz-findings.js.map +1 -1
- package/docs/classify-severity-records.md +27 -12
- package/docs/cli.md +853 -639
- package/docs/dedupe-records.md +44 -24
- package/docs/findings-service.md +84 -44
- package/docs/hosted-remediation.md +27 -11
- package/docs/hosted-scans.md +50 -42
- package/docs/sdk.md +903 -0
- package/docs/telemetry.md +236 -0
- package/docs/validate-records.md +78 -44
- package/package.json +23 -16
- package/schemas/external-findings.schema.json +4 -1
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
- package/dist/external-imports-feature.d.ts +0 -6
- package/dist/external-imports-feature.d.ts.map +0 -1
- package/dist/external-imports-feature.js +0 -51
- package/dist/external-imports-feature.js.map +0 -1
- package/dist/finding-normalization.d.ts +0 -5
- package/dist/finding-normalization.d.ts.map +0 -1
- package/dist/finding-normalization.js +0 -155
- package/dist/finding-normalization.js.map +0 -1
- package/dist/reader-selection.d.ts +0 -13
- package/dist/reader-selection.d.ts.map +0 -1
- package/dist/reader-selection.js +0 -81
- package/dist/reader-selection.js.map +0 -1
package/docs/cli.md
CHANGED
|
@@ -14,14 +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.
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
findings file in local scan history, use
|
|
22
|
-
[`scan import`](#import-findings-as-a-saved-scan). These are separate workflows:
|
|
23
|
-
GitHub import returns upstream alerts for validation; file import saves findings
|
|
24
|
-
without running security analysis.
|
|
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.
|
|
25
21
|
|
|
26
22
|
## Find a workflow
|
|
27
23
|
|
|
@@ -31,10 +27,8 @@ without running security analysis.
|
|
|
31
27
|
[save project settings](#project-files).
|
|
32
28
|
- [Review one system across repositories](#review-one-system-across-repositories)
|
|
33
29
|
or [run independent bulk scans](#bulk-scans).
|
|
34
|
-
- [
|
|
35
|
-
|
|
36
|
-
[save findings as a scan](#import-findings-as-a-saved-scan), or
|
|
37
|
-
[retrieve GitHub alerts](#import-alerts-from-the-cli).
|
|
30
|
+
- [Choose an import command](#import-vendor-findings-locally) to save a scan,
|
|
31
|
+
collect upstream alerts, or store vendor evidence locally or in Cloud.
|
|
38
32
|
- [Inspect saved scans and rerun them](#scan-history-and-reruns),
|
|
39
33
|
[classify severity](#classify-finding-severity), or
|
|
40
34
|
[suggest owners](#suggest-finding-owners).
|
|
@@ -46,6 +40,26 @@ without running security analysis.
|
|
|
46
40
|
- [Use a hosted executor](#hosted-standard-scan) or
|
|
47
41
|
[run bulk scans in containers](#containerized-bulk-scans).
|
|
48
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
|
+
|
|
49
63
|
## Authentication
|
|
50
64
|
|
|
51
65
|
Sign in with ChatGPT, or supply an API key for CI:
|
|
@@ -87,7 +101,9 @@ your local browser. Keep SSH connected until login finishes.
|
|
|
87
101
|
### OpenAI credentials
|
|
88
102
|
|
|
89
103
|
Interactive scans ask which credentials to use when both ChatGPT and an
|
|
90
|
-
environment API key are available.
|
|
104
|
+
environment API key are available. A dedicated sign-in takes precedence. After
|
|
105
|
+
`codex-security logout`, the prompt skips the ambient sign-in until you log in
|
|
106
|
+
again. Noninteractive commands prefer
|
|
91
107
|
`OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
|
|
92
108
|
with `--auth`:
|
|
93
109
|
|
|
@@ -104,12 +120,25 @@ the stored login. Patch follow-up assessments and `scan --patch` retain the
|
|
|
104
120
|
chosen authentication. Environment keys do not replace the saved login.
|
|
105
121
|
The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
|
|
106
122
|
|
|
123
|
+
For a scan using a custom native provider, `auto` and `api-key` use the
|
|
124
|
+
environment variable declared by `model_providers.<id>.env_key`, including
|
|
125
|
+
when a Codex file profile selects that provider. Set that variable before
|
|
126
|
+
starting the scan. To use `--auth chatgpt`, select a provider configured for
|
|
127
|
+
account authentication. A custom provider that requires its own key cannot
|
|
128
|
+
honor that combination.
|
|
129
|
+
|
|
107
130
|
Stored OpenAI credentials live in
|
|
108
131
|
`$CODEX_SECURITY_STATE_DIR/codex-home`, or
|
|
109
132
|
`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
|
|
110
133
|
outside the target and every enclosing Git worktree. It also serves providers
|
|
111
134
|
with `requires_openai_auth = true`.
|
|
112
135
|
|
|
136
|
+
If you manually hard-linked the two homes’ `auth.json` files, keep both homes
|
|
137
|
+
accessible when running `codex-security logout`. When the CLI verifies the
|
|
138
|
+
two hard links, it removes the private link before invoking native logout.
|
|
139
|
+
If the ambient home is unavailable, the configured credential store handles
|
|
140
|
+
logout normally.
|
|
141
|
+
|
|
113
142
|
Codex carries credential-storage, forced-login, and workspace settings from the
|
|
114
143
|
ambient configuration into this home. Managed-device policies still apply;
|
|
115
144
|
workspace-managed policies may require ChatGPT credentials even with an API key.
|
|
@@ -123,8 +152,21 @@ after logout completes.
|
|
|
123
152
|
Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
|
|
124
153
|
`HOME` or `USERPROFILE` environment setting.
|
|
125
154
|
|
|
126
|
-
If
|
|
127
|
-
|
|
155
|
+
If you use file-based ChatGPT credentials with both Codex and Codex Security,
|
|
156
|
+
run `codex-security login` before your first scan or status check to give Codex
|
|
157
|
+
Security its own session. An imported sign-in shares a single-use refresh token.
|
|
158
|
+
When either client renews it, the other client's next refresh can fail even
|
|
159
|
+
while its login status reports that it is signed in.
|
|
160
|
+
|
|
161
|
+
If Codex Security reports that the refresh token was already used, run
|
|
162
|
+
`codex-security logout`, then `codex-security login`. If your Codex CLI or app
|
|
163
|
+
reports that error, sign out and sign back in there.
|
|
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
|
+
|
|
167
|
+
For other refresh errors, check `codex-security login status`. Retry if the
|
|
168
|
+
sign-in recently changed. Otherwise run `codex-security logout`, then
|
|
169
|
+
`codex-security login`.
|
|
128
170
|
Some cybersecurity requests and protected findings require
|
|
129
171
|
[Trusted Access for Cyber](https://chatgpt.com/cyber).
|
|
130
172
|
|
|
@@ -142,7 +184,7 @@ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
|
|
|
142
184
|
In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
|
|
143
185
|
to explicitly turn it off.
|
|
144
186
|
The setting carries through saved scan recipes, resumed scans, Deep Scan
|
|
145
|
-
discovery
|
|
187
|
+
discovery workers, and `scan --patch`. Standalone `validate`,
|
|
146
188
|
`patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
|
|
147
189
|
Threads created by these commands retain the setting when resumed in Codex.
|
|
148
190
|
Scans use isolated configuration, so set it on the CLI, SDK client, or project
|
|
@@ -152,8 +194,7 @@ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
|
|
|
152
194
|
an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
|
|
153
195
|
or set top-level `daybreak = true` in the configuration loaded by the runner.
|
|
154
196
|
Deep Scan inherits the active turn's effective access program from its saved
|
|
155
|
-
Codex session, including an explicit Standard selection. Discovery
|
|
156
|
-
workers retain that selection when resumed. If the host does not supply a
|
|
197
|
+
Codex session, including an explicit Standard selection. Discovery workers retain that selection when resumed. If the host does not supply a
|
|
157
198
|
persisted turn context, workers use their runner configuration; CLI and SDK scans
|
|
158
199
|
use the explicit scan settings above.
|
|
159
200
|
|
|
@@ -181,7 +222,7 @@ codex-security scan /path/to/repository \
|
|
|
181
222
|
In the SDK, select your model through `codexOverrides.model` and pass
|
|
182
223
|
`auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
|
|
183
224
|
Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
|
|
184
|
-
The selection reaches discovery
|
|
225
|
+
The selection reaches discovery workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
|
|
185
226
|
for configuration precedence and the API-key feature setting.
|
|
186
227
|
|
|
187
228
|
`access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
|
|
@@ -236,6 +277,15 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
|
|
|
236
277
|
codex-security scan . --provider cheaperinference --model gpt-5.4
|
|
237
278
|
```
|
|
238
279
|
|
|
280
|
+
### Hugging Face compatibility
|
|
281
|
+
|
|
282
|
+
In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
|
|
283
|
+
`namespace` and could request `web_search`. Hugging Face's published Responses
|
|
284
|
+
implementation accepts `function` and remote `mcp` tool declarations. A named
|
|
285
|
+
Hugging Face scan provider is deferred until the scanner and router can exchange
|
|
286
|
+
the tools a complete scan requires. [Hugging Face's implementation notes](https://huggingface.co/docs/inference-providers/en/guides/gpt-oss#responses-api)
|
|
287
|
+
and [request schema](https://github.com/huggingface/responses.js/blob/0e3e84c469a9f59ad16e2eb3a0d6f1c4de637a7b/src/schemas.ts#L219-L232).
|
|
288
|
+
|
|
239
289
|
### Amazon Bedrock
|
|
240
290
|
|
|
241
291
|
Use AWS credentials and a region with access to the exact Bedrock model ID:
|
|
@@ -255,6 +305,45 @@ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/
|
|
|
255
305
|
for credential alternatives, restricted-model access, cost estimates, and
|
|
256
306
|
reasoning-summary configuration.
|
|
257
307
|
|
|
308
|
+
### Google Cloud Vertex AI cost estimates
|
|
309
|
+
|
|
310
|
+
The SDK estimates Standard online inference costs for OpenAI models served by
|
|
311
|
+
Google Cloud's Model as a Service (MaaS). Rates are in USD per million tokens.
|
|
312
|
+
[Google Cloud partner model pricing](https://cloud.google.com/model-garden/partner-models/pricing)
|
|
313
|
+
and [OpenAI model locations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/maas/openai).
|
|
314
|
+
|
|
315
|
+
| Managed model ID | Location | Input | Cached input | Output |
|
|
316
|
+
| -------------------------- | ----------------------- | ----: | -----------: | -----: |
|
|
317
|
+
| `openai/gpt-oss-120b-maas` | `global` | $0.09 | $0.09 | $0.36 |
|
|
318
|
+
| `openai/gpt-oss-20b-maas` | `us-central1` (retired) | $0.07 | $0.007 | $0.25 |
|
|
319
|
+
|
|
320
|
+
Google publishes a cache-hit discount only for 20B, so the estimator uses the
|
|
321
|
+
ordinary input rate for cached 120B tokens. Google retired the managed 20B
|
|
322
|
+
endpoint on October 21, 2026. The SDK retains its rates for historical usage.
|
|
323
|
+
[Google Cloud retirement schedule](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/open-models).
|
|
324
|
+
|
|
325
|
+
To estimate recorded usage locally, pass the managed model ID and the GCP
|
|
326
|
+
provider to `estimateScanCost`.
|
|
327
|
+
|
|
328
|
+
```ts
|
|
329
|
+
import { estimateScanCost } from "@openai/codex-security";
|
|
330
|
+
|
|
331
|
+
const cost = estimateScanCost(
|
|
332
|
+
"openai/gpt-oss-120b-maas",
|
|
333
|
+
{ input_tokens: 1_000_000, output_tokens: 500_000 },
|
|
334
|
+
{ provider: "gcp" },
|
|
335
|
+
);
|
|
336
|
+
// cost?.estimatedUsd is 0.27.
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
Google documents the managed GPT OSS IDs on its shared chat-completions API.
|
|
340
|
+
The bundled Codex `gcp` provider uses Google's Responses API with a separate
|
|
341
|
+
frontier model catalog. Google has published no Standard token rates for that
|
|
342
|
+
catalog, including GPT-6 Astra, GPT-6.1 Sol, GPT-6.1 Terra, and GPT-6 Luna.
|
|
343
|
+
Those scans record token usage and require a published price to use
|
|
344
|
+
`--max-cost`. Self-deployed Model Garden endpoints incur infrastructure charges.
|
|
345
|
+
[Google Cloud's preview announcement](https://cloud.google.com/blog/products/ai-machine-learning/google-cloud-brings-openai-models-to-customers).
|
|
346
|
+
|
|
258
347
|
## Generate a security policy
|
|
259
348
|
|
|
260
349
|
Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
|
|
@@ -320,11 +409,11 @@ Add context with `--knowledge-base`:
|
|
|
320
409
|
codex-security policy . --knowledge-base architecture.md
|
|
321
410
|
```
|
|
322
411
|
|
|
323
|
-
| Invocation
|
|
324
|
-
|
|
|
325
|
-
| `policy . --
|
|
326
|
-
| `policy . --format md`
|
|
327
|
-
| `policy . --dry-run --json`
|
|
412
|
+
| Invocation | Result |
|
|
413
|
+
| --------------------------- | -------------------------------------------------------- |
|
|
414
|
+
| `policy . --json` | Generate without prompts; return paths and review notes. |
|
|
415
|
+
| `policy . --format md` | Generate and write the draft to stdout. |
|
|
416
|
+
| `policy . --dry-run --json` | Check local inputs without calling Codex. |
|
|
328
417
|
|
|
329
418
|
`--headless` leaves unanswered questions in the review notes. By default, files
|
|
330
419
|
go in the Codex Security state directory. To choose a location, use an empty
|
|
@@ -430,6 +519,14 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
|
|
|
430
519
|
requested work separately from optional `coverage.openQuestions` follow-up.
|
|
431
520
|
Human-readable output quotes ambiguous paths, while JSON retains their original strings.
|
|
432
521
|
|
|
522
|
+
A dry run reports `stateDirectory`, the root for saved scan state. It checks the
|
|
523
|
+
storage location without creating a scan directory. Pass boolean scan options
|
|
524
|
+
as bare flags or use lowercase `=true` or `=false`.
|
|
525
|
+
|
|
526
|
+
When a cost limit is configured, `scan --dry-run` shows the resolved
|
|
527
|
+
`maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
|
|
528
|
+
against the limit and why in-flight requests can exceed it.
|
|
529
|
+
|
|
433
530
|
Whole-codebase and path scans also accept ordinary directories, including SVN
|
|
434
531
|
working copies. Their source inventories exclude `.git` and `.svn` metadata.
|
|
435
532
|
|
|
@@ -441,7 +538,8 @@ be clean and at the commit recorded by the parent.
|
|
|
441
538
|
Committed-diff scans require a clean, full checkout at the requested head
|
|
442
539
|
revision, including when using `--validate`. A different checkout revision or
|
|
443
540
|
local changes are rejected before scanning; check out the requested head and
|
|
444
|
-
commit or stash local changes before retrying.
|
|
541
|
+
commit or stash local changes before retrying. The check also verifies tracked
|
|
542
|
+
files marked `assume-unchanged` and preserves their Git index flags.
|
|
445
543
|
|
|
446
544
|
`--owner-suggestions` writes optional `owner-suggestions.json` after a completed
|
|
447
545
|
committed Git scan, using the same checkout, model, and reasoning effort. Owner
|
|
@@ -456,14 +554,25 @@ Use the separate `suggest-owners` command for explicit owner-only jobs.
|
|
|
456
554
|
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
457
555
|
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
458
556
|
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
459
|
-
with every repository.
|
|
557
|
+
with every repository. Select external documents directly. Links in a checkout
|
|
558
|
+
must stay inside it. For bulk scans with bare or separate Git storage, use
|
|
559
|
+
canonical paths for shared documents and prompt files.
|
|
460
560
|
|
|
461
561
|
Use `--output-dir DIR` to choose where a scan saves its results. The directory
|
|
462
562
|
must be empty and outside the scanned directory and enclosing Git worktree.
|
|
463
|
-
Existing directories keep their permissions
|
|
464
|
-
private to you by default.
|
|
465
|
-
|
|
466
|
-
|
|
563
|
+
Existing directories keep their permissions. Newly created directories are
|
|
564
|
+
private to you by default. On Windows, the directory and its parents must be
|
|
565
|
+
owned by your account, Administrators, SYSTEM, or TrustedInstaller. Choose a
|
|
566
|
+
path where another user cannot replace the output directory or one of its
|
|
567
|
+
parents. A parent can allow other users to read it or create sibling directories.
|
|
568
|
+
For an empty write destination, grant content-writing permissions to children
|
|
569
|
+
through inheritance. Other users must not have permission to set reparse data
|
|
570
|
+
on the destination directory itself.
|
|
571
|
+
`--archive-existing` moves earlier output to a sibling directory with a unique
|
|
572
|
+
suffix, such as `results.previous-ab12cd34` for an output directory named
|
|
573
|
+
`results`. If adding the suffix exceeds the filesystem's filename limit on POSIX,
|
|
574
|
+
the archive uses a short sibling name starting with `.previous-` and a hash of the
|
|
575
|
+
original filename. Use `--dry-run` to preview the move.
|
|
467
576
|
|
|
468
577
|
Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
|
|
469
578
|
optional export fails, the scan can still complete. Use the
|
|
@@ -503,7 +612,9 @@ or JSONL output produce:
|
|
|
503
612
|
{ "status": "failed", "code": "SCAN_FAILED", "message": "..." }
|
|
504
613
|
```
|
|
505
614
|
|
|
506
|
-
With `--full-output`, the error
|
|
615
|
+
With `--full-output`, JSON and JSONL failures put the error under `error` in an
|
|
616
|
+
`ok: false` envelope. YAML and TOON use the same failed envelope when retained
|
|
617
|
+
sealed scan results are available (including TOON selected by default).
|
|
507
618
|
If the scan target changed, the error explains that the results no longer
|
|
508
619
|
represent the current checkout. Retained sealed results remain available under
|
|
509
620
|
`data`, including their manifest, findings, review summary, scan directory, and report
|
|
@@ -515,19 +626,25 @@ selecting an unavailable field can return `null` or omit `data`.
|
|
|
515
626
|
Saved-scan setup failures use the same output shape with
|
|
516
627
|
`SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
|
|
517
628
|
available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
|
|
518
|
-
scan uses `SCAN_IMPORT_FAILED` if the import fails.
|
|
519
|
-
stderr
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
629
|
+
scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
|
|
630
|
+
on stderr without `--full-output`, or when retained results are unavailable.
|
|
631
|
+
|
|
632
|
+
Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
|
|
633
|
+
envelope with `error.code` and `error.message`. Command schema validation errors
|
|
634
|
+
with JSON or JSONL retain their field details and name missing or invalid
|
|
635
|
+
options by their CLI flags. Diagnostics stay on stderr.
|
|
636
|
+
`scan --schema --format json` describes optional caller inputs before defaults
|
|
637
|
+
and the fields returned by preflight, completed scans, and execution failures,
|
|
638
|
+
including sealed results recovered after an interruption.
|
|
523
639
|
See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
524
640
|
|
|
525
641
|
### Follow-up finding validation
|
|
526
642
|
|
|
527
643
|
Scans already validate findings against local source. Add `--validate` to run
|
|
528
644
|
the existing standalone validation workflow for each reported finding after
|
|
529
|
-
the scan, using the same selected Cyber access program. Validation
|
|
530
|
-
|
|
645
|
+
the scan, using the same selected Cyber access program. Validation sends each
|
|
646
|
+
finding to the configured model provider. Its review tools have read-only
|
|
647
|
+
filesystem access, with network access and web search disabled. Each assessment uses a
|
|
531
648
|
separate evidence directory; the combined report is saved as
|
|
532
649
|
`<scan-dir>/validation.md`, or a uniquely suffixed report
|
|
533
650
|
if that path already exists. Each completed assessment is saved immediately;
|
|
@@ -571,26 +688,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
|
|
|
571
688
|
fail after registration but before writing its artifacts; investigate those
|
|
572
689
|
failures through its history record and any available logs. When artifacts were
|
|
573
690
|
retained, use the saved results directory returned by `scans show` to inspect
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
| File | What to check
|
|
577
|
-
| -------------------- |
|
|
578
|
-
| `scan-manifest.json` | `scan.status
|
|
579
|
-
| `
|
|
580
|
-
| `
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
`
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
proving that each file was reviewed. An absent path in a surface summary does not
|
|
590
|
-
establish whether it was read, and the scan ID cannot reconstruct evidence that
|
|
591
|
-
was never saved.
|
|
592
|
-
Session logs can help explain failures and tool activity, but do not prove
|
|
593
|
-
complete review either.
|
|
691
|
+
the saved files:
|
|
692
|
+
|
|
693
|
+
| File | What to check |
|
|
694
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
695
|
+
| `scan-manifest.json` | `scan.status` and `scan.target` identify the outcome and snapshot. `scan.scope` lists requested inclusions and exclusions. `scan.review.excludedPaths` lists additional excluded paths in current scans. |
|
|
696
|
+
| `findings.json` | Reported findings, source locations and supporting evidence. |
|
|
697
|
+
| `report.md` | A readable summary of the scope and findings. |
|
|
698
|
+
|
|
699
|
+
When a checkpoint is retained, `checkpoint-head.json` identifies the file in
|
|
700
|
+
`checkpoints/`. In a retained draft or checkpoint, `reviewState.deferred` lists
|
|
701
|
+
unfinished work and `reviewState.openQuestions` lists follow-up questions.
|
|
702
|
+
Older manifests with `scan.coverageRef` point to a separate `coverage.json`
|
|
703
|
+
with reviewed surfaces, explicit exclusions and deferred work. A saved source
|
|
704
|
+
inventory identifies inputs. Neither that inventory nor session logs establish
|
|
705
|
+
which files the scan reviewed in full.
|
|
594
706
|
|
|
595
707
|
For a local plugin scan, ask Codex to open the saved scan and explain its scope,
|
|
596
708
|
exclusions, deferred work, and follow-up questions. CLI history can also locate
|
|
@@ -612,8 +724,8 @@ Choose the next step from the recorded reason:
|
|
|
612
724
|
start a new scan with the intended scope, including for plugin scans without
|
|
613
725
|
a recipe. Retained findings can still be reviewed, but absence of findings
|
|
614
726
|
from a stopped run is inconclusive.
|
|
615
|
-
- **A Deep Scan was interrupted and is still recorded as `running`:** it may
|
|
616
|
-
support [resume](#resuming-an-interrupted-
|
|
727
|
+
- **A Standard or Deep Scan was interrupted and is still recorded as `running`:** it may
|
|
728
|
+
support [resume](#resuming-an-interrupted-scan) with the original checkout,
|
|
617
729
|
artifacts, and session. Completed, failed, and canceled scans cannot resume.
|
|
618
730
|
|
|
619
731
|
For example, after identifying an omitted API directory:
|
|
@@ -634,12 +746,13 @@ completeness values to determine scan status or exit codes.
|
|
|
634
746
|
|
|
635
747
|
```bash
|
|
636
748
|
codex-security init
|
|
637
|
-
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
638
749
|
codex-security info -c codex-security.yaml --json
|
|
750
|
+
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
639
751
|
```
|
|
640
752
|
|
|
641
753
|
Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
|
|
642
|
-
|
|
754
|
+
Keep `-c` on both `info` and the scan preview to inspect the same target and
|
|
755
|
+
limits. Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
|
|
643
756
|
`scan-components`, and `info` accept project files. SDK calls and saved reruns
|
|
644
757
|
do not load them automatically.
|
|
645
758
|
|
|
@@ -657,16 +770,18 @@ from the config directory; scope paths resolve from the repository.
|
|
|
657
770
|
### Import findings as a saved scan
|
|
658
771
|
|
|
659
772
|
```bash
|
|
660
|
-
codex-security scan import
|
|
661
|
-
codex-security scan import
|
|
662
|
-
codex-security scan import
|
|
773
|
+
codex-security scan import /path/to/findings.csv
|
|
774
|
+
codex-security scan import /path/to/findings.json --json
|
|
775
|
+
codex-security scan import /path/to/report --input-format csv --dry-run
|
|
663
776
|
```
|
|
664
777
|
|
|
665
778
|
Supply exactly one input. CSV follows the
|
|
666
779
|
[findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
|
|
667
780
|
JSON accepts a complete `codex-security.findings` document or
|
|
668
|
-
`{ "findings": [...] }` matching the findings schema.
|
|
669
|
-
|
|
781
|
+
`{ "findings": [...] }` matching the findings schema. The CLI infers the format from a `.csv` or `.json` suffix.
|
|
782
|
+
Use `--input-format csv|json` to override it. Put `--json` after the filename
|
|
783
|
+
to request JSON output. Existing scripts using `--csv FILE` or `--json FILE`
|
|
784
|
+
can continue to select the input that way. The input must be a
|
|
670
785
|
regular file with no symlinks or directory junctions in its path.
|
|
671
786
|
|
|
672
787
|
Each import creates a completed scan in local history, retains the input under
|
|
@@ -693,7 +808,8 @@ runs, four with new identities, and two duplicate pairs for testing deduplicatio
|
|
|
693
808
|
Paths and snippets are fictional; repository files remain unchanged.
|
|
694
809
|
|
|
695
810
|
Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
|
|
696
|
-
archiving, and severity thresholds work normally.
|
|
811
|
+
archiving, and severity thresholds work normally. Use `scans show` to inspect a
|
|
812
|
+
mock scan. Mock scans have no Codex session logs. Reruns preserve mock mode.
|
|
697
813
|
Separate matching or deduplication commands still make their usual model calls.
|
|
698
814
|
|
|
699
815
|
Mock mode supports Standard repository, path, and diff scans. It cannot combine
|
|
@@ -746,6 +862,13 @@ codex-security scan-components . \
|
|
|
746
862
|
--output-dir /path/outside/project/results
|
|
747
863
|
```
|
|
748
864
|
|
|
865
|
+
`--plan-only` with `--component` or `--components-file` validates local paths
|
|
866
|
+
without signing in. The CLI prints a command to scan the saved plan into a fresh
|
|
867
|
+
`results` directory inside the plan directory. Running that command starts scans.
|
|
868
|
+
Run it from the original working directory to reuse relative paths. The command
|
|
869
|
+
includes the selected project configuration and scan flags. Reapply any inline
|
|
870
|
+
`--codex` overrides yourself, since these can contain credentials.
|
|
871
|
+
|
|
749
872
|
Plans use literal repository-relative paths, so `~/src` selects a directory
|
|
750
873
|
named `~` inside the repository rather than expanding the home directory.
|
|
751
874
|
Existing absolute paths inside the repository are also accepted.
|
|
@@ -772,11 +895,18 @@ individual scan folder.
|
|
|
772
895
|
Failures do not stop other components. Failed scans or
|
|
773
896
|
failed matching return `2`; severity-policy violations return `1`. Retry with
|
|
774
897
|
`--components-file retry-components.json` and a new empty output directory.
|
|
775
|
-
The retry report covers only those components.
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
898
|
+
The retry report covers only those components. Each registered component keeps its
|
|
899
|
+
scan ID in the summary, including when the scan fails.
|
|
900
|
+
|
|
901
|
+
`--max-cost` applies per component, excluding planning and matching.
|
|
902
|
+
Use `--max-total-cost USD` with explicit components to split one estimated
|
|
903
|
+
budget among them. The smaller of each component's share and its per-scan
|
|
904
|
+
limit applies. Findings stay separate because model-based matching is skipped.
|
|
905
|
+
The total limit also skips owner suggestions, including when enabled in project configuration.
|
|
906
|
+
Automatic planning and post-scan prompts must run separately.
|
|
907
|
+
|
|
908
|
+
`--model` and `--effort` also apply to matching. `--auth` applies throughout.
|
|
909
|
+
Planning and matching reject ambient command providers that conflict with explicit ChatGPT
|
|
780
910
|
or API-key auth. SDK-selected command providers retain their authentication.
|
|
781
911
|
|
|
782
912
|
From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
|
|
@@ -801,6 +931,7 @@ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
|
|
|
801
931
|
`markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
|
|
802
932
|
Markdown. A supplied snapshot takes precedence over a file.
|
|
803
933
|
|
|
934
|
+
A dry run reads and validates an explicit rubric before reporting a successful preflight.
|
|
804
935
|
The scan saves the rubric text in its local launch recipe. Retrying a Standard
|
|
805
936
|
scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
|
|
806
937
|
with a saved rubric reuses that copy even if the remote default or file changes.
|
|
@@ -825,7 +956,7 @@ behavior are unchanged.
|
|
|
825
956
|
|
|
826
957
|
The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
|
|
827
958
|
Each launched scan or rerun gets its own allowance after setup, and reconnects
|
|
828
|
-
do not reset it. Standard scans
|
|
959
|
+
do not reset it. [Resumed Standard scans](#resuming-an-interrupted-scan) keep the original deadline. For batch and
|
|
829
960
|
component scans, the project setting applies separately to each scan attempt,
|
|
830
961
|
not to planning, result matching, or the total campaign.
|
|
831
962
|
|
|
@@ -836,13 +967,20 @@ codex-security scan . --mode deep --workers 2 --subagents 0 \
|
|
|
836
967
|
--stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
|
|
837
968
|
```
|
|
838
969
|
|
|
839
|
-
|
|
840
|
-
`--subagents`
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
970
|
+
Deep Scan repeats Standard scans in batches of up to `--workers`, with
|
|
971
|
+
`--subagents` per scan. Workers can share what they are investigating, ask each
|
|
972
|
+
other to check a source location, and reply while their audits are running. Each
|
|
973
|
+
worker verifies the evidence it reports. Deep Scan merges each completed batch in launch order.
|
|
974
|
+
It uses source locations, cited code and weakness descriptions to match repeated
|
|
975
|
+
findings. Each group keeps its first description, all reported locations, and
|
|
976
|
+
the original observations. Later batches receive the titles and primary
|
|
977
|
+
locations of retained findings so workers can investigate other reachable paths.
|
|
978
|
+
`--stop-after-no-new` counts consecutive
|
|
979
|
+
completed scans that added no findings. `--max-discovery-runs` caps the total
|
|
980
|
+
number started, including failures. `--max-time` stops discovery and returns
|
|
981
|
+
the findings from completed scans.
|
|
844
982
|
|
|
845
|
-
For TypeScript, see the [SDK Deep Scan example](
|
|
983
|
+
For TypeScript, see the [SDK Deep Scan example](sdk.md#configure-deep-scans).
|
|
846
984
|
|
|
847
985
|
Use project-file `scan.deep` settings or legacy
|
|
848
986
|
`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
|
|
@@ -850,6 +988,8 @@ that `subagents` can be zero. Discovery time accepts positive fractional minutes
|
|
|
850
988
|
its default and maximum are 5760 minutes (96 hours). Unlike Standard's
|
|
851
989
|
advisory allowance, the Deep discovery limit is enforced. Resuming a
|
|
852
990
|
Deep scan keeps its original deadline; rerunning starts a new scan.
|
|
991
|
+
If the deadline expires before any source review completes, the saved report
|
|
992
|
+
and scan manifest record that limitation.
|
|
853
993
|
`--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
|
|
854
994
|
legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
|
|
855
995
|
hours. Explicit settings override lower-priority configuration across units.
|
|
@@ -896,18 +1036,21 @@ credentials, and workflow resume behavior.
|
|
|
896
1036
|
For `dedupe --scan latest`, matching across worktrees or clones requires a Git
|
|
897
1037
|
executable outside all saved scan targets. If a historical target includes the
|
|
898
1038
|
available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
|
|
899
|
-
explicit saved scan ID. Exact-path `latest` lookup
|
|
1039
|
+
explicit saved scan ID. Exact-path `latest` lookup works without Git for non-Git
|
|
1040
|
+
scan targets; recorded Git generations require a trusted Git executable to verify
|
|
1041
|
+
that the checkout still owns its saved history.
|
|
900
1042
|
|
|
901
|
-
Repeat `--codex KEY=VALUE` for supported native settings.
|
|
902
|
-
`--codex
|
|
903
|
-
|
|
1043
|
+
Repeat `--codex KEY=VALUE` for supported native settings. For example,
|
|
1044
|
+
`--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
|
|
1045
|
+
Command Prompt, and PowerShell. Repeated or conflicting keys are rejected,
|
|
1046
|
+
including a `--model` or `--effort` flag plus its native equivalent.
|
|
904
1047
|
|
|
905
1048
|
To select a Codex file profile, put its settings in
|
|
906
1049
|
`$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
|
|
907
1050
|
`CODEX_HOME` is unset), then run:
|
|
908
1051
|
|
|
909
1052
|
```bash
|
|
910
|
-
npx @openai/codex-security scan . --codex
|
|
1053
|
+
npx @openai/codex-security scan . --codex "profile='review'"
|
|
911
1054
|
```
|
|
912
1055
|
|
|
913
1056
|
In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
|
|
@@ -933,11 +1076,11 @@ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
|
|
|
933
1076
|
|
|
934
1077
|
```bash
|
|
935
1078
|
codex-security patch "Security issue" --model gateway-model \
|
|
936
|
-
--codex
|
|
937
|
-
--codex
|
|
938
|
-
--codex
|
|
939
|
-
--codex
|
|
940
|
-
--codex
|
|
1079
|
+
--codex "model_provider='gateway'" \
|
|
1080
|
+
--codex "model_providers.gateway.name='Gateway'" \
|
|
1081
|
+
--codex "model_providers.gateway.base_url='https://gateway.example.test/v1'" \
|
|
1082
|
+
--codex "model_providers.gateway.wire_api='responses'" \
|
|
1083
|
+
--codex "model_providers.gateway.env_key='GATEWAY_API_KEY'"
|
|
941
1084
|
```
|
|
942
1085
|
|
|
943
1086
|
Set the provider's key environment variable before running. Patching and
|
|
@@ -963,12 +1106,14 @@ publication uses the same request attribution; embedding requests identify
|
|
|
963
1106
|
the package and version in their `User-Agent`.
|
|
964
1107
|
|
|
965
1108
|
These fields provide request attribution for supported inference providers, including
|
|
966
|
-
Bedrock. They do not create a separate telemetry collector
|
|
967
|
-
|
|
1109
|
+
Bedrock. They do not create a separate telemetry collector or make another
|
|
1110
|
+
provider's traffic visible to OpenAI. Local operation receipts separately record
|
|
1111
|
+
starts, outcomes, duration, and usage coverage; see
|
|
1112
|
+
[telemetry and measurement](telemetry.md).
|
|
968
1113
|
|
|
969
1114
|
Disable Codex usage analytics and built-in metrics with
|
|
970
|
-
`--codex
|
|
971
|
-
patch-risk assessment, and Deep Scan discovery
|
|
1115
|
+
`--codex analytics.enabled=false`. The setting carries into `scan --patch`,
|
|
1116
|
+
patch-risk assessment, and Deep Scan discovery workers, including
|
|
972
1117
|
resumed workers. Selected-profile settings take precedence over root settings.
|
|
973
1118
|
Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
|
|
974
1119
|
workers, including exporter choices and prompt-logging controls.
|
|
@@ -977,32 +1122,43 @@ The setting does not control configured OpenTelemetry exporters, integrations,
|
|
|
977
1122
|
authentication, or CLI update checks. Validation uses isolated configuration;
|
|
978
1123
|
patching and verification preserve ambient project trust.
|
|
979
1124
|
|
|
1125
|
+
For scan outcomes, the workbench saves a separate, local `lifecycle` record
|
|
1126
|
+
with the scan ID, launch surface, available release versions, mode, timestamps,
|
|
1127
|
+
and committed status. A completed scan indicates whether it produced reportable
|
|
1128
|
+
findings. Use `codex-security scans list --json` for the current repository.
|
|
1129
|
+
To find an offline import, use `codex-security scans list --scan-root <DIR> --json`
|
|
1130
|
+
with its output directory. Imported scans have lifecycle mode `import`. The SDK
|
|
1131
|
+
exposes `onLifecycle`, and the CLI includes observations in verbose diagnostics.
|
|
1132
|
+
Canceling a newly registered SDK scan through its abort signal, closing the
|
|
1133
|
+
client during the scan, or receiving a canceled hosted execution records
|
|
1134
|
+
`canceled`. A scan that has already completed keeps its committed outcome.
|
|
1135
|
+
Applications can choose how to collect and export these observations.
|
|
1136
|
+
|
|
980
1137
|
For filesystem and approval behavior, see the
|
|
981
|
-
[local security model](
|
|
1138
|
+
[local security model](sdk.md#local-security-model).
|
|
982
1139
|
|
|
983
1140
|
### Environment variables
|
|
984
1141
|
|
|
985
|
-
| Variable | Effect
|
|
986
|
-
| --------------------------------------------------------------------------- |
|
|
987
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence.
|
|
988
|
-
| `
|
|
989
|
-
| `
|
|
990
|
-
| `
|
|
991
|
-
| `
|
|
992
|
-
| `
|
|
993
|
-
| `
|
|
994
|
-
| `
|
|
995
|
-
| `
|
|
996
|
-
| `
|
|
997
|
-
| `
|
|
998
|
-
| `
|
|
999
|
-
| `
|
|
1000
|
-
| `
|
|
1001
|
-
| `
|
|
1002
|
-
| `
|
|
1003
|
-
| `
|
|
1004
|
-
| `
|
|
1005
|
-
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
1142
|
+
| Variable | Effect |
|
|
1143
|
+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
1144
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
|
|
1145
|
+
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
|
|
1146
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
|
|
1147
|
+
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
|
|
1148
|
+
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
|
|
1149
|
+
| `PYTHON` | Python interpreter unless an explicit option overrides it. |
|
|
1150
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
|
|
1151
|
+
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
|
|
1152
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
|
|
1153
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
|
|
1154
|
+
| `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
|
|
1155
|
+
| `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
|
|
1156
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
|
|
1157
|
+
| `GH_HOST` | GitHub Enterprise host for bulk discovery. |
|
|
1158
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
|
|
1159
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
|
|
1160
|
+
| `CI` | Disable interactive update notices. |
|
|
1161
|
+
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
1006
1162
|
|
|
1007
1163
|
Custom Codex executables need thread source attribution for `exec` and
|
|
1008
1164
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -1012,11 +1168,16 @@ Python lookup: `--python` on commands that expose interpreter selection or SDK
|
|
|
1012
1168
|
`pythonPath`, then
|
|
1013
1169
|
`PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
|
|
1014
1170
|
works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
|
|
1171
|
+
On POSIX, `CODEX_CLI_PATH` and `PYTHON` preserve trailing whitespace in an
|
|
1172
|
+
explicit path that selects an executable. Use an absolute path or a `./`
|
|
1173
|
+
prefix for filenames beginning or ending in whitespace. Bare command names
|
|
1174
|
+
are trimmed before lookup.
|
|
1015
1175
|
|
|
1016
1176
|
### Troubleshooting
|
|
1017
1177
|
|
|
1018
1178
|
Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
|
|
1019
|
-
retry, and worker diagnostics on stderr.
|
|
1179
|
+
retry, and worker diagnostics on stderr. Direct Deep Scans include coordinator events
|
|
1180
|
+
such as worker retries and duplicate-comparison failures. Diagnostic text is preserved in output,
|
|
1020
1181
|
saved failures, receipts, and patch-risk summaries. Review it for sensitive
|
|
1021
1182
|
information before sharing; upstream Codex output may already be redacted.
|
|
1022
1183
|
|
|
@@ -1025,6 +1186,12 @@ Finish older-version operations before upgrading. Never remove
|
|
|
1025
1186
|
`.codex-security-scan.sqlite3` during an operation. Stop all operations using the
|
|
1026
1187
|
credential home before manually removing an old `.codex-security-scan.lock`.
|
|
1027
1188
|
|
|
1189
|
+
If a scan reports that its state directory overlaps a protected root, choose a
|
|
1190
|
+
private directory in a separate tree, such as a sibling of the protected root.
|
|
1191
|
+
Set `CODEX_SECURITY_STATE_DIR` for local scans or `stateDirectory` on a hosted
|
|
1192
|
+
scan request. SDK callers handling `OutputInsideProtectedRootError.pathKind`
|
|
1193
|
+
can match `"state"` for this case.
|
|
1194
|
+
|
|
1028
1195
|
If credential-home preparation fails, the error includes the underlying
|
|
1029
1196
|
filesystem diagnostic. For permission or read-only filesystem errors, check
|
|
1030
1197
|
the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
|
|
@@ -1034,6 +1201,11 @@ and does not migrate existing credentials or reports.
|
|
|
1034
1201
|
Sandbox startup errors include the native diagnostic followed by a command to
|
|
1035
1202
|
reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
|
|
1036
1203
|
|
|
1204
|
+
If Windows Application Control blocks `windows.node` while validating a scan
|
|
1205
|
+
output directory, look for the module's block event in Event Viewer under
|
|
1206
|
+
Applications and Services Logs → Microsoft → Windows → CodeIntegrity → Operational.
|
|
1207
|
+
[Microsoft's App Control event reference](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/operations/event-id-explanations)
|
|
1208
|
+
|
|
1037
1209
|
On Windows, credential-home checks require trusted ownership and permissions
|
|
1038
1210
|
through every ancestor, including the volume root. Codex Security can repair
|
|
1039
1211
|
the credential home and its descendants; it does not change ancestor ownership
|
|
@@ -1090,10 +1262,13 @@ their own timestamps, window durations, and reset times. These are historical
|
|
|
1090
1262
|
observations, not a live allowance check or scan-only consumption. Empty readings
|
|
1091
1263
|
mean allowance was unavailable. There is no token-to-allowance conversion here.
|
|
1092
1264
|
|
|
1093
|
-
Cost displays use
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1265
|
+
Cost displays use Standard token rates for the model. OpenAI models use
|
|
1266
|
+
[OpenAI API pricing](https://developers.openai.com/api/docs/pricing). OpenAI
|
|
1267
|
+
models on Bedrock use [AWS pricing for the model, inference route, and region](https://github.com/openai/codex-security/blob/main/docs/bedrock.md#scan-cost-estimates).
|
|
1268
|
+
For managed OpenAI models on Vertex AI, see [Google Cloud Vertex AI cost estimates](#google-cloud-vertex-ai-cost-estimates).
|
|
1269
|
+
The short/long-context range estimates usage at published rates. Other service
|
|
1270
|
+
tiers, account discounts, and ChatGPT subscription allowance are outside that
|
|
1271
|
+
estimate. Models without known prices have no estimate.
|
|
1097
1272
|
|
|
1098
1273
|
JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
|
|
1099
1274
|
and `context: "unknown"`). A null maximum means no upper estimate is available.
|
|
@@ -1108,13 +1283,26 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
|
|
|
1108
1283
|
Automatic history matching gets at most one extra call with a limit; if more
|
|
1109
1284
|
work is needed, the scan is preserved and you can run `scans match --all`.
|
|
1110
1285
|
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1286
|
+
A scan with a cost limit requires complete token usage for its recorded scan,
|
|
1287
|
+
worker, and custom validation sessions before the SDK returns a completed result.
|
|
1288
|
+
The workbench reads compressed `.jsonl.zst` sessions with `compression.zstd`
|
|
1289
|
+
(Python 3.14+) or `backports.zstd` when available. Otherwise it uses the
|
|
1290
|
+
Node.js decoder bundled with the plugin.
|
|
1291
|
+
Missing or unreadable usage fails budget verification. Without a limit, usage
|
|
1292
|
+
reporting remains best effort.
|
|
1293
|
+
|
|
1294
|
+
When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealed
|
|
1295
|
+
report and retains unvalidated candidates as follow-up work. The saved report and
|
|
1296
|
+
the manifest's `scan.scope.limitations` record that validation was deferred.
|
|
1297
|
+
Reaching a configured limit with a valid finalized report returns `0` by default,
|
|
1298
|
+
or `1` if findings meet a configured failure threshold.
|
|
1299
|
+
|
|
1300
|
+
When a worker turn fails with a known cybersecurity policy refusal or an
|
|
1301
|
+
exhausted usage limit, Deep Scan stops retries and replacements, cancels active
|
|
1302
|
+
siblings, and retains completed worker artifacts. A capability check can succeed
|
|
1303
|
+
before a later request is refused. Use `scans show SCAN_ID` to inspect the failed
|
|
1304
|
+
scan and its retained results. To run it again from a saved recipe, use
|
|
1305
|
+
`scans rerun SCAN_ID`, which starts fresh discovery.
|
|
1118
1306
|
|
|
1119
1307
|
At 80% of a single interactive scan's limit, the dashboard offers a higher total
|
|
1120
1308
|
budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
|
|
@@ -1193,7 +1381,8 @@ the campaign a joint source review across repositories. For that workflow, use
|
|
|
1193
1381
|
|
|
1194
1382
|
Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
|
|
1195
1383
|
selection. It lists repositories pushed in the last 90 days, excluding forks
|
|
1196
|
-
and archives, asks
|
|
1384
|
+
and archives, asks where to save results, and saves the selection as `repositories.csv`.
|
|
1385
|
+
Pass `--output-dir DIR` to set the initial answer in the wizard.
|
|
1197
1386
|
Private checkouts use your GitHub CLI login.
|
|
1198
1387
|
|
|
1199
1388
|
For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
|
|
@@ -1209,7 +1398,32 @@ codex-security bulk-scan repositories.csv \
|
|
|
1209
1398
|
--output-dir /path/outside/repositories/results --workers 4
|
|
1210
1399
|
```
|
|
1211
1400
|
|
|
1401
|
+
`--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
|
|
1402
|
+
estimated limit among the pending repositories and their possible attempts for
|
|
1403
|
+
this invocation, including recovery. For example, a $12 limit with three pending
|
|
1404
|
+
repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
|
|
1405
|
+
overrun reduces the remaining budget for queued attempts. In-flight work can
|
|
1406
|
+
exceed a limit. The total limit skips model-based matching and owner suggestions,
|
|
1407
|
+
including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
|
|
1408
|
+
limit and includes prior recorded usage in its cost estimate.
|
|
1409
|
+
|
|
1212
1410
|
Bulk scans use clean shallow checkouts and support repository/path scopes.
|
|
1411
|
+
Bulk checkout, scan, and recovery processes select host tools outside every local
|
|
1412
|
+
source and campaign checkout. Inventory uses an external ripgrep executable or
|
|
1413
|
+
the copy shipped with the selected Codex installation.
|
|
1414
|
+
|
|
1415
|
+
On POSIX, campaign processes and script-based inventory tools search readable
|
|
1416
|
+
tool directories. Launchers must be readable so their shebang interpreters can
|
|
1417
|
+
be checked. Use an absolute interpreter path for campaign scripts, including
|
|
1418
|
+
`#!/usr/bin/env sh`, because workers run in different directories. If a directory
|
|
1419
|
+
contains an ineligible executable, its other tools remain available through a
|
|
1420
|
+
temporary PATH. Scripts using the system `/bin/sh` or `/usr/bin/env` run from
|
|
1421
|
+
their installed location when the packaged dispatcher can start. Keep other
|
|
1422
|
+
prefix-sensitive tools, including Python virtual environments, in directories
|
|
1423
|
+
where every entry can be used. On Windows, the campaign omits a tool directory
|
|
1424
|
+
from the child PATH if its Git, ripgrep, or Node executable link passes through a
|
|
1425
|
+
selected source.
|
|
1426
|
+
|
|
1213
1427
|
CSV scopes are literal paths relative to each checkout, including names such
|
|
1214
1428
|
as `~/src`.
|
|
1215
1429
|
Configured diff or working-tree scopes are rejected unless every affected row
|
|
@@ -1224,6 +1438,12 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
|
|
|
1224
1438
|
attempt per pending repository per invocation. Repeating the command continues
|
|
1225
1439
|
the campaign, skips completed results, and starts pending attempts. Occupied
|
|
1226
1440
|
attempt directories stop that repository and suggest `--recover`.
|
|
1441
|
+
If an ordinary attempt finds its checkout path already occupied, it stops before
|
|
1442
|
+
fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
|
|
1443
|
+
existing checkout before an ordinary retry.
|
|
1444
|
+
If checkout cleanup previously failed, the next invocation removes it only when
|
|
1445
|
+
its marker still identifies the same directory and scan attempt. Older or
|
|
1446
|
+
replacement checkouts without a matching marker are preserved.
|
|
1227
1447
|
Completed results are skipped only when their saved contract and seal are valid
|
|
1228
1448
|
and the manifest records a completed scan. Damaged or unsuccessful results get a
|
|
1229
1449
|
new attempt, including with `--recover`, while the old artifacts remain available.
|
|
@@ -1234,6 +1454,12 @@ require a new output directory. Version 1 manifests also require a new directory
|
|
|
1234
1454
|
because their original knowledge inputs and direct overrides cannot be verified.
|
|
1235
1455
|
Worker and retry counts can change when resuming.
|
|
1236
1456
|
|
|
1457
|
+
On POSIX, local repository paths retain `..` components in the campaign manifest
|
|
1458
|
+
so distinct symlink traversals remain distinct sources. Older campaigns may have
|
|
1459
|
+
recorded a normalized absolute path instead. Use that recorded path to resume the
|
|
1460
|
+
previously selected source; it can differ from the physical target selected by
|
|
1461
|
+
the original traversal. Use a new output directory to scan the corrected target.
|
|
1462
|
+
|
|
1237
1463
|
### Recovering failed or interrupted bulk scans
|
|
1238
1464
|
|
|
1239
1465
|
Use the original CSV, output directory, and options:
|
|
@@ -1253,10 +1479,12 @@ failed or interrupted attempt:
|
|
|
1253
1479
|
- An unavailable, failed, or canceled scan starts a new attempt at the pinned
|
|
1254
1480
|
revision, preserving old artifacts and checkouts.
|
|
1255
1481
|
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1482
|
+
Each nonempty committed line in `results.jsonl` must be valid JSON with a string
|
|
1483
|
+
task ID and a positive safe integer attempt number. If a line fails these checks,
|
|
1484
|
+
the command reports its line number and preserves the ledger. Restore a complete
|
|
1485
|
+
ledger backup that includes every committed attempt, or start a separate campaign
|
|
1486
|
+
in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
|
|
1487
|
+
a fresh attempt requires a new campaign.
|
|
1260
1488
|
|
|
1261
1489
|
New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
|
|
1262
1490
|
workers and one recovery/new attempt per repository. A resume connection failure
|
|
@@ -1326,32 +1554,56 @@ Supply the validation prompt again when rerunning.
|
|
|
1326
1554
|
|
|
1327
1555
|
## Import vendor findings locally
|
|
1328
1556
|
|
|
1329
|
-
Choose
|
|
1330
|
-
Each guide shows how to preview its input for a local repository. Follow the [shared procedure](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
|
|
1331
|
-
to confirm the import and read the resulting records.
|
|
1557
|
+
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.
|
|
1332
1558
|
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1559
|
+
| Input and goal | Command | Service contacted | Where to find the result |
|
|
1560
|
+
| ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
1561
|
+
| Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
|
|
1562
|
+
| 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. |
|
|
1563
|
+
| 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`. |
|
|
1564
|
+
| 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. |
|
|
1565
|
+
| 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. |
|
|
1339
1566
|
|
|
1340
1567
|
For `publish findings`, `--to` is required. With `--to local`, `--repository`
|
|
1341
|
-
takes a checkout path.
|
|
1342
|
-
selects the output format. A local preview
|
|
1343
|
-
|
|
1568
|
+
takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
|
|
1569
|
+
The reader detects the file format. `--format json` selects the output format. A local preview checks the file offline without
|
|
1570
|
+
saving findings or calling a model. For example, preview a complete Endor
|
|
1571
|
+
Finding export from the matching checkout, replacing the namespace, project
|
|
1572
|
+
and branch in the source key.
|
|
1573
|
+
|
|
1574
|
+
```sh
|
|
1575
|
+
codex-security publish findings /private/path/endor-findings.json --provider endor \
|
|
1576
|
+
--to local --repository . --source-key NAMESPACE/PROJECT/main --dry-run --format json
|
|
1577
|
+
```
|
|
1578
|
+
|
|
1579
|
+
After reviewing the findings and exclusions, rerun the command without
|
|
1580
|
+
`--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).
|
|
1581
|
+
|
|
1582
|
+
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)
|
|
1344
1583
|
|
|
1345
1584
|
Local readback uses `findings imported [PATH]`. The path defaults to the current
|
|
1346
1585
|
directory. Each imported record starts as `not_assessed`. Unknown revisions and
|
|
1347
1586
|
locations stay unknown. Repository-scoped sources are checked against comparable
|
|
1348
1587
|
configured Git remotes as described in the provider guide. Reimporting the same
|
|
1349
1588
|
source key and finding ID reports created, updated, or unchanged records.
|
|
1350
|
-
Records omitted from the new selection stay stored.
|
|
1351
|
-
|
|
1589
|
+
Records omitted from the new selection stay stored. Local imports can retain
|
|
1590
|
+
evidence that exceeds Cloud's per-finding limits.
|
|
1591
|
+
|
|
1592
|
+
If a report contains both ready and excluded records, the local dry run exits
|
|
1593
|
+
with status 0. After confirmation, the import stores the ready records and
|
|
1594
|
+
exits with status 1. If all records are excluded, both commands exit with
|
|
1595
|
+
status 2. A clean empty report exits with status 0 in either mode and stores
|
|
1596
|
+
no findings.
|
|
1597
|
+
|
|
1598
|
+
Preview the same file and source key again for the intended destination before
|
|
1599
|
+
publishing. Semgrep Guardian selections, Web API SAST selections and full
|
|
1600
|
+
project collections support both destinations. Choose the [Semgrep import method](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md) that matches your source.
|
|
1352
1601
|
|
|
1353
|
-
|
|
1354
|
-
|
|
1602
|
+
## Import Trivy dependency findings
|
|
1603
|
+
|
|
1604
|
+
Use `--provider trivy` for language-package vulnerabilities in schema-v2
|
|
1605
|
+
repository or filesystem JSON. The [Trivy guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) explains how
|
|
1606
|
+
to set the scan root and check manifest paths.
|
|
1355
1607
|
|
|
1356
1608
|
## Import Endor Labs findings
|
|
1357
1609
|
|
|
@@ -1359,31 +1611,88 @@ Use `--provider endor` for one Endor project and context. The
|
|
|
1359
1611
|
[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
|
|
1360
1612
|
SARIF compatibility, and the local preview.
|
|
1361
1613
|
|
|
1614
|
+
## Import SonarQube Cloud issues
|
|
1615
|
+
|
|
1616
|
+
`import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
|
|
1617
|
+
that capture for the intended destination before confirming. A Cloud confirmation
|
|
1618
|
+
saves the issues locally and publishes them. Use `--full-output` with
|
|
1619
|
+
`--format json` or `--format jsonl` for a structured result.
|
|
1620
|
+
[Collect and replay a Sonar capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
|
|
1621
|
+
|
|
1622
|
+
## Import GitHub findings locally or to Cloud
|
|
1623
|
+
|
|
1624
|
+
Use `--provider github` with separate source keys for
|
|
1625
|
+
[code scanning alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
|
|
1626
|
+
[Dependabot alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md) and
|
|
1627
|
+
[security advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
|
|
1628
|
+
Sign in with `gh` for the CLI collectors. `GH_HOST` defaults to `github.com`.
|
|
1629
|
+
|
|
1630
|
+
### Import GHSA advisories separately
|
|
1631
|
+
|
|
1632
|
+
Use `import github-advisories OWNER/REPO` for published repository advisories
|
|
1633
|
+
or add `--github-advisory-source global` and one or more `--github-advisory`
|
|
1634
|
+
IDs to collect global advisories. Check the installed dependency against each
|
|
1635
|
+
affected range. [Advisory selection and SDK examples](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
|
|
1636
|
+
|
|
1637
|
+
## Import alerts from the CLI
|
|
1638
|
+
|
|
1639
|
+
Collect open code-scanning alerts on the default branch and save the complete
|
|
1640
|
+
array outside the checkout. Use a private temporary directory and run
|
|
1641
|
+
validation from the matching checkout. Validation sends the evidence to your
|
|
1642
|
+
configured model provider.
|
|
1643
|
+
|
|
1644
|
+
```sh
|
|
1645
|
+
out=$(mktemp -d) &&
|
|
1646
|
+
codex-security import github OWNER/REPO --format json > "$out/alerts.json" &&
|
|
1647
|
+
codex-security validate "$out/alerts.json"
|
|
1648
|
+
```
|
|
1649
|
+
|
|
1650
|
+
The collector reads alerts, including third-party SARIF uploads. It does not
|
|
1651
|
+
start a scan. For filters, ref selection and SDK validation, see the
|
|
1652
|
+
[code scanning guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md).
|
|
1653
|
+
|
|
1362
1654
|
## Publish findings to Cloud
|
|
1363
1655
|
|
|
1364
|
-
Use
|
|
1365
|
-
|
|
1366
|
-
to preview and confirm it. The following settings and result fields apply to
|
|
1367
|
-
scanner publication across providers.
|
|
1656
|
+
Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
|
|
1657
|
+
If you're collecting live issues with `import sonar`, [publish from the Sonar preview's saved capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
|
|
1368
1658
|
|
|
1369
1659
|
### Preview and publish
|
|
1370
1660
|
|
|
1371
|
-
|
|
1372
|
-
repository URL or Cloud
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1661
|
+
Set `--to cloud`. For `--repository`, use the connected GitHub or GitHub
|
|
1662
|
+
Enterprise repository URL or its Cloud ID. Either works for retries. If
|
|
1663
|
+
several connectors share the URL, use the ID. You can import before the
|
|
1664
|
+
repository's first native scan.
|
|
1665
|
+
|
|
1666
|
+
Cloud requires a file-backed ChatGPT login. Codex Security signs in with the
|
|
1667
|
+
`cli_auth_credentials_store` set in your Codex `config.toml`
|
|
1668
|
+
(`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Without it, the login
|
|
1669
|
+
can be saved in the system keyring. To publish, set
|
|
1670
|
+
`cli_auth_credentials_store = "file"` there, then run `codex-security login`
|
|
1671
|
+
with the ChatGPT account you want to use. `codex-security login status`
|
|
1672
|
+
checks the current sign-in without changing credential storage.
|
|
1673
|
+
|
|
1674
|
+
### Review the Cloud destination
|
|
1675
|
+
|
|
1676
|
+
Run the command with `--dry-run --format json`. Check `accountId`,
|
|
1677
|
+
`cloudApiUrl`, `destination` and `source.source_key`. Compare `findings` and
|
|
1678
|
+
`excluded` with the records you meant to import.
|
|
1679
|
+
|
|
1680
|
+
- **Private findings inbox.** If the preview includes `privateImport`, the
|
|
1681
|
+
report goes to your inbox. The repository and connector identify the
|
|
1682
|
+
suggested assessment target. Check `format`, `bytes` and `sha256` in
|
|
1683
|
+
`privateImport` to identify the upload. The CLI and SDK encode the reviewed
|
|
1684
|
+
occurrences as `security.findings.v1` when it fits. For Wiz and Endor, an
|
|
1685
|
+
inbox that requires native records or has a smaller upload limit can receive
|
|
1686
|
+
native records that reproduce the reviewed evidence.
|
|
1687
|
+
- **Repository publisher.** Check `repository.environment_id` in each entry
|
|
1688
|
+
of `requests`. The publisher checks the current source versions. Existing
|
|
1689
|
+
records keep their environment. New records use the repository's authorized
|
|
1690
|
+
default.
|
|
1691
|
+
|
|
1692
|
+
To import, run the same command without `--dry-run` and confirm. The terminal
|
|
1693
|
+
shows the file, exclusions, severities and up to five finding IDs and titles.
|
|
1694
|
+
The prompt defaults to No. For a noninteractive import, add `--yes` after
|
|
1695
|
+
reviewing the full JSON preview.
|
|
1387
1696
|
|
|
1388
1697
|
### Configure an alternate Cloud deployment
|
|
1389
1698
|
|
|
@@ -1402,23 +1711,62 @@ instructions. API requests always use the API root. The older
|
|
|
1402
1711
|
|
|
1403
1712
|
### Resume interrupted imports
|
|
1404
1713
|
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1714
|
+
If the result includes `savedSubmission`, keep that checkpoint. Rerun the
|
|
1715
|
+
original command with `--dry-run --format json` using the same build, input, account,
|
|
1716
|
+
destination, API endpoint and state directory. Check `cloudApiUrl`. If
|
|
1717
|
+
`resumed` is true, confirm to continue the saved submission. If it's false,
|
|
1718
|
+
review the new submission before confirming. Finish older-format pending submissions with the client that created them. If a response was lost, check the inbox job or repository records before starting a fresh upload.
|
|
1719
|
+
|
|
1720
|
+
- **Private inbox.** The CLI checks the report digest and reuses its saved
|
|
1721
|
+
request IDs. It can read an accepted job even if the deployment has since
|
|
1722
|
+
disabled uploads. After an inbox reset, check the new report format, size
|
|
1723
|
+
and digest before confirming.
|
|
1724
|
+
- **Repository publisher.** The CLI saves each request privately before
|
|
1725
|
+
sending up to 100 findings. Retries use the same publisher, request IDs and
|
|
1726
|
+
bodies. If the repository has been reset, preview and confirm a fresh
|
|
1727
|
+
submission.
|
|
1728
|
+
|
|
1412
1729
|
[Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
|
|
1413
1730
|
|
|
1414
1731
|
### Results and exit codes
|
|
1415
1732
|
|
|
1416
|
-
| Status | Exit code | Meaning
|
|
1417
|
-
| ------------- | --------- |
|
|
1418
|
-
| `
|
|
1419
|
-
| `
|
|
1420
|
-
| `
|
|
1421
|
-
| `
|
|
1733
|
+
| Status | Exit code | Meaning |
|
|
1734
|
+
| ------------- | --------- | -------------------------------------------------------------------------------------- |
|
|
1735
|
+
| `empty` | 0 | No records were available to upload. |
|
|
1736
|
+
| `complete` | 0 | The inbox job processed every record successfully, or the publisher verified each one. |
|
|
1737
|
+
| `partial` | 1 | The import had exclusions or record errors, or the inbox job failed or was cancelled. |
|
|
1738
|
+
| `interrupted` | 2 | The CLI stopped while uploading, checking the result or saving a receipt. |
|
|
1739
|
+
| `failed` | 2 | Preparation failed before upload. |
|
|
1740
|
+
|
|
1741
|
+
A clean empty report needs no confirmation. Self-contained file imports can
|
|
1742
|
+
finish before Cloud sign-in; Semgrep Platform and Snyk REST captures use the
|
|
1743
|
+
Cloud catalog to verify their repository. Local imports still validate the
|
|
1744
|
+
checkout and create no workbench database. Explicit scanner errors
|
|
1745
|
+
and selections containing only excluded records fail; JSON output retains their
|
|
1746
|
+
diagnostics and exclusion reasons. Existing findings stay open.
|
|
1747
|
+
|
|
1748
|
+
For automation, check the scanner's exit status as well as the import's. SARIF
|
|
1749
|
+
can contain no runs or omit results in a rules-only export. `empty` describes
|
|
1750
|
+
the selected report, not whether a scan completed successfully.
|
|
1751
|
+
|
|
1752
|
+
For a partial or interrupted import, check `excluded` and any `error` before
|
|
1753
|
+
retrying. Some records may already have reached Cloud.
|
|
1754
|
+
|
|
1755
|
+
- **Private inbox.** In `privateJob`, check the job `status`, `counts.error`
|
|
1756
|
+
and `counts.unprocessed`. The receipt also identifies the job (`id`) and the
|
|
1757
|
+
uploaded file (`input.file_id`). The CLI reads the job receipt, so a
|
|
1758
|
+
successful import can show `verified: 0`. To share a finding, open it in
|
|
1759
|
+
your inbox, assess it against a pinned repository revision and publish the
|
|
1760
|
+
reportable assessment.
|
|
1761
|
+
- **Repository publisher.** `verified` counts records whose identity the CLI
|
|
1762
|
+
confirmed by reading them back. If the version matches the receipt, the CLI
|
|
1763
|
+
also checks the evidence. A newer version can have different evidence and
|
|
1764
|
+
still count as verified. `unacknowledged` counts records awaiting a receipt,
|
|
1765
|
+
including records Cloud accepted if the response was lost. Use `client_id`
|
|
1766
|
+
to match a receipt item to its request and `source_finding_id` in `failures`
|
|
1767
|
+
to find a failed vendor record. Counts include earlier batches with receipts.
|
|
1768
|
+
When present, `cloudUrl` opens the repository. Assessment and sharing are
|
|
1769
|
+
separate steps.
|
|
1422
1770
|
|
|
1423
1771
|
With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
|
|
1424
1772
|
Failed and interrupted imports set `ok` to `false` and `error.code` to
|
|
@@ -1426,235 +1774,37 @@ Failed and interrupted imports set `ok` to `false` and `error.code` to
|
|
|
1426
1774
|
Other formats reject `--full-output` before reading the file or contacting
|
|
1427
1775
|
Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
|
|
1428
1776
|
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
unacknowledged. Review `error` before retrying, and check `excluded` for local
|
|
1433
|
-
input errors. Counts include previously acknowledged batches in the same
|
|
1434
|
-
saved submission.
|
|
1777
|
+
Progress goes to stderr and JSON results to stdout. The repository publisher
|
|
1778
|
+
uploads sequentially and uses up to four concurrent requests for lookups and
|
|
1779
|
+
readback.
|
|
1435
1780
|
|
|
1436
|
-
|
|
1437
|
-
to four concurrent requests. Uploads are sequential. Saved receipts and
|
|
1438
|
-
readback verify source-record identity and evidence. Codex assessment and
|
|
1439
|
-
visibility in the shared Cloud Findings view are separate. `cloudUrl`, when
|
|
1440
|
-
available, links to the destination repository in Cloud.
|
|
1781
|
+
### Import Snyk findings
|
|
1441
1782
|
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
separate source key for each format. See the [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for
|
|
1447
|
-
collection and preview commands.
|
|
1783
|
+
Use `--provider snyk` for native Open Source JSON, plugin exports, SARIF or
|
|
1784
|
+
monitored Open Source and Code issues. The [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md)
|
|
1785
|
+
covers saved files, distinct source keys for each format, and collection with
|
|
1786
|
+
`import snyk`.
|
|
1448
1787
|
|
|
1449
1788
|
### Import Wiz findings
|
|
1450
1789
|
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1456
|
-
|
|
1457
|
-
The preview shows which Cloud destination will receive the selected records.
|
|
1458
|
-
When the deployment advertises private import for the scanner, the CLI puts a
|
|
1459
|
-
report in the signed-in account’s **private findings inbox**. The preview
|
|
1460
|
-
identifies its format and byte count. For complete Endor findings and Wiz
|
|
1461
|
-
vulnerability JSON exports, the CLI sends the original bytes when Cloud
|
|
1462
|
-
advertises the format and every record matches the reviewed selection. Other
|
|
1463
|
-
selections and in-memory collectors use `security.findings.v1`. The CLI
|
|
1464
|
-
attaches the selected repository and connector as a suggested assessment
|
|
1465
|
-
target. Review the selection, exclusions, source key and destination before
|
|
1466
|
-
confirming.
|
|
1467
|
-
|
|
1468
|
-
The job receipt contains the file and job identifiers and record counts. To
|
|
1469
|
-
share a finding, open it in Cloud, assess it against a pinned repository
|
|
1470
|
-
revision, and explicitly publish a reportable assessment. An import can
|
|
1471
|
-
finish with record errors. Check the error and unprocessed counts in the
|
|
1472
|
-
receipt.
|
|
1473
|
-
|
|
1474
|
-
Repeat the same command to recover an interrupted private import. The CLI
|
|
1475
|
-
checks the report digest, reuses its saved request IDs, and reads an accepted
|
|
1476
|
-
job even when new uploads are disabled. Resetting the inbox requires a new
|
|
1477
|
-
preview and confirmation. Deployments and scanners using the repository
|
|
1478
|
-
publisher continue to show the repository destination and per-finding receipts.
|
|
1479
|
-
An in-flight repository publication resumes on its original protocol.
|
|
1480
|
-
|
|
1481
|
-
#### Select findings and a destination
|
|
1482
|
-
|
|
1483
|
-
Acquire selected findings through an authorized Wiz connection and save the
|
|
1484
|
-
complete native response. The publisher reads the saved file. MCP summaries,
|
|
1485
|
-
Wiz Issues, and local Wiz CLI scan results may have different shapes. Verify
|
|
1486
|
-
the selected response against the format for its finding family. Acquisition
|
|
1487
|
-
against a live Wiz tenant requires separate qualification.
|
|
1488
|
-
|
|
1489
|
-
For saved reports, use the detailed repository package vulnerability export
|
|
1490
|
-
shown in the Wiz guide. Raw Event on Code & Build Scans contains scan
|
|
1491
|
-
metadata. For other CSV exports, see [Convert CSV reports](#convert-csv-reports).
|
|
1492
|
-
|
|
1493
|
-
#### Package vulnerability inputs
|
|
1494
|
-
|
|
1495
|
-
Native package input can be a Wiz JSON vulnerability report, a vulnerability
|
|
1496
|
-
finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
|
|
1497
|
-
with one package record per line. The repository package-vulnerability CSV
|
|
1498
|
-
profile below is also supported. Plain and gzip-compressed files are accepted.
|
|
1499
|
-
A response that advertises another page is rejected. Complete the requested pages
|
|
1500
|
-
or save only the explicitly selected records; retain the named collection for
|
|
1501
|
-
SAST, repository secrets, and IaC.
|
|
1502
|
-
|
|
1503
|
-
For native package records, include `id`, `name`, `detailedName`,
|
|
1504
|
-
`vulnerableAsset.id`, and `vendorSeverity` or `severity`. Retain any available
|
|
1505
|
-
package, image, and repository metadata.
|
|
1506
|
-
|
|
1507
|
-
The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
|
|
1508
|
-
`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
|
|
1509
|
-
this profile; other Wiz report types use different fields.
|
|
1510
|
-
For repository imports, `CloudPlatform` must identify GitHub and
|
|
1511
|
-
`CloudProviderURL` must identify a repository branch. The repository URL must
|
|
1512
|
-
match the selected Cloud repository or, for local import, one of the checkout's
|
|
1513
|
-
Git remotes when configured. This also applies when the parsed findings are saved and
|
|
1514
|
-
read again as normalized JSONL. Other resource types are excluded.
|
|
1515
|
-
|
|
1516
|
-
CSV imports use `ID` as the occurrence identity and retain every parsed field,
|
|
1517
|
-
including unknown columns and quoted multiline values, in `source_data.row`.
|
|
1518
|
-
Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
|
|
1519
|
-
Vendor resolution status stays in the original evidence. The importer does not
|
|
1520
|
-
derive a branch or revision from a tree URL, or treat last-detected time as a
|
|
1521
|
-
record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
|
|
1522
|
-
and duplicate occurrence IDs among otherwise importable records stop the import.
|
|
1523
|
-
Review any excluded records in the preview before publishing.
|
|
1524
|
-
|
|
1525
|
-
Normalized JSONL is also accepted:
|
|
1526
|
-
|
|
1527
|
-
```json
|
|
1528
|
-
{
|
|
1529
|
-
"source_finding_id": "vendor-finding-42",
|
|
1530
|
-
"evidence": {
|
|
1531
|
-
"title": "Vulnerable example package",
|
|
1532
|
-
"severity": "high",
|
|
1533
|
-
"source_data": { "id": "vendor-finding-42" }
|
|
1534
|
-
}
|
|
1535
|
-
}
|
|
1536
|
-
```
|
|
1537
|
-
|
|
1538
|
-
Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
|
|
1539
|
-
exports; a selected project filter does not change the vendor namespace. Confirm
|
|
1540
|
-
that the selected assets or builds map to this repository. The raw Wiz adapter
|
|
1541
|
-
retains each record in `source_data`, uses reported severity, and leaves unknown
|
|
1542
|
-
branch/revision empty. Repository-branch findings retain their repository-relative
|
|
1543
|
-
file paths; container and other workload paths remain vendor evidence rather than
|
|
1544
|
-
source-code locations. It does not
|
|
1545
|
-
fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
|
|
1546
|
-
Findings from external network scans are excluded from this package vulnerability
|
|
1547
|
-
mapping.
|
|
1548
|
-
|
|
1549
|
-
#### SAST, repository secrets, and IaC inputs
|
|
1550
|
-
|
|
1551
|
-
For SAST, repository secrets, and IaC, save the documented JSON API collection:
|
|
1552
|
-
|
|
1553
|
-
| Finding family | Collection | Raw occurrence identity |
|
|
1554
|
-
| ------------------ | ---------------------------- | ----------------------- |
|
|
1555
|
-
| SAST | `data.sastFindings.nodes` | `sast:<id>` |
|
|
1556
|
-
| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
|
|
1557
|
-
| IaC | `data.iacFindings.nodes` | `iac:<id>` |
|
|
1558
|
-
|
|
1559
|
-
The collection identifies the mapping. Bare arrays of these raw findings are
|
|
1560
|
-
excluded because their overlapping fields do not identify a family. An export
|
|
1561
|
-
may contain multiple named collections. GraphQL errors and unfinished pages stop
|
|
1562
|
-
the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
|
|
1563
|
-
relationship to source code does not make it a repository secret.
|
|
1564
|
-
|
|
1565
|
-
Each new finding needs a verified source repository URL. Supply `repository.url`
|
|
1566
|
-
in the finding's repository metadata, or include the matching repository inventory
|
|
1567
|
-
in `data.versionControlResources.nodes`. For secrets, repository metadata is under
|
|
1568
|
-
`resource.typedProperties.repository`. The importer joins the inventory's
|
|
1569
|
-
`repository.id` to that source ID and uses `repository.url`; inventory node IDs,
|
|
1570
|
-
`providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
|
|
1571
|
-
must agree with the inventory and with the selected Cloud repository before any
|
|
1572
|
-
finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
|
|
1573
|
-
establishes case-insensitive repository matching on custom GitHub Enterprise
|
|
1574
|
-
hosts. Fresh imports preserve the reported branch name literally. Duplicate
|
|
1575
|
-
entries for one repository ID must agree on their platform and repository URL.
|
|
1576
|
-
For example, this synthetic selection supplies the inventory alongside its SAST
|
|
1577
|
-
collection:
|
|
1578
|
-
|
|
1579
|
-
```json
|
|
1580
|
-
{
|
|
1581
|
-
"data": {
|
|
1582
|
-
"sastFindings": {
|
|
1583
|
-
"nodes": [
|
|
1584
|
-
{
|
|
1585
|
-
"id": "finding-42",
|
|
1586
|
-
"name": "Untrusted query construction",
|
|
1587
|
-
"severity": "HIGH",
|
|
1588
|
-
"repository": { "id": "source-repository-1" },
|
|
1589
|
-
"filePath": "src/query.ts",
|
|
1590
|
-
"startLine": 10,
|
|
1591
|
-
"endLine": 12
|
|
1592
|
-
}
|
|
1593
|
-
]
|
|
1594
|
-
},
|
|
1595
|
-
"versionControlResources": {
|
|
1596
|
-
"nodes": [
|
|
1597
|
-
{
|
|
1598
|
-
"repository": {
|
|
1599
|
-
"id": "source-repository-1",
|
|
1600
|
-
"url": "https://github.com/example/project"
|
|
1601
|
-
}
|
|
1602
|
-
}
|
|
1603
|
-
]
|
|
1604
|
-
}
|
|
1605
|
-
}
|
|
1606
|
-
}
|
|
1607
|
-
```
|
|
1790
|
+
<a id="select-findings-and-a-destination"></a>
|
|
1791
|
+
<a id="package-vulnerability-inputs"></a>
|
|
1792
|
+
<a id="sast-repository-secrets-and-iac-inputs"></a>
|
|
1793
|
+
<a id="preserved-evidence"></a>
|
|
1794
|
+
<a id="convert-csv-reports"></a>
|
|
1608
1795
|
|
|
1609
|
-
|
|
1610
|
-
|
|
1611
|
-
|
|
1612
|
-
|
|
1613
|
-
|
|
1614
|
-
|
|
1615
|
-
| Family | Evidence retained in typed fields |
|
|
1616
|
-
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1617
|
-
| SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
|
|
1618
|
-
| Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
|
|
1619
|
-
| IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
|
|
1620
|
-
|
|
1621
|
-
Vendor status and verdict remain separate from Codex assessment. A secret's
|
|
1622
|
-
introduced commit is not its scanned revision. Missing source revisions and scan
|
|
1623
|
-
IDs stay unknown. A logical IaC resource is retained in the original record and
|
|
1624
|
-
does not establish that it is deployed. Precise original timestamps remain in
|
|
1625
|
-
`source_data`; only an explicit record-update timestamp maps to the whole-second
|
|
1626
|
-
`source_updated_at` field. SAST creation time and IaC last-seen time are not update
|
|
1627
|
-
timestamps.
|
|
1628
|
-
|
|
1629
|
-
#### Convert CSV reports
|
|
1630
|
-
|
|
1631
|
-
Native SAST and secret report downloads can be CSV, including gzip-compressed
|
|
1632
|
-
CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
|
|
1633
|
-
for its actual column headers into normalized JSONL, preserving each original row
|
|
1634
|
-
in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
|
|
1635
|
-
verifying the source repository. Use the same prefixed occurrence ID shown above
|
|
1636
|
-
so API and report imports update the same finding; normalized IDs are accepted
|
|
1637
|
-
exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
|
|
1638
|
-
for a vendor occurrence ID. Missing IDs or severity must be corrected at the
|
|
1639
|
-
source rather than invented.
|
|
1640
|
-
|
|
1641
|
-
For repository-secret reports, select `path` and `lineNumber` for source
|
|
1642
|
-
navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
|
|
1643
|
-
as the introduced commit. The standard secret metadata API does not supply a
|
|
1644
|
-
path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
|
|
1645
|
-
`rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
|
|
1646
|
-
repository/branch metadata. Preserve the original fields; source locations must
|
|
1647
|
-
be repository-relative, and an end line requires a start line. Keep credential
|
|
1648
|
-
values out of the metadata selection; the importer does not retrieve or test
|
|
1649
|
-
credentials or apply remediation instructions.
|
|
1650
|
-
|
|
1651
|
-
Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
|
|
1652
|
-
integer range is rejected; export those values as strings to preserve them
|
|
1653
|
-
exactly. Invalid records appear in `excluded` with their source ID and reason.
|
|
1796
|
+
Use `--provider wiz` for a [saved Wiz report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#quick-start).
|
|
1797
|
+
The provider guide describes [package JSON and CSV](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#package-vulnerability-inputs),
|
|
1798
|
+
[named SAST, secret and IaC collections](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#sast-repository-secrets-and-iac-inputs),
|
|
1799
|
+
[retained evidence](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#preserved-evidence) and
|
|
1800
|
+
[conversion to normalized JSONL](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#convert-csv-reports).
|
|
1654
1801
|
|
|
1655
1802
|
### Publish completed scans
|
|
1656
1803
|
|
|
1657
|
-
|
|
1804
|
+
The public `publish scan --help` menu describes Linear and custom publication
|
|
1805
|
+
from saved scans. The CSV input below belongs to Cloud publication.
|
|
1806
|
+
The following workflow is available to installations with Cloud publication access.
|
|
1807
|
+
Preview selected completed scans locally before uploading them.
|
|
1658
1808
|
|
|
1659
1809
|
```bash
|
|
1660
1810
|
codex-security publish scan --to cloud --dry-run --json
|
|
@@ -1668,12 +1818,15 @@ prefix of at least eight characters, or `latest` for the current repository.
|
|
|
1668
1818
|
Local sealed artifacts are required. Dry runs need no login or network access.
|
|
1669
1819
|
|
|
1670
1820
|
Uploads require ChatGPT credentials saved to a file. Set
|
|
1671
|
-
`cli_auth_credentials_store = "file"` in Codex `config.toml`, then
|
|
1672
|
-
|
|
1673
|
-
|
|
1674
|
-
|
|
1675
|
-
|
|
1676
|
-
|
|
1821
|
+
`cli_auth_credentials_store = "file"` in Codex `config.toml`, then run
|
|
1822
|
+
`codex-security login` again. Login, scans and other commands use that setting
|
|
1823
|
+
for the Codex Security sign-in.
|
|
1824
|
+
A dedicated login using automatic storage can publish if Codex Security
|
|
1825
|
+
recorded the native file fallback. An unverified file can belong to another
|
|
1826
|
+
account, so Cloud publication requires an explicit file store for an ambient login.
|
|
1827
|
+
|
|
1828
|
+
Use `publish scan DIR --to cloud` for one directory outside history. For
|
|
1829
|
+
multiple directories, repeat `--scan-dir PATH`. Each must contain one completed sealed scan, not a bulk-run
|
|
1677
1830
|
directory or `results.jsonl`. Do not mix directories with `--scan`.
|
|
1678
1831
|
Cloud also accepts exported CSV:
|
|
1679
1832
|
|
|
@@ -1705,7 +1858,8 @@ Select one completed scan by ID, prefix, `latest`, or directory; omit the select
|
|
|
1705
1858
|
for the picker. Live publication and `--skip-existing` require local history.
|
|
1706
1859
|
A directory-only dry run does not.
|
|
1707
1860
|
|
|
1708
|
-
`--linear-project PROJECT_ID`
|
|
1861
|
+
`--linear-project PROJECT_ID` selects a project. Existing scripts using the deprecated
|
|
1862
|
+
`--project PROJECT_ID` spelling continue to work. Flags override
|
|
1709
1863
|
`CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
|
|
1710
1864
|
previews titles offline; `--json` returns structured output.
|
|
1711
1865
|
|
|
@@ -1717,10 +1871,10 @@ Keys are omitted from saved results; diagnostic messages remain unchanged.
|
|
|
1717
1871
|
|
|
1718
1872
|
```bash
|
|
1719
1873
|
codex-security publish check /path/to/completed-scan \
|
|
1720
|
-
--
|
|
1874
|
+
--linear-team TEAM_ID --json
|
|
1721
1875
|
```
|
|
1722
1876
|
|
|
1723
|
-
`publish check` verifies artifacts and recorded publications. With an API key,
|
|
1877
|
+
`publish check` verifies scan artifacts and recorded Linear publications. With an API key,
|
|
1724
1878
|
it also checks authentication and destination access. It does not test issue
|
|
1725
1879
|
creation; connected-app access is reported as `not-checked`.
|
|
1726
1880
|
|
|
@@ -1729,15 +1883,16 @@ Choose a destination authorized to receive that content. Local history records
|
|
|
1729
1883
|
successful issue IDs separately from sealed artifacts. The CLI and the plugin's
|
|
1730
1884
|
finding-tracking workflow share these records when using the same Codex Security
|
|
1731
1885
|
state directory. Accepted writes remain recorded even if a later issue read fails.
|
|
1732
|
-
The shared-history migration preserves existing Linear receipts and replaces their
|
|
1733
|
-
old table. Upgrade CLI and plugin installations together when they share state;
|
|
1734
|
-
older publishers cannot write to the migrated database.
|
|
1735
1886
|
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1887
|
+
By default, publishing the same scan again creates new issues. With
|
|
1888
|
+
`--skip-existing`, the CLI skips occurrences with a recorded success for the
|
|
1889
|
+
same team and project. This includes issues the plugin created or reused.
|
|
1890
|
+
The CLI checks local history only. After an interrupted or concurrent run,
|
|
1891
|
+
check Linear for an existing issue before retrying.
|
|
1892
|
+
|
|
1893
|
+
If the CLI and plugin share a database from an older installation, upgrade
|
|
1894
|
+
both together. The shared history preserves existing Linear receipts, but
|
|
1895
|
+
publishers that require the old table can no longer record new ones.
|
|
1741
1896
|
|
|
1742
1897
|
```ts
|
|
1743
1898
|
import { publishScan } from "@openai/codex-security";
|
|
@@ -1778,7 +1933,9 @@ request. It sends the config name without findings or account identifiers.
|
|
|
1778
1933
|
If the request fails, times out, or returns an invalid rubric, the built-in
|
|
1779
1934
|
rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
|
|
1780
1935
|
uses your policy for every review. Rubrics and repeatable `--knowledge-base`
|
|
1781
|
-
context accept text, PDF, DOCX, and directories.
|
|
1936
|
+
context accept text, PDF, DOCX, and directories. Select external documents directly.
|
|
1937
|
+
Links in the artifact directory or a saved checkout must stay inside their source.
|
|
1938
|
+
When `--scan` cannot verify the saved checkout, use the document's canonical path.
|
|
1782
1939
|
|
|
1783
1940
|
Each finding is classified three times by default. `--runs N` accepts
|
|
1784
1941
|
an integer from 1 through 10; SDK options use `classificationRuns` with the same
|
|
@@ -1820,15 +1977,17 @@ or effort. A successful
|
|
|
1820
1977
|
run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
|
|
1821
1978
|
unchanged.
|
|
1822
1979
|
|
|
1823
|
-
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe
|
|
1824
|
-
`
|
|
1825
|
-
|
|
1980
|
+
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe returns
|
|
1981
|
+
`scanRepresentativeFindingIds` for this selection, in the same order as its
|
|
1982
|
+
corpus-wide `uniqueFindingIds`.
|
|
1826
1983
|
Linear publication defaults to saved classification selection, omits exclusions,
|
|
1827
1984
|
and uses assessed severity for title and priority. Descriptions retain original
|
|
1828
1985
|
severity and add the classification rationale. Publication rejects incomplete or
|
|
1829
1986
|
stale assessments. It never reclassifies or rereads the rubric at publication time.
|
|
1830
1987
|
|
|
1831
1988
|
```bash
|
|
1989
|
+
# List the IDs you can pass to --finding-id.
|
|
1990
|
+
codex-security dedupe --scan SCAN_ID --json | jq -r '.scanRepresentativeFindingIds[]'
|
|
1832
1991
|
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
|
|
1833
1992
|
--finding-id FINDING_ID
|
|
1834
1993
|
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
|
|
@@ -1843,46 +2002,32 @@ import {
|
|
|
1843
2002
|
classifySeverity,
|
|
1844
2003
|
classifyScanSeverity,
|
|
1845
2004
|
classifyScanDirectorySeverity,
|
|
2005
|
+
deduplicateScanDirectory,
|
|
1846
2006
|
publishScan,
|
|
1847
|
-
type FindingsDocument,
|
|
1848
2007
|
} from "@openai/codex-security";
|
|
1849
|
-
import { readFile } from "node:fs/promises";
|
|
1850
|
-
import { join } from "node:path";
|
|
1851
2008
|
|
|
1852
2009
|
// Assess supplied reports in memory.
|
|
1853
|
-
|
|
2010
|
+
await classifySeverity(findings, {
|
|
1854
2011
|
rubricPath: "/path/to/policy.md",
|
|
1855
2012
|
knowledgeBasePaths: ["/path/to/context.md"],
|
|
1856
2013
|
});
|
|
1857
2014
|
|
|
1858
2015
|
// Save assessments for a scan ID or sealed directory.
|
|
1859
2016
|
await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
|
|
1860
|
-
const
|
|
1861
|
-
|
|
1862
|
-
await readFile(join(scanDirectory, "findings.json"), "utf8"),
|
|
1863
|
-
) as FindingsDocument
|
|
1864
|
-
).findings;
|
|
1865
|
-
const scanFindingIds = new Set(
|
|
1866
|
-
scanFindings.map((finding) => finding.findingId),
|
|
1867
|
-
);
|
|
1868
|
-
// dedupeResult was produced by deduplicating this same scan.
|
|
1869
|
-
const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
|
|
1870
|
-
if (scanFindingIds.has(representative)) return representative;
|
|
1871
|
-
return dedupeResult.duplicateGroups
|
|
1872
|
-
.find((group) => group.includes(representative))!
|
|
1873
|
-
.find((member) => scanFindingIds.has(member))!;
|
|
2017
|
+
const dedupeResult = await deduplicateScanDirectory(scanDirectory, {
|
|
2018
|
+
repository: "/path/to/repository",
|
|
1874
2019
|
});
|
|
1875
|
-
await classifyScanDirectorySeverity(scanDirectory, {
|
|
2020
|
+
const classification = await classifyScanDirectorySeverity(scanDirectory, {
|
|
1876
2021
|
rubricPath: "/path/to/policy.md",
|
|
1877
|
-
findingIds:
|
|
2022
|
+
findingIds: dedupeResult.scanRepresentativeFindingIds,
|
|
1878
2023
|
});
|
|
1879
2024
|
|
|
1880
|
-
//
|
|
2025
|
+
// Preview Linear publication for those same findings using their assessments.
|
|
1881
2026
|
await publishScan(scanDirectory, {
|
|
1882
2027
|
destination: "linear",
|
|
1883
2028
|
teamId: "TEAM_ID",
|
|
1884
2029
|
classification,
|
|
1885
|
-
findingIds:
|
|
2030
|
+
findingIds: dedupeResult.scanRepresentativeFindingIds,
|
|
1886
2031
|
dryRun: true,
|
|
1887
2032
|
});
|
|
1888
2033
|
```
|
|
@@ -1989,24 +2134,41 @@ attach only their owner's session. Unrecorded earlier retry sessions may be abse
|
|
|
1989
2134
|
## Scan history and reruns
|
|
1990
2135
|
|
|
1991
2136
|
Commands default to the current repository. IDs accept unique prefixes of at
|
|
1992
|
-
least eight characters.
|
|
1993
|
-
|
|
1994
|
-
|
|
1995
|
-
|
|
1996
|
-
|
|
1997
|
-
|
|
1998
|
-
|
|
1999
|
-
|
|
2000
|
-
|
|
2001
|
-
|
|
2002
|
-
|
|
2003
|
-
|
|
2004
|
-
|
|
|
2005
|
-
|
|
|
2006
|
-
| `
|
|
2007
|
-
|
|
2008
|
-
|
|
2009
|
-
|
|
2137
|
+
least eight characters. Reading empty history leaves the workbench database uninitialized.
|
|
2138
|
+
|
|
2139
|
+
Linked Git worktrees share scans, findings, and reviewer decisions when their
|
|
2140
|
+
scans record the same repository generation in the selected state database.
|
|
2141
|
+
Older scans without this evidence remain target-local. Removed worktrees retain
|
|
2142
|
+
their recorded history; a reused checkout path does not inherit its previous
|
|
2143
|
+
owner's history. Separately verified clones can still be compared explicitly,
|
|
2144
|
+
but their finding histories remain separate.
|
|
2145
|
+
|
|
2146
|
+
Finding confirmation and automatic post-scan matching follow completion order
|
|
2147
|
+
in the workbench, without changing sealed report timestamps.
|
|
2148
|
+
|
|
2149
|
+
| Command | Purpose |
|
|
2150
|
+
| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
2151
|
+
| `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
|
|
2152
|
+
| `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
|
|
2153
|
+
| `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
|
|
2154
|
+
| `scans resume SCAN_ID` | Continue an interrupted Standard or Deep Scan. |
|
|
2155
|
+
| `scans rerun [SCAN_ID]` | Rerun a saved recipe in its checkout. |
|
|
2156
|
+
| `scans match --all` | Match completed scans in this repository generation, including linked worktrees. |
|
|
2157
|
+
| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
|
|
2158
|
+
| `findings list [REPOSITORY]` | List open findings. |
|
|
2159
|
+
| `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
|
|
2160
|
+
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
|
|
2161
|
+
|
|
2162
|
+
In the terminal, `findings list` shows the occurrence ID for each open finding.
|
|
2163
|
+
Copy that ID into `findings false-positive` with your reason. Subsequent scans can
|
|
2164
|
+
use the explanation while it applies. In `scans show SCAN_ID --json`, each
|
|
2165
|
+
displayed occurrence has its saved rationale in `triage.note` after dismissal. The list identifies
|
|
2166
|
+
a repository with no saved scan history separately from one with zero open findings.
|
|
2167
|
+
From an unregistered Git subdirectory with no scan history of its own, it uses the worktree root.
|
|
2168
|
+
|
|
2169
|
+
With an omitted ID or the literal `latest`, `scans show` selects the latest completed scan, while `scans logs`
|
|
2170
|
+
selects the latest scan of any status. Both prefer a scan in the current
|
|
2171
|
+
worktree when one qualifies. After a successful scan followed by a
|
|
2010
2172
|
failed or active scan, these defaults refer to different runs. Human output
|
|
2011
2173
|
identifies the selected run, labels its saved update time, and gives matching
|
|
2012
2174
|
commands with its full scan ID:
|
|
@@ -2024,9 +2186,24 @@ history. Inspect its saved status before choosing resume or rerun, and supply
|
|
|
2024
2186
|
the original custom prompt files for reruns. Structured history and log output
|
|
2025
2187
|
and command selection defaults are unchanged.
|
|
2026
2188
|
|
|
2027
|
-
|
|
2028
|
-
|
|
2029
|
-
|
|
2189
|
+
Without an ID, rerun selects the latest completed scan in the current worktree.
|
|
2190
|
+
If only a related checkout has a completed scan, rerun shows its ID, path, and
|
|
2191
|
+
revision. Pass that ID to run the saved recipe using the files currently at its
|
|
2192
|
+
saved checkout and context paths. Reruns do not reload project files.
|
|
2193
|
+
The readable scan recipe records your authentication choice. A separate private
|
|
2194
|
+
replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
|
|
2195
|
+
`model_providers` settings, including any credentials written directly in
|
|
2196
|
+
`http_headers`. If you use `env_key` or `env_http_headers`, the profile stores
|
|
2197
|
+
the variable names. Set those variables when you rerun or resume. Settings
|
|
2198
|
+
inherited from a named file profile are reloaded from that file. If an older
|
|
2199
|
+
scan omitted your endpoint, start a new scan with the original `--codex` override.
|
|
2200
|
+
|
|
2201
|
+
When routing through environment variables, set them for each launch, including
|
|
2202
|
+
rerun and resume. Deep workers inherit `CODEX_OSS_BASE_URL` and `CODEX_OSS_PORT`
|
|
2203
|
+
for Ollama and LM Studio, and `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`,
|
|
2204
|
+
and `GOOGLE_APPLICATION_CREDENTIALS` for Vertex AI.
|
|
2205
|
+
|
|
2206
|
+
Supply replacement scan and custom-validation prompts when the original used them:
|
|
2030
2207
|
|
|
2031
2208
|
```bash
|
|
2032
2209
|
codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
|
|
@@ -2048,25 +2225,64 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
|
2048
2225
|
writable, and outside the target repository. Session logs may contain sensitive
|
|
2049
2226
|
data even though scan recipes do not store credentials.
|
|
2050
2227
|
|
|
2051
|
-
|
|
2052
|
-
|
|
2053
|
-
|
|
2054
|
-
|
|
2055
|
-
|
|
2228
|
+
Keep the same state directory across linked worktrees. Changing it selects
|
|
2229
|
+
separate history, artifacts, and a dedicated Codex sign-in. `--scan-root`
|
|
2230
|
+
filters recorded artifact paths; it does not import another directory's scans.
|
|
2231
|
+
|
|
2232
|
+
The workbench records the outer checkout directory when it registers a target.
|
|
2233
|
+
A later nested checkout cannot make tools from that directory eligible for
|
|
2234
|
+
automatic discovery. When an older saved target lacks a recorded checkout
|
|
2235
|
+
directory, set `CODEX_SECURITY_GIT` to the absolute path of a trusted Git
|
|
2236
|
+
executable outside the checkouts. If you use a system Python instead of the
|
|
2237
|
+
Codex managed runtime, set `PYTHON` to the absolute path of your interpreter.
|
|
2238
|
+
|
|
2239
|
+
Saved scan logs retain the finishing turn, including its final response, and
|
|
2240
|
+
exclude later turns once the scan records a completion boundary. Older scans
|
|
2241
|
+
retain the full history of their attributed sessions and keep their existing
|
|
2242
|
+
worker-selection boundaries. This also applies to logs attached with
|
|
2243
|
+
`feedback --include-logs`.
|
|
2244
|
+
|
|
2245
|
+
Codex may compress saved session logs to `.jsonl.zst`. Plain and compressed logs
|
|
2246
|
+
work on all supported Node.js versions, including logs, feedback attachments,
|
|
2247
|
+
usage accounting, and saved-session discovery for resume. A bundled decoder
|
|
2248
|
+
reads concatenated frames and reports truncated streams as collection errors.
|
|
2056
2249
|
|
|
2057
|
-
### Resuming an interrupted
|
|
2250
|
+
### Resuming an interrupted scan
|
|
2058
2251
|
|
|
2059
2252
|
```bash
|
|
2060
2253
|
codex-security scans list --scan-root /path/to/security-scans
|
|
2061
2254
|
codex-security scans resume SCAN_ID
|
|
2062
2255
|
```
|
|
2063
2256
|
|
|
2257
|
+
The terminal list shows the full scan ID and labels the last activity of a
|
|
2258
|
+
`running` scan after 24 hours without an update. For a Standard or Deep Scan with a saved
|
|
2259
|
+
launch recipe and its original session, it also shows the resume command to use after interruption.
|
|
2260
|
+
|
|
2064
2261
|
The scan must still be `running`, with its original checkout, output directory,
|
|
2065
2262
|
and Codex session in the same state directory. Checkout identity, revision, and
|
|
2066
2263
|
contents must match. Completed, failed, and canceled scans need a rerun instead.
|
|
2067
2264
|
|
|
2068
|
-
|
|
2069
|
-
|
|
2265
|
+
On Windows, keep the protected `.codex-security-resume` directory in the scan
|
|
2266
|
+
output. It lets the workbench verify the original output even before the first
|
|
2267
|
+
checkpoint. If an older scan stopped with an empty output, start a new scan with
|
|
2268
|
+
`codex-security scans rerun SCAN_ID`.
|
|
2269
|
+
|
|
2270
|
+
New Windows Standard and Deep Scans also record the checkout's native volume and file ID
|
|
2271
|
+
when the filesystem supplies them. Validation and remediation verify the same
|
|
2272
|
+
checkout identity. An older scan can resume across Python
|
|
2273
|
+
versions when its saved checkout identity can be verified. If the workbench
|
|
2274
|
+
cannot verify it, resume with the Python runtime that started the scan or use
|
|
2275
|
+
`codex-security scans rerun SCAN_ID` to start a new scan.
|
|
2276
|
+
|
|
2277
|
+
Resume keeps the scan ID, saved settings and instructions, completed workers, artifacts,
|
|
2278
|
+
and accumulated cost. A Standard scan continues in its original Codex session with
|
|
2279
|
+
the same `--max-cost` limit and `--max-time` deadline. Only one CLI or SDK call
|
|
2280
|
+
can run it at a time. If the connection fails after the session is saved, the CLI
|
|
2281
|
+
prints the resume command. Work since the last checkpoint may need to be repeated.
|
|
2282
|
+
Use `scans rerun` for canceled or failed scans, including authentication failures.
|
|
2283
|
+
For custom validation, rerun with the original validation instructions.
|
|
2284
|
+
|
|
2285
|
+
Knowledge-bearing scans save their extracted documents in
|
|
2070
2286
|
the private `.scan-knowledge.json` continuation file beside the scan artifacts.
|
|
2071
2287
|
Resume verifies and uses that snapshot even if the original files changed or were
|
|
2072
2288
|
deleted. Preserve it with the scan directory; canonical reports do not embed its
|
|
@@ -2084,7 +2300,10 @@ to update campaign receipts. Individual resume does not update `results.jsonl`.
|
|
|
2084
2300
|
|
|
2085
2301
|
### Matching saved scans
|
|
2086
2302
|
|
|
2087
|
-
|
|
2303
|
+
Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the model
|
|
2304
|
+
and save its matching decisions. Pass `--force` to recompute saved matches.
|
|
2305
|
+
The older `scans match BEFORE AFTER` spelling is also supported.
|
|
2306
|
+
Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
|
|
2088
2307
|
Comparisons classify findings as new, persisting, reopened, not observed, resolved,
|
|
2089
2308
|
or unknown. An absent finding in the later scope is not observed; absence alone
|
|
2090
2309
|
does not verify remediation. A finding is resolved only after it was explicitly
|
|
@@ -2095,6 +2314,13 @@ One comparison ID is compared with the latest completed scan.
|
|
|
2095
2314
|
codex-security scans match --all --force --model gpt-6.1-sol --effort high
|
|
2096
2315
|
```
|
|
2097
2316
|
|
|
2317
|
+
When a saved Standard scan and a Deep scan have the same recorded target,
|
|
2318
|
+
revision, and snapshot digest, matching flags findings that have different
|
|
2319
|
+
anchors but share a unique rule, first displayed source range, and optional
|
|
2320
|
+
instance. Matching preserves the case of saved paths. Codex can request the
|
|
2321
|
+
saved evidence to distinguish separate causes at that site. Automatic matching
|
|
2322
|
+
under a cost limit keeps its single comparison call.
|
|
2323
|
+
|
|
2098
2324
|
Only high-confidence root-cause matches are grouped. Uncertain and related
|
|
2099
2325
|
findings remain separate. Rebuilding retains stable identities, triage, and
|
|
2100
2326
|
sealed artifacts; interruption preserves completed comparisons. Model/effort
|
|
@@ -2144,6 +2370,10 @@ must already exist.
|
|
|
2144
2370
|
|
|
2145
2371
|
SARIF is the default format, and `./results.sarif` is the default output path.
|
|
2146
2372
|
Use `--export-format json` or `--export-format csv` to choose another format.
|
|
2373
|
+
An existing default output file is preserved. Pass `--output FILE` to choose
|
|
2374
|
+
a filename or explicitly replace it. Use `--output -` to pipe the complete
|
|
2375
|
+
artifact. Response filters, token controls, and `--full-output` require a
|
|
2376
|
+
command that returns a formatted response.
|
|
2147
2377
|
To select a saved scan by its ID and export JSON, run:
|
|
2148
2378
|
|
|
2149
2379
|
```bash
|
|
@@ -2292,9 +2522,11 @@ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/exa
|
|
|
2292
2522
|
|
|
2293
2523
|
### Local pre-commit checks
|
|
2294
2524
|
|
|
2295
|
-
|
|
2296
|
-
failure or findings at
|
|
2297
|
-
for
|
|
2525
|
+
The generated hook runs a `--working-tree` scan and blocks the commit on scan
|
|
2526
|
+
failure or findings at or above its threshold (`high` by default). It uses the
|
|
2527
|
+
checkout's normal index for staged and unstaged changes, so it can include changes
|
|
2528
|
+
outside a partial commit and miss content staged only in a separate index.
|
|
2529
|
+
Use required CI for enforcement because local hooks are optional.
|
|
2298
2530
|
|
|
2299
2531
|
Install the CLI outside the target repository and run that copy directly. `npx`
|
|
2300
2532
|
can select a repository-local package. Before installation, inspect:
|
|
@@ -2312,148 +2544,14 @@ codex-security install-hook /path/to/repository
|
|
|
2312
2544
|
```
|
|
2313
2545
|
|
|
2314
2546
|
To migrate an existing generated hook, verify it is a regular file used only by
|
|
2315
|
-
this repository and contains only the generated
|
|
2316
|
-
|
|
2317
|
-
|
|
2318
|
-
|
|
2319
|
-
|
|
2320
|
-
|
|
2321
|
-
|
|
2322
|
-
|
|
2323
|
-
The [SonarQube Cloud guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md) covers live collection, repository
|
|
2324
|
-
binding, saved issue-search pages, and replay. Unlike a saved-file
|
|
2325
|
-
`publish findings` preview, `import sonar --dry-run` writes a private capture
|
|
2326
|
-
and returns its path. Confirm with the capture from the preview for the intended
|
|
2327
|
-
destination. A Cloud confirmation imports the selected issues locally and
|
|
2328
|
-
publishes them to Cloud. Use `--full-output` with `--format json` or
|
|
2329
|
-
`--format jsonl` for a structured success or error envelope.
|
|
2330
|
-
|
|
2331
|
-
## Import GitHub findings locally or to Cloud
|
|
2332
|
-
|
|
2333
|
-
Choose the [code scanning](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
|
|
2334
|
-
[Dependabot](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md), or
|
|
2335
|
-
[GitHub Security Advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md) guide to acquire
|
|
2336
|
-
and preview findings. All three use `--provider github`. Keep a separate source
|
|
2337
|
-
key for each family. Saving locally or publishing to Cloud requires the
|
|
2338
|
-
[external-import opt-in](#import-vendor-findings-locally).
|
|
2339
|
-
|
|
2340
|
-
The code-scanning and advisory CLI collectors use `gh` to authenticate for
|
|
2341
|
-
`GH_HOST` (default `github.com`). A GitHub
|
|
2342
|
-
plugin connection can select alerts but does not sign the CLI in.
|
|
2343
|
-
Collection retains the selected ref's instance. Branches keep separate
|
|
2344
|
-
evidence. An alert-wide dismissal takes precedence over the selected instance's
|
|
2345
|
-
open or fixed state. Missing security severity stays `unknown`. See
|
|
2346
|
-
[code-scanning access requirements](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository).
|
|
2347
|
-
|
|
2348
|
-
The SDK offers the same preview and publication boundary for Cloud:
|
|
2349
|
-
|
|
2350
|
-
```ts
|
|
2351
|
-
import {
|
|
2352
|
-
importGitHubCodeScanningAlerts,
|
|
2353
|
-
normalizeGitHubCodeScanningAlerts,
|
|
2354
|
-
prepareNormalizedExternalPublication,
|
|
2355
|
-
} from "@openai/codex-security";
|
|
2356
|
-
|
|
2357
|
-
const alerts = await importGitHubCodeScanningAlerts({
|
|
2358
|
-
repository: "example/project",
|
|
2359
|
-
});
|
|
2360
|
-
const prepared = await prepareNormalizedExternalPublication(
|
|
2361
|
-
normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
|
|
2362
|
-
{
|
|
2363
|
-
provider: "github",
|
|
2364
|
-
repository: "https://github.com/example/project",
|
|
2365
|
-
sourceKey: "github.com/example/project/code-scanning",
|
|
2366
|
-
},
|
|
2367
|
-
);
|
|
2368
|
-
console.log(prepared.preview);
|
|
2369
|
-
// After reviewing the preview:
|
|
2370
|
-
const receipt = await prepared.publish();
|
|
2371
|
-
```
|
|
2372
|
-
|
|
2373
|
-
For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
|
|
2374
|
-
the original alerts to retain evidence that exceeds Cloud limits. Pass the result
|
|
2375
|
-
to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
|
|
2376
|
-
its preview, and call `import()`. Alternatively, pass the saved alert file directly
|
|
2377
|
-
to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
|
|
2378
|
-
|
|
2379
|
-
### Import GHSA advisories separately
|
|
2380
|
-
|
|
2381
|
-
See the [GitHub Security Advisories guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md)
|
|
2382
|
-
to save repository advisories or selected global database records and preview
|
|
2383
|
-
them for the chosen destination. Advisories report affected ranges and
|
|
2384
|
-
available fixes. Verify installed dependencies and applicability in the
|
|
2385
|
-
destination repository separately.
|
|
2386
|
-
|
|
2387
|
-
Repository lists default to published advisories. When selecting exact IDs, omit
|
|
2388
|
-
`--github-state`. Selecting a repository advisory by its GHSA ID can return a
|
|
2389
|
-
draft if you have access.
|
|
2390
|
-
Global collection requires one or more explicit IDs.
|
|
2391
|
-
Acquisition failure yields no partial selection. Access to private or
|
|
2392
|
-
unpublished repository advisories requires the repository advisory read
|
|
2393
|
-
permission and access to the record. See
|
|
2394
|
-
[GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
|
|
2395
|
-
|
|
2396
|
-
In the SDK, collect the advisories with `importGitHubAdvisories()`. For Cloud,
|
|
2397
|
-
pass `normalizeGitHubAdvisories(advisories, "cloud")` to
|
|
2398
|
-
`prepareNormalizedExternalPublication()`. For local storage, pass
|
|
2399
|
-
`normalizeGitHubAdvisories(advisories, "local")` to `prepareNormalizedLocalImport()`.
|
|
2400
|
-
`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
|
|
2401
|
-
`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
|
|
2402
|
-
records. Both forms require `repository: "OWNER/REPO"` as source or target context.
|
|
2403
|
-
Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
|
|
2404
|
-
|
|
2405
|
-
## Import alerts from the CLI
|
|
2406
|
-
|
|
2407
|
-
```bash
|
|
2408
|
-
codex-security import github example/repository --format json > /path/outside/repository/alerts.json
|
|
2409
|
-
codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
|
|
2410
|
-
codex-security validate /path/outside/repository/alerts.json
|
|
2411
|
-
```
|
|
2412
|
-
|
|
2413
|
-
Run validation from the matching local repository. Import defaults to open alerts
|
|
2414
|
-
on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
|
|
2415
|
-
`--github-ref REF` to filter. Exact alert numbers ignore state and reject a
|
|
2416
|
-
nondefault state.
|
|
2417
|
-
|
|
2418
|
-
Import is read-only and returns an array. Save validation inputs without output
|
|
2419
|
-
filters or token limits. It includes third-party SARIF uploads, does not start
|
|
2420
|
-
Codex, and does not check out code. Each record contains `source`, `repository`,
|
|
2421
|
-
`number`, `url`, and the full upstream `alert`.
|
|
2422
|
-
|
|
2423
|
-
For a disposition per alert, import and validate through the SDK:
|
|
2424
|
-
|
|
2425
|
-
```ts
|
|
2426
|
-
import {
|
|
2427
|
-
CodexSecurity,
|
|
2428
|
-
importGitHubCodeScanningAlerts,
|
|
2429
|
-
} from "@openai/codex-security";
|
|
2430
|
-
|
|
2431
|
-
const findings = await importGitHubCodeScanningAlerts({
|
|
2432
|
-
repository: "example/repository",
|
|
2433
|
-
alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
|
|
2434
|
-
githubHost: "github.com",
|
|
2435
|
-
githubToken: process.env["GH_TOKEN"],
|
|
2436
|
-
});
|
|
2437
|
-
|
|
2438
|
-
const security = new CodexSecurity();
|
|
2439
|
-
try {
|
|
2440
|
-
for (const finding of findings) {
|
|
2441
|
-
const result = await security.validate({
|
|
2442
|
-
repositoryPath: "/path/to/repository",
|
|
2443
|
-
finding,
|
|
2444
|
-
});
|
|
2445
|
-
console.log(finding.url, result.disposition, result.outputDir);
|
|
2446
|
-
}
|
|
2447
|
-
} finally {
|
|
2448
|
-
await security.close();
|
|
2449
|
-
}
|
|
2450
|
-
```
|
|
2451
|
-
|
|
2452
|
-
SDK options include `state` (default `"open"`), `ref`, and `signal`.
|
|
2453
|
-
Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
|
|
2454
|
-
If you omit the token, the SDK asks the GitHub CLI for credentials, including
|
|
2455
|
-
its supported token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
|
|
2456
|
-
The token needs code-scanning read access; access failures reject the import.
|
|
2547
|
+
this repository and contains only the generated commands. Rerun `install-hook`
|
|
2548
|
+
with the desired `--fail-on-severity` level to change the threshold. The installer
|
|
2549
|
+
recognizes the legacy `npx` hook and earlier generated templates with matching
|
|
2550
|
+
absolute Node and CLI paths. It refuses to replace a hand-edited hook.
|
|
2551
|
+
On POSIX, reinstalling a recognized hook restores its owner execute bit if Git
|
|
2552
|
+
could not execute it. The installer checks that the resulting hook is executable.
|
|
2553
|
+
The installer uses host Git for the selected repository and respects
|
|
2554
|
+
`core.hooksPath`.
|
|
2457
2555
|
|
|
2458
2556
|
## Validate and patch findings
|
|
2459
2557
|
|
|
@@ -2461,12 +2559,12 @@ Hosts that manage their own model execution can use `codex-security validate --r
|
|
|
2461
2559
|
This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
|
|
2462
2560
|
See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
|
|
2463
2561
|
|
|
2464
|
-
`validate`
|
|
2465
|
-
|
|
2466
|
-
|
|
2467
|
-
|
|
2468
|
-
|
|
2469
|
-
|
|
2562
|
+
`validate` sends the finding to your configured model provider. Its review
|
|
2563
|
+
tools can read the checkout, with network access and web search disabled.
|
|
2564
|
+
The assessment uses source evidence and skips builds, tests, PoCs and application
|
|
2565
|
+
execution. Both `validate` and `patch` accept files or literal text in the
|
|
2566
|
+
current directory. Patching by saved finding or occurrence ID selects the
|
|
2567
|
+
original repository.
|
|
2470
2568
|
|
|
2471
2569
|
Basic patching also works in ordinary directories and Git worktrees before their
|
|
2472
2570
|
first commit. Directory change tracking excludes `.git` and `.svn` metadata.
|
|
@@ -2480,6 +2578,14 @@ codex-security patch --scan SCAN_ID --severity high --json
|
|
|
2480
2578
|
codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
|
|
2481
2579
|
```
|
|
2482
2580
|
|
|
2581
|
+
For `validate`, `patch`, and `verify-fix`, an explicit local file URL such as
|
|
2582
|
+
`file:///home/reviewer/finding.md` (Windows: `file:///C:/reviews/finding.md`)
|
|
2583
|
+
requires the file to exist. A missing file stops the command before the model
|
|
2584
|
+
runs. Use `pathToFileURL(absolutePath).href` in Node to encode spaces and
|
|
2585
|
+
special characters correctly. Absolute paths and paths starting with `~/`, `./`, or `../`
|
|
2586
|
+
also require an existing file. Use `text:/path is exposed` to pass path-shaped
|
|
2587
|
+
prose verbatim, or `text:text:example` for a finding that starts with `text:`.
|
|
2588
|
+
|
|
2483
2589
|
Context inputs are optional and can be combined:
|
|
2484
2590
|
|
|
2485
2591
|
- `--context TEXT` adds inline security context or reviewer feedback.
|
|
@@ -2487,6 +2593,7 @@ Context inputs are optional and can be combined:
|
|
|
2487
2593
|
- Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
|
|
2488
2594
|
document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
|
|
2489
2595
|
are searched recursively; binary files, symlinks, and Git metadata are skipped.
|
|
2596
|
+
When validating from a Git checkout, select external documents directly.
|
|
2490
2597
|
|
|
2491
2598
|
Inline and file context are included in the prompt. Knowledge-base documents are
|
|
2492
2599
|
prepared in a temporary directory for Codex to read during the assessment, then
|
|
@@ -2508,7 +2615,7 @@ locally does not guarantee provider support. Keep the schema small and use it on
|
|
|
2508
2615
|
when the caller needs structured results. It checks the result's shape, not whether
|
|
2509
2616
|
the security conclusion is correct. Relative paths resolve from the current directory.
|
|
2510
2617
|
|
|
2511
|
-
|
|
2618
|
+
Save the assessment by redirecting stdout:
|
|
2512
2619
|
`codex-security validate findings.json > assessment.md`. For runtime proof, run a
|
|
2513
2620
|
separate reproduction step. Missing facts are reported as proof gaps; a finding
|
|
2514
2621
|
supported by source evidence does not require runtime reproduction.
|
|
@@ -2570,7 +2677,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
|
|
|
2570
2677
|
|
|
2571
2678
|
An illustrative result is below. Actual decisions depend on the repository;
|
|
2572
2679
|
this example assumes a tenant filter exists but deployment routing is unavailable.
|
|
2573
|
-
|
|
2680
|
+
Before updating finding records, [check that each input ID appears exactly
|
|
2681
|
+
once](validate-records.md#check-the-returned-ids), including unresolved
|
|
2682
|
+
candidates.
|
|
2574
2683
|
|
|
2575
2684
|
```json
|
|
2576
2685
|
{
|
|
@@ -2635,7 +2744,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
|
|
|
2635
2744
|
task. The container must provide it. There is no automatic fallback; optional
|
|
2636
2745
|
patch-risk assessment still uses its read-only sandbox.
|
|
2637
2746
|
|
|
2638
|
-
`scan --patch` runs after a complete scan
|
|
2747
|
+
`scan --patch` runs after a complete scan without a cost limit. A cost-limited
|
|
2748
|
+
scan saves the findings and skips the interactive patch offer. Use
|
|
2749
|
+
`codex-security patch --scan SCAN_ID` to patch separately.
|
|
2750
|
+
`--patch-severity` defaults to `low`;
|
|
2639
2751
|
`high` selects high and critical findings. Interactive users can select findings
|
|
2640
2752
|
and add instructions. The interactive finding browser lists critical, high,
|
|
2641
2753
|
medium, then low findings, preserving scan order within each severity.
|
|
@@ -2658,8 +2770,13 @@ including code, HTML, and math, retain their original text.
|
|
|
2658
2770
|
GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
|
|
2659
2771
|
```
|
|
2660
2772
|
|
|
2661
|
-
Both providers return `pullRequest: { branch, url }`.
|
|
2662
|
-
|
|
2773
|
+
Both providers return `pullRequest: { branch, url }`. Saved-finding publication
|
|
2774
|
+
includes files changed and verified in the same patch turn. If a selected file
|
|
2775
|
+
already had local edits, the CLI keeps the patch in the working tree for review.
|
|
2776
|
+
The risk assessment and commit use the same verified tree. If staging changed
|
|
2777
|
+
during the run and Git cannot update the index, the CLI reports it and keeps
|
|
2778
|
+
the existing staging.
|
|
2779
|
+
Supplied-issue patching requires a clean tree. If publication fails, run the printed
|
|
2663
2780
|
`patch --resume-pr BRANCH` command in the same repository. It reuses the saved
|
|
2664
2781
|
commit and refuses changed branches. Retain the GitLab host setting on resume.
|
|
2665
2782
|
|
|
@@ -2687,16 +2804,20 @@ truncating any selected finding. The CLI prints verdicts in selection order
|
|
|
2687
2804
|
after every request returns valid results. For these selections the CLI omits
|
|
2688
2805
|
per-event progress and update notices so stderr cannot delay the verdicts.
|
|
2689
2806
|
|
|
2690
|
-
If
|
|
2691
|
-
the
|
|
2692
|
-
|
|
2693
|
-
|
|
2807
|
+
If a finding would exceed the input limit, `validate`, `patch`, and `verify-fix`
|
|
2808
|
+
put the complete finding data in a temporary file for Codex to search alongside
|
|
2809
|
+
the checkout. A single input file keeps its original text and line breaks.
|
|
2810
|
+
The file remains available until the task finishes and is then removed. The
|
|
2811
|
+
SDK's local `validate()` and `patch()` methods use the same fallback.
|
|
2694
2812
|
|
|
2695
2813
|
`--verification-mode static` selects source-only assessment, as described above
|
|
2696
2814
|
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
2697
2815
|
|
|
2698
2816
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
2699
|
-
|
|
2817
|
+
Without output options, each finding prints a verdict and its evidence.
|
|
2818
|
+
Explicit output formats, field selection and token controls operate on the
|
|
2819
|
+
structured result containing `repository`, optional `scanId`, and `results`.
|
|
2820
|
+
Exit codes are `0` when all findings are
|
|
2700
2821
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|
|
2701
2822
|
With `--json` or `--format jsonl`, authentication and execution failures return
|
|
2702
2823
|
`status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
|
|
@@ -2709,9 +2830,21 @@ retain exit codes `130` and `143` without a result.
|
|
|
2709
2830
|
|
|
2710
2831
|
## Command discovery and integrations
|
|
2711
2832
|
|
|
2712
|
-
|
|
2713
|
-
|
|
2714
|
-
`--format
|
|
2833
|
+
Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.
|
|
2834
|
+
|
|
2835
|
+
Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Add `--json` to return the generated script as a JSON string. The same option returns the menu text when an omitted command or subcommand displays help. With `--full-output`, the text is in `data`. Scan output supports
|
|
2836
|
+
`--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
|
|
2837
|
+
`--filter-output`, `--token-limit`, and `--token-offset` options accept either
|
|
2838
|
+
`--option value` or `--option=value`.
|
|
2839
|
+
|
|
2840
|
+
`--token-limit` and `--token-offset` take nonnegative integers and select a
|
|
2841
|
+
text view of the formatted result. Truncated JSON and JSONL views are returned
|
|
2842
|
+
as a JSON string containing the excerpt and its token range. With
|
|
2843
|
+
`--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
|
|
2844
|
+
the next page when more tokens are available. `--token-count` returns the
|
|
2845
|
+
estimated size instead. A failed full-output JSON or JSONL response always
|
|
2846
|
+
retains its error code and message. If the failure carries result data,
|
|
2847
|
+
`--token-count` reports its size in `meta.tokenCount`.
|
|
2715
2848
|
|
|
2716
2849
|
`skills add` syncs generated CLI command guidance; it does not install the full
|
|
2717
2850
|
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
|
|
@@ -2719,9 +2852,90 @@ only read-only `info` because the transport cannot cancel scans. For the plugin'
|
|
|
2719
2852
|
scan, triage, patch, and verification workflows, see the
|
|
2720
2853
|
[agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
|
|
2721
2854
|
|
|
2855
|
+
Both installers default to `--scope user`. Use `--scope project` for the current
|
|
2856
|
+
directory. Existing scripts can continue using `--no-global` for project scope.
|
|
2857
|
+
Inspect either command with `--help`, `--schema`, or `--version` before installing.
|
|
2858
|
+
|
|
2859
|
+
`skills add --depth 0` creates a single skill. The default depth of 1 groups
|
|
2860
|
+
guidance by top-level command. To check the installed files, use the same
|
|
2861
|
+
depth with `skills list`, for example `skills list --depth 0 --json`. Each
|
|
2862
|
+
entry includes its canonical `SKILL.md` locations in the current project and
|
|
2863
|
+
user profile.
|
|
2864
|
+
|
|
2865
|
+
`mcp add` registers detected compatible clients. If it finds none in the
|
|
2866
|
+
selected scope, choose a client with `--agent NAME` (repeatable), or register
|
|
2867
|
+
every compatible client with `--all`. For example, `mcp add --scope project
|
|
2868
|
+
--agent cursor` writes Cursor's project configuration. In user scope, Codex
|
|
2869
|
+
detection and registration use `CODEX_HOME` when set. Amp supports user
|
|
2870
|
+
registration only.
|
|
2871
|
+
|
|
2872
|
+
The default launcher runs `npx --yes @openai/codex-security --mcp`. To register
|
|
2873
|
+
an installed executable, use its name or path with `--exec` and repeat
|
|
2874
|
+
`--arg=VALUE` for each argument. Each value is stored literally, including
|
|
2875
|
+
spaces, empty arguments, and leading dashes. To run an npm package, select
|
|
2876
|
+
`--package NAME`. The existing `--command` accepts a command line or HTTP(S)
|
|
2877
|
+
URL. Quotes group command-line words, and backslashes are literal. A bare
|
|
2878
|
+
executable name is stored directly. Use `--exec` for a path with
|
|
2879
|
+
spaces, including when the executable will be installed on another machine.
|
|
2880
|
+
|
|
2881
|
+
```bash
|
|
2882
|
+
codex-security mcp add --agent cursor --exec "/opt/My Tools/server" --arg=--mcp
|
|
2883
|
+
codex-security mcp add --agent cursor --package @openai/codex-security --arg=--mcp
|
|
2884
|
+
```
|
|
2885
|
+
|
|
2886
|
+
`mcp doctor` checks the current CLI's server startup and tool catalog. To
|
|
2887
|
+
verify a registered launcher, connect from the client where it was registered.
|
|
2888
|
+
|
|
2722
2889
|
For local findings storage, deduplication, and custom endpoints, see the
|
|
2723
2890
|
[findings guide](findings-service.md).
|
|
2724
2891
|
|
|
2892
|
+
### Shell completions
|
|
2893
|
+
|
|
2894
|
+
The generated scripts register both `codex-security` and `cs`. Choose your shell
|
|
2895
|
+
and open a new session after saving the setup.
|
|
2896
|
+
|
|
2897
|
+
**Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:
|
|
2898
|
+
|
|
2899
|
+
```bash
|
|
2900
|
+
source <(codex-security completions bash)
|
|
2901
|
+
```
|
|
2902
|
+
|
|
2903
|
+
**Zsh.** In `~/.zshrc`, load the generated script after your completion system
|
|
2904
|
+
calls `compinit`. If you initialize completions yourself, use:
|
|
2905
|
+
|
|
2906
|
+
```zsh
|
|
2907
|
+
autoload -Uz compinit
|
|
2908
|
+
compinit
|
|
2909
|
+
source <(codex-security completions zsh)
|
|
2910
|
+
```
|
|
2911
|
+
|
|
2912
|
+
**Fish.** Add this line to `~/.config/fish/config.fish`:
|
|
2913
|
+
|
|
2914
|
+
```fish
|
|
2915
|
+
codex-security completions fish | source
|
|
2916
|
+
```
|
|
2917
|
+
|
|
2918
|
+
**Nushell.** Save the generated closures alongside `config.nu`:
|
|
2919
|
+
|
|
2920
|
+
```nu
|
|
2921
|
+
codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)
|
|
2922
|
+
```
|
|
2923
|
+
|
|
2924
|
+
In `config.nu`, source the file and dispatch the two names to their completers:
|
|
2925
|
+
|
|
2926
|
+
```nu
|
|
2927
|
+
source codex-security-completions.nu
|
|
2928
|
+
let previous_completer = $env.config.completions.external.completer?
|
|
2929
|
+
$env.config.completions.external.enable = true
|
|
2930
|
+
$env.config.completions.external.completer = {|spans|
|
|
2931
|
+
match $spans.0 {
|
|
2932
|
+
"codex-security" => { do $_incur_complete_codex_security $spans }
|
|
2933
|
+
"cs" => { do $_incur_complete_cs $spans }
|
|
2934
|
+
_ => { if $previous_completer != null { do $previous_completer $spans } }
|
|
2935
|
+
}
|
|
2936
|
+
}
|
|
2937
|
+
```
|
|
2938
|
+
|
|
2725
2939
|
### Hosted Standard scan
|
|
2726
2940
|
|
|
2727
2941
|
`codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
|