@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/dedupe-records.md
CHANGED
|
@@ -6,25 +6,26 @@ Findings API. It performs no authentication, update checks, local Codex launches
|
|
|
6
6
|
candidate retrieval, or persistence. The host owns repository authorization,
|
|
7
7
|
model execution, sessions, credentials, cancellation of remote work, and cleanup.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## A minimal exchange
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
11
|
+
To check the connection before dispatching reviews, send an empty batch as
|
|
12
|
+
one line on the CLI's stdin. Keep the pipe open.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
async run(request, { signal } = {}) {
|
|
17
|
-
return await hostReview(request, signal); // Return the structured answer.
|
|
18
|
-
},
|
|
19
|
-
},
|
|
20
|
-
signal: controller.signal,
|
|
21
|
-
});
|
|
14
|
+
```text
|
|
15
|
+
{"jsonrpc":"2.0","id":"run-1","method":"run","params":{"version":1,"observations":[],"candidateRelationships":[]}}
|
|
22
16
|
```
|
|
23
17
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
18
|
+
The CLI writes one line to stdout with the same run ID. With no candidates,
|
|
19
|
+
this exchange makes zero model calls.
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
{"jsonrpc":"2.0","id":"run-1","result":{"version":1,"status":"completed","groups":[],"unresolved":[]}}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
For a populated batch, supply observations and candidate relationships as below.
|
|
26
|
+
[Answer each review](#review-exchange) using its own request ID, then read the
|
|
27
|
+
[terminal result](#final-response-and-persistence) using your original run ID.
|
|
28
|
+
The [Python host](#runnable-python-fake-host) demonstrates the complete exchange.
|
|
28
29
|
|
|
29
30
|
## Input and identities
|
|
30
31
|
|
|
@@ -36,7 +37,8 @@ from -9007199254740991 through 9007199254740991 and are compared without coercio
|
|
|
36
37
|
Use strings for larger numeric identifiers. Review IDs are generated strings;
|
|
37
38
|
request and response ID namespaces are directional.
|
|
38
39
|
|
|
39
|
-
The
|
|
40
|
+
The following messages are expanded for reading. Serialize each object to a
|
|
41
|
+
single line before writing it to the pipe. For a populated batch, the host sends:
|
|
40
42
|
|
|
41
43
|
```json
|
|
42
44
|
{
|
|
@@ -131,8 +133,7 @@ and beneficiaries are nonempty. Candidate-only observations never become
|
|
|
131
133
|
beneficiaries, even when selected as the final representative. An incoming
|
|
132
134
|
observation participating in several reviews appears in each review's metadata.
|
|
133
135
|
|
|
134
|
-
|
|
135
|
-
Older hosts may ignore it; hosts that require attribution must validate it
|
|
136
|
+
Hosts that use attribution for accounting must validate it
|
|
136
137
|
and reject missing or unknown identities before executing a review. Persist the
|
|
137
138
|
request UUID and attribution before provisioning remote execution. The host owns
|
|
138
139
|
accounting and any partitioning of invocation anchors by origin scan; the CLI
|
|
@@ -203,16 +204,11 @@ For failure or an inconclusive review, send an explicit error:
|
|
|
203
204
|
A host error ends the review without another submission. Invalid final model
|
|
204
205
|
answers, missing final decisions, and host errors make the whole batch unresolved;
|
|
205
206
|
previous successful reviews in that run do not become persistence decisions.
|
|
206
|
-
The
|
|
207
|
+
The CLI treats a validated `DISTINCT` as a nonmatch, when
|
|
207
208
|
supplied finding content is insufficient to establish a shared correction. If the host considers the review
|
|
208
209
|
inconclusive, it must return an error rather than manufacture a `DISTINCT` answer.
|
|
209
210
|
No new `INCONCLUSIVE` model decision is introduced.
|
|
210
211
|
|
|
211
|
-
The existing screening, independent pair review, contradiction-aware grouping, and
|
|
212
|
-
severity-based representative selection are reused. No local review checkpoints
|
|
213
|
-
are read or written in records mode. Local saved-scan execution retains its
|
|
214
|
-
existing tool-submission validation and workflow checkpoints.
|
|
215
|
-
|
|
216
212
|
### Continuing a review
|
|
217
213
|
|
|
218
214
|
A `review.run` request with `supportsContinuation: true` can receive the result
|
|
@@ -278,6 +274,30 @@ observation as unique. Cross-run replay/idempotency and reconciliation of remote
|
|
|
278
274
|
work whose acceptance is uncertain belong to the host; a new process creates
|
|
279
275
|
new review IDs and does not resume earlier remote execution.
|
|
280
276
|
|
|
277
|
+
## TypeScript integration
|
|
278
|
+
|
|
279
|
+
The SDK accepts the same input and returns the result directly. In this host
|
|
280
|
+
integration, provide an authorized `reviewRunner` that executes the request
|
|
281
|
+
and returns the structured answer. Pass an `AbortSignal` to support cancellation.
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
import {
|
|
285
|
+
deduplicateRecords,
|
|
286
|
+
type DeduplicateRecordsInput,
|
|
287
|
+
type DeduplicationReviewRunner,
|
|
288
|
+
} from "@openai/codex-security";
|
|
289
|
+
|
|
290
|
+
export function reviewDuplicates(
|
|
291
|
+
input: DeduplicateRecordsInput,
|
|
292
|
+
reviewRunner: DeduplicationReviewRunner,
|
|
293
|
+
signal: AbortSignal,
|
|
294
|
+
) {
|
|
295
|
+
return deduplicateRecords(input, { reviewRunner, signal });
|
|
296
|
+
}
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
`DeduplicateRecordsResult` and `DeduplicationReviewRequest` are also exported.
|
|
300
|
+
|
|
281
301
|
## Cancellation and protocol failures
|
|
282
302
|
|
|
283
303
|
To cancel the active run, send a notification:
|
package/docs/findings-service.md
CHANGED
|
@@ -1,23 +1,31 @@
|
|
|
1
1
|
# Findings storage and deduplication
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
Deduplication reads that database directly; no local HTTP service is needed.
|
|
5
|
-
The CLI can also publish to and deduplicate against independently operated
|
|
6
|
-
compatible endpoints through explicit `--findings-url` settings.
|
|
3
|
+
Choose where the duplicate candidates and groups should live.
|
|
7
4
|
|
|
8
|
-
|
|
5
|
+
- **Local workbench.** The CLI stores saved scans and findings in SQLite.
|
|
6
|
+
Use this default to search the current checkout's stored findings. New
|
|
7
|
+
embeddings and fresh reviews still need provider access.
|
|
8
|
+
- **Independently operated endpoint.** To search a shared corpus, use a
|
|
9
|
+
[compatible findings endpoint](#compatible-endpoint-contract) that already
|
|
10
|
+
holds your candidates. [Publish the scan](#publish-a-scan) or import its
|
|
11
|
+
findings into the service with the matching `repositoryId` first.
|
|
9
12
|
|
|
10
13
|
## Deduplicate a scan
|
|
11
14
|
|
|
12
|
-
|
|
13
|
-
publication step is required:
|
|
15
|
+
For the local workbench, run:
|
|
14
16
|
|
|
15
17
|
```bash
|
|
16
18
|
codex-security dedupe --scan SCAN_ID --json
|
|
17
19
|
```
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
+
For a shared corpus, supply the base URL of your endpoint:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Replace `SCAN_ID` with the ID of a completed scan, or use `latest` for the
|
|
28
|
+
current repository. For local setup, see [embedding credentials and backups](#local-embeddings-and-backups).
|
|
21
29
|
|
|
22
30
|
The CLI prepares missing or stale embeddings for the local repository's stored
|
|
23
31
|
findings, searches them, and saves reviewed duplicate groups in the workbench
|
|
@@ -36,24 +44,15 @@ select logical findings using their current stored bodies; dedupe does not
|
|
|
36
44
|
replace newer bodies with old scan artifacts. A local database does not include
|
|
37
45
|
findings stored only in a separate Docker volume or remote service.
|
|
38
46
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
A scan or workflow selector is required. `--scan`
|
|
47
|
-
accepts a full ID, unique prefix, or `latest` for the current repository. The
|
|
48
|
-
scan must be complete, with sealed artifacts and a local checkout available.
|
|
47
|
+
A scan or workflow selector is required. `--scan` also accepts a unique ID
|
|
48
|
+
prefix. The scan must have sealed artifacts and a local checkout available.
|
|
49
49
|
Local `latest` lookup matches the exact checkout path without Git. Matching
|
|
50
50
|
across worktrees or clones additionally requires a Git executable outside all
|
|
51
51
|
saved scan targets. If an unrelated historical target includes the available
|
|
52
52
|
Git installation, use `codex-security dedupe --scan SCAN_ID` with an explicit
|
|
53
53
|
saved scan ID instead.
|
|
54
54
|
By default, candidates come from its manifest's `scan.target.targetId`. Use
|
|
55
|
-
`--all-repositories` to search the whole selected database or service.
|
|
56
|
-
`--findings-url` retains the existing remote lookup and publication behavior.
|
|
55
|
+
`--all-repositories` to search the whole selected database or service.
|
|
57
56
|
|
|
58
57
|
```typescript
|
|
59
58
|
import { deduplicateScan } from "@openai/codex-security";
|
|
@@ -67,6 +66,21 @@ const result = await deduplicateScan("scan_example_001", {
|
|
|
67
66
|
console.log(result.duplicateGroups);
|
|
68
67
|
```
|
|
69
68
|
|
|
69
|
+
Both saved-scan APIs accept `onEmbeddingUsage` for the built-in local adapter.
|
|
70
|
+
It receives one observation per processed batch: model, tokenized input count
|
|
71
|
+
(including chunks of long findings), provider-reported input tokens, outcome,
|
|
72
|
+
and duration in milliseconds. `inputTokens: null` means usage was unavailable,
|
|
73
|
+
including responses that omit usage; it does not mean zero tokens. Cached
|
|
74
|
+
embeddings generate no new observations. Observers are best effort: throws,
|
|
75
|
+
rejections, and pending promises do not fail or block embedding work. No finding
|
|
76
|
+
text, vectors, credentials, or endpoint is included.
|
|
77
|
+
|
|
78
|
+
Embedding tokens remain separate from scan model-token and cost totals. A batch
|
|
79
|
+
can contain several HTTP attempts when the local adapter retries, and its
|
|
80
|
+
observation only includes usage from the final response. Remote services and
|
|
81
|
+
custom embedding bindings own their usage reporting; set an observer directly on
|
|
82
|
+
`OpenAiFindingEmbedder` when using it in a custom binding.
|
|
83
|
+
|
|
70
84
|
For a different embedding provider or model, both saved-scan SDK methods accept
|
|
71
85
|
an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
|
|
72
86
|
`{ model, vector }` per input finding, in input order. The adapter owns its
|
|
@@ -210,8 +224,8 @@ Empty scans and findings without eligible candidates make no review calls.
|
|
|
210
224
|
Other scans can require multiple calls per finding. Completion means the
|
|
211
225
|
retrieval, review, and group write finished; it does not mean that every pair
|
|
212
226
|
in the database was compared. Use Ctrl-C or SIGTERM in the CLI, or an
|
|
213
|
-
`AbortSignal` in the SDK, to cancel.
|
|
214
|
-
|
|
227
|
+
`AbortSignal` in the SDK, to cancel. Deep Scan merges its own workers’ findings
|
|
228
|
+
locally.
|
|
215
229
|
|
|
216
230
|
### Resume a findings workflow
|
|
217
231
|
|
|
@@ -326,10 +340,25 @@ const receipt = await publishScanToCustom("/path/to/completed-scan", {
|
|
|
326
340
|
console.log(receipt.repositoryId, receipt.findingIds);
|
|
327
341
|
```
|
|
328
342
|
|
|
343
|
+
The Linear and custom publication SDKs return a content-free `telemetry`
|
|
344
|
+
summary and accept `onTelemetry` for outcomes, including preparation failure and
|
|
345
|
+
cancellation. Existing Linear receipts and custom workflow results retain this
|
|
346
|
+
summary. It includes an attempt ID, destination family, duration, outcome, and
|
|
347
|
+
counts of selected, submitted, created, reused, acknowledged, and failed findings.
|
|
348
|
+
Submitted counts describe findings handed to publication, not HTTP attempts.
|
|
349
|
+
`null` denotes unknown counts; in particular, the custom bulk API acknowledges
|
|
350
|
+
IDs without distinguishing creation from upsert. Unknown mutation outcomes are
|
|
351
|
+
`indeterminate`, and dry runs have `outcome: "preview"` and `attempted: false`.
|
|
352
|
+
Reusing a saved custom workflow receipt produces a new attempt summary with no
|
|
353
|
+
submitted findings. Hosts should group repeated receipt snapshots by attempt ID
|
|
354
|
+
and use the latest observation. Callback failures do not change publication
|
|
355
|
+
results, and these callbacks add no network destination or separate files.
|
|
356
|
+
|
|
329
357
|
## Compatible endpoint contract
|
|
330
358
|
|
|
331
|
-
The
|
|
332
|
-
|
|
359
|
+
The HTTP client appends these paths to the configured base URL, preserving any base path.
|
|
360
|
+
It follows redirects within that origin (scheme, host, and port). If the service
|
|
361
|
+
moves to another origin, set `--findings-url` to its new base URL.
|
|
333
362
|
|
|
334
363
|
| Method | Path | Response |
|
|
335
364
|
| ------ | --------------------------------------- | ------------------------------------------------------------------------ |
|
|
@@ -341,8 +370,8 @@ Publication sends `{findings, repositoryId}`. Candidate requests include either
|
|
|
341
370
|
`repositoryId` or `allRepositories=true`. Group writes send
|
|
342
371
|
`{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
|
|
343
372
|
workflow retries. Both POST endpoints must persist their writes before
|
|
344
|
-
acknowledging them and return a JSON body.
|
|
345
|
-
|
|
373
|
+
acknowledging them and return a JSON body. Supply your service’s base URL to use
|
|
374
|
+
these endpoints. With no URL, deduplication uses local SQLite.
|
|
346
375
|
|
|
347
376
|
SDK findings client failures preserve the endpoint's error code and message with
|
|
348
377
|
the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
|
|
@@ -352,20 +381,16 @@ behavior uses the HTTP status and `Retry-After`.
|
|
|
352
381
|
|
|
353
382
|
### Local service removal
|
|
354
383
|
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
384
|
+
If you previously used the bundled HTTP service, back up the SQLite state
|
|
385
|
+
directory or service volume. Set `CODEX_SECURITY_STATE_DIR` to the directory
|
|
386
|
+
that contains the existing database to keep using its saved scans, findings,
|
|
387
|
+
and duplicate groups. For clients that need HTTP, configure a service that
|
|
388
|
+
implements the [endpoint contract](#compatible-endpoint-contract).
|
|
360
389
|
|
|
361
|
-
|
|
362
|
-
groups are retained. No data migration or deletion is performed. Keep any
|
|
363
|
-
existing service volume or state directory and back it up before changing
|
|
364
|
-
deployments; local deduplication uses the database selected by
|
|
365
|
-
`CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
|
|
390
|
+
### Use SQLite from the SDK
|
|
366
391
|
|
|
367
|
-
`@openai/codex-security/server`
|
|
368
|
-
`SqliteFindingsStore`, and their storage types
|
|
392
|
+
`@openai/codex-security/server` exports `OpenAiFindingEmbedder`,
|
|
393
|
+
`SqliteFindingsStore`, and their storage types.
|
|
369
394
|
|
|
370
395
|
For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
|
|
371
396
|
static key or `() => string | Promise<string>` as its first argument. It calls
|
|
@@ -373,6 +398,8 @@ the callback before each HTTP batch; the caller handles token acquisition.
|
|
|
373
398
|
Cancellation prevents a new callback or HTTP request. Direct embedder callers
|
|
374
399
|
still await a key callback that has already started.
|
|
375
400
|
Pass `fetch` as the second argument and the full endpoint URL as the third.
|
|
401
|
+
The fourth argument accepts an `AbortSignal`; the fifth accepts an
|
|
402
|
+
`EmbeddingUsageObserver`.
|
|
376
403
|
By default, the saved-scan deduplication APIs use environment credentials. A
|
|
377
404
|
custom SDK `embedding` binding can supply an adapter with its own credentials,
|
|
378
405
|
including an `OpenAiFindingEmbedder` with a renewable key callback.
|
|
@@ -12,7 +12,14 @@ to its recorded base. The API does not apply a patch or infer a branch from the
|
|
|
12
12
|
finding. It checks HEAD before and after execution; the host owns checking the
|
|
13
13
|
candidate's bytes/digest and verifying that verification did not change them.
|
|
14
14
|
|
|
15
|
+
In this TypeScript host integration, `executor` is your application's
|
|
16
|
+
`RemediationExecutor`. It runs the request in the prepared checkout and returns
|
|
17
|
+
an execution receipt. Substitute the frozen revision, finding evidence, model
|
|
18
|
+
and attempt identity from your host.
|
|
19
|
+
|
|
15
20
|
```ts
|
|
21
|
+
import { runHostedRemediation } from "@openai/codex-security";
|
|
22
|
+
|
|
16
23
|
const result = await runHostedRemediation(
|
|
17
24
|
{
|
|
18
25
|
version: 1,
|
|
@@ -39,6 +46,9 @@ const result = await runHostedRemediation(
|
|
|
39
46
|
);
|
|
40
47
|
```
|
|
41
48
|
|
|
49
|
+
Read `result.verification?.status` and its evidence before marking a finding
|
|
50
|
+
fixed. A completed request can return `still_vulnerable` or `inconclusive`.
|
|
51
|
+
|
|
42
52
|
Both instruction fields are optional and are distinct from finding data.
|
|
43
53
|
Reasoning effort is passed through unchanged so the selected model and provider
|
|
44
54
|
determine which values they support.
|
|
@@ -50,8 +60,7 @@ verification are separate operations.
|
|
|
50
60
|
Set `verificationMode: "static"` to review attack paths, bypasses, and legitimate
|
|
51
61
|
behavior from source and diffs, without installing dependencies or executing
|
|
52
62
|
builds, tests, reproducers, or the application. Select it for both `patch` and
|
|
53
|
-
`verify` requests when both stages should be static.
|
|
54
|
-
retains the existing behavior.
|
|
63
|
+
`verify` requests when both stages should be static. Use `"standard"` (the default) when runtime checks are appropriate.
|
|
55
64
|
|
|
56
65
|
Static mode treats validation instructions as source-review questions. Missing
|
|
57
66
|
runtime tooling alone is not a blocker; material proof gaps still produce
|
|
@@ -110,14 +119,12 @@ codex-security verify-fix --host
|
|
|
110
119
|
|
|
111
120
|
Use `--host` alone with either command. The `run` request supplies all settings,
|
|
112
121
|
and its `operation` must match the command: `patch` or `verify`, respectively.
|
|
113
|
-
|
|
114
|
-
remain unchanged when `--host` is omitted.
|
|
122
|
+
The host executes the model request for either command.
|
|
115
123
|
|
|
116
124
|
The SDK also exports `runHostedRemediationProtocol` for in-process hosts.
|
|
117
125
|
|
|
118
|
-
Use
|
|
119
|
-
|
|
120
|
-
receipt. `execution.progress` notifications use `{ requestId, event }` and are
|
|
126
|
+
Use one JSON object per line. Send one `run` request whose `params` are the
|
|
127
|
+
input above. Respond to `execution.run` with the executor receipt. `execution.progress` notifications use `{ requestId, event }` and are
|
|
121
128
|
forwarded as `remediation.progress` with `{ id: originalRunId, event }`. Send
|
|
122
129
|
`cancel` with `{ id: originalRunId }` to receive `execution.cancel`; then return
|
|
123
130
|
the final execution receipt so usage and session identity survive cancellation.
|
package/docs/hosted-scans.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
`codex-security scan --host` runs one scan using newline-delimited JSON-RPC on
|
|
4
4
|
stdin/stdout. Use the flag alone. It performs no login, update check, local
|
|
5
|
-
inference, or model fallback.
|
|
5
|
+
inference, or model fallback.
|
|
6
6
|
|
|
7
7
|
For hosted patch generation and verification, use the separate
|
|
8
8
|
[hosted remediation API](hosted-remediation.md).
|
|
@@ -22,6 +22,9 @@ accepted output independently from inference. Findings ingestion and
|
|
|
22
22
|
deduplication consume that accepted output separately. CLI workbench state
|
|
23
23
|
remains scan-domain state; there is no hosted-attempt replay store.
|
|
24
24
|
|
|
25
|
+
In this TypeScript integration, `host` is your application's executor and
|
|
26
|
+
receipt store. Substitute your authorized model, checkout and frozen revision.
|
|
27
|
+
|
|
25
28
|
```ts
|
|
26
29
|
import { runHostedScan, type ScanExecutor } from "@openai/codex-security";
|
|
27
30
|
|
|
@@ -86,44 +89,6 @@ host's durable run state before starting its first CLI process. Send that saved
|
|
|
86
89
|
snapshot with every subsequent attempt for the same run, including attempts in
|
|
87
90
|
a fresh checkout or container. A configuration change then applies to new runs.
|
|
88
91
|
|
|
89
|
-
Set `ownerSuggestions: true` to record ownership evidence during the existing
|
|
90
|
-
scan execution. The scan agent may include an optional hint on each finding:
|
|
91
|
-
|
|
92
|
-
```json
|
|
93
|
-
{
|
|
94
|
-
"extensions": {
|
|
95
|
-
"ownerSuggestion": {
|
|
96
|
-
"email": "alex@example.test",
|
|
97
|
-
"commit": "0123456789012345678901234567890123456789",
|
|
98
|
-
"reason": "Maintains the affected source."
|
|
99
|
-
}
|
|
100
|
-
}
|
|
101
|
-
}
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
Use an observed contributor email and a full supporting commit hash from Git
|
|
105
|
-
blame/history for the affected source. Omit the hint when ownership is unclear.
|
|
106
|
-
Hints use the scan's existing session and budget; there is no extra ownership
|
|
107
|
-
turn or model call. Security findings take priority over optional hints.
|
|
108
|
-
|
|
109
|
-
After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
|
|
110
|
-
CODEOWNERS declarations take precedence. Other hints must match an observed Git
|
|
111
|
-
identity and supporting commit in the finding's evidence. Missing hints abstain;
|
|
112
|
-
invalid hints produce per-finding owner errors. Neither invalid hints nor report
|
|
113
|
-
failures invalidate sealed findings. A completed receipt includes the artifact
|
|
114
|
-
when available, or `ownerSuggestionsError` if finalization fails.
|
|
115
|
-
|
|
116
|
-
Hosts run the normal scan request and capture the optional owner report.
|
|
117
|
-
Automatic reporting uses `suggestOwnersFromScan`; it does not use the legacy
|
|
118
|
-
`ownerCodex` option or send `owner.infer` / `owner.cancel` requests.
|
|
119
|
-
|
|
120
|
-
The standalone `suggestOwners` API and `suggest-owners` command can call a
|
|
121
|
-
model under their own budget. Both paths use the same CODEOWNERS rules, Git
|
|
122
|
-
evidence, identity checks, and report format.
|
|
123
|
-
|
|
124
|
-
Report generation works after the scan reaches `maxCostUsd`. It uses the
|
|
125
|
-
hints already recorded and never starts another model call to fill gaps.
|
|
126
|
-
|
|
127
92
|
`ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
|
|
128
93
|
`{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
|
|
129
94
|
uses the existing `ScanProgress` type; activity uses `ScanActivity`. Progress may
|
|
@@ -206,7 +171,7 @@ the same state. This includes:
|
|
|
206
171
|
- The whole `stateDirectory`, including the registered workbench database,
|
|
207
172
|
journals, and scan inputs; a live database file alone is not a consistent copy.
|
|
208
173
|
- `outputDirectory`, where the executor records its draft and the CLI later
|
|
209
|
-
writes the validated manifest, findings
|
|
174
|
+
writes the validated manifest, findings and report.
|
|
210
175
|
- The temporary files named by `CODEX_SECURITY_CONFIG_PATH` and, for path scans,
|
|
211
176
|
`CODEX_SECURITY_TARGET_PATHS_FILE` in `runtime.environment`. These are required
|
|
212
177
|
by preflight and scope binding, even though they can live outside the state
|
|
@@ -275,6 +240,42 @@ resume, or finalize-only operation: calling `runHostedScan` again registers a ne
|
|
|
275
240
|
scan. A provider reporting execution completion does not substitute for a
|
|
276
241
|
validated, sealed scan receipt.
|
|
277
242
|
|
|
243
|
+
## Optional owner suggestions
|
|
244
|
+
|
|
245
|
+
Set `ownerSuggestions: true` to record ownership evidence during the existing
|
|
246
|
+
scan execution. The scan agent may include an optional hint on each finding:
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"extensions": {
|
|
251
|
+
"ownerSuggestion": {
|
|
252
|
+
"email": "alex@example.test",
|
|
253
|
+
"commit": "0123456789012345678901234567890123456789",
|
|
254
|
+
"reason": "Maintains the affected source."
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Use an observed contributor email and a full supporting commit hash from Git
|
|
261
|
+
blame/history for the affected source. Omit the hint when ownership is unclear.
|
|
262
|
+
The scan collects hints within its session and budget. Findings take priority
|
|
263
|
+
over optional hints.
|
|
264
|
+
|
|
265
|
+
After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
|
|
266
|
+
CODEOWNERS declarations take precedence. Other hints must match an observed Git
|
|
267
|
+
identity and supporting commit in the finding's evidence. Missing hints abstain;
|
|
268
|
+
invalid hints produce per-finding owner errors. Neither invalid hints nor report
|
|
269
|
+
failures invalidate sealed findings. A completed receipt includes the artifact
|
|
270
|
+
when available, or `ownerSuggestionsError` if finalization fails.
|
|
271
|
+
|
|
272
|
+
Read the owner report from the completed receipt. Finalization uses
|
|
273
|
+
`suggestOwnersFromScan` and can run after the scan reaches `maxCostUsd`.
|
|
274
|
+
|
|
275
|
+
The standalone `suggestOwners` API and `suggest-owners` command can call a
|
|
276
|
+
model under their own budget. Both paths use the same CODEOWNERS rules, Git
|
|
277
|
+
evidence, identity checks, and report format.
|
|
278
|
+
|
|
278
279
|
## Progress, cancellation and artifacts
|
|
279
280
|
|
|
280
281
|
The host sends `execution.progress` notifications with `{requestId, event}`.
|
|
@@ -288,8 +289,15 @@ a canceled receipt with the requested checkout, scope, and rubric before startin
|
|
|
288
289
|
the executor. Invalid request fields still return a JSON-RPC error.
|
|
289
290
|
After dispatch the CLI aborts its executor signal, emits
|
|
290
291
|
`execution.cancel` with `{requestId}`, and waits for the host's outcome/usage
|
|
291
|
-
before returning a canceled result.
|
|
292
|
-
|
|
292
|
+
before returning a canceled result. For a registered scan, the durable lifecycle
|
|
293
|
+
and final scan receipt record cancellation even if the executor reports failure.
|
|
294
|
+
The `execution` field retains that failure, its diagnostics, and any usage.
|
|
295
|
+
A caller deadline expiring after registration records a failed scan, including
|
|
296
|
+
when the executor acknowledges the deadline with a canceled execution.
|
|
297
|
+
If the executor reports `acceptance_unknown`, the local scan records `failed`
|
|
298
|
+
and the host receives `acceptance_unknown` for reconciliation.
|
|
299
|
+
|
|
300
|
+
The host must continue reading notifications while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with
|
|
293
301
|
blocked output terminate the transport even while a write callback is stuck.
|
|
294
302
|
Input EOF before the terminal response fails the run; EOF while that response is
|
|
295
303
|
flushing waits for the write callback. A selected successful result is not a
|