@openai/codex-security 0.6.0 → 0.7.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 +68 -37
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
- 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/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
- package/_bundled_plugin/references/access-advisory.md +11 -0
- package/_bundled_plugin/references/core-scan.md +30 -77
- package/_bundled_plugin/references/final-report.md +45 -189
- package/_bundled_plugin/references/scan-contract.md +2 -0
- package/_bundled_plugin/references/scan-prologue.md +1 -1
- package/_bundled_plugin/references/scan-runtime.md +1 -5
- package/_bundled_plugin/references/threat-model.md +33 -41
- package/_bundled_plugin/schemas/coverage.schema.json +12 -1
- package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
- package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
- package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
- package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
- package/_bundled_plugin/scripts/report_projection.py +44 -15
- package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
- package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
- package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
- package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
- package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
- package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
- package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
- package/_bundled_plugin/scripts/workbench_cli.py +3 -0
- package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
- package/_bundled_plugin/scripts/workbench_db.py +51 -22
- package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
- package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
- package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
- package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
- package/_bundled_plugin/scripts/workbench_schema.py +1 -1
- package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
- package/_bundled_plugin/scripts/workbench_target.py +142 -17
- package/_bundled_plugin/scripts/workbench_validation.py +9 -2
- package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
- package/_bundled_plugin/shared/workbench-migrations.json +28 -0
- package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
- package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
- package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
- package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
- package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
- package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
- package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
- package/_bundled_plugin/skills/publish-findings/SKILL.md +28 -24
- package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
- package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
- package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
- package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
- package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
- package/_bundled_plugin/skills/validation/SKILL.md +42 -104
- package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
- package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
- package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
- package/dist/api.d.ts +5 -3
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +341 -37
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +4 -1
- package/dist/auth.js.map +1 -1
- package/dist/cli.d.ts +2 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +674 -419
- package/dist/cli.js.map +1 -1
- package/dist/component-scan.d.ts +8 -2
- package/dist/component-scan.d.ts.map +1 -1
- package/dist/component-scan.js +2 -0
- package/dist/component-scan.js.map +1 -1
- package/dist/contract.d.ts +2 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +67 -33
- package/dist/contract.js.map +1 -1
- package/dist/cost.d.ts +18 -0
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +107 -12
- package/dist/cost.js.map +1 -1
- package/dist/coverage-presentation.d.ts +6 -0
- package/dist/coverage-presentation.d.ts.map +1 -0
- package/dist/coverage-presentation.js +34 -0
- package/dist/coverage-presentation.js.map +1 -0
- package/dist/custom-validation-prompt.js +3 -3
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/custom-validation.d.ts.map +1 -1
- package/dist/custom-validation.js +30 -4
- package/dist/custom-validation.js.map +1 -1
- package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
- package/dist/deduplication/checkpointed-review.js +3 -1
- package/dist/deduplication/checkpointed-review.js.map +1 -1
- package/dist/deduplication/scan.d.ts.map +1 -1
- package/dist/deduplication/scan.js +7 -5
- package/dist/deduplication/scan.js.map +1 -1
- package/dist/endor-findings.d.ts +4 -3
- package/dist/endor-findings.d.ts.map +1 -1
- package/dist/endor-findings.js +16 -11
- package/dist/endor-findings.js.map +1 -1
- package/dist/external-findings-import.d.ts.map +1 -1
- package/dist/external-findings-import.js +13 -5
- package/dist/external-findings-import.js.map +1 -1
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +8 -1
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts +1 -1
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +11 -3
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +11 -1
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +15 -6
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-import-contract.d.ts +3 -1
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +33 -25
- package/dist/external-import-contract.js.map +1 -1
- package/dist/external-imports-feature.d.ts +6 -0
- package/dist/external-imports-feature.d.ts.map +1 -0
- package/dist/external-imports-feature.js +51 -0
- package/dist/external-imports-feature.js.map +1 -0
- package/dist/finding-workflow.d.ts +22 -5
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +21 -9
- package/dist/finding-workflow.js.map +1 -1
- package/dist/github-advisories.d.ts.map +1 -1
- package/dist/github-advisories.js +3 -1
- package/dist/github-advisories.js.map +1 -1
- package/dist/github-findings.d.ts +4 -3
- package/dist/github-findings.d.ts.map +1 -1
- package/dist/github-findings.js +16 -14
- package/dist/github-findings.js.map +1 -1
- package/dist/hosted-remediation.d.ts.map +1 -1
- package/dist/hosted-remediation.js +19 -2
- package/dist/hosted-remediation.js.map +1 -1
- package/dist/hosted-scan.d.ts +1 -1
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +0 -5
- package/dist/hosted-scan.js.map +1 -1
- package/dist/import-scan.js +1 -1
- package/dist/import-scan.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/knowledge-base.d.ts +1 -0
- package/dist/knowledge-base.d.ts.map +1 -1
- package/dist/knowledge-base.js +17 -8
- package/dist/knowledge-base.js.map +1 -1
- package/dist/models.d.ts +1 -0
- package/dist/models.d.ts.map +1 -1
- package/dist/models.js.map +1 -1
- package/dist/owner-evidence.d.ts +2 -0
- package/dist/owner-evidence.d.ts.map +1 -1
- package/dist/owner-evidence.js +2 -1
- package/dist/owner-evidence.js.map +1 -1
- package/dist/publish.d.ts +2 -0
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +1 -1
- package/dist/publish.js.map +1 -1
- package/dist/remediation.d.ts +1 -25
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +3 -24
- package/dist/remediation.js.map +1 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +7 -7
- package/dist/runtime.js.map +1 -1
- package/dist/scan-dashboard.d.ts +5 -3
- package/dist/scan-dashboard.d.ts.map +1 -1
- package/dist/scan-dashboard.js +79 -26
- package/dist/scan-dashboard.js.map +1 -1
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +8 -2
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/scan-owner-suggestions.d.ts +1 -1
- package/dist/scan-owner-suggestions.d.ts.map +1 -1
- package/dist/scan-owner-suggestions.js +4 -4
- package/dist/scan-owner-suggestions.js.map +1 -1
- package/dist/scan-usage-display.d.ts +8 -0
- package/dist/scan-usage-display.d.ts.map +1 -0
- package/dist/scan-usage-display.js +46 -0
- package/dist/scan-usage-display.js.map +1 -0
- package/dist/scanner-import.d.ts +1 -1
- package/dist/scanner-import.d.ts.map +1 -1
- package/dist/scanner-import.js +7 -3
- package/dist/scanner-import.js.map +1 -1
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +1 -20
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts +4 -3
- package/dist/semgrep-findings.d.ts.map +1 -1
- package/dist/semgrep-findings.js +9 -9
- package/dist/semgrep-findings.js.map +1 -1
- package/dist/skill-authentication.d.ts +18 -0
- package/dist/skill-authentication.d.ts.map +1 -0
- package/dist/skill-authentication.js +82 -0
- package/dist/skill-authentication.js.map +1 -0
- package/dist/snyk-findings.d.ts +5 -4
- package/dist/snyk-findings.d.ts.map +1 -1
- package/dist/snyk-findings.js +18 -17
- package/dist/snyk-findings.js.map +1 -1
- package/dist/suggest-owners.d.ts +4 -1
- package/dist/suggest-owners.d.ts.map +1 -1
- package/dist/suggest-owners.js +53 -21
- package/dist/suggest-owners.js.map +1 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +4 -1
- package/dist/targets.js.map +1 -1
- package/dist/wiz-csv.d.ts +2 -1
- package/dist/wiz-csv.d.ts.map +1 -1
- package/dist/wiz-csv.js +3 -3
- package/dist/wiz-csv.js.map +1 -1
- package/dist/wiz-findings.d.ts +2 -1
- package/dist/wiz-findings.d.ts.map +1 -1
- package/dist/wiz-findings.js +27 -23
- package/dist/wiz-findings.js.map +1 -1
- package/docs/classify-severity-records.md +3 -4
- package/docs/cli.md +155 -38
- package/docs/findings-service.md +119 -118
- package/docs/hosted-remediation.md +19 -17
- package/docs/hosted-scans.md +37 -11
- package/package.json +8 -8
- package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
- package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
- package/_bundled_plugin/scripts/rank_preview.py +0 -129
package/docs/cli.md
CHANGED
|
@@ -23,6 +23,28 @@ findings file in local scan history, use
|
|
|
23
23
|
GitHub import returns upstream alerts for validation; file import saves findings
|
|
24
24
|
without running security analysis.
|
|
25
25
|
|
|
26
|
+
## Find a workflow
|
|
27
|
+
|
|
28
|
+
- [Sign in or configure a provider](#authentication).
|
|
29
|
+
- [Scan a repository or selected paths](#scan-options-and-output),
|
|
30
|
+
[configure a Deep Scan](#configure-deep-scans), or
|
|
31
|
+
[save project settings](#project-files).
|
|
32
|
+
- [Review one system across repositories](#review-one-system-across-repositories)
|
|
33
|
+
or [run independent bulk scans](#bulk-scans).
|
|
34
|
+
- [Import vendor findings locally](#import-vendor-findings-locally),
|
|
35
|
+
[save findings as a scan](#import-findings-as-a-saved-scan), or
|
|
36
|
+
[retrieve GitHub alerts](#import-alerts-from-the-cli).
|
|
37
|
+
- [Inspect saved scans and rerun them](#scan-history-and-reruns),
|
|
38
|
+
[classify severity](#classify-finding-severity), or
|
|
39
|
+
[suggest owners](#suggest-finding-owners).
|
|
40
|
+
- [Validate and patch findings](#validate-and-patch-findings) or
|
|
41
|
+
[verify an existing fix](#verify-fixes).
|
|
42
|
+
- [Publish to Cloud](#publish-findings-to-cloud) or
|
|
43
|
+
[Linear](#publish-completed-scans-to-linear), or [export results](#exports-and-ci).
|
|
44
|
+
- [Draft a security policy](#generate-a-security-policy).
|
|
45
|
+
- [Use a hosted executor](#hosted-standard-scan) or
|
|
46
|
+
[run bulk scans in containers](#containerized-bulk-scans).
|
|
47
|
+
|
|
26
48
|
## Authentication
|
|
27
49
|
|
|
28
50
|
Sign in with ChatGPT, or supply an API key for CI:
|
|
@@ -404,6 +426,11 @@ codex-security scan . --owner-suggestions
|
|
|
404
426
|
codex-security scan . --output-dir /path/outside/repository/results --dry-run
|
|
405
427
|
```
|
|
406
428
|
|
|
429
|
+
`--path` selects files or directories. The scan summary and saved scan details
|
|
430
|
+
show requested paths and exclusions. `coverage.deferred` records unfinished
|
|
431
|
+
requested work separately from optional `coverage.openQuestions` follow-up.
|
|
432
|
+
Human-readable output quotes ambiguous paths, while JSON retains their original strings.
|
|
433
|
+
|
|
407
434
|
Whole-codebase and path scans also accept ordinary directories, including SVN
|
|
408
435
|
working copies. Their source inventories exclude `.git` and `.svn` metadata.
|
|
409
436
|
|
|
@@ -412,12 +439,20 @@ changes. Both require Git. Deep scans support whole repositories and path scopes
|
|
|
412
439
|
Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
|
|
413
440
|
be clean and at the commit recorded by the parent.
|
|
414
441
|
|
|
442
|
+
Committed-diff scans require a clean, full checkout at the requested head
|
|
443
|
+
revision, including when using `--validate`. A different checkout revision or
|
|
444
|
+
local changes are rejected before scanning; check out the requested head and
|
|
445
|
+
commit or stash local changes before retrying.
|
|
446
|
+
|
|
415
447
|
`--owner-suggestions` writes optional `owner-suggestions.json` after a completed
|
|
416
448
|
committed Git scan, using the same checkout, model, and reasoning effort. Owner
|
|
417
449
|
errors leave the base scan completed. The JSON result includes
|
|
418
450
|
`ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
|
|
419
451
|
manifest stay unchanged. This option is unsupported for working-tree and
|
|
420
|
-
directory snapshots
|
|
452
|
+
directory snapshots. It works with `--max-cost`: hints are recorded within the
|
|
453
|
+
existing scan execution and budget, and the report is finalized without another
|
|
454
|
+
model call. Missing hints abstain; invalid hints produce per-finding owner errors.
|
|
455
|
+
Use the separate `suggest-owners` command for explicit owner-only jobs.
|
|
421
456
|
|
|
422
457
|
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
423
458
|
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
@@ -487,6 +522,38 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
|
|
|
487
522
|
its successful output and failure codes.
|
|
488
523
|
See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
|
|
489
524
|
|
|
525
|
+
### Follow-up finding validation
|
|
526
|
+
|
|
527
|
+
Scans already validate findings against local source. Add `--validate` to run
|
|
528
|
+
the existing standalone validation workflow for each reported finding after
|
|
529
|
+
the scan, using the same selected Cyber access program. Validation has read-only
|
|
530
|
+
filesystem access with network and web search disabled. Each assessment uses a
|
|
531
|
+
separate evidence directory; the combined report is saved as
|
|
532
|
+
`<scan-dir>/validation.md`, or a uniquely suffixed report
|
|
533
|
+
if that path already exists. Each completed assessment is saved immediately;
|
|
534
|
+
failed or interrupted runs retain the partial report. JSON scan output includes
|
|
535
|
+
the execution status, completed assessment count, and report path. Completion means the assessments finished,
|
|
536
|
+
not that every finding was confirmed. A scan with no findings needs no second
|
|
537
|
+
pass.
|
|
538
|
+
|
|
539
|
+
With `--workflow-id`, retries reuse completed assessments for unchanged findings,
|
|
540
|
+
source, validation settings, and saved evidence. Missing or changed evidence
|
|
541
|
+
causes validation to run again, as do older assessments without recorded evidence
|
|
542
|
+
fingerprints. By default, regeneration uses a new evidence directory. An explicit
|
|
543
|
+
SDK validation `outputDir` reuses an assessment only when it points to the same
|
|
544
|
+
evidence directory. A different destination starts a new assessment. The requested
|
|
545
|
+
directory must be empty when regenerating; existing files are never overwritten.
|
|
546
|
+
When `--knowledge-base` is supplied, the scan and all follow-up assessments use
|
|
547
|
+
one captured copy of those documents. A workflow retry must use the same document
|
|
548
|
+
contents. Use a new workflow ID if they changed or if the workflow was created
|
|
549
|
+
before document snapshots were bound to follow-up validation.
|
|
550
|
+
|
|
551
|
+
The report is supplemental: its assessments are not applied to the saved
|
|
552
|
+
findings or the `--fail-on-severity` decision. Validation failures exit with
|
|
553
|
+
`2` while retaining the completed scan. The additional model calls are not
|
|
554
|
+
cost-tracked, so `--validate` cannot be combined with `--max-cost` (including a
|
|
555
|
+
configured scan cost limit), `--dry-run`, or `--mock`.
|
|
556
|
+
|
|
490
557
|
### Understand scan scope and follow-up work
|
|
491
558
|
|
|
492
559
|
A completed scan means the requested workflow finished. It does not mean every
|
|
@@ -739,16 +806,9 @@ not to planning, result matching, or the total campaign.
|
|
|
739
806
|
|
|
740
807
|
### Configure deep scans
|
|
741
808
|
|
|
742
|
-
```
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
workers: 2,
|
|
746
|
-
subagents: 0,
|
|
747
|
-
stopAfterNoNew: 3,
|
|
748
|
-
stopAfterConsecutiveErrors: 2,
|
|
749
|
-
maxDiscoveryRuns: 10,
|
|
750
|
-
maxTimeMinutes: 90,
|
|
751
|
-
});
|
|
809
|
+
```bash
|
|
810
|
+
codex-security scan . --mode deep --workers 2 --subagents 0 \
|
|
811
|
+
--stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
|
|
752
812
|
```
|
|
753
813
|
|
|
754
814
|
For `scan --mode deep`, `--workers` controls discovery concurrency and
|
|
@@ -757,11 +817,13 @@ For `scan --mode deep`, `--workers` controls discovery concurrency and
|
|
|
757
817
|
or duration. At the deadline, discovery stops; the scan then combines and returns
|
|
758
818
|
completed findings.
|
|
759
819
|
|
|
820
|
+
For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
|
|
821
|
+
|
|
760
822
|
Use project-file `scan.deep` settings or legacy
|
|
761
823
|
`$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
|
|
762
824
|
that `subagents` can be zero. Discovery time accepts positive fractional minutes;
|
|
763
|
-
its default and maximum
|
|
764
|
-
advisory allowance,
|
|
825
|
+
its default and maximum are 5760 minutes (96 hours). Unlike Standard's
|
|
826
|
+
advisory allowance, the Deep discovery limit is enforced. Resuming a
|
|
765
827
|
Deep scan keeps its original deadline; rerunning starts a new scan.
|
|
766
828
|
`--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
|
|
767
829
|
legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
|
|
@@ -877,26 +939,27 @@ For filesystem and approval behavior, see the
|
|
|
877
939
|
|
|
878
940
|
### Environment variables
|
|
879
941
|
|
|
880
|
-
| Variable | Effect
|
|
881
|
-
| --------------------------------------------------------------------------- |
|
|
882
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence.
|
|
883
|
-
| `
|
|
884
|
-
| `
|
|
885
|
-
| `
|
|
886
|
-
| `
|
|
887
|
-
| `
|
|
888
|
-
| `
|
|
889
|
-
| `
|
|
890
|
-
| `
|
|
891
|
-
| `
|
|
892
|
-
| `
|
|
893
|
-
| `
|
|
894
|
-
| `
|
|
895
|
-
| `
|
|
896
|
-
| `
|
|
897
|
-
| `
|
|
898
|
-
| `
|
|
899
|
-
| `
|
|
942
|
+
| Variable | Effect |
|
|
943
|
+
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
944
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
|
|
945
|
+
| `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS` | Set to `1` to enable vendor finding imports, imported-findings readback, and GitHub advisory acquisition; disabled otherwise. |
|
|
946
|
+
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
|
|
947
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
|
|
948
|
+
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
|
|
949
|
+
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
|
|
950
|
+
| `PYTHON` | Python interpreter unless an explicit option overrides it. |
|
|
951
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
|
|
952
|
+
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
|
|
953
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
|
|
954
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
|
|
955
|
+
| `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
|
|
956
|
+
| `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
|
|
957
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
|
|
958
|
+
| `GH_HOST` | GitHub Enterprise host for bulk discovery. |
|
|
959
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
|
|
960
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
|
|
961
|
+
| `CI` | Disable interactive update notices. |
|
|
962
|
+
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
900
963
|
|
|
901
964
|
Custom Codex executables need thread source attribution for `exec` and
|
|
902
965
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -961,6 +1024,14 @@ work could not be measured, including in-flight turns or missing earlier attempt
|
|
|
961
1024
|
The parent can continue after report completion, so final CLI tokens can exceed
|
|
962
1025
|
the saved measurement window.
|
|
963
1026
|
|
|
1027
|
+
During a scan, progress shows when Codex reported the displayed token and cost
|
|
1028
|
+
totals, in UTC. If the report has no timestamp, progress says so.
|
|
1029
|
+
In-flight requests may add tokens and cost after that time. When Codex supplies
|
|
1030
|
+
account allowance, progress shows the percentage used in each reported window
|
|
1031
|
+
and the time of that reading. On a short terminal, resize the window or press
|
|
1032
|
+
`d` to scroll through the full readings in Details. With ChatGPT authentication,
|
|
1033
|
+
progress also says when Codex has yet to report allowance.
|
|
1034
|
+
|
|
964
1035
|
`usage.accountRateLimits` saves the latest observed account-wide readings with
|
|
965
1036
|
their own timestamps, window durations, and reset times. These are historical
|
|
966
1037
|
observations, not a live allowance check or scan-only consumption. Empty readings
|
|
@@ -1197,6 +1268,24 @@ Supply the validation prompt again when rerunning.
|
|
|
1197
1268
|
|
|
1198
1269
|
## Import vendor findings locally
|
|
1199
1270
|
|
|
1271
|
+
External finding imports are disabled by default. Opt in for the current shell:
|
|
1272
|
+
|
|
1273
|
+
```bash
|
|
1274
|
+
export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
|
|
1275
|
+
```
|
|
1276
|
+
|
|
1277
|
+
In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
|
|
1278
|
+
Only `1` enables the feature. Without it, `publish findings`, `findings imported`,
|
|
1279
|
+
and `import github-advisories` are absent from command help and schemas and cannot
|
|
1280
|
+
run. The SDK's external publication, local import/readback, and advisory
|
|
1281
|
+
acquisition APIs require the same flag in their effective environment. An explicit
|
|
1282
|
+
`dependencies.environment` is used instead of the process environment. Pure
|
|
1283
|
+
normalizers and file readers remain available as library utilities.
|
|
1284
|
+
|
|
1285
|
+
This flag does not affect `publish scan`, `publish check`, `scan import`, or the
|
|
1286
|
+
existing `import github` alert collector. Disabling it retains previously imported
|
|
1287
|
+
records; enable it again to read them with `findings imported`.
|
|
1288
|
+
|
|
1200
1289
|
Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
|
|
1201
1290
|
reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
|
|
1202
1291
|
inputs only for providers and report profiles that support them. A JSON API
|
|
@@ -1366,6 +1455,8 @@ network findings are not supported by this repository importer. Cloud destinatio
|
|
|
1366
1455
|
currently support connected GitHub and GitHub Enterprise repositories, including
|
|
1367
1456
|
custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
|
|
1368
1457
|
|
|
1458
|
+
#### Select findings and a destination
|
|
1459
|
+
|
|
1369
1460
|
Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
|
|
1370
1461
|
connection to acquire findings and save the supported native JSON. A configured
|
|
1371
1462
|
plugin may provide that connection; an official Codex plugin is not a prerequisite.
|
|
@@ -1412,6 +1503,8 @@ gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
|
|
|
1412
1503
|
filename extension. **Raw Event** on Code & Build Scans contains scan metadata
|
|
1413
1504
|
rather than findings.
|
|
1414
1505
|
|
|
1506
|
+
#### Configure an alternate Cloud deployment
|
|
1507
|
+
|
|
1415
1508
|
For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
|
|
1416
1509
|
API root before previewing or uploading, for example
|
|
1417
1510
|
`https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
|
|
@@ -1432,6 +1525,8 @@ the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
|
|
|
1432
1525
|
For custom API destinations without a configured app URL, completion retains
|
|
1433
1526
|
the manual navigation guidance rather than guessing a UI host or port.
|
|
1434
1527
|
|
|
1528
|
+
#### Preview and publish
|
|
1529
|
+
|
|
1435
1530
|
Preview the selection and destination:
|
|
1436
1531
|
|
|
1437
1532
|
```bash
|
|
@@ -1457,6 +1552,8 @@ exclusions. `--dry-run --format json` retains all normalized findings and comple
|
|
|
1457
1552
|
evidence for inspection. A prompt explicitly includes any records that will be
|
|
1458
1553
|
skipped.
|
|
1459
1554
|
|
|
1555
|
+
#### Package vulnerability inputs
|
|
1556
|
+
|
|
1460
1557
|
Native package input can be a Wiz JSON vulnerability report, a vulnerability
|
|
1461
1558
|
finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
|
|
1462
1559
|
with one package record per line. The repository package-vulnerability CSV
|
|
@@ -1507,6 +1604,8 @@ fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
|
|
|
1507
1604
|
Findings from external network scans are excluded from this package vulnerability
|
|
1508
1605
|
mapping.
|
|
1509
1606
|
|
|
1607
|
+
#### SAST, repository secrets, and IaC inputs
|
|
1608
|
+
|
|
1510
1609
|
For SAST, repository secrets, and IaC, save the documented JSON API collection:
|
|
1511
1610
|
|
|
1512
1611
|
| Finding family | Collection | Raw occurrence identity |
|
|
@@ -1565,6 +1664,8 @@ collection:
|
|
|
1565
1664
|
}
|
|
1566
1665
|
```
|
|
1567
1666
|
|
|
1667
|
+
#### Preserved evidence
|
|
1668
|
+
|
|
1568
1669
|
The adapters preserve each selected raw node exactly in `source_data`. Typed
|
|
1569
1670
|
`evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
|
|
1570
1671
|
and family-specific evidence:
|
|
@@ -1583,6 +1684,8 @@ does not establish that it is deployed. Precise original timestamps remain in
|
|
|
1583
1684
|
`source_updated_at` field. SAST creation time and IaC last-seen time are not update
|
|
1584
1685
|
timestamps.
|
|
1585
1686
|
|
|
1687
|
+
#### Convert CSV reports
|
|
1688
|
+
|
|
1586
1689
|
Native SAST and secret report downloads can be CSV, including gzip-compressed
|
|
1587
1690
|
CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
|
|
1588
1691
|
for its actual column headers into normalized JSONL, preserving each original row
|
|
@@ -1607,6 +1710,8 @@ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
|
|
|
1607
1710
|
integer range is rejected; export those values as strings to preserve them
|
|
1608
1711
|
exactly. Invalid records appear in `excluded` with their source ID and reason.
|
|
1609
1712
|
|
|
1713
|
+
#### Resume interrupted imports
|
|
1714
|
+
|
|
1610
1715
|
Requests contain at most 100 findings and respect the Cloud payload limits.
|
|
1611
1716
|
Before uploading, the publisher saves request IDs and bodies privately under
|
|
1612
1717
|
the configured Codex Security state directory. After an uncertain response,
|
|
@@ -1618,6 +1723,8 @@ API endpoint, not a link to the Cloud UI. A reset
|
|
|
1618
1723
|
retires the old request without republishing; review and explicitly approve a
|
|
1619
1724
|
fresh invocation.
|
|
1620
1725
|
|
|
1726
|
+
#### Results and exit codes
|
|
1727
|
+
|
|
1621
1728
|
Results distinguish completion from partial or interrupted work:
|
|
1622
1729
|
|
|
1623
1730
|
| Status | Exit code | Meaning |
|
|
@@ -1768,7 +1875,7 @@ The [records protocol](classify-severity-records.md) accepts immutable Markdown
|
|
|
1768
1875
|
report snapshots and delegates model execution to the host.
|
|
1769
1876
|
|
|
1770
1877
|
For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
|
|
1771
|
-
Omitting `--rubric` runs classification with the [built-in severity rubric](
|
|
1878
|
+
Omitting `--rubric` runs classification with the [built-in severity rubric](https://github.com/openai/codex-security/blob/main/sdk/typescript/src/default-severity-rubric.ts).
|
|
1772
1879
|
It evaluates attacker access, boundary crossing, additional harm, and evidence for
|
|
1773
1880
|
Critical, High, Medium, Low, and Informational findings. Confidence remains separate
|
|
1774
1881
|
from severity; missing proof alone does not justify a downgrade. An explicit
|
|
@@ -2278,6 +2385,9 @@ installation fails. The installer respects `core.hooksPath`.
|
|
|
2278
2385
|
|
|
2279
2386
|
## Import GitHub findings locally or to Cloud
|
|
2280
2387
|
|
|
2388
|
+
Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
|
|
2389
|
+
The existing alert collector remains available without it.
|
|
2390
|
+
|
|
2281
2391
|
Acquire code-scanning findings with the existing `import github` collector and
|
|
2282
2392
|
save its complete JSON output. In Codex, the official
|
|
2283
2393
|
[GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
|
|
@@ -2369,6 +2479,8 @@ import file directly. Read records with `listLocalExternalFindings({ repository
|
|
|
2369
2479
|
|
|
2370
2480
|
### Import GHSA advisories separately
|
|
2371
2481
|
|
|
2482
|
+
Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
|
|
2483
|
+
|
|
2372
2484
|
**Importing a GHSA advisory does not establish an installed dependency or
|
|
2373
2485
|
applicability to the destination repository.** Repository advisories are
|
|
2374
2486
|
disclosures maintained by a repository; global advisories describe affected
|
|
@@ -2705,6 +2817,11 @@ for `patch`. Omit it or use `--verification-mode standard` for the default check
|
|
|
2705
2817
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
2706
2818
|
`--json` returns structured output. Exit codes are `0` when all findings are
|
|
2707
2819
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|
|
2820
|
+
Authentication and execution failures print diagnostics on stderr and return
|
|
2821
|
+
`status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message` with `--json`
|
|
2822
|
+
or `--format jsonl`. With JSON/JSONL `--full-output`, failures use an `ok: false`
|
|
2823
|
+
error envelope. Other formats retain stderr-only failures. Interruptions retain
|
|
2824
|
+
exit codes `130` and `143` without a result.
|
|
2708
2825
|
|
|
2709
2826
|
## Command discovery and integrations
|
|
2710
2827
|
|
|
@@ -2721,6 +2838,10 @@ scan, triage, patch, and verification workflows, see the
|
|
|
2721
2838
|
For local findings storage, deduplication, and custom endpoints, see the
|
|
2722
2839
|
[findings guide](findings-service.md).
|
|
2723
2840
|
|
|
2841
|
+
### Hosted Standard scan
|
|
2842
|
+
|
|
2843
|
+
`codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
|
|
2844
|
+
|
|
2724
2845
|
## Containerized bulk scans
|
|
2725
2846
|
|
|
2726
2847
|
Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run
|
|
@@ -2760,7 +2881,3 @@ capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested us
|
|
|
2760
2881
|
namespaces do not need it. The legacy Landlock fallback is unsupported.
|
|
2761
2882
|
See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
|
|
2762
2883
|
for deployment and source-build instructions.
|
|
2763
|
-
|
|
2764
|
-
### Hosted Standard scan
|
|
2765
|
-
|
|
2766
|
-
`codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
|
package/docs/findings-service.md
CHANGED
|
@@ -5,124 +5,7 @@ Deduplication reads that database directly; no local HTTP service is needed.
|
|
|
5
5
|
The CLI can also publish to and deduplicate against independently operated
|
|
6
6
|
compatible endpoints through explicit `--findings-url` settings.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
The `serve` command (including `--port`), `start:server` script,
|
|
11
|
-
`dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
|
|
12
|
-
dashboard, and findings-service Compose deployment have been removed.
|
|
13
|
-
`HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
|
|
14
|
-
service. The dashboard storage projection is also removed.
|
|
15
|
-
|
|
16
|
-
Existing SQLite databases, migrations, saved scans, findings, and duplicate
|
|
17
|
-
groups are retained. No data migration or deletion is performed. Keep any
|
|
18
|
-
existing service volume or state directory and back it up before changing
|
|
19
|
-
deployments; local deduplication uses the database selected by
|
|
20
|
-
`CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
|
|
21
|
-
|
|
22
|
-
`@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
|
|
23
|
-
`SqliteFindingsStore`, and their storage types for direct storage users.
|
|
24
|
-
|
|
25
|
-
For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
|
|
26
|
-
static key or `() => string | Promise<string>` as its first argument. It calls
|
|
27
|
-
the callback before each HTTP batch; the caller handles token acquisition.
|
|
28
|
-
Cancellation prevents a new callback or HTTP request. Direct embedder callers
|
|
29
|
-
still await a key callback that has already started.
|
|
30
|
-
Pass `fetch` as the second argument and the full endpoint URL as the third.
|
|
31
|
-
By default, the saved-scan deduplication APIs use environment credentials. A
|
|
32
|
-
custom SDK `embedding` binding can supply an adapter with its own credentials,
|
|
33
|
-
including an `OpenAiFindingEmbedder` with a renewable key callback.
|
|
34
|
-
|
|
35
|
-
Custom publication, explicit remote deduplication, Cloud publication, the
|
|
36
|
-
plugin MCP server, and Codex app-server are unchanged.
|
|
37
|
-
|
|
38
|
-
## Direct storage helpers
|
|
39
|
-
|
|
40
|
-
Direct callers of the retired Python findings helpers can use the retained Node
|
|
41
|
-
helpers from an installed plugin directory:
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
scripts/launch_codex_security_mcp --helper list-stored-findings < request.json
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
On Windows, use `scripts\launch_codex_security_mcp.cmd` with the same arguments
|
|
48
|
-
and JSON on stdin. For example, `request.json` selects the existing database:
|
|
49
|
-
|
|
50
|
-
```json
|
|
51
|
-
{
|
|
52
|
-
"stateDirectory": "/absolute/path/to/state",
|
|
53
|
-
"payload": { "limit": 50, "offset": 0 }
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Use an absolute Windows path on Windows. The retained helper commands accept
|
|
58
|
-
these `payload` fields:
|
|
59
|
-
|
|
60
|
-
| Command | Payload |
|
|
61
|
-
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
62
|
-
| `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
|
|
63
|
-
| `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
|
|
64
|
-
| `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
|
|
65
|
-
| `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
|
|
66
|
-
| `list-dedupe-groups` | `findingId`. |
|
|
67
|
-
|
|
68
|
-
Retained scan commands such as `workbench_db.py list-findings` keep their existing
|
|
69
|
-
interface. The dashboard projection is removed along with the browser dashboard.
|
|
70
|
-
|
|
71
|
-
## Publish a scan
|
|
72
|
-
|
|
73
|
-
Send a completed scan to an independently operated compatible endpoint:
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
codex-security publish scan --scan SCAN_ID --to custom \
|
|
77
|
-
--findings-url https://findings.example.com --json
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
`--findings-url` is required. The client appends `/v1/bulk/findings` to this
|
|
81
|
-
base URL, preserving any base path. Custom endpoints must implement that API
|
|
82
|
-
and return the stored finding IDs.
|
|
83
|
-
|
|
84
|
-
Publication sends the complete sealed findings and the manifest's
|
|
85
|
-
`scan.target.targetId` as `repositoryId`. It leaves the scan artifacts unchanged
|
|
86
|
-
and does not forward model credentials. The endpoint is responsible for storing the batch before acknowledging it.
|
|
87
|
-
|
|
88
|
-
Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or
|
|
89
|
-
the interactive picker. Custom publication accepts one scan; CSV input and
|
|
90
|
-
Linear options do not apply. Add `--dry-run` to preview the payload without an
|
|
91
|
-
HTTP request. Upload failures and incomplete receipts fail the command. Uploads
|
|
92
|
-
are not automatically retried because a lost response may have been committed.
|
|
93
|
-
|
|
94
|
-
```typescript
|
|
95
|
-
import { publishScanToCustom } from "@openai/codex-security";
|
|
96
|
-
|
|
97
|
-
const receipt = await publishScanToCustom("/path/to/completed-scan", {
|
|
98
|
-
findingsUrl: "https://findings.example.com",
|
|
99
|
-
// dryRun: true,
|
|
100
|
-
// signal: controller.signal,
|
|
101
|
-
});
|
|
102
|
-
console.log(receipt.repositoryId, receipt.findingIds);
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
## Compatible endpoint contract
|
|
106
|
-
|
|
107
|
-
The retained HTTP clients use these endpoints on the supplied base URL,
|
|
108
|
-
preserving its base path:
|
|
109
|
-
|
|
110
|
-
| Method | Path | Response |
|
|
111
|
-
| ------ | --------------------------------------- | ------------------------------------------------------------------------ |
|
|
112
|
-
| `POST` | `/v1/bulk/findings` | An array acknowledging all submitted finding IDs; order does not matter. |
|
|
113
|
-
| `GET` | `/v1/finding/{id}/potential-duplicates` | `{finding, potentialDuplicates}` containing complete finding records. |
|
|
114
|
-
| `POST` | `/v1/dedupe-groups` | A successful JSON acknowledgement, such as `{}`. |
|
|
115
|
-
|
|
116
|
-
Publication sends `{findings, repositoryId}`. Candidate requests include either
|
|
117
|
-
`repositoryId` or `allRepositories=true`. Group writes send
|
|
118
|
-
`{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
|
|
119
|
-
workflow retries. Both POST endpoints must persist their writes before
|
|
120
|
-
acknowledging them and return a JSON body. An explicit URL selects this remote
|
|
121
|
-
contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
|
|
122
|
-
|
|
123
|
-
SDK findings client failures preserve the endpoint's error code and message with
|
|
124
|
-
the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
|
|
125
|
-
behavior uses the HTTP status and `Retry-After`.
|
|
8
|
+
For an older service deployment or helper integration, see [compatibility](#compatibility).
|
|
126
9
|
|
|
127
10
|
## Deduplicate a scan
|
|
128
11
|
|
|
@@ -405,3 +288,121 @@ including `text-embedding-3-large`, 1,536-dimensional float vectors, and token
|
|
|
405
288
|
array inputs. Requests encode the complete finding JSON with `cl100k_base` and
|
|
406
289
|
send the API key as a bearer token. Long inputs are combined without truncation.
|
|
407
290
|
Cached compatible vectors avoid new requests.
|
|
291
|
+
|
|
292
|
+
## Publish a scan
|
|
293
|
+
|
|
294
|
+
Send a completed scan to an independently operated compatible endpoint:
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
codex-security publish scan --scan SCAN_ID --to custom \
|
|
298
|
+
--findings-url https://findings.example.com --json
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
`--findings-url` is required. The client appends `/v1/bulk/findings` to this
|
|
302
|
+
base URL, preserving any base path. Custom endpoints must implement that API
|
|
303
|
+
and return the stored finding IDs.
|
|
304
|
+
|
|
305
|
+
Publication sends the complete sealed findings and the manifest's
|
|
306
|
+
`scan.target.targetId` as `repositoryId`. It leaves the scan artifacts unchanged
|
|
307
|
+
and does not forward model credentials. The endpoint is responsible for storing the batch before acknowledging it.
|
|
308
|
+
|
|
309
|
+
Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or
|
|
310
|
+
the interactive picker. Custom publication accepts one scan; CSV input and
|
|
311
|
+
Linear options do not apply. Add `--dry-run` to preview the payload without an
|
|
312
|
+
HTTP request. Upload failures and incomplete receipts fail the command. Uploads
|
|
313
|
+
are not automatically retried because a lost response may have been committed.
|
|
314
|
+
|
|
315
|
+
```typescript
|
|
316
|
+
import { publishScanToCustom } from "@openai/codex-security";
|
|
317
|
+
|
|
318
|
+
const receipt = await publishScanToCustom("/path/to/completed-scan", {
|
|
319
|
+
findingsUrl: "https://findings.example.com",
|
|
320
|
+
// dryRun: true,
|
|
321
|
+
// signal: controller.signal,
|
|
322
|
+
});
|
|
323
|
+
console.log(receipt.repositoryId, receipt.findingIds);
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
## Compatible endpoint contract
|
|
327
|
+
|
|
328
|
+
The retained HTTP clients use these endpoints on the supplied base URL,
|
|
329
|
+
preserving its base path:
|
|
330
|
+
|
|
331
|
+
| Method | Path | Response |
|
|
332
|
+
| ------ | --------------------------------------- | ------------------------------------------------------------------------ |
|
|
333
|
+
| `POST` | `/v1/bulk/findings` | An array acknowledging all submitted finding IDs; order does not matter. |
|
|
334
|
+
| `GET` | `/v1/finding/{id}/potential-duplicates` | `{finding, potentialDuplicates}` containing complete finding records. |
|
|
335
|
+
| `POST` | `/v1/dedupe-groups` | A successful JSON acknowledgement, such as `{}`. |
|
|
336
|
+
|
|
337
|
+
Publication sends `{findings, repositoryId}`. Candidate requests include either
|
|
338
|
+
`repositoryId` or `allRepositories=true`. Group writes send
|
|
339
|
+
`{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
|
|
340
|
+
workflow retries. Both POST endpoints must persist their writes before
|
|
341
|
+
acknowledging them and return a JSON body. An explicit URL selects this remote
|
|
342
|
+
contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
|
|
343
|
+
|
|
344
|
+
SDK findings client failures preserve the endpoint's error code and message with
|
|
345
|
+
the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
|
|
346
|
+
behavior uses the HTTP status and `Retry-After`.
|
|
347
|
+
|
|
348
|
+
## Compatibility
|
|
349
|
+
|
|
350
|
+
### Local service removal
|
|
351
|
+
|
|
352
|
+
The `serve` command (including `--port`), `start:server` script,
|
|
353
|
+
`dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
|
|
354
|
+
dashboard, and findings-service Compose deployment have been removed.
|
|
355
|
+
`HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
|
|
356
|
+
service. The dashboard storage projection is also removed.
|
|
357
|
+
|
|
358
|
+
Existing SQLite databases, migrations, saved scans, findings, and duplicate
|
|
359
|
+
groups are retained. No data migration or deletion is performed. Keep any
|
|
360
|
+
existing service volume or state directory and back it up before changing
|
|
361
|
+
deployments; local deduplication uses the database selected by
|
|
362
|
+
`CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
|
|
363
|
+
|
|
364
|
+
`@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
|
|
365
|
+
`SqliteFindingsStore`, and their storage types for direct storage users.
|
|
366
|
+
|
|
367
|
+
For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
|
|
368
|
+
static key or `() => string | Promise<string>` as its first argument. It calls
|
|
369
|
+
the callback before each HTTP batch; the caller handles token acquisition.
|
|
370
|
+
Cancellation prevents a new callback or HTTP request. Direct embedder callers
|
|
371
|
+
still await a key callback that has already started.
|
|
372
|
+
Pass `fetch` as the second argument and the full endpoint URL as the third.
|
|
373
|
+
By default, the saved-scan deduplication APIs use environment credentials. A
|
|
374
|
+
custom SDK `embedding` binding can supply an adapter with its own credentials,
|
|
375
|
+
including an `OpenAiFindingEmbedder` with a renewable key callback.
|
|
376
|
+
|
|
377
|
+
### Direct storage helpers
|
|
378
|
+
|
|
379
|
+
Direct callers of the retired Python findings helpers can use the retained Node
|
|
380
|
+
helpers from an installed plugin directory:
|
|
381
|
+
|
|
382
|
+
```bash
|
|
383
|
+
scripts/launch_codex_security_mcp --helper list-stored-findings < request.json
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
On Windows, use `scripts\launch_codex_security_mcp.cmd` with the same arguments
|
|
387
|
+
and JSON on stdin. For example, `request.json` selects the existing database:
|
|
388
|
+
|
|
389
|
+
```json
|
|
390
|
+
{
|
|
391
|
+
"stateDirectory": "/absolute/path/to/state",
|
|
392
|
+
"payload": { "limit": 50, "offset": 0 }
|
|
393
|
+
}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
Use an absolute Windows path on Windows. The retained helper commands accept
|
|
397
|
+
these `payload` fields:
|
|
398
|
+
|
|
399
|
+
| Command | Payload |
|
|
400
|
+
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
401
|
+
| `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
|
|
402
|
+
| `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
|
|
403
|
+
| `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
|
|
404
|
+
| `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
|
|
405
|
+
| `list-dedupe-groups` | `findingId`. |
|
|
406
|
+
|
|
407
|
+
Retained scan commands such as `workbench_db.py list-findings` keep their existing
|
|
408
|
+
interface.
|