@openai/codex-security 0.1.31 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +442 -2434
- package/_bundled_plugin/.app.json +5 -1
- package/_bundled_plugin/.codex-plugin/plugin.json +9 -5
- package/_bundled_plugin/.mcp.json +3 -0
- package/_bundled_plugin/examples/completed-scan/coverage.json +0 -1
- package/_bundled_plugin/examples/completed-scan/report.md +28 -26
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
- package/_bundled_plugin/mcp/helpers.mjs +1 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +7 -214
- 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/permission-profile-preflight.mjs +563 -0
- package/_bundled_plugin/mcp/server.mjs +1 -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/preflight/capability-profiles.toml +0 -13
- package/_bundled_plugin/references/artifact-storage.md +5 -5
- package/_bundled_plugin/references/config-preflight.md +1 -5
- package/_bundled_plugin/references/core-scan.md +34 -10
- package/_bundled_plugin/references/final-report.md +13 -13
- package/_bundled_plugin/references/finding-detail-fields.md +90 -80
- package/_bundled_plugin/references/sarif-adapter.md +1 -1
- package/_bundled_plugin/references/scan-artifacts.md +3 -4
- package/_bundled_plugin/references/scan-contract.md +11 -6
- package/_bundled_plugin/references/scan-prologue.md +12 -0
- package/_bundled_plugin/references/security-guidance.md +2 -2
- package/_bundled_plugin/references/standalone-validation.md +11 -0
- package/_bundled_plugin/references/threat-model.md +2 -2
- package/_bundled_plugin/schemas/coverage.schema.json +23 -47
- package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +2 -24
- package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +49 -25
- package/_bundled_plugin/schemas/findings.schema.json +71 -192
- package/_bundled_plugin/schemas/scan-manifest.schema.json +83 -95
- package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +91 -83
- package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +35 -64
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +5 -2
- package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +6 -55
- package/_bundled_plugin/schemas/tools/review-items.schema.json +2 -38
- package/_bundled_plugin/schemas/tools/scan-draft.schema.json +245 -356
- package/_bundled_plugin/scripts/codex_profile.mjs +239 -0
- package/_bundled_plugin/scripts/codex_session.mjs +53 -0
- package/_bundled_plugin/scripts/config_preflight.py +29 -69
- package/_bundled_plugin/scripts/deep_scan_config.py +9 -11
- package/_bundled_plugin/scripts/deep_scan_workbench.py +208 -363
- package/_bundled_plugin/scripts/filesystem_identity.py +1 -5
- package/_bundled_plugin/scripts/finalize_scan_contract.py +733 -375
- package/_bundled_plugin/scripts/finding_preview.py +81 -91
- package/_bundled_plugin/scripts/generate_in_scope_files.py +48 -102
- package/_bundled_plugin/scripts/generate_rank_input.py +117 -888
- package/_bundled_plugin/scripts/launch_codex_security_mcp +35 -6
- package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +5 -5
- package/_bundled_plugin/scripts/rank_preview.py +43 -902
- package/_bundled_plugin/scripts/report_projection.py +143 -219
- package/_bundled_plugin/scripts/snapshot_sqlite.py +6 -1
- package/_bundled_plugin/scripts/threat_model_projection.py +161 -0
- package/_bundled_plugin/scripts/validate_scan_contract.py +4 -34
- package/_bundled_plugin/scripts/validate_tracking_source.py +3 -13
- package/_bundled_plugin/scripts/windows_scan_local_files.py +59 -9
- package/_bundled_plugin/scripts/workbench/handoff.py +25 -50
- package/_bundled_plugin/scripts/workbench/runtime_toml.py +22 -0
- package/_bundled_plugin/scripts/workbench/storage.py +21 -6
- package/_bundled_plugin/scripts/workbench_cli.py +99 -190
- package/_bundled_plugin/scripts/workbench_constants.py +6 -14
- package/_bundled_plugin/scripts/workbench_db.py +524 -672
- package/_bundled_plugin/scripts/workbench_feedback.py +6 -3
- package/_bundled_plugin/scripts/workbench_finding_index.py +20 -7
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +18 -4
- package/_bundled_plugin/scripts/workbench_local_dedupe.py +136 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +28 -18
- package/_bundled_plugin/scripts/workbench_progress.py +26 -92
- package/_bundled_plugin/scripts/workbench_publication.py +77 -116
- package/_bundled_plugin/scripts/workbench_remediation.py +14 -20
- package/_bundled_plugin/scripts/workbench_saved_results.py +1402 -263
- package/_bundled_plugin/scripts/workbench_scan_history.py +57 -57
- package/_bundled_plugin/scripts/workbench_scan_start.py +109 -52
- package/_bundled_plugin/scripts/workbench_scan_usage.py +30 -49
- package/_bundled_plugin/scripts/workbench_schema.py +71 -1370
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +16 -7
- package/_bundled_plugin/scripts/workbench_target.py +526 -150
- package/_bundled_plugin/scripts/workbench_target_state.py +1 -5
- package/_bundled_plugin/scripts/workbench_validation.py +19 -44
- package/_bundled_plugin/shared/workbench-history-repairs.json +218 -0
- package/_bundled_plugin/shared/workbench-migrations.json +397 -0
- package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +15 -4
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -0
- package/_bundled_plugin/skills/cloud-findings/SKILL.md +54 -0
- package/_bundled_plugin/skills/cloud-findings/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +6 -6
- package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +3 -3
- package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +50 -20
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +8 -14
- package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
- package/_bundled_plugin/skills/security-scan/SKILL.md +22 -7
- package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +13 -1
- package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
- package/_bundled_plugin/skills/track-findings/SKILL.md +46 -178
- package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
- package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +16 -24
- package/_bundled_plugin/skills/track-findings/references/jira.md +15 -61
- package/_bundled_plugin/skills/triage-finding/SKILL.md +50 -289
- package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +2 -2
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +23 -43
- package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +7 -1
- package/bin/codex-security.mjs +9 -2
- package/dist/api.d.ts +63 -15
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +970 -553
- package/dist/api.js.map +1 -1
- package/dist/artifact-export.d.ts +70 -0
- package/dist/artifact-export.d.ts.map +1 -0
- package/dist/artifact-export.js +292 -0
- package/dist/artifact-export.js.map +1 -0
- package/dist/auth.d.ts +2 -6
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +27 -12
- package/dist/auth.js.map +1 -1
- package/dist/bulk-scan-discovery.d.ts +1 -0
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +9 -9
- package/dist/bulk-scan-discovery.js.map +1 -1
- package/dist/classify-scan-severity.d.ts.map +1 -1
- package/dist/classify-scan-severity.js +2 -5
- package/dist/classify-scan-severity.js.map +1 -1
- package/dist/classify-severity.d.ts +28 -17
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +16 -35
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-help.d.ts +3 -0
- package/dist/cli-help.d.ts.map +1 -0
- package/dist/cli-help.js +285 -0
- package/dist/cli-help.js.map +1 -0
- package/dist/cli-signals.d.ts +8 -0
- package/dist/cli-signals.d.ts.map +1 -0
- package/dist/cli-signals.js +28 -0
- package/dist/cli-signals.js.map +1 -0
- package/dist/cli.d.ts +22 -24
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1660 -1556
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +11 -17
- package/dist/cloud-publish.js.map +1 -1
- package/dist/codeowners.d.ts +19 -0
- package/dist/codeowners.d.ts.map +1 -0
- package/dist/codeowners.js +138 -0
- package/dist/codeowners.js.map +1 -0
- package/dist/codex-prompt.d.ts.map +1 -1
- package/dist/codex-prompt.js +1 -2
- package/dist/codex-prompt.js.map +1 -1
- package/dist/codex-sdk-environment.d.ts +3 -0
- package/dist/codex-sdk-environment.d.ts.map +1 -0
- package/dist/codex-sdk-environment.js +68 -0
- package/dist/codex-sdk-environment.js.map +1 -0
- package/dist/component-plan.d.ts +2 -5
- package/dist/component-plan.d.ts.map +1 -1
- package/dist/component-plan.js +38 -34
- package/dist/component-plan.js.map +1 -1
- package/dist/component-scan.d.ts +7 -5
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +54 -44
- package/dist/component-scan.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +93 -104
- package/dist/config.js.map +1 -1
- package/dist/contract.d.ts +15 -2
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +124 -348
- package/dist/contract.js.map +1 -1
- package/dist/cost-model.d.ts +13 -6
- package/dist/cost-model.d.ts.map +1 -1
- package/dist/cost-model.js +75 -34
- package/dist/cost-model.js.map +1 -1
- package/dist/cost.d.ts +10 -2
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +116 -134
- package/dist/cost.js.map +1 -1
- package/dist/custom-validation-prompt.d.ts.map +1 -1
- package/dist/custom-validation-prompt.js +7 -6
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/custom-validation.d.ts +1 -2
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +23 -16
- package/dist/custom-validation.js.map +1 -1
- package/dist/deduplication/checkpointed-review.d.ts +4 -2
- package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
- package/dist/deduplication/checkpointed-review.js +33 -20
- package/dist/deduplication/checkpointed-review.js.map +1 -1
- package/dist/deduplication/codex-review.d.ts +9 -1
- package/dist/deduplication/codex-review.d.ts.map +1 -1
- package/dist/deduplication/codex-review.js +129 -20
- package/dist/deduplication/codex-review.js.map +1 -1
- package/dist/deduplication/deduplication-prompts.d.ts +5 -2
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
- package/dist/deduplication/deduplication-prompts.js +18 -4
- package/dist/deduplication/deduplication-prompts.js.map +1 -1
- package/dist/deduplication/deduplication-reviewer.d.ts +26 -4
- package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
- package/dist/deduplication/deduplication-reviewer.js +59 -47
- package/dist/deduplication/deduplication-reviewer.js.map +1 -1
- package/dist/deduplication/deduplication.d.ts.map +1 -1
- package/dist/deduplication/deduplication.js +59 -113
- package/dist/deduplication/deduplication.js.map +1 -1
- package/dist/deduplication/diagnostics.d.ts +17 -0
- package/dist/deduplication/diagnostics.d.ts.map +1 -0
- package/dist/deduplication/diagnostics.js +5 -0
- package/dist/deduplication/diagnostics.js.map +1 -0
- package/dist/deduplication/finding-schema.d.ts.map +1 -1
- package/dist/deduplication/finding-schema.js +7 -1
- package/dist/deduplication/finding-schema.js.map +1 -1
- package/dist/deduplication/local.d.ts +31 -0
- package/dist/deduplication/local.d.ts.map +1 -0
- package/dist/deduplication/local.js +166 -0
- package/dist/deduplication/local.js.map +1 -0
- package/dist/deduplication/records-protocol.d.ts.map +1 -1
- package/dist/deduplication/records-protocol.js +12 -28
- package/dist/deduplication/records-protocol.js.map +1 -1
- package/dist/deduplication/records.d.ts +188 -12
- package/dist/deduplication/records.d.ts.map +1 -1
- package/dist/deduplication/records.js +34 -24
- package/dist/deduplication/records.js.map +1 -1
- package/dist/deduplication/review.d.ts +7 -0
- package/dist/deduplication/review.d.ts.map +1 -1
- package/dist/deduplication/review.js.map +1 -1
- package/dist/deduplication/scan.d.ts +9 -3
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +159 -44
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/deep-config.d.ts +2 -1
- package/dist/deep-config.d.ts.map +1 -1
- package/dist/deep-config.js +7 -23
- package/dist/deep-config.js.map +1 -1
- package/dist/deep-progress.d.ts +2 -1
- package/dist/deep-progress.d.ts.map +1 -1
- package/dist/deep-progress.js +32 -47
- package/dist/deep-progress.js.map +1 -1
- package/dist/deep-scan.d.ts +20 -0
- package/dist/deep-scan.d.ts.map +1 -0
- package/dist/deep-scan.js +113 -0
- package/dist/deep-scan.js.map +1 -0
- package/dist/errors.d.ts +5 -2
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +7 -7
- package/dist/errors.js.map +1 -1
- package/dist/feedback.d.ts.map +1 -1
- package/dist/feedback.js +53 -21
- package/dist/feedback.js.map +1 -1
- package/dist/finding-catalogue.d.ts.map +1 -1
- package/dist/finding-catalogue.js +26 -30
- package/dist/finding-catalogue.js.map +1 -1
- package/dist/finding-normalization.d.ts +5 -0
- package/dist/finding-normalization.d.ts.map +1 -0
- package/dist/finding-normalization.js +120 -0
- package/dist/finding-normalization.js.map +1 -0
- package/dist/finding-retrieval.d.ts +9 -0
- package/dist/finding-retrieval.d.ts.map +1 -1
- package/dist/finding-retrieval.js.map +1 -1
- package/dist/finding-workflow.d.ts +13 -8
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +18 -13
- package/dist/finding-workflow.js.map +1 -1
- package/dist/findings-client.d.ts +2 -1
- package/dist/findings-client.d.ts.map +1 -1
- package/dist/findings-client.js +36 -9
- package/dist/findings-client.js.map +1 -1
- package/dist/findings-errors.d.ts +16 -0
- package/dist/findings-errors.d.ts.map +1 -0
- package/dist/findings-errors.js +24 -0
- package/dist/findings-errors.js.map +1 -0
- package/dist/findings-import.d.ts +1 -1
- package/dist/findings-import.d.ts.map +1 -1
- package/dist/findings-import.js +16 -44
- package/dist/findings-import.js.map +1 -1
- package/dist/github.d.ts.map +1 -1
- package/dist/github.js +9 -4
- package/dist/github.js.map +1 -1
- package/dist/import-scan.d.ts.map +1 -1
- package/dist/import-scan.js +49 -39
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +11 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts +7 -1
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +115 -47
- package/dist/knowledge-base.js.map +1 -1
- package/dist/linear.d.ts.map +1 -1
- package/dist/linear.js +4 -10
- package/dist/linear.js.map +1 -1
- package/dist/mock-scan.d.ts.map +1 -1
- package/dist/mock-scan.js +0 -1
- package/dist/mock-scan.js.map +1 -1
- package/dist/models.d.ts +24 -2
- package/dist/models.d.ts.map +1 -1
- package/dist/models.js.map +1 -1
- package/dist/multiscan.d.ts +9 -3
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +225 -153
- package/dist/multiscan.js.map +1 -1
- package/dist/owner-evidence.d.ts +10 -2
- package/dist/owner-evidence.d.ts.map +1 -1
- package/dist/owner-evidence.js +69 -14
- package/dist/owner-evidence.js.map +1 -1
- package/dist/patch-tui.d.ts.map +1 -1
- package/dist/patch-tui.js +5 -6
- package/dist/patch-tui.js.map +1 -1
- package/dist/project-config-schema.d.ts +10 -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 +5 -3
- package/dist/project-config.js.map +1 -1
- package/dist/prompt-files.d.ts +0 -1
- package/dist/prompt-files.d.ts.map +1 -1
- package/dist/prompt-files.js +2 -4
- package/dist/prompt-files.js.map +1 -1
- package/dist/provider-profile.d.ts +21 -0
- package/dist/provider-profile.d.ts.map +1 -0
- package/dist/provider-profile.js +133 -0
- package/dist/provider-profile.js.map +1 -0
- package/dist/publication-events.d.ts +6 -8
- package/dist/publication-events.d.ts.map +1 -1
- package/dist/publication-events.js +40 -79
- package/dist/publication-events.js.map +1 -1
- package/dist/publication-store.d.ts.map +1 -1
- package/dist/publication-store.js +48 -76
- package/dist/publication-store.js.map +1 -1
- package/dist/publication.d.ts +1 -2
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +7 -16
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts +1 -5
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +138 -199
- package/dist/publish.js.map +1 -1
- package/dist/record.d.ts +2 -0
- package/dist/record.d.ts.map +1 -0
- package/dist/record.js +4 -0
- package/dist/record.js.map +1 -0
- package/dist/request-metadata.d.ts +9 -0
- package/dist/request-metadata.d.ts.map +1 -0
- package/dist/request-metadata.js +13 -0
- package/dist/request-metadata.js.map +1 -0
- package/dist/result.d.ts +4 -1
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +7 -0
- package/dist/result.js.map +1 -1
- package/dist/runtime.d.ts +25 -17
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +619 -255
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan-bootstrap.d.ts +14 -0
- package/dist/saved-scan-bootstrap.d.ts.map +1 -0
- package/dist/saved-scan-bootstrap.js +261 -0
- package/dist/saved-scan-bootstrap.js.map +1 -0
- package/dist/saved-scan.d.ts +1 -1
- package/dist/saved-scan.d.ts.map +1 -1
- package/dist/saved-scan.js +16 -32
- package/dist/saved-scan.js.map +1 -1
- package/dist/scan-activity.d.ts.map +1 -1
- package/dist/scan-activity.js +19 -30
- package/dist/scan-activity.js.map +1 -1
- package/dist/scan-comparison.d.ts +31 -18
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +307 -347
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-dashboard.d.ts +3 -1
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +351 -92
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +55 -15
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-inputs.d.ts +6 -0
- package/dist/scan-inputs.d.ts.map +1 -0
- package/dist/scan-inputs.js +71 -0
- package/dist/scan-inputs.js.map +1 -0
- package/dist/scan-logs.d.ts +2 -3
- package/dist/scan-logs.d.ts.map +1 -1
- package/dist/scan-logs.js +14 -12
- package/dist/scan-logs.js.map +1 -1
- package/dist/scan-sessions.d.ts +4 -0
- package/dist/scan-sessions.d.ts.map +1 -1
- package/dist/scan-sessions.js +18 -3
- package/dist/scan-sessions.js.map +1 -1
- package/dist/scan-settings.d.ts +5 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +4 -0
- package/dist/scan-settings.js.map +1 -1
- package/dist/scan-skill-paths.d.ts +8 -0
- package/dist/scan-skill-paths.d.ts.map +1 -0
- package/dist/scan-skill-paths.js +47 -0
- package/dist/scan-skill-paths.js.map +1 -0
- package/dist/security-policy-cli.d.ts.map +1 -1
- package/dist/security-policy-cli.js +15 -33
- package/dist/security-policy-cli.js.map +1 -1
- package/dist/security-policy.d.ts +17 -9
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +131 -98
- package/dist/security-policy.js.map +1 -1
- package/dist/server/api.d.ts +0 -1
- package/dist/server/api.d.ts.map +1 -1
- package/dist/server/api.js +0 -1
- package/dist/server/api.js.map +1 -1
- package/dist/server/embeddings.d.ts +3 -1
- package/dist/server/embeddings.d.ts.map +1 -1
- package/dist/server/embeddings.js +11 -3
- package/dist/server/embeddings.js.map +1 -1
- package/dist/server/errors.d.ts +5 -2
- package/dist/server/errors.d.ts.map +1 -1
- package/dist/server/errors.js +7 -0
- package/dist/server/errors.js.map +1 -1
- package/dist/server/sqlite-store.d.ts +0 -2
- package/dist/server/sqlite-store.d.ts.map +1 -1
- package/dist/server/sqlite-store.js +55 -55
- package/dist/server/sqlite-store.js.map +1 -1
- package/dist/server/storage.d.ts +0 -2
- package/dist/server/storage.d.ts.map +1 -1
- package/dist/server/storage.js.map +1 -1
- package/dist/severity-store.js +20 -32
- package/dist/severity-store.js.map +1 -1
- package/dist/standalone-validation-prompt.d.ts +2 -0
- package/dist/standalone-validation-prompt.d.ts.map +1 -0
- package/dist/standalone-validation-prompt.js +10 -0
- package/dist/standalone-validation-prompt.js.map +1 -0
- package/dist/suggest-owners.d.ts +6 -5
- package/dist/suggest-owners.d.ts.map +1 -1
- package/dist/suggest-owners.js +15 -10
- package/dist/suggest-owners.js.map +1 -1
- package/dist/targets.d.ts +12 -0
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +124 -62
- package/dist/targets.js.map +1 -1
- package/dist/trusted-executable.d.ts +6 -1
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +28 -9
- package/dist/trusted-executable.js.map +1 -1
- package/dist/value.d.ts +2 -0
- package/dist/value.d.ts.map +1 -0
- package/dist/value.js +27 -0
- package/dist/value.js.map +1 -0
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +3 -6
- package/dist/version.js.map +1 -1
- package/dist/windows-path.d.ts.map +1 -1
- package/dist/windows-path.js +1 -2
- package/dist/windows-path.js.map +1 -1
- package/dist/workbench-arguments.d.ts +3 -0
- package/dist/workbench-arguments.d.ts.map +1 -0
- package/dist/workbench-arguments.js +15 -0
- package/dist/workbench-arguments.js.map +1 -0
- package/dist/worker-progress.d.ts +2 -0
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +40 -46
- package/dist/worker-progress.js.map +1 -1
- package/docs/cli.md +1778 -0
- package/docs/dedupe-records.md +24 -0
- package/docs/findings-service.md +402 -0
- package/package.json +23 -23
- package/schemas/project-config.schema.json +5 -0
- package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +0 -18
- package/_bundled_plugin/scripts/normalize_candidates.py +0 -338
- package/_bundled_plugin/scripts/workbench_dashboard.py +0 -159
- package/_bundled_plugin/scripts/workbench_findings.py +0 -221
- package/_bundled_plugin/scripts/workbench_severity.py +0 -119
- package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +0 -163
- package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +0 -276
- package/dist/server/dashboard/app.css +0 -2
- package/dist/server/dashboard/app.js +0 -66
- package/dist/server/dashboard/index.html +0 -18
- package/dist/server/dashboard-types.d.ts +0 -48
- package/dist/server/dashboard-types.d.ts.map +0 -1
- package/dist/server/dashboard-types.js +0 -2
- package/dist/server/dashboard-types.js.map +0 -1
- package/dist/server/dashboard.d.ts +0 -6
- package/dist/server/dashboard.d.ts.map +0 -1
- package/dist/server/dashboard.js +0 -59
- package/dist/server/dashboard.js.map +0 -1
- package/dist/server/findings-service.d.ts +0 -20
- package/dist/server/findings-service.d.ts.map +0 -1
- package/dist/server/findings-service.js +0 -31
- package/dist/server/findings-service.js.map +0 -1
- package/dist/server/index.d.ts +0 -2
- package/dist/server/index.d.ts.map +0 -1
- package/dist/server/index.js +0 -6
- package/dist/server/index.js.map +0 -1
- package/dist/server/routes.d.ts +0 -6
- package/dist/server/routes.d.ts.map +0 -1
- package/dist/server/routes.js +0 -86
- package/dist/server/routes.js.map +0 -1
- package/dist/server/serve.d.ts +0 -2
- package/dist/server/serve.d.ts.map +0 -1
- package/dist/server/serve.js +0 -28
- package/dist/server/serve.js.map +0 -1
- package/dist/server/server.d.ts +0 -10
- package/dist/server/server.d.ts.map +0 -1
- package/dist/server/server.js +0 -17
- package/dist/server/server.js.map +0 -1
- package/dist/server/validation.d.ts +0 -17
- package/dist/server/validation.d.ts.map +0 -1
- package/dist/server/validation.js +0 -53
- package/dist/server/validation.js.map +0 -1
package/docs/cli.md
ADDED
|
@@ -0,0 +1,1778 @@
|
|
|
1
|
+
# CLI and workflows
|
|
2
|
+
|
|
3
|
+
The global installation provides both `codex-security` and its short alias `cs`.
|
|
4
|
+
They accept the same arguments and options. The examples below use
|
|
5
|
+
`codex-security`; you can also use `cs` or, without a global installation,
|
|
6
|
+
`npx @openai/codex-security`. See the [installation guide](../README.md#install).
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
codex-security --help
|
|
10
|
+
codex-security scan --help
|
|
11
|
+
codex-security --version
|
|
12
|
+
codex-security info --json
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`--help` lists commands by task; `<command> --help` lists its options.
|
|
16
|
+
`info --json` reports package, plugin, runtime, and model details.
|
|
17
|
+
`scans` and `findings` default to their `list` subcommands.
|
|
18
|
+
|
|
19
|
+
## Authentication
|
|
20
|
+
|
|
21
|
+
Sign in with ChatGPT, or supply an API key for CI:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
codex-security login
|
|
25
|
+
codex-security scan .
|
|
26
|
+
|
|
27
|
+
# Save an API key from the environment.
|
|
28
|
+
printenv OPENAI_API_KEY | codex-security login --with-api-key
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`OPENAI_API_KEY` and `CODEX_API_KEY` also work without saving a login.
|
|
32
|
+
Environment keys apply to the current command; only `login --with-api-key`
|
|
33
|
+
saves them. `login --with-access-token` accepts a Codex access token on stdin.
|
|
34
|
+
Access-token environment variables are not scan API keys.
|
|
35
|
+
|
|
36
|
+
On remote or headless machines, use `login --device-auth` if your workspace
|
|
37
|
+
allows it. If device auth is disabled, use SSH forwarding below.
|
|
38
|
+
|
|
39
|
+
On Windows, set a key in PowerShell:
|
|
40
|
+
|
|
41
|
+
```powershell
|
|
42
|
+
$env:OPENAI_API_KEY = "<your-api-key>"
|
|
43
|
+
codex-security scan C:\code\repository
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Remote login with SSH forwarding
|
|
47
|
+
|
|
48
|
+
On your local machine, open a tunnel to the remote host:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
ssh -L 1455:localhost:1455 user@remote-host
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Run `codex-security login` in that SSH session and open its sign-in URL in
|
|
55
|
+
your local browser. Keep SSH connected until login finishes.
|
|
56
|
+
|
|
57
|
+
### OpenAI credentials
|
|
58
|
+
|
|
59
|
+
Interactive scans ask which credentials to use when both ChatGPT and an
|
|
60
|
+
environment API key are available. Noninteractive commands prefer
|
|
61
|
+
`OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
|
|
62
|
+
with `--auth`:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
codex-security scan . --auth chatgpt
|
|
66
|
+
codex-security scan . --auth api-key
|
|
67
|
+
codex-security patch OCCURRENCE_ID --auth chatgpt
|
|
68
|
+
codex-security verify-fix OCCURRENCE_ID --auth api-key
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`--auth chatgpt` ignores environment API keys. `--auth api-key` requires a key.
|
|
72
|
+
The default is `auto`. Scans, validation, patching, and fix verification share
|
|
73
|
+
the stored login. Patch follow-up assessments and `scan --patch` retain the
|
|
74
|
+
chosen authentication. Environment keys do not replace the saved login.
|
|
75
|
+
The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
|
|
76
|
+
|
|
77
|
+
Stored OpenAI credentials live in
|
|
78
|
+
`$CODEX_SECURITY_STATE_DIR/codex-home`, or
|
|
79
|
+
`$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
|
|
80
|
+
outside the target and every enclosing Git worktree. It also serves providers
|
|
81
|
+
with `requires_openai_auth = true`.
|
|
82
|
+
|
|
83
|
+
Codex carries credential-storage, forced-login, and workspace settings from the
|
|
84
|
+
ambient configuration into this home. Managed-device policies still apply;
|
|
85
|
+
workspace-managed policies may require ChatGPT credentials even with an API key.
|
|
86
|
+
Without an overriding environment API key, scans and status checks import
|
|
87
|
+
existing file-based Codex credentials when this home is empty. Import errors make
|
|
88
|
+
`login status` exit with code 2 and SDK `account()` reject its promise. Logout
|
|
89
|
+
disables imports until you log in again. Status imports and logout share the
|
|
90
|
+
credential-home lock so a concurrent status check cannot restore credentials
|
|
91
|
+
after logout completes.
|
|
92
|
+
|
|
93
|
+
Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
|
|
94
|
+
`HOME` or `USERPROFILE` environment setting.
|
|
95
|
+
|
|
96
|
+
If credentials cannot refresh, run `login status`. Retry if the sign-in recently
|
|
97
|
+
changed; otherwise run `logout`, then `login`.
|
|
98
|
+
Some cybersecurity requests and protected findings require
|
|
99
|
+
[Trusted Access for Cyber](https://chatgpt.com/cyber).
|
|
100
|
+
|
|
101
|
+
### Daybreak Blue with an API key
|
|
102
|
+
|
|
103
|
+
The [Responses API defaults](https://developers.openai.com/api/docs/guides/daybreak#understand-defaults-when-omitted)
|
|
104
|
+
can apply Daybreak Blue to compatible mainline models when the API organization
|
|
105
|
+
and project have access. An omitted `access_programs.cyber` field does not by
|
|
106
|
+
itself mean that Daybreak treatment is disabled.
|
|
107
|
+
|
|
108
|
+
Choose a compatible model available to your project and select Daybreak Blue
|
|
109
|
+
explicitly:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
codex-security scan /path/to/repository \
|
|
113
|
+
--auth api-key --model "<model>" --cyber-access-program daybreak_blue
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
In the SDK, select your model through `codexOverrides.model` and pass
|
|
117
|
+
`auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
|
|
118
|
+
Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
|
|
119
|
+
The selection reaches discovery and reducer workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
|
|
120
|
+
for configuration precedence and the API-key feature setting.
|
|
121
|
+
|
|
122
|
+
The previously documented `gpt-daybreak-blue-latest` alias is
|
|
123
|
+
[deprecated](https://developers.openai.com/api/docs/models/gpt-daybreak-blue-latest).
|
|
124
|
+
Use a current model available to your project. `access_programs.cyber` is a
|
|
125
|
+
Responses API field; use the supported selector instead of passing it as a
|
|
126
|
+
`--codex` configuration key.
|
|
127
|
+
|
|
128
|
+
### Select a Cyber access program
|
|
129
|
+
|
|
130
|
+
For the built-in OpenAI provider, choose `standard`, `daybreak_blue`, or
|
|
131
|
+
`daybreak_red`:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
codex-security scan . --auth api-key --cyber-access-program daybreak_blue
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
await security.run("/path/to/repository", {
|
|
139
|
+
auth: "api-key",
|
|
140
|
+
cyberAccessProgram: "daybreak_blue",
|
|
141
|
+
});
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`scan-components` accepts the same flag. Project files use
|
|
145
|
+
`scan.cyber_access_program`, including for bulk scans. Explicit CLI or SDK values
|
|
146
|
+
override the file; omission preserves Codex defaults. `standard` explicitly
|
|
147
|
+
selects the standard program.
|
|
148
|
+
|
|
149
|
+
The selection applies to workers, resumed scans, planning, matching, and scan
|
|
150
|
+
follow-ups. Recipes retain it for resume and rerun. API-key selection enables
|
|
151
|
+
Codex's experimental Cyber support unless native configuration explicitly disables
|
|
152
|
+
`features.api_key_cyber_access_programs`. A selection does not grant entitlement;
|
|
153
|
+
explicit disables and access denials remain errors.
|
|
154
|
+
|
|
155
|
+
### Native command authentication and other providers
|
|
156
|
+
|
|
157
|
+
SDK callers can select a native command provider through
|
|
158
|
+
`codexOverrides.model_providers.<id>.auth` and `model_provider`, including a
|
|
159
|
+
selected profile. Codex runs the credential helper and renews its token. Scans,
|
|
160
|
+
comparisons, and deduplication preserve that selection. Relative helper paths and
|
|
161
|
+
`auth.cwd` resolve from `CODEX_HOME` (default `~/.codex`). Comparisons and reviews
|
|
162
|
+
also honor the selected command provider in that home's `config.toml`.
|
|
163
|
+
|
|
164
|
+
For other providers, set their key and select a model the provider supports:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
export OPENROUTER_API_KEY="<your-openrouter-api-key>"
|
|
168
|
+
codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
|
|
169
|
+
|
|
170
|
+
export FIREWORKS_API_KEY="<your-fireworks-api-key>"
|
|
171
|
+
codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Amazon Bedrock
|
|
175
|
+
|
|
176
|
+
Use AWS credentials and a region with access to the exact Bedrock model ID:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
export AWS_PROFILE="security-scan"
|
|
180
|
+
export AWS_REGION="us-east-2"
|
|
181
|
+
codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Run credential setup and the scan in the same shell or job. Bedrock scanning
|
|
185
|
+
uses AWS authentication, including in Deep Scan workers; it does not need an
|
|
186
|
+
OpenAI API key or separate CLI login. Publishing to Cloud requires separate
|
|
187
|
+
ChatGPT credentials. `info` and `--dry-run` do not verify AWS access.
|
|
188
|
+
|
|
189
|
+
See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
|
|
190
|
+
for credential alternatives, restricted-model access, cost estimates, and
|
|
191
|
+
reasoning-summary configuration.
|
|
192
|
+
|
|
193
|
+
## Generate a security policy
|
|
194
|
+
|
|
195
|
+
Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
|
|
196
|
+
the project's security boundaries and what should count as a finding. This step
|
|
197
|
+
is optional: you can scan with an existing policy or without one.
|
|
198
|
+
|
|
199
|
+
From the repository root, run:
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
codex-security policy .
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The command saves a draft outside the repository and leaves existing files
|
|
206
|
+
unchanged. In a terminal, it asks about facts the source cannot establish and
|
|
207
|
+
shows the proposed diff.
|
|
208
|
+
|
|
209
|
+
1. Read the saved `SECURITY.md`, diff, and **Review notes**. Edit the draft as
|
|
210
|
+
needed. Preserve reporting instructions and confirm exclusions, accepted
|
|
211
|
+
risks, and severity decisions with the project owner.
|
|
212
|
+
2. If you choose to use the draft, copy only the reviewed `SECURITY.md` to the
|
|
213
|
+
displayed **Policy target**. Keep the supporting documents outside the
|
|
214
|
+
repository.
|
|
215
|
+
3. Run `codex-security scan .`. The scan reads the policy from the repository.
|
|
216
|
+
|
|
217
|
+
If you reject the draft, skip the copy and scan with your existing policy or
|
|
218
|
+
without one. If the command reports that `SECURITY.md` is already up to date, no
|
|
219
|
+
copy is needed; review any notes and continue to the scan.
|
|
220
|
+
|
|
221
|
+
You can leave answers blank during generation. Keep unresolved decisions
|
|
222
|
+
explicit in any policy you adopt, or scan without adopting the draft while you
|
|
223
|
+
resolve them. Regenerate if relevant source or neighboring policies changed
|
|
224
|
+
during generation.
|
|
225
|
+
|
|
226
|
+
### Existing policies and components
|
|
227
|
+
|
|
228
|
+
If your existing root or component `SECURITY.md` already describes the relevant
|
|
229
|
+
security boundaries, scan with it directly. To propose an update, use `policy .`
|
|
230
|
+
for the root policy or select a component:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
codex-security policy . --path services/api
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
This drafts `services/api/SECURITY.md`, whether or not that file already exists.
|
|
237
|
+
The repository defaults to the current directory. A component inherits policies
|
|
238
|
+
from its Git root, with the closest policy taking precedence. Inherited policies
|
|
239
|
+
may refer to ancestor `SECURITY.md` files or the checkout's `.github/SECURITY.md`
|
|
240
|
+
and `docs/SECURITY.md`; they cannot widen the component's scope.
|
|
241
|
+
|
|
242
|
+
A `.github/SECURITY.md` or `docs/SECURITY.md` often describes how to report
|
|
243
|
+
vulnerabilities. Keep those instructions: these files do not automatically
|
|
244
|
+
provide repository-wide scan guidance. Use a root `SECURITY.md` for that guidance,
|
|
245
|
+
or a component `SECURITY.md` for guidance specific to that directory. Before
|
|
246
|
+
replacing the policy target, check whether either reporting file links to it;
|
|
247
|
+
the replacement can affect their guidance too.
|
|
248
|
+
|
|
249
|
+
### Generation options and saved files
|
|
250
|
+
|
|
251
|
+
Generation describes the system, builds a threat model, then drafts the policy.
|
|
252
|
+
Add context with `--knowledge-base`:
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
codex-security policy . --knowledge-base architecture.md
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
| Invocation | Result |
|
|
259
|
+
| ---------------------------- | -------------------------------------------------------- |
|
|
260
|
+
| `policy . --headless --json` | Generate without prompts; return paths and review notes. |
|
|
261
|
+
| `policy . --format md` | Generate and write the draft to stdout. |
|
|
262
|
+
| `policy . --dry-run --json` | Check local inputs without calling Codex. |
|
|
263
|
+
|
|
264
|
+
`--headless` leaves unanswered questions in the review notes. By default, files
|
|
265
|
+
go in the Codex Security state directory. To choose a location, use an empty
|
|
266
|
+
directory outside every enclosing checkout and its Git metadata:
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
codex-security policy . --path services/api --headless \
|
|
270
|
+
--output-dir /path/outside/repository/api-policy --json
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
| Artifact | Contents |
|
|
274
|
+
| ---------------------- | ----------------------------------------------- |
|
|
275
|
+
| `SECURITY.md` | Policy draft. |
|
|
276
|
+
| `threatmodel.md` | Threat model with source references. |
|
|
277
|
+
| `project-spec.md` | System description and security boundaries. |
|
|
278
|
+
| `previous-SECURITY.md` | Original policy used for the diff. |
|
|
279
|
+
| `policy-draft.json` | Target, hashes, stage status, and review notes. |
|
|
280
|
+
|
|
281
|
+
Keep supporting documents private until reviewed for disclosure. If governing
|
|
282
|
+
policies change during generation, the documents remain for inspection but no
|
|
283
|
+
completed-draft manifest is written. A preview failure reports saved paths.
|
|
284
|
+
|
|
285
|
+
`--max-cost` applies to the whole generation. Progress goes to stderr;
|
|
286
|
+
`--json` includes status and estimated cost. `--full-output` reports failures
|
|
287
|
+
with `ok: false`. If a stage cannot inspect required evidence, generation stops
|
|
288
|
+
and keeps completed documents. Fix the problem and retry in a new directory.
|
|
289
|
+
|
|
290
|
+
### Source access and restrictions
|
|
291
|
+
|
|
292
|
+
The command uses scan authentication and read-only access to the selected source.
|
|
293
|
+
It denies Git metadata and sibling-component access, disables network, web, apps,
|
|
294
|
+
and MCP, and uses only Codex's core shell environment. Knowledge-base text stays
|
|
295
|
+
in private review artifacts during generation and is removed afterward.
|
|
296
|
+
|
|
297
|
+
Targets and links stay within the checkout and outside Git metadata. Linked
|
|
298
|
+
worktrees and initialized submodules use their own roots. For a separate Git
|
|
299
|
+
directory, set `core.worktree` to the checkout's absolute path; use
|
|
300
|
+
`git worktree repair` for moved linked worktrees.
|
|
301
|
+
|
|
302
|
+
Generation currently fails on Unix directories with non-UTF-8 names. On macOS,
|
|
303
|
+
the bundled runtime does not fully enforce write restrictions under `/tmp`
|
|
304
|
+
(including `/private/tmp`); keep source and artifacts elsewhere when read-only
|
|
305
|
+
enforcement is required. See the
|
|
306
|
+
[upstream sandbox issue](https://github.com/openai/codex/issues/32395).
|
|
307
|
+
|
|
308
|
+
### Generate a policy from TypeScript
|
|
309
|
+
|
|
310
|
+
```ts
|
|
311
|
+
import { CodexSecurity } from "@openai/codex-security";
|
|
312
|
+
|
|
313
|
+
const security = new CodexSecurity();
|
|
314
|
+
try {
|
|
315
|
+
const draft = await security.generatePolicy("/path/to/repository", {
|
|
316
|
+
path: "services/api",
|
|
317
|
+
knowledgeBasePaths: ["/path/to/architecture.md"],
|
|
318
|
+
onStage: (stage) => console.error(stage),
|
|
319
|
+
});
|
|
320
|
+
console.log(await security.previewPolicy(draft));
|
|
321
|
+
// Review the saved policy at draft.draftPath before installing it.
|
|
322
|
+
} finally {
|
|
323
|
+
await security.close();
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
`preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied
|
|
328
|
+
in-memory draft and escapes terminal controls; editing its saved file does not
|
|
329
|
+
change that object. `securityPolicyDiff()` returns a raw diff for files and other
|
|
330
|
+
non-terminal uses, with an optional Python interpreter.
|
|
331
|
+
|
|
332
|
+
`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
|
|
333
|
+
`maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives
|
|
334
|
+
groups of up to three owner questions and a cancellation signal. Without the
|
|
335
|
+
callback, questions remain unresolved.
|
|
336
|
+
|
|
337
|
+
## Scan options and output
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
codex-security scan .
|
|
341
|
+
codex-security scan . --path src --path tests
|
|
342
|
+
codex-security scan . --diff origin/main --json
|
|
343
|
+
codex-security scan . --working-tree
|
|
344
|
+
codex-security scan . --output-dir /path/outside/repository/results --dry-run
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
`--diff` scans committed changes; `--working-tree` scans staged and unstaged
|
|
348
|
+
changes. Deep scans support whole repositories and path scopes. Working-tree
|
|
349
|
+
snapshots include untracked nested Git repositories. Initialized submodules must
|
|
350
|
+
be clean and at the commit recorded by the parent.
|
|
351
|
+
|
|
352
|
+
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
353
|
+
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
354
|
+
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
355
|
+
with every repository.
|
|
356
|
+
|
|
357
|
+
Output directories must be empty and outside the scanned directory and enclosing
|
|
358
|
+
Git worktree. On macOS/Linux, existing directories must be private (`chmod 700`).
|
|
359
|
+
`--archive-existing` moves earlier output to
|
|
360
|
+
`<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
|
|
361
|
+
SARIF, when produced, is saved at `<scan-dir>/exports/results.sarif`.
|
|
362
|
+
|
|
363
|
+
Completed scans exit with `0` by default. Configure `--fail-on-severity high`
|
|
364
|
+
to return `1` for high or critical findings. Scope exclusions, skipped files, and follow-up notes
|
|
365
|
+
do not fail a scan or bypass the findings threshold. Execution, target-integrity,
|
|
366
|
+
and required-output failures exit with `2`.
|
|
367
|
+
|
|
368
|
+
New reports omit `coverage.completeness`. Use `manifest.scan.status` and the
|
|
369
|
+
command exit code to distinguish execution failures from findings-policy violations.
|
|
370
|
+
Legacy completeness values affect neither.
|
|
371
|
+
Bulk and component summaries report completed and failed scans without an
|
|
372
|
+
`incomplete` count. Component matching errors have status `failed`.
|
|
373
|
+
|
|
374
|
+
New drafts use the current finding schema: `codeEvidence`, `rootCause`,
|
|
375
|
+
`attackPath.dataflow`, and `evidenceRefs`. Source snippets belong in
|
|
376
|
+
`codeEvidence`; `rootCause.evidenceRefs` links to them. Legacy aliases and
|
|
377
|
+
malformed optional fields are rejected before completion rather than repaired.
|
|
378
|
+
This applies to model-authored files, worker results, custom validation, and new
|
|
379
|
+
imports. Existing sealed reports remain readable and exportable without
|
|
380
|
+
rewriting their contents. Older unfinished drafts must be updated to the current
|
|
381
|
+
schema or completed with their original CLI/plugin version.
|
|
382
|
+
|
|
383
|
+
`scan`, `scans rerun`, and `scans resume` execution failures with `--json`, JSON,
|
|
384
|
+
or JSONL output produce:
|
|
385
|
+
|
|
386
|
+
```json
|
|
387
|
+
{ "status": "failed", "code": "SCAN_FAILED", "message": "..." }
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
With `--full-output`, the error appears under `error` in an `ok: false` envelope.
|
|
391
|
+
If the scan target changed, the error explains that the results no longer
|
|
392
|
+
represent the current checkout. Retained sealed results remain available under
|
|
393
|
+
`data`, including their manifest, findings, coverage, scan directory, and report
|
|
394
|
+
path. Unsealed or invalid artifacts are not included. This also applies to
|
|
395
|
+
`scans rerun` and `scans resume`.
|
|
396
|
+
For `scans rerun` and `scans resume`, `--filter-output` applies to retained `data`;
|
|
397
|
+
selecting an unavailable field can return `null` or omit `data`.
|
|
398
|
+
|
|
399
|
+
Saved-scan setup failures use the same output shape with
|
|
400
|
+
`SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
|
|
401
|
+
available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
|
|
402
|
+
scan uses `SCAN_IMPORT_FAILED` if the import fails. Other output formats retain
|
|
403
|
+
stderr-only failures, including when `--full-output` is selected.
|
|
404
|
+
|
|
405
|
+
Diagnostics stay on stderr. Each command's `--schema --format json` describes
|
|
406
|
+
its successful output and failure codes.
|
|
407
|
+
See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
408
|
+
|
|
409
|
+
### Project files
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
codex-security init
|
|
413
|
+
codex-security scan . -c codex-security.yaml --dry-run --json
|
|
414
|
+
codex-security info -c codex-security.yaml --json
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
|
|
418
|
+
Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
|
|
419
|
+
`scan-components`, and `info` accept project files. SDK calls and saved reruns
|
|
420
|
+
do not load them automatically.
|
|
421
|
+
|
|
422
|
+
Treat the selected file as trusted operator configuration: native settings can
|
|
423
|
+
start MCP processes and choose model-service destinations. Keep CI scanner
|
|
424
|
+
configuration outside the untrusted checkout being assessed.
|
|
425
|
+
|
|
426
|
+
See [Project configuration](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)
|
|
427
|
+
for settings, precedence, paths, schemas, and SDK loading. File paths resolve
|
|
428
|
+
from the config directory; scope paths resolve from the repository.
|
|
429
|
+
|
|
430
|
+
### Import findings as a saved scan
|
|
431
|
+
|
|
432
|
+
```bash
|
|
433
|
+
codex-security scan import --csv /path/to/findings.csv
|
|
434
|
+
codex-security scan import --json /path/to/findings.json --format json
|
|
435
|
+
codex-security scan import --csv /path/to/findings.csv --dry-run
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
Supply exactly one input. CSV follows the
|
|
439
|
+
[findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
|
|
440
|
+
JSON accepts a complete `codex-security.findings` document or
|
|
441
|
+
`{ "findings": [...] }` matching the findings schema. For this command, `--json`
|
|
442
|
+
selects the input file; use `--format json` for JSON output. The input must be a
|
|
443
|
+
regular file with no symlinks or directory junctions in its path.
|
|
444
|
+
|
|
445
|
+
Each import creates a completed scan in local history, retains the input under
|
|
446
|
+
`artifacts/import/`, and preserves each occurrence, including duplicates.
|
|
447
|
+
Original identifiers live in `extensions.import`; referenced writeup paths are
|
|
448
|
+
metadata only. Completion means import finished; no security analysis occurred.
|
|
449
|
+
Import needs no model calls or authentication. `--dry-run` validates without
|
|
450
|
+
saving; `--output-dir` and `--archive-existing` control output. `scans rerun`
|
|
451
|
+
reimports the retained input.
|
|
452
|
+
|
|
453
|
+
### Generate mock scan results
|
|
454
|
+
|
|
455
|
+
```bash
|
|
456
|
+
codex-security scan /path/to/repository --mock
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
The SDK equivalent is `security.run(repository, { mock: true })`. Mock scans
|
|
460
|
+
save synthetic results through the normal reporting and history flow without
|
|
461
|
+
model calls or authentication. Each contains 12 findings: eight stable across
|
|
462
|
+
runs, four with new identities, and two duplicate pairs for testing deduplication.
|
|
463
|
+
Paths and snippets are fictional; repository files remain unchanged.
|
|
464
|
+
|
|
465
|
+
Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
|
|
466
|
+
archiving, and severity thresholds work normally. Reruns preserve mock mode.
|
|
467
|
+
Separate matching or deduplication commands still make their usual model calls.
|
|
468
|
+
|
|
469
|
+
Mock mode supports Standard repository, path, and diff scans. It cannot combine
|
|
470
|
+
with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan prompts.
|
|
471
|
+
Scan prompts and knowledge bases do not change the fixtures.
|
|
472
|
+
|
|
473
|
+
### Attribute scans to end users
|
|
474
|
+
|
|
475
|
+
Pass a stable hashed ID when scanning on behalf of users:
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
codex-security scan . --auth api-key --safety-identifier hashed-user-id
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
```ts
|
|
482
|
+
await security.run("/path/to/repository", {
|
|
483
|
+
auth: "api-key",
|
|
484
|
+
safetyIdentifier: hashedUserId,
|
|
485
|
+
});
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
Use 1–64 characters, with no NUL or personal data such as email addresses.
|
|
489
|
+
The ID applies to workers, retries, and follow-ups. Supply it again for reruns.
|
|
490
|
+
|
|
491
|
+
The bundled runtime does not yet support native `--safety-identifier`; select a
|
|
492
|
+
compatible build with `CODEX_CLI_PATH` and a plugin that forwards it to workers.
|
|
493
|
+
The SDK checks the format, not runtime/plugin compatibility. Older versions may
|
|
494
|
+
omit the ID.
|
|
495
|
+
|
|
496
|
+
### Scan project components
|
|
497
|
+
|
|
498
|
+
`scan --path` runs one scan over selected paths. `scan-components` runs a separate
|
|
499
|
+
scan for each component:
|
|
500
|
+
|
|
501
|
+
```bash
|
|
502
|
+
codex-security scan-components /path/to/project \
|
|
503
|
+
--component apps/api --component apps/web --component packages/shared \
|
|
504
|
+
--workers 4 --output-dir /path/outside/project/results
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Use `-c FILE` to share scan settings, including Deep mode, context, cost limits,
|
|
508
|
+
and severity policy. Component plans override the file's scope. Use `--auto` to
|
|
509
|
+
propose a split, then review the saved plan:
|
|
510
|
+
|
|
511
|
+
```bash
|
|
512
|
+
codex-security scan-components . --auto --plan-only \
|
|
513
|
+
--output-dir /path/outside/project/plan
|
|
514
|
+
codex-security scan-components . \
|
|
515
|
+
--components-file /path/outside/project/plan/components.json \
|
|
516
|
+
--output-dir /path/outside/project/results
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
Plans use repository-relative paths:
|
|
520
|
+
|
|
521
|
+
```json
|
|
522
|
+
{
|
|
523
|
+
"components": [
|
|
524
|
+
{ "name": "API", "paths": ["apps/api", "packages/auth"] },
|
|
525
|
+
{ "name": "Web", "paths": ["apps/web"] }
|
|
526
|
+
]
|
|
527
|
+
}
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
Automatic planning respects Git ignore rules and includes omitted inventory
|
|
531
|
+
files in `Other files` components. Large inventories require multiple planning
|
|
532
|
+
calls and may produce more components. Planning leaves source unchanged.
|
|
533
|
+
|
|
534
|
+
Each component saves artifacts under `component-N/`. Combined `findings.json`
|
|
535
|
+
groups high-confidence root-cause matches, keeping original IDs and the highest
|
|
536
|
+
severity. Uncertain matches stay separate. `summary.json` records component execution and
|
|
537
|
+
matching status; `report.md` links to component reports. Export or publish each
|
|
538
|
+
individual scan folder.
|
|
539
|
+
|
|
540
|
+
Failures do not stop other components. Failed scans or
|
|
541
|
+
failed matching return `2`; severity-policy violations return `1`. Retry with
|
|
542
|
+
`--components-file retry-components.json` and a new empty output directory.
|
|
543
|
+
The retry report covers only those components.
|
|
544
|
+
|
|
545
|
+
`--max-cost` applies per component, excluding planning and matching. `--model`
|
|
546
|
+
and `--effort` also apply to matching; `--auth` applies throughout. Planning and
|
|
547
|
+
matching reject ambient command providers that conflict with explicit ChatGPT
|
|
548
|
+
or API-key auth. SDK-selected command providers retain their authentication.
|
|
549
|
+
|
|
550
|
+
From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
|
|
551
|
+
Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
|
|
552
|
+
planning and authentication choices.
|
|
553
|
+
|
|
554
|
+
### Configure deep scans
|
|
555
|
+
|
|
556
|
+
```ts
|
|
557
|
+
await security.run("/path/to/repository", {
|
|
558
|
+
mode: "deep",
|
|
559
|
+
workers: 2,
|
|
560
|
+
subagents: 0,
|
|
561
|
+
stopAfterNoNew: 3,
|
|
562
|
+
stopAfterConsecutiveErrors: 2,
|
|
563
|
+
maxDiscoveryRuns: 10,
|
|
564
|
+
maxTimeHours: 1.5,
|
|
565
|
+
});
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
For `scan --mode deep`, `--workers` controls discovery concurrency and
|
|
569
|
+
`--subagents` controls subagents per worker. `--stop-after-no-new`,
|
|
570
|
+
`--max-discovery-runs`, and `--max-time-hours` stop discovery by novelty, count,
|
|
571
|
+
or duration. At the deadline, discovery stops; the scan then combines and returns
|
|
572
|
+
completed findings.
|
|
573
|
+
|
|
574
|
+
Use project-file `scan.deep` settings or legacy
|
|
575
|
+
`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
|
|
576
|
+
that `subagents` can be zero. Time accepts positive fractional hours up to 96.
|
|
577
|
+
`stopAfterConsecutiveErrors` is an SDK/project-file setting, with no CLI flag.
|
|
578
|
+
`--codex` does not configure deep-scan settings. See
|
|
579
|
+
[Deep settings and limits](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md#deep-settings-and-limits).
|
|
580
|
+
|
|
581
|
+
`bulk-scan --workers` controls concurrent repositories; `scan --workers` controls
|
|
582
|
+
workers within one Deep Scan. New recipes save all resolved deep settings so
|
|
583
|
+
resume and rerun do not depend on later changes to legacy defaults.
|
|
584
|
+
|
|
585
|
+
### Runtime configuration and worker limits
|
|
586
|
+
|
|
587
|
+
Scans use an isolated Codex configuration. The default model and effort are
|
|
588
|
+
`gpt-5.6-sol` and `xhigh`. Multi-agent v2 allows nine concurrent threads: the
|
|
589
|
+
parent and up to eight delegated workers. That limit is separate from Deep Scan
|
|
590
|
+
and bulk worker counts.
|
|
591
|
+
|
|
592
|
+
```bash
|
|
593
|
+
codex-security scan . --model gpt-6.1-sol --effort high \
|
|
594
|
+
--codex features.multi_agent_v2.max_concurrent_threads_per_session=4
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
Model IDs and `--effort` values pass through to Codex unchanged, including values
|
|
598
|
+
such as `minimal`, `none`, and `high`. Supported combinations depend on the model,
|
|
599
|
+
provider, Codex version, and credentials. Codex and provider errors are reported
|
|
600
|
+
without substituting another model or effort.
|
|
601
|
+
The flags also work with bulk/component scans, policy, validation, patching,
|
|
602
|
+
verification, owner suggestions, severity classification, and scan matching.
|
|
603
|
+
Matching and severity classification default to Codex's configured model and
|
|
604
|
+
`medium` effort. `dedupe` has separate default screening and review models;
|
|
605
|
+
the host's Codex model and effort settings override those defaults for both
|
|
606
|
+
stages.
|
|
607
|
+
|
|
608
|
+
`codex-security dedupe --scan SCAN_ID --json` prepares embeddings and deduplicates
|
|
609
|
+
directly in local SQLite. An optional `--findings-url URL` selects an existing
|
|
610
|
+
findings service instead. Local mode needs an embedding API key for missing or
|
|
611
|
+
stale vectors and a model provider for fresh reviews; it does not publish to
|
|
612
|
+
Cloud. See [deduplication](findings-service.md#deduplicate-a-scan) for scope,
|
|
613
|
+
credentials, and workflow resume behavior.
|
|
614
|
+
|
|
615
|
+
For `dedupe --scan latest`, matching across worktrees or clones requires a Git
|
|
616
|
+
executable outside all saved scan targets. If a historical target includes the
|
|
617
|
+
available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
|
|
618
|
+
explicit saved scan ID. Exact-path `latest` lookup still works without Git.
|
|
619
|
+
|
|
620
|
+
Repeat `--codex KEY=VALUE` for supported native settings. Quote strings as TOML:
|
|
621
|
+
`--codex 'model_reasoning_effort="high"'`. Repeated or conflicting keys are
|
|
622
|
+
rejected, including a `--model` or `--effort` flag plus its native equivalent.
|
|
623
|
+
Choose plugins with `--plugin-path`; native plugin and marketplace overrides are
|
|
624
|
+
rejected. New and resumed Deep Scans require the current plugin's direct engine,
|
|
625
|
+
worker provider snapshot, and isolated worker configuration capabilities. Update
|
|
626
|
+
older custom plugins or omit `--plugin-path` to use the bundled plugin. The SDK
|
|
627
|
+
no longer adapts direct `node ./mcp/server.mjs` entrypoints; use the current shell
|
|
628
|
+
or Windows MCP launcher. Saved reports remain readable.
|
|
629
|
+
Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
|
|
630
|
+
|
|
631
|
+
`validate`, `patch`, and `verify-fix` limit native overrides to `model`,
|
|
632
|
+
`model_reasoning_effort`, `model_provider`, `model_providers`, and
|
|
633
|
+
`analytics.enabled`. For a custom provider:
|
|
634
|
+
|
|
635
|
+
```bash
|
|
636
|
+
codex-security patch "Security issue" --model gateway-model \
|
|
637
|
+
--codex 'model_provider="gateway"' \
|
|
638
|
+
--codex 'model_providers.gateway.name="Gateway"' \
|
|
639
|
+
--codex 'model_providers.gateway.base_url="https://gateway.example.test/v1"' \
|
|
640
|
+
--codex 'model_providers.gateway.wire_api="responses"' \
|
|
641
|
+
--codex 'model_providers.gateway.env_key="GATEWAY_API_KEY"'
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
Set the provider's key environment variable before running. Patching and
|
|
645
|
+
verification preserve unspecified provider settings from Codex configuration.
|
|
646
|
+
With `auto` or `api-key`, the provider's `env_key` takes precedence over OpenAI
|
|
647
|
+
account authentication. Explicit `--auth chatgpt` selects stored account auth,
|
|
648
|
+
omits the provider key, and clears any configured experimental bearer token for
|
|
649
|
+
that command. Model, effort, and provider choices carry into patch-risk assessment.
|
|
650
|
+
|
|
651
|
+
Model requests include Codex Security attribution in `responses_api_metadata`:
|
|
652
|
+
`codex_security_surface` (`cli` or `sdk`), `codex_security_command`,
|
|
653
|
+
`codex_security_package_version`, and `codex_security_plugin_version` when the
|
|
654
|
+
selected plugin declares a version. These fields identify the workflow and
|
|
655
|
+
versions producing a model request; they do not record command starts,
|
|
656
|
+
completions, or failures.
|
|
657
|
+
|
|
658
|
+
Disable Codex usage analytics and built-in metrics with
|
|
659
|
+
`--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
|
|
660
|
+
patch-risk assessment, and Deep Scan discovery and reducer workers, including
|
|
661
|
+
resumed workers. Deep Scan workers also preserve the scan's request metadata.
|
|
662
|
+
Model-request attribution metadata remains attached when analytics are disabled.
|
|
663
|
+
The setting does not control configured OpenTelemetry exporters, integrations,
|
|
664
|
+
authentication, or CLI update checks. Validation uses isolated configuration;
|
|
665
|
+
patching and verification preserve ambient project trust.
|
|
666
|
+
|
|
667
|
+
For filesystem and approval behavior, see the
|
|
668
|
+
[local security model](../README.md#local-security-model).
|
|
669
|
+
|
|
670
|
+
### Environment variables
|
|
671
|
+
|
|
672
|
+
| Variable | Effect |
|
|
673
|
+
| --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
674
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
|
|
675
|
+
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
|
|
676
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
|
|
677
|
+
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
|
|
678
|
+
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
|
|
679
|
+
| `PYTHON` | Python interpreter unless an explicit option overrides it. |
|
|
680
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
|
|
681
|
+
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
|
|
682
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
|
|
683
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
|
|
684
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
|
|
685
|
+
| `GH_HOST` | GitHub Enterprise host for bulk discovery. |
|
|
686
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
|
|
687
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
|
|
688
|
+
| `CI` | Disable interactive update notices. |
|
|
689
|
+
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
690
|
+
|
|
691
|
+
Custom Codex executables need thread source attribution for `exec` and
|
|
692
|
+
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
693
|
+
command shims such as `codex.cmd` fall back to the bundled executable.
|
|
694
|
+
|
|
695
|
+
Python lookup: `--python` on commands that expose interpreter selection or SDK
|
|
696
|
+
`pythonPath`, then
|
|
697
|
+
`PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
|
|
698
|
+
works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
|
|
699
|
+
|
|
700
|
+
### Troubleshooting
|
|
701
|
+
|
|
702
|
+
Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
|
|
703
|
+
retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,
|
|
704
|
+
saved failures, receipts, and patch-risk summaries. Review it for sensitive
|
|
705
|
+
information before sharing; upstream Codex output may already be redacted.
|
|
706
|
+
|
|
707
|
+
Keep state and reports when recovering authentication or locking problems.
|
|
708
|
+
Finish older-version operations before upgrading. Never remove
|
|
709
|
+
`.codex-security-scan.sqlite3` during an operation. Stop all operations using the
|
|
710
|
+
credential home before manually removing an old `.codex-security-scan.lock`.
|
|
711
|
+
|
|
712
|
+
On Windows, an older sandboxed run can leave invalid ACLs on a credential-home
|
|
713
|
+
ancestor. Preserve that state, then select a new private `CODEX_SECURITY_STATE_DIR`
|
|
714
|
+
outside the old state and repository. Sign in again if needed; the new directory
|
|
715
|
+
has separate scan history.
|
|
716
|
+
|
|
717
|
+
### Progress and cost
|
|
718
|
+
|
|
719
|
+
Interactive scans show full-screen progress. CI, redirected output, `--headless`,
|
|
720
|
+
and `--verbose` use plain status lines. Results go to stdout; progress and
|
|
721
|
+
diagnostics go to stderr. Press `d` in the dashboard for details, then `a` for
|
|
722
|
+
all sources, `m` for the main scan, or `1`–`9` for a worker.
|
|
723
|
+
|
|
724
|
+
Token totals include input plus output; cache reads and writes are subsets of
|
|
725
|
+
input. Missing cache-write usage makes the uncached/cache-write breakdown
|
|
726
|
+
unavailable. The CLI cannot recover missing information already recorded as zero
|
|
727
|
+
by the runtime.
|
|
728
|
+
|
|
729
|
+
Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
|
|
730
|
+
and show a short/long-context range. They estimate model usage, excluding other
|
|
731
|
+
tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
|
|
732
|
+
subscription allowance. Models without known prices have no estimate.
|
|
733
|
+
|
|
734
|
+
JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
|
|
735
|
+
and `context: "unknown"`). A null maximum means no upper estimate is available.
|
|
736
|
+
`cost.pricing` records source, verification date, tier, and rates. Older results
|
|
737
|
+
keep their legacy estimates. `cost.estimatedUsd` is the short-context baseline
|
|
738
|
+
used for spending limits; use the range for reporting. Missing cache-write usage
|
|
739
|
+
is recorded by `cacheWriteInputTokensReported: false`.
|
|
740
|
+
|
|
741
|
+
`--max-cost USD` stops the scan and workers after estimated cost exceeds the
|
|
742
|
+
limit; in-flight requests can finish above it. Bulk limits apply per repository
|
|
743
|
+
attempt. Post-scan prompts run after cost tracking and are outside this limit.
|
|
744
|
+
Automatic history matching gets at most one extra call with a limit; if more
|
|
745
|
+
work is needed, the scan is preserved and you can run `scans match --all`.
|
|
746
|
+
|
|
747
|
+
When Deep discovery has finished at a cost stop, the scan returns a sealed
|
|
748
|
+
report and lists unvalidated candidates as follow-up work. Reaching a configured
|
|
749
|
+
limit with a valid finalized report returns `0` by default, or `1` if findings
|
|
750
|
+
meet a configured failure threshold.
|
|
751
|
+
|
|
752
|
+
When Codex reports an exhausted usage limit, Deep Scan cancels active workers
|
|
753
|
+
and stops retrying or launching replacements. Completed worker artifacts are retained.
|
|
754
|
+
|
|
755
|
+
At 80% of a single interactive scan's limit, the dashboard offers a higher total
|
|
756
|
+
budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
|
|
757
|
+
Work continues while you decide; the old limit remains active until saved.
|
|
758
|
+
CI, JSON/JSONL, headless, and verbose scans do not offer increases.
|
|
759
|
+
|
|
760
|
+
SDK callers can use `onBudgetApproaching({ maxCostUsd, cost, signal })`, returning
|
|
761
|
+
a larger total or `undefined`. It runs once per limit without blocking the scan.
|
|
762
|
+
Late responses after cancellation/completion are ignored; invalid increases or
|
|
763
|
+
save failures keep the existing limit. `onCost(cost, maxCostUsd)` reports changes.
|
|
764
|
+
|
|
765
|
+
## Review one system across repositories
|
|
766
|
+
|
|
767
|
+
Use a single directory/path scan when an application spans repositories and you
|
|
768
|
+
want Codex to follow relationships between their source files. Put the checkouts
|
|
769
|
+
under one parent directory; that parent does not need to be a Git repository.
|
|
770
|
+
Select the relevant paths beneath it and supply the shared architecture and
|
|
771
|
+
reporting instructions explicitly:
|
|
772
|
+
|
|
773
|
+
```text
|
|
774
|
+
workspace/
|
|
775
|
+
├── application/
|
|
776
|
+
│ ├── api/ # Git checkout
|
|
777
|
+
│ ├── web/ # Git checkout
|
|
778
|
+
│ └── shared/ # Git checkout
|
|
779
|
+
├── context/
|
|
780
|
+
│ ├── architecture.md
|
|
781
|
+
│ └── scan-instructions.md
|
|
782
|
+
└── results/
|
|
783
|
+
```
|
|
784
|
+
|
|
785
|
+
From `workspace/`, run:
|
|
786
|
+
|
|
787
|
+
```bash
|
|
788
|
+
codex-security scan ./application \
|
|
789
|
+
--mode deep \
|
|
790
|
+
--path api/src --path web/src --path shared/src \
|
|
791
|
+
--knowledge-base ./context/architecture.md \
|
|
792
|
+
--scan-prompt-file ./context/scan-instructions.md \
|
|
793
|
+
--output-dir ./results/system-review
|
|
794
|
+
```
|
|
795
|
+
|
|
796
|
+
Scope paths are relative to `application/`. Context and output paths in this
|
|
797
|
+
example are relative to the working directory. Keep results outside the scanned
|
|
798
|
+
directory and any enclosing Git worktree. You do not need to add `AGENTS.md` or
|
|
799
|
+
`SECURITY.md` to each checkout to pass these documents.
|
|
800
|
+
|
|
801
|
+
Include both sides of a boundary you want reviewed, such as an API caller and
|
|
802
|
+
its authorization implementation. Architecture documents can explain deployment
|
|
803
|
+
facts and trust boundaries, but cannot replace missing source evidence. Identify
|
|
804
|
+
excluded or unavailable services in the context so their dependencies remain
|
|
805
|
+
explicit coverage limitations. Distinguish source that supports an investigation
|
|
806
|
+
from locations where you want findings reported.
|
|
807
|
+
|
|
808
|
+
Record each checkout's commit and local changes before scanning, and keep the
|
|
809
|
+
checkouts unchanged while a scan or resume is active. A non-Git parent is recorded
|
|
810
|
+
as one directory snapshot, rather than one pinned revision per child repository.
|
|
811
|
+
Use the saved scan ID when inspecting results and logs:
|
|
812
|
+
|
|
813
|
+
```bash
|
|
814
|
+
codex-security scans show SCAN_ID
|
|
815
|
+
codex-security scans logs SCAN_ID
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
See [scan history and reruns](#scan-history-and-reruns) for the distinction between
|
|
819
|
+
continuing an interrupted scan and starting a new run. Neither approach proves
|
|
820
|
+
that every possible cross-service path was reviewed; inspect the reported
|
|
821
|
+
coverage and unresolved questions alongside findings.
|
|
822
|
+
|
|
823
|
+
## Bulk scans
|
|
824
|
+
|
|
825
|
+
Bulk scans run independent repository reviews in one resumable campaign. Shared
|
|
826
|
+
knowledge-base documents give each review application context; they do not make
|
|
827
|
+
the campaign a joint source review across repositories. For that workflow, use
|
|
828
|
+
[one system scan](#review-one-system-across-repositories).
|
|
829
|
+
|
|
830
|
+
Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
|
|
831
|
+
selection. It lists repositories pushed in the last 90 days, excluding forks
|
|
832
|
+
and archives, asks for output, and saves the selection as `repositories.csv`.
|
|
833
|
+
Private checkouts use your GitHub CLI login.
|
|
834
|
+
|
|
835
|
+
For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
|
|
836
|
+
Optional `scope`, `mode`, and `prompt` customize each row:
|
|
837
|
+
|
|
838
|
+
```csv
|
|
839
|
+
id,repository,revision,scope,mode,prompt
|
|
840
|
+
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authentication and authorization.
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
```bash
|
|
844
|
+
codex-security bulk-scan repositories.csv \
|
|
845
|
+
--output-dir /path/outside/repositories/results --workers 4
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
Bulk scans use clean shallow checkouts and support repository/path scopes.
|
|
849
|
+
Configured diff or working-tree scopes are rejected unless every affected row
|
|
850
|
+
overrides them with a path scope. `--output-dir` requires CSV input.
|
|
851
|
+
|
|
852
|
+
Use `-c FILE` for shared settings; CSV mode/scope override file values.
|
|
853
|
+
`--scan-prompt-file` adds shared instructions before each row's prompt.
|
|
854
|
+
`--post-scan-prompt-file` runs a follow-up even after failure, but not after
|
|
855
|
+
cancellation or a cost stop.
|
|
856
|
+
|
|
857
|
+
Concurrency defaults to four repositories. `--max-attempts` defaults to one
|
|
858
|
+
attempt per pending repository per invocation. Repeating the command continues
|
|
859
|
+
the campaign, skips completed results, and starts pending attempts. Occupied
|
|
860
|
+
attempt directories stop that repository and suggest `--recover`.
|
|
861
|
+
Changes to project configuration, extracted knowledge-base text, staged document
|
|
862
|
+
filenames, direct Codex overrides, or explicit `--plugin-path`/`--python` selections
|
|
863
|
+
require a new output directory. Version 1 manifests also require a new directory
|
|
864
|
+
because their original knowledge inputs and direct overrides cannot be verified.
|
|
865
|
+
Worker and retry counts can change when resuming.
|
|
866
|
+
|
|
867
|
+
### Recovering failed or interrupted bulk scans
|
|
868
|
+
|
|
869
|
+
Use the original CSV, output directory, and options:
|
|
870
|
+
|
|
871
|
+
```bash
|
|
872
|
+
codex-security bulk-scan repositories.csv \
|
|
873
|
+
--output-dir /path/outside/repositories/results --recover
|
|
874
|
+
```
|
|
875
|
+
|
|
876
|
+
Recovery requires a matching campaign manifest. It skips completed results
|
|
877
|
+
(including saved results with legacy coverage notes) and repositories never started. For each latest
|
|
878
|
+
failed or interrupted attempt:
|
|
879
|
+
|
|
880
|
+
- A sealed scan is recorded in `results.jsonl` without scanning again.
|
|
881
|
+
- An eligible running Deep Scan resumes its original session, keeping its ID,
|
|
882
|
+
workers, artifacts, settings, and accumulated cost.
|
|
883
|
+
- An unavailable, failed, or canceled scan starts a new attempt at the pinned
|
|
884
|
+
revision, preserving old artifacts and checkouts.
|
|
885
|
+
|
|
886
|
+
New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
|
|
887
|
+
workers and one recovery/new attempt per repository. A resume connection failure
|
|
888
|
+
stops only that repository for this invocation. Failed recovery checkouts remain;
|
|
889
|
+
fresh completed checkouts are removed after recording their result.
|
|
890
|
+
|
|
891
|
+
Same-scan resume needs the original checkout, session logs, and state directory.
|
|
892
|
+
Recovery cannot reconstruct deleted checkpoints or fix execution failures.
|
|
893
|
+
New attempts incur new costs. Remaining execution failures return `2`;
|
|
894
|
+
completed severity-policy violations return `1` without retrying the scan.
|
|
895
|
+
|
|
896
|
+
## Custom validation
|
|
897
|
+
|
|
898
|
+
Replace the final validation step of a Standard or diff scan with a prompt:
|
|
899
|
+
|
|
900
|
+
```bash
|
|
901
|
+
codex-security scan . --validation-prompt-file validation.md
|
|
902
|
+
```
|
|
903
|
+
|
|
904
|
+
```ts
|
|
905
|
+
const result = await security.run(repository, {
|
|
906
|
+
validationPrompt:
|
|
907
|
+
"Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",
|
|
908
|
+
});
|
|
909
|
+
```
|
|
910
|
+
|
|
911
|
+
Source review still runs; discovery workers do not receive this prompt. Include
|
|
912
|
+
setup, authorized targets, required evidence, and cleanup. Use environment
|
|
913
|
+
variables for credentials. Deep scans reject custom validation; scans with no
|
|
914
|
+
candidates skip it. The SDK also accepts `validationPromptFile`.
|
|
915
|
+
|
|
916
|
+
The model must return a `CustomValidationResult` with one entry per candidate:
|
|
917
|
+
|
|
918
|
+
```json
|
|
919
|
+
{
|
|
920
|
+
"status": "complete",
|
|
921
|
+
"reason": null,
|
|
922
|
+
"validations": [
|
|
923
|
+
{
|
|
924
|
+
"candidateId": "candidate-1",
|
|
925
|
+
"validation": {
|
|
926
|
+
"disposition": "reportable",
|
|
927
|
+
"method": "integration test",
|
|
928
|
+
"confidence": "high",
|
|
929
|
+
"confidence_rationale": "The test reproduced the reported behavior.",
|
|
930
|
+
"rubric": "Check the protected operation.",
|
|
931
|
+
"evidence": ["The unauthorized request succeeded."],
|
|
932
|
+
"counterevidence_or_proof_gap": "",
|
|
933
|
+
"remaining_uncertainty": "",
|
|
934
|
+
"artifact_paths": []
|
|
935
|
+
},
|
|
936
|
+
"severity": null,
|
|
937
|
+
"impact": null
|
|
938
|
+
}
|
|
939
|
+
]
|
|
940
|
+
}
|
|
941
|
+
```
|
|
942
|
+
|
|
943
|
+
Dispositions are `reportable`, `suppressed`, `not_applicable`, or `deferred`.
|
|
944
|
+
Set severity/impact to `{ "level": "medium", "rationale": "..." }` to revise
|
|
945
|
+
them, or null to retain them. Identity and source locations stay unchanged.
|
|
946
|
+
|
|
947
|
+
Candidates and results remain under `artifacts/custom-validation/`. Setup
|
|
948
|
+
failure or incomplete/invalid output fails the scan. Deferred candidates remain
|
|
949
|
+
follow-up notes and do not fail the scan. An incompatible plugin stops the scan.
|
|
950
|
+
Supply the validation prompt again when rerunning.
|
|
951
|
+
|
|
952
|
+
## Publish findings to Cloud
|
|
953
|
+
|
|
954
|
+
Preview selected completed scans before uploading:
|
|
955
|
+
|
|
956
|
+
```bash
|
|
957
|
+
codex-security publish scan --to cloud --dry-run --json
|
|
958
|
+
codex-security publish scan --scan SCAN_ID_A --scan SCAN_ID_B \
|
|
959
|
+
--to cloud --dry-run --json
|
|
960
|
+
```
|
|
961
|
+
|
|
962
|
+
The interactive picker starts with nothing selected; press Space to select and
|
|
963
|
+
Enter to submit. Find IDs with `scans list --json`. Select by full ID, unique
|
|
964
|
+
prefix of at least eight characters, or `latest` for the current repository.
|
|
965
|
+
Local sealed artifacts are required. Dry runs need no login or network access.
|
|
966
|
+
|
|
967
|
+
Uploads require ChatGPT credentials saved to a file. Set
|
|
968
|
+
`cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in again.
|
|
969
|
+
Cloud publication rejects automatic/keyring storage even when `auth.json` exists,
|
|
970
|
+
because that file may be stale or belong to another account.
|
|
971
|
+
|
|
972
|
+
Use a positional scan directory or repeated `--scan-dir PATH` for artifacts
|
|
973
|
+
outside history. Each must contain one completed sealed scan, not a bulk-run
|
|
974
|
+
directory or `results.jsonl`. Do not mix directories with `--scan`.
|
|
975
|
+
Cloud also accepts exported CSV:
|
|
976
|
+
|
|
977
|
+
```bash
|
|
978
|
+
codex-security publish scan --to cloud --csv /path/outside/repository/findings.csv
|
|
979
|
+
```
|
|
980
|
+
|
|
981
|
+
CSV cannot combine with scan selectors. Use the
|
|
982
|
+
[CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)
|
|
983
|
+
or `export --export-format csv` output.
|
|
984
|
+
|
|
985
|
+
One scan returns a receipt directly. Multiple scans return `results`, `failed`,
|
|
986
|
+
and `notAttempted` arrays. Uploads run sequentially and continue after individual
|
|
987
|
+
failures, returning `2` if any fail. Cancellation returns results so far with
|
|
988
|
+
`130` (Ctrl-C) or `143` (SIGTERM), unless every upload was already confirmed.
|
|
989
|
+
|
|
990
|
+
Save receipts: Cloud does not store them in local history. IDs are Cloud finding
|
|
991
|
+
IDs in request order. Uploads are not retried automatically. A missing receipt
|
|
992
|
+
can still mean the upload succeeded; check Cloud before retrying and do not
|
|
993
|
+
resend a confirmed upload.
|
|
994
|
+
|
|
995
|
+
## Publish completed scans to Linear
|
|
996
|
+
|
|
997
|
+
```bash
|
|
998
|
+
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID
|
|
999
|
+
```
|
|
1000
|
+
|
|
1001
|
+
Select one completed scan by ID, prefix, `latest`, or directory; omit the selector
|
|
1002
|
+
for the picker. Live publication and `--skip-existing` require local history.
|
|
1003
|
+
A directory-only dry run does not.
|
|
1004
|
+
|
|
1005
|
+
`--linear-project PROJECT_ID` (`--project`) selects a project. Flags override
|
|
1006
|
+
`CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
|
|
1007
|
+
previews titles offline; `--json` returns structured output.
|
|
1008
|
+
|
|
1009
|
+
Sign in to Codex and connect Linear, or set `CODEX_SECURITY_LINEAR_API_KEY` to
|
|
1010
|
+
use its API directly. Direct API publication leaves issues unassigned unless
|
|
1011
|
+
`--linear-assignee` gives a user ID or email. Prefer the environment variable
|
|
1012
|
+
over `--linear-api-key`, which exposes the key in shell history/process listings.
|
|
1013
|
+
Keys are omitted from saved results; diagnostic messages remain unchanged.
|
|
1014
|
+
|
|
1015
|
+
```bash
|
|
1016
|
+
codex-security publish check /path/to/completed-scan \
|
|
1017
|
+
--to linear --linear-team TEAM_ID --json
|
|
1018
|
+
```
|
|
1019
|
+
|
|
1020
|
+
`publish check` verifies artifacts and recorded publications. With an API key,
|
|
1021
|
+
it also checks authentication and destination access. It does not test issue
|
|
1022
|
+
creation; connected-app access is reported as `not-checked`.
|
|
1023
|
+
|
|
1024
|
+
Each finding becomes an issue with severity, source, evidence, and remediation.
|
|
1025
|
+
Choose a destination authorized to receive that content. Local history records
|
|
1026
|
+
successful issue IDs separately from sealed artifacts.
|
|
1027
|
+
|
|
1028
|
+
Republishing creates duplicates unless `--skip-existing` finds a recorded success
|
|
1029
|
+
for that occurrence, team, and project. It does not check remote issues or cover
|
|
1030
|
+
unrecorded/concurrent publication. After interruption, inspect the handoff,
|
|
1031
|
+
evidence, and destination before retrying.
|
|
1032
|
+
|
|
1033
|
+
```ts
|
|
1034
|
+
import { publishScan } from "@openai/codex-security";
|
|
1035
|
+
|
|
1036
|
+
const publication = await publishScan("/path/to/completed-scan", {
|
|
1037
|
+
destination: "linear",
|
|
1038
|
+
teamId: "TEAM_ID",
|
|
1039
|
+
skipExisting: true,
|
|
1040
|
+
});
|
|
1041
|
+
console.log(publication.scanId, publication.created.length);
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
Options also include `projectId`, `linearApiKey`, and `assigneeId` (ID or email).
|
|
1045
|
+
`checkScanPublication()` takes the same destination options for a read-only check.
|
|
1046
|
+
|
|
1047
|
+
## Classify finding severity
|
|
1048
|
+
|
|
1049
|
+
Apply a rubric to completed findings without repeating discovery:
|
|
1050
|
+
|
|
1051
|
+
```bash
|
|
1052
|
+
codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
|
|
1053
|
+
codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
1054
|
+
```
|
|
1055
|
+
|
|
1056
|
+
Use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
|
|
1057
|
+
Omitting `--rubric` inherits original severity without model calls. Rubrics and
|
|
1058
|
+
repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
|
|
1059
|
+
Each finding is classified in a separate read-only turn using its report and
|
|
1060
|
+
supplied context, without tools or source inspection. `--model` and `--effort`
|
|
1061
|
+
override Codex's configured model and the default medium effort.
|
|
1062
|
+
|
|
1063
|
+
Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,
|
|
1064
|
+
the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
|
|
1065
|
+
missing facts that could change the result. Exclusions have a null level.
|
|
1066
|
+
Finding/occurrence IDs and input hashes bind each assessment to its evidence.
|
|
1067
|
+
|
|
1068
|
+
Successful assessments checkpoint immediately in local SQLite. Retries reuse
|
|
1069
|
+
matching evidence, rubric, and context hashes; failed/canceled runs keep completed
|
|
1070
|
+
work. Use `--reprocess` to replace assessments, including when changing only model
|
|
1071
|
+
or effort. A successful run also writes `severity-classification.json`, but
|
|
1072
|
+
publication reads the database. Original findings and sealed artifacts remain
|
|
1073
|
+
unchanged.
|
|
1074
|
+
|
|
1075
|
+
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
|
|
1076
|
+
`uniqueFindingIds` can represent findings from another scan; replace an outside-scan
|
|
1077
|
+
representative with a member of its `duplicateGroups` entry from this scan.
|
|
1078
|
+
Linear publication defaults to saved classification selection, omits exclusions,
|
|
1079
|
+
and uses assessed severity for title and priority. Descriptions retain original
|
|
1080
|
+
severity and add the classification rationale. Publication rejects incomplete or
|
|
1081
|
+
stale assessments. It never reclassifies or rereads the rubric at publication time.
|
|
1082
|
+
|
|
1083
|
+
```bash
|
|
1084
|
+
codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
|
|
1085
|
+
--finding-id FINDING_ID
|
|
1086
|
+
codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
|
|
1087
|
+
```
|
|
1088
|
+
|
|
1089
|
+
Linear publication also accepts `--finding-id`. If a classification exists, every
|
|
1090
|
+
selected finding needs an assessment. Existing tickets are not changed;
|
|
1091
|
+
`--skip-existing` preserves recorded tickets and human priority edits.
|
|
1092
|
+
|
|
1093
|
+
```ts
|
|
1094
|
+
import {
|
|
1095
|
+
classifySeverity,
|
|
1096
|
+
classifyScanSeverity,
|
|
1097
|
+
classifyScanDirectorySeverity,
|
|
1098
|
+
publishScan,
|
|
1099
|
+
type FindingsDocument,
|
|
1100
|
+
} from "@openai/codex-security";
|
|
1101
|
+
import { readFile } from "node:fs/promises";
|
|
1102
|
+
import { join } from "node:path";
|
|
1103
|
+
|
|
1104
|
+
// Assess supplied reports in memory.
|
|
1105
|
+
const classification = await classifySeverity(findings, {
|
|
1106
|
+
rubricPath: "/path/to/policy.md",
|
|
1107
|
+
knowledgeBasePaths: ["/path/to/context.md"],
|
|
1108
|
+
});
|
|
1109
|
+
|
|
1110
|
+
// Save assessments for a scan ID or sealed directory.
|
|
1111
|
+
await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
|
|
1112
|
+
const scanFindings = (
|
|
1113
|
+
JSON.parse(
|
|
1114
|
+
await readFile(join(scanDirectory, "findings.json"), "utf8"),
|
|
1115
|
+
) as FindingsDocument
|
|
1116
|
+
).findings;
|
|
1117
|
+
const scanFindingIds = new Set(
|
|
1118
|
+
scanFindings.map((finding) => finding.findingId),
|
|
1119
|
+
);
|
|
1120
|
+
// dedupeResult was produced by deduplicating this same scan.
|
|
1121
|
+
const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
|
|
1122
|
+
if (scanFindingIds.has(representative)) return representative;
|
|
1123
|
+
return dedupeResult.duplicateGroups
|
|
1124
|
+
.find((group) => group.includes(representative))!
|
|
1125
|
+
.find((member) => scanFindingIds.has(member))!;
|
|
1126
|
+
});
|
|
1127
|
+
await classifyScanDirectorySeverity(scanDirectory, {
|
|
1128
|
+
rubricPath: "/path/to/policy.md",
|
|
1129
|
+
findingIds: selectedIds,
|
|
1130
|
+
});
|
|
1131
|
+
|
|
1132
|
+
// Or supply an in-memory assessment directly to publication.
|
|
1133
|
+
await publishScan(scanDirectory, {
|
|
1134
|
+
destination: "linear",
|
|
1135
|
+
teamId: "TEAM_ID",
|
|
1136
|
+
classification,
|
|
1137
|
+
findingIds: classification.assessments.map(({ findingId }) => findingId),
|
|
1138
|
+
dryRun: true,
|
|
1139
|
+
});
|
|
1140
|
+
```
|
|
1141
|
+
|
|
1142
|
+
`classifySeverity()` accepts `findingId`, `title`, `summary`, and available
|
|
1143
|
+
evidence/metadata. Imported reports may lack severity or occurrence IDs; missing
|
|
1144
|
+
severity requires a rubric. Scan wrappers persist checkpoints (including for
|
|
1145
|
+
external directories), accept `reprocess: true`, and treat `findingIds: []` as an
|
|
1146
|
+
empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
|
|
1147
|
+
publication. Older JSON-only assessments need reclassification once. All
|
|
1148
|
+
classification methods accept `signal`; keep human overrides in your workflow.
|
|
1149
|
+
|
|
1150
|
+
## Suggest finding owners
|
|
1151
|
+
|
|
1152
|
+
```bash
|
|
1153
|
+
codex-security suggest-owners findings.json --source-root /path/to/repo --json > owners.json
|
|
1154
|
+
```
|
|
1155
|
+
|
|
1156
|
+
Input is a findings document or `{ "findings": [...] }`. The source root
|
|
1157
|
+
defaults to the current directory. The command reads committed `HEAD`, relevant
|
|
1158
|
+
source, CODEOWNERS, blame, and history; it does not read uncommitted source or assign tickets.
|
|
1159
|
+
Finding location paths are relative to the Git worktree root, including when
|
|
1160
|
+
`--source-root` points to a subdirectory. A location for `src/handler.ts` keeps
|
|
1161
|
+
that prefix; a location of `handler.ts` refers to the root file. Rebase imported
|
|
1162
|
+
subdirectory-relative locations to repository-relative paths before suggesting
|
|
1163
|
+
owners.
|
|
1164
|
+
|
|
1165
|
+
Linked worktrees and bound separate Git directories are supported; borrowed
|
|
1166
|
+
external object stores such as `git clone --shared` are rejected.
|
|
1167
|
+
|
|
1168
|
+
CODEOWNERS declarations take priority over Git history, following
|
|
1169
|
+
[GitHub's CODEOWNERS rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
|
|
1170
|
+
The last matching rule wins, and the command returns its first declared owner.
|
|
1171
|
+
Git history is the fallback when no declared owner applies.
|
|
1172
|
+
|
|
1173
|
+
Results preserve IDs and report `identified`, `abstained`, or `error`. Identified
|
|
1174
|
+
owners include a declared GitHub user, team, or email, or an observed Git
|
|
1175
|
+
name/email, with a reason and checked citations.
|
|
1176
|
+
Git identities do not establish current employment or tracker accounts; match
|
|
1177
|
+
accounts before assigning. Use a checkout matching the findings.
|
|
1178
|
+
|
|
1179
|
+
An owner can be a Git name/email identity, a GitHub user or team handle,
|
|
1180
|
+
an email-only identity, or `null`. Example JSON excerpt:
|
|
1181
|
+
|
|
1182
|
+
```json
|
|
1183
|
+
{
|
|
1184
|
+
"schemaVersion": 2,
|
|
1185
|
+
"results": [
|
|
1186
|
+
{
|
|
1187
|
+
"owner": {
|
|
1188
|
+
"kind": "group",
|
|
1189
|
+
"provider": "github",
|
|
1190
|
+
"handle": "example/maintainers"
|
|
1191
|
+
}
|
|
1192
|
+
}
|
|
1193
|
+
]
|
|
1194
|
+
}
|
|
1195
|
+
```
|
|
1196
|
+
|
|
1197
|
+
The command uses scan-default model/effort; override with `--model` and `--effort`.
|
|
1198
|
+
The model receives collected evidence with tools/network disabled. Exit `0`
|
|
1199
|
+
includes abstentions; `2` means invalid input or a failed recommendation, while
|
|
1200
|
+
retaining other results. Cancellation uses `130` or `143`.
|
|
1201
|
+
|
|
1202
|
+
```ts
|
|
1203
|
+
import { suggestOwners } from "@openai/codex-security";
|
|
1204
|
+
|
|
1205
|
+
const owners = await suggestOwners("/path/to/repo", result.findings.findings, {
|
|
1206
|
+
reasoningEffort: "high",
|
|
1207
|
+
});
|
|
1208
|
+
for (const { owner } of owners.results) {
|
|
1209
|
+
if (owner === null) continue;
|
|
1210
|
+
console.log("handle" in owner ? owner.handle : owner.email);
|
|
1211
|
+
}
|
|
1212
|
+
```
|
|
1213
|
+
|
|
1214
|
+
SDK inputs can include `sourceRevision`. If it differs from `HEAD`, the collector
|
|
1215
|
+
ignores stale line ranges and reports the mismatch. Reports remain separate from
|
|
1216
|
+
scan artifacts and record the analyzed revision and limitations.
|
|
1217
|
+
|
|
1218
|
+
## Feedback
|
|
1219
|
+
|
|
1220
|
+
```bash
|
|
1221
|
+
codex-security feedback --reason "The scan stopped before it finished"
|
|
1222
|
+
codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs
|
|
1223
|
+
```
|
|
1224
|
+
|
|
1225
|
+
Share the returned ID with support. Without a selector, `feedback` uses the most
|
|
1226
|
+
recently started scan in the current repository, including failed/active scans,
|
|
1227
|
+
or sends a general report if none exist. Reports include your description,
|
|
1228
|
+
versions, and selected scan/session IDs. `--json` returns structured output.
|
|
1229
|
+
|
|
1230
|
+
Logs are off by default. `--include-logs` sends Codex diagnostics and saved scan/
|
|
1231
|
+
worker activity, potentially including source, prompts, findings, and tool output.
|
|
1232
|
+
Include only logs you can share with OpenAI. `feedback.enabled = false` disables
|
|
1233
|
+
the service.
|
|
1234
|
+
|
|
1235
|
+
For Desktop-plugin scans, run on the machine where the scan ran with the same
|
|
1236
|
+
Codex home and state directory. The command searches active/archived sessions and
|
|
1237
|
+
recorded worker descendants. Standard scans in an existing Codex conversation
|
|
1238
|
+
attach only their owner's session. Unrecorded earlier retry sessions may be absent.
|
|
1239
|
+
|
|
1240
|
+
## Scan history and reruns
|
|
1241
|
+
|
|
1242
|
+
Commands default to the current repository. IDs accept unique prefixes of at
|
|
1243
|
+
least eight characters.
|
|
1244
|
+
|
|
1245
|
+
| Command | Purpose |
|
|
1246
|
+
| ----------------------------------------------------- | ---------------------------------------------------------- |
|
|
1247
|
+
| `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
|
|
1248
|
+
| `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
|
|
1249
|
+
| `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
|
|
1250
|
+
| `scans resume SCAN_ID` | Continue an interrupted Deep Scan. |
|
|
1251
|
+
| `scans rerun [SCAN_ID]` | Repeat on the current checkout. |
|
|
1252
|
+
| `scans match BEFORE AFTER` | Link findings with the same root cause. |
|
|
1253
|
+
| `scans match --all` | Match completed scans across worktrees/clones. |
|
|
1254
|
+
| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
|
|
1255
|
+
| `findings list [REPOSITORY]` | List open findings. |
|
|
1256
|
+
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
|
|
1257
|
+
|
|
1258
|
+
Without an ID, `scans show` selects the latest completed scan, while `scans logs`
|
|
1259
|
+
selects the latest scan of any status. After a successful scan followed by a
|
|
1260
|
+
failed or active scan, these defaults refer to different runs. Human output
|
|
1261
|
+
identifies the selected run, labels its saved update time, and gives matching
|
|
1262
|
+
commands with its full scan ID:
|
|
1263
|
+
|
|
1264
|
+
```bash
|
|
1265
|
+
codex-security scans show SCAN_ID
|
|
1266
|
+
codex-security scans logs SCAN_ID
|
|
1267
|
+
```
|
|
1268
|
+
|
|
1269
|
+
Completion summaries include that ID and the saved results directory. Failure
|
|
1270
|
+
summaries include the same navigation when the current run was registered, plus
|
|
1271
|
+
the last observed phase when available. A failure before registration has no
|
|
1272
|
+
scan ID. The handoff uses that run's registration receipt without querying scan
|
|
1273
|
+
history. Inspect its saved status before choosing resume or rerun, and supply
|
|
1274
|
+
the original custom prompt files for reruns. Structured history and log output
|
|
1275
|
+
and command selection defaults are unchanged.
|
|
1276
|
+
|
|
1277
|
+
Recipes save settings and authentication choice, not credentials. Reruns use the
|
|
1278
|
+
current checkout/context files and do not reload project files. Supply replacement
|
|
1279
|
+
scan and custom-validation prompts when the original used them:
|
|
1280
|
+
|
|
1281
|
+
```bash
|
|
1282
|
+
codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
|
|
1283
|
+
```
|
|
1284
|
+
|
|
1285
|
+
A rerun creates a new scan. When the original has saved input identities, the
|
|
1286
|
+
rerun reports changes to the scan instructions or knowledge base. `scans show`
|
|
1287
|
+
includes the saved scope, runtime and Deep Scan settings, instruction digest,
|
|
1288
|
+
and knowledge snapshot/document digests. JSON includes these identities under
|
|
1289
|
+
`recipe.scanInputs`. The instruction digest covers the exact UTF-8 prompt text;
|
|
1290
|
+
document digests cover the extracted text workers receive. These identities
|
|
1291
|
+
describe supplied inputs, not proof that a model read or followed every passage.
|
|
1292
|
+
|
|
1293
|
+
History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
|
|
1294
|
+
`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Keep it private,
|
|
1295
|
+
writable, and outside the target repository. Session logs may contain sensitive
|
|
1296
|
+
data even though scan recipes do not store credentials.
|
|
1297
|
+
|
|
1298
|
+
Codex may compress saved session logs to `.jsonl.zst`. Reading those logs requires
|
|
1299
|
+
Node.js 22.15.0+ within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14,
|
|
1300
|
+
compressed sessions are unavailable to `scans logs`, feedback attachments, and
|
|
1301
|
+
`scans resume`. Upgrade Node.js to read or resume these sessions. Plain `.jsonl`
|
|
1302
|
+
logs work on all supported runtimes.
|
|
1303
|
+
|
|
1304
|
+
### Resuming an interrupted Deep Scan
|
|
1305
|
+
|
|
1306
|
+
```bash
|
|
1307
|
+
codex-security scans list --scan-root /path/to/security-scans
|
|
1308
|
+
codex-security scans resume SCAN_ID
|
|
1309
|
+
```
|
|
1310
|
+
|
|
1311
|
+
The scan must still be `running`, with its original checkout, output directory,
|
|
1312
|
+
and Codex session in the same state directory. Checkout identity, revision, and
|
|
1313
|
+
contents must match. Completed, failed, and canceled scans need a rerun instead.
|
|
1314
|
+
|
|
1315
|
+
Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved
|
|
1316
|
+
settings/instructions. Knowledge-bearing scans save their extracted documents in
|
|
1317
|
+
the private `.scan-knowledge.json` continuation file beside the scan artifacts.
|
|
1318
|
+
Resume verifies and uses that snapshot even if the original files changed or were
|
|
1319
|
+
deleted. Preserve it with the scan directory; canonical reports do not embed its
|
|
1320
|
+
document text. Old individual scans without a saved knowledge snapshot require a
|
|
1321
|
+
new scan when they used a knowledge base. Old scans without a knowledge base and
|
|
1322
|
+
bulk campaigns with an already-bound snapshot retain their existing resume path.
|
|
1323
|
+
New records save the authentication mode, explicit safety
|
|
1324
|
+
identifier, and post-scan prompt; older records cannot reconstruct missing values.
|
|
1325
|
+
A failed connection leaves the scan available for another resume attempt.
|
|
1326
|
+
Compatible scans can resume after plugin updates; sealed results keep their
|
|
1327
|
+
original producer version. Unsupported artifacts are rejected without rewriting them.
|
|
1328
|
+
|
|
1329
|
+
For bulk scans, use [bulk recovery](#recovering-failed-or-interrupted-bulk-scans)
|
|
1330
|
+
to update campaign receipts. Individual resume does not update `results.jsonl`.
|
|
1331
|
+
|
|
1332
|
+
### Matching saved scans
|
|
1333
|
+
|
|
1334
|
+
Matching uses sealed artifacts and cached decisions unless `--force` is supplied.
|
|
1335
|
+
Comparisons classify findings as new, persisting, reopened, not observed, resolved,
|
|
1336
|
+
or unknown. An absent finding in the later scope is not observed; absence alone
|
|
1337
|
+
does not verify remediation. A finding is resolved only after it was explicitly
|
|
1338
|
+
closed as already fixed. Excluded paths and uncertain matches remain unknown.
|
|
1339
|
+
One comparison ID is compared with the latest completed scan.
|
|
1340
|
+
|
|
1341
|
+
```bash
|
|
1342
|
+
codex-security scans match --all --force --model gpt-6.1-sol --effort high
|
|
1343
|
+
```
|
|
1344
|
+
|
|
1345
|
+
Only high-confidence root-cause matches are grouped. Uncertain and related
|
|
1346
|
+
findings remain separate. Rebuilding retains stable identities, triage, and
|
|
1347
|
+
sealed artifacts; interruption preserves completed comparisons. Model/effort
|
|
1348
|
+
changes alone do not invalidate cached decisions.
|
|
1349
|
+
|
|
1350
|
+
```ts
|
|
1351
|
+
import { readFile } from "node:fs/promises";
|
|
1352
|
+
import {
|
|
1353
|
+
matchScanFindings,
|
|
1354
|
+
type FindingsDocument,
|
|
1355
|
+
} from "@openai/codex-security";
|
|
1356
|
+
|
|
1357
|
+
const before = JSON.parse(
|
|
1358
|
+
await readFile("/path/to/earlier-scan/findings.json", "utf8"),
|
|
1359
|
+
) as FindingsDocument;
|
|
1360
|
+
const after = JSON.parse(
|
|
1361
|
+
await readFile("/path/to/later-scan/findings.json", "utf8"),
|
|
1362
|
+
) as FindingsDocument;
|
|
1363
|
+
|
|
1364
|
+
const comparison = await matchScanFindings(
|
|
1365
|
+
{ before: before.findings, after: after.findings },
|
|
1366
|
+
{ workingDirectory: "/path/to/repository" },
|
|
1367
|
+
);
|
|
1368
|
+
console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
|
|
1369
|
+
```
|
|
1370
|
+
|
|
1371
|
+
This SDK method does not save a workbench comparison. `knownFindingGroups` can
|
|
1372
|
+
reuse confirmed stable `findingId` groups; results identify original occurrence
|
|
1373
|
+
IDs. Options include model, reasoning effort, `signal`, and `onProgress`.
|
|
1374
|
+
Progress callback failures do not stop matching.
|
|
1375
|
+
|
|
1376
|
+
## Exports and CI
|
|
1377
|
+
|
|
1378
|
+
`export` reads saved results without Codex or credentials. It defaults to the
|
|
1379
|
+
current repository's latest completed scan. Choose either a positional result
|
|
1380
|
+
directory or `--scan ID`. Findings require sealed results and support
|
|
1381
|
+
`--export-format csv|json|sarif` (default SARIF). `--source-root PATH` adds SARIF
|
|
1382
|
+
source-line fingerprints.
|
|
1383
|
+
|
|
1384
|
+
```bash
|
|
1385
|
+
codex-security export --scan SCAN_ID --export-format json --output findings.json
|
|
1386
|
+
codex-security export --artifact threat-model --output docs/threatmodel.md
|
|
1387
|
+
codex-security export /path/to/policy-results --artifact threat-model --output -
|
|
1388
|
+
```
|
|
1389
|
+
|
|
1390
|
+
Threat-model exports use Markdown and default to `./threatmodel.md`. Standard,
|
|
1391
|
+
Deep, Diff, and policy workflows retain models when available; component/bulk
|
|
1392
|
+
runs save one per child. Explicit results may expose a model before completion
|
|
1393
|
+
or after later failure. Missing models return an error rather than generating
|
|
1394
|
+
or substituting one. Historical models in sealed scans need a matching manifest
|
|
1395
|
+
digest.
|
|
1396
|
+
|
|
1397
|
+
`--output -` emits only artifact content, with diagnostics on stderr. Markdown
|
|
1398
|
+
and CSV stdout cannot combine with JSON command output. Exporting into a checkout
|
|
1399
|
+
does not make the model scan input; pass it with `--knowledge-base`.
|
|
1400
|
+
|
|
1401
|
+
`ScanResult.threatModel` and `threatModelPath` expose the retained model and
|
|
1402
|
+
document, or null. Export still works if the document could not be written.
|
|
1403
|
+
|
|
1404
|
+
```ts
|
|
1405
|
+
import { exportArtifact } from "@openai/codex-security";
|
|
1406
|
+
|
|
1407
|
+
const exported = await exportArtifact({
|
|
1408
|
+
source: { directory: "/path/to/scan-results" }, // Or { scanId: "SCAN_ID" }.
|
|
1409
|
+
artifact: "threat-model",
|
|
1410
|
+
output: "/path/to/threatmodel.md",
|
|
1411
|
+
});
|
|
1412
|
+
console.log(exported.path, exported.provenance);
|
|
1413
|
+
```
|
|
1414
|
+
|
|
1415
|
+
Use `artifact: "findings"` with `format: "csv" | "json" | "sarif"` for findings.
|
|
1416
|
+
`output: "-"` streams stdout and returns null path/provenance. `pythonPath`
|
|
1417
|
+
selects an interpreter; `signal` cancels.
|
|
1418
|
+
|
|
1419
|
+
JSON preserves sealed findings. CSV marks them open, omits local triage state,
|
|
1420
|
+
and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
|
|
1421
|
+
leading apostrophes; import removes the escape. Use JSON to recover ambiguous
|
|
1422
|
+
apostrophes from older CSV exports.
|
|
1423
|
+
|
|
1424
|
+
For CI, place output outside the checkout and set a severity threshold:
|
|
1425
|
+
|
|
1426
|
+
```bash
|
|
1427
|
+
SCAN_ROOT="$(mktemp -d)"
|
|
1428
|
+
codex-security scan . --diff origin/main \
|
|
1429
|
+
--output-dir "$SCAN_ROOT/results" --json --fail-on-severity high \
|
|
1430
|
+
> "$SCAN_ROOT/findings.json"
|
|
1431
|
+
```
|
|
1432
|
+
|
|
1433
|
+
| Exit code | Meaning |
|
|
1434
|
+
| ------------- | ------------------------------------------------------------------------ |
|
|
1435
|
+
| `0` | Complete report-only scan or passing severity policy. |
|
|
1436
|
+
| `1` | Severity policy violation. |
|
|
1437
|
+
| `2` | Invalid input, runtime error, target change, or required-output failure. |
|
|
1438
|
+
| `130` / `143` | Interrupt / termination. |
|
|
1439
|
+
|
|
1440
|
+
JSON scans have no interactive controls. `validate`, `login`, and `logout` reject
|
|
1441
|
+
`--json`. Use `validate --output-schema FILE` for a schema-checked JSON assessment.
|
|
1442
|
+
For GitHub Actions setup, see the
|
|
1443
|
+
[Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md)
|
|
1444
|
+
or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md).
|
|
1445
|
+
|
|
1446
|
+
### Local pre-commit checks
|
|
1447
|
+
|
|
1448
|
+
`install-hook` checks staged and unstaged changes, blocking the commit on scan
|
|
1449
|
+
failure or findings at/above its threshold (`high` by default). Use required CI
|
|
1450
|
+
for enforcement; local hooks are optional.
|
|
1451
|
+
|
|
1452
|
+
Install the CLI outside the target repository and run that copy directly. `npx`
|
|
1453
|
+
can select a repository-local package. Before installation, inspect:
|
|
1454
|
+
|
|
1455
|
+
```bash
|
|
1456
|
+
git -C /path/to/repository rev-parse --git-path hooks/pre-commit
|
|
1457
|
+
```
|
|
1458
|
+
|
|
1459
|
+
Resolve relative output against the repository. Leave custom, linked, shared, or
|
|
1460
|
+
unverified hooks/directories alone; contact their owner or use CI. If the directory
|
|
1461
|
+
belongs only to this repository and no hook exists, run from outside the checkout:
|
|
1462
|
+
|
|
1463
|
+
```bash
|
|
1464
|
+
codex-security install-hook /path/to/repository
|
|
1465
|
+
```
|
|
1466
|
+
|
|
1467
|
+
To migrate an existing generated hook, verify it is a regular file used only by
|
|
1468
|
+
this repository and contains only the generated command. Preserve its severity.
|
|
1469
|
+
The installer can update older `npx` hooks when the severity matches. New hooks
|
|
1470
|
+
record absolute Node/CLI paths. If those change, back up and remove the verified
|
|
1471
|
+
generated hook, then reinstall with the same threshold. Restore the backup if
|
|
1472
|
+
installation fails. The installer respects `core.hooksPath`.
|
|
1473
|
+
|
|
1474
|
+
## Import alerts from the CLI
|
|
1475
|
+
|
|
1476
|
+
```bash
|
|
1477
|
+
codex-security import github example/repository --format json > /path/outside/repository/alerts.json
|
|
1478
|
+
codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
|
|
1479
|
+
codex-security validate /path/outside/repository/alerts.json
|
|
1480
|
+
```
|
|
1481
|
+
|
|
1482
|
+
Run validation from the matching local repository. Import defaults to open alerts
|
|
1483
|
+
on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
|
|
1484
|
+
`--github-ref REF` to filter. Exact alert numbers ignore state and reject a
|
|
1485
|
+
nondefault state.
|
|
1486
|
+
|
|
1487
|
+
Import is read-only and returns an array. Save validation inputs without output
|
|
1488
|
+
filters or token limits. It includes third-party SARIF uploads, does not start
|
|
1489
|
+
Codex, and does not check out code. Each record contains `source`, `repository`,
|
|
1490
|
+
`number`, `url`, and the full upstream `alert`.
|
|
1491
|
+
|
|
1492
|
+
For a disposition per alert, import and validate through the SDK:
|
|
1493
|
+
|
|
1494
|
+
```ts
|
|
1495
|
+
import {
|
|
1496
|
+
CodexSecurity,
|
|
1497
|
+
importGitHubCodeScanningAlerts,
|
|
1498
|
+
} from "@openai/codex-security";
|
|
1499
|
+
|
|
1500
|
+
const findings = await importGitHubCodeScanningAlerts({
|
|
1501
|
+
repository: "example/repository",
|
|
1502
|
+
alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
|
|
1503
|
+
githubToken: process.env["GH_TOKEN"],
|
|
1504
|
+
});
|
|
1505
|
+
|
|
1506
|
+
const security = new CodexSecurity();
|
|
1507
|
+
try {
|
|
1508
|
+
for (const finding of findings) {
|
|
1509
|
+
const result = await security.validate({
|
|
1510
|
+
repositoryPath: "/path/to/repository",
|
|
1511
|
+
finding,
|
|
1512
|
+
});
|
|
1513
|
+
console.log(finding.url, result.disposition, result.outputDir);
|
|
1514
|
+
}
|
|
1515
|
+
} finally {
|
|
1516
|
+
await security.close();
|
|
1517
|
+
}
|
|
1518
|
+
```
|
|
1519
|
+
|
|
1520
|
+
SDK options include `state` (default `"open"`), `ref`, and `signal`.
|
|
1521
|
+
Supply `githubToken` or use `gh auth token` credentials, including GitHub CLI
|
|
1522
|
+
token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
|
|
1523
|
+
The token needs code-scanning read access; access failures reject the import.
|
|
1524
|
+
|
|
1525
|
+
## Validate and patch findings
|
|
1526
|
+
|
|
1527
|
+
`validate` assesses candidates from local source evidence without building the
|
|
1528
|
+
target, executing application code, running tests or PoCs, or contacting services.
|
|
1529
|
+
It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
|
|
1530
|
+
validation, and `patch` still fixes and verifies findings. Both commands accept files
|
|
1531
|
+
or literal text and work in the current directory. Saved finding/occurrence IDs
|
|
1532
|
+
select their original repository for patching.
|
|
1533
|
+
|
|
1534
|
+
```bash
|
|
1535
|
+
codex-security validate "Possible SQL injection" --effort high
|
|
1536
|
+
codex-security validate findings.json --knowledge-base ./context --context "Check the tenant boundary."
|
|
1537
|
+
codex-security validate findings.json --context-file context.md --output-schema result.schema.json > assessment.json
|
|
1538
|
+
codex-security patch OCCURRENCE_ID
|
|
1539
|
+
codex-security patch --scan SCAN_ID --severity high --json
|
|
1540
|
+
codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
|
|
1541
|
+
```
|
|
1542
|
+
|
|
1543
|
+
Context inputs are optional and can be combined:
|
|
1544
|
+
|
|
1545
|
+
- `--context TEXT` adds inline security context or reviewer feedback.
|
|
1546
|
+
- `--context-file PATH` reads a single UTF-8 file.
|
|
1547
|
+
- Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
|
|
1548
|
+
document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
|
|
1549
|
+
are searched recursively; binary files, symlinks, and Git metadata are skipped.
|
|
1550
|
+
|
|
1551
|
+
Inline and file context are included in the prompt. Knowledge-base documents are
|
|
1552
|
+
prepared in a temporary directory for Codex to read during the assessment, then
|
|
1553
|
+
removed. Context is separate from findings and checked against source evidence;
|
|
1554
|
+
feedback alone does not dismiss a finding.
|
|
1555
|
+
|
|
1556
|
+
By default, `validate` prints a readable assessment without JSON-schema checking.
|
|
1557
|
+
`--output-schema PATH` supplies the schema to Codex **before generation** using
|
|
1558
|
+
native structured output. The CLI also checks the completed JSON before writing
|
|
1559
|
+
stdout; it does not convert a prose assessment into JSON afterward. Invalid JSON
|
|
1560
|
+
or a schema mismatch fails with exit code 2 and no assessment on stdout.
|
|
1561
|
+
|
|
1562
|
+
Use a self-contained schema in the subset supported by the selected Codex model
|
|
1563
|
+
and provider. The local checker uses JSON Schema 2020-12, but accepting a schema
|
|
1564
|
+
locally does not guarantee provider support. Keep the schema small and use it only
|
|
1565
|
+
when the caller needs structured results. It checks the result's shape, not whether
|
|
1566
|
+
the security conclusion is correct. Relative paths resolve from the current directory.
|
|
1567
|
+
|
|
1568
|
+
The validator no longer writes reports. Save the assessment by redirecting stdout:
|
|
1569
|
+
`codex-security validate findings.json > assessment.md`. For runtime proof, run a
|
|
1570
|
+
separate reproduction step. Missing facts are reported as proof gaps; a finding
|
|
1571
|
+
supported by source evidence does not require runtime reproduction.
|
|
1572
|
+
|
|
1573
|
+
### Structured validation example
|
|
1574
|
+
|
|
1575
|
+
Save two synthetic candidates as `findings.json`:
|
|
1576
|
+
|
|
1577
|
+
```json
|
|
1578
|
+
[
|
|
1579
|
+
{
|
|
1580
|
+
"id": "candidate-1",
|
|
1581
|
+
"title": "Missing tenant filter",
|
|
1582
|
+
"location": "src/invoices.ts:24"
|
|
1583
|
+
},
|
|
1584
|
+
{
|
|
1585
|
+
"id": "candidate-2",
|
|
1586
|
+
"title": "Anonymous access",
|
|
1587
|
+
"location": "src/routes.ts:18"
|
|
1588
|
+
}
|
|
1589
|
+
]
|
|
1590
|
+
```
|
|
1591
|
+
|
|
1592
|
+
Save this minimal schema as `result.schema.json`. Each `report` contains the
|
|
1593
|
+
assessment's source evidence, counterevidence, confidence, context used, and proof
|
|
1594
|
+
gaps; callers can instead define separate fields for those details.
|
|
1595
|
+
|
|
1596
|
+
```json
|
|
1597
|
+
{
|
|
1598
|
+
"type": "object",
|
|
1599
|
+
"additionalProperties": false,
|
|
1600
|
+
"required": ["assessments"],
|
|
1601
|
+
"properties": {
|
|
1602
|
+
"assessments": {
|
|
1603
|
+
"type": "array",
|
|
1604
|
+
"items": {
|
|
1605
|
+
"type": "object",
|
|
1606
|
+
"additionalProperties": false,
|
|
1607
|
+
"required": ["id", "disposition", "report"],
|
|
1608
|
+
"properties": {
|
|
1609
|
+
"id": { "type": "string" },
|
|
1610
|
+
"disposition": {
|
|
1611
|
+
"type": "string",
|
|
1612
|
+
"enum": ["reportable", "suppressed", "not_applicable", "deferred"]
|
|
1613
|
+
},
|
|
1614
|
+
"report": { "type": "string" }
|
|
1615
|
+
}
|
|
1616
|
+
}
|
|
1617
|
+
}
|
|
1618
|
+
}
|
|
1619
|
+
}
|
|
1620
|
+
```
|
|
1621
|
+
|
|
1622
|
+
Run from the repository directory:
|
|
1623
|
+
|
|
1624
|
+
```bash
|
|
1625
|
+
codex-security validate findings.json --output-schema result.schema.json > assessment.json
|
|
1626
|
+
```
|
|
1627
|
+
|
|
1628
|
+
An illustrative result is below. Actual decisions depend on the repository;
|
|
1629
|
+
this example assumes a tenant filter exists but deployment routing is unavailable.
|
|
1630
|
+
Both candidate IDs remain in the output, including the unresolved claim.
|
|
1631
|
+
|
|
1632
|
+
```json
|
|
1633
|
+
{
|
|
1634
|
+
"assessments": [
|
|
1635
|
+
{
|
|
1636
|
+
"id": "candidate-1",
|
|
1637
|
+
"disposition": "suppressed",
|
|
1638
|
+
"report": "Missing tenant filter: src/invoices.ts:24 filters by the authenticated tenant, defeating the claimed cross-tenant read. Static confidence: high. No material proof gap for this claim. No additional context supplied; no runtime checks performed."
|
|
1639
|
+
},
|
|
1640
|
+
{
|
|
1641
|
+
"id": "candidate-2",
|
|
1642
|
+
"disposition": "deferred",
|
|
1643
|
+
"report": "Anonymous access: src/routes.ts:18 has no local authentication guard. An upstream gateway may provide one, but its routing configuration was not supplied. Proof gap: whether unauthenticated traffic can reach this route. Static confidence: low. No additional context supplied; no runtime checks performed."
|
|
1644
|
+
}
|
|
1645
|
+
]
|
|
1646
|
+
}
|
|
1647
|
+
```
|
|
1648
|
+
|
|
1649
|
+
### Patch existing findings
|
|
1650
|
+
|
|
1651
|
+
`--scan latest` uses the current repository's latest completed scan. Patching
|
|
1652
|
+
supports JSON for saved findings, literal text, and files. Each finding gets a
|
|
1653
|
+
saved Codex desktop task. `--model` and `--effort` control the model.
|
|
1654
|
+
|
|
1655
|
+
`--validation-prompt-file PATH` supplies setup, authorized targets, expected
|
|
1656
|
+
results, and cleanup for dynamic validation. It works with saved findings,
|
|
1657
|
+
text/files, and Linear inputs. Paths resolve from the invocation directory, even
|
|
1658
|
+
when the finding belongs to another repository. The file must be nonempty and
|
|
1659
|
+
regular, is read before patching, and cannot combine with `--resume-pr`.
|
|
1660
|
+
|
|
1661
|
+
`--assess-patch-risk` runs an advisory assessment after patching. Human-readable
|
|
1662
|
+
output prints its report; saved-finding JSON includes `patchRisk.report`.
|
|
1663
|
+
With `--create-pr`, the draft description includes the concise Markdown summary.
|
|
1664
|
+
The assessment does not change the patch or merge state.
|
|
1665
|
+
|
|
1666
|
+
Patching first checks that its sandbox can start. Failure reports
|
|
1667
|
+
`SANDBOX_UNAVAILABLE`; no file changes from the task reports `NO_PATCH_APPLIED`.
|
|
1668
|
+
Results list `applied`, `filesChanged`, and `files`, excluding preexisting edits.
|
|
1669
|
+
File changes alone do not prove a fix; saved findings require a verified result.
|
|
1670
|
+
|
|
1671
|
+
For a controlled container providing its own isolation:
|
|
1672
|
+
|
|
1673
|
+
```bash
|
|
1674
|
+
codex-security patch "Security issue" --external-sandbox --json
|
|
1675
|
+
```
|
|
1676
|
+
|
|
1677
|
+
This explicit option disables Codex filesystem/network enforcement for the patch
|
|
1678
|
+
task. The container must provide it. There is no automatic fallback; optional
|
|
1679
|
+
patch-risk assessment still uses its read-only sandbox.
|
|
1680
|
+
|
|
1681
|
+
`scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;
|
|
1682
|
+
`high` selects high and critical findings. Interactive users can select findings
|
|
1683
|
+
and add instructions. Patch results are `verified`, `no_change`, `blocked`, or
|
|
1684
|
+
`failed`. Verified/already-fixed findings no longer fail the severity threshold.
|
|
1685
|
+
|
|
1686
|
+
### Create or resume a draft pull request
|
|
1687
|
+
|
|
1688
|
+
`--create-pr` commits generated patch files and opens a draft GitHub PR with `gh`
|
|
1689
|
+
or a GitLab merge request with `glab`. Authenticate the appropriate CLI first.
|
|
1690
|
+
The `origin` push URL selects GitLab.com, including SSH and subgroup projects.
|
|
1691
|
+
For self-hosted GitLab, set `GITLAB_HOST` to that host and authenticate with
|
|
1692
|
+
`glab auth login --hostname HOST`. `GITLAB_URI` and `GL_HOST` are fallback aliases.
|
|
1693
|
+
GitLab merge requests stay within the origin project; a fork merge request with
|
|
1694
|
+
the same branch name is not reused. GitLab descriptions display the report in a
|
|
1695
|
+
blockquote so report text cannot execute quick actions. The report contents,
|
|
1696
|
+
including code, HTML, and math, retain their original text.
|
|
1697
|
+
|
|
1698
|
+
```bash
|
|
1699
|
+
GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
|
|
1700
|
+
```
|
|
1701
|
+
|
|
1702
|
+
Both providers return `pullRequest: { branch, url }`. Supplied-issue patching
|
|
1703
|
+
requires a clean tree. If publication fails, run the printed
|
|
1704
|
+
`patch --resume-pr BRANCH` command in the same repository. It reuses the saved
|
|
1705
|
+
commit and refuses changed branches. Retain the GitLab host setting on resume.
|
|
1706
|
+
|
|
1707
|
+
### Patch Linear issues
|
|
1708
|
+
|
|
1709
|
+
Repeat `--linear-issue ISSUE` (ID or URL), or select `--linear-project "PROJECT"`
|
|
1710
|
+
with optional native JSON `--linear-filter`. Completed/canceled issues are
|
|
1711
|
+
excluded unless the filter sets `state`.
|
|
1712
|
+
|
|
1713
|
+
Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or
|
|
1714
|
+
`LINEAR_ACCESS_TOKEN` for OAuth. Prefer environment variables over
|
|
1715
|
+
`--linear-api-key`. Intake is read-only, includes comments, and keeps Linear
|
|
1716
|
+
credentials out of the patch subprocess. URLs must match the selected workspace.
|
|
1717
|
+
|
|
1718
|
+
## Verify fixes
|
|
1719
|
+
|
|
1720
|
+
`verify-fix` checks fixes in a read-only sandbox. It accepts descriptions, saved
|
|
1721
|
+
finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
|
|
1722
|
+
filter for completed Linear issues to check a finished backlog.
|
|
1723
|
+
|
|
1724
|
+
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
1725
|
+
`--json` returns structured output. Exit codes are `0` when all findings are
|
|
1726
|
+
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|
|
1727
|
+
|
|
1728
|
+
## Command discovery and integrations
|
|
1729
|
+
|
|
1730
|
+
Use `--llms` for the command manifest, `scan --schema --format json` for its
|
|
1731
|
+
schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
|
|
1732
|
+
`--format toon|json|yaml|jsonl` and `--full-output`.
|
|
1733
|
+
|
|
1734
|
+
`skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
|
|
1735
|
+
MCP exposes only read-only `info`, because the transport cannot cancel scans.
|
|
1736
|
+
|
|
1737
|
+
For local findings storage, deduplication, and custom endpoints, see the
|
|
1738
|
+
[findings guide](findings-service.md).
|
|
1739
|
+
|
|
1740
|
+
## Containerized bulk scans
|
|
1741
|
+
|
|
1742
|
+
Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run
|
|
1743
|
+
from the repository root with the published image:
|
|
1744
|
+
|
|
1745
|
+
```bash
|
|
1746
|
+
mkdir -p results state
|
|
1747
|
+
chmod 700 results state
|
|
1748
|
+
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
|
|
1749
|
+
export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:latest
|
|
1750
|
+
docker compose pull codex-security
|
|
1751
|
+
docker compose run --rm codex-security login --device-auth
|
|
1752
|
+
docker compose run --rm codex-security
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1755
|
+
Use device login only if your workspace permits it. For unattended scans, set
|
|
1756
|
+
`OPENAI_API_KEY` or `CODEX_API_KEY`. Results go to `results/`; login stays in
|
|
1757
|
+
`state/`. Private GitHub checkouts use `GH_TOKEN` or `GITHUB_TOKEN`; Enterprise
|
|
1758
|
+
uses `CODEX_SECURITY_GIT_HOST`. The container requires CSV input.
|
|
1759
|
+
|
|
1760
|
+
Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,
|
|
1761
|
+
`CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and
|
|
1762
|
+
`CODEX_SECURITY_STATE` for its image, user, seccomp policy, and mounts.
|
|
1763
|
+
|
|
1764
|
+
Codex requires Bubblewrap for filesystem-restricted Linux execution. On Ubuntu
|
|
1765
|
+
hosts that restrict unprivileged user namespaces, an administrator must install
|
|
1766
|
+
the AppArmor profile and use the Compose override:
|
|
1767
|
+
|
|
1768
|
+
```bash
|
|
1769
|
+
sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
|
|
1770
|
+
sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
|
|
1771
|
+
docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
|
|
1772
|
+
```
|
|
1773
|
+
|
|
1774
|
+
The override enables nested namespaces while keeping the nonroot user, dropped
|
|
1775
|
+
capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested user
|
|
1776
|
+
namespaces do not need it. The legacy Landlock fallback is unsupported.
|
|
1777
|
+
See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
|
|
1778
|
+
for deployment and source-build instructions.
|