@openai/codex-security 0.9.1 → 0.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -788
- package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
- package/_bundled_plugin/.mcp.json +3 -0
- package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
- package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
- package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br +0 -0
- package/_bundled_plugin/references/access-advisory.md +1 -1
- package/_bundled_plugin/references/artifact-storage.md +1 -1
- package/_bundled_plugin/references/baseline-auditor.md +18 -0
- package/_bundled_plugin/references/core-scan.md +5 -42
- package/_bundled_plugin/references/final-report.md +1 -1
- package/_bundled_plugin/references/focused-investigator.md +13 -0
- package/_bundled_plugin/references/scan-prologue.md +2 -2
- package/_bundled_plugin/references/scan-runtime.md +4 -2
- package/_bundled_plugin/references/security-guidance.md +14 -1
- package/_bundled_plugin/references/threat-model.md +1 -0
- package/_bundled_plugin/references/validate-scan-findings.md +3 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +30 -12
- package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +47 -9
- package/_bundled_plugin/scripts/launch_codex_security_mcp +54 -16
- package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +2 -0
- package/_bundled_plugin/scripts/posix_scan_local_files.py +26 -1
- package/_bundled_plugin/scripts/snapshot_sqlite.py +8 -2
- package/_bundled_plugin/scripts/windows_scan_local_files.py +216 -25
- package/_bundled_plugin/scripts/workbench/handoff.py +55 -25
- package/_bundled_plugin/scripts/workbench/storage.py +25 -5
- package/_bundled_plugin/scripts/workbench_cli.py +24 -2
- package/_bundled_plugin/scripts/workbench_constants.py +2 -0
- package/_bundled_plugin/scripts/workbench_db.py +257 -268
- package/_bundled_plugin/scripts/workbench_feedback.py +49 -4
- package/_bundled_plugin/scripts/workbench_native_indexes.py +226 -29
- package/_bundled_plugin/scripts/workbench_progress.py +159 -3
- package/_bundled_plugin/scripts/workbench_publication.py +2 -3
- package/_bundled_plugin/scripts/workbench_remediation.py +142 -2
- package/_bundled_plugin/scripts/workbench_saved_results.py +48 -8
- package/_bundled_plugin/scripts/workbench_scan_history.py +291 -134
- package/_bundled_plugin/scripts/workbench_scan_start.py +208 -11
- package/_bundled_plugin/scripts/workbench_scan_usage.py +36 -10
- package/_bundled_plugin/scripts/workbench_schema.py +220 -14
- package/_bundled_plugin/scripts/workbench_setup.py +1 -1
- package/_bundled_plugin/scripts/workbench_source_scopes.py +8 -0
- package/_bundled_plugin/scripts/workbench_target.py +486 -85
- package/_bundled_plugin/scripts/workbench_target_state.py +1108 -22
- package/_bundled_plugin/shared/workbench-history-repairs.json +64 -14
- package/_bundled_plugin/shared/workbench-migrations.json +66 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -2
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +2 -2
- package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -0
- package/_bundled_plugin/skills/publish-findings/SKILL.md +26 -160
- package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +2 -2
- package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +3 -58
- package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
- package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
- package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
- package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
- package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
- package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
- package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
- package/bin/codex-security.mjs +2 -2
- package/dist/api.d.ts +7 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +459 -157
- package/dist/api.js.map +1 -1
- package/dist/armorcode-findings.d.ts +9 -0
- package/dist/armorcode-findings.d.ts.map +1 -0
- package/dist/armorcode-findings.js +145 -0
- package/dist/armorcode-findings.js.map +1 -0
- package/dist/artifact-export.d.ts +2 -0
- package/dist/artifact-export.d.ts.map +1 -1
- package/dist/artifact-export.js +29 -13
- package/dist/artifact-export.js.map +1 -1
- package/dist/auth.d.ts +6 -2
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +33 -12
- package/dist/auth.js.map +1 -1
- package/dist/batch-cost.d.ts +18 -0
- package/dist/batch-cost.d.ts.map +1 -0
- package/dist/batch-cost.js +41 -0
- package/dist/batch-cost.js.map +1 -0
- package/dist/blackduck-findings.d.ts +1 -1
- package/dist/blackduck-findings.d.ts.map +1 -1
- package/dist/blackduck-findings.js +5 -18
- package/dist/blackduck-findings.js.map +1 -1
- package/dist/bundled-plugin.d.ts +4 -0
- package/dist/bundled-plugin.d.ts.map +1 -0
- package/dist/bundled-plugin.js +23 -0
- package/dist/bundled-plugin.js.map +1 -0
- package/dist/classify-scan-severity.d.ts +1 -1
- package/dist/classify-scan-severity.d.ts.map +1 -1
- package/dist/classify-scan-severity.js +11 -3
- package/dist/classify-scan-severity.js.map +1 -1
- package/dist/classify-severity-diagnostics.d.ts +10 -0
- package/dist/classify-severity-diagnostics.d.ts.map +1 -0
- package/dist/classify-severity-diagnostics.js +57 -0
- package/dist/classify-severity-diagnostics.js.map +1 -0
- package/dist/classify-severity-records.d.ts +4 -0
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +35 -8
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +9 -6
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-argument.d.ts +4 -0
- package/dist/cli-argument.d.ts.map +1 -0
- package/dist/cli-argument.js +17 -0
- package/dist/cli-argument.js.map +1 -0
- package/dist/cli-help.d.ts +1 -1
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +71 -29
- package/dist/cli-help.js.map +1 -1
- package/dist/cli-hook.d.ts +3 -0
- package/dist/cli-hook.d.ts.map +1 -0
- package/dist/cli-hook.js +87 -0
- package/dist/cli-hook.js.map +1 -0
- package/dist/cli-integrations.d.ts +13 -0
- package/dist/cli-integrations.d.ts.map +1 -0
- package/dist/cli-integrations.js +333 -0
- package/dist/cli-integrations.js.map +1 -0
- package/dist/cli-mcp.d.ts +15 -0
- package/dist/cli-mcp.d.ts.map +1 -0
- package/dist/cli-mcp.js +178 -0
- package/dist/cli-mcp.js.map +1 -0
- package/dist/cli-token-view.d.ts +10 -0
- package/dist/cli-token-view.d.ts.map +1 -0
- package/dist/cli-token-view.js +41 -0
- package/dist/cli-token-view.js.map +1 -0
- package/dist/cli.d.ts +8 -3
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1860 -903
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +33 -31
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codex-sdk-environment.d.ts +6 -0
- package/dist/codex-sdk-environment.d.ts.map +1 -1
- package/dist/codex-sdk-environment.js +19 -0
- package/dist/codex-sdk-environment.js.map +1 -1
- package/dist/command-words.d.ts +3 -0
- package/dist/command-words.d.ts.map +1 -0
- package/dist/command-words.js +46 -0
- package/dist/command-words.js.map +1 -0
- package/dist/component-plan.d.ts.map +1 -1
- package/dist/component-plan.js +3 -3
- package/dist/component-plan.js.map +1 -1
- package/dist/component-scan.d.ts +3 -1
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +40 -7
- package/dist/component-scan.js.map +1 -1
- package/dist/config.d.ts +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +30 -1
- package/dist/config.js.map +1 -1
- package/dist/continuum-aws.d.ts +6 -0
- package/dist/continuum-aws.d.ts.map +1 -0
- package/dist/continuum-aws.js +202 -0
- package/dist/continuum-aws.js.map +1 -0
- package/dist/continuum-collector.d.ts +44 -0
- package/dist/continuum-collector.d.ts.map +1 -0
- package/dist/continuum-collector.js +266 -0
- package/dist/continuum-collector.js.map +1 -0
- package/dist/continuum-findings.d.ts +31 -2
- package/dist/continuum-findings.d.ts.map +1 -1
- package/dist/continuum-findings.js +497 -59
- package/dist/continuum-findings.js.map +1 -1
- package/dist/contract.d.ts +1 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +3 -0
- package/dist/contract.js.map +1 -1
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +1 -45
- package/dist/cost.js.map +1 -1
- package/dist/crowdstrike-findings.d.ts +7 -0
- package/dist/crowdstrike-findings.d.ts.map +1 -0
- package/dist/crowdstrike-findings.js +210 -0
- package/dist/crowdstrike-findings.js.map +1 -0
- package/dist/custom-validation-prompt.d.ts +1 -1
- package/dist/custom-validation-prompt.d.ts.map +1 -1
- package/dist/custom-validation-prompt.js +29 -19
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/local.d.ts +3 -1
- package/dist/deduplication/local.d.ts.map +1 -1
- package/dist/deduplication/local.js +8 -1
- package/dist/deduplication/local.js.map +1 -1
- package/dist/deduplication/refusal.d.ts.map +1 -1
- package/dist/deduplication/refusal.js +2 -1
- package/dist/deduplication/refusal.js.map +1 -1
- package/dist/deduplication/scan.d.ts +2 -0
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +24 -7
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-scan.d.ts.map +1 -1
- package/dist/deep-scan.js +16 -15
- package/dist/deep-scan.js.map +1 -1
- package/dist/endor-findings.d.ts +2 -2
- package/dist/endor-findings.d.ts.map +1 -1
- package/dist/endor-findings.js +6 -23
- package/dist/endor-findings.js.map +1 -1
- package/dist/errors.d.ts +3 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +7 -3
- package/dist/errors.js.map +1 -1
- package/dist/executable-path.d.ts +3 -0
- package/dist/executable-path.d.ts.map +1 -1
- package/dist/executable-path.js +26 -0
- package/dist/executable-path.js.map +1 -1
- package/dist/external-findings-import.d.ts.map +1 -1
- package/dist/external-findings-import.js +12 -1
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts +66 -4
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +258 -59
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +6 -1
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +330 -1633
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +11 -2
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +56 -53
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-findings.d.ts +1 -1
- package/dist/external-findings.d.ts.map +1 -1
- package/dist/external-findings.js +12 -1
- package/dist/external-findings.js.map +1 -1
- package/dist/external-import-contract.d.ts +6 -11
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +35 -177
- package/dist/external-import-contract.js.map +1 -1
- package/dist/external-import-models.d.ts +1 -1
- package/dist/external-import-models.d.ts.map +1 -1
- package/dist/external-import-models.js.map +1 -1
- package/dist/finding-prompt.d.ts.map +1 -1
- package/dist/finding-prompt.js +2 -2
- package/dist/finding-prompt.js.map +1 -1
- package/dist/github-dependabot-findings.d.ts.map +1 -1
- package/dist/github-dependabot-findings.js +3 -4
- package/dist/github-dependabot-findings.js.map +1 -1
- package/dist/github-findings.d.ts.map +1 -1
- package/dist/github-findings.js +19 -287
- package/dist/github-findings.js.map +1 -1
- package/dist/host-protocol.d.ts +6 -0
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js +11 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/host-records-protocol.d.ts +2 -0
- package/dist/host-records-protocol.d.ts.map +1 -1
- package/dist/host-records-protocol.js +4 -0
- package/dist/host-records-protocol.js.map +1 -1
- package/dist/hosted-remediation.d.ts +1 -0
- package/dist/hosted-remediation.d.ts.map +1 -1
- package/dist/hosted-remediation.js +23 -3
- package/dist/hosted-remediation.js.map +1 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/inspector-findings.d.ts.map +1 -1
- package/dist/inspector-findings.js +19 -35
- package/dist/inspector-findings.js.map +1 -1
- package/dist/knowledge-base.d.ts +1 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +34 -27
- package/dist/knowledge-base.js.map +1 -1
- package/dist/linear.d.ts +11 -0
- package/dist/linear.d.ts.map +1 -1
- package/dist/linear.js.map +1 -1
- package/dist/local-git-metadata.d.ts +5 -2
- package/dist/local-git-metadata.d.ts.map +1 -1
- package/dist/local-git-metadata.js +8 -4
- package/dist/local-git-metadata.js.map +1 -1
- package/dist/multiscan.d.ts +4 -0
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +83 -39
- package/dist/multiscan.js.map +1 -1
- package/dist/opengrep-findings.d.ts +4 -2
- package/dist/opengrep-findings.d.ts.map +1 -1
- package/dist/opengrep-findings.js +39 -22
- package/dist/opengrep-findings.js.map +1 -1
- package/dist/private-finding-import.d.ts +8 -13
- package/dist/private-finding-import.d.ts.map +1 -1
- package/dist/private-finding-import.js +69 -129
- package/dist/private-finding-import.js.map +1 -1
- package/dist/project-config-schema.d.ts +2 -0
- package/dist/project-config-schema.d.ts.map +1 -1
- package/dist/project-config-schema.js +1 -0
- package/dist/project-config-schema.js.map +1 -1
- package/dist/project-config.d.ts +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +56 -13
- package/dist/project-config.js.map +1 -1
- package/dist/prompt-files.d.ts +7 -2
- package/dist/prompt-files.d.ts.map +1 -1
- package/dist/prompt-files.js +42 -20
- package/dist/prompt-files.js.map +1 -1
- package/dist/provider-profile.d.ts.map +1 -1
- package/dist/provider-profile.js +4 -9
- package/dist/provider-profile.js.map +1 -1
- package/dist/publication.d.ts +1 -1
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js.map +1 -1
- package/dist/record.d.ts +1 -5
- package/dist/record.d.ts.map +1 -1
- package/dist/record.js +3 -51
- package/dist/record.js.map +1 -1
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +3 -1
- package/dist/remediation.js.map +1 -1
- package/dist/runtime.d.ts +35 -7
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +782 -153
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan-bootstrap.d.ts +6 -1
- package/dist/saved-scan-bootstrap.d.ts.map +1 -1
- package/dist/saved-scan-bootstrap.js +267 -115
- package/dist/saved-scan-bootstrap.js.map +1 -1
- package/dist/scan-archive-path.d.ts +2 -0
- package/dist/scan-archive-path.d.ts.map +1 -0
- package/dist/scan-archive-path.js +5 -0
- package/dist/scan-archive-path.js.map +1 -0
- package/dist/scan-comparison.d.ts +20 -2
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +26 -5
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +1 -0
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +18 -2
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-executor.d.ts.map +1 -1
- package/dist/scan-executor.js +4 -2
- package/dist/scan-executor.js.map +1 -1
- package/dist/scan-history-renderer.d.ts +1 -0
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +25 -9
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +28 -4
- package/dist/scan-logs.js.map +1 -1
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +1 -0
- package/dist/scan-settings.js.map +1 -1
- package/dist/scanner-import.d.ts +5 -11
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +16 -89
- package/dist/scanner-import.js.map +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +26 -6
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts.map +1 -1
- package/dist/semgrep-findings.js +14 -48
- package/dist/semgrep-findings.js.map +1 -1
- package/dist/semgrep-platform-findings.d.ts +20 -70
- package/dist/semgrep-platform-findings.d.ts.map +1 -1
- package/dist/semgrep-platform-findings.js +116 -333
- package/dist/semgrep-platform-findings.js.map +1 -1
- package/dist/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +1 -0
- package/dist/severity-review.js.map +1 -1
- package/dist/snyk-findings.d.ts +2 -0
- package/dist/snyk-findings.d.ts.map +1 -1
- package/dist/snyk-findings.js +5 -8
- package/dist/snyk-findings.js.map +1 -1
- package/dist/snyk-rest-findings.d.ts +3 -20
- package/dist/snyk-rest-findings.d.ts.map +1 -1
- package/dist/snyk-rest-findings.js +45 -217
- package/dist/snyk-rest-findings.js.map +1 -1
- package/dist/sonar-findings.d.ts +1 -1
- package/dist/sonar-findings.d.ts.map +1 -1
- package/dist/sonar-findings.js +2 -4
- package/dist/sonar-findings.js.map +1 -1
- package/dist/sonar-import.d.ts +3 -0
- package/dist/sonar-import.d.ts.map +1 -1
- package/dist/sonar-import.js +28 -30
- package/dist/sonar-import.js.map +1 -1
- package/dist/stored-finding-projection.d.ts +6 -0
- package/dist/stored-finding-projection.d.ts.map +1 -0
- package/dist/stored-finding-projection.js +129 -0
- package/dist/stored-finding-projection.js.map +1 -0
- package/dist/stored-findings-publication.d.ts +23 -0
- package/dist/stored-findings-publication.d.ts.map +1 -0
- package/dist/stored-findings-publication.js +169 -0
- package/dist/stored-findings-publication.js.map +1 -0
- package/dist/targets.d.ts +8 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +103 -23
- package/dist/targets.js.map +1 -1
- package/dist/tenable-findings.d.ts +1 -4
- package/dist/tenable-findings.d.ts.map +1 -1
- package/dist/tenable-findings.js.map +1 -1
- package/dist/trivy-findings.d.ts.map +1 -1
- package/dist/trivy-findings.js +0 -11
- package/dist/trivy-findings.js.map +1 -1
- package/dist/trusted-executable.d.ts +7 -0
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +148 -37
- package/dist/trusted-executable.js.map +1 -1
- package/dist/value.js +3 -1
- package/dist/value.js.map +1 -1
- package/dist/veracode-findings.d.ts +1 -3
- package/dist/veracode-findings.d.ts.map +1 -1
- package/dist/veracode-findings.js +13 -38
- package/dist/veracode-findings.js.map +1 -1
- package/dist/version.d.ts +3 -1
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +184 -32
- package/dist/version.js.map +1 -1
- package/dist/wiz-findings.d.ts +2 -2
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +14 -92
- package/dist/wiz-findings.js.map +1 -1
- package/docs/classify-severity-records.md +30 -0
- package/docs/cli.md +537 -124
- package/docs/findings-service.md +22 -9
- package/docs/hosted-remediation.md +13 -4
- package/docs/sdk.md +918 -0
- package/package.json +15 -6
- package/schemas/external-findings.schema.json +2 -1
- package/schemas/project-config.schema.json +5 -0
- package/dist/hosted-scanner-v1.d.ts +0 -6
- package/dist/hosted-scanner-v1.d.ts.map +0 -1
- package/dist/hosted-scanner-v1.js +0 -60
- package/dist/hosted-scanner-v1.js.map +0 -1
- package/dist/reader-selection.d.ts +0 -15
- package/dist/reader-selection.d.ts.map +0 -1
- package/dist/reader-selection.js +0 -89
- package/dist/reader-selection.js.map +0 -1
- package/dist/semgrep-platform-v1.d.ts +0 -6
- package/dist/semgrep-platform-v1.d.ts.map +0 -1
- package/dist/semgrep-platform-v1.js +0 -83
- package/dist/semgrep-platform-v1.js.map +0 -1
- package/dist/snyk-rest-v1.d.ts +0 -28
- package/dist/snyk-rest-v1.d.ts.map +0 -1
- package/dist/snyk-rest-v1.js +0 -132
- package/dist/snyk-rest-v1.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,836 +1,85 @@
|
|
|
1
1
|
# `@openai/codex-security`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- Scan repositories, selected paths, or Git changes. Deep scans repeat Standard
|
|
8
|
-
scans of the selected scope and merge their findings after each batch.
|
|
9
|
-
- Validate findings, generate patches, and verify existing fixes.
|
|
10
|
-
- Draft security policies and retain threat models.
|
|
11
|
-
- Review saved findings, identify duplicates, classify severity, and suggest owners.
|
|
12
|
-
- Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
|
|
13
|
-
findings to Linear or a findings service.
|
|
14
|
-
- Import saved scanner reports locally or publish them to Codex Security Cloud.
|
|
15
|
-
See the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) for supported vendors and formats.
|
|
16
|
-
- Automate scans across repositories and project components.
|
|
17
|
-
|
|
18
|
-
See the [CLI reference](docs/cli.md),
|
|
19
|
-
[findings guide](docs/findings-service.md), or
|
|
20
|
-
[online documentation](https://learn.chatgpt.com/docs/security) for setup and examples.
|
|
21
|
-
|
|
22
|
-
Before version `1.0.0`, minor releases may change the public API.
|
|
3
|
+
Scan a repository, selected paths, or Git changes for vulnerabilities. The CLI
|
|
4
|
+
and TypeScript SDK can validate findings, generate patches, verify fixes, and
|
|
5
|
+
export results as SARIF, JSON, or CSV. The package includes the Codex runtime
|
|
6
|
+
and security plugin.
|
|
23
7
|
|
|
24
8
|
## Install
|
|
25
9
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
- Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, on macOS, Linux, or Windows.
|
|
29
|
-
- Python 3.10+ for scans, policy generation, exports, scan history, and saved
|
|
30
|
-
findings. Python 3.10 also needs `tomli`.
|
|
31
|
-
|
|
32
|
-
Compressed Codex session logs (`.jsonl.zst`) are readable on all supported Node.js
|
|
33
|
-
versions. The bundled streaming decoder reads concatenated frames and reports
|
|
34
|
-
truncated streams as collection errors.
|
|
10
|
+
Use Node.js 22.x (22.13.0 or later), 24.x, or 26.x on macOS, Linux, or Windows.
|
|
11
|
+
Scans also require Python 3.10 or later. On Python 3.10, install `tomli`.
|
|
35
12
|
|
|
36
13
|
### Install the CLI
|
|
37
14
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
```bash
|
|
15
|
+
```sh
|
|
41
16
|
npm install --global @openai/codex-security
|
|
42
|
-
cs --version
|
|
43
17
|
```
|
|
44
18
|
|
|
45
|
-
|
|
46
|
-
`codex-security`
|
|
47
|
-
fails with `EEXIST`, use `npx @openai/codex-security` in place of `cs`.
|
|
19
|
+
The CLI runs as `cs` or `codex-security`. To skip the global install, use
|
|
20
|
+
`npx @openai/codex-security` in place of `cs` in the examples below.
|
|
48
21
|
|
|
49
22
|
### Install the TypeScript SDK
|
|
50
23
|
|
|
51
|
-
Install the package
|
|
24
|
+
Install the package in your project directory.
|
|
52
25
|
|
|
53
|
-
```
|
|
26
|
+
```sh
|
|
54
27
|
npm install @openai/codex-security
|
|
55
28
|
```
|
|
56
29
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
Sign in with ChatGPT:
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
cs login
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
If you installed only the SDK locally, sign in from your project directory:
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
npx @openai/codex-security login
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
In the following CLI examples, replace `cs` with `npx @openai/codex-security`
|
|
72
|
-
when using a local SDK installation, including the API-key login example below.
|
|
30
|
+
Before 1.0, minor releases may change the public API.
|
|
73
31
|
|
|
74
|
-
|
|
75
|
-
These keys apply to the current command without replacing your saved login.
|
|
76
|
-
To save an API key instead, pass it on stdin:
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
printenv OPENAI_API_KEY | cs login --with-api-key
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,
|
|
83
|
-
prefers `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
|
|
84
|
-
Use `"chatgpt"` to ignore environment API keys. The CLI uses the same `--auth`
|
|
85
|
-
values and prompts in an interactive terminal when both credential types are available.
|
|
32
|
+
## Authentication
|
|
86
33
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
34
|
+
Run `cs login` to sign in with ChatGPT. With a local SDK installation, run
|
|
35
|
+
`npx @openai/codex-security login` from your project. In CI, set
|
|
36
|
+
`OPENAI_API_KEY` or `CODEX_API_KEY` in the scan environment.
|
|
37
|
+
Some requests require [Trusted Access for Cyber](https://chatgpt.com/cyber).
|
|
91
38
|
|
|
92
|
-
|
|
39
|
+
## CLI
|
|
93
40
|
|
|
94
|
-
|
|
95
|
-
allows it. Otherwise, open an SSH tunnel from your local machine:
|
|
41
|
+
Run a scan from the repository you want to review.
|
|
96
42
|
|
|
97
|
-
```
|
|
98
|
-
|
|
43
|
+
```sh
|
|
44
|
+
cs scan .
|
|
99
45
|
```
|
|
100
46
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
Bedrock scans use AWS credentials and model access. They do not require
|
|
107
|
-
`codex-security login` or an OpenAI API key. See the
|
|
108
|
-
[Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
|
|
109
|
-
for setup, model selection, and verification.
|
|
47
|
+
To scan only committed changes from `origin/main` to `HEAD`, run
|
|
48
|
+
`cs scan . --diff origin/main`. A completed scan exits with code `0` by default,
|
|
49
|
+
even when it finds vulnerabilities. Add `--fail-on-severity high` to exit with
|
|
50
|
+
code `1` for high or critical findings.
|
|
110
51
|
|
|
111
52
|
## Run a scan from TypeScript
|
|
112
53
|
|
|
113
|
-
|
|
54
|
+
Run this ES module from the repository you want to scan.
|
|
114
55
|
|
|
115
56
|
```ts
|
|
116
57
|
import { CodexSecurity } from "@openai/codex-security";
|
|
117
58
|
|
|
118
59
|
const security = new CodexSecurity();
|
|
119
|
-
|
|
120
60
|
try {
|
|
121
|
-
const result = await security.run("
|
|
122
|
-
|
|
61
|
+
const result = await security.run(".");
|
|
123
62
|
console.log(result.reportPath);
|
|
124
|
-
console.log(result.findings.findings);
|
|
125
|
-
|
|
126
|
-
if (result.hasFindingsAtOrAbove("high")) {
|
|
127
|
-
process.exitCode = 1;
|
|
128
|
-
}
|
|
63
|
+
console.log(`${result.findings.findings.length} findings`);
|
|
129
64
|
} finally {
|
|
130
65
|
await security.close();
|
|
131
66
|
}
|
|
132
67
|
```
|
|
133
68
|
|
|
134
|
-
Omitting `outputDir` saves results in the private Codex Security state directory.
|
|
135
|
-
To choose another location, use a new or empty directory outside the scanned
|
|
136
|
-
repository and its enclosing Git worktree. Existing output directories keep their
|
|
137
|
-
permissions; newly created directories are private to you by default.
|
|
138
|
-
|
|
139
69
|
### Read results
|
|
140
70
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
| `review.excludedPaths` | Additional paths the scan excluded. |
|
|
146
|
-
| `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
|
|
147
|
-
| `sarifPath` | SARIF export path, or `null`. |
|
|
148
|
-
| `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
|
|
149
|
-
| `cost` | Estimated model usage cost, or `null` when unavailable. |
|
|
150
|
-
|
|
151
|
-
Read `result.manifest.scan.status` and `result.manifest.scan.scope` alongside
|
|
152
|
-
`result.review.excludedPaths` to see the outcome, the requested scope and any
|
|
153
|
-
additional exclusions. A completed scan can report zero findings within that scope.
|
|
154
|
-
|
|
155
|
-
If the run retained a draft or checkpoint, its `reviewState.deferred` lists
|
|
156
|
-
unfinished work and `reviewState.openQuestions` lists follow-up questions.
|
|
157
|
-
See [saved scan files](docs/cli.md#understand-scan-scope-and-follow-up-work)
|
|
158
|
-
for the current and legacy layouts. Reports and logs can include source code,
|
|
159
|
-
vulnerability details and credentials. Review them before sharing.
|
|
160
|
-
|
|
161
|
-
Saved-history excerpts use scanned Git objects without fetching missing data.
|
|
162
|
-
Working-tree diff scans omit excerpts, as do historical scans whose source or
|
|
163
|
-
scope cannot be established. Unambiguous older scans remain readable. An omitted
|
|
164
|
-
excerpt does not remove the finding.
|
|
165
|
-
|
|
166
|
-
The SDK does not set your process's exit status. Use `hasFindingsAtOrAbove()`
|
|
167
|
-
as in the example to enforce a severity threshold.
|
|
168
|
-
|
|
169
|
-
### Scan options and output
|
|
170
|
-
|
|
171
|
-
Pass scan settings as the second argument to `run()`. The following SDK snippets
|
|
172
|
-
assume an open `CodexSecurity` client named `security`; close it when finished.
|
|
173
|
-
|
|
174
|
-
```ts
|
|
175
|
-
const result = await security.run("/path/to/repository", {
|
|
176
|
-
target: ["src", "tests"],
|
|
177
|
-
knowledgeBasePaths: ["/path/to/architecture.md"],
|
|
178
|
-
scanPrompt: "Focus on authentication and authorization.",
|
|
179
|
-
outputDir: "/path/outside/repository/results",
|
|
180
|
-
maxCostUsd: 5,
|
|
181
|
-
});
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
| Option | Use |
|
|
185
|
-
| ------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
186
|
-
| `target` | Whole repository (default), repository-relative paths, or a `DiffTarget`. |
|
|
187
|
-
| `mode` | `"standard"` (default) or `"deep"`. Deep scans support repositories and paths. |
|
|
188
|
-
| `knowledgeBasePaths` | Supporting text, PDF, DOCX files, or directories. |
|
|
189
|
-
| `scanPrompt` / `scanPromptFile` | Additional scan instructions. Inline text takes precedence. |
|
|
190
|
-
| `validationPrompt` / `validationPromptFile` | Custom validation instructions for standard scans. |
|
|
191
|
-
| `postScanPrompt` / `postScanPromptFile` | Follow-up instructions after the scan. |
|
|
192
|
-
| `ownerSuggestions` | Write optional owner suggestions after a committed scan (default: `false`). |
|
|
193
|
-
| `outputDir` | Results directory; omit to use the state directory. |
|
|
194
|
-
| `archiveExisting` | Move previous results aside before reusing `outputDir`. |
|
|
195
|
-
| `maxCostUsd` | Stop at an estimated model cost; see [cost limits](#progress-and-cost). |
|
|
196
|
-
| `signal` | An `AbortSignal` to cancel the scan. |
|
|
197
|
-
|
|
198
|
-
The exported `ScanOptions` type describes all options and callbacks. For full
|
|
199
|
-
CLI behavior, see [scan options and output](docs/cli.md#scan-options-and-output).
|
|
200
|
-
|
|
201
|
-
Set `ownerSuggestions: true` or run `codex-security scan --owner-suggestions`
|
|
202
|
-
to write `owner-suggestions.json` beside a completed committed Git scan. Project
|
|
203
|
-
files can set `scan.owner_suggestions: true`. The report uses the scan's finding
|
|
204
|
-
IDs and frozen revision; it does not change the sealed findings or assign users.
|
|
205
|
-
Owner failures leave the base scan completed and appear as
|
|
206
|
-
`result.ownerSuggestionsError`; successful reports set `result.ownerSuggestionsPath`.
|
|
207
|
-
The scan records optional owner hints within its existing session and budget.
|
|
208
|
-
Report finalization applies CODEOWNERS and validates Git evidence without another
|
|
209
|
-
model call, including when `maxCostUsd` is set. Missing hints abstain and invalid
|
|
210
|
-
hints produce per-finding errors. Working-tree and directory snapshots are
|
|
211
|
-
unsupported. Explicit owner-only analysis remains available through `suggestOwners`
|
|
212
|
-
and `suggest-owners`, sharing the same evidence validation and report code.
|
|
213
|
-
|
|
214
|
-
### Scan a diff
|
|
215
|
-
|
|
216
|
-
```ts
|
|
217
|
-
import { DiffTarget } from "@openai/codex-security";
|
|
218
|
-
|
|
219
|
-
const result = await security.run("/path/to/repository", {
|
|
220
|
-
target: DiffTarget.refs({ base: "origin/main" }),
|
|
221
|
-
});
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
`DiffTarget.refs()` compares the base with `HEAD` unless you supply `head`.
|
|
225
|
-
The checkout must be clean, complete, and at that head revision.
|
|
226
|
-
Use `DiffTarget.workingTree()` for staged and unstaged changes relative to `HEAD`.
|
|
227
|
-
Diff targets require standard mode.
|
|
228
|
-
|
|
229
|
-
### Configure the client
|
|
230
|
-
|
|
231
|
-
Set model and native Codex settings on the client:
|
|
232
|
-
|
|
233
|
-
```ts
|
|
234
|
-
const security = new CodexSecurity({
|
|
235
|
-
codexOverrides: {
|
|
236
|
-
model_reasoning_effort: "high",
|
|
237
|
-
analytics: { enabled: false },
|
|
238
|
-
},
|
|
239
|
-
});
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.
|
|
243
|
-
The bundled runtime and plugin are used by default. `pythonPath` overrides the
|
|
244
|
-
`PYTHON` environment variable. To choose a model, set `codexOverrides.model`.
|
|
245
|
-
For a custom `pluginPath`, check [custom plugin compatibility](#custom-plugins).
|
|
246
|
-
|
|
247
|
-
To enable Daybreak on Codex 0.163.0 or later, set `codexOverrides.daybreak: true`.
|
|
248
|
-
The toggle defaults off; an explicit `false` keeps it off. The setting reaches
|
|
249
|
-
Deep Scan discovery workers, including resumed workers. Scans use
|
|
250
|
-
isolated configuration, so a desktop toggle or personal Codex configuration does
|
|
251
|
-
not configure an SDK scan. See [Daybreak opt-in](docs/cli.md#daybreak-opt-in) for
|
|
252
|
-
CLI, project-file, and direct plugin configuration.
|
|
253
|
-
|
|
254
|
-
Deep Scan workers, including resumed workers, inherit per-scan provider,
|
|
255
|
-
authentication, environment, and executable settings with read-only permissions.
|
|
256
|
-
|
|
257
|
-
Scans use an isolated Codex configuration. See
|
|
258
|
-
[runtime configuration](docs/cli.md#runtime-configuration-and-worker-limits)
|
|
259
|
-
for supported overrides and defaults.
|
|
260
|
-
|
|
261
|
-
Windows defaults to `windows.sandbox = "elevated"` to enforce credential read
|
|
262
|
-
denials. Explicit `windows.sandbox` settings remain unchanged; Codex reports
|
|
263
|
-
policies unsupported by the selected backend.
|
|
264
|
-
|
|
265
|
-
### Load a project file
|
|
266
|
-
|
|
267
|
-
Load shared CLI and SDK settings explicitly:
|
|
268
|
-
|
|
269
|
-
```ts
|
|
270
|
-
import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
|
|
271
|
-
|
|
272
|
-
const { config, options } = await loadProjectConfig("codex-security.yaml");
|
|
273
|
-
const security = new CodexSecurity(config);
|
|
274
|
-
|
|
275
|
-
try {
|
|
276
|
-
const result = await security.run("/path/to/repository", options);
|
|
277
|
-
if (
|
|
278
|
-
options.failureSeverity !== undefined &&
|
|
279
|
-
result.hasFindingsAtOrAbove(options.failureSeverity)
|
|
280
|
-
) {
|
|
281
|
-
process.exitCode = 1;
|
|
282
|
-
}
|
|
283
|
-
} finally {
|
|
284
|
-
await security.close();
|
|
285
|
-
}
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
`run()` does not discover project files. Paths inside a file resolve from that
|
|
289
|
-
file's directory; scope paths resolve from the repository. For a typed object,
|
|
290
|
-
use `resolveProjectConfig(input, directory?)`. Override loaded options with
|
|
291
|
-
`{ ...options, maxCostUsd: 5 }`.
|
|
292
|
-
|
|
293
|
-
Project files are trusted configuration and can select model endpoints or start
|
|
294
|
-
MCP servers. Keep CI scanner configuration outside the checkout being assessed.
|
|
295
|
-
See the [project configuration guide](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)
|
|
296
|
-
for the schema and precedence rules.
|
|
297
|
-
|
|
298
|
-
### Check inputs before scanning
|
|
299
|
-
|
|
300
|
-
```ts
|
|
301
|
-
const plan = await security.preflight("/path/to/repository", {
|
|
302
|
-
target: ["src"],
|
|
303
|
-
maxCostUsd: 5,
|
|
304
|
-
});
|
|
305
|
-
console.log(plan);
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
`preflight()` checks local inputs without starting Codex or using the network.
|
|
309
|
-
It does not verify credentials, model access, Python, or the plugin. The CLI
|
|
310
|
-
equivalent is `scan --dry-run`.
|
|
311
|
-
|
|
312
|
-
### Set investigation time
|
|
313
|
-
|
|
314
|
-
```ts
|
|
315
|
-
await security.run("/path/to/repository", { maxTimeMinutes: 15 });
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
`maxTimeMinutes` accepts positive fractional minutes. Standard scans use an
|
|
319
|
-
advisory allowance, unset by default; Deep scans retain their enforced discovery
|
|
320
|
-
limit. Scans may finish early and reporting may run longer. The CLI equivalent is
|
|
321
|
-
`scan --max-time 15`; project files use `scan.max_time_minutes`. See
|
|
322
|
-
[investigation time](docs/cli.md#set-investigation-time) for lifecycle and limit
|
|
323
|
-
semantics. `maxCostUsd` and `signal` keep their existing behavior.
|
|
324
|
-
|
|
325
|
-
### Configure deep scans
|
|
326
|
-
|
|
327
|
-
```ts
|
|
328
|
-
const result = await security.run("/path/to/repository", {
|
|
329
|
-
mode: "deep",
|
|
330
|
-
workers: 2,
|
|
331
|
-
subagents: 0,
|
|
332
|
-
stopAfterNoNew: 3,
|
|
333
|
-
stopAfterConsecutiveErrors: 3,
|
|
334
|
-
maxDiscoveryRuns: 10,
|
|
335
|
-
maxTimeMinutes: 90,
|
|
336
|
-
});
|
|
337
|
-
```
|
|
338
|
-
|
|
339
|
-
`workers` controls concurrent Standard scans and `subagents` controls delegation
|
|
340
|
-
within each scan. Time and run limits apply to discovery. The coordinator merges
|
|
341
|
-
completed findings before the next batch starts. See
|
|
342
|
-
[deep scan settings](docs/cli.md#configure-deep-scans) for defaults and saved settings.
|
|
343
|
-
Deep discovery retains its enforced deadline, with a default and maximum of
|
|
344
|
-
5760 minutes. `maxTimeHours` remains a deprecated Deep-only alias in hours.
|
|
345
|
-
|
|
346
|
-
### Progress and cost
|
|
347
|
-
|
|
348
|
-
Use `onLifecycle` to observe the saved state of a top-level scan in your own
|
|
349
|
-
application:
|
|
350
|
-
|
|
351
|
-
```ts
|
|
352
|
-
await security.run(repository, {
|
|
353
|
-
onLifecycle(scan) {
|
|
354
|
-
console.log(scan.scanId, scan.status, scan.hasReportableFindings);
|
|
355
|
-
},
|
|
356
|
-
});
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
For `runComponentScans()`, subscribe to `onScanEvent` and select events with
|
|
360
|
-
`type === "lifecycle"` to correlate each snapshot with its `componentId`. Deep
|
|
361
|
-
component scans also emit `deep-progress` events with independent review counts.
|
|
362
|
-
|
|
363
|
-
Group observations by `scanId`. A completed scan with
|
|
364
|
-
`hasReportableFindings: false` finished with zero reportable findings.
|
|
365
|
-
The field is `null` until that outcome is known. Saved scan history retains
|
|
366
|
-
the lifecycle snapshot after the originating process exits. The snapshot
|
|
367
|
-
includes the launch surface, package and plugin versions when available,
|
|
368
|
-
and whether the scan used a mock. Offline imports appear in history with
|
|
369
|
-
lifecycle mode `import`. Exclude imports and mock scans when counting executed
|
|
370
|
-
scans. For older records, saved recipes identify known imports, mock scans,
|
|
371
|
-
and the plugin version used at launch. Missing fields stay unknown.
|
|
372
|
-
|
|
373
|
-
If `run()` rejects before you receive a registration, record the error separately
|
|
374
|
-
from saved scan outcomes. The caller may have missed the registration receipt.
|
|
375
|
-
|
|
376
|
-
Use `onProgress` for scan progress and `onMeasurement` for observed token/cost
|
|
377
|
-
subtotals, coverage, and collection time. `onCost` and `onUsage` report complete
|
|
378
|
-
totals. `onUsageObservation` reports the native token measurement time
|
|
379
|
-
(`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
|
|
380
|
-
Each reading has its own `observedAt` timestamp and percentages used in each
|
|
381
|
-
reported window. An allowance can arrive before any token measurement. See
|
|
382
|
-
[telemetry and measurement](docs/telemetry.md) for operation receipts, collection
|
|
383
|
-
controls, replay, and reporting definitions.
|
|
384
|
-
|
|
385
|
-
Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
|
|
386
|
-
persisted worker sessions discovered by the SDK's existing session tracker,
|
|
387
|
-
independently of model-emitted status markers:
|
|
388
|
-
|
|
389
|
-
```ts
|
|
390
|
-
await security.run(repository, {
|
|
391
|
-
onWorkerEvent(event) {
|
|
392
|
-
console.log(`Worker ${event.worker} observed`);
|
|
393
|
-
},
|
|
394
|
-
});
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
The callback contains only `{ kind: "observed", worker: number }`. The scan-local
|
|
398
|
-
worker number matches `onActivity` and `onSessionEvent`; no prompts, raw thread
|
|
399
|
-
IDs, or session contents are exposed. Each session is reported once per run,
|
|
400
|
-
including nested workers and scan-associated validation or Deep Scan sessions.
|
|
401
|
-
On resume, already persisted workers can be reported again. Observation ends
|
|
402
|
-
with scan cost tracking, before `postScanPrompt`.
|
|
403
|
-
|
|
404
|
-
This works with the bundled Codex version. Persistence and polling can delay
|
|
405
|
-
notification, and missing notifications do not prove that delegation was skipped.
|
|
406
|
-
An observed session does not establish that a worker just started or that file
|
|
407
|
-
review has begun. The callback does not report failed spawn attempts, phase names,
|
|
408
|
-
or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or
|
|
409
|
-
`signal` for cancellation. Observer failures go to `onObserverError` without
|
|
410
|
-
stopping the scan.
|
|
411
|
-
|
|
412
|
-
`onWorkerStatus` reports **best-effort** phase dispatch counts from model-emitted
|
|
413
|
-
text markers. A missing dispatch status does not mean delegation was skipped.
|
|
414
|
-
For retired progress hooks, see [older progress integrations](#older-progress-integrations).
|
|
415
|
-
|
|
416
|
-
`onSessionEvent` receives saved events with thread IDs and worker numbers and can
|
|
417
|
-
contain source code or credentials. Deep scans additionally expose durable
|
|
418
|
-
independent-review counts through `onDeepProgress`: `completed`, `active`, and
|
|
419
|
-
`maximum`. The maximum is a configured cap, not a percentage denominator. The
|
|
420
|
-
optional `consolidating` flag is true while the running scan combines results or
|
|
421
|
-
waits for finalization after its coordinator finishes. It is false once the scan
|
|
422
|
-
completes, fails, or is canceled.
|
|
423
|
-
`ScanOptions` lists all callbacks.
|
|
424
|
-
|
|
425
|
-
Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
|
|
426
|
-
allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
|
|
427
|
-
short-context estimate; in-flight requests can exceed it. Post-scan prompts run
|
|
428
|
-
outside that limit. With a cost limit, completing the scan requires verifiable
|
|
429
|
-
usage for the scan and its workers. Matching earlier findings can also make model calls.
|
|
430
|
-
See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.
|
|
431
|
-
|
|
432
|
-
### Validate an existing finding
|
|
433
|
-
|
|
434
|
-
`validate()` sends the finding to your configured model provider. The model's
|
|
435
|
-
review tools can read the checkout, with network access and web search disabled.
|
|
436
|
-
Validation uses source evidence and skips builds, tests and application execution.
|
|
437
|
-
|
|
438
|
-
```ts
|
|
439
|
-
import { writeFile } from "node:fs/promises";
|
|
440
|
-
|
|
441
|
-
const result = await security.validate({
|
|
442
|
-
repositoryPath: "/path/to/repository",
|
|
443
|
-
finding: {
|
|
444
|
-
title: "Possible SQL injection",
|
|
445
|
-
location: "src/query.ts:42",
|
|
446
|
-
},
|
|
447
|
-
});
|
|
448
|
-
console.log(result.disposition, result.report);
|
|
449
|
-
await writeFile("/path/to/reports/assessment.md", result.report, "utf8");
|
|
450
|
-
```
|
|
451
|
-
|
|
452
|
-
Pass literal finding text or a JSON-serializable object. The assessment is
|
|
453
|
-
returned to the caller and has no scan history entry. The example saves
|
|
454
|
-
`result.report` in an existing directory. Use `outputDir` to select the
|
|
455
|
-
session directory. If you need runtime evidence, arrange a separate check.
|
|
456
|
-
|
|
457
|
-
The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.
|
|
458
|
-
`reportable` can rely on static analysis; `deferred` means there is insufficient
|
|
459
|
-
evidence. Failed or malformed responses reject the promise. `outputDir`, `auth`,
|
|
460
|
-
and `signal` are also supported.
|
|
461
|
-
|
|
462
|
-
To validate GitHub code scanning alerts, first import them with
|
|
463
|
-
`importGitHubCodeScanningAlerts()`. See the
|
|
464
|
-
[import guide](docs/cli.md#import-alerts-from-the-cli) for CLI and SDK examples.
|
|
465
|
-
|
|
466
|
-
For host-managed model execution, use `validateRecords()` or `validate --records`.
|
|
467
|
-
See [host-provided standalone validation](docs/validate-records.md).
|
|
468
|
-
|
|
469
|
-
### Generate and verify a patch
|
|
470
|
-
|
|
471
|
-
`patch()` runs the bundled remediation workflow non-interactively against a
|
|
472
|
-
workspace that the caller has intentionally made writable:
|
|
473
|
-
|
|
474
|
-
```ts
|
|
475
|
-
import { CodexSecurity } from "@openai/codex-security";
|
|
476
|
-
|
|
477
|
-
const security = new CodexSecurity();
|
|
478
|
-
try {
|
|
479
|
-
const result = await security.patch({
|
|
480
|
-
repositoryPath: "/path/to/disposable/workspace",
|
|
481
|
-
finding: {
|
|
482
|
-
title: "Possible SQL injection",
|
|
483
|
-
summary: "User input reaches a raw SQL query.",
|
|
484
|
-
locations: [{ path: "src/query.ts", startLine: 42 }],
|
|
485
|
-
},
|
|
486
|
-
onActivity(activity) {
|
|
487
|
-
console.log(activity.description);
|
|
488
|
-
},
|
|
489
|
-
onCost(cost) {
|
|
490
|
-
console.log(cost.estimatedUsd);
|
|
491
|
-
},
|
|
492
|
-
});
|
|
493
|
-
|
|
494
|
-
switch (result.status) {
|
|
495
|
-
case "verified":
|
|
496
|
-
case "no_change":
|
|
497
|
-
console.log(result.verificationReport);
|
|
498
|
-
break;
|
|
499
|
-
case "blocked":
|
|
500
|
-
case "failed":
|
|
501
|
-
console.error(result.reason);
|
|
502
|
-
break;
|
|
503
|
-
}
|
|
504
|
-
} finally {
|
|
505
|
-
await security.close();
|
|
506
|
-
}
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
Pass literal finding text or a JSON-serializable object; strings are never read
|
|
510
|
-
as file paths. Sandboxed patch commands may edit only `repositoryPath` and run
|
|
511
|
-
without network access or web search. Patch workspaces are always treated as
|
|
512
|
-
untrusted Codex projects, so repository-local Codex configuration and MCP
|
|
513
|
-
servers are not loaded. Host-configured tools retain their host permissions.
|
|
514
|
-
The method does not create a commit, push, open a pull request, publish findings,
|
|
515
|
-
change remote finding state, or add a scan to history.
|
|
516
|
-
Callers remain responsible for reviewing and deriving the authoritative diff,
|
|
517
|
-
approval, commit creation, and delivery.
|
|
518
|
-
|
|
519
|
-
The discriminated result reports `verified`, `no_change`, `blocked`, or
|
|
520
|
-
`failed`, plus repository-relative `changedFiles`, `threadId`, and estimated
|
|
521
|
-
`cost` when model pricing and usage are available. Verified and no-change
|
|
522
|
-
results include `verificationReport`; blocked and failed results include
|
|
523
|
-
`reason`. Transport, authentication, cancellation, incomplete turns, and
|
|
524
|
-
malformed results reject the promise. Failed, blocked, or interrupted operations
|
|
525
|
-
can leave partial workspace changes for the caller to inspect or discard.
|
|
526
|
-
|
|
527
|
-
`changedFiles` is model-reported metadata, not the authoritative diff.
|
|
528
|
-
Patch-risk assessment is not included in this API.
|
|
529
|
-
|
|
530
|
-
Patch operations reuse constructor configuration and credentials. Pass `auth`,
|
|
531
|
-
`safetyIdentifier`, `model`, or `reasoningEffort` for per-call selection.
|
|
532
|
-
`onActivity`, `onSessionEvent`, `onCost`, `onReconnect`, `onAuthentication`,
|
|
533
|
-
`onWarning`, and `onObserverError` use the same observer contracts as scans.
|
|
534
|
-
|
|
535
|
-
## CLI
|
|
536
|
-
|
|
537
|
-
After [installing the CLI](#install-the-cli), sign in if needed:
|
|
538
|
-
|
|
539
|
-
```bash
|
|
540
|
-
cs login
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
From the repository you want to review, run:
|
|
544
|
-
|
|
545
|
-
```bash
|
|
546
|
-
cs scan .
|
|
547
|
-
```
|
|
548
|
-
|
|
549
|
-
Open the report at the path printed on completion. To inspect the latest
|
|
550
|
-
completed scan for this checkout, run `cs scans show`. To provide a project
|
|
551
|
-
policy for future scans, [draft and review a `SECURITY.md`](#generate-a-security-policy).
|
|
552
|
-
|
|
553
|
-
To narrow the scan scope or check the configuration before scanning:
|
|
554
|
-
|
|
555
|
-
```bash
|
|
556
|
-
cs scan . --path src --path tests
|
|
557
|
-
cs scan . --diff origin/main --json
|
|
558
|
-
cs scan . --dry-run
|
|
559
|
-
```
|
|
560
|
-
|
|
561
|
-
Use `--help` to find commands and `<command> --help` for options. Scans are
|
|
562
|
-
report-only by default. Add `--fail-on-severity high` to return exit code `1`
|
|
563
|
-
for high or critical findings; execution and required-output failures return `2`.
|
|
564
|
-
Scope exclusions and follow-up notes do not change a completed scan's exit code.
|
|
565
|
-
|
|
566
|
-
The [CLI reference](docs/cli.md) covers scan history, reruns, bulk and component
|
|
567
|
-
scans, custom validation, imports, patching, and integrations.
|
|
568
|
-
|
|
569
|
-
### Generate a security policy
|
|
570
|
-
|
|
571
|
-
Use `policy` to draft a new `SECURITY.md` or update an existing one. To select a
|
|
572
|
-
component:
|
|
573
|
-
|
|
574
|
-
```bash
|
|
575
|
-
cs policy . --path services/api
|
|
576
|
-
```
|
|
577
|
-
|
|
578
|
-
Existing files stay unchanged until you review and copy the draft to the
|
|
579
|
-
**Policy target** shown. Scans already use root and component policies; you can
|
|
580
|
-
keep them without generating new ones.
|
|
581
|
-
|
|
582
|
-
The SDK provides `generatePolicy()`, `preflightPolicy()`, and `previewPolicy()`. See
|
|
583
|
-
[policy generation](docs/cli.md#generate-a-security-policy) for SDK examples,
|
|
584
|
-
policy locations and reporting instructions, headless use, and saved artifacts.
|
|
585
|
-
|
|
586
|
-
### Exports and CI
|
|
587
|
-
|
|
588
|
-
Export a completed scan's findings to a SARIF file:
|
|
589
|
-
|
|
590
|
-
```bash
|
|
591
|
-
cs export /path/to/scan-results --output results.sarif
|
|
592
|
-
```
|
|
593
|
-
|
|
594
|
-
Replace `/path/to/scan-results` with the results directory printed by `scan`.
|
|
595
|
-
Export reads saved results, so you don't need to rerun the scan or sign in.
|
|
596
|
-
|
|
597
|
-
See [exports and CI](docs/cli.md#exports-and-ci) for source fingerprints, other
|
|
598
|
-
formats, threat models, and the `exportArtifact()` SDK method. For repository or
|
|
599
|
-
pull request scans in GitHub Actions, use the
|
|
600
|
-
[GitHub Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md).
|
|
601
|
-
Separate examples cover
|
|
602
|
-
[GitHub Actions with Bedrock](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md)
|
|
603
|
-
and [Azure Pipelines](https://github.com/openai/codex-security/blob/main/examples/azure-pipelines/README.md).
|
|
604
|
-
|
|
605
|
-
### Classify finding severity
|
|
606
|
-
|
|
607
|
-
Use `classify-severity` to assess saved findings with the built-in severity rubric
|
|
608
|
-
or an explicit custom rubric, without changing their original severity or evidence.
|
|
609
|
-
Each finding receives three independent reviews by default; the most common severity wins,
|
|
610
|
-
with the highest severity breaking ties among the top vote counts.
|
|
611
|
-
Use `--runs N` to request 1–10 reviews (default: 3). The SDK exposes `classifySeverity()`,
|
|
612
|
-
`classifyScanSeverity()`, and `classifyScanDirectorySeverity()`. See
|
|
613
|
-
[severity classification](docs/cli.md#classify-finding-severity) for selection,
|
|
614
|
-
checkpointing, and publication behavior.
|
|
615
|
-
|
|
616
|
-
For canonical records without a saved scan, use `classify-severity --records`
|
|
617
|
-
or `classifySeverityRecords()` with [host-provided execution](docs/classify-severity-records.md).
|
|
618
|
-
|
|
619
|
-
### Suggest finding owners
|
|
620
|
-
|
|
621
|
-
Use `suggest-owners` or the SDK's `suggestOwners()` to suggest contributors based
|
|
622
|
-
on CODEOWNERS, source, and Git history. Declared owners take priority over Git
|
|
623
|
-
contributors. Suggestions do not assign tickets. See
|
|
624
|
-
[owner suggestions](docs/cli.md#suggest-finding-owners) for input and output examples.
|
|
625
|
-
|
|
626
|
-
### Read existing Cloud findings
|
|
627
|
-
|
|
628
|
-
The Security plugin includes `$cloud-findings` for accounts where Codex Security
|
|
629
|
-
Cloud is available. Install the plugin through your configured Codex marketplace,
|
|
630
|
-
sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
|
|
631
|
-
the intended account and workspace. Installation alone does not authenticate the
|
|
632
|
-
connection. Local scans do not require Cloud, and an API key used for scanning
|
|
633
|
-
does not replace the Cloud connection.
|
|
634
|
-
|
|
635
|
-
In Codex desktop or the interactive Codex CLI, ask:
|
|
636
|
-
|
|
637
|
-
> Use $cloud-findings to list findings for example/security-demo in my selected
|
|
638
|
-
> workspace. Inspect the highest-severity finding and its report, and show its
|
|
639
|
-
> recorded assignee, patch links, verification results, and latest scan status.
|
|
640
|
-
> Do not change anything.
|
|
641
|
-
|
|
642
|
-
After completing connection setup, the same host connection can be used by
|
|
643
|
-
`codex exec`:
|
|
644
|
-
|
|
645
|
-
```bash
|
|
646
|
-
codex exec --ephemeral --json -s read-only 'Use $codex-security:cloud-findings to read findings and the latest scan status for example/security-demo in my selected workspace. Inspect one finding and its report. If the workspace or repository is ambiguous, explain the required selection and stop. Do not change anything.'
|
|
647
|
-
```
|
|
648
|
-
|
|
649
|
-
Noninteractive execution needs an existing authenticated connection; it cannot
|
|
650
|
-
complete first-time sign-in. If authentication expires, the app is unavailable,
|
|
651
|
-
or workspace policy denies access, complete the reported setup action before
|
|
652
|
-
retrying. Those failures do not mean the repository has no findings.
|
|
653
|
-
|
|
654
|
-
Assignment, issue validation, patch checks, periodic fix checks, and finding
|
|
655
|
-
lifecycle status are separate records. Some finding sources do not provide all
|
|
656
|
-
of them. The read workflow reports missing data and incomplete evidence pages,
|
|
657
|
-
and does not describe failed or unfinished scans as clean.
|
|
658
|
-
|
|
659
|
-
### Publish findings to Cloud
|
|
660
|
-
|
|
661
|
-
Use `publish scan --to cloud` for completed Codex Security scans or a Codex
|
|
662
|
-
Security findings CSV. Preview either input offline with `--dry-run`. Uploads
|
|
663
|
-
require a file-backed ChatGPT login. [Cloud publication](docs/cli.md#publish-completed-scans)
|
|
664
|
-
|
|
665
|
-
For a report exported by a scanner, see [Import external findings](#import-external-findings).
|
|
666
|
-
For issue tracking, see [Linear publication](docs/cli.md#publish-completed-scans-to-linear).
|
|
667
|
-
|
|
668
|
-
### Import external findings
|
|
669
|
-
|
|
670
|
-
For a saved scanner report, call `prepareLocalExternalImport` for a checkout
|
|
671
|
-
or `prepareExternalPublication` for a connected Cloud repository. Review the
|
|
672
|
-
returned `preview`, then call `import()` to save locally or `publish()` to
|
|
673
|
-
upload. The [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md)
|
|
674
|
-
list the supported report formats and destinations for each provider.
|
|
675
|
-
|
|
676
|
-
For normalized evidence, use `prepareNormalizedLocalImport(findings, options)`
|
|
677
|
-
or `prepareNormalizedExternalPublication(findings, options)` and review the
|
|
678
|
-
preview in the same way. Cloud file imports use `ExternalPublicationOptions`,
|
|
679
|
-
and normalized Cloud imports use `NormalizedExternalPublicationOptions`. Keep
|
|
680
|
-
Cloud receipts and saved requests when retrying an interrupted submission.
|
|
681
|
-
|
|
682
|
-
Use `listLocalExternalFindings({ repository })` to read saved scanner evidence.
|
|
683
|
-
It starts unassessed. Reimporting the same repository, provider, source key
|
|
684
|
-
and finding ID updates that record. Records omitted from the export remain stored.
|
|
685
|
-
|
|
686
|
-
A local SDK import with only excluded records returns the exclusions and zero
|
|
687
|
-
writes. The CLI exits 2 in that case. When Cloud preparation throws
|
|
688
|
-
`NoPublishableFindingsError`, inspect its `selection` for the read count,
|
|
689
|
-
exclusions and scanner diagnostics. A clean empty report needs no upload.
|
|
690
|
-
|
|
691
|
-
File imports forward repository references from the reader automatically. With
|
|
692
|
-
`prepareNormalizedLocalImport()`, supply additional known references in the
|
|
693
|
-
third argument's `sourceRepositories` when they are absent from
|
|
694
|
-
`evidence.details.repository.url`. For a known GitHub custom host, include
|
|
695
|
-
`platform: "github"`, for example `{ sourceRepositories: [{ url:
|
|
696
|
-
"https://git.example.test/example/project", platform: "github" }] }`. Named Wiz
|
|
697
|
-
reports carry this platform in their repository inventory. If you export only the
|
|
698
|
-
normalized finding rows to JSONL, supply that metadata separately; the original
|
|
699
|
-
finding evidence does not include the surrounding inventory.
|
|
700
|
-
|
|
701
|
-
#### Collect and normalize scanner evidence
|
|
702
|
-
|
|
703
|
-
To collect selected Sonar issues, pass their keys to `collectSonarIssues` in `options.issueKeys`.
|
|
704
|
-
Omit `issueKeys` to collect the project's open security issues. An empty list is rejected.
|
|
705
|
-
If you know the source repository, pass its Git URL in `options.sourceRepositoryUrl`
|
|
706
|
-
to check the Sonar binding before fetching issues.
|
|
707
|
-
|
|
708
|
-
For AWS Continuum code findings, use `readContinuumFindings(path, sourceRepositoryUrl)`
|
|
709
|
-
with a saved list or detail response, or `normalizeContinuumFindings(input, sourceRepositoryUrl)`
|
|
710
|
-
with parsed JSON. Verify the repository for the selected findings before passing its Git URL.
|
|
711
|
-
[Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
|
|
712
|
-
|
|
713
|
-
For a saved Checkmarx One CLI JSON or CxSAST XML report, use
|
|
714
|
-
`readCheckmarxFindings(path, sourceRepositoryUrl, "local")` to inspect its evidence.
|
|
715
|
-
To prepare a local import, pass `provider: "checkmarx"` and the verified
|
|
716
|
-
`sourceRepositoryUrl` to `prepareLocalExternalImport`. Keep each batch of normalized
|
|
717
|
-
Checkmarx findings scoped to one scan and its repository.
|
|
718
|
-
[Checkmarx SAST import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/checkmarx.md)
|
|
719
|
-
|
|
720
|
-
Use `collectSelectedSemgrepGuardianFindings` with a connected Guardian MCP client to
|
|
721
|
-
[capture selected Code or Supply Chain findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-guardian-findings) using the user's Guardian sign-in.
|
|
722
|
-
Use `normalizeSelectedSemgrepPlatformFindings` for selected SAST findings from saved
|
|
723
|
-
Semgrep Web API responses. See the [Semgrep SDK example](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk).
|
|
724
|
-
Use `selectSemgrepPlatformFindings` to [save a selection for the local CLI](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings).
|
|
725
|
-
Use `collectSemgrepPlatformFindings` to [collect one project at an explicit ref](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#collect-a-platform-project-and-branch) for a single product (default `sast`).
|
|
726
|
-
|
|
727
|
-
Use `collectSnykIssues` to [collect existing Open Source or Code issues](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md#existing-issues-from-snyk) for local import or Cloud publication.
|
|
728
|
-
For a private repository with a verified SCM, pass its URL and `platform: "gitlab"` or `"github"` in `sourceRepositories` to match standard SSH clone URLs.
|
|
729
|
-
|
|
730
|
-
To inspect dependency vulnerabilities in a saved Trivy schema-v2 repository or filesystem
|
|
731
|
-
report, call `readTrivyFindings` with the JSON or gzip path. Use `normalizeTrivyFindings`
|
|
732
|
-
for an already parsed report. Supply the scanned directory relative to the checkout
|
|
733
|
-
(`.` for the whole checkout) unless the report's remote target and Git metadata establish it.
|
|
734
|
-
|
|
735
|
-
```ts
|
|
736
|
-
import { readTrivyFindings } from "@openai/codex-security";
|
|
737
|
-
|
|
738
|
-
const { findings, excluded, report } = await readTrivyFindings(
|
|
739
|
-
"trivy.json.gz",
|
|
740
|
-
"local",
|
|
741
|
-
".",
|
|
742
|
-
);
|
|
743
|
-
```
|
|
744
|
-
|
|
745
|
-
## Findings storage and deduplication
|
|
746
|
-
|
|
747
|
-
Saved-scan deduplication uses local SQLite directly:
|
|
748
|
-
|
|
749
|
-
```bash
|
|
750
|
-
cs dedupe --scan SCAN_ID --json
|
|
751
|
-
```
|
|
752
|
-
|
|
753
|
-
The [findings guide](docs/findings-service.md) covers local storage, embedding
|
|
754
|
-
credentials, deduplication, backups, and independently operated HTTP endpoints.
|
|
755
|
-
For an older service deployment, see [migration guidance](docs/findings-service.md#local-service-removal).
|
|
756
|
-
For records stored in your own system, see
|
|
757
|
-
[SDK records deduplication](docs/dedupe-records.md).
|
|
758
|
-
|
|
759
|
-
## Containerized bulk scans
|
|
760
|
-
|
|
761
|
-
Use the scanner image and Compose files to scan a list of repositories with
|
|
762
|
-
persistent results and authentication. See
|
|
763
|
-
[containerized bulk scans](docs/cli.md#containerized-bulk-scans) for setup, or the
|
|
764
|
-
[workflow runner](https://github.com/openai/codex-security/blob/main/docker/README.md#workflow-runner)
|
|
765
|
-
for individual CLI stages in containers.
|
|
71
|
+
By default, results are saved in the private Codex Security state directory.
|
|
72
|
+
Open the Markdown report at the CLI’s **REPORT** path or the SDK’s
|
|
73
|
+
`result.reportPath`. Reports and logs can contain source code, credentials, and
|
|
74
|
+
vulnerability details. Review them before sharing.
|
|
766
75
|
|
|
767
76
|
## Local security model
|
|
768
77
|
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
Local tools running under the same account are trusted.
|
|
772
|
-
|
|
773
|
-
The scan profile allows reads across the local filesystem and writes to workspace
|
|
774
|
-
roots. Execution approvals are reviewed automatically and may grant extra
|
|
775
|
-
permissions for an operation. Set `codexOverrides.approval_policy: "never"`
|
|
776
|
-
(or CLI `--codex "approval_policy='never'"`) to deny permission requests.
|
|
777
|
-
If you select a Codex profile, its explicit `approval_policy` takes precedence
|
|
778
|
-
over the root setting.
|
|
779
|
-
Host and network restrictions still apply.
|
|
780
|
-
|
|
781
|
-
Repository contents, model output, and imported artifacts do not authorize
|
|
782
|
-
access to other targets, disclosure of credentials, or writes outside approved
|
|
783
|
-
paths. Keep state and scan artifacts private and outside the repository.
|
|
784
|
-
|
|
785
|
-
## Compatibility
|
|
786
|
-
|
|
787
|
-
### Package and plugin versions
|
|
788
|
-
|
|
789
|
-
When reporting a problem, run `codex-security info --json` with the installation
|
|
790
|
-
that produced it. For a local SDK installation, run
|
|
791
|
-
`npx @openai/codex-security info --json` in that project. Include `cliVersion`,
|
|
792
|
-
`sdkVersion`, `bundledPluginVersion`, `codexVersion` and `codexSdkVersion`. If
|
|
793
|
-
you supplied a separate plugin or Codex executable, include its version too.
|
|
794
|
-
|
|
795
|
-
For package provenance, compare the registry's `gitHead` and `dist.integrity`
|
|
796
|
-
with the release tag and tarball. If a package omits `gitHead`, use the commit
|
|
797
|
-
in its [verified release attestation](https://github.com/openai/codex-security/blob/main/.github/workflows/node-github-release.yml).
|
|
798
|
-
|
|
799
|
-
### Custom plugins
|
|
800
|
-
|
|
801
|
-
New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
|
|
802
|
-
`workerProviderSnapshot: 4`, and isolated worker configuration support. Older
|
|
803
|
-
custom plugins fail before scan execution; update the plugin or omit `pluginPath`
|
|
804
|
-
to use the bundled version. Reading saved reports does not require these
|
|
805
|
-
execution capabilities.
|
|
806
|
-
|
|
807
|
-
Use the current shell or Windows launcher for runtime-root routing. The SDK does
|
|
808
|
-
not adapt the older `node ./mcp/server.mjs` MCP entrypoint.
|
|
809
|
-
|
|
810
|
-
Custom plugins must support the current workbench protocol for scan comparison
|
|
811
|
-
and archival. The SDK does not adapt older payloads or archive scan directories
|
|
812
|
-
on behalf of older workbench implementations.
|
|
813
|
-
|
|
814
|
-
### Older progress integrations
|
|
815
|
-
|
|
816
|
-
The helper-derived `kind: "preflight"` event, `config_preflight.py` helper, and
|
|
817
|
-
custom capability registries are retired. This includes the `preflightChecks`
|
|
818
|
-
progress-tool input and workbench `--preflight-issues-json` /
|
|
819
|
-
`--preflight-issues-json-stdin` arguments. Scans use available runtime tools and
|
|
820
|
-
parent fallback without a capability registry. Saved preflight history remains
|
|
821
|
-
readable. Local `preflight()` input checks, authentication, sandbox enforcement,
|
|
822
|
-
and Deep worker configuration still apply.
|
|
823
|
-
|
|
824
|
-
### Error types
|
|
825
|
-
|
|
826
|
-
`LocalPluginBootstrapError` identifies local plugin setup failures and extends
|
|
827
|
-
`PluginBootstrapError`, so existing catches keep working. Knowledge-base
|
|
828
|
-
preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
|
|
78
|
+
Scans run with your operating-system permissions. Start them with only the
|
|
79
|
+
credentials they need because subprocesses can inherit your environment.
|
|
829
80
|
|
|
830
81
|
## Documentation and security
|
|
831
82
|
|
|
832
|
-
- [
|
|
833
|
-
- [
|
|
834
|
-
- [
|
|
835
|
-
- [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and feature requests
|
|
836
|
-
- [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md) for private vulnerability reporting
|
|
83
|
+
- [CLI reference](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md) for scan options, authentication, and exports.
|
|
84
|
+
- [SDK guide](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/sdk.md) for configuration, progress events, and the full set of examples.
|
|
85
|
+
- [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md) for reporting vulnerabilities in this package privately.
|