@openai/codex-security 0.8.3 → 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 +192 -151
- package/_bundled_plugin/.mcp.json +5 -1
- package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
- package/_bundled_plugin/examples/completed-scan/report.md +11 -8
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
- package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
- package/_bundled_plugin/mcp/helpers.mjs +2 -11
- package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
- package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
- package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/package.json +1 -0
- package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
- package/_bundled_plugin/mcp/server.mjs +2 -11
- package/_bundled_plugin/mcp/server.mjs.br +0 -0
- package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
- package/_bundled_plugin/references/default-severity-rubric.md +9 -4
- package/_bundled_plugin/references/final-report.md +5 -3
- package/_bundled_plugin/references/finding-detail-fields.md +18 -18
- package/_bundled_plugin/references/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/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 +165 -342
- package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +153 -227
- package/_bundled_plugin/scripts/finding_preview.py +20 -0
- 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 +11 -0
- package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
- package/_bundled_plugin/scripts/report_projection.py +81 -43
- package/_bundled_plugin/scripts/review_state.py +8 -2
- package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
- package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
- package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
- package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
- package/_bundled_plugin/scripts/windows_scan_local_files.py +388 -17
- 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 +30 -51
- package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
- package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
- package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
- package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
- package/_bundled_plugin/scripts/workbench/storage.py +71 -7
- package/_bundled_plugin/scripts/workbench_cli.py +30 -12
- package/_bundled_plugin/scripts/workbench_constants.py +10 -0
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
- package/_bundled_plugin/scripts/workbench_db.py +369 -137
- 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 +4 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +12 -12
- 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 +13 -0
- package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
- package/_bundled_plugin/scripts/workbench_scan_history.py +117 -55
- package/_bundled_plugin/scripts/workbench_scan_start.py +83 -24
- package/_bundled_plugin/scripts/workbench_scan_usage.py +644 -68
- package/_bundled_plugin/scripts/workbench_schema.py +44 -55
- package/_bundled_plugin/scripts/workbench_setup.py +13 -1
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
- package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
- package/_bundled_plugin/scripts/workbench_target.py +127 -56
- package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
- package/_bundled_plugin/scripts/workbench_validation.py +43 -3
- package/_bundled_plugin/shared/workbench-history-repairs.json +19 -23
- package/_bundled_plugin/shared/workbench-migrations.json +34 -0
- package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
- package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -1
- package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -25
- package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
- package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
- package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
- package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
- package/dist/api.d.ts +39 -4
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +774 -292
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +4 -6
- 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.map +1 -1
- package/dist/blackduck-findings.js +35 -20
- package/dist/blackduck-findings.js.map +1 -1
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +4 -4
- package/dist/bulk-scan-discovery.js.map +1 -1
- package/dist/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 +1 -9
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +3 -13
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +2 -4
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli.d.ts +11 -5
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1734 -1238
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.js +2 -2
- package/dist/cloud-publish.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 +27 -2
- package/dist/component-scan.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +100 -66
- package/dist/config.js.map +1 -1
- package/dist/continuum-findings.d.ts.map +1 -1
- package/dist/continuum-findings.js +80 -12
- package/dist/continuum-findings.js.map +1 -1
- package/dist/contract-values.d.ts +2 -0
- package/dist/contract-values.d.ts.map +1 -1
- package/dist/contract-values.js +12 -9
- package/dist/contract-values.js.map +1 -1
- package/dist/cost-model.d.ts +13 -1
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +66 -112
- package/dist/cost-model.js.map +1 -1
- package/dist/cost.d.ts +42 -3
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +483 -104
- 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/deduplication/local.d.ts +2 -2
- package/dist/deduplication/local.d.ts.map +1 -1
- package/dist/deduplication/local.js +2 -2
- package/dist/deduplication/local.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 +2 -0
- package/dist/deep-scan.d.ts.map +1 -1
- package/dist/deep-scan.js +28 -4
- package/dist/deep-scan.js.map +1 -1
- package/dist/default-severity-rubric.d.ts +1 -1
- package/dist/default-severity-rubric.d.ts.map +1 -1
- package/dist/default-severity-rubric.js +1 -1
- package/dist/default-severity-rubric.js.map +1 -1
- package/dist/endor-findings.d.ts +3 -1
- package/dist/endor-findings.d.ts.map +1 -1
- package/dist/endor-findings.js +103 -45
- 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 +8 -1
- 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 +7 -6
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts +7 -5
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +337 -89
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +8 -6
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +1318 -258
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +20 -2
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +148 -66
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +15 -3
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js +42 -1
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +5 -1
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +23 -9
- package/dist/external-import-contract.js.map +1 -1
- package/dist/external-import-models.d.ts +1 -1
- package/dist/external-import-models.d.ts.map +1 -1
- package/dist/external-import-models.js.map +1 -1
- package/dist/feedback.d.ts.map +1 -1
- package/dist/feedback.js +5 -4
- package/dist/feedback.js.map +1 -1
- package/dist/finding-prompt.d.ts +5 -0
- package/dist/finding-prompt.d.ts.map +1 -0
- package/dist/finding-prompt.js +32 -0
- package/dist/finding-prompt.js.map +1 -0
- package/dist/findings-client.d.ts +1 -0
- package/dist/findings-client.d.ts.map +1 -1
- package/dist/findings-client.js +27 -3
- package/dist/findings-client.js.map +1 -1
- package/dist/github-advisories.d.ts.map +1 -1
- package/dist/github-advisories.js +0 -2
- package/dist/github-advisories.js.map +1 -1
- package/dist/github-dependabot-findings.d.ts.map +1 -1
- package/dist/github-dependabot-findings.js +15 -4
- 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 +55 -30
- package/dist/github-findings.js.map +1 -1
- package/dist/hosted-git-remotes.d.ts +5 -0
- package/dist/hosted-git-remotes.d.ts.map +1 -0
- package/dist/hosted-git-remotes.js +285 -0
- package/dist/hosted-git-remotes.js.map +1 -0
- package/dist/hosted-git-repository.d.ts +28 -0
- package/dist/hosted-git-repository.d.ts.map +1 -0
- package/dist/hosted-git-repository.js +222 -0
- package/dist/hosted-git-repository.js.map +1 -0
- package/dist/hosted-scan-protocol.js +2 -2
- package/dist/hosted-scan-protocol.js.map +1 -1
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +16 -11
- package/dist/hosted-scan.js.map +1 -1
- package/dist/hosted-scanner-http.d.ts +21 -0
- package/dist/hosted-scanner-http.d.ts.map +1 -0
- package/dist/hosted-scanner-http.js +204 -0
- package/dist/hosted-scanner-http.js.map +1 -0
- package/dist/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 +18 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -2
- package/dist/index.js.map +1 -1
- package/dist/inspector-findings.d.ts.map +1 -1
- package/dist/inspector-findings.js +47 -65
- package/dist/inspector-findings.js.map +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +68 -5
- package/dist/knowledge-base.js.map +1 -1
- package/dist/local-git-metadata.d.ts +1 -1
- package/dist/local-git-metadata.d.ts.map +1 -1
- package/dist/local-git-metadata.js +1 -2
- package/dist/local-git-metadata.js.map +1 -1
- package/dist/multiscan.d.ts +6 -4
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +138 -65
- 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 +17 -13
- package/dist/opengrep-findings.js.map +1 -1
- package/dist/operation-telemetry.d.ts +104 -0
- package/dist/operation-telemetry.d.ts.map +1 -0
- package/dist/operation-telemetry.js +293 -0
- package/dist/operation-telemetry.js.map +1 -0
- package/dist/plugin-python-probe.d.ts +4 -0
- package/dist/plugin-python-probe.d.ts.map +1 -0
- package/dist/plugin-python-probe.js +10 -0
- package/dist/plugin-python-probe.js.map +1 -0
- package/dist/private-finding-import.d.ts +97 -2
- package/dist/private-finding-import.d.ts.map +1 -1
- package/dist/private-finding-import.js +58 -34
- package/dist/private-finding-import.js.map +1 -1
- package/dist/provider-profile.d.ts +1 -1
- package/dist/provider-profile.d.ts.map +1 -1
- package/dist/provider-profile.js +8 -1
- 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/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 +2 -0
- package/dist/reader-selection.d.ts.map +1 -1
- package/dist/reader-selection.js +8 -0
- package/dist/reader-selection.js.map +1 -1
- package/dist/remediation.d.ts +1 -4
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +3 -7
- package/dist/remediation.js.map +1 -1
- package/dist/request-metadata.d.ts +3 -0
- package/dist/request-metadata.d.ts.map +1 -1
- package/dist/request-metadata.js +9 -0
- package/dist/request-metadata.js.map +1 -1
- package/dist/result.d.ts +4 -0
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +1 -1
- package/dist/result.js.map +1 -1
- package/dist/retry-windows-rename.d.ts +8 -0
- package/dist/retry-windows-rename.d.ts.map +1 -0
- package/dist/retry-windows-rename.js +24 -0
- package/dist/retry-windows-rename.js.map +1 -0
- package/dist/runtime.d.ts +20 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +313 -110
- 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 +141 -56
- 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 +60 -15
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +6 -6
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +75 -42
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-executor.d.ts +10 -1
- package/dist/scan-executor.d.ts.map +1 -1
- package/dist/scan-executor.js +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 +9 -19
- 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 +20 -2
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +200 -8
- package/dist/scanner-import.js.map +1 -1
- package/dist/scanner-repository-url.d.ts +4 -1
- package/dist/scanner-repository-url.d.ts.map +1 -1
- package/dist/scanner-repository-url.js +10 -6
- package/dist/scanner-repository-url.js.map +1 -1
- package/dist/security-policy.d.ts +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js.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 +107 -43
- 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 +207 -6
- package/dist/semgrep-platform-findings.d.ts.map +1 -1
- package/dist/semgrep-platform-findings.js +983 -103
- package/dist/semgrep-platform-findings.js.map +1 -1
- 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/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 +93 -70
- 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.map +1 -1
- package/dist/sonar-collector.js +0 -3
- package/dist/sonar-collector.js.map +1 -1
- package/dist/sonar-import.d.ts.map +1 -1
- package/dist/sonar-import.js +2 -4
- package/dist/sonar-import.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 +2 -0
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +56 -20
- 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-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.js +1 -1
- package/dist/validation-records.js.map +1 -1
- package/dist/veracode-findings.d.ts +2 -0
- package/dist/veracode-findings.d.ts.map +1 -1
- package/dist/veracode-findings.js +49 -11
- package/dist/veracode-findings.js.map +1 -1
- package/dist/vertex-pricing.d.ts +8 -0
- package/dist/vertex-pricing.d.ts.map +1 -0
- package/dist/vertex-pricing.js +20 -0
- package/dist/vertex-pricing.js.map +1 -0
- package/dist/windows-path.d.ts +1 -0
- package/dist/windows-path.d.ts.map +1 -1
- package/dist/windows-path.js +26 -1
- package/dist/windows-path.js.map +1 -1
- package/dist/wiz-findings.d.ts +4 -0
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +57 -3
- package/dist/wiz-findings.js.map +1 -1
- package/docs/classify-severity-records.md +27 -12
- package/docs/cli.md +497 -550
- package/docs/dedupe-records.md +44 -24
- package/docs/findings-service.md +66 -39
- package/docs/hosted-remediation.md +14 -7
- package/docs/hosted-scans.md +50 -42
- package/docs/telemetry.md +236 -0
- package/docs/validate-records.md +78 -44
- package/package.json +18 -15
- package/schemas/external-findings.schema.json +3 -1
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
- package/dist/external-imports-feature.d.ts +0 -6
- package/dist/external-imports-feature.d.ts.map +0 -1
- package/dist/external-imports-feature.js +0 -51
- package/dist/external-imports-feature.js.map +0 -1
- package/dist/finding-normalization.d.ts +0 -5
- package/dist/finding-normalization.d.ts.map +0 -1
- package/dist/finding-normalization.js +0 -155
- package/dist/finding-normalization.js.map +0 -1
package/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,10 +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
|
-
[save findings as a scan](#import-findings-as-a-saved-scan), or
|
|
37
|
-
[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.
|
|
38
29
|
- [Inspect saved scans and rerun them](#scan-history-and-reruns),
|
|
39
30
|
[classify severity](#classify-finding-severity), or
|
|
40
31
|
[suggest owners](#suggest-finding-owners).
|
|
@@ -87,7 +78,9 @@ your local browser. Keep SSH connected until login finishes.
|
|
|
87
78
|
### OpenAI credentials
|
|
88
79
|
|
|
89
80
|
Interactive scans ask which credentials to use when both ChatGPT and an
|
|
90
|
-
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
|
|
91
84
|
`OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
|
|
92
85
|
with `--auth`:
|
|
93
86
|
|
|
@@ -104,12 +97,25 @@ the stored login. Patch follow-up assessments and `scan --patch` retain the
|
|
|
104
97
|
chosen authentication. Environment keys do not replace the saved login.
|
|
105
98
|
The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
|
|
106
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
|
+
|
|
107
107
|
Stored OpenAI credentials live in
|
|
108
108
|
`$CODEX_SECURITY_STATE_DIR/codex-home`, or
|
|
109
109
|
`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
|
|
110
110
|
outside the target and every enclosing Git worktree. It also serves providers
|
|
111
111
|
with `requires_openai_auth = true`.
|
|
112
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
|
+
|
|
113
119
|
Codex carries credential-storage, forced-login, and workspace settings from the
|
|
114
120
|
ambient configuration into this home. Managed-device policies still apply;
|
|
115
121
|
workspace-managed policies may require ChatGPT credentials even with an API key.
|
|
@@ -123,8 +129,19 @@ after logout completes.
|
|
|
123
129
|
Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
|
|
124
130
|
`HOME` or `USERPROFILE` environment setting.
|
|
125
131
|
|
|
126
|
-
If
|
|
127
|
-
|
|
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`.
|
|
128
145
|
Some cybersecurity requests and protected findings require
|
|
129
146
|
[Trusted Access for Cyber](https://chatgpt.com/cyber).
|
|
130
147
|
|
|
@@ -142,7 +159,7 @@ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
|
|
|
142
159
|
In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
|
|
143
160
|
to explicitly turn it off.
|
|
144
161
|
The setting carries through saved scan recipes, resumed scans, Deep Scan
|
|
145
|
-
discovery
|
|
162
|
+
discovery workers, and `scan --patch`. Standalone `validate`,
|
|
146
163
|
`patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
|
|
147
164
|
Threads created by these commands retain the setting when resumed in Codex.
|
|
148
165
|
Scans use isolated configuration, so set it on the CLI, SDK client, or project
|
|
@@ -152,8 +169,7 @@ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
|
|
|
152
169
|
an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
|
|
153
170
|
or set top-level `daybreak = true` in the configuration loaded by the runner.
|
|
154
171
|
Deep Scan inherits the active turn's effective access program from its saved
|
|
155
|
-
Codex session, including an explicit Standard selection. Discovery
|
|
156
|
-
workers retain that selection when resumed. If the host does not supply a
|
|
172
|
+
Codex session, including an explicit Standard selection. Discovery workers retain that selection when resumed. If the host does not supply a
|
|
157
173
|
persisted turn context, workers use their runner configuration; CLI and SDK scans
|
|
158
174
|
use the explicit scan settings above.
|
|
159
175
|
|
|
@@ -181,7 +197,7 @@ codex-security scan /path/to/repository \
|
|
|
181
197
|
In the SDK, select your model through `codexOverrides.model` and pass
|
|
182
198
|
`auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
|
|
183
199
|
Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
|
|
184
|
-
The selection reaches discovery
|
|
200
|
+
The selection reaches discovery workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
|
|
185
201
|
for configuration precedence and the API-key feature setting.
|
|
186
202
|
|
|
187
203
|
`access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
|
|
@@ -236,6 +252,15 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
|
|
|
236
252
|
codex-security scan . --provider cheaperinference --model gpt-5.4
|
|
237
253
|
```
|
|
238
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
|
+
|
|
239
264
|
### Amazon Bedrock
|
|
240
265
|
|
|
241
266
|
Use AWS credentials and a region with access to the exact Bedrock model ID:
|
|
@@ -255,6 +280,45 @@ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/
|
|
|
255
280
|
for credential alternatives, restricted-model access, cost estimates, and
|
|
256
281
|
reasoning-summary configuration.
|
|
257
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
|
+
|
|
258
322
|
## Generate a security policy
|
|
259
323
|
|
|
260
324
|
Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
|
|
@@ -430,6 +494,10 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
|
|
|
430
494
|
requested work separately from optional `coverage.openQuestions` follow-up.
|
|
431
495
|
Human-readable output quotes ambiguous paths, while JSON retains their original strings.
|
|
432
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
|
+
|
|
433
501
|
Whole-codebase and path scans also accept ordinary directories, including SVN
|
|
434
502
|
working copies. Their source inventories exclude `.git` and `.svn` metadata.
|
|
435
503
|
|
|
@@ -460,10 +528,17 @@ with every repository.
|
|
|
460
528
|
|
|
461
529
|
Use `--output-dir DIR` to choose where a scan saves its results. The directory
|
|
462
530
|
must be empty and outside the scanned directory and enclosing Git worktree.
|
|
463
|
-
Existing directories keep their permissions
|
|
464
|
-
private to you by default.
|
|
465
|
-
|
|
466
|
-
|
|
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.
|
|
467
542
|
|
|
468
543
|
Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
|
|
469
544
|
optional export fails, the scan can still complete. Use the
|
|
@@ -503,7 +578,9 @@ or JSONL output produce:
|
|
|
503
578
|
{ "status": "failed", "code": "SCAN_FAILED", "message": "..." }
|
|
504
579
|
```
|
|
505
580
|
|
|
506
|
-
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).
|
|
507
584
|
If the scan target changed, the error explains that the results no longer
|
|
508
585
|
represent the current checkout. Retained sealed results remain available under
|
|
509
586
|
`data`, including their manifest, findings, review summary, scan directory, and report
|
|
@@ -515,8 +592,8 @@ selecting an unavailable field can return `null` or omit `data`.
|
|
|
515
592
|
Saved-scan setup failures use the same output shape with
|
|
516
593
|
`SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
|
|
517
594
|
available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
|
|
518
|
-
scan uses `SCAN_IMPORT_FAILED` if the import fails.
|
|
519
|
-
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.
|
|
520
597
|
|
|
521
598
|
Diagnostics stay on stderr. Each command's `--schema --format json` describes
|
|
522
599
|
its successful output and failure codes.
|
|
@@ -526,8 +603,9 @@ See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
|
526
603
|
|
|
527
604
|
Scans already validate findings against local source. Add `--validate` to run
|
|
528
605
|
the existing standalone validation workflow for each reported finding after
|
|
529
|
-
the scan, using the same selected Cyber access program. Validation
|
|
530
|
-
|
|
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
|
|
531
609
|
separate evidence directory; the combined report is saved as
|
|
532
610
|
`<scan-dir>/validation.md`, or a uniquely suffixed report
|
|
533
611
|
if that path already exists. Each completed assessment is saved immediately;
|
|
@@ -571,26 +649,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
|
|
|
571
649
|
fail after registration but before writing its artifacts; investigate those
|
|
572
650
|
failures through its history record and any available logs. When artifacts were
|
|
573
651
|
retained, use the saved results directory returned by `scans show` to inspect
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
| File | What to check
|
|
577
|
-
| -------------------- |
|
|
578
|
-
| `scan-manifest.json` | `scan.status
|
|
579
|
-
| `
|
|
580
|
-
| `
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
`
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
proving that each file was reviewed. An absent path in a surface summary does not
|
|
590
|
-
establish whether it was read, and the scan ID cannot reconstruct evidence that
|
|
591
|
-
was never saved.
|
|
592
|
-
Session logs can help explain failures and tool activity, but do not prove
|
|
593
|
-
complete review either.
|
|
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.
|
|
594
667
|
|
|
595
668
|
For a local plugin scan, ask Codex to open the saved scan and explain its scope,
|
|
596
669
|
exclusions, deferred work, and follow-up questions. CLI history can also locate
|
|
@@ -634,12 +707,13 @@ completeness values to determine scan status or exit codes.
|
|
|
634
707
|
|
|
635
708
|
```bash
|
|
636
709
|
codex-security init
|
|
637
|
-
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
638
710
|
codex-security info -c codex-security.yaml --json
|
|
711
|
+
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
639
712
|
```
|
|
640
713
|
|
|
641
714
|
Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
|
|
642
|
-
|
|
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`,
|
|
643
717
|
`scan-components`, and `info` accept project files. SDK calls and saved reruns
|
|
644
718
|
do not load them automatically.
|
|
645
719
|
|
|
@@ -693,7 +767,8 @@ runs, four with new identities, and two duplicate pairs for testing deduplicatio
|
|
|
693
767
|
Paths and snippets are fictional; repository files remain unchanged.
|
|
694
768
|
|
|
695
769
|
Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
|
|
696
|
-
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.
|
|
697
772
|
Separate matching or deduplication commands still make their usual model calls.
|
|
698
773
|
|
|
699
774
|
Mock mode supports Standard repository, path, and diff scans. It cannot combine
|
|
@@ -772,7 +847,8 @@ individual scan folder.
|
|
|
772
847
|
Failures do not stop other components. Failed scans or
|
|
773
848
|
failed matching return `2`; severity-policy violations return `1`. Retry with
|
|
774
849
|
`--components-file retry-components.json` and a new empty output directory.
|
|
775
|
-
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.
|
|
776
852
|
|
|
777
853
|
`--max-cost` applies per component, excluding planning and matching. `--model`
|
|
778
854
|
and `--effort` also apply to matching; `--auth` applies throughout. Planning and
|
|
@@ -836,11 +912,18 @@ codex-security scan . --mode deep --workers 2 --subagents 0 \
|
|
|
836
912
|
--stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
|
|
837
913
|
```
|
|
838
914
|
|
|
839
|
-
|
|
840
|
-
`--subagents`
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
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.
|
|
844
927
|
|
|
845
928
|
For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
|
|
846
929
|
|
|
@@ -850,6 +933,8 @@ that `subagents` can be zero. Discovery time accepts positive fractional minutes
|
|
|
850
933
|
its default and maximum are 5760 minutes (96 hours). Unlike Standard's
|
|
851
934
|
advisory allowance, the Deep discovery limit is enforced. Resuming a
|
|
852
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.
|
|
853
938
|
`--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
|
|
854
939
|
legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
|
|
855
940
|
hours. Explicit settings override lower-priority configuration across units.
|
|
@@ -898,16 +983,17 @@ executable outside all saved scan targets. If a historical target includes the
|
|
|
898
983
|
available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
|
|
899
984
|
explicit saved scan ID. Exact-path `latest` lookup still works without Git.
|
|
900
985
|
|
|
901
|
-
Repeat `--codex KEY=VALUE` for supported native settings.
|
|
902
|
-
`--codex
|
|
903
|
-
|
|
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.
|
|
904
990
|
|
|
905
991
|
To select a Codex file profile, put its settings in
|
|
906
992
|
`$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
|
|
907
993
|
`CODEX_HOME` is unset), then run:
|
|
908
994
|
|
|
909
995
|
```bash
|
|
910
|
-
npx @openai/codex-security scan . --codex
|
|
996
|
+
npx @openai/codex-security scan . --codex "profile='review'"
|
|
911
997
|
```
|
|
912
998
|
|
|
913
999
|
In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
|
|
@@ -933,11 +1019,11 @@ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
|
|
|
933
1019
|
|
|
934
1020
|
```bash
|
|
935
1021
|
codex-security patch "Security issue" --model gateway-model \
|
|
936
|
-
--codex
|
|
937
|
-
--codex
|
|
938
|
-
--codex
|
|
939
|
-
--codex
|
|
940
|
-
--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'"
|
|
941
1027
|
```
|
|
942
1028
|
|
|
943
1029
|
Set the provider's key environment variable before running. Patching and
|
|
@@ -963,12 +1049,14 @@ publication uses the same request attribution; embedding requests identify
|
|
|
963
1049
|
the package and version in their `User-Agent`.
|
|
964
1050
|
|
|
965
1051
|
These fields provide request attribution for supported inference providers, including
|
|
966
|
-
Bedrock. They do not create a separate telemetry collector
|
|
967
|
-
|
|
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).
|
|
968
1056
|
|
|
969
1057
|
Disable Codex usage analytics and built-in metrics with
|
|
970
|
-
`--codex
|
|
971
|
-
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
|
|
972
1060
|
resumed workers. Selected-profile settings take precedence over root settings.
|
|
973
1061
|
Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
|
|
974
1062
|
workers, including exporter choices and prompt-logging controls.
|
|
@@ -977,32 +1065,43 @@ The setting does not control configured OpenTelemetry exporters, integrations,
|
|
|
977
1065
|
authentication, or CLI update checks. Validation uses isolated configuration;
|
|
978
1066
|
patching and verification preserve ambient project trust.
|
|
979
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
|
+
|
|
980
1080
|
For filesystem and approval behavior, see the
|
|
981
1081
|
[local security model](../README.md#local-security-model).
|
|
982
1082
|
|
|
983
1083
|
### Environment variables
|
|
984
1084
|
|
|
985
|
-
| Variable | Effect
|
|
986
|
-
| --------------------------------------------------------------------------- |
|
|
987
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence.
|
|
988
|
-
| `
|
|
989
|
-
| `
|
|
990
|
-
| `
|
|
991
|
-
| `
|
|
992
|
-
| `
|
|
993
|
-
| `
|
|
994
|
-
| `
|
|
995
|
-
| `
|
|
996
|
-
| `
|
|
997
|
-
| `
|
|
998
|
-
| `
|
|
999
|
-
| `
|
|
1000
|
-
| `
|
|
1001
|
-
| `
|
|
1002
|
-
| `
|
|
1003
|
-
| `
|
|
1004
|
-
| `
|
|
1005
|
-
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
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`. |
|
|
1006
1105
|
|
|
1007
1106
|
Custom Codex executables need thread source attribution for `exec` and
|
|
1008
1107
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -1016,7 +1115,8 @@ works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage
|
|
|
1016
1115
|
### Troubleshooting
|
|
1017
1116
|
|
|
1018
1117
|
Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
|
|
1019
|
-
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,
|
|
1020
1120
|
saved failures, receipts, and patch-risk summaries. Review it for sensitive
|
|
1021
1121
|
information before sharing; upstream Codex output may already be redacted.
|
|
1022
1122
|
|
|
@@ -1025,6 +1125,12 @@ Finish older-version operations before upgrading. Never remove
|
|
|
1025
1125
|
`.codex-security-scan.sqlite3` during an operation. Stop all operations using the
|
|
1026
1126
|
credential home before manually removing an old `.codex-security-scan.lock`.
|
|
1027
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
|
+
|
|
1028
1134
|
If credential-home preparation fails, the error includes the underlying
|
|
1029
1135
|
filesystem diagnostic. For permission or read-only filesystem errors, check
|
|
1030
1136
|
the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
|
|
@@ -1090,10 +1196,13 @@ their own timestamps, window durations, and reset times. These are historical
|
|
|
1090
1196
|
observations, not a live allowance check or scan-only consumption. Empty readings
|
|
1091
1197
|
mean allowance was unavailable. There is no token-to-allowance conversion here.
|
|
1092
1198
|
|
|
1093
|
-
Cost displays use
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
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.
|
|
1097
1206
|
|
|
1098
1207
|
JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
|
|
1099
1208
|
and `context: "unknown"`). A null maximum means no upper estimate is available.
|
|
@@ -1108,13 +1217,25 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
|
|
|
1108
1217
|
Automatic history matching gets at most one extra call with a limit; if more
|
|
1109
1218
|
work is needed, the scan is preserved and you can run `scans match --all`.
|
|
1110
1219
|
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
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.
|
|
1118
1239
|
|
|
1119
1240
|
At 80% of a single interactive scan's limit, the dashboard offers a higher total
|
|
1120
1241
|
budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
|
|
@@ -1224,6 +1345,12 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
|
|
|
1224
1345
|
attempt per pending repository per invocation. Repeating the command continues
|
|
1225
1346
|
the campaign, skips completed results, and starts pending attempts. Occupied
|
|
1226
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.
|
|
1227
1354
|
Completed results are skipped only when their saved contract and seal are valid
|
|
1228
1355
|
and the manifest records a completed scan. Damaged or unsuccessful results get a
|
|
1229
1356
|
new attempt, including with `--recover`, while the old artifacts remain available.
|
|
@@ -1253,10 +1380,12 @@ failed or interrupted attempt:
|
|
|
1253
1380
|
- An unavailable, failed, or canceled scan starts a new attempt at the pinned
|
|
1254
1381
|
revision, preserving old artifacts and checkouts.
|
|
1255
1382
|
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
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.
|
|
1260
1389
|
|
|
1261
1390
|
New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
|
|
1262
1391
|
workers and one recovery/new attempt per repository. A resume connection failure
|
|
@@ -1326,32 +1455,56 @@ Supply the validation prompt again when rerunning.
|
|
|
1326
1455
|
|
|
1327
1456
|
## Import vendor findings locally
|
|
1328
1457
|
|
|
1329
|
-
Choose
|
|
1330
|
-
Each guide shows how to preview its input for a local repository. Follow the [shared procedure](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
|
|
1331
|
-
to confirm the import and read the resulting records.
|
|
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.
|
|
1332
1459
|
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
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. |
|
|
1339
1467
|
|
|
1340
1468
|
For `publish findings`, `--to` is required. With `--to local`, `--repository`
|
|
1341
|
-
takes a checkout path.
|
|
1342
|
-
selects the output format. A local preview
|
|
1343
|
-
|
|
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.
|
|
1474
|
+
|
|
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
|
|
1478
|
+
```
|
|
1479
|
+
|
|
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).
|
|
1482
|
+
|
|
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)
|
|
1344
1484
|
|
|
1345
1485
|
Local readback uses `findings imported [PATH]`. The path defaults to the current
|
|
1346
1486
|
directory. Each imported record starts as `not_assessed`. Unknown revisions and
|
|
1347
1487
|
locations stay unknown. Repository-scoped sources are checked against comparable
|
|
1348
1488
|
configured Git remotes as described in the provider guide. Reimporting the same
|
|
1349
1489
|
source key and finding ID reports created, updated, or unchanged records.
|
|
1350
|
-
Records omitted from the new selection stay stored.
|
|
1351
|
-
|
|
1490
|
+
Records omitted from the new selection stay stored. Local imports can retain
|
|
1491
|
+
evidence that exceeds Cloud's per-finding limits.
|
|
1492
|
+
|
|
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.
|
|
1352
1498
|
|
|
1353
|
-
|
|
1354
|
-
|
|
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.
|
|
1502
|
+
|
|
1503
|
+
## Import Trivy dependency findings
|
|
1504
|
+
|
|
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.
|
|
1355
1508
|
|
|
1356
1509
|
## Import Endor Labs findings
|
|
1357
1510
|
|
|
@@ -1359,31 +1512,85 @@ Use `--provider endor` for one Endor project and context. The
|
|
|
1359
1512
|
[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
|
|
1360
1513
|
SARIF compatibility, and the local preview.
|
|
1361
1514
|
|
|
1515
|
+
## Import SonarQube Cloud issues
|
|
1516
|
+
|
|
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).
|
|
1522
|
+
|
|
1523
|
+
## Import GitHub findings locally or to Cloud
|
|
1524
|
+
|
|
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`.
|
|
1530
|
+
|
|
1531
|
+
### Import GHSA advisories separately
|
|
1532
|
+
|
|
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).
|
|
1537
|
+
|
|
1538
|
+
## Import alerts from the CLI
|
|
1539
|
+
|
|
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.
|
|
1544
|
+
|
|
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"
|
|
1549
|
+
```
|
|
1550
|
+
|
|
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).
|
|
1554
|
+
|
|
1362
1555
|
## Publish findings to Cloud
|
|
1363
1556
|
|
|
1364
|
-
Use
|
|
1365
|
-
|
|
1366
|
-
to preview and confirm it. The following settings and result fields apply to
|
|
1367
|
-
scanner publication across providers.
|
|
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).
|
|
1368
1559
|
|
|
1369
1560
|
### Preview and publish
|
|
1370
1561
|
|
|
1371
|
-
|
|
1372
|
-
repository URL or Cloud
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
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.
|
|
1387
1594
|
|
|
1388
1595
|
### Configure an alternate Cloud deployment
|
|
1389
1596
|
|
|
@@ -1402,23 +1609,62 @@ instructions. API requests always use the API root. The older
|
|
|
1402
1609
|
|
|
1403
1610
|
### Resume interrupted imports
|
|
1404
1611
|
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
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
|
+
|
|
1412
1627
|
[Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
|
|
1413
1628
|
|
|
1414
1629
|
### Results and exit codes
|
|
1415
1630
|
|
|
1416
|
-
| Status | Exit code | Meaning
|
|
1417
|
-
| ------------- | --------- |
|
|
1418
|
-
| `
|
|
1419
|
-
| `
|
|
1420
|
-
| `
|
|
1421
|
-
| `
|
|
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.
|
|
1422
1668
|
|
|
1423
1669
|
With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
|
|
1424
1670
|
Failed and interrupted imports set `ok` to `false` and `error.code` to
|
|
@@ -1426,231 +1672,30 @@ Failed and interrupted imports set `ok` to `false` and `error.code` to
|
|
|
1426
1672
|
Other formats reject `--full-output` before reading the file or contacting
|
|
1427
1673
|
Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
|
|
1428
1674
|
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
unacknowledged. Review `error` before retrying, and check `excluded` for local
|
|
1433
|
-
input errors. Counts include previously acknowledged batches in the same
|
|
1434
|
-
saved submission.
|
|
1435
|
-
|
|
1436
|
-
Progress goes to stderr and JSON results to stdout. Lookups and readback use up
|
|
1437
|
-
to four concurrent requests. Uploads are sequential. Saved receipts and
|
|
1438
|
-
readback verify source-record identity and evidence. Codex assessment and
|
|
1439
|
-
visibility in the shared Cloud Findings view are separate. `cloudUrl`, when
|
|
1440
|
-
available, links to the destination repository in Cloud.
|
|
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.
|
|
1441
1678
|
|
|
1442
|
-
### Import Snyk
|
|
1679
|
+
### Import Snyk findings
|
|
1443
1680
|
|
|
1444
|
-
Use `--provider snyk` for Open Source
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
|
|
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`.
|
|
1448
1685
|
|
|
1449
1686
|
### Import Wiz findings
|
|
1450
1687
|
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1456
|
-
|
|
1457
|
-
The preview shows which Cloud destination will receive the selected records.
|
|
1458
|
-
When the deployment advertises private import for the scanner, the CLI puts a
|
|
1459
|
-
report in the signed-in account’s **private findings inbox**. The preview
|
|
1460
|
-
identifies its format and byte count. For complete Endor findings and Wiz
|
|
1461
|
-
vulnerability JSON exports, the CLI sends the original bytes when Cloud
|
|
1462
|
-
advertises the format and every record matches the reviewed selection. Other
|
|
1463
|
-
selections and in-memory collectors use `security.findings.v1`. The CLI
|
|
1464
|
-
attaches the selected repository and connector as a suggested assessment
|
|
1465
|
-
target. Review the selection, exclusions, source key and destination before
|
|
1466
|
-
confirming.
|
|
1467
|
-
|
|
1468
|
-
The job receipt contains the file and job identifiers and record counts. To
|
|
1469
|
-
share a finding, open it in Cloud, assess it against a pinned repository
|
|
1470
|
-
revision, and explicitly publish a reportable assessment. An import can
|
|
1471
|
-
finish with record errors. Check the error and unprocessed counts in the
|
|
1472
|
-
receipt.
|
|
1473
|
-
|
|
1474
|
-
Repeat the same command to recover an interrupted private import. The CLI
|
|
1475
|
-
checks the report digest, reuses its saved request IDs, and reads an accepted
|
|
1476
|
-
job even when new uploads are disabled. Resetting the inbox requires a new
|
|
1477
|
-
preview and confirmation. Deployments and scanners using the repository
|
|
1478
|
-
publisher continue to show the repository destination and per-finding receipts.
|
|
1479
|
-
An in-flight repository publication resumes on its original protocol.
|
|
1480
|
-
|
|
1481
|
-
#### Select findings and a destination
|
|
1482
|
-
|
|
1483
|
-
Acquire selected findings through an authorized Wiz connection and save the
|
|
1484
|
-
complete native response. The publisher reads the saved file. MCP summaries,
|
|
1485
|
-
Wiz Issues, and local Wiz CLI scan results may have different shapes. Verify
|
|
1486
|
-
the selected response against the format for its finding family. Acquisition
|
|
1487
|
-
against a live Wiz tenant requires separate qualification.
|
|
1488
|
-
|
|
1489
|
-
For saved reports, use the detailed repository package vulnerability export
|
|
1490
|
-
shown in the Wiz guide. Raw Event on Code & Build Scans contains scan
|
|
1491
|
-
metadata. For other CSV exports, see [Convert CSV reports](#convert-csv-reports).
|
|
1492
|
-
|
|
1493
|
-
#### Package vulnerability inputs
|
|
1494
|
-
|
|
1495
|
-
Native package input can be a Wiz JSON vulnerability report, a vulnerability
|
|
1496
|
-
finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
|
|
1497
|
-
with one package record per line. The repository package-vulnerability CSV
|
|
1498
|
-
profile below is also supported. Plain and gzip-compressed files are accepted.
|
|
1499
|
-
A response that advertises another page is rejected. Complete the requested pages
|
|
1500
|
-
or save only the explicitly selected records; retain the named collection for
|
|
1501
|
-
SAST, repository secrets, and IaC.
|
|
1502
|
-
|
|
1503
|
-
For native package records, include `id`, `name`, `detailedName`,
|
|
1504
|
-
`vulnerableAsset.id`, and `vendorSeverity` or `severity`. Retain any available
|
|
1505
|
-
package, image, and repository metadata.
|
|
1506
|
-
|
|
1507
|
-
The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
|
|
1508
|
-
`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
|
|
1509
|
-
this profile; other Wiz report types use different fields.
|
|
1510
|
-
For repository imports, `CloudPlatform` must identify GitHub and
|
|
1511
|
-
`CloudProviderURL` must identify a repository branch. The repository URL must
|
|
1512
|
-
match the selected Cloud repository or, for local import, one of the checkout's
|
|
1513
|
-
Git remotes when configured. This also applies when the parsed findings are saved and
|
|
1514
|
-
read again as normalized JSONL. Other resource types are excluded.
|
|
1515
|
-
|
|
1516
|
-
CSV imports use `ID` as the occurrence identity and retain every parsed field,
|
|
1517
|
-
including unknown columns and quoted multiline values, in `source_data.row`.
|
|
1518
|
-
Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
|
|
1519
|
-
Vendor resolution status stays in the original evidence. The importer does not
|
|
1520
|
-
derive a branch or revision from a tree URL, or treat last-detected time as a
|
|
1521
|
-
record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
|
|
1522
|
-
and duplicate occurrence IDs among otherwise importable records stop the import.
|
|
1523
|
-
Review any excluded records in the preview before publishing.
|
|
1524
|
-
|
|
1525
|
-
Normalized JSONL is also accepted:
|
|
1526
|
-
|
|
1527
|
-
```json
|
|
1528
|
-
{
|
|
1529
|
-
"source_finding_id": "vendor-finding-42",
|
|
1530
|
-
"evidence": {
|
|
1531
|
-
"title": "Vulnerable example package",
|
|
1532
|
-
"severity": "high",
|
|
1533
|
-
"source_data": { "id": "vendor-finding-42" }
|
|
1534
|
-
}
|
|
1535
|
-
}
|
|
1536
|
-
```
|
|
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>
|
|
1537
1693
|
|
|
1538
|
-
Use
|
|
1539
|
-
|
|
1540
|
-
|
|
1541
|
-
|
|
1542
|
-
|
|
1543
|
-
file paths; container and other workload paths remain vendor evidence rather than
|
|
1544
|
-
source-code locations. It does not
|
|
1545
|
-
fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
|
|
1546
|
-
Findings from external network scans are excluded from this package vulnerability
|
|
1547
|
-
mapping.
|
|
1548
|
-
|
|
1549
|
-
#### SAST, repository secrets, and IaC inputs
|
|
1550
|
-
|
|
1551
|
-
For SAST, repository secrets, and IaC, save the documented JSON API collection:
|
|
1552
|
-
|
|
1553
|
-
| Finding family | Collection | Raw occurrence identity |
|
|
1554
|
-
| ------------------ | ---------------------------- | ----------------------- |
|
|
1555
|
-
| SAST | `data.sastFindings.nodes` | `sast:<id>` |
|
|
1556
|
-
| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
|
|
1557
|
-
| IaC | `data.iacFindings.nodes` | `iac:<id>` |
|
|
1558
|
-
|
|
1559
|
-
The collection identifies the mapping. Bare arrays of these raw findings are
|
|
1560
|
-
excluded because their overlapping fields do not identify a family. An export
|
|
1561
|
-
may contain multiple named collections. GraphQL errors and unfinished pages stop
|
|
1562
|
-
the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
|
|
1563
|
-
relationship to source code does not make it a repository secret.
|
|
1564
|
-
|
|
1565
|
-
Each new finding needs a verified source repository URL. Supply `repository.url`
|
|
1566
|
-
in the finding's repository metadata, or include the matching repository inventory
|
|
1567
|
-
in `data.versionControlResources.nodes`. For secrets, repository metadata is under
|
|
1568
|
-
`resource.typedProperties.repository`. The importer joins the inventory's
|
|
1569
|
-
`repository.id` to that source ID and uses `repository.url`; inventory node IDs,
|
|
1570
|
-
`providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
|
|
1571
|
-
must agree with the inventory and with the selected Cloud repository before any
|
|
1572
|
-
finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
|
|
1573
|
-
establishes case-insensitive repository matching on custom GitHub Enterprise
|
|
1574
|
-
hosts. Fresh imports preserve the reported branch name literally. Duplicate
|
|
1575
|
-
entries for one repository ID must agree on their platform and repository URL.
|
|
1576
|
-
For example, this synthetic selection supplies the inventory alongside its SAST
|
|
1577
|
-
collection:
|
|
1578
|
-
|
|
1579
|
-
```json
|
|
1580
|
-
{
|
|
1581
|
-
"data": {
|
|
1582
|
-
"sastFindings": {
|
|
1583
|
-
"nodes": [
|
|
1584
|
-
{
|
|
1585
|
-
"id": "finding-42",
|
|
1586
|
-
"name": "Untrusted query construction",
|
|
1587
|
-
"severity": "HIGH",
|
|
1588
|
-
"repository": { "id": "source-repository-1" },
|
|
1589
|
-
"filePath": "src/query.ts",
|
|
1590
|
-
"startLine": 10,
|
|
1591
|
-
"endLine": 12
|
|
1592
|
-
}
|
|
1593
|
-
]
|
|
1594
|
-
},
|
|
1595
|
-
"versionControlResources": {
|
|
1596
|
-
"nodes": [
|
|
1597
|
-
{
|
|
1598
|
-
"repository": {
|
|
1599
|
-
"id": "source-repository-1",
|
|
1600
|
-
"url": "https://github.com/example/project"
|
|
1601
|
-
}
|
|
1602
|
-
}
|
|
1603
|
-
]
|
|
1604
|
-
}
|
|
1605
|
-
}
|
|
1606
|
-
}
|
|
1607
|
-
```
|
|
1608
|
-
|
|
1609
|
-
#### Preserved evidence
|
|
1610
|
-
|
|
1611
|
-
The adapters preserve each selected raw node exactly in `source_data`. Typed
|
|
1612
|
-
`evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
|
|
1613
|
-
and family-specific evidence:
|
|
1614
|
-
|
|
1615
|
-
| Family | Evidence retained in typed fields |
|
|
1616
|
-
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1617
|
-
| SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
|
|
1618
|
-
| Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
|
|
1619
|
-
| IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
|
|
1620
|
-
|
|
1621
|
-
Vendor status and verdict remain separate from Codex assessment. A secret's
|
|
1622
|
-
introduced commit is not its scanned revision. Missing source revisions and scan
|
|
1623
|
-
IDs stay unknown. A logical IaC resource is retained in the original record and
|
|
1624
|
-
does not establish that it is deployed. Precise original timestamps remain in
|
|
1625
|
-
`source_data`; only an explicit record-update timestamp maps to the whole-second
|
|
1626
|
-
`source_updated_at` field. SAST creation time and IaC last-seen time are not update
|
|
1627
|
-
timestamps.
|
|
1628
|
-
|
|
1629
|
-
#### Convert CSV reports
|
|
1630
|
-
|
|
1631
|
-
Native SAST and secret report downloads can be CSV, including gzip-compressed
|
|
1632
|
-
CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
|
|
1633
|
-
for its actual column headers into normalized JSONL, preserving each original row
|
|
1634
|
-
in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
|
|
1635
|
-
verifying the source repository. Use the same prefixed occurrence ID shown above
|
|
1636
|
-
so API and report imports update the same finding; normalized IDs are accepted
|
|
1637
|
-
exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
|
|
1638
|
-
for a vendor occurrence ID. Missing IDs or severity must be corrected at the
|
|
1639
|
-
source rather than invented.
|
|
1640
|
-
|
|
1641
|
-
For repository-secret reports, select `path` and `lineNumber` for source
|
|
1642
|
-
navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
|
|
1643
|
-
as the introduced commit. The standard secret metadata API does not supply a
|
|
1644
|
-
path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
|
|
1645
|
-
`rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
|
|
1646
|
-
repository/branch metadata. Preserve the original fields; source locations must
|
|
1647
|
-
be repository-relative, and an end line requires a start line. Keep credential
|
|
1648
|
-
values out of the metadata selection; the importer does not retrieve or test
|
|
1649
|
-
credentials or apply remediation instructions.
|
|
1650
|
-
|
|
1651
|
-
Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
|
|
1652
|
-
integer range is rejected; export those values as strings to preserve them
|
|
1653
|
-
exactly. Invalid records appear in `excluded` with their source ID and reason.
|
|
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).
|
|
1654
1699
|
|
|
1655
1700
|
### Publish completed scans
|
|
1656
1701
|
|
|
@@ -1729,15 +1774,16 @@ Choose a destination authorized to receive that content. Local history records
|
|
|
1729
1774
|
successful issue IDs separately from sealed artifacts. The CLI and the plugin's
|
|
1730
1775
|
finding-tracking workflow share these records when using the same Codex Security
|
|
1731
1776
|
state directory. Accepted writes remain recorded even if a later issue read fails.
|
|
1732
|
-
The shared-history migration preserves existing Linear receipts and replaces their
|
|
1733
|
-
old table. Upgrade CLI and plugin installations together when they share state;
|
|
1734
|
-
older publishers cannot write to the migrated database.
|
|
1735
1777
|
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
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.
|
|
1741
1787
|
|
|
1742
1788
|
```ts
|
|
1743
1789
|
import { publishScan } from "@openai/codex-security";
|
|
@@ -2024,9 +2070,21 @@ history. Inspect its saved status before choosing resume or rerun, and supply
|
|
|
2024
2070
|
the original custom prompt files for reruns. Structured history and log output
|
|
2025
2071
|
and command selection defaults are unchanged.
|
|
2026
2072
|
|
|
2027
|
-
|
|
2028
|
-
|
|
2029
|
-
|
|
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:
|
|
2030
2088
|
|
|
2031
2089
|
```bash
|
|
2032
2090
|
codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
|
|
@@ -2048,11 +2106,16 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
|
2048
2106
|
writable, and outside the target repository. Session logs may contain sensitive
|
|
2049
2107
|
data even though scan recipes do not store credentials.
|
|
2050
2108
|
|
|
2051
|
-
|
|
2052
|
-
|
|
2053
|
-
|
|
2054
|
-
|
|
2055
|
-
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.
|
|
2056
2119
|
|
|
2057
2120
|
### Resuming an interrupted Deep Scan
|
|
2058
2121
|
|
|
@@ -2095,6 +2158,13 @@ One comparison ID is compared with the latest completed scan.
|
|
|
2095
2158
|
codex-security scans match --all --force --model gpt-6.1-sol --effort high
|
|
2096
2159
|
```
|
|
2097
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
|
+
|
|
2098
2168
|
Only high-confidence root-cause matches are grouped. Uncertain and related
|
|
2099
2169
|
findings remain separate. Rebuilding retains stable identities, triage, and
|
|
2100
2170
|
sealed artifacts; interruption preserves completed comparisons. Model/effort
|
|
@@ -2292,9 +2362,11 @@ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/exa
|
|
|
2292
2362
|
|
|
2293
2363
|
### Local pre-commit checks
|
|
2294
2364
|
|
|
2295
|
-
|
|
2296
|
-
failure or findings at
|
|
2297
|
-
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.
|
|
2298
2370
|
|
|
2299
2371
|
Install the CLI outside the target repository and run that copy directly. `npx`
|
|
2300
2372
|
can select a repository-local package. Before installation, inspect:
|
|
@@ -2312,148 +2384,13 @@ codex-security install-hook /path/to/repository
|
|
|
2312
2384
|
```
|
|
2313
2385
|
|
|
2314
2386
|
To migrate an existing generated hook, verify it is a regular file used only by
|
|
2315
|
-
this repository and contains only the generated
|
|
2316
|
-
|
|
2317
|
-
|
|
2318
|
-
|
|
2319
|
-
|
|
2320
|
-
|
|
2321
|
-
|
|
2322
|
-
|
|
2323
|
-
The [SonarQube Cloud guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md) covers live collection, repository
|
|
2324
|
-
binding, saved issue-search pages, and replay. Unlike a saved-file
|
|
2325
|
-
`publish findings` preview, `import sonar --dry-run` writes a private capture
|
|
2326
|
-
and returns its path. Confirm with the capture from the preview for the intended
|
|
2327
|
-
destination. A Cloud confirmation imports the selected issues locally and
|
|
2328
|
-
publishes them to Cloud. Use `--full-output` with `--format json` or
|
|
2329
|
-
`--format jsonl` for a structured success or error envelope.
|
|
2330
|
-
|
|
2331
|
-
## Import GitHub findings locally or to Cloud
|
|
2332
|
-
|
|
2333
|
-
Choose the [code scanning](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
|
|
2334
|
-
[Dependabot](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md), or
|
|
2335
|
-
[GitHub Security Advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md) guide to acquire
|
|
2336
|
-
and preview findings. All three use `--provider github`. Keep a separate source
|
|
2337
|
-
key for each family. Saving locally or publishing to Cloud requires the
|
|
2338
|
-
[external-import opt-in](#import-vendor-findings-locally).
|
|
2339
|
-
|
|
2340
|
-
The code-scanning and advisory CLI collectors use `gh` to authenticate for
|
|
2341
|
-
`GH_HOST` (default `github.com`). A GitHub
|
|
2342
|
-
plugin connection can select alerts but does not sign the CLI in.
|
|
2343
|
-
Collection retains the selected ref's instance. Branches keep separate
|
|
2344
|
-
evidence. An alert-wide dismissal takes precedence over the selected instance's
|
|
2345
|
-
open or fixed state. Missing security severity stays `unknown`. See
|
|
2346
|
-
[code-scanning access requirements](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository).
|
|
2347
|
-
|
|
2348
|
-
The SDK offers the same preview and publication boundary for Cloud:
|
|
2349
|
-
|
|
2350
|
-
```ts
|
|
2351
|
-
import {
|
|
2352
|
-
importGitHubCodeScanningAlerts,
|
|
2353
|
-
normalizeGitHubCodeScanningAlerts,
|
|
2354
|
-
prepareNormalizedExternalPublication,
|
|
2355
|
-
} from "@openai/codex-security";
|
|
2356
|
-
|
|
2357
|
-
const alerts = await importGitHubCodeScanningAlerts({
|
|
2358
|
-
repository: "example/project",
|
|
2359
|
-
});
|
|
2360
|
-
const prepared = await prepareNormalizedExternalPublication(
|
|
2361
|
-
normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
|
|
2362
|
-
{
|
|
2363
|
-
provider: "github",
|
|
2364
|
-
repository: "https://github.com/example/project",
|
|
2365
|
-
sourceKey: "github.com/example/project/code-scanning",
|
|
2366
|
-
},
|
|
2367
|
-
);
|
|
2368
|
-
console.log(prepared.preview);
|
|
2369
|
-
// After reviewing the preview:
|
|
2370
|
-
const receipt = await prepared.publish();
|
|
2371
|
-
```
|
|
2372
|
-
|
|
2373
|
-
For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
|
|
2374
|
-
the original alerts to retain evidence that exceeds Cloud limits. Pass the result
|
|
2375
|
-
to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
|
|
2376
|
-
its preview, and call `import()`. Alternatively, pass the saved alert file directly
|
|
2377
|
-
to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
|
|
2378
|
-
|
|
2379
|
-
### Import GHSA advisories separately
|
|
2380
|
-
|
|
2381
|
-
See the [GitHub Security Advisories guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md)
|
|
2382
|
-
to save repository advisories or selected global database records and preview
|
|
2383
|
-
them for the chosen destination. Advisories report affected ranges and
|
|
2384
|
-
available fixes. Verify installed dependencies and applicability in the
|
|
2385
|
-
destination repository separately.
|
|
2386
|
-
|
|
2387
|
-
Repository lists default to published advisories. When selecting exact IDs, omit
|
|
2388
|
-
`--github-state`. Selecting a repository advisory by its GHSA ID can return a
|
|
2389
|
-
draft if you have access.
|
|
2390
|
-
Global collection requires one or more explicit IDs.
|
|
2391
|
-
Acquisition failure yields no partial selection. Access to private or
|
|
2392
|
-
unpublished repository advisories requires the repository advisory read
|
|
2393
|
-
permission and access to the record. See
|
|
2394
|
-
[GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
|
|
2395
|
-
|
|
2396
|
-
In the SDK, collect the advisories with `importGitHubAdvisories()`. For Cloud,
|
|
2397
|
-
pass `normalizeGitHubAdvisories(advisories, "cloud")` to
|
|
2398
|
-
`prepareNormalizedExternalPublication()`. For local storage, pass
|
|
2399
|
-
`normalizeGitHubAdvisories(advisories, "local")` to `prepareNormalizedLocalImport()`.
|
|
2400
|
-
`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
|
|
2401
|
-
`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
|
|
2402
|
-
records. Both forms require `repository: "OWNER/REPO"` as source or target context.
|
|
2403
|
-
Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
|
|
2404
|
-
|
|
2405
|
-
## Import alerts from the CLI
|
|
2406
|
-
|
|
2407
|
-
```bash
|
|
2408
|
-
codex-security import github example/repository --format json > /path/outside/repository/alerts.json
|
|
2409
|
-
codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
|
|
2410
|
-
codex-security validate /path/outside/repository/alerts.json
|
|
2411
|
-
```
|
|
2412
|
-
|
|
2413
|
-
Run validation from the matching local repository. Import defaults to open alerts
|
|
2414
|
-
on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
|
|
2415
|
-
`--github-ref REF` to filter. Exact alert numbers ignore state and reject a
|
|
2416
|
-
nondefault state.
|
|
2417
|
-
|
|
2418
|
-
Import is read-only and returns an array. Save validation inputs without output
|
|
2419
|
-
filters or token limits. It includes third-party SARIF uploads, does not start
|
|
2420
|
-
Codex, and does not check out code. Each record contains `source`, `repository`,
|
|
2421
|
-
`number`, `url`, and the full upstream `alert`.
|
|
2422
|
-
|
|
2423
|
-
For a disposition per alert, import and validate through the SDK:
|
|
2424
|
-
|
|
2425
|
-
```ts
|
|
2426
|
-
import {
|
|
2427
|
-
CodexSecurity,
|
|
2428
|
-
importGitHubCodeScanningAlerts,
|
|
2429
|
-
} from "@openai/codex-security";
|
|
2430
|
-
|
|
2431
|
-
const findings = await importGitHubCodeScanningAlerts({
|
|
2432
|
-
repository: "example/repository",
|
|
2433
|
-
alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
|
|
2434
|
-
githubHost: "github.com",
|
|
2435
|
-
githubToken: process.env["GH_TOKEN"],
|
|
2436
|
-
});
|
|
2437
|
-
|
|
2438
|
-
const security = new CodexSecurity();
|
|
2439
|
-
try {
|
|
2440
|
-
for (const finding of findings) {
|
|
2441
|
-
const result = await security.validate({
|
|
2442
|
-
repositoryPath: "/path/to/repository",
|
|
2443
|
-
finding,
|
|
2444
|
-
});
|
|
2445
|
-
console.log(finding.url, result.disposition, result.outputDir);
|
|
2446
|
-
}
|
|
2447
|
-
} finally {
|
|
2448
|
-
await security.close();
|
|
2449
|
-
}
|
|
2450
|
-
```
|
|
2451
|
-
|
|
2452
|
-
SDK options include `state` (default `"open"`), `ref`, and `signal`.
|
|
2453
|
-
Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
|
|
2454
|
-
If you omit the token, the SDK asks the GitHub CLI for credentials, including
|
|
2455
|
-
its supported token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
|
|
2456
|
-
The token needs code-scanning read access; access failures reject the import.
|
|
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`.
|
|
2457
2394
|
|
|
2458
2395
|
## Validate and patch findings
|
|
2459
2396
|
|
|
@@ -2461,12 +2398,12 @@ Hosts that manage their own model execution can use `codex-security validate --r
|
|
|
2461
2398
|
This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
|
|
2462
2399
|
See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
|
|
2463
2400
|
|
|
2464
|
-
`validate`
|
|
2465
|
-
|
|
2466
|
-
|
|
2467
|
-
|
|
2468
|
-
|
|
2469
|
-
|
|
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.
|
|
2470
2407
|
|
|
2471
2408
|
Basic patching also works in ordinary directories and Git worktrees before their
|
|
2472
2409
|
first commit. Directory change tracking excludes `.git` and `.svn` metadata.
|
|
@@ -2508,7 +2445,7 @@ locally does not guarantee provider support. Keep the schema small and use it on
|
|
|
2508
2445
|
when the caller needs structured results. It checks the result's shape, not whether
|
|
2509
2446
|
the security conclusion is correct. Relative paths resolve from the current directory.
|
|
2510
2447
|
|
|
2511
|
-
|
|
2448
|
+
Save the assessment by redirecting stdout:
|
|
2512
2449
|
`codex-security validate findings.json > assessment.md`. For runtime proof, run a
|
|
2513
2450
|
separate reproduction step. Missing facts are reported as proof gaps; a finding
|
|
2514
2451
|
supported by source evidence does not require runtime reproduction.
|
|
@@ -2570,7 +2507,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
|
|
|
2570
2507
|
|
|
2571
2508
|
An illustrative result is below. Actual decisions depend on the repository;
|
|
2572
2509
|
this example assumes a tenant filter exists but deployment routing is unavailable.
|
|
2573
|
-
|
|
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.
|
|
2574
2513
|
|
|
2575
2514
|
```json
|
|
2576
2515
|
{
|
|
@@ -2658,8 +2597,13 @@ including code, HTML, and math, retain their original text.
|
|
|
2658
2597
|
GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
|
|
2659
2598
|
```
|
|
2660
2599
|
|
|
2661
|
-
Both providers return `pullRequest: { branch, url }`.
|
|
2662
|
-
|
|
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
|
|
2663
2607
|
`patch --resume-pr BRANCH` command in the same repository. It reuses the saved
|
|
2664
2608
|
commit and refuses changed branches. Retain the GitLab host setting on resume.
|
|
2665
2609
|
|
|
@@ -2687,10 +2631,11 @@ truncating any selected finding. The CLI prints verdicts in selection order
|
|
|
2687
2631
|
after every request returns valid results. For these selections the CLI omits
|
|
2688
2632
|
per-event progress and update notices so stderr cannot delay the verdicts.
|
|
2689
2633
|
|
|
2690
|
-
If
|
|
2691
|
-
the
|
|
2692
|
-
|
|
2693
|
-
|
|
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.
|
|
2694
2639
|
|
|
2695
2640
|
`--verification-mode static` selects source-only assessment, as described above
|
|
2696
2641
|
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
@@ -2711,7 +2656,9 @@ retain exit codes `130` and `143` without a result.
|
|
|
2711
2656
|
|
|
2712
2657
|
Use `--llms` for the command manifest, `scan --schema --format json` for its
|
|
2713
2658
|
schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
|
|
2714
|
-
`--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`.
|
|
2715
2662
|
|
|
2716
2663
|
`skills add` syncs generated CLI command guidance; it does not install the full
|
|
2717
2664
|
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
|