@openai/codex-security 0.1.24 → 0.1.26

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.
Files changed (150) hide show
  1. package/README.md +399 -27
  2. package/_bundled_plugin/.app.json +0 -5
  3. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  4. package/_bundled_plugin/.mcp.json +1 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/references/config-preflight.md +2 -2
  8. package/_bundled_plugin/references/final-report.md +5 -3
  9. package/_bundled_plugin/references/scan-artifacts.md +5 -1
  10. package/_bundled_plugin/references/scan-contract.md +7 -3
  11. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +27 -1
  12. package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
  13. package/_bundled_plugin/scripts/finalize_scan_contract.py +2 -5
  14. package/_bundled_plugin/scripts/rank_preview.py +11 -1
  15. package/_bundled_plugin/scripts/report_projection.py +1 -1
  16. package/_bundled_plugin/scripts/workbench_cli.py +11 -1
  17. package/_bundled_plugin/scripts/workbench_db.py +55 -4
  18. package/_bundled_plugin/scripts/workbench_saved_results.py +41 -22
  19. package/_bundled_plugin/scripts/workbench_scan_history.py +374 -66
  20. package/_bundled_plugin/scripts/workbench_scan_usage.py +7 -6
  21. package/_bundled_plugin/scripts/workbench_schema.py +46 -0
  22. package/_bundled_plugin/scripts/workbench_severity.py +119 -0
  23. package/_bundled_plugin/scripts/workbench_target.py +86 -12
  24. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -3
  25. package/_bundled_plugin/skills/verify-fix/SKILL.md +5 -1
  26. package/dist/api.d.ts +15 -2
  27. package/dist/api.d.ts.map +1 -1
  28. package/dist/api.js +333 -32
  29. package/dist/api.js.map +1 -1
  30. package/dist/auth.d.ts.map +1 -1
  31. package/dist/auth.js +35 -3
  32. package/dist/auth.js.map +1 -1
  33. package/dist/classify-scan-severity.d.ts +16 -0
  34. package/dist/classify-scan-severity.d.ts.map +1 -0
  35. package/dist/classify-scan-severity.js +96 -0
  36. package/dist/classify-scan-severity.js.map +1 -0
  37. package/dist/classify-severity.d.ts +38 -0
  38. package/dist/classify-severity.d.ts.map +1 -0
  39. package/dist/classify-severity.js +185 -0
  40. package/dist/classify-severity.js.map +1 -0
  41. package/dist/cli.d.ts +7 -2
  42. package/dist/cli.d.ts.map +1 -1
  43. package/dist/cli.js +403 -116
  44. package/dist/cli.js.map +1 -1
  45. package/dist/component-plan.d.ts.map +1 -1
  46. package/dist/component-plan.js +4 -2
  47. package/dist/component-plan.js.map +1 -1
  48. package/dist/component-scan.d.ts.map +1 -1
  49. package/dist/component-scan.js +21 -6
  50. package/dist/component-scan.js.map +1 -1
  51. package/dist/config.d.ts.map +1 -1
  52. package/dist/config.js +46 -2
  53. package/dist/config.js.map +1 -1
  54. package/dist/cost.d.ts +1 -0
  55. package/dist/cost.d.ts.map +1 -1
  56. package/dist/cost.js +43 -17
  57. package/dist/cost.js.map +1 -1
  58. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  59. package/dist/deduplication/checkpointed-review.js +2 -1
  60. package/dist/deduplication/checkpointed-review.js.map +1 -1
  61. package/dist/deduplication/codex-review.d.ts +3 -0
  62. package/dist/deduplication/codex-review.d.ts.map +1 -1
  63. package/dist/deduplication/codex-review.js +122 -36
  64. package/dist/deduplication/codex-review.js.map +1 -1
  65. package/dist/deduplication/deduplication-prompts.d.ts +4 -3
  66. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  67. package/dist/deduplication/deduplication-prompts.js +18 -9
  68. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  69. package/dist/deduplication/deduplication-reviewer.d.ts +2 -7
  70. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  71. package/dist/deduplication/deduplication-reviewer.js +47 -25
  72. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  73. package/dist/deduplication/deduplication.d.ts.map +1 -1
  74. package/dist/deduplication/deduplication.js +186 -23
  75. package/dist/deduplication/deduplication.js.map +1 -1
  76. package/dist/deduplication/scan.d.ts +9 -1
  77. package/dist/deduplication/scan.d.ts.map +1 -1
  78. package/dist/deduplication/scan.js +24 -7
  79. package/dist/deduplication/scan.js.map +1 -1
  80. package/dist/errors.d.ts +13 -0
  81. package/dist/errors.d.ts.map +1 -1
  82. package/dist/errors.js +7 -0
  83. package/dist/errors.js.map +1 -1
  84. package/dist/finding-catalogue.d.ts +11 -0
  85. package/dist/finding-catalogue.d.ts.map +1 -0
  86. package/dist/finding-catalogue.js +150 -0
  87. package/dist/finding-catalogue.js.map +1 -0
  88. package/dist/index.d.ts +11 -5
  89. package/dist/index.d.ts.map +1 -1
  90. package/dist/index.js +5 -2
  91. package/dist/index.js.map +1 -1
  92. package/dist/mock-scan.d.ts +4 -0
  93. package/dist/mock-scan.d.ts.map +1 -0
  94. package/dist/mock-scan.js +210 -0
  95. package/dist/mock-scan.js.map +1 -0
  96. package/dist/patch-tui.js +1 -1
  97. package/dist/patch-tui.js.map +1 -1
  98. package/dist/publication-store.d.ts.map +1 -1
  99. package/dist/publication-store.js +9 -4
  100. package/dist/publication-store.js.map +1 -1
  101. package/dist/publication.d.ts +9 -0
  102. package/dist/publication.d.ts.map +1 -1
  103. package/dist/publication.js +45 -5
  104. package/dist/publication.js.map +1 -1
  105. package/dist/publish.d.ts +4 -2
  106. package/dist/publish.d.ts.map +1 -1
  107. package/dist/publish.js +4 -4
  108. package/dist/publish.js.map +1 -1
  109. package/dist/runtime.d.ts +1 -0
  110. package/dist/runtime.d.ts.map +1 -1
  111. package/dist/runtime.js +49 -14
  112. package/dist/runtime.js.map +1 -1
  113. package/dist/scan-comparison.d.ts +44 -30
  114. package/dist/scan-comparison.d.ts.map +1 -1
  115. package/dist/scan-comparison.js +673 -101
  116. package/dist/scan-comparison.js.map +1 -1
  117. package/dist/scan-dashboard.d.ts +3 -1
  118. package/dist/scan-dashboard.d.ts.map +1 -1
  119. package/dist/scan-dashboard.js +70 -3
  120. package/dist/scan-dashboard.js.map +1 -1
  121. package/dist/scan-history-renderer.d.ts.map +1 -1
  122. package/dist/scan-history-renderer.js +26 -0
  123. package/dist/scan-history-renderer.js.map +1 -1
  124. package/dist/server/api.d.ts +6 -0
  125. package/dist/server/api.d.ts.map +1 -0
  126. package/dist/server/api.js +4 -0
  127. package/dist/server/api.js.map +1 -0
  128. package/dist/server/dashboard/app.css +1 -1
  129. package/dist/server/embeddings.d.ts +2 -1
  130. package/dist/server/embeddings.d.ts.map +1 -1
  131. package/dist/server/embeddings.js +8 -3
  132. package/dist/server/embeddings.js.map +1 -1
  133. package/dist/server/serve.d.ts.map +1 -1
  134. package/dist/server/serve.js +1 -1
  135. package/dist/server/serve.js.map +1 -1
  136. package/dist/severity-store.d.ts +2 -0
  137. package/dist/severity-store.d.ts.map +1 -0
  138. package/dist/severity-store.js +111 -0
  139. package/dist/severity-store.js.map +1 -0
  140. package/dist/targets.d.ts.map +1 -1
  141. package/dist/targets.js +3 -5
  142. package/dist/targets.js.map +1 -1
  143. package/dist/thread-source.d.ts +1 -0
  144. package/dist/thread-source.d.ts.map +1 -1
  145. package/dist/thread-source.js +1 -0
  146. package/dist/thread-source.js.map +1 -1
  147. package/dist/version.d.ts +1 -1
  148. package/dist/version.js +1 -1
  149. package/dist/version.js.map +1 -1
  150. package/package.json +11 -6
