@openai/codex-security 0.8.2 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +201 -178
- package/_bundled_plugin/.app.json +4 -0
- package/_bundled_plugin/.mcp.json +6 -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 +51 -14
- 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/core-scan.md +14 -5
- package/_bundled_plugin/references/default-severity-rubric.md +33 -0
- package/_bundled_plugin/references/final-report.md +5 -3
- package/_bundled_plugin/references/finding-detail-fields.md +19 -18
- 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/threat-model.md +1 -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 +188 -454
- package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +317 -377
- package/_bundled_plugin/scripts/finding_preview.py +25 -29
- package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
- package/_bundled_plugin/scripts/legacy_findings.py +148 -0
- package/_bundled_plugin/scripts/posix_scan_local_files.py +198 -0
- package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
- package/_bundled_plugin/scripts/report_projection.py +167 -178
- 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 +1 -0
- package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
- package/_bundled_plugin/scripts/validate_scan_contract.py +9 -7
- package/_bundled_plugin/scripts/windows_scan_local_files.py +600 -72
- package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
- package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
- package/_bundled_plugin/scripts/workbench/retained_coverage.py +38 -75
- 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 +152 -248
- 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 +71 -7
- package/_bundled_plugin/scripts/workbench_cli.py +121 -14
- package/_bundled_plugin/scripts/workbench_constants.py +19 -0
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
- package/_bundled_plugin/scripts/workbench_db.py +550 -492
- package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
- package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +90 -4
- package/_bundled_plugin/scripts/workbench_native_indexes.py +29 -33
- package/_bundled_plugin/scripts/workbench_progress.py +10 -1
- package/_bundled_plugin/scripts/workbench_publication.py +14 -10
- package/_bundled_plugin/scripts/workbench_remediation.py +508 -11
- package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
- package/_bundled_plugin/scripts/workbench_scan_history.py +139 -80
- package/_bundled_plugin/scripts/workbench_scan_start.py +84 -25
- package/_bundled_plugin/scripts/workbench_scan_usage.py +666 -117
- package/_bundled_plugin/scripts/workbench_schema.py +44 -55
- package/_bundled_plugin/scripts/workbench_setup.py +251 -0
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
- package/_bundled_plugin/scripts/workbench_source_scopes.py +33 -23
- package/_bundled_plugin/scripts/workbench_target.py +330 -66
- package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
- package/_bundled_plugin/scripts/workbench_validation.py +44 -12
- package/_bundled_plugin/shared/workbench-history-repairs.json +19 -16
- package/_bundled_plugin/shared/workbench-migrations.json +53 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
- package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
- package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/cloud-findings/SKILL.md +6 -4
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
- package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -2
- package/_bundled_plugin/skills/publish-findings/SKILL.md +81 -45
- package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
- package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +5 -24
- package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
- package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +36 -9
- package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
- package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +12 -6
- package/dist/api.d.ts +45 -5
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +1144 -411
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +10 -7
- package/dist/auth.js.map +1 -1
- 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 +8 -0
- package/dist/blackduck-findings.d.ts.map +1 -0
- package/dist/blackduck-findings.js +320 -0
- package/dist/blackduck-findings.js.map +1 -0
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +51 -36
- package/dist/bulk-scan-discovery.js.map +1 -1
- 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-severity-records.d.ts +6 -9
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +9 -21
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts +4 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +30 -13
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli.d.ts +14 -5
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +2112 -1266
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.js +2 -2
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codex-prompt.d.ts +2 -0
- package/dist/codex-prompt.d.ts.map +1 -1
- package/dist/codex-prompt.js +6 -0
- package/dist/codex-prompt.js.map +1 -1
- package/dist/component-scan.d.ts +16 -3
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +32 -6
- package/dist/component-scan.js.map +1 -1
- package/dist/config.d.ts +2 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +221 -65
- package/dist/config.js.map +1 -1
- package/dist/continuum-findings.d.ts +7 -0
- package/dist/continuum-findings.d.ts.map +1 -0
- package/dist/continuum-findings.js +225 -0
- package/dist/continuum-findings.js.map +1 -0
- package/dist/contract-values.d.ts +30 -0
- package/dist/contract-values.d.ts.map +1 -0
- package/dist/contract-values.js +78 -0
- package/dist/contract-values.js.map +1 -0
- package/dist/contract.d.ts +2 -20
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +58 -669
- package/dist/contract.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 -115
- package/dist/cost-model.js.map +1 -1
- package/dist/cost.d.ts +61 -4
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +2560 -100
- 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 +5 -0
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/custom-validation.d.ts +2 -0
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +4 -0
- package/dist/custom-validation.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +4 -4
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +2 -2
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
- package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
- package/dist/deduplication/deduplication-reviewer.js +11 -4
- package/dist/deduplication/deduplication-reviewer.js.map +1 -1
- package/dist/deduplication/deduplication.js.map +1 -1
- package/dist/deduplication/finding-schema.d.ts +19 -1
- package/dist/deduplication/finding-schema.d.ts.map +1 -1
- package/dist/deduplication/finding-schema.js +25 -0
- package/dist/deduplication/finding-schema.js.map +1 -1
- package/dist/deduplication/local.d.ts +2 -2
- package/dist/deduplication/local.d.ts.map +1 -1
- package/dist/deduplication/local.js +5 -10
- package/dist/deduplication/local.js.map +1 -1
- package/dist/deduplication/records.d.ts +8 -2
- package/dist/deduplication/records.d.ts.map +1 -1
- package/dist/deduplication/records.js +36 -8
- package/dist/deduplication/records.js.map +1 -1
- package/dist/deduplication/refusal.d.ts.map +1 -1
- package/dist/deduplication/refusal.js +25 -5
- package/dist/deduplication/refusal.js.map +1 -1
- package/dist/deduplication/scan.d.ts +3 -0
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +1 -1
- 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 +13 -0
- package/dist/deep-scan.d.ts.map +1 -1
- package/dist/deep-scan.js +262 -7
- package/dist/deep-scan.js.map +1 -1
- package/dist/default-severity-rubric.d.ts +1 -2
- package/dist/default-severity-rubric.d.ts.map +1 -1
- package/dist/default-severity-rubric.js +2 -66
- 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 +108 -80
- package/dist/endor-findings.js.map +1 -1
- package/dist/errors.d.ts +1 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +9 -2
- package/dist/errors.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 +11 -16
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts +15 -4
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +619 -225
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +20 -6
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +2356 -308
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +28 -2
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +174 -81
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +17 -3
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js +153 -1
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +33 -1
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +335 -51
- 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/finding-retrieval.d.ts +3 -3
- package/dist/finding-retrieval.d.ts.map +1 -1
- package/dist/finding-retrieval.js.map +1 -1
- package/dist/finding-workflow.d.ts +6 -1
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +2 -2
- package/dist/finding-workflow.js.map +1 -1
- 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/git-remote.d.ts +4 -0
- package/dist/git-remote.d.ts.map +1 -1
- package/dist/git-remote.js +20 -0
- package/dist/git-remote.js.map +1 -1
- package/dist/github-advisories.d.ts +3 -12
- package/dist/github-advisories.d.ts.map +1 -1
- package/dist/github-advisories.js +9 -31
- package/dist/github-advisories.js.map +1 -1
- package/dist/github-dependabot-findings.d.ts.map +1 -1
- package/dist/github-dependabot-findings.js +22 -20
- 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 +392 -79
- package/dist/github-findings.js.map +1 -1
- package/dist/github.d.ts +17 -7
- package/dist/github.d.ts.map +1 -1
- package/dist/github.js +43 -30
- package/dist/github.js.map +1 -1
- package/dist/host-protocol.d.ts +2 -2
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/host-records-protocol.d.ts +10 -11
- package/dist/host-records-protocol.d.ts.map +1 -1
- package/dist/host-records-protocol.js +69 -9
- package/dist/host-records-protocol.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-scan-protocol.js +2 -2
- package/dist/hosted-scan-protocol.js.map +1 -1
- package/dist/hosted-scan.d.ts +15 -0
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +71 -44
- 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/hosted-scanner-v1.d.ts +6 -0
- package/dist/hosted-scanner-v1.d.ts.map +1 -0
- package/dist/hosted-scanner-v1.js +60 -0
- package/dist/hosted-scanner-v1.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 +24 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +15 -1
- package/dist/index.js.map +1 -1
- package/dist/inspector-findings.d.ts.map +1 -1
- package/dist/inspector-findings.js +58 -81
- package/dist/inspector-findings.js.map +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +86 -10
- package/dist/knowledge-base.js.map +1 -1
- package/dist/local-git-metadata.d.ts +5 -0
- package/dist/local-git-metadata.d.ts.map +1 -0
- package/dist/local-git-metadata.js +130 -0
- package/dist/local-git-metadata.js.map +1 -0
- package/dist/multiscan.d.ts +6 -4
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +160 -77
- 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 +1 -0
- package/dist/opengrep-findings.d.ts.map +1 -1
- package/dist/opengrep-findings.js +49 -31
- 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/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js +90 -35
- package/dist/patch-tui.js.map +1 -1
- 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 +341 -0
- package/dist/private-finding-import.d.ts.map +1 -0
- package/dist/private-finding-import.js +411 -0
- package/dist/private-finding-import.js.map +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +2 -2
- package/dist/project-config.js.map +1 -1
- package/dist/provider-profile.d.ts +11 -3
- package/dist/provider-profile.d.ts.map +1 -1
- package/dist/provider-profile.js +80 -11
- 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.js +7 -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/reader-selection.d.ts +15 -0
- package/dist/reader-selection.d.ts.map +1 -0
- package/dist/reader-selection.js +89 -0
- package/dist/reader-selection.js.map +1 -0
- package/dist/record.d.ts +6 -1
- package/dist/record.d.ts.map +1 -1
- package/dist/record.js +53 -2
- package/dist/record.js.map +1 -1
- package/dist/remediation.d.ts +3 -1
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +28 -2
- 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 +6 -0
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +3 -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 +22 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +408 -162
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan-bootstrap.d.ts +1 -0
- package/dist/saved-scan-bootstrap.d.ts.map +1 -1
- package/dist/saved-scan-bootstrap.js +18 -15
- package/dist/saved-scan-bootstrap.js.map +1 -1
- package/dist/scan-activity.d.ts.map +1 -1
- package/dist/scan-activity.js +172 -64
- package/dist/scan-activity.js.map +1 -1
- package/dist/scan-comparison.d.ts +10 -5
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +68 -25
- 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 +91 -79
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-executor.d.ts +12 -1
- package/dist/scan-executor.d.ts.map +1 -1
- package/dist/scan-executor.js +22 -2
- package/dist/scan-executor.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +31 -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 +106 -77
- 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 +64 -6
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +406 -48
- package/dist/scanner-import.js.map +1 -1
- package/dist/scanner-repository-url.d.ts +17 -0
- package/dist/scanner-repository-url.d.ts.map +1 -0
- package/dist/scanner-repository-url.js +71 -0
- package/dist/scanner-repository-url.js.map +1 -0
- package/dist/security-policy.d.ts +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- 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 +124 -88
- 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 +213 -0
- package/dist/semgrep-platform-findings.d.ts.map +1 -0
- package/dist/semgrep-platform-findings.js +1078 -0
- package/dist/semgrep-platform-findings.js.map +1 -0
- package/dist/semgrep-platform-v1.d.ts +6 -0
- package/dist/semgrep-platform-v1.d.ts.map +1 -0
- package/dist/semgrep-platform-v1.js +83 -0
- package/dist/semgrep-platform-v1.js.map +1 -0
- 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/severity-rubric.d.ts +20 -0
- package/dist/severity-rubric.d.ts.map +1 -0
- package/dist/severity-rubric.js +73 -0
- package/dist/severity-rubric.js.map +1 -0
- package/dist/severity-store.js +15 -5
- package/dist/severity-store.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 +7 -2
- package/dist/snyk-findings.d.ts.map +1 -1
- package/dist/snyk-findings.js +108 -84
- package/dist/snyk-findings.js.map +1 -1
- package/dist/snyk-rest-findings.d.ts +76 -0
- package/dist/snyk-rest-findings.d.ts.map +1 -0
- package/dist/snyk-rest-findings.js +1051 -0
- package/dist/snyk-rest-findings.js.map +1 -0
- package/dist/snyk-rest-v1.d.ts +28 -0
- package/dist/snyk-rest-v1.d.ts.map +1 -0
- package/dist/snyk-rest-v1.js +132 -0
- package/dist/snyk-rest-v1.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 +16 -0
- package/dist/sonar-collector.d.ts.map +1 -0
- package/dist/sonar-collector.js +380 -0
- package/dist/sonar-collector.js.map +1 -0
- package/dist/sonar-findings.d.ts +49 -0
- package/dist/sonar-findings.d.ts.map +1 -0
- package/dist/sonar-findings.js +288 -0
- package/dist/sonar-findings.js.map +1 -0
- package/dist/sonar-import.d.ts +111 -0
- package/dist/sonar-import.d.ts.map +1 -0
- package/dist/sonar-import.js +277 -0
- package/dist/sonar-import.js.map +1 -0
- package/dist/suggest-owners.d.ts.map +1 -1
- package/dist/suggest-owners.js +2 -1
- package/dist/suggest-owners.js.map +1 -1
- 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 +5 -0
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +73 -31
- package/dist/targets.js.map +1 -1
- package/dist/tenable-findings.d.ts +9 -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-columns.d.ts +4 -0
- package/dist/terminal-columns.d.ts.map +1 -0
- package/dist/terminal-columns.js +19 -0
- package/dist/terminal-columns.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 +435 -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/validation-records.d.ts +0 -3
- package/dist/validation-records.d.ts.map +1 -1
- package/dist/validation-records.js +1 -17
- package/dist/validation-records.js.map +1 -1
- package/dist/veracode-findings.d.ts +9 -0
- package/dist/veracode-findings.d.ts.map +1 -0
- package/dist/veracode-findings.js +409 -0
- package/dist/veracode-findings.js.map +1 -0
- 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 +27 -1
- package/dist/windows-path.js.map +1 -1
- package/dist/wiz-csv.d.ts +2 -2
- package/dist/wiz-csv.d.ts.map +1 -1
- package/dist/wiz-csv.js +1 -3
- package/dist/wiz-csv.js.map +1 -1
- package/dist/wiz-findings.d.ts +14 -2
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +143 -50
- package/dist/wiz-findings.js.map +1 -1
- package/docs/classify-severity-records.md +28 -13
- package/docs/cli.md +623 -843
- package/docs/dedupe-records.md +54 -24
- package/docs/findings-service.md +87 -47
- package/docs/hosted-remediation.md +14 -7
- package/docs/hosted-scans.md +64 -41
- package/docs/telemetry.md +236 -0
- package/docs/validate-records.md +78 -44
- package/package.json +19 -17
- package/schemas/external-findings.schema.json +14 -1
- package/schemas/hosted-scan-v2.fixture.json +16 -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/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
- package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
- package/dist/deduplication/records-protocol.d.ts +0 -4
- package/dist/deduplication/records-protocol.d.ts.map +0 -1
- package/dist/deduplication/records-protocol.js +0 -49
- package/dist/deduplication/records-protocol.js.map +0 -1
- 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 -120
- package/dist/finding-normalization.js.map +0 -1
package/docs/cli.md
CHANGED
|
@@ -16,13 +16,6 @@ codex-security info --json
|
|
|
16
16
|
`info --json` reports package, plugin, runtime, and model details.
|
|
17
17
|
`scans` and `findings` default to their `list` subcommands.
|
|
18
18
|
|
|
19
|
-
To retrieve GitHub code scanning alerts without an MCP server, use
|
|
20
|
-
[`import github`](#import-alerts-from-the-cli). To save an existing CSV or JSON
|
|
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.
|
|
25
|
-
|
|
26
19
|
## Find a workflow
|
|
27
20
|
|
|
28
21
|
- [Sign in or configure a provider](#authentication).
|
|
@@ -31,9 +24,8 @@ without running security analysis.
|
|
|
31
24
|
[save project settings](#project-files).
|
|
32
25
|
- [Review one system across repositories](#review-one-system-across-repositories)
|
|
33
26
|
or [run independent bulk scans](#bulk-scans).
|
|
34
|
-
- [
|
|
35
|
-
|
|
36
|
-
[retrieve GitHub alerts](#import-alerts-from-the-cli).
|
|
27
|
+
- [Choose an import command](#import-vendor-findings-locally) to save a scan,
|
|
28
|
+
collect upstream alerts, or store vendor evidence locally or in Cloud.
|
|
37
29
|
- [Inspect saved scans and rerun them](#scan-history-and-reruns),
|
|
38
30
|
[classify severity](#classify-finding-severity), or
|
|
39
31
|
[suggest owners](#suggest-finding-owners).
|
|
@@ -86,7 +78,9 @@ your local browser. Keep SSH connected until login finishes.
|
|
|
86
78
|
### OpenAI credentials
|
|
87
79
|
|
|
88
80
|
Interactive scans ask which credentials to use when both ChatGPT and an
|
|
89
|
-
environment API key are available.
|
|
81
|
+
environment API key are available. A dedicated sign-in takes precedence. After
|
|
82
|
+
`codex-security logout`, the prompt skips the ambient sign-in until you log in
|
|
83
|
+
again. Noninteractive commands prefer
|
|
90
84
|
`OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
|
|
91
85
|
with `--auth`:
|
|
92
86
|
|
|
@@ -103,12 +97,25 @@ the stored login. Patch follow-up assessments and `scan --patch` retain the
|
|
|
103
97
|
chosen authentication. Environment keys do not replace the saved login.
|
|
104
98
|
The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
|
|
105
99
|
|
|
100
|
+
For a scan using a custom native provider, `auto` and `api-key` use the
|
|
101
|
+
environment variable declared by `model_providers.<id>.env_key`, including
|
|
102
|
+
when a Codex file profile selects that provider. Set that variable before
|
|
103
|
+
starting the scan. To use `--auth chatgpt`, select a provider configured for
|
|
104
|
+
account authentication. A custom provider that requires its own key cannot
|
|
105
|
+
honor that combination.
|
|
106
|
+
|
|
106
107
|
Stored OpenAI credentials live in
|
|
107
108
|
`$CODEX_SECURITY_STATE_DIR/codex-home`, or
|
|
108
109
|
`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
|
|
109
110
|
outside the target and every enclosing Git worktree. It also serves providers
|
|
110
111
|
with `requires_openai_auth = true`.
|
|
111
112
|
|
|
113
|
+
If you manually hard-linked the two homes’ `auth.json` files, keep both homes
|
|
114
|
+
accessible when running `codex-security logout`. When the CLI verifies the
|
|
115
|
+
two hard links, it removes the private link before invoking native logout.
|
|
116
|
+
If the ambient home is unavailable, the configured credential store handles
|
|
117
|
+
logout normally.
|
|
118
|
+
|
|
112
119
|
Codex carries credential-storage, forced-login, and workspace settings from the
|
|
113
120
|
ambient configuration into this home. Managed-device policies still apply;
|
|
114
121
|
workspace-managed policies may require ChatGPT credentials even with an API key.
|
|
@@ -122,8 +129,19 @@ after logout completes.
|
|
|
122
129
|
Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
|
|
123
130
|
`HOME` or `USERPROFILE` environment setting.
|
|
124
131
|
|
|
125
|
-
If
|
|
126
|
-
|
|
132
|
+
If you use file-based ChatGPT credentials with both Codex and Codex Security,
|
|
133
|
+
run `codex-security login` before your first scan or status check to give Codex
|
|
134
|
+
Security its own session. An imported sign-in shares a single-use refresh token.
|
|
135
|
+
When either client renews it, the other client's next refresh can fail even
|
|
136
|
+
while its login status reports that it is signed in.
|
|
137
|
+
|
|
138
|
+
If Codex Security reports that the refresh token was already used, run
|
|
139
|
+
`codex-security logout`, then `codex-security login`. If your Codex CLI or app
|
|
140
|
+
reports that error, sign out and sign back in there.
|
|
141
|
+
|
|
142
|
+
For other refresh errors, check `codex-security login status`. Retry if the
|
|
143
|
+
sign-in recently changed. Otherwise run `codex-security logout`, then
|
|
144
|
+
`codex-security login`.
|
|
127
145
|
Some cybersecurity requests and protected findings require
|
|
128
146
|
[Trusted Access for Cyber](https://chatgpt.com/cyber).
|
|
129
147
|
|
|
@@ -141,7 +159,7 @@ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
|
|
|
141
159
|
In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
|
|
142
160
|
to explicitly turn it off.
|
|
143
161
|
The setting carries through saved scan recipes, resumed scans, Deep Scan
|
|
144
|
-
discovery
|
|
162
|
+
discovery workers, and `scan --patch`. Standalone `validate`,
|
|
145
163
|
`patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
|
|
146
164
|
Threads created by these commands retain the setting when resumed in Codex.
|
|
147
165
|
Scans use isolated configuration, so set it on the CLI, SDK client, or project
|
|
@@ -151,8 +169,7 @@ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
|
|
|
151
169
|
an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
|
|
152
170
|
or set top-level `daybreak = true` in the configuration loaded by the runner.
|
|
153
171
|
Deep Scan inherits the active turn's effective access program from its saved
|
|
154
|
-
Codex session, including an explicit Standard selection. Discovery
|
|
155
|
-
workers retain that selection when resumed. If the host does not supply a
|
|
172
|
+
Codex session, including an explicit Standard selection. Discovery workers retain that selection when resumed. If the host does not supply a
|
|
156
173
|
persisted turn context, workers use their runner configuration; CLI and SDK scans
|
|
157
174
|
use the explicit scan settings above.
|
|
158
175
|
|
|
@@ -169,7 +186,8 @@ and project have access. An omitted `access_programs.cyber` field does not by
|
|
|
169
186
|
itself mean that Daybreak treatment is disabled.
|
|
170
187
|
|
|
171
188
|
Choose a compatible model available to your project and select Daybreak Blue
|
|
172
|
-
explicitly
|
|
189
|
+
explicitly. If you use `--max-cost` or the SDK's `maxCostUsd`, choose a model
|
|
190
|
+
with built-in pricing so the scan can enforce the limit.
|
|
173
191
|
|
|
174
192
|
```bash
|
|
175
193
|
codex-security scan /path/to/repository \
|
|
@@ -179,14 +197,11 @@ codex-security scan /path/to/repository \
|
|
|
179
197
|
In the SDK, select your model through `codexOverrides.model` and pass
|
|
180
198
|
`auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
|
|
181
199
|
Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
|
|
182
|
-
The selection reaches discovery
|
|
200
|
+
The selection reaches discovery workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
|
|
183
201
|
for configuration precedence and the API-key feature setting.
|
|
184
202
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
Use a current model available to your project. `access_programs.cyber` is a
|
|
188
|
-
Responses API field; use the supported selector instead of passing it as a
|
|
189
|
-
`--codex` configuration key.
|
|
203
|
+
`access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
|
|
204
|
+
instead of passing it as a `--codex` configuration key.
|
|
190
205
|
|
|
191
206
|
### Select a Cyber access program
|
|
192
207
|
|
|
@@ -237,6 +252,15 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
|
|
|
237
252
|
codex-security scan . --provider cheaperinference --model gpt-5.4
|
|
238
253
|
```
|
|
239
254
|
|
|
255
|
+
### Hugging Face compatibility
|
|
256
|
+
|
|
257
|
+
In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
|
|
258
|
+
`namespace` and could request `web_search`. Hugging Face's published Responses
|
|
259
|
+
implementation accepts `function` and remote `mcp` tool declarations. A named
|
|
260
|
+
Hugging Face scan provider is deferred until the scanner and router can exchange
|
|
261
|
+
the tools a complete scan requires. [Hugging Face's implementation notes](https://huggingface.co/docs/inference-providers/en/guides/gpt-oss#responses-api)
|
|
262
|
+
and [request schema](https://github.com/huggingface/responses.js/blob/0e3e84c469a9f59ad16e2eb3a0d6f1c4de637a7b/src/schemas.ts#L219-L232).
|
|
263
|
+
|
|
240
264
|
### Amazon Bedrock
|
|
241
265
|
|
|
242
266
|
Use AWS credentials and a region with access to the exact Bedrock model ID:
|
|
@@ -256,6 +280,45 @@ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/
|
|
|
256
280
|
for credential alternatives, restricted-model access, cost estimates, and
|
|
257
281
|
reasoning-summary configuration.
|
|
258
282
|
|
|
283
|
+
### Google Cloud Vertex AI cost estimates
|
|
284
|
+
|
|
285
|
+
The SDK estimates Standard online inference costs for OpenAI models served by
|
|
286
|
+
Google Cloud's Model as a Service (MaaS). Rates are in USD per million tokens.
|
|
287
|
+
[Google Cloud partner model pricing](https://cloud.google.com/model-garden/partner-models/pricing)
|
|
288
|
+
and [OpenAI model locations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/maas/openai).
|
|
289
|
+
|
|
290
|
+
| Managed model ID | Location | Input | Cached input | Output |
|
|
291
|
+
| -------------------------- | ----------------------- | ----: | -----------: | -----: |
|
|
292
|
+
| `openai/gpt-oss-120b-maas` | `global` | $0.09 | $0.09 | $0.36 |
|
|
293
|
+
| `openai/gpt-oss-20b-maas` | `us-central1` (retired) | $0.07 | $0.007 | $0.25 |
|
|
294
|
+
|
|
295
|
+
Google publishes a cache-hit discount only for 20B, so the estimator uses the
|
|
296
|
+
ordinary input rate for cached 120B tokens. Google retired the managed 20B
|
|
297
|
+
endpoint on October 21, 2026. The SDK retains its rates for historical usage.
|
|
298
|
+
[Google Cloud retirement schedule](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/open-models).
|
|
299
|
+
|
|
300
|
+
To estimate recorded usage locally, pass the managed model ID and the GCP
|
|
301
|
+
provider to `estimateScanCost`.
|
|
302
|
+
|
|
303
|
+
```ts
|
|
304
|
+
import { estimateScanCost } from "@openai/codex-security";
|
|
305
|
+
|
|
306
|
+
const cost = estimateScanCost(
|
|
307
|
+
"openai/gpt-oss-120b-maas",
|
|
308
|
+
{ input_tokens: 1_000_000, output_tokens: 500_000 },
|
|
309
|
+
{ provider: "gcp" },
|
|
310
|
+
);
|
|
311
|
+
// cost?.estimatedUsd is 0.27.
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Google documents the managed GPT OSS IDs on its shared chat-completions API.
|
|
315
|
+
The bundled Codex `gcp` provider uses Google's Responses API with a separate
|
|
316
|
+
frontier model catalog. Google has published no Standard token rates for that
|
|
317
|
+
catalog, including GPT-6 Astra, GPT-6.1 Sol, GPT-6.1 Terra, and GPT-6 Luna.
|
|
318
|
+
Those scans record token usage and require a published price to use
|
|
319
|
+
`--max-cost`. Self-deployed Model Garden endpoints incur infrastructure charges.
|
|
320
|
+
[Google Cloud's preview announcement](https://cloud.google.com/blog/products/ai-machine-learning/google-cloud-brings-openai-models-to-customers).
|
|
321
|
+
|
|
259
322
|
## Generate a security policy
|
|
260
323
|
|
|
261
324
|
Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
|
|
@@ -431,6 +494,10 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
|
|
|
431
494
|
requested work separately from optional `coverage.openQuestions` follow-up.
|
|
432
495
|
Human-readable output quotes ambiguous paths, while JSON retains their original strings.
|
|
433
496
|
|
|
497
|
+
When a cost limit is configured, `scan --dry-run` shows the resolved
|
|
498
|
+
`maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
|
|
499
|
+
against the limit and why in-flight requests can exceed it.
|
|
500
|
+
|
|
434
501
|
Whole-codebase and path scans also accept ordinary directories, including SVN
|
|
435
502
|
working copies. Their source inventories exclude `.git` and `.svn` metadata.
|
|
436
503
|
|
|
@@ -461,10 +528,17 @@ with every repository.
|
|
|
461
528
|
|
|
462
529
|
Use `--output-dir DIR` to choose where a scan saves its results. The directory
|
|
463
530
|
must be empty and outside the scanned directory and enclosing Git worktree.
|
|
464
|
-
Existing directories keep their permissions
|
|
465
|
-
private to you by default.
|
|
466
|
-
|
|
467
|
-
|
|
531
|
+
Existing directories keep their permissions. Newly created directories are
|
|
532
|
+
private to you by default. On Windows, the directory and its parents must be
|
|
533
|
+
owned by your account, Administrators, SYSTEM, or TrustedInstaller. Choose a
|
|
534
|
+
path where another user cannot replace the output directory or one of its
|
|
535
|
+
parents. A parent can allow other users to read it or create sibling directories.
|
|
536
|
+
For an empty write destination, grant content-writing permissions to children
|
|
537
|
+
through inheritance. Other users must not have permission to set reparse data
|
|
538
|
+
on the destination directory itself.
|
|
539
|
+
`--archive-existing` moves earlier output to a sibling directory with a unique
|
|
540
|
+
suffix, such as `results.previous-ab12cd34` for an output directory named
|
|
541
|
+
`results`. Use `--dry-run` to preview the move.
|
|
468
542
|
|
|
469
543
|
Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
|
|
470
544
|
optional export fails, the scan can still complete. Use the
|
|
@@ -504,7 +578,9 @@ or JSONL output produce:
|
|
|
504
578
|
{ "status": "failed", "code": "SCAN_FAILED", "message": "..." }
|
|
505
579
|
```
|
|
506
580
|
|
|
507
|
-
With `--full-output`, the error
|
|
581
|
+
With `--full-output`, JSON and JSONL failures put the error under `error` in an
|
|
582
|
+
`ok: false` envelope. YAML and TOON use the same failed envelope when retained
|
|
583
|
+
sealed scan results are available (including TOON selected by default).
|
|
508
584
|
If the scan target changed, the error explains that the results no longer
|
|
509
585
|
represent the current checkout. Retained sealed results remain available under
|
|
510
586
|
`data`, including their manifest, findings, review summary, scan directory, and report
|
|
@@ -516,8 +592,8 @@ selecting an unavailable field can return `null` or omit `data`.
|
|
|
516
592
|
Saved-scan setup failures use the same output shape with
|
|
517
593
|
`SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
|
|
518
594
|
available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
|
|
519
|
-
scan uses `SCAN_IMPORT_FAILED` if the import fails.
|
|
520
|
-
stderr
|
|
595
|
+
scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
|
|
596
|
+
on stderr without `--full-output`, or when retained results are unavailable.
|
|
521
597
|
|
|
522
598
|
Diagnostics stay on stderr. Each command's `--schema --format json` describes
|
|
523
599
|
its successful output and failure codes.
|
|
@@ -527,8 +603,9 @@ See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
|
527
603
|
|
|
528
604
|
Scans already validate findings against local source. Add `--validate` to run
|
|
529
605
|
the existing standalone validation workflow for each reported finding after
|
|
530
|
-
the scan, using the same selected Cyber access program. Validation
|
|
531
|
-
|
|
606
|
+
the scan, using the same selected Cyber access program. Validation sends each
|
|
607
|
+
finding to the configured model provider. Its review tools have read-only
|
|
608
|
+
filesystem access, with network access and web search disabled. Each assessment uses a
|
|
532
609
|
separate evidence directory; the combined report is saved as
|
|
533
610
|
`<scan-dir>/validation.md`, or a uniquely suffixed report
|
|
534
611
|
if that path already exists. Each completed assessment is saved immediately;
|
|
@@ -572,26 +649,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
|
|
|
572
649
|
fail after registration but before writing its artifacts; investigate those
|
|
573
650
|
failures through its history record and any available logs. When artifacts were
|
|
574
651
|
retained, use the saved results directory returned by `scans show` to inspect
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
| File | What to check
|
|
578
|
-
| -------------------- |
|
|
579
|
-
| `scan-manifest.json` | `scan.status
|
|
580
|
-
| `
|
|
581
|
-
| `
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
`
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
proving that each file was reviewed. An absent path in a surface summary does not
|
|
591
|
-
establish whether it was read, and the scan ID cannot reconstruct evidence that
|
|
592
|
-
was never saved.
|
|
593
|
-
Session logs can help explain failures and tool activity, but do not prove
|
|
594
|
-
complete review either.
|
|
652
|
+
the saved files:
|
|
653
|
+
|
|
654
|
+
| File | What to check |
|
|
655
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
656
|
+
| `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. |
|
|
657
|
+
| `findings.json` | Reported findings, source locations and supporting evidence. |
|
|
658
|
+
| `report.md` | A readable summary of the scope and findings. |
|
|
659
|
+
|
|
660
|
+
When a checkpoint is retained, `checkpoint-head.json` identifies the file in
|
|
661
|
+
`checkpoints/`. In a retained draft or checkpoint, `reviewState.deferred` lists
|
|
662
|
+
unfinished work and `reviewState.openQuestions` lists follow-up questions.
|
|
663
|
+
Older manifests with `scan.coverageRef` point to a separate `coverage.json`
|
|
664
|
+
with reviewed surfaces, explicit exclusions and deferred work. A saved source
|
|
665
|
+
inventory identifies inputs. Neither that inventory nor session logs establish
|
|
666
|
+
which files the scan reviewed in full.
|
|
595
667
|
|
|
596
668
|
For a local plugin scan, ask Codex to open the saved scan and explain its scope,
|
|
597
669
|
exclusions, deferred work, and follow-up questions. CLI history can also locate
|
|
@@ -635,15 +707,19 @@ completeness values to determine scan status or exit codes.
|
|
|
635
707
|
|
|
636
708
|
```bash
|
|
637
709
|
codex-security init
|
|
638
|
-
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
639
710
|
codex-security info -c codex-security.yaml --json
|
|
711
|
+
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
640
712
|
```
|
|
641
713
|
|
|
642
714
|
Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
|
|
643
|
-
|
|
715
|
+
Keep `-c` on both `info` and the scan preview to inspect the same target and
|
|
716
|
+
limits. Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
|
|
644
717
|
`scan-components`, and `info` accept project files. SDK calls and saved reruns
|
|
645
718
|
do not load them automatically.
|
|
646
719
|
|
|
720
|
+
JSON project files and component plans (`--components-file`) accept UTF-8 with
|
|
721
|
+
or without a leading byte-order mark.
|
|
722
|
+
|
|
647
723
|
Treat the selected file as trusted operator configuration: native settings can
|
|
648
724
|
start MCP processes and choose model-service destinations. Keep CI scanner
|
|
649
725
|
configuration outside the untrusted checkout being assessed.
|
|
@@ -691,7 +767,8 @@ runs, four with new identities, and two duplicate pairs for testing deduplicatio
|
|
|
691
767
|
Paths and snippets are fictional; repository files remain unchanged.
|
|
692
768
|
|
|
693
769
|
Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
|
|
694
|
-
archiving, and severity thresholds work normally.
|
|
770
|
+
archiving, and severity thresholds work normally. Use `scans show` to inspect a
|
|
771
|
+
mock scan. Mock scans have no Codex session logs. Reruns preserve mock mode.
|
|
695
772
|
Separate matching or deduplication commands still make their usual model calls.
|
|
696
773
|
|
|
697
774
|
Mock mode supports Standard repository, path, and diff scans. It cannot combine
|
|
@@ -770,7 +847,8 @@ individual scan folder.
|
|
|
770
847
|
Failures do not stop other components. Failed scans or
|
|
771
848
|
failed matching return `2`; severity-policy violations return `1`. Retry with
|
|
772
849
|
`--components-file retry-components.json` and a new empty output directory.
|
|
773
|
-
The retry report covers only those components.
|
|
850
|
+
The retry report covers only those components. Each registered component keeps its
|
|
851
|
+
scan ID in the summary, including when the scan fails.
|
|
774
852
|
|
|
775
853
|
`--max-cost` applies per component, excluding planning and matching. `--model`
|
|
776
854
|
and `--effort` also apply to matching; `--auth` applies throughout. Planning and
|
|
@@ -782,6 +860,28 @@ Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
|
|
|
782
860
|
planning and authentication choices. Custom `createSecurity` clients receive
|
|
783
861
|
absolute targets; saved plans and component receipts retain relative paths.
|
|
784
862
|
|
|
863
|
+
### Choose a severity rubric
|
|
864
|
+
|
|
865
|
+
Standalone Standard and Deep scans grade findings with the bundled rubric by
|
|
866
|
+
default. Set `CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1` to fetch the
|
|
867
|
+
current default from Statsig once when starting a scan. If that lookup fails,
|
|
868
|
+
the scan uses the bundled rubric.
|
|
869
|
+
|
|
870
|
+
```bash
|
|
871
|
+
CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1 codex-security scan .
|
|
872
|
+
codex-security scan . --mode deep --rubric ./severity.md
|
|
873
|
+
```
|
|
874
|
+
|
|
875
|
+
An explicit Markdown file takes precedence and skips the lookup, even when
|
|
876
|
+
opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
|
|
877
|
+
`markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
|
|
878
|
+
Markdown. A supplied snapshot takes precedence over a file.
|
|
879
|
+
|
|
880
|
+
The scan saves the rubric text in its local launch recipe. Retrying a Standard
|
|
881
|
+
scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
|
|
882
|
+
with a saved rubric reuses that copy even if the remote default or file changes.
|
|
883
|
+
Older scans without a saved rubric continue to resume using their existing workflow.
|
|
884
|
+
|
|
785
885
|
### Set investigation time
|
|
786
886
|
|
|
787
887
|
```bash
|
|
@@ -812,11 +912,18 @@ codex-security scan . --mode deep --workers 2 --subagents 0 \
|
|
|
812
912
|
--stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
|
|
813
913
|
```
|
|
814
914
|
|
|
815
|
-
|
|
816
|
-
`--subagents`
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
915
|
+
Deep Scan repeats Standard scans in batches of up to `--workers`, with
|
|
916
|
+
`--subagents` per scan. Workers can share what they are investigating, ask each
|
|
917
|
+
other to check a source location, and reply while their audits are running. Each
|
|
918
|
+
worker verifies the evidence it reports. Deep Scan merges each completed batch in launch order.
|
|
919
|
+
It uses source locations, cited code and weakness descriptions to match repeated
|
|
920
|
+
findings. Each group keeps its first description, all reported locations, and
|
|
921
|
+
the original observations. Later batches receive the titles and primary
|
|
922
|
+
locations of retained findings so workers can investigate other reachable paths.
|
|
923
|
+
`--stop-after-no-new` counts consecutive
|
|
924
|
+
completed scans that added no findings. `--max-discovery-runs` caps the total
|
|
925
|
+
number started, including failures. `--max-time` stops discovery and returns
|
|
926
|
+
the findings from completed scans.
|
|
820
927
|
|
|
821
928
|
For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
|
|
822
929
|
|
|
@@ -826,6 +933,8 @@ that `subagents` can be zero. Discovery time accepts positive fractional minutes
|
|
|
826
933
|
its default and maximum are 5760 minutes (96 hours). Unlike Standard's
|
|
827
934
|
advisory allowance, the Deep discovery limit is enforced. Resuming a
|
|
828
935
|
Deep scan keeps its original deadline; rerunning starts a new scan.
|
|
936
|
+
If the deadline expires before any source review completes, the saved report
|
|
937
|
+
and scan manifest record that limitation.
|
|
829
938
|
`--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
|
|
830
939
|
legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
|
|
831
940
|
hours. Explicit settings override lower-priority configuration across units.
|
|
@@ -874,9 +983,28 @@ executable outside all saved scan targets. If a historical target includes the
|
|
|
874
983
|
available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
|
|
875
984
|
explicit saved scan ID. Exact-path `latest` lookup still works without Git.
|
|
876
985
|
|
|
877
|
-
Repeat `--codex KEY=VALUE` for supported native settings.
|
|
878
|
-
`--codex
|
|
879
|
-
|
|
986
|
+
Repeat `--codex KEY=VALUE` for supported native settings. For example,
|
|
987
|
+
`--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
|
|
988
|
+
Command Prompt, and PowerShell. Repeated or conflicting keys are rejected,
|
|
989
|
+
including a `--model` or `--effort` flag plus its native equivalent.
|
|
990
|
+
|
|
991
|
+
To select a Codex file profile, put its settings in
|
|
992
|
+
`$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
|
|
993
|
+
`CODEX_HOME` is unset), then run:
|
|
994
|
+
|
|
995
|
+
```bash
|
|
996
|
+
npx @openai/codex-security scan . --codex "profile='review'"
|
|
997
|
+
```
|
|
998
|
+
|
|
999
|
+
In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
|
|
1000
|
+
set `codex.profile: review`. The profile file uses top-level Codex TOML keys.
|
|
1001
|
+
Its settings override scanner defaults. Explicit scan settings take precedence.
|
|
1002
|
+
Relative file paths, including `model_instructions_file`, resolve from the
|
|
1003
|
+
profile directory. Saved launches retain the profile name and reload its settings.
|
|
1004
|
+
Include custom provider definitions in the file so the scan
|
|
1005
|
+
can use them from its isolated Codex home. An absent file contributes no
|
|
1006
|
+
settings. Existing inline `profiles` tables still work.
|
|
1007
|
+
|
|
880
1008
|
Choose plugins with `--plugin-path`; native plugin and marketplace overrides are
|
|
881
1009
|
rejected. New and resumed Deep Scans require the current plugin's direct engine,
|
|
882
1010
|
worker provider snapshot, and isolated worker configuration capabilities. Update
|
|
@@ -891,11 +1019,11 @@ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
|
|
|
891
1019
|
|
|
892
1020
|
```bash
|
|
893
1021
|
codex-security patch "Security issue" --model gateway-model \
|
|
894
|
-
--codex
|
|
895
|
-
--codex
|
|
896
|
-
--codex
|
|
897
|
-
--codex
|
|
898
|
-
--codex
|
|
1022
|
+
--codex "model_provider='gateway'" \
|
|
1023
|
+
--codex "model_providers.gateway.name='Gateway'" \
|
|
1024
|
+
--codex "model_providers.gateway.base_url='https://gateway.example.test/v1'" \
|
|
1025
|
+
--codex "model_providers.gateway.wire_api='responses'" \
|
|
1026
|
+
--codex "model_providers.gateway.env_key='GATEWAY_API_KEY'"
|
|
899
1027
|
```
|
|
900
1028
|
|
|
901
1029
|
Set the provider's key environment variable before running. Patching and
|
|
@@ -921,12 +1049,14 @@ publication uses the same request attribution; embedding requests identify
|
|
|
921
1049
|
the package and version in their `User-Agent`.
|
|
922
1050
|
|
|
923
1051
|
These fields provide request attribution for supported inference providers, including
|
|
924
|
-
Bedrock. They do not create a separate telemetry collector
|
|
925
|
-
|
|
1052
|
+
Bedrock. They do not create a separate telemetry collector or make another
|
|
1053
|
+
provider's traffic visible to OpenAI. Local operation receipts separately record
|
|
1054
|
+
starts, outcomes, duration, and usage coverage; see
|
|
1055
|
+
[telemetry and measurement](telemetry.md).
|
|
926
1056
|
|
|
927
1057
|
Disable Codex usage analytics and built-in metrics with
|
|
928
|
-
`--codex
|
|
929
|
-
patch-risk assessment, and Deep Scan discovery
|
|
1058
|
+
`--codex analytics.enabled=false`. The setting carries into `scan --patch`,
|
|
1059
|
+
patch-risk assessment, and Deep Scan discovery workers, including
|
|
930
1060
|
resumed workers. Selected-profile settings take precedence over root settings.
|
|
931
1061
|
Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
|
|
932
1062
|
workers, including exporter choices and prompt-logging controls.
|
|
@@ -935,32 +1065,43 @@ The setting does not control configured OpenTelemetry exporters, integrations,
|
|
|
935
1065
|
authentication, or CLI update checks. Validation uses isolated configuration;
|
|
936
1066
|
patching and verification preserve ambient project trust.
|
|
937
1067
|
|
|
1068
|
+
For scan outcomes, the workbench saves a separate, local `lifecycle` record
|
|
1069
|
+
with the scan ID, launch surface, available release versions, mode, timestamps,
|
|
1070
|
+
and committed status. A completed scan indicates whether it produced reportable
|
|
1071
|
+
findings. Use `codex-security scans list --json` for the current repository.
|
|
1072
|
+
To find an offline import, use `codex-security scans list --scan-root <DIR> --json`
|
|
1073
|
+
with its output directory. Imported scans have lifecycle mode `import`. The SDK
|
|
1074
|
+
exposes `onLifecycle`, and the CLI includes observations in verbose diagnostics.
|
|
1075
|
+
Canceling a newly registered SDK scan through its abort signal, closing the
|
|
1076
|
+
client during the scan, or receiving a canceled hosted execution records
|
|
1077
|
+
`canceled`. A scan that has already completed keeps its committed outcome.
|
|
1078
|
+
Applications can choose how to collect and export these observations.
|
|
1079
|
+
|
|
938
1080
|
For filesystem and approval behavior, see the
|
|
939
1081
|
[local security model](../README.md#local-security-model).
|
|
940
1082
|
|
|
941
1083
|
### Environment variables
|
|
942
1084
|
|
|
943
|
-
| Variable | Effect
|
|
944
|
-
| --------------------------------------------------------------------------- |
|
|
945
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence.
|
|
946
|
-
| `
|
|
947
|
-
| `
|
|
948
|
-
| `
|
|
949
|
-
| `
|
|
950
|
-
| `
|
|
951
|
-
| `
|
|
952
|
-
| `
|
|
953
|
-
| `
|
|
954
|
-
| `
|
|
955
|
-
| `
|
|
956
|
-
| `
|
|
957
|
-
| `
|
|
958
|
-
| `
|
|
959
|
-
| `
|
|
960
|
-
| `
|
|
961
|
-
| `
|
|
962
|
-
| `
|
|
963
|
-
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
1085
|
+
| Variable | Effect |
|
|
1086
|
+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
1087
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
|
|
1088
|
+
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
|
|
1089
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
|
|
1090
|
+
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
|
|
1091
|
+
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
|
|
1092
|
+
| `PYTHON` | Python interpreter unless an explicit option overrides it. |
|
|
1093
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
|
|
1094
|
+
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
|
|
1095
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
|
|
1096
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
|
|
1097
|
+
| `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
|
|
1098
|
+
| `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
|
|
1099
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
|
|
1100
|
+
| `GH_HOST` | GitHub Enterprise host for bulk discovery. |
|
|
1101
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
|
|
1102
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
|
|
1103
|
+
| `CI` | Disable interactive update notices. |
|
|
1104
|
+
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
964
1105
|
|
|
965
1106
|
Custom Codex executables need thread source attribution for `exec` and
|
|
966
1107
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -974,7 +1115,8 @@ works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage
|
|
|
974
1115
|
### Troubleshooting
|
|
975
1116
|
|
|
976
1117
|
Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
|
|
977
|
-
retry, and worker diagnostics on stderr.
|
|
1118
|
+
retry, and worker diagnostics on stderr. Direct Deep Scans include coordinator events
|
|
1119
|
+
such as worker retries and duplicate-comparison failures. Diagnostic text is preserved in output,
|
|
978
1120
|
saved failures, receipts, and patch-risk summaries. Review it for sensitive
|
|
979
1121
|
information before sharing; upstream Codex output may already be redacted.
|
|
980
1122
|
|
|
@@ -983,6 +1125,21 @@ Finish older-version operations before upgrading. Never remove
|
|
|
983
1125
|
`.codex-security-scan.sqlite3` during an operation. Stop all operations using the
|
|
984
1126
|
credential home before manually removing an old `.codex-security-scan.lock`.
|
|
985
1127
|
|
|
1128
|
+
If a scan reports that its state directory overlaps a protected root, choose a
|
|
1129
|
+
private directory in a separate tree, such as a sibling of the protected root.
|
|
1130
|
+
Set `CODEX_SECURITY_STATE_DIR` for local scans or `stateDirectory` on a hosted
|
|
1131
|
+
scan request. SDK callers handling `OutputInsideProtectedRootError.pathKind`
|
|
1132
|
+
can match `"state"` for this case.
|
|
1133
|
+
|
|
1134
|
+
If credential-home preparation fails, the error includes the underlying
|
|
1135
|
+
filesystem diagnostic. For permission or read-only filesystem errors, check
|
|
1136
|
+
the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
|
|
1137
|
+
directory outside the repository. A new state directory has separate history
|
|
1138
|
+
and does not migrate existing credentials or reports.
|
|
1139
|
+
|
|
1140
|
+
Sandbox startup errors include the native diagnostic followed by a command to
|
|
1141
|
+
reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
|
|
1142
|
+
|
|
986
1143
|
On Windows, credential-home checks require trusted ownership and permissions
|
|
987
1144
|
through every ancestor, including the volume root. Codex Security can repair
|
|
988
1145
|
the credential home and its descendants; it does not change ancestor ownership
|
|
@@ -1039,10 +1196,13 @@ their own timestamps, window durations, and reset times. These are historical
|
|
|
1039
1196
|
observations, not a live allowance check or scan-only consumption. Empty readings
|
|
1040
1197
|
mean allowance was unavailable. There is no token-to-allowance conversion here.
|
|
1041
1198
|
|
|
1042
|
-
Cost displays use
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1199
|
+
Cost displays use Standard token rates for the model. OpenAI models use
|
|
1200
|
+
[OpenAI API pricing](https://developers.openai.com/api/docs/pricing). OpenAI
|
|
1201
|
+
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).
|
|
1202
|
+
For managed OpenAI models on Vertex AI, see [Google Cloud Vertex AI cost estimates](#google-cloud-vertex-ai-cost-estimates).
|
|
1203
|
+
The short/long-context range estimates usage at published rates. Other service
|
|
1204
|
+
tiers, account discounts, and ChatGPT subscription allowance are outside that
|
|
1205
|
+
estimate. Models without known prices have no estimate.
|
|
1046
1206
|
|
|
1047
1207
|
JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
|
|
1048
1208
|
and `context: "unknown"`). A null maximum means no upper estimate is available.
|
|
@@ -1057,13 +1217,25 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
|
|
|
1057
1217
|
Automatic history matching gets at most one extra call with a limit; if more
|
|
1058
1218
|
work is needed, the scan is preserved and you can run `scans match --all`.
|
|
1059
1219
|
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1220
|
+
A scan with a cost limit requires complete token usage for its recorded scan,
|
|
1221
|
+
worker, and custom validation sessions before the SDK returns a completed result.
|
|
1222
|
+
Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or
|
|
1223
|
+
`backports.zstd` installed in the selected Python environment.
|
|
1224
|
+
Missing or unreadable usage fails budget verification. Without a limit, usage
|
|
1225
|
+
reporting remains best effort.
|
|
1226
|
+
|
|
1227
|
+
When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealed
|
|
1228
|
+
report and retains unvalidated candidates as follow-up work. The saved report and
|
|
1229
|
+
the manifest's `scan.scope.limitations` record that validation was deferred.
|
|
1230
|
+
Reaching a configured limit with a valid finalized report returns `0` by default,
|
|
1231
|
+
or `1` if findings meet a configured failure threshold.
|
|
1232
|
+
|
|
1233
|
+
When a worker turn fails with a known cybersecurity policy refusal or an
|
|
1234
|
+
exhausted usage limit, Deep Scan stops retries and replacements, cancels active
|
|
1235
|
+
siblings, and retains completed worker artifacts. A capability check can succeed
|
|
1236
|
+
before a later request is refused. Use `scans show SCAN_ID` to inspect the failed
|
|
1237
|
+
scan and its retained results. To run it again from a saved recipe, use
|
|
1238
|
+
`scans rerun SCAN_ID`, which starts fresh discovery.
|
|
1067
1239
|
|
|
1068
1240
|
At 80% of a single interactive scan's limit, the dashboard offers a higher total
|
|
1069
1241
|
budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
|
|
@@ -1173,6 +1345,12 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
|
|
|
1173
1345
|
attempt per pending repository per invocation. Repeating the command continues
|
|
1174
1346
|
the campaign, skips completed results, and starts pending attempts. Occupied
|
|
1175
1347
|
attempt directories stop that repository and suggest `--recover`.
|
|
1348
|
+
If an ordinary attempt finds its checkout path already occupied, it stops before
|
|
1349
|
+
fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
|
|
1350
|
+
existing checkout before an ordinary retry.
|
|
1351
|
+
If checkout cleanup previously failed, the next invocation removes it only when
|
|
1352
|
+
its marker still identifies the same directory and scan attempt. Older or
|
|
1353
|
+
replacement checkouts without a matching marker are preserved.
|
|
1176
1354
|
Completed results are skipped only when their saved contract and seal are valid
|
|
1177
1355
|
and the manifest records a completed scan. Damaged or unsuccessful results get a
|
|
1178
1356
|
new attempt, including with `--recover`, while the old artifacts remain available.
|
|
@@ -1202,6 +1380,13 @@ failed or interrupted attempt:
|
|
|
1202
1380
|
- An unavailable, failed, or canceled scan starts a new attempt at the pinned
|
|
1203
1381
|
revision, preserving old artifacts and checkouts.
|
|
1204
1382
|
|
|
1383
|
+
Each nonempty committed line in `results.jsonl` must be valid JSON with a string
|
|
1384
|
+
task ID and a positive safe integer attempt number. If a line fails these checks,
|
|
1385
|
+
the command reports its line number and preserves the ledger. Restore a complete
|
|
1386
|
+
ledger backup that includes every committed attempt, or start a separate campaign
|
|
1387
|
+
in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
|
|
1388
|
+
a fresh attempt requires a new campaign.
|
|
1389
|
+
|
|
1205
1390
|
New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
|
|
1206
1391
|
workers and one recovery/new attempt per repository. A resume connection failure
|
|
1207
1392
|
stops only that repository for this invocation. Failed recovery checkouts remain;
|
|
@@ -1270,512 +1455,247 @@ Supply the validation prompt again when rerunning.
|
|
|
1270
1455
|
|
|
1271
1456
|
## Import vendor findings locally
|
|
1272
1457
|
|
|
1273
|
-
|
|
1458
|
+
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.
|
|
1274
1459
|
|
|
1275
|
-
|
|
1460
|
+
| Input and goal | Command | Service contacted | Where to find the result |
|
|
1461
|
+
| ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
1462
|
+
| Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
|
|
1463
|
+
| 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. |
|
|
1464
|
+
| Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
|
|
1465
|
+
| Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
|
|
1466
|
+
| 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. |
|
|
1276
1467
|
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
and `import github-advisories` are absent from command help and schemas and cannot
|
|
1284
|
-
run. The SDK's external publication, local import/readback, and advisory
|
|
1285
|
-
acquisition APIs require the same flag in their effective environment. An explicit
|
|
1286
|
-
`dependencies.environment` is used instead of the process environment. Pure
|
|
1287
|
-
normalizers and file readers remain available as library utilities.
|
|
1288
|
-
|
|
1289
|
-
This flag does not affect `publish scan`, `publish check`, `scan import`, or the
|
|
1290
|
-
existing `import github` alert collector. Disabling it retains previously imported
|
|
1291
|
-
records; enable it again to read them with `findings imported`.
|
|
1292
|
-
|
|
1293
|
-
Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
|
|
1294
|
-
reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
|
|
1295
|
-
inputs only for providers and report profiles that support them. A JSON API
|
|
1296
|
-
summary is not automatically a supported report; follow the provider's acquisition
|
|
1297
|
-
instructions and retain the original records. The readers detect supported input
|
|
1298
|
-
formats; `--format json` selects command output, not the input format.
|
|
1299
|
-
|
|
1300
|
-
Keep the acquisition format consistent across imports. Depending on the provider,
|
|
1301
|
-
switching formats can create separate records for the same vulnerability or
|
|
1302
|
-
replace a richer evidence snapshot with less detail. The importer does not merge
|
|
1303
|
-
evidence or deduplicate equivalent vulnerabilities across different source IDs.
|
|
1304
|
-
|
|
1305
|
-
Use the same vendor input and parser as Cloud publication, selecting a local
|
|
1306
|
-
repository path instead of a Cloud repository ID or URL. Supported inputs include
|
|
1307
|
-
Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
|
|
1308
|
-
[Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
|
|
1309
|
-
[Amazon Inspector repository findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md),
|
|
1310
|
-
[Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
|
|
1311
|
-
[OpenGrep native JSON](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md),
|
|
1312
|
-
[GitHub Dependabot repository alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md),
|
|
1313
|
-
and [saved GitHub code-scanning alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
|
|
1468
|
+
For `publish findings`, `--to` is required. With `--to local`, `--repository`
|
|
1469
|
+
takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
|
|
1470
|
+
The reader detects the file format. `--format json` selects the output format. A local preview checks the file offline without
|
|
1471
|
+
saving findings or calling a model. For example, preview a complete Endor
|
|
1472
|
+
Finding export from the matching checkout, replacing the namespace, project
|
|
1473
|
+
and branch in the source key.
|
|
1314
1474
|
|
|
1315
|
-
```
|
|
1316
|
-
codex-security publish findings
|
|
1317
|
-
--to local --repository
|
|
1318
|
-
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
1475
|
+
```sh
|
|
1476
|
+
codex-security publish findings /private/path/endor-findings.json --provider endor \
|
|
1477
|
+
--to local --repository . --source-key NAMESPACE/PROJECT/main --dry-run --format json
|
|
1319
1478
|
```
|
|
1320
1479
|
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
after reviewing the preview. `--to` is required; there is no default destination.
|
|
1324
|
-
Local import uses the workbench SQLite database and requires no Cloud login,
|
|
1325
|
-
network connection, or model call. `--dry-run` does not write findings.
|
|
1480
|
+
After reviewing the findings and exclusions, rerun the command without
|
|
1481
|
+
`--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).
|
|
1326
1482
|
|
|
1327
|
-
|
|
1483
|
+
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)
|
|
1328
1484
|
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
scan or automatically validate or patch findings. Missing revisions, locations,
|
|
1337
|
-
and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
|
|
1338
|
-
Git remotes, the URL must match one of those remotes; the importer does not
|
|
1339
|
-
substitute the checkout's current commit for an unknown scanner revision.
|
|
1340
|
-
|
|
1341
|
-
Repeated imports update the same record by repository, provider, source key, and
|
|
1342
|
-
source finding ID. The result reports created, updated, and unchanged counts.
|
|
1343
|
-
Keep the source key stable across exports. Records omitted from a later selection
|
|
1344
|
-
remain stored; omission does not resolve or delete a finding. Excluded records
|
|
1345
|
-
are reported, and an import with exclusions exits with status 1. Both destinations
|
|
1346
|
-
read the same vendor formats; Cloud's field, size and nesting limits do not apply
|
|
1347
|
-
to local file imports.
|
|
1348
|
-
|
|
1349
|
-
For OpenGrep, use `--provider opengrep` and supply `--source-repository-url`.
|
|
1350
|
-
The reader supports native JSON and gzip for both destinations. It uses the
|
|
1351
|
-
existing `semgrep` source-provider contract while retaining `OpenGrep` as the
|
|
1352
|
-
scanner origin; keep a stable OpenGrep-specific source key. Review report
|
|
1353
|
-
diagnostics as well as findings: import completion does not establish scan
|
|
1354
|
-
coverage. The [OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md)
|
|
1355
|
-
covers evidence identity, empty reports, and assessing an imported finding with
|
|
1356
|
-
the existing SDK validator.
|
|
1357
|
-
|
|
1358
|
-
`scan import --json` and `scan import --csv` remain separate commands for importing
|
|
1359
|
-
Codex Security's findings schema as a saved scan; they do not accept vendor
|
|
1360
|
-
exports.
|
|
1485
|
+
Local readback uses `findings imported [PATH]`. The path defaults to the current
|
|
1486
|
+
directory. Each imported record starts as `not_assessed`. Unknown revisions and
|
|
1487
|
+
locations stay unknown. Repository-scoped sources are checked against comparable
|
|
1488
|
+
configured Git remotes as described in the provider guide. Reimporting the same
|
|
1489
|
+
source key and finding ID reports created, updated, or unchanged records.
|
|
1490
|
+
Records omitted from the new selection stay stored. Local imports can retain
|
|
1491
|
+
evidence that exceeds Cloud's per-finding limits.
|
|
1361
1492
|
|
|
1362
|
-
|
|
1493
|
+
If a report contains both ready and excluded records, the local dry run exits
|
|
1494
|
+
with status 0. After confirmation, the import stores the ready records and
|
|
1495
|
+
exits with status 1. If all records are excluded, both commands exit with
|
|
1496
|
+
status 2. A clean empty report exits with status 0 in either mode and stores
|
|
1497
|
+
no findings.
|
|
1363
1498
|
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1499
|
+
Preview the same file and source key again for the intended destination before
|
|
1500
|
+
publishing. Semgrep Guardian selections, Web API SAST selections and full
|
|
1501
|
+
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.
|
|
1367
1502
|
|
|
1368
|
-
|
|
1369
|
-
endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
|
|
1370
|
-
--filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
|
|
1371
|
-
--list-all --output-type json > endor-findings.json
|
|
1372
|
-
codex-security publish findings endor-findings.json --to local \
|
|
1373
|
-
--provider endor --repository ./project \
|
|
1374
|
-
--source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
|
|
1375
|
-
```
|
|
1376
|
-
|
|
1377
|
-
Replace the example namespace, project UUID and local repository with your selection.
|
|
1378
|
-
Review the preview, remove `--dry-run` to confirm, then read the stored evidence
|
|
1379
|
-
with `codex-security findings imported ./project --format json`. To publish to
|
|
1380
|
-
Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
|
|
1381
|
-
file, provider and source key. The official
|
|
1382
|
-
[Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
|
|
1383
|
-
can help with setup and investigation, but summaries, counts and field-masked
|
|
1384
|
-
results do not replace complete Finding objects. `endorctl` reads the Endor API;
|
|
1385
|
-
the importer reads the saved export without maintaining an API connection or
|
|
1386
|
-
writing changes back to Endor.
|
|
1387
|
-
|
|
1388
|
-
Native JSON retains severity, package and advisory data, primary SAST/AI SAST
|
|
1389
|
-
locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
|
|
1390
|
-
reports are a lossy compatibility format, retaining finding links and UUIDs;
|
|
1391
|
-
unavailable severity and revisions stay unknown. Both formats use the Endor UUID
|
|
1392
|
-
within the selected repository and stable source key as identity. Importing SARIF
|
|
1393
|
-
after native JSON for that UUID updates the same record by replacing its evidence
|
|
1394
|
-
snapshot, not merging it. Native detail absent from SARIF is removed from the
|
|
1395
|
-
snapshot. Use native JSON consistently for ongoing imports.
|
|
1396
|
-
|
|
1397
|
-
Local and Cloud records remain unassessed source evidence. Local imports use the
|
|
1398
|
-
SQLite readback described above; Cloud imports use the login, preview,
|
|
1399
|
-
confirmation and retry flow below.
|
|
1503
|
+
## Import Trivy dependency findings
|
|
1400
1504
|
|
|
1401
|
-
|
|
1505
|
+
Use `--provider trivy` for language-package vulnerabilities in schema-v2
|
|
1506
|
+
repository or filesystem JSON. The [Trivy guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) explains how
|
|
1507
|
+
to set the scan root and check manifest paths.
|
|
1402
1508
|
|
|
1403
|
-
|
|
1509
|
+
## Import Endor Labs findings
|
|
1404
1510
|
|
|
1405
|
-
|
|
1406
|
-
|
|
1511
|
+
Use `--provider endor` for one Endor project and context. The
|
|
1512
|
+
[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
|
|
1513
|
+
SARIF compatibility, and the local preview.
|
|
1407
1514
|
|
|
1408
|
-
|
|
1409
|
-
with its `snyk-findings-export` skill to collect SCA findings from the repository's
|
|
1410
|
-
Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
|
|
1411
|
-
it does not retrieve existing platform project findings.
|
|
1515
|
+
## Import SonarQube Cloud issues
|
|
1412
1516
|
|
|
1413
|
-
|
|
1414
|
-
|
|
1517
|
+
`import sonar --dry-run` writes a private capture and returns its path. Preview
|
|
1518
|
+
that capture for the intended destination before confirming. A Cloud confirmation
|
|
1519
|
+
saves the issues locally and publishes them. Use `--full-output` with
|
|
1520
|
+
`--format json` or `--format jsonl` for a structured result.
|
|
1521
|
+
[Collect and replay a Sonar capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
|
|
1415
1522
|
|
|
1416
|
-
|
|
1417
|
-
codex-security publish findings snyk-findings.json --to local \
|
|
1418
|
-
--provider snyk --repository ./project \
|
|
1419
|
-
--source-key github.com/example/project/main/root/plugin-sca --dry-run
|
|
1420
|
-
```
|
|
1523
|
+
## Import GitHub findings locally or to Cloud
|
|
1421
1524
|
|
|
1422
|
-
|
|
1525
|
+
Use `--provider github` with separate source keys for
|
|
1526
|
+
[code scanning alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
|
|
1527
|
+
[Dependabot alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md) and
|
|
1528
|
+
[security advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
|
|
1529
|
+
Sign in with `gh` for the CLI collectors. `GH_HOST` defaults to `github.com`.
|
|
1423
1530
|
|
|
1424
|
-
|
|
1425
|
-
codex-security publish findings snyk-findings.json --to cloud \
|
|
1426
|
-
--provider snyk --repository https://github.com/example/project \
|
|
1427
|
-
--source-key github.com/example/project/main/root/plugin-sca --dry-run
|
|
1428
|
-
```
|
|
1429
|
-
|
|
1430
|
-
Check the collection's scan outcomes and limitations. Only Open Source SCA
|
|
1431
|
-
vulnerabilities are imported; other products and licenses are explicit exclusions.
|
|
1432
|
-
The importer retains the selected finding, native MCP record and collection
|
|
1433
|
-
context. MCP may shorten descriptions and omit dependency paths. Plugin paths
|
|
1434
|
-
remain in original evidence because v1 lacks their offset from the Git root.
|
|
1435
|
-
|
|
1436
|
-
For automation, prefer native JSON from
|
|
1437
|
-
`snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
|
|
1438
|
-
stop on other nonzero exits before importing. The existing `--provider snyk`
|
|
1439
|
-
autodetects a single project object or an `--all-projects` array; any project error
|
|
1440
|
-
stops the import. Use default ungrouped output, without `--group-issues`.
|
|
1441
|
-
Native JSON preserves individual dependency paths and remediation fields. Its
|
|
1442
|
-
paths remain original evidence because it does not establish their Git-root offset.
|
|
1443
|
-
|
|
1444
|
-
Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
|
|
1445
|
-
for compatibility. Its target-relative manifest paths and synthetic line numbers
|
|
1446
|
-
remain original evidence, without being projected as repository locations or
|
|
1447
|
-
package manifest paths. All three formats accept either destination. Use a consistent
|
|
1448
|
-
format and stable source key per repository, branch and scan target, for example
|
|
1449
|
-
`github.com/example/project/main/root/native-sca` for native JSON. Their source
|
|
1450
|
-
identities differ: use separate keys when switching acquisition formats. Imports
|
|
1451
|
-
do not deduplicate across formats or remove earlier imported records.
|
|
1452
|
-
|
|
1453
|
-
Known repository claims must
|
|
1454
|
-
match the selected Cloud repository or, when available, a configured local Git
|
|
1455
|
-
remote. Unknown repository context still requires selecting the correct target;
|
|
1456
|
-
the importer does not infer provenance from the current checkout.
|
|
1457
|
-
|
|
1458
|
-
Remove `--dry-run` from the selected command to review and confirm the import, or
|
|
1459
|
-
use `--yes` after reviewing the preview. Read local records with
|
|
1460
|
-
`codex-security findings imported ./project --format json`. Imported source
|
|
1461
|
-
evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
|
|
1462
|
-
[Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
|
|
1463
|
-
acquisition details.
|
|
1531
|
+
### Import GHSA advisories separately
|
|
1464
1532
|
|
|
1465
|
-
|
|
1533
|
+
Use `import github-advisories OWNER/REPO` for published repository advisories
|
|
1534
|
+
or add `--github-advisory-source global` and one or more `--github-advisory`
|
|
1535
|
+
IDs to collect global advisories. Check the installed dependency against each
|
|
1536
|
+
affected range. [Advisory selection and SDK examples](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
|
|
1466
1537
|
|
|
1467
|
-
Import
|
|
1468
|
-
and IaC findings without creating a scan. Imported records retain vendor evidence
|
|
1469
|
-
and remain **not assessed by Codex**, including when Wiz marks them resolved or
|
|
1470
|
-
reports an AI verdict. Workload secrets, cloud configuration findings, and external
|
|
1471
|
-
network findings are not supported by this repository importer. Cloud destinations
|
|
1472
|
-
currently support connected GitHub and GitHub Enterprise repositories, including
|
|
1473
|
-
custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
|
|
1474
|
-
|
|
1475
|
-
#### Select findings and a destination
|
|
1476
|
-
|
|
1477
|
-
Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
|
|
1478
|
-
connection to acquire findings and save the supported native JSON. A configured
|
|
1479
|
-
plugin may provide that connection; an official Codex plugin is not a prerequisite.
|
|
1480
|
-
The publisher reads the saved records. It does not fetch from Wiz or require a
|
|
1481
|
-
manual website download. The acquisition path still needs validation against
|
|
1482
|
-
actual responses from an authorized Wiz tenant; local parser checks do not
|
|
1483
|
-
establish that qualification.
|
|
1484
|
-
|
|
1485
|
-
Inspect the connection's actual response before importing it. MCP summaries,
|
|
1486
|
-
Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
|
|
1487
|
-
this finding mapper. Keep the original occurrence IDs and evidence; use the
|
|
1488
|
-
named collections below when the response contains repository findings.
|
|
1489
|
-
|
|
1490
|
-
Before the first import:
|
|
1491
|
-
|
|
1492
|
-
1. Select an existing repository in Codex Security Cloud and copy its URL or
|
|
1493
|
-
Cloud repository ID. The repository needs an
|
|
1494
|
-
authorized environment, but does not need a completed native scan.
|
|
1495
|
-
2. Read the selected records through the authorized connection and save their
|
|
1496
|
-
JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
|
|
1497
|
-
`vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
|
|
1498
|
-
package, image, and source metadata. For SAST, repository secrets, and IaC,
|
|
1499
|
-
retain the named API collections and repository metadata described below.
|
|
1500
|
-
Complete the selected pages before importing; a summary or unfinished page
|
|
1501
|
-
is not a complete finding selection.
|
|
1502
|
-
3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
|
|
1503
|
-
for that Wiz tenant and finding class across exports. Do not create a new key
|
|
1504
|
-
for each project filter or import; that creates different source identities.
|
|
1505
|
-
4. Check the ChatGPT account used by your existing file-backed Codex Security
|
|
1506
|
-
login. API-key-only and keyring-only logins are not supported for Cloud
|
|
1507
|
-
publication. See the credential-storage instructions below.
|
|
1508
|
-
|
|
1509
|
-
Prefer the supported native JSON. Existing package-vulnerability CSV reports are
|
|
1510
|
-
accepted as a compatibility input. **CSV support covers repository package
|
|
1511
|
-
vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
|
|
1512
|
-
Wiz code-to-cloud coverage.** The named JSON readers described below handle their
|
|
1513
|
-
respective finding families separately.
|
|
1514
|
-
|
|
1515
|
-
When a UI report is needed, retain the repository and finding filters in Wiz
|
|
1516
|
-
**Vulnerability Findings**, choose **Save as → Report**, select **Repository
|
|
1517
|
-
Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
|
|
1518
|
-
report. CSV must use the columns described below and a comma delimiter. Plain and
|
|
1519
|
-
gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
|
|
1520
|
-
filename extension. **Raw Event** on Code & Build Scans contains scan metadata
|
|
1521
|
-
rather than findings.
|
|
1522
|
-
|
|
1523
|
-
#### Configure an alternate Cloud deployment
|
|
1524
|
-
|
|
1525
|
-
For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
|
|
1526
|
-
API root before previewing or uploading, for example
|
|
1527
|
-
`https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
|
|
1528
|
-
HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
|
|
1529
|
-
`::1`). Use a login issued by that deployment and an isolated
|
|
1530
|
-
`CODEX_SECURITY_STATE_DIR` for testing. The endpoint
|
|
1531
|
-
does not change your login or sign you into another deployment. An invalid or
|
|
1532
|
-
empty configured URL stops the import before authentication or network requests.
|
|
1533
|
-
With the variable unset, the existing production endpoint remains the default.
|
|
1534
|
-
The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
|
|
1535
|
-
publication endpoint; it does not route vendor imports.
|
|
1536
|
-
|
|
1537
|
-
If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
|
|
1538
|
-
to the full Cloud app URL shown in the browser. The import handoff supplies both
|
|
1539
|
-
deployment settings. The preview and result include a repository-specific
|
|
1540
|
-
`cloudUrl`, and terminal completion prints the link. This setting only controls
|
|
1541
|
-
the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
|
|
1542
|
-
For custom API destinations without a configured app URL, completion retains
|
|
1543
|
-
the manual navigation guidance rather than guessing a UI host or port.
|
|
1544
|
-
|
|
1545
|
-
#### Preview and publish
|
|
1546
|
-
|
|
1547
|
-
Preview the selection and destination:
|
|
1538
|
+
## Import alerts from the CLI
|
|
1548
1539
|
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1553
|
-
```
|
|
1554
|
-
|
|
1555
|
-
`--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
|
|
1556
|
-
destination and resume the same saved submission. This command reads the
|
|
1557
|
-
authorized destination and current source versions during
|
|
1558
|
-
preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
|
|
1559
|
-
repository needs an existing environment; no native scan is required. Review the
|
|
1560
|
-
Cloud API endpoint, account, repository, environments, findings, and exclusions,
|
|
1561
|
-
then rerun without
|
|
1562
|
-
`--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
|
|
1563
|
-
reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
|
|
1564
|
-
occurs. Existing source findings keep their Cloud environment; new findings use
|
|
1565
|
-
the repository’s current authorized default. Preview shows the environments that
|
|
1566
|
-
will receive the selected findings. The terminal preview summarizes severities,
|
|
1567
|
-
shows up to five finding IDs and titles, and identifies the evidence file and
|
|
1568
|
-
exclusions. `--dry-run --format json` retains all normalized findings and complete
|
|
1569
|
-
evidence for inspection. A prompt explicitly includes any records that will be
|
|
1570
|
-
skipped.
|
|
1571
|
-
|
|
1572
|
-
#### Package vulnerability inputs
|
|
1573
|
-
|
|
1574
|
-
Native package input can be a Wiz JSON vulnerability report, a vulnerability
|
|
1575
|
-
finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
|
|
1576
|
-
with one package record per line. The repository package-vulnerability CSV
|
|
1577
|
-
profile below is also supported. Plain and gzip-compressed files are accepted.
|
|
1578
|
-
A response that advertises another page is rejected. Complete the requested pages
|
|
1579
|
-
or save only the explicitly selected records; retain the named collection for
|
|
1580
|
-
SAST, repository secrets, and IaC.
|
|
1581
|
-
|
|
1582
|
-
The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
|
|
1583
|
-
`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
|
|
1584
|
-
this profile; other Wiz report types use different fields.
|
|
1585
|
-
For repository imports, `CloudPlatform` must identify GitHub and
|
|
1586
|
-
`CloudProviderURL` must identify a repository branch. The repository URL must
|
|
1587
|
-
match the selected Cloud repository or, for local import, one of the checkout's
|
|
1588
|
-
Git remotes when configured. This also applies when the parsed findings are saved and
|
|
1589
|
-
read again as normalized JSONL. Other resource types are excluded.
|
|
1590
|
-
|
|
1591
|
-
CSV imports use `ID` as the occurrence identity and retain every parsed field,
|
|
1592
|
-
including unknown columns and quoted multiline values, in `source_data.row`.
|
|
1593
|
-
Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
|
|
1594
|
-
Vendor resolution status stays in the original evidence. The importer does not
|
|
1595
|
-
derive a branch or revision from a tree URL, or treat last-detected time as a
|
|
1596
|
-
record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
|
|
1597
|
-
and duplicate occurrence IDs among otherwise importable records stop the import.
|
|
1598
|
-
Review any excluded records in the preview before publishing.
|
|
1599
|
-
|
|
1600
|
-
Normalized JSONL is also accepted:
|
|
1540
|
+
Collect open code-scanning alerts on the default branch and save the complete
|
|
1541
|
+
array outside the checkout. Use a private temporary directory and run
|
|
1542
|
+
validation from the matching checkout. Validation sends the evidence to your
|
|
1543
|
+
configured model provider.
|
|
1601
1544
|
|
|
1602
|
-
```
|
|
1603
|
-
|
|
1604
|
-
"
|
|
1605
|
-
"
|
|
1606
|
-
"title": "Vulnerable example package",
|
|
1607
|
-
"severity": "high",
|
|
1608
|
-
"source_data": { "id": "vendor-finding-42" }
|
|
1609
|
-
}
|
|
1610
|
-
}
|
|
1545
|
+
```sh
|
|
1546
|
+
out=$(mktemp -d) &&
|
|
1547
|
+
codex-security import github OWNER/REPO --format json > "$out/alerts.json" &&
|
|
1548
|
+
codex-security validate "$out/alerts.json"
|
|
1611
1549
|
```
|
|
1612
1550
|
|
|
1613
|
-
|
|
1614
|
-
|
|
1615
|
-
|
|
1616
|
-
retains each record in `source_data`, uses reported severity, and leaves unknown
|
|
1617
|
-
branch/revision empty. Repository-branch findings retain their repository-relative
|
|
1618
|
-
file paths; container and other workload paths remain vendor evidence rather than
|
|
1619
|
-
source-code locations. It does not
|
|
1620
|
-
fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
|
|
1621
|
-
Findings from external network scans are excluded from this package vulnerability
|
|
1622
|
-
mapping.
|
|
1623
|
-
|
|
1624
|
-
#### SAST, repository secrets, and IaC inputs
|
|
1625
|
-
|
|
1626
|
-
For SAST, repository secrets, and IaC, save the documented JSON API collection:
|
|
1627
|
-
|
|
1628
|
-
| Finding family | Collection | Raw occurrence identity |
|
|
1629
|
-
| ------------------ | ---------------------------- | ----------------------- |
|
|
1630
|
-
| SAST | `data.sastFindings.nodes` | `sast:<id>` |
|
|
1631
|
-
| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
|
|
1632
|
-
| IaC | `data.iacFindings.nodes` | `iac:<id>` |
|
|
1633
|
-
|
|
1634
|
-
The collection identifies the mapping. Bare arrays of these raw findings are
|
|
1635
|
-
excluded because their overlapping fields do not identify a family. An export
|
|
1636
|
-
may contain multiple named collections. GraphQL errors and unfinished pages stop
|
|
1637
|
-
the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
|
|
1638
|
-
relationship to source code does not make it a repository secret.
|
|
1639
|
-
|
|
1640
|
-
Each new finding needs a verified source repository URL. Supply `repository.url`
|
|
1641
|
-
in the finding's repository metadata, or include the matching repository inventory
|
|
1642
|
-
in `data.versionControlResources.nodes`. For secrets, repository metadata is under
|
|
1643
|
-
`resource.typedProperties.repository`. The importer joins the inventory's
|
|
1644
|
-
`repository.id` to that source ID and uses `repository.url`; inventory node IDs,
|
|
1645
|
-
`providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
|
|
1646
|
-
must agree with the inventory and with the selected Cloud repository before any
|
|
1647
|
-
finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
|
|
1648
|
-
establishes case-insensitive repository matching on custom GitHub Enterprise
|
|
1649
|
-
hosts. Fresh imports preserve the reported branch name literally. Duplicate
|
|
1650
|
-
entries for one repository ID must agree on their platform and repository URL.
|
|
1651
|
-
For example, this synthetic selection supplies the inventory alongside its SAST
|
|
1652
|
-
collection:
|
|
1551
|
+
The collector reads alerts, including third-party SARIF uploads. It does not
|
|
1552
|
+
start a scan. For filters, ref selection and SDK validation, see the
|
|
1553
|
+
[code scanning guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md).
|
|
1653
1554
|
|
|
1654
|
-
|
|
1655
|
-
{
|
|
1656
|
-
"data": {
|
|
1657
|
-
"sastFindings": {
|
|
1658
|
-
"nodes": [
|
|
1659
|
-
{
|
|
1660
|
-
"id": "finding-42",
|
|
1661
|
-
"name": "Untrusted query construction",
|
|
1662
|
-
"severity": "HIGH",
|
|
1663
|
-
"repository": { "id": "source-repository-1" },
|
|
1664
|
-
"filePath": "src/query.ts",
|
|
1665
|
-
"startLine": 10,
|
|
1666
|
-
"endLine": 12
|
|
1667
|
-
}
|
|
1668
|
-
]
|
|
1669
|
-
},
|
|
1670
|
-
"versionControlResources": {
|
|
1671
|
-
"nodes": [
|
|
1672
|
-
{
|
|
1673
|
-
"repository": {
|
|
1674
|
-
"id": "source-repository-1",
|
|
1675
|
-
"url": "https://github.com/example/project"
|
|
1676
|
-
}
|
|
1677
|
-
}
|
|
1678
|
-
]
|
|
1679
|
-
}
|
|
1680
|
-
}
|
|
1681
|
-
}
|
|
1682
|
-
```
|
|
1555
|
+
## Publish findings to Cloud
|
|
1683
1556
|
|
|
1684
|
-
|
|
1685
|
-
|
|
1686
|
-
|
|
1687
|
-
|
|
1688
|
-
|
|
1689
|
-
|
|
1690
|
-
|
|
1691
|
-
|
|
1692
|
-
|
|
1693
|
-
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
|
|
1697
|
-
|
|
1698
|
-
|
|
1699
|
-
|
|
1700
|
-
|
|
1701
|
-
`
|
|
1702
|
-
|
|
1703
|
-
|
|
1704
|
-
|
|
1705
|
-
|
|
1706
|
-
|
|
1707
|
-
|
|
1708
|
-
|
|
1709
|
-
|
|
1710
|
-
|
|
1711
|
-
|
|
1712
|
-
|
|
1713
|
-
|
|
1714
|
-
|
|
1715
|
-
|
|
1716
|
-
|
|
1717
|
-
|
|
1718
|
-
|
|
1719
|
-
|
|
1720
|
-
|
|
1721
|
-
|
|
1722
|
-
|
|
1723
|
-
|
|
1724
|
-
|
|
1725
|
-
|
|
1726
|
-
|
|
1727
|
-
|
|
1728
|
-
|
|
1729
|
-
|
|
1730
|
-
|
|
1731
|
-
|
|
1732
|
-
|
|
1733
|
-
|
|
1734
|
-
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
|
|
1742
|
-
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1756
|
-
|
|
1757
|
-
|
|
1758
|
-
|
|
1759
|
-
|
|
1760
|
-
|
|
1761
|
-
|
|
1762
|
-
`
|
|
1763
|
-
|
|
1764
|
-
|
|
1765
|
-
|
|
1766
|
-
|
|
1767
|
-
|
|
1768
|
-
|
|
1769
|
-
|
|
1770
|
-
|
|
1771
|
-
|
|
1772
|
-
|
|
1773
|
-
|
|
1774
|
-
|
|
1775
|
-
|
|
1776
|
-
|
|
1777
|
-
|
|
1778
|
-
|
|
1557
|
+
Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
|
|
1558
|
+
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).
|
|
1559
|
+
|
|
1560
|
+
### Preview and publish
|
|
1561
|
+
|
|
1562
|
+
Set `--to cloud`. For `--repository`, use the connected GitHub or GitHub
|
|
1563
|
+
Enterprise repository URL or its Cloud ID. Either works for retries. If
|
|
1564
|
+
several connectors share the URL, use the ID. You can import before the
|
|
1565
|
+
repository's first native scan.
|
|
1566
|
+
|
|
1567
|
+
Cloud requires a file-backed ChatGPT login. To use your regular Codex login,
|
|
1568
|
+
set `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in
|
|
1569
|
+
again with the ChatGPT account you want to use.
|
|
1570
|
+
|
|
1571
|
+
### Review the Cloud destination
|
|
1572
|
+
|
|
1573
|
+
Run the command with `--dry-run --format json`. Check `accountId`,
|
|
1574
|
+
`cloudApiUrl`, `destination` and `source.source_key`. Compare `findings` and
|
|
1575
|
+
`excluded` with the records you meant to import.
|
|
1576
|
+
|
|
1577
|
+
- **Private findings inbox.** If the preview includes `privateImport`, the
|
|
1578
|
+
report goes to your inbox. The repository and connector identify the
|
|
1579
|
+
suggested assessment target. Check `format`, `bytes` and `sha256` in
|
|
1580
|
+
`privateImport` to identify the upload. For an Endor Finding, an Endor
|
|
1581
|
+
`list.objects` response or a Wiz vulnerability JSON export, the CLI can
|
|
1582
|
+
send the original bytes when Cloud accepts the format and every record
|
|
1583
|
+
matches your selection. Other inputs, including arrays of selected Endor
|
|
1584
|
+
Findings, use `security.findings.v1`.
|
|
1585
|
+
- **Repository publisher.** Check `repository.environment_id` in each entry
|
|
1586
|
+
of `requests`. The publisher checks the current source versions. Existing
|
|
1587
|
+
records keep their environment. New records use the repository's authorized
|
|
1588
|
+
default.
|
|
1589
|
+
|
|
1590
|
+
To import, run the same command without `--dry-run` and confirm. The terminal
|
|
1591
|
+
shows the file, exclusions, severities and up to five finding IDs and titles.
|
|
1592
|
+
The prompt defaults to No. For a noninteractive import, add `--yes` after
|
|
1593
|
+
reviewing the full JSON preview.
|
|
1594
|
+
|
|
1595
|
+
### Configure an alternate Cloud deployment
|
|
1596
|
+
|
|
1597
|
+
Set `CODEX_SECURITY_CLOUD_BASE_URL` to the deployment's API root, such as
|
|
1598
|
+
`https://cloud.example.test/backend-api/aardvark`. Use a login issued by that
|
|
1599
|
+
deployment. Remote API roots require HTTPS. Loopback development also accepts
|
|
1600
|
+
HTTP on `localhost`, `127.0.0.0/8`, or `::1`. An empty or invalid setting
|
|
1601
|
+
stops preparation before authentication or network requests. Leaving it unset
|
|
1602
|
+
selects production. For testing, use an isolated `CODEX_SECURITY_STATE_DIR`.
|
|
1603
|
+
|
|
1604
|
+
For a separately hosted Cloud UI, set `CODEX_SECURITY_CLOUD_WEB_URL` to the
|
|
1605
|
+
full app URL. The preview and result can then supply a repository-specific
|
|
1606
|
+
`cloudUrl`. With a custom API and no web URL, the CLI prints navigation
|
|
1607
|
+
instructions. API requests always use the API root. The older
|
|
1608
|
+
`CODEX_SECURITY_CLOUD_PUBLISH_URL` setting applies only to native scan publishing.
|
|
1609
|
+
|
|
1610
|
+
### Resume interrupted imports
|
|
1611
|
+
|
|
1612
|
+
If the result includes `savedSubmission`, keep that checkpoint. Rerun the
|
|
1613
|
+
original command with `--dry-run --format json` using the same input, account,
|
|
1614
|
+
destination, API endpoint and state directory. Check `cloudApiUrl`. If
|
|
1615
|
+
`resumed` is true, confirm to continue the saved submission. If it's false,
|
|
1616
|
+
review the new submission before confirming.
|
|
1617
|
+
|
|
1618
|
+
- **Private inbox.** The CLI checks the report digest and reuses its saved
|
|
1619
|
+
request IDs. It can read an accepted job even if the deployment has since
|
|
1620
|
+
disabled uploads. After an inbox reset, check the new report format, size
|
|
1621
|
+
and digest before confirming.
|
|
1622
|
+
- **Repository publisher.** The CLI saves each request privately before
|
|
1623
|
+
sending up to 100 findings. Retries use the same publisher, request IDs and
|
|
1624
|
+
bodies. If the repository has been reset, preview and confirm a fresh
|
|
1625
|
+
submission.
|
|
1626
|
+
|
|
1627
|
+
[Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
|
|
1628
|
+
|
|
1629
|
+
### Results and exit codes
|
|
1630
|
+
|
|
1631
|
+
| Status | Exit code | Meaning |
|
|
1632
|
+
| ------------- | --------- | -------------------------------------------------------------------------------------- |
|
|
1633
|
+
| `empty` | 0 | No records were available to upload. |
|
|
1634
|
+
| `complete` | 0 | The inbox job processed every record successfully, or the publisher verified each one. |
|
|
1635
|
+
| `partial` | 1 | The import had exclusions or record errors, or the inbox job failed or was cancelled. |
|
|
1636
|
+
| `interrupted` | 2 | The CLI stopped while uploading, checking the result or saving a receipt. |
|
|
1637
|
+
| `failed` | 2 | Preparation failed before upload. |
|
|
1638
|
+
|
|
1639
|
+
A clean empty report needs no confirmation. Self-contained file imports can
|
|
1640
|
+
finish before Cloud sign-in; Semgrep Platform and Snyk REST captures use the
|
|
1641
|
+
Cloud catalog to verify their repository. Local imports still validate the
|
|
1642
|
+
checkout and create no workbench database. Explicit scanner errors
|
|
1643
|
+
and selections containing only excluded records fail; JSON output retains their
|
|
1644
|
+
diagnostics and exclusion reasons. Existing findings stay open.
|
|
1645
|
+
|
|
1646
|
+
For automation, check the scanner's exit status as well as the import's. SARIF
|
|
1647
|
+
can contain no runs or omit results in a rules-only export. `empty` describes
|
|
1648
|
+
the selected report, not whether a scan completed successfully.
|
|
1649
|
+
|
|
1650
|
+
For a partial or interrupted import, check `excluded` and any `error` before
|
|
1651
|
+
retrying. Some records may already have reached Cloud.
|
|
1652
|
+
|
|
1653
|
+
- **Private inbox.** In `privateJob`, check the job `status`, `counts.error`
|
|
1654
|
+
and `counts.unprocessed`. The receipt also identifies the job (`id`) and the
|
|
1655
|
+
uploaded file (`input.file_id`). The CLI reads the job receipt, so a
|
|
1656
|
+
successful import can show `verified: 0`. To share a finding, open it in
|
|
1657
|
+
your inbox, assess it against a pinned repository revision and publish the
|
|
1658
|
+
reportable assessment.
|
|
1659
|
+
- **Repository publisher.** `verified` counts records whose identity the CLI
|
|
1660
|
+
confirmed by reading them back. If the version matches the receipt, the CLI
|
|
1661
|
+
also checks the evidence. A newer version can have different evidence and
|
|
1662
|
+
still count as verified. `unacknowledged` counts records awaiting a receipt,
|
|
1663
|
+
including records Cloud accepted if the response was lost. Use `client_id`
|
|
1664
|
+
to match a receipt item to its request and `source_finding_id` in `failures`
|
|
1665
|
+
to find a failed vendor record. Counts include earlier batches with receipts.
|
|
1666
|
+
When present, `cloudUrl` opens the repository. Assessment and sharing are
|
|
1667
|
+
separate steps.
|
|
1668
|
+
|
|
1669
|
+
With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
|
|
1670
|
+
Failed and interrupted imports set `ok` to `false` and `error.code` to
|
|
1671
|
+
`IMPORT_FAILED`. Available results, receipts, and counts remain under `data`.
|
|
1672
|
+
Other formats reject `--full-output` before reading the file or contacting
|
|
1673
|
+
Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
|
|
1674
|
+
|
|
1675
|
+
Progress goes to stderr and JSON results to stdout. The repository publisher
|
|
1676
|
+
uploads sequentially and uses up to four concurrent requests for lookups and
|
|
1677
|
+
readback.
|
|
1678
|
+
|
|
1679
|
+
### Import Snyk findings
|
|
1680
|
+
|
|
1681
|
+
Use `--provider snyk` for native Open Source JSON, plugin exports, SARIF or
|
|
1682
|
+
monitored Open Source and Code issues. The [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md)
|
|
1683
|
+
covers saved files, distinct source keys for each format, and collection with
|
|
1684
|
+
`import snyk`.
|
|
1685
|
+
|
|
1686
|
+
### Import Wiz findings
|
|
1687
|
+
|
|
1688
|
+
<a id="select-findings-and-a-destination"></a>
|
|
1689
|
+
<a id="package-vulnerability-inputs"></a>
|
|
1690
|
+
<a id="sast-repository-secrets-and-iac-inputs"></a>
|
|
1691
|
+
<a id="preserved-evidence"></a>
|
|
1692
|
+
<a id="convert-csv-reports"></a>
|
|
1693
|
+
|
|
1694
|
+
Use `--provider wiz` for a [saved Wiz report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#quick-start).
|
|
1695
|
+
The provider guide describes [package JSON and CSV](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#package-vulnerability-inputs),
|
|
1696
|
+
[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),
|
|
1697
|
+
[retained evidence](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#preserved-evidence) and
|
|
1698
|
+
[conversion to normalized JSONL](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#convert-csv-reports).
|
|
1779
1699
|
|
|
1780
1700
|
### Publish completed scans
|
|
1781
1701
|
|
|
@@ -1854,15 +1774,16 @@ Choose a destination authorized to receive that content. Local history records
|
|
|
1854
1774
|
successful issue IDs separately from sealed artifacts. The CLI and the plugin's
|
|
1855
1775
|
finding-tracking workflow share these records when using the same Codex Security
|
|
1856
1776
|
state directory. Accepted writes remain recorded even if a later issue read fails.
|
|
1857
|
-
The shared-history migration preserves existing Linear receipts and replaces their
|
|
1858
|
-
old table. Upgrade CLI and plugin installations together when they share state;
|
|
1859
|
-
older publishers cannot write to the migrated database.
|
|
1860
1777
|
|
|
1861
|
-
|
|
1862
|
-
|
|
1863
|
-
|
|
1864
|
-
|
|
1865
|
-
|
|
1778
|
+
By default, publishing the same scan again creates new issues. With
|
|
1779
|
+
`--skip-existing`, the CLI skips occurrences with a recorded success for the
|
|
1780
|
+
same team and project. This includes issues the plugin created or reused.
|
|
1781
|
+
The CLI checks local history only. After an interrupted or concurrent run,
|
|
1782
|
+
check Linear for an existing issue before retrying.
|
|
1783
|
+
|
|
1784
|
+
If the CLI and plugin share a database from an older installation, upgrade
|
|
1785
|
+
both together. The shared history preserves existing Linear receipts, but
|
|
1786
|
+
publishers that require the old table can no longer record new ones.
|
|
1866
1787
|
|
|
1867
1788
|
```ts
|
|
1868
1789
|
import { publishScan } from "@openai/codex-security";
|
|
@@ -1892,12 +1813,19 @@ The [records protocol](classify-severity-records.md) accepts immutable Markdown
|
|
|
1892
1813
|
report snapshots and delegates model execution to the host.
|
|
1893
1814
|
|
|
1894
1815
|
For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
|
|
1895
|
-
|
|
1816
|
+
By default, saved findings are classified with the [built-in severity rubric](https://github.com/openai/codex-security/blob/main/plugins/codex-security/references/default-severity-rubric.md).
|
|
1896
1817
|
It evaluates attacker access, boundary crossing, additional harm, and evidence for
|
|
1897
1818
|
Critical, High, Medium, Low, and Informational findings. Confidence remains separate
|
|
1898
|
-
from severity; missing proof alone does not justify a downgrade.
|
|
1899
|
-
|
|
1900
|
-
|
|
1819
|
+
from severity; missing proof alone does not justify a downgrade.
|
|
1820
|
+
|
|
1821
|
+
Set `CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1` to fetch the current default
|
|
1822
|
+
from Statsig once per reclassification. Only the exact value `1` enables the
|
|
1823
|
+
request. It sends the config name without findings or account identifiers.
|
|
1824
|
+
If the request fails, times out, or returns an invalid rubric, the built-in
|
|
1825
|
+
rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
|
|
1826
|
+
uses your policy for every review. Rubrics and repeatable `--knowledge-base`
|
|
1827
|
+
context accept text, PDF, DOCX, and directories.
|
|
1828
|
+
|
|
1901
1829
|
Each finding is classified three times by default. `--runs N` accepts
|
|
1902
1830
|
an integer from 1 through 10; SDK options use `classificationRuns` with the same
|
|
1903
1831
|
default and bounds. Each review runs in an independent read-only turn using the
|
|
@@ -1918,6 +1846,12 @@ the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
|
|
|
1918
1846
|
missing facts that could change the result. Exclusions have a null level.
|
|
1919
1847
|
Finding/occurrence IDs and input hashes bind each assessment to its evidence.
|
|
1920
1848
|
|
|
1849
|
+
For a single rubric document, the classification result reports the SHA-256 of
|
|
1850
|
+
the exact UTF-8 text supplied to the reviewer in `rubricSha256`. For multiple
|
|
1851
|
+
documents it reports the digest of the ordered text collection. A bundled or
|
|
1852
|
+
remote default also records its `rubricRevision`. Older saved results retain
|
|
1853
|
+
their original digest and may omit the revision.
|
|
1854
|
+
|
|
1921
1855
|
Successful assessments checkpoint immediately in local SQLite. Retries reuse
|
|
1922
1856
|
matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
|
|
1923
1857
|
work. Default-rubric assessments use `source: "rubric"` and a content hash; former
|
|
@@ -2001,7 +1935,7 @@ await publishScan(scanDirectory, {
|
|
|
2001
1935
|
|
|
2002
1936
|
`classifySeverity()` accepts `findingId`, `title`, `summary`, and available
|
|
2003
1937
|
evidence/metadata. Imported reports may lack severity or occurrence IDs; omitting
|
|
2004
|
-
`rubricPath` uses the
|
|
1938
|
+
`rubricPath` uses the selected default policy even when a scanner severity is present.
|
|
2005
1939
|
Scan wrappers persist checkpoints (including for
|
|
2006
1940
|
external directories), accept `reprocess: true`, and treat `findingIds: []` as an
|
|
2007
1941
|
empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
|
|
@@ -2136,9 +2070,21 @@ history. Inspect its saved status before choosing resume or rerun, and supply
|
|
|
2136
2070
|
the original custom prompt files for reruns. Structured history and log output
|
|
2137
2071
|
and command selection defaults are unchanged.
|
|
2138
2072
|
|
|
2139
|
-
|
|
2140
|
-
|
|
2141
|
-
|
|
2073
|
+
Reruns use the current checkout/context files and do not reload project files.
|
|
2074
|
+
The readable scan recipe records your authentication choice. A separate private
|
|
2075
|
+
replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
|
|
2076
|
+
`model_providers` settings, including any credentials written directly in
|
|
2077
|
+
`http_headers`. If you use `env_key` or `env_http_headers`, the profile stores
|
|
2078
|
+
the variable names. Set those variables when you rerun or resume. Settings
|
|
2079
|
+
inherited from a named file profile are reloaded from that file. If an older
|
|
2080
|
+
scan omitted your endpoint, start a new scan with the original `--codex` override.
|
|
2081
|
+
|
|
2082
|
+
When routing through environment variables, set them for each launch, including
|
|
2083
|
+
rerun and resume. Deep workers inherit `CODEX_OSS_BASE_URL` and `CODEX_OSS_PORT`
|
|
2084
|
+
for Ollama and LM Studio, and `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`,
|
|
2085
|
+
and `GOOGLE_APPLICATION_CREDENTIALS` for Vertex AI.
|
|
2086
|
+
|
|
2087
|
+
Supply replacement scan and custom-validation prompts when the original used them:
|
|
2142
2088
|
|
|
2143
2089
|
```bash
|
|
2144
2090
|
codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
|
|
@@ -2160,11 +2106,16 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
|
2160
2106
|
writable, and outside the target repository. Session logs may contain sensitive
|
|
2161
2107
|
data even though scan recipes do not store credentials.
|
|
2162
2108
|
|
|
2163
|
-
|
|
2164
|
-
|
|
2165
|
-
|
|
2166
|
-
|
|
2167
|
-
logs
|
|
2109
|
+
Saved scan logs retain the finishing turn, including its final response, and
|
|
2110
|
+
exclude later turns once the scan records a completion boundary. Older scans
|
|
2111
|
+
retain the full history of their attributed sessions and keep their existing
|
|
2112
|
+
worker-selection boundaries. This also applies to logs attached with
|
|
2113
|
+
`feedback --include-logs`.
|
|
2114
|
+
|
|
2115
|
+
Codex may compress saved session logs to `.jsonl.zst`. Plain and compressed logs
|
|
2116
|
+
work on all supported Node.js versions, including logs, feedback attachments,
|
|
2117
|
+
usage accounting, and saved-session discovery for resume. A bundled decoder
|
|
2118
|
+
reads concatenated frames and reports truncated streams as collection errors.
|
|
2168
2119
|
|
|
2169
2120
|
### Resuming an interrupted Deep Scan
|
|
2170
2121
|
|
|
@@ -2207,6 +2158,13 @@ One comparison ID is compared with the latest completed scan.
|
|
|
2207
2158
|
codex-security scans match --all --force --model gpt-6.1-sol --effort high
|
|
2208
2159
|
```
|
|
2209
2160
|
|
|
2161
|
+
When a saved Standard scan and a Deep scan have the same recorded target,
|
|
2162
|
+
revision, and snapshot digest, matching flags findings that have different
|
|
2163
|
+
anchors but share a unique rule, first displayed source range, and optional
|
|
2164
|
+
instance. Matching preserves the case of saved paths. Codex can request the
|
|
2165
|
+
saved evidence to distinguish separate causes at that site. Automatic matching
|
|
2166
|
+
under a cost limit keeps its single comparison call.
|
|
2167
|
+
|
|
2210
2168
|
Only high-confidence root-cause matches are grouped. Uncertain and related
|
|
2211
2169
|
findings remain separate. Rebuilding retains stable identities, triage, and
|
|
2212
2170
|
sealed artifacts; interruption preserves completed comparisons. Model/effort
|
|
@@ -2310,7 +2268,8 @@ marks shortened text. Other template columns keep their original values.
|
|
|
2310
2268
|
|
|
2311
2269
|
The output defaults to `servicenow-avit.csv`. Upload the completed file in the
|
|
2312
2270
|
same ServiceNow screen. Each upload creates a new penetration-test form for the
|
|
2313
|
-
application.
|
|
2271
|
+
application. If the submission result is unclear, check its status and log notes
|
|
2272
|
+
on the Vulnerability Integration Push Queues page before uploading again. See [ServiceNow's upload instructions](https://www.servicenow.com/docs/r/security-management/application-vulnerability-response/ingest-vulnerabilities-manually-avr.html).
|
|
2314
2273
|
|
|
2315
2274
|
### Export a threat model
|
|
2316
2275
|
|
|
@@ -2403,9 +2362,11 @@ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/exa
|
|
|
2403
2362
|
|
|
2404
2363
|
### Local pre-commit checks
|
|
2405
2364
|
|
|
2406
|
-
|
|
2407
|
-
failure or findings at
|
|
2408
|
-
for
|
|
2365
|
+
The generated hook runs a `--working-tree` scan and blocks the commit on scan
|
|
2366
|
+
failure or findings at or above its threshold (`high` by default). It uses the
|
|
2367
|
+
checkout's normal index for staged and unstaged changes, so it can include changes
|
|
2368
|
+
outside a partial commit and miss content staged only in a separate index.
|
|
2369
|
+
Use required CI for enforcement because local hooks are optional.
|
|
2409
2370
|
|
|
2410
2371
|
Install the CLI outside the target repository and run that copy directly. `npx`
|
|
2411
2372
|
can select a repository-local package. Before installation, inspect:
|
|
@@ -2423,222 +2384,13 @@ codex-security install-hook /path/to/repository
|
|
|
2423
2384
|
```
|
|
2424
2385
|
|
|
2425
2386
|
To migrate an existing generated hook, verify it is a regular file used only by
|
|
2426
|
-
this repository and contains only the generated
|
|
2427
|
-
|
|
2428
|
-
|
|
2429
|
-
|
|
2430
|
-
|
|
2431
|
-
|
|
2432
|
-
|
|
2433
|
-
|
|
2434
|
-
Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
|
|
2435
|
-
The existing alert collector remains available without it.
|
|
2436
|
-
|
|
2437
|
-
Acquire code-scanning findings with the existing `import github` collector and
|
|
2438
|
-
save its complete JSON output. In Codex, the official
|
|
2439
|
-
[GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
|
|
2440
|
-
can help select the repository, alert numbers and ref through GitHub's MCP
|
|
2441
|
-
server. Pass that selection to the collector. For Dependabot, use a token with
|
|
2442
|
-
**Dependabot alerts: read** and follow
|
|
2443
|
-
the [repository alert export guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md)
|
|
2444
|
-
to save the native REST records from one repository and preview them with
|
|
2445
|
-
`--provider github`. For GHSA disclosures, use the
|
|
2446
|
-
[advisory collector](#import-ghsa-advisories-separately).
|
|
2447
|
-
The following example previews local storage of a code-scanning export.
|
|
2448
|
-
|
|
2449
|
-
```bash
|
|
2450
|
-
codex-security import github example/project --format json > /path/outside/repository/alerts.json
|
|
2451
|
-
codex-security publish findings /path/outside/repository/alerts.json \
|
|
2452
|
-
--to local --provider github --repository ./project \
|
|
2453
|
-
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
2454
|
-
```
|
|
2455
|
-
|
|
2456
|
-
Or preview publication to a connected Cloud repository:
|
|
2457
|
-
|
|
2458
|
-
```bash
|
|
2459
|
-
codex-security publish findings /path/outside/repository/alerts.json \
|
|
2460
|
-
--to cloud --provider github --repository https://github.com/example/project \
|
|
2461
|
-
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
2462
|
-
```
|
|
2463
|
-
|
|
2464
|
-
The importer fetches every page, retrieves alert details, and retains the selected
|
|
2465
|
-
ref's instance. It writes the saved input for publication; no website download or
|
|
2466
|
-
hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
|
|
2467
|
-
selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
|
|
2468
|
-
the default branch. MCP list calls are paginated separately. Code-scanning
|
|
2469
|
-
imports require the saved collector output, which includes the selected instance.
|
|
2470
|
-
|
|
2471
|
-
The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
|
|
2472
|
-
the plugin's connection does not sign in `gh`. Reading code-scanning alerts requires
|
|
2473
|
-
[code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
|
|
2474
|
-
**Code scanning alerts: read** for a fine-grained token, or `security_events` for
|
|
2475
|
-
a classic token (`public_repo` is sufficient for public repositories). The source
|
|
2476
|
-
repository must have code scanning available. For Cloud publication, the
|
|
2477
|
-
destination must be connected in the selected Cloud account. For local import,
|
|
2478
|
-
the source repository must match a configured Git remote when remotes are
|
|
2479
|
-
available; no Cloud login is required to store the acquired evidence.
|
|
2480
|
-
|
|
2481
|
-
Review the destination, source, exclusions and evidence in the preview. Repeat the
|
|
2482
|
-
selected command without `--dry-run` and confirm it, or add `--yes` for a
|
|
2483
|
-
previously reviewed input. Local persistence and readback follow the
|
|
2484
|
-
[local import flow](#import-vendor-findings-locally); use
|
|
2485
|
-
`codex-security findings imported ./project --format json` to read the records.
|
|
2486
|
-
Cloud authentication, batching, saved receipts, partial results and
|
|
2487
|
-
interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
|
|
2488
|
-
JSON, JSONL and gzip are supported. Save complete import output without field or
|
|
2489
|
-
token filters or `--full-output`.
|
|
2490
|
-
|
|
2491
|
-
Use a stable source key for the GitHub host, repository and finding family.
|
|
2492
|
-
Code-scanning identities include the selected ref, so branches retain separate
|
|
2493
|
-
evidence. The original alert, rule, scanner, location, revision and source state
|
|
2494
|
-
remain attached. An alert-wide dismissal takes precedence over the selected
|
|
2495
|
-
instance's open/fixed state. Missing security severity stays `unknown`;
|
|
2496
|
-
SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
|
|
2497
|
-
remains unassessed by Codex.
|
|
2498
|
-
|
|
2499
|
-
The SDK offers the same preview and publication boundary for Cloud:
|
|
2500
|
-
|
|
2501
|
-
```ts
|
|
2502
|
-
import {
|
|
2503
|
-
importGitHubCodeScanningAlerts,
|
|
2504
|
-
normalizeGitHubCodeScanningAlerts,
|
|
2505
|
-
prepareNormalizedExternalPublication,
|
|
2506
|
-
} from "@openai/codex-security";
|
|
2507
|
-
|
|
2508
|
-
const alerts = await importGitHubCodeScanningAlerts({
|
|
2509
|
-
repository: "example/project",
|
|
2510
|
-
});
|
|
2511
|
-
const prepared = await prepareNormalizedExternalPublication(
|
|
2512
|
-
normalizeGitHubCodeScanningAlerts(alerts),
|
|
2513
|
-
{
|
|
2514
|
-
provider: "github",
|
|
2515
|
-
repository: "https://github.com/example/project",
|
|
2516
|
-
sourceKey: "github.com/example/project/code-scanning",
|
|
2517
|
-
},
|
|
2518
|
-
);
|
|
2519
|
-
console.log(prepared.preview);
|
|
2520
|
-
// After reviewing the preview:
|
|
2521
|
-
const receipt = await prepared.publish();
|
|
2522
|
-
```
|
|
2523
|
-
|
|
2524
|
-
For local storage, pass the same normalized evidence to
|
|
2525
|
-
`prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
|
|
2526
|
-
its preview, and call `import()`. `prepareLocalExternalImport()` accepts the saved
|
|
2527
|
-
import file directly. Read records with `listLocalExternalFindings({ repository })`.
|
|
2528
|
-
|
|
2529
|
-
### Import GHSA advisories separately
|
|
2530
|
-
|
|
2531
|
-
Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
|
|
2532
|
-
|
|
2533
|
-
**Importing a GHSA advisory does not establish an installed dependency or
|
|
2534
|
-
applicability to the destination repository.** Repository advisories are
|
|
2535
|
-
disclosures maintained by a repository; global advisories describe affected
|
|
2536
|
-
software in GitHub's public advisory database. Both are evidence for
|
|
2537
|
-
investigation, not Dependabot alerts. Check the repository’s dependency versions
|
|
2538
|
-
and applicability separately.
|
|
2539
|
-
|
|
2540
|
-
```bash
|
|
2541
|
-
# Read only published advisories for this repository.
|
|
2542
|
-
codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
|
|
2543
|
-
|
|
2544
|
-
# Select individual public database records without enumerating the database.
|
|
2545
|
-
codex-security import github-advisories example/project \
|
|
2546
|
-
--github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
|
|
2547
|
-
--format json > /path/outside/repository/advisories.json
|
|
2548
|
-
|
|
2549
|
-
codex-security publish findings /path/outside/repository/advisories.json \
|
|
2550
|
-
--to cloud --provider github --repository https://github.com/example/project \
|
|
2551
|
-
--source-key github.com/example/project/security-advisories --dry-run --format json
|
|
2552
|
-
```
|
|
2553
|
-
|
|
2554
|
-
For local storage, use the same advisory file, provider and source key with
|
|
2555
|
-
`--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
|
|
2556
|
-
to review, confirm and read the stored evidence.
|
|
2557
|
-
|
|
2558
|
-
`--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
|
|
2559
|
-
to select exact IDs from that API, regardless of advisory state. Repository
|
|
2560
|
-
lists default to `--github-state published`; `draft`, `triage`, and `closed`
|
|
2561
|
-
require explicit selection. A nondefault state cannot be combined with exact
|
|
2562
|
-
IDs. Global selection requires at least one ID and never lists the advisory
|
|
2563
|
-
database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
|
|
2564
|
-
the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
|
|
2565
|
-
[repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
|
|
2566
|
-
require **Repository security advisories: read**, or the classic `repo` or
|
|
2567
|
-
`repository_advisories:read` scope, plus access to the advisory. Public records
|
|
2568
|
-
need no additional advisory permission.
|
|
2569
|
-
|
|
2570
|
-
Review the saved evidence before local import or Cloud publication, including any
|
|
2571
|
-
selected private advisories. Acquisition failure returns no partial selection.
|
|
2572
|
-
Both destinations report invalid records as exclusions. Cloud publication retains
|
|
2573
|
-
acknowledged receipts if a later batch or readback fails.
|
|
2574
|
-
|
|
2575
|
-
Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
|
|
2576
|
-
patched versions, source status and original JSON. It does not infer an installed
|
|
2577
|
-
version or source location. Global advisories omit a source repository; the
|
|
2578
|
-
explicit local or Cloud destination binds the import for investigation. Repository
|
|
2579
|
-
advisories retain their source repository and check it against the Cloud target
|
|
2580
|
-
or configured local Git remotes when available. Withdrawal remains vendor
|
|
2581
|
-
state, and all imported evidence remains not assessed by Codex. Use a separate
|
|
2582
|
-
source key from code-scanning alerts; shared advisory IDs do not combine source
|
|
2583
|
-
records from different providers.
|
|
2584
|
-
|
|
2585
|
-
In the SDK, call `importGitHubAdvisories()` and `normalizeGitHubAdvisories()`
|
|
2586
|
-
with `prepareNormalizedExternalPublication()` for Cloud or
|
|
2587
|
-
`prepareNormalizedLocalImport()` for local storage as described above.
|
|
2588
|
-
`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
|
|
2589
|
-
`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
|
|
2590
|
-
records. Both forms require `repository: "OWNER/REPO"` as source or target context.
|
|
2591
|
-
|
|
2592
|
-
## Import alerts from the CLI
|
|
2593
|
-
|
|
2594
|
-
```bash
|
|
2595
|
-
codex-security import github example/repository --format json > /path/outside/repository/alerts.json
|
|
2596
|
-
codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
|
|
2597
|
-
codex-security validate /path/outside/repository/alerts.json
|
|
2598
|
-
```
|
|
2599
|
-
|
|
2600
|
-
Run validation from the matching local repository. Import defaults to open alerts
|
|
2601
|
-
on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
|
|
2602
|
-
`--github-ref REF` to filter. Exact alert numbers ignore state and reject a
|
|
2603
|
-
nondefault state.
|
|
2604
|
-
|
|
2605
|
-
Import is read-only and returns an array. Save validation inputs without output
|
|
2606
|
-
filters or token limits. It includes third-party SARIF uploads, does not start
|
|
2607
|
-
Codex, and does not check out code. Each record contains `source`, `repository`,
|
|
2608
|
-
`number`, `url`, and the full upstream `alert`.
|
|
2609
|
-
|
|
2610
|
-
For a disposition per alert, import and validate through the SDK:
|
|
2611
|
-
|
|
2612
|
-
```ts
|
|
2613
|
-
import {
|
|
2614
|
-
CodexSecurity,
|
|
2615
|
-
importGitHubCodeScanningAlerts,
|
|
2616
|
-
} from "@openai/codex-security";
|
|
2617
|
-
|
|
2618
|
-
const findings = await importGitHubCodeScanningAlerts({
|
|
2619
|
-
repository: "example/repository",
|
|
2620
|
-
alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
|
|
2621
|
-
githubToken: process.env["GH_TOKEN"],
|
|
2622
|
-
});
|
|
2623
|
-
|
|
2624
|
-
const security = new CodexSecurity();
|
|
2625
|
-
try {
|
|
2626
|
-
for (const finding of findings) {
|
|
2627
|
-
const result = await security.validate({
|
|
2628
|
-
repositoryPath: "/path/to/repository",
|
|
2629
|
-
finding,
|
|
2630
|
-
});
|
|
2631
|
-
console.log(finding.url, result.disposition, result.outputDir);
|
|
2632
|
-
}
|
|
2633
|
-
} finally {
|
|
2634
|
-
await security.close();
|
|
2635
|
-
}
|
|
2636
|
-
```
|
|
2637
|
-
|
|
2638
|
-
SDK options include `state` (default `"open"`), `ref`, and `signal`.
|
|
2639
|
-
Supply `githubToken` or use `gh auth token` credentials, including GitHub CLI
|
|
2640
|
-
token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
|
|
2641
|
-
The token needs code-scanning read access; access failures reject the import.
|
|
2387
|
+
this repository and contains only the generated commands. Rerun `install-hook`
|
|
2388
|
+
with `--fail-on-severity` set to its original threshold. It recognizes the legacy
|
|
2389
|
+
`npx` hook and supported earlier templates with matching absolute Node and CLI
|
|
2390
|
+
paths. If it refuses to overwrite the verified hook, back it up, remove it and
|
|
2391
|
+
reinstall with the same threshold. Restore the backup if installation fails.
|
|
2392
|
+
The installer uses host Git for the selected repository and respects
|
|
2393
|
+
`core.hooksPath`.
|
|
2642
2394
|
|
|
2643
2395
|
## Validate and patch findings
|
|
2644
2396
|
|
|
@@ -2646,12 +2398,12 @@ Hosts that manage their own model execution can use `codex-security validate --r
|
|
|
2646
2398
|
This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
|
|
2647
2399
|
See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
|
|
2648
2400
|
|
|
2649
|
-
`validate`
|
|
2650
|
-
|
|
2651
|
-
|
|
2652
|
-
|
|
2653
|
-
|
|
2654
|
-
|
|
2401
|
+
`validate` sends the finding to your configured model provider. Its review
|
|
2402
|
+
tools can read the checkout, with network access and web search disabled.
|
|
2403
|
+
The assessment uses source evidence and skips builds, tests, PoCs and application
|
|
2404
|
+
execution. Both `validate` and `patch` accept files or literal text in the
|
|
2405
|
+
current directory. Patching by saved finding or occurrence ID selects the
|
|
2406
|
+
original repository.
|
|
2655
2407
|
|
|
2656
2408
|
Basic patching also works in ordinary directories and Git worktrees before their
|
|
2657
2409
|
first commit. Directory change tracking excludes `.git` and `.svn` metadata.
|
|
@@ -2684,13 +2436,16 @@ native structured output. The CLI also checks the completed JSON before writing
|
|
|
2684
2436
|
stdout; it does not convert a prose assessment into JSON afterward. Invalid JSON
|
|
2685
2437
|
or a schema mismatch fails with exit code 2 and no assessment on stdout.
|
|
2686
2438
|
|
|
2439
|
+
Save the output schema as UTF-8 without a byte-order mark so both the CLI and
|
|
2440
|
+
Codex can read it.
|
|
2441
|
+
|
|
2687
2442
|
Use a self-contained schema in the subset supported by the selected Codex model
|
|
2688
2443
|
and provider. The local checker uses JSON Schema 2020-12, but accepting a schema
|
|
2689
2444
|
locally does not guarantee provider support. Keep the schema small and use it only
|
|
2690
2445
|
when the caller needs structured results. It checks the result's shape, not whether
|
|
2691
2446
|
the security conclusion is correct. Relative paths resolve from the current directory.
|
|
2692
2447
|
|
|
2693
|
-
|
|
2448
|
+
Save the assessment by redirecting stdout:
|
|
2694
2449
|
`codex-security validate findings.json > assessment.md`. For runtime proof, run a
|
|
2695
2450
|
separate reproduction step. Missing facts are reported as proof gaps; a finding
|
|
2696
2451
|
supported by source evidence does not require runtime reproduction.
|
|
@@ -2752,7 +2507,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
|
|
|
2752
2507
|
|
|
2753
2508
|
An illustrative result is below. Actual decisions depend on the repository;
|
|
2754
2509
|
this example assumes a tenant filter exists but deployment routing is unavailable.
|
|
2755
|
-
|
|
2510
|
+
Before updating finding records, [check that each input ID appears exactly
|
|
2511
|
+
once](validate-records.md#check-the-returned-ids), including unresolved
|
|
2512
|
+
candidates.
|
|
2756
2513
|
|
|
2757
2514
|
```json
|
|
2758
2515
|
{
|
|
@@ -2840,8 +2597,13 @@ including code, HTML, and math, retain their original text.
|
|
|
2840
2597
|
GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
|
|
2841
2598
|
```
|
|
2842
2599
|
|
|
2843
|
-
Both providers return `pullRequest: { branch, url }`.
|
|
2844
|
-
|
|
2600
|
+
Both providers return `pullRequest: { branch, url }`. Saved-finding publication
|
|
2601
|
+
includes files changed and verified in the same patch turn. If a selected file
|
|
2602
|
+
already had local edits, the CLI keeps the patch in the working tree for review.
|
|
2603
|
+
The risk assessment and commit use the same verified tree. If staging changed
|
|
2604
|
+
during the run and Git cannot update the index, the CLI reports it and keeps
|
|
2605
|
+
the existing staging.
|
|
2606
|
+
Supplied-issue patching requires a clean tree. If publication fails, run the printed
|
|
2845
2607
|
`patch --resume-pr BRANCH` command in the same repository. It reuses the saved
|
|
2846
2608
|
commit and refuses changed branches. Retain the GitLab host setting on resume.
|
|
2847
2609
|
|
|
@@ -2862,23 +2624,41 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
|
|
|
2862
2624
|
finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
|
|
2863
2625
|
filter for completed Linear issues to check a finished backlog.
|
|
2864
2626
|
|
|
2627
|
+
The CLI selects findings from the workbench and loads their evidence from the
|
|
2628
|
+
saved scan artifacts. It measures the verification request with that evidence
|
|
2629
|
+
included. Large selections use multiple requests without splitting or further
|
|
2630
|
+
truncating any selected finding. The CLI prints verdicts in selection order
|
|
2631
|
+
after every request returns valid results. For these selections the CLI omits
|
|
2632
|
+
per-event progress and update notices so stderr cannot delay the verdicts.
|
|
2633
|
+
|
|
2634
|
+
If a finding would exceed the input limit, `validate`, `patch`, and `verify-fix`
|
|
2635
|
+
put the complete finding data in a temporary file for Codex to search alongside
|
|
2636
|
+
the checkout. A single input file keeps its original text and line breaks.
|
|
2637
|
+
The file remains available until the task finishes and is then removed. The
|
|
2638
|
+
SDK's local `validate()` and `patch()` methods use the same fallback.
|
|
2639
|
+
|
|
2865
2640
|
`--verification-mode static` selects source-only assessment, as described above
|
|
2866
2641
|
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
2867
2642
|
|
|
2868
2643
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
2869
2644
|
`--json` returns structured output. Exit codes are `0` when all findings are
|
|
2870
2645
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|
|
2871
|
-
|
|
2872
|
-
`status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message
|
|
2873
|
-
|
|
2874
|
-
|
|
2875
|
-
|
|
2646
|
+
With `--json` or `--format jsonl`, authentication and execution failures return
|
|
2647
|
+
`status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
|
|
2648
|
+
`--full-output`, these failures use an `ok: false` error envelope. If a saved
|
|
2649
|
+
selection exceeds one request, the CLI sends the failure message only to the
|
|
2650
|
+
structured output. With `--token-count`, `--token-limit`, or `--token-offset`,
|
|
2651
|
+
stderr also carries the diagnostic so it remains available alongside a count
|
|
2652
|
+
or a partial result. Other formats report failures on stderr. Interruptions
|
|
2653
|
+
retain exit codes `130` and `143` without a result.
|
|
2876
2654
|
|
|
2877
2655
|
## Command discovery and integrations
|
|
2878
2656
|
|
|
2879
2657
|
Use `--llms` for the command manifest, `scan --schema --format json` for its
|
|
2880
2658
|
schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
|
|
2881
|
-
`--format toon|json|yaml|jsonl` and `--full-output`.
|
|
2659
|
+
`--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
|
|
2660
|
+
`--filter-output`, `--token-limit`, and `--token-offset` options accept either
|
|
2661
|
+
`--option value` or `--option=value`.
|
|
2882
2662
|
|
|
2883
2663
|
`skills add` syncs generated CLI command guidance; it does not install the full
|
|
2884
2664
|
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
|