package/README.md CHANGED
@@ -40,7 +40,7 @@ try {
40
40
 
41
41
  `result.findings` contains this scan's findings; `repositoryFindings` also
42
42
  includes earlier open findings when available. Matching earlier findings can
43
- make one extra model call, even with a cost limit.
43
+ make extra model calls; see [Progress and cost](#progress-and-cost).
44
44
 
45
45
  Keep results outside the repository and restrict access: reports can contain
46
46
  source code, vulnerability details, and reproduction steps.
@@ -69,6 +69,10 @@ Pass literal text or a JSON-serializable object as `finding`, not a file path.
69
69
  Validation uses the client's settings and credentials without changing
70
70
  repository files or adding a scan to history.
71
71
 
72
+ To disable Codex usage analytics and built-in metrics, create the client with
73
+ `new CodexSecurity({ codexOverrides: { analytics: { enabled: false } } })`.
74
+ This setting also applies to scans run by the same client.
75
+
72
76
  Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,
73
77
  or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.
74
78
  `reportable` may rely on static analysis; `deferred` means insufficient evidence.
@@ -186,6 +190,16 @@ Environment API keys apply to the current scan; only `login --with-api-key`
186
190
  saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
187
191
  Access-token environment variables are not scan API keys.
188
192
 
193
+ SDK callers can select native command authentication through
194
+ `codexOverrides.model_providers.<id>.auth` and `model_provider` (including a
195
+ selected `profile`). Scans, comparisons, and deduplication reviews preserve
196
+ that selection without requiring an API key or replacing it with a stored
197
+ login. Codex executes the helper and renews its token. Helper paths and relative
198
+ `auth.cwd` values resolve from the supplied `CODEX_HOME` (default `~/.codex`),
199
+ not the source checkout; an absolute `auth.cwd` is preserved. Comparisons and
200
+ reviews also honor the selected command provider in that home's `config.toml`.
201
+ Configuration is passed to Codex for validation, including profile support.
202
+
189
203
  For other inference providers:
190
204
 
191
205
  ```bash
@@ -289,6 +303,41 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
289
303
  `1` if a completed scan finds high or critical issues. Incomplete scans exit
290
304
  with `2`, writing available results to stdout and a coverage warning to stderr.
291
305
 
306
+ ### Generate mock scan results
307
+
308
+ Use `--mock` to populate a Standard scan with synthetic test data in seconds,
309
+ without Codex authentication or any LLM calls:
310
+
311
+ ```bash
312
+ codex-security scan /path/to/repository --mock
313
+ codex-security scan /path/to/repository --mock --output-dir /path/outside/repository/mock-results
314
+ ```
315
+
316
+ The SDK equivalent is `await security.run(repository, { mock: true })`.
317
+ Mock mode is off by default. It uses normal target validation, scan registration,
318
+ artifact finalization, reports, and local scan/finding history. Output directories,
319
+ archiving, JSON output, exports, and `--fail-on-severity` work as usual.
320
+ `--dry-run` only validates inputs; `--mock` saves a completed scan.
321
+
322
+ Each run contains 12 findings across all severity levels: eight stable findings
323
+ recur on subsequent scans of the same repository, and four have new identities
324
+ on every run. Two pairs describe the same root causes with different titles and
325
+ identities, providing inputs for deduplication testing. Mock scans skip automatic
326
+ LLM matching; existing identity-based history indexing still runs. Separate
327
+ comparison or deduplication commands retain their usual model behavior.
328
+
329
+ Titles, provenance, artifact metadata, and reports identify the results as
330
+ synthetic. Paths and code snippets are fictional and are never written into the
331
+ repository. Completion means fixture generation finished, not that the repository
332
+ was audited. Results enter the selected local state just like other scans; set
333
+ `CODEX_SECURITY_STATE_DIR` to a separate directory when creating disposable data.
334
+ Token usage is zero. `scans rerun` preserves mock mode.
335
+
336
+ Mock mode supports repository, path, and diff targets in Standard mode. It cannot
337
+ be combined with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan
338
+ prompts. Scan prompts and knowledge-base inputs do not change the fixtures, and
339
+ mock scans do not offer interactive patching.
340
+
292
341
  ### Attribute scans to end users
293
342
 
294
343
  When scanning on behalf of users, pass each user's stable hashed ID:
@@ -356,13 +405,22 @@ original IDs. Uncertain matches stay separate. `summary.json` records coverage
356
405
  and matching status; `report.md` links to component reports. Export and publish
357
406
  from the individual scan folders, not the combined summary.
358
407
 
408
+ Large comparisons use bounded batches that cover every earlier/later finding
409
+ pair. Overlapping confirmed groups are joined in code. Finding text is not
410
+ truncated; pairs above Codex's input limit leave matching incomplete.
411
+
359
412
  Use an empty output directory outside the project. Failed components don't
360
413
  stop others, but failures, incomplete coverage, or failed matching exit with
361
414
  `2`. Retry failed or incomplete components with
362
415
  `--components-file retry-components.json` and a new output directory.
416
+ The retry report covers only those components; it does not update the original
417
+ combined report.
363
418
 
364
419
  `--max-cost` applies per component, excluding planning and matching.
365
420
  `--model` and `--effort` also apply to matching; `--auth` applies throughout.
421
+ Planning and matching reject an ambient command provider that conflicts with
422
+ explicit `--auth chatgpt` or `--auth api-key`. A command provider explicitly
423
+ selected through SDK `codexOverrides` retains its authentication configuration.
366
424
  Use `--knowledge-base`, `--scan-prompt-file`, and `--post-scan-prompt-file` as for
367
425
  bulk scans.
368
426
 
@@ -461,8 +519,29 @@ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
461
519
  stay enabled: `agents.max_threads` and
462
520
  `features.multi_agent_v2.enabled=false` are rejected.
463
521
 
464
- `validate` and `patch` accept `--effort` and the `model` and
465
- `model_reasoning_effort` keys in `--codex`, but no other runtime overrides.
522
+ `validate`, `patch`, and `verify-fix` accept `--effort` and the `model`,
523
+ `model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
524
+ other runtime overrides.
525
+
526
+ Use `--codex 'analytics.enabled=false'` to disable Codex usage analytics and
527
+ built-in metrics for a command:
528
+
529
+ ```bash
530
+ npx @openai/codex-security validate "Candidate finding" --codex 'analytics.enabled=false'
531
+ npx @openai/codex-security patch "Security issue" --codex 'analytics.enabled=false'
532
+ npx @openai/codex-security verify-fix "Security issue" --codex 'analytics.enabled=false'
533
+ ```
534
+
535
+ The same setting works for `scan` and `bulk-scan`. An explicit setting is
536
+ preserved when `scan --patch` starts remediation and when
537
+ `patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
538
+ is also accepted; omitting the setting preserves the command's existing
539
+ configuration and Codex defaults. Validation continues to ignore user
540
+ configuration, while patching and verification retain their existing ambient
541
+ configuration and project-trust behavior.
542
+
543
+ This setting does not control explicitly configured OpenTelemetry log or trace
544
+ exporters, authentication, integrations, or CLI update checks.
466
545
 
467
546
  See [Local security model](#local-security-model) for approval and filesystem
468
547
  restrictions.
@@ -472,6 +551,7 @@ restrictions.
472
551
  | Variable | Effect |
473
552
  | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
474
553
  | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
554
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
475
555
  | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
476
556
  | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
477
557
  | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
@@ -513,6 +593,31 @@ discovery has finished, the scan returns a sealed partial report without more
513
593
  model calls and lists unvalidated candidates as follow-up work. Bulk scans
514
594
  apply the limit per repository attempt.
515
595
 
596
+ With `--max-cost`, automatic finding-history matching makes at most one extra
597
+ model call. If it needs more context, the completed scan is kept and a warning
598
+ directs you to run `scans match --all` explicitly.
599
+
600
+ For a single scan in the interactive dashboard, reaching 80% of the limit
601
+ offers a higher **total** USD limit. Enter a larger amount to approve it, or
602
+ press Enter with an empty input or Escape to keep the current limit. The scan
603
+ continues running while you decide, and the existing limit remains enforced
604
+ until the increase is saved. Increases keep the same scan and accumulated cost;
605
+ they do not restart work or extend time or discovery limits. CI, JSON/JSONL,
606
+ `--headless`, and `--verbose` scans do not offer budget increases. If usage crosses the limit
607
+ before an increase is approved, the scan still stops.
608
+
609
+ SDK callers can supply `onBudgetApproaching({ maxCostUsd, cost, signal })` and
610
+ return a higher total limit, or `undefined` to keep the current limit. The
611
+ callback runs once per limit at 80% usage without blocking tracking or
612
+ execution. Its signal aborts when the scan stops or finishes model work; late
613
+ answers are ignored. Invalid increases or failures to save them leave the
614
+ existing limit in place and report a warning. `onCost(cost, maxCostUsd)` reports
615
+ the current limit, including after an approved increase.
616
+
617
+ These amounts estimate API-equivalent model usage, not ChatGPT subscription
618
+ allowance. Post-scan prompts run after scan cost tracking ends and are outside
619
+ this limit.
620
+
516
621
  ### Bulk scans
517
622
 
518
623
  Run `gh auth login`, then `npx @openai/codex-security bulk-scan` to select
@@ -750,6 +855,139 @@ Options include `projectId`, `skipExisting`, `linearApiKey` for direct API
750
855
  publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts
751
856
  the same destination options for a read-only check.
752
857
 
858
+ ### Classify finding severity
859
+
860
+ Classify findings after a scan or dedupe without repeating discovery or changing
861
+ the original severity, evidence, or sealed scan artifacts:
862
+
863
+ ```bash
864
+ codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md --json
865
+ codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
866
+ codex-security classify-severity --scan-dir /path/to/completed-scan --json
867
+ ```
868
+
869
+ `--scan` accepts a saved scan ID, unique prefix, or `latest` for the current
870
+ repository, matching `dedupe` and `publish scan`. `--scan-dir` accepts an external
871
+ completed scan without requiring local history. Supply exactly one selector.
872
+ Omitting `--rubric` inherits each finding's existing severity without a model call.
873
+
874
+ `--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
875
+ to provide supporting architecture, deployment, or business context. Both accept
876
+ the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
877
+ Rubric classification uses the full supplied report and context in a separate
878
+ read-only Codex turn per finding, without source inspection, tools, or new
879
+ validation. `--model` and `--effort` select the classification model and reasoning
880
+ effort; otherwise Codex's configured model and the helper's medium effort apply.
881
+
882
+ The result contains one assessment per selected finding:
883
+
884
+ - `decision`: `assessed` or `excluded`; policy exclusions do not become Low.
885
+ - `level`: `critical`, `high`, `medium`, `low`, or `informational`; null for exclusions.
886
+ - `rubricLabel`: the policy's original label, such as `URGENT`, normalized to
887
+ `critical`; null for inherited severity or exclusions.
888
+ - `rationale`, separate `confidence`, and `reviewTrigger` describing a missing
889
+ fact that would change the classification. Inherited severity has no new
890
+ classification-confidence judgment.
891
+ - `findingId`, `occurrenceId`, and `inputSha256` binding the assessment to the
892
+ report. Top-level metadata includes `assessedAt`, `rubricSha256`, and
893
+ `knowledgeBaseSha256` for the supplied policy and context snapshots.
894
+
895
+ Scan classification saves each successful finding immediately in the local
896
+ workbench SQLite database. Rerunning skips assessments with matching finding
897
+ evidence, rubric, and knowledge-base hashes, including exclusions, and returns
898
+ both reused and newly generated assessments. Changed inputs are classified again.
899
+ Use `--reprocess` to rerun every selected finding regardless of its saved
900
+ assessment; each row is replaced only after its new assessment succeeds. A failed
901
+ or canceled run keeps completed checkpoints, so a normal retry resumes missing
902
+ work. Changing only the model or effort requires `--reprocess`.
903
+
904
+ SQLite is authoritative. A successful run also exports the complete selected
905
+ result to `severity-classification.json` alongside the sealed artifacts. The file
906
+ is replaced atomically and is not read for reuse or publication. The scan's
907
+ original findings and severity are unchanged. The database stores the requested
908
+ selection and policy/context hashes; publication rejects an incomplete selection
909
+ or assessments whose inputs no longer match. Rubric documents are read at
910
+ classification time, not again at publication time.
911
+
912
+ ```bash
913
+ codex-security classify-severity --scan latest --rubric /path/to/policy.md --reprocess
914
+ ```
915
+
916
+ Use repeatable `--finding-id ID` to classify a selected set, such as the
917
+ `uniqueFindingIds` returned by dedupe. With a saved classification, Linear
918
+ publication defaults to that selection, omits excluded records, and uses assessed
919
+ severity for issue priority and title. The description retains original scan
920
+ severity and adds classification reasoning. Without a saved classification,
921
+ publication retains its existing severity mapping and selection behavior.
922
+ Publication rejects assessments whose IDs or evidence hashes no longer match.
923
+
924
+ ```bash
925
+ codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
926
+ --finding-id FINDING_ID --json
927
+ codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
928
+ --dry-run --json
929
+ codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
930
+ --skip-existing --json
931
+ ```
932
+
933
+ `publish scan --to linear` also accepts repeatable `--finding-id ID` to select a
934
+ subset directly. If a classification exists, every explicitly selected finding
935
+ must have an assessment. Classification does not change existing Linear tickets;
936
+ `--skip-existing` preserves recorded tickets and any human priority edits. It
937
+ retains the existing limitations around unrecorded or concurrent publications.
938
+
939
+ The SDK exposes the same operations:
940
+
941
+ ```ts
942
+ import {
943
+ classifySeverity,
944
+ classifyScanSeverity,
945
+ classifyScanDirectorySeverity,
946
+ publishScan,
947
+ } from "@openai/codex-security";
948
+
949
+ // Supplied reports from any source: returns an assessment without writing files.
950
+ const classification = await classifySeverity(findings, {
951
+ rubricPath: "/path/to/policy.md",
952
+ knowledgeBasePaths: ["/path/to/context.md"],
953
+ });
954
+
955
+ // Saved IDs (including prefixes/latest), or sealed directories; saves an assessment.
956
+ await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
957
+ await classifyScanDirectorySeverity(scanDirectory, {
958
+ rubricPath: "/path/to/policy.md",
959
+ findingIds: dedupeResult.uniqueFindingIds,
960
+ });
961
+
962
+ await publishScan(scanDirectory, {
963
+ destination: "linear",
964
+ teamId: "TEAM_ID",
965
+ skipExisting: true,
966
+ });
967
+
968
+ // Alternatively supply a classification directly, without a saved assessment.
969
+ await publishScan(scanDirectory, {
970
+ destination: "linear",
971
+ teamId: "TEAM_ID",
972
+ classification,
973
+ findingIds: classification.assessments.map(({ findingId }) => findingId),
974
+ dryRun: true,
975
+ });
976
+ ```
977
+
978
+ `classifySeverity` accepts reports with `findingId`, `title`, and `summary`, plus
979
+ their available evidence and metadata. Original `severity` and `occurrenceId`
980
+ may be absent for imported reports; reports without severity require a rubric.
981
+ `classifySeverity` remains an in-memory operation without database persistence.
982
+ The scan wrappers use the local state database (also for external scan
983
+ directories), accept `reprocess: true`, and accept `findingIds: []` as an
984
+ intentionally empty selection. Rows outside the selected set are retained.
985
+ Use the same `CODEX_SECURITY_STATE_DIR` for classification and publication.
986
+ JSON exports from versions without database checkpoints must be reclassified
987
+ once before they can be reused.
988
+ Pass `signal` to cancel any classification operation. Keep human overrides in the
989
+ calling workflow or issue tracker; assessments remain separate recommendations.
990
+
753
991
  ### Scan history and reruns
754
992
 
755
993
  Commands default to the current repository. Select scans by full ID or a
@@ -773,6 +1011,44 @@ or unknown. Missing findings aren't resolved if the later scan is incomplete
773
1011
  or excludes their original scope. With one ID, `scans compare` compares it
774
1012
  to the latest completed scan.
775
1013
 
1014
+ Use `scans match --all --force` to rebuild comparisons chronologically while
1015
+ retaining stable finding identities. Ctrl-C keeps comparisons already saved.
1016
+ Only high-confidence duplicates are grouped; uncertain and independently
1017
+ related findings stay separate. Matching preserves triage and sealed artifacts.
1018
+
1019
+ Codex is called only when a new decision is needed, using existing authentication.
1020
+ Scans without sealed artifacts are skipped, but their confirmed links can still
1021
+ be reused. Older custom plugins save confirmed and uncertain matches; use the
1022
+ bundled plugin for related links and large comparisons.
1023
+
1024
+ SDK callers can compare findings without saving a workbench comparison:
1025
+
1026
+ ```ts
1027
+ import { readFile } from "node:fs/promises";
1028
+ import {
1029
+ matchScanFindings,
1030
+ type FindingsDocument,
1031
+ } from "@openai/codex-security";
1032
+
1033
+ const before = JSON.parse(
1034
+ await readFile("/path/to/earlier-scan/findings.json", "utf8"),
1035
+ ) as FindingsDocument;
1036
+ const after = JSON.parse(
1037
+ await readFile("/path/to/later-scan/findings.json", "utf8"),
1038
+ ) as FindingsDocument;
1039
+
1040
+ const comparison = await matchScanFindings(
1041
+ { before: before.findings, after: after.findings },
1042
+ { workingDirectory: "/path/to/repository" },
1043
+ );
1044
+ console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
1045
+ ```
1046
+
1047
+ Pass `knownFindingGroups` to reuse confirmed groups of stable `findingId` values
1048
+ from your store. Results identify the original `occurrenceId` values. Options
1049
+ include model, reasoning effort, `AbortSignal`, and an optional `onProgress`
1050
+ callback whose errors do not interrupt matching.
1051
+
776
1052
  History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
777
1053
  `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and
778
1054
  workbench maintain the database and its journal files as the current user.
@@ -852,8 +1128,8 @@ assessment skill once on the completed patch. The assessment is advisory and
852
1128
  does not change the patch or its merge state. Human-readable commands print the
853
1129
  report after the patch results; saved-finding JSON output returns it as
854
1130
  `patchRisk.report` in the same result object. When combined with `--create-pr`,
855
- the draft pull request body includes only the concise Markdown summary from the
856
- assessment; the validated JSON remains in the command result.
1131
+ the draft pull request or merge request body includes only the concise Markdown
1132
+ summary from the assessment; the validated JSON remains in the command result.
857
1133
 
858
1134
  ```bash
859
1135
  npx @openai/codex-security validate "Possible SQL injection" --effort high
@@ -875,11 +1151,25 @@ to select findings and add patch instructions. Results include a `patches`
875
1151
  entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
876
1152
  Verified and already-fixed findings no longer fail `--fail-on-severity`.
877
1153
 
878
- `--create-pr` commits generated patch files and opens a draft PR with `gh`.
879
- Supplied-issue pull requests require a clean working tree before patching so
1154
+ `--create-pr` commits generated patch files and opens a draft GitHub pull request
1155
+ with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
1156
+ the appropriate CLI first (`gh auth login` or `glab auth login`). GitLab.com is
1157
+ selected from the `origin` push URL, including SSH URLs and subgroup projects.
1158
+ For self-hosted GitLab, set `GITLAB_HOST` to the host in that URL and authenticate
1159
+ with `glab auth login --hostname HOST`. The existing `GITLAB_URI` and `GL_HOST`
1160
+ aliases are also accepted, in that order after `GITLAB_HOST`. Other hosts retain
1161
+ the GitHub workflow.
1162
+
1163
+ ```bash
1164
+ GITLAB_HOST=gitlab.example.com npx @openai/codex-security patch --scan SCAN_ID --create-pr
1165
+ ```
1166
+
1167
+ Both providers use the existing `pullRequest: { branch, url }` JSON result.
1168
+ Supplied-issue requests require a clean working tree before patching so
880
1169
  existing work is never included. If publication fails, run the printed
881
1170
  `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
882
1171
  commit without rerunning Codex, but refuses to publish if the branch changed.
1172
+ Use the same GitLab host setting when resuming a self-hosted merge request.
883
1173
 
884
1174
  To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
885
1175
  `--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
@@ -1134,6 +1424,22 @@ const result = await deduplicateScan("scan_example_001", {
1134
1424
  console.log(result.duplicateGroups);
1135
1425
  ```
1136
1426
 
1427
+ For a complete, sealed scan directory that is not registered in local scan
1428
+ history, provide the repository checkout separately:
1429
+
1430
+ ```typescript
1431
+ import { deduplicateScanDirectory } from "@openai/codex-security";
1432
+
1433
+ const result = await deduplicateScanDirectory("/path/to/completed-scan", {
1434
+ repository: "/path/to/repository",
1435
+ findingsUrl: "http://127.0.0.1:3000",
1436
+ // expectedScanId: "scan_example_001",
1437
+ // allRepositories: true,
1438
+ // signal: controller.signal,
1439
+ });
1440
+ console.log(result.duplicateGroups);
1441
+ ```
1442
+
1137
1443
  The CLI and SDK return the same result:
1138
1444
 
1139
1445
  ```json
@@ -1231,11 +1537,16 @@ reviews or group writes. A publication whose acknowledgement was lost is retried
1231
1537
  using the service's existing idempotent upsert.
1232
1538
 
1233
1539
  Each validated screening and pair review is checkpointed locally,
1234
- including DISTINCT decisions. Every SAME checkpoint retains its required
1235
- `canonicalFindingId` and generated `mergedFinding`. The merged record must satisfy
1236
- the Finding schema and preserve the canonical finding ID. Validation still happens
1237
- through `review_validator.submit_decisions`; invalid submissions are corrected in
1238
- the same review conversation, and invalid or unfinished reviews are not cached.
1540
+ including DISTINCT decisions. Screening checkpoints retain pair recommendations
1541
+ and rationales under host-assigned pair slots bound to the original records.
1542
+ Every SAME pair-review checkpoint retains its
1543
+ required `canonicalFindingId` and generated `mergedFinding`; the merged record
1544
+ must satisfy the Finding schema and preserve the canonical finding ID. Validation
1545
+ still happens through `review_validator.submit_decisions`; invalid submissions
1546
+ are corrected in the same review conversation. A completed turn without an
1547
+ accepted submission receives one corrective turn in that same conversation.
1548
+ Transport, model, cancellation, and accepted `submit_error` failures are terminal.
1549
+ Invalid or unfinished reviews are not cached.
1239
1550
 
1240
1551
  Checkpoints bind to the exact original records and ordering, approved source path,
1241
1552
  Git revision and current file contents (including ignored files), repository scope,
@@ -1263,12 +1574,12 @@ use another workflow ID for a fresh review rather than changing that saved resul
1263
1574
  2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
1264
1575
  effort. The review covers every anchor-neighbor pair; nominations between
1265
1576
  neighbors are rejected.
1266
- 3. Independently review each nominated pair once with `gpt-5.6-sol` at `xhigh`
1577
+ 3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
1267
1578
  reasoning effort. Only accepted pairs contribute to duplicate groups.
1268
- 4. Group connected findings deterministically, treating accepted duplicate
1269
- pairs as transitive: if A matches B and B matches C, all three belong to one
1270
- group. There is no additional whole-group review. A mistaken accepted pair
1271
- can therefore join otherwise distinct findings.
1579
+ 4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
1580
+ decision contradicts the resulting component. Contradicted components are
1581
+ split deterministically, preferring legal subgroups that preserve more
1582
+ accepted-pair support. There is no additional whole-group review.
1272
1583
  5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result
1273
1584
  only after the service accepts the write. An empty result requires no write.
1274
1585
 
@@ -1283,14 +1594,50 @@ and Codex state. Screening denies approval requests; final reviews use Codex's
1283
1594
  automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.
1284
1595
  Finding content never authorizes access to another target.
1285
1596
 
1597
+ Pair reviews cover exactly the two supplied findings. Linked parent tickets,
1598
+ duplicate targets, and related-ticket records are metadata, not additional
1599
+ findings to fetch or prerequisites for a verdict. An unsupplied duplicate target
1600
+ is neither automatically canonical nor an error; source-code investigation for
1601
+ the supplied pair remains allowed.
1602
+
1603
+ Incomplete supplied finding content can produce `DISTINCT` with the limitation
1604
+ explained. An execution, tool, or source-access blocker that prevents a required
1605
+ check instead uses `review_validator.submit_error` with a nonempty `reason`.
1606
+ That submission fails the review without a verdict or review checkpoint, so it
1607
+ cannot become a `DISTINCT` veto or a completed duplicate-group result. A failed
1608
+ optional lookup does not force failure or `DISTINCT` when other evidence suffices.
1609
+
1286
1610
  Decisions must arrive through the direct `review_validator.submit_decisions`
1287
1611
  tool; invalid submissions can be corrected in the same session. A final text
1288
- answer alone is insufficient. Every `SAME` decision, including screening
1289
- nominations, requires an assigned `canonicalFindingId` and a generated,
1290
- inclusive `mergedFinding`; missing or null values are rejected. Screening
1291
- canonicals must belong to the nominated pair. Sol reviews use only the complete
1292
- originals, never earlier merged findings. These review fields do not change
1293
- the command's ID-only result or stored findings.
1612
+ answer alone is insufficient. Luna screening returns a `SAME` or `DISTINCT`
1613
+ decision and rationale under each required host-assigned slot (`pair-1`,
1614
+ `pair-2`, and so on). The host binds each slot to its corresponding
1615
+ anchor-neighbor pair, so the model does not submit finding IDs. Luna does not
1616
+ select a canonical or generate a merged finding. Every
1617
+ Sol `SAME` decision requires an assigned `canonicalFindingId` and
1618
+ a generated, inclusive `mergedFinding`; missing or null values are rejected.
1619
+ Sol reviews use only the complete originals, never earlier model rationales or
1620
+ merged findings. These review fields do not change the command's ID-only result
1621
+ or stored findings.
1622
+
1623
+ Non-cancellation review failures throw `DeduplicationReviewError`. Its `metadata`
1624
+ contains only the review stage, model, failure category, attempt count, and a
1625
+ sanitized reason for diagnostics or an external support bundle; it does not
1626
+ contain findings, prompts, paths, thread IDs, or credentials.
1627
+
1628
+ If a completed turn has no accepted submission, whether it ended with text only
1629
+ or after rejected submissions, the runner sends one corrective instruction in
1630
+ the same conversation. This preserves the original assignment, source work, and
1631
+ tool feedback. Reviews are limited to two turns; `metadata.attempts` counts
1632
+ those turns (or the initial attempt if setup fails). Accepted results are not
1633
+ replayed. Cancellation, accepted `submit_error` reports, and model or transport
1634
+ failures remain terminal.
1635
+
1636
+ The SDK does not retain private review transcripts, subprocess stderr, or full
1637
+ provider/RPC error payloads, and ephemeral review state is removed after the
1638
+ session. The public metadata is a limited diagnostic summary, not a complete
1639
+ troubleshooting trace; it intentionally omits the original error cause. Private
1640
+ diagnostic retention is not currently implemented.
1294
1641
 
1295
1642
  Model calls run sequentially on the SDK/CLI host using its Codex sign-in or
1296
1643
  `OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model
@@ -1350,6 +1697,18 @@ precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using
1350
1697
  `CODEX_API_KEY` instead. Listing and empty imports do not require a key.
1351
1698
  A Codex ChatGPT login is not an embedding API credential.
1352
1699
 
1700
+ Set `CODEX_SECURITY_EMBEDDINGS_URL` to override the full embeddings endpoint URL,
1701
+ including its path and any query parameters. Unset or empty values use
1702
+ `https://api.openai.com/v1/embeddings`. Export it before `codex-security serve`,
1703
+ or set it in `.env` for Docker Compose, which passes it to the service. For example:
1704
+
1705
+ ```bash
1706
+ CODEX_SECURITY_EMBEDDINGS_URL=https://embeddings.example.com/v1/embeddings codex-security serve
1707
+ ```
1708
+
1709
+ The configured endpoint receives the finding inputs and the API key as a bearer
1710
+ token and must support the same OpenAI embeddings request and response format.
1711
+
1353
1712
  The service calls the OpenAI embeddings API with `text-embedding-3-large` and
1354
1713
  1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
1355
1714
  bundled `cl100k_base` encoding. Long inputs are split without truncation;
@@ -1379,8 +1738,8 @@ The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and
1379
1738
  `CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if
1380
1739
  changing these settings. Compose binds only to host loopback; the API has no
1381
1740
  authentication. Use an authenticated TLS proxy before sharing access. Finding
1382
- JSON is sent to `api.openai.com` over HTTPS for embeddings; the database and
1383
- generated embeddings stay in the local volume.
1741
+ JSON is sent to the configured embeddings endpoint (`api.openai.com` over HTTPS
1742
+ by default); the database and generated embeddings stay in the local volume.
1384
1743
 
1385
1744
  ### Upgrades and backups
1386
1745
 
@@ -1423,7 +1782,7 @@ From a source checkout's `sdk/typescript` directory:
1423
1782
 
1424
1783
  ```bash
1425
1784
  pnpm install --frozen-lockfile
1426
- npm ci --prefix ../../plugins/codex-security/mcp-app
1785
+ pnpm --dir ../../plugins/codex-security/mcp-app install --frozen-lockfile
1427
1786
  pnpm run build:plugin
1428
1787
  pnpm run build
1429
1788
  node bin/codex-security.mjs serve --port 3000
@@ -1450,11 +1809,24 @@ migration that also imports known associations from stored scan occurrences.
1450
1809
  New scan findings retain their target associations when indexed locally.
1451
1810
  The server entrypoint selects the concrete
1452
1811
  embedder and store, so either can be replaced independently.
1812
+
1813
+ For renewable embeddings credentials, import `OpenAiFindingEmbedder`,
1814
+ `SqliteFindingsStore`, and `startFindingsServer` from
1815
+ `@openai/codex-security/server`. The embedder's first argument accepts a static
1816
+ key or `() => string | Promise<string>`. It calls the callback before every
1817
+ HTTP batch, including subsequent calls to `embed`; callers own token acquisition.
1818
+ Pass `fetch` as the second argument and
1819
+ `process.env.CODEX_SECURITY_EMBEDDINGS_URL || undefined` as the third to use
1820
+ the same full endpoint URL and default as `codex-security serve`. Importing the
1821
+ server API does not start a listener.
1822
+
1453
1823
  The local workflow lives under `src/deduplication/`. `FindingDeduplicator`
1454
1824
  receives a candidate API client and a `DeduplicationReviewer`, keeping grouping
1455
1825
  separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts
1456
1826
  and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.
1457
- `deduplicateScan` validates saved scan artifacts before running the workflow.
1827
+ `deduplicateScan` validates saved scan artifacts before running the workflow;
1828
+ `deduplicateScanDirectory` performs the same validation for an explicit sealed
1829
+ scan directory without consulting local scan history.
1458
1830
  The SDK reuses the existing Codex runtime and credentials without additional
1459
1831
  runtime dependencies.
1460
1832
 
@@ -1,10 +1,5 @@
1
1
  {
2
2
  "apps": {
3
- "codex-security-access": {
4
- "id": "connector_openai_codex_security_access",
5
- "category": "Security",
6
- "required": false
7
- },
8
3
  "linear": {
9
4
  "id": "asdk_app_69a089a326dc8191b32a3f2553f5be2c",
10
5
  "category": "Work Tracking & Coordination"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-security",
3
- "version": "0.1.79",
3
+ "version": "0.1.95",
4
4
  "description": "Codex Security workflows for security scans, analysis, and investigation.",
5
5
  "author": {
6
6
  "name": "OpenAI"
@@ -49,6 +49,7 @@
49
49
  "NODE_EXTRA_CA_CERTS",
50
50
  "XDG_CACHE_HOME"
51
51
  ],
52
+ "startup_timeout_sec": 120,
52
53
  "tool_timeout_sec": 349200
53
54
  }
54
55
  }
@@ -84,6 +84,6 @@ Present applicable remediation in the Codex thread. Ask before editing persisten
84
84
 
85
85
  Codex CLI and other hosts use the same prompt-based preflight before substantive work. Explain the exact reasons and remediation in chat. Interactive CLI sessions ask before editing persistent config; non-interactive CLI sessions use the narrow automatic-remediation path above and continue only after a `ready` rerun.
86
86
 
87
- ## TAC Status Advisory
87
+ ## Daybreak Access Advisory
88
88
 
89
- After capability preflight is `ready` and immediately before the workflow's first substantive scan action, use the hosted Codex Security Access app [$codex-security-access](app://connector_openai_codex_security_access) to call its `get_tac_status` action exactly once as the automatic pre-scan advisory. For Deep Security Scan, make this call immediately before `start_codex_security_deep_scan`. If this scan already performed the automatic advisory in an earlier continuation, reuse that result instead of calling it again. Report its exact `status` and TAC grant levels. When `status` is `not_granted`, before any other scan-start progress, present a separate, prominent warning that TAC access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link; if that field is absent, use `https://chatgpt.com/cyber`. Do not bury this warning in a routine status summary. When `status` is `unknown`, or the app or action is unavailable, instead warn that TAC access could not be verified and protected scan outputs may not be displayable. Then continue regardless. This result is advisory and must never authorize or gate the scan. Do not poll it or repeat it between scan phases. If the user explicitly asks to re-check after an account or TAC access change, call the action again for a fresh result; this user-requested refresh is the only repeat.
89
+ After capability preflight is `ready` and immediately before the workflow's first substantive scan action, call the plugin's `get_codex_security_daybreak_access` tool exactly once when available as the automatic pre-scan advisory. ChatGPT-authenticated desktop and CLI sessions both support this advisory; API-key-only sessions cannot verify account access. For Deep Security Scan, make this call immediately before `start_codex_security_deep_scan`. If this scan already performed the automatic advisory in an earlier continuation, reuse that result instead of calling it again. Report its exact `status` and available Daybreak programs. When `status` is `not_granted`, before any other scan-start progress, present a separate, prominent warning that Daybreak access is not granted for this account and protected scan outputs may not be displayable. Include the returned `enrollmentUrl` as a clickable application link; if that field is absent, use `https://chatgpt.com/cyber`. Do not bury this warning in a routine status summary. When `status` is `unknown`, `stale` is `true`, or the tool is unavailable or fails, instead warn that Daybreak access could not be verified and protected scan outputs may not be displayable. Then continue regardless. This result is advisory and must never authorize or gate the scan. Do not poll it or repeat it between scan phases. If the user explicitly asks to re-check after an account or Daybreak access change, call the tool again when available for a fresh result; this user-requested refresh is the only repeat.