@openai/codex-security 0.1.23 → 0.1.25

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 (135) hide show
  1. package/README.md +200 -23
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/references/scan-contract.md +10 -0
  7. package/_bundled_plugin/scripts/deep_scan_workbench.py +6 -1
  8. package/_bundled_plugin/scripts/finalize_scan_contract.py +27 -78
  9. package/_bundled_plugin/scripts/generate_in_scope_files.py +2 -8
  10. package/_bundled_plugin/scripts/generate_rank_input.py +1 -5
  11. package/_bundled_plugin/scripts/rank_preview.py +12 -1
  12. package/_bundled_plugin/scripts/report_projection.py +8 -14
  13. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -3
  14. package/_bundled_plugin/scripts/windows_scan_local_files.py +5 -15
  15. package/_bundled_plugin/scripts/workbench_cli.py +14 -1
  16. package/_bundled_plugin/scripts/workbench_dashboard.py +41 -18
  17. package/_bundled_plugin/scripts/workbench_db.py +127 -541
  18. package/_bundled_plugin/scripts/workbench_finding_workflows.py +31 -13
  19. package/_bundled_plugin/scripts/workbench_findings.py +8 -3
  20. package/_bundled_plugin/scripts/workbench_native_indexes.py +1 -2
  21. package/_bundled_plugin/scripts/workbench_publication.py +520 -0
  22. package/_bundled_plugin/scripts/workbench_remediation.py +37 -0
  23. package/_bundled_plugin/scripts/workbench_saved_results.py +298 -90
  24. package/_bundled_plugin/scripts/workbench_scan_history.py +375 -68
  25. package/_bundled_plugin/scripts/workbench_scan_usage.py +9 -33
  26. package/_bundled_plugin/scripts/workbench_schema.py +49 -21
  27. package/_bundled_plugin/scripts/workbench_target.py +96 -17
  28. package/_bundled_plugin/scripts/workbench_validation.py +1 -5
  29. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +1 -5
  30. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +6 -1
  31. package/dist/api.d.ts +18 -3
  32. package/dist/api.d.ts.map +1 -1
  33. package/dist/api.js +350 -28
  34. package/dist/api.js.map +1 -1
  35. package/dist/auth.d.ts.map +1 -1
  36. package/dist/auth.js +35 -3
  37. package/dist/auth.js.map +1 -1
  38. package/dist/cli.d.ts +2 -0
  39. package/dist/cli.d.ts.map +1 -1
  40. package/dist/cli.js +118 -35
  41. package/dist/cli.js.map +1 -1
  42. package/dist/component-plan.d.ts.map +1 -1
  43. package/dist/component-plan.js +4 -2
  44. package/dist/component-plan.js.map +1 -1
  45. package/dist/component-scan.d.ts.map +1 -1
  46. package/dist/component-scan.js +21 -6
  47. package/dist/component-scan.js.map +1 -1
  48. package/dist/config.d.ts.map +1 -1
  49. package/dist/config.js +46 -2
  50. package/dist/config.js.map +1 -1
  51. package/dist/cost.d.ts +1 -0
  52. package/dist/cost.d.ts.map +1 -1
  53. package/dist/cost.js +23 -11
  54. package/dist/cost.js.map +1 -1
  55. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  56. package/dist/deduplication/checkpointed-review.js +2 -1
  57. package/dist/deduplication/checkpointed-review.js.map +1 -1
  58. package/dist/deduplication/codex-review.d.ts +3 -0
  59. package/dist/deduplication/codex-review.d.ts.map +1 -1
  60. package/dist/deduplication/codex-review.js +122 -36
  61. package/dist/deduplication/codex-review.js.map +1 -1
  62. package/dist/deduplication/deduplication-prompts.d.ts +4 -3
  63. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  64. package/dist/deduplication/deduplication-prompts.js +18 -9
  65. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  66. package/dist/deduplication/deduplication-reviewer.d.ts +2 -7
  67. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  68. package/dist/deduplication/deduplication-reviewer.js +46 -24
  69. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  70. package/dist/deduplication/deduplication.d.ts.map +1 -1
  71. package/dist/deduplication/deduplication.js +186 -23
  72. package/dist/deduplication/deduplication.js.map +1 -1
  73. package/dist/deduplication/scan.d.ts +9 -1
  74. package/dist/deduplication/scan.d.ts.map +1 -1
  75. package/dist/deduplication/scan.js +24 -7
  76. package/dist/deduplication/scan.js.map +1 -1
  77. package/dist/deep-progress.d.ts +21 -0
  78. package/dist/deep-progress.d.ts.map +1 -0
  79. package/dist/deep-progress.js +108 -0
  80. package/dist/deep-progress.js.map +1 -0
  81. package/dist/errors.d.ts +13 -0
  82. package/dist/errors.d.ts.map +1 -1
  83. package/dist/errors.js +7 -0
  84. package/dist/errors.js.map +1 -1
  85. package/dist/index.d.ts +6 -5
  86. package/dist/index.d.ts.map +1 -1
  87. package/dist/index.js +2 -2
  88. package/dist/index.js.map +1 -1
  89. package/dist/mock-scan.d.ts +4 -0
  90. package/dist/mock-scan.d.ts.map +1 -0
  91. package/dist/mock-scan.js +210 -0
  92. package/dist/mock-scan.js.map +1 -0
  93. package/dist/publish.d.ts.map +1 -1
  94. package/dist/publish.js +2 -2
  95. package/dist/publish.js.map +1 -1
  96. package/dist/runtime.d.ts +1 -0
  97. package/dist/runtime.d.ts.map +1 -1
  98. package/dist/runtime.js +54 -14
  99. package/dist/runtime.js.map +1 -1
  100. package/dist/scan-activity.d.ts.map +1 -1
  101. package/dist/scan-activity.js +12 -2
  102. package/dist/scan-activity.js.map +1 -1
  103. package/dist/scan-comparison.d.ts +11 -2
  104. package/dist/scan-comparison.d.ts.map +1 -1
  105. package/dist/scan-comparison.js +237 -39
  106. package/dist/scan-comparison.js.map +1 -1
  107. package/dist/scan-dashboard.d.ts +3 -1
  108. package/dist/scan-dashboard.d.ts.map +1 -1
  109. package/dist/scan-dashboard.js +70 -3
  110. package/dist/scan-dashboard.js.map +1 -1
  111. package/dist/scan-history-renderer.d.ts.map +1 -1
  112. package/dist/scan-history-renderer.js +21 -0
  113. package/dist/scan-history-renderer.js.map +1 -1
  114. package/dist/server/api.d.ts +6 -0
  115. package/dist/server/api.d.ts.map +1 -0
  116. package/dist/server/api.js +4 -0
  117. package/dist/server/api.js.map +1 -0
  118. package/dist/server/dashboard/app.css +1 -1
  119. package/dist/server/embeddings.d.ts +2 -1
  120. package/dist/server/embeddings.d.ts.map +1 -1
  121. package/dist/server/embeddings.js +8 -3
  122. package/dist/server/embeddings.js.map +1 -1
  123. package/dist/server/index.js +2 -28
  124. package/dist/server/index.js.map +1 -1
  125. package/dist/server/serve.d.ts +2 -0
  126. package/dist/server/serve.d.ts.map +1 -0
  127. package/dist/server/serve.js +28 -0
  128. package/dist/server/serve.js.map +1 -0
  129. package/dist/targets.d.ts.map +1 -1
  130. package/dist/targets.js +3 -5
  131. package/dist/targets.js.map +1 -1
  132. package/dist/version.d.ts +1 -1
  133. package/dist/version.js +1 -1
  134. package/dist/version.js.map +1 -1
  135. package/package.json +10 -5
package/README.md CHANGED
@@ -152,7 +152,10 @@ Options for `security.run(repository, options)` and
152
152
  | `signal` | `AbortSignal` to cancel a scan. |
153
153
 
154
154
  Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
155
- saved events with thread IDs and worker numbers; `ScanOptions` lists all callbacks.
155
+ saved events with thread IDs and worker numbers. Deep scans can additionally use
156
+ `onDeepProgress` for durable independent-review counts: `completed`, `active`,
157
+ and `maximum`. The maximum is a configured cap, not a percentage denominator.
158
+ `ScanOptions` lists all callbacks.
156
159
 
157
160
  `preflight` and CLI `--dry-run` check local inputs without starting Codex or
158
161
  using the network. They don't authenticate, verify model access, resolve Python,
@@ -183,6 +186,16 @@ Environment API keys apply to the current scan; only `login --with-api-key`
183
186
  saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
184
187
  Access-token environment variables are not scan API keys.
185
188
 
189
+ SDK callers can select native command authentication through
190
+ `codexOverrides.model_providers.<id>.auth` and `model_provider` (including a
191
+ selected `profile`). Scans, comparisons, and deduplication reviews preserve
192
+ that selection without requiring an API key or replacing it with a stored
193
+ login. Codex executes the helper and renews its token. Helper paths and relative
194
+ `auth.cwd` values resolve from the supplied `CODEX_HOME` (default `~/.codex`),
195
+ not the source checkout; an absolute `auth.cwd` is preserved. Comparisons and
196
+ reviews also honor the selected command provider in that home's `config.toml`.
197
+ Configuration is passed to Codex for validation, including profile support.
198
+
186
199
  For other inference providers:
187
200
 
188
201
  ```bash
@@ -286,6 +299,41 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
286
299
  `1` if a completed scan finds high or critical issues. Incomplete scans exit
287
300
  with `2`, writing available results to stdout and a coverage warning to stderr.
288
301
 
302
+ ### Generate mock scan results
303
+
304
+ Use `--mock` to populate a Standard scan with synthetic test data in seconds,
305
+ without Codex authentication or any LLM calls:
306
+
307
+ ```bash
308
+ codex-security scan /path/to/repository --mock
309
+ codex-security scan /path/to/repository --mock --output-dir /path/outside/repository/mock-results
310
+ ```
311
+
312
+ The SDK equivalent is `await security.run(repository, { mock: true })`.
313
+ Mock mode is off by default. It uses normal target validation, scan registration,
314
+ artifact finalization, reports, and local scan/finding history. Output directories,
315
+ archiving, JSON output, exports, and `--fail-on-severity` work as usual.
316
+ `--dry-run` only validates inputs; `--mock` saves a completed scan.
317
+
318
+ Each run contains 12 findings across all severity levels: eight stable findings
319
+ recur on subsequent scans of the same repository, and four have new identities
320
+ on every run. Two pairs describe the same root causes with different titles and
321
+ identities, providing inputs for deduplication testing. Mock scans skip automatic
322
+ LLM matching; existing identity-based history indexing still runs. Separate
323
+ comparison or deduplication commands retain their usual model behavior.
324
+
325
+ Titles, provenance, artifact metadata, and reports identify the results as
326
+ synthetic. Paths and code snippets are fictional and are never written into the
327
+ repository. Completion means fixture generation finished, not that the repository
328
+ was audited. Results enter the selected local state just like other scans; set
329
+ `CODEX_SECURITY_STATE_DIR` to a separate directory when creating disposable data.
330
+ Token usage is zero. `scans rerun` preserves mock mode.
331
+
332
+ Mock mode supports repository, path, and diff targets in Standard mode. It cannot
333
+ be combined with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan
334
+ prompts. Scan prompts and knowledge-base inputs do not change the fixtures, and
335
+ mock scans do not offer interactive patching.
336
+
289
337
  ### Attribute scans to end users
290
338
 
291
339
  When scanning on behalf of users, pass each user's stable hashed ID:
@@ -353,13 +401,22 @@ original IDs. Uncertain matches stay separate. `summary.json` records coverage
353
401
  and matching status; `report.md` links to component reports. Export and publish
354
402
  from the individual scan folders, not the combined summary.
355
403
 
404
+ Large comparisons use bounded batches that cover every earlier/later finding
405
+ pair. Overlapping confirmed groups are joined in code. Finding text is not
406
+ truncated; pairs above Codex's input limit leave matching incomplete.
407
+
356
408
  Use an empty output directory outside the project. Failed components don't
357
409
  stop others, but failures, incomplete coverage, or failed matching exit with
358
410
  `2`. Retry failed or incomplete components with
359
411
  `--components-file retry-components.json` and a new output directory.
412
+ The retry report covers only those components; it does not update the original
413
+ combined report.
360
414
 
361
415
  `--max-cost` applies per component, excluding planning and matching.
362
416
  `--model` and `--effort` also apply to matching; `--auth` applies throughout.
417
+ Planning and matching reject an ambient command provider that conflicts with
418
+ explicit `--auth chatgpt` or `--auth api-key`. A command provider explicitly
419
+ selected through SDK `codexOverrides` retains its authentication configuration.
363
420
  Use `--knowledge-base`, `--scan-prompt-file`, and `--post-scan-prompt-file` as for
364
421
  bulk scans.
365
422
 
@@ -469,6 +526,7 @@ restrictions.
469
526
  | Variable | Effect |
470
527
  | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
471
528
  | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
529
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
472
530
  | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
473
531
  | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
474
532
  | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
@@ -510,6 +568,27 @@ discovery has finished, the scan returns a sealed partial report without more
510
568
  model calls and lists unvalidated candidates as follow-up work. Bulk scans
511
569
  apply the limit per repository attempt.
512
570
 
571
+ For a single scan in the interactive dashboard, reaching 80% of the limit
572
+ offers a higher **total** USD limit. Enter a larger amount to approve it, or
573
+ press Enter with an empty input or Escape to keep the current limit. The scan
574
+ continues running while you decide, and the existing limit remains enforced
575
+ until the increase is saved. Increases keep the same scan and accumulated cost;
576
+ they do not restart work or extend time or discovery limits. CI, JSON/JSONL,
577
+ `--headless`, and `--verbose` scans do not offer budget increases. If usage crosses the limit
578
+ before an increase is approved, the scan still stops.
579
+
580
+ SDK callers can supply `onBudgetApproaching({ maxCostUsd, cost, signal })` and
581
+ return a higher total limit, or `undefined` to keep the current limit. The
582
+ callback runs once per limit at 80% usage without blocking tracking or
583
+ execution. Its signal aborts when the scan stops or finishes model work; late
584
+ answers are ignored. Invalid increases or failures to save them leave the
585
+ existing limit in place and report a warning. `onCost(cost, maxCostUsd)` reports
586
+ the current limit, including after an approved increase.
587
+
588
+ These amounts estimate API-equivalent model usage, not ChatGPT subscription
589
+ allowance. Post-scan prompts run after scan cost tracking ends and are outside
590
+ this limit.
591
+
513
592
  ### Bulk scans
514
593
 
515
594
  Run `gh auth login`, then `npx @openai/codex-security bulk-scan` to select
@@ -1131,6 +1210,22 @@ const result = await deduplicateScan("scan_example_001", {
1131
1210
  console.log(result.duplicateGroups);
1132
1211
  ```
1133
1212
 
1213
+ For a complete, sealed scan directory that is not registered in local scan
1214
+ history, provide the repository checkout separately:
1215
+
1216
+ ```typescript
1217
+ import { deduplicateScanDirectory } from "@openai/codex-security";
1218
+
1219
+ const result = await deduplicateScanDirectory("/path/to/completed-scan", {
1220
+ repository: "/path/to/repository",
1221
+ findingsUrl: "http://127.0.0.1:3000",
1222
+ // expectedScanId: "scan_example_001",
1223
+ // allRepositories: true,
1224
+ // signal: controller.signal,
1225
+ });
1226
+ console.log(result.duplicateGroups);
1227
+ ```
1228
+
1134
1229
  The CLI and SDK return the same result:
1135
1230
 
1136
1231
  ```json
@@ -1228,11 +1323,16 @@ reviews or group writes. A publication whose acknowledgement was lost is retried
1228
1323
  using the service's existing idempotent upsert.
1229
1324
 
1230
1325
  Each validated screening and pair review is checkpointed locally,
1231
- including DISTINCT decisions. Every SAME checkpoint retains its required
1232
- `canonicalFindingId` and generated `mergedFinding`. The merged record must satisfy
1233
- the Finding schema and preserve the canonical finding ID. Validation still happens
1234
- through `review_validator.submit_decisions`; invalid submissions are corrected in
1235
- the same review conversation, and invalid or unfinished reviews are not cached.
1326
+ including DISTINCT decisions. Screening checkpoints retain pair recommendations
1327
+ and rationales under host-assigned pair slots bound to the original records.
1328
+ Every SAME pair-review checkpoint retains its
1329
+ required `canonicalFindingId` and generated `mergedFinding`; the merged record
1330
+ must satisfy the Finding schema and preserve the canonical finding ID. Validation
1331
+ still happens through `review_validator.submit_decisions`; invalid submissions
1332
+ are corrected in the same review conversation. A completed turn without an
1333
+ accepted submission receives one corrective turn in that same conversation.
1334
+ Transport, model, cancellation, and accepted `submit_error` failures are terminal.
1335
+ Invalid or unfinished reviews are not cached.
1236
1336
 
1237
1337
  Checkpoints bind to the exact original records and ordering, approved source path,
1238
1338
  Git revision and current file contents (including ignored files), repository scope,
@@ -1262,10 +1362,10 @@ use another workflow ID for a fresh review rather than changing that saved resul
1262
1362
  neighbors are rejected.
1263
1363
  3. Independently review each nominated pair once with `gpt-5.6-sol` at `xhigh`
1264
1364
  reasoning effort. Only accepted pairs contribute to duplicate groups.
1265
- 4. Group connected findings deterministically, treating accepted duplicate
1266
- pairs as transitive: if A matches B and B matches C, all three belong to one
1267
- group. There is no additional whole-group review. A mistaken accepted pair
1268
- can therefore join otherwise distinct findings.
1365
+ 4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
1366
+ decision contradicts the resulting component. Contradicted components are
1367
+ split deterministically, preferring legal subgroups that preserve more
1368
+ accepted-pair support. There is no additional whole-group review.
1269
1369
  5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result
1270
1370
  only after the service accepts the write. An empty result requires no write.
1271
1371
 
@@ -1280,14 +1380,50 @@ and Codex state. Screening denies approval requests; final reviews use Codex's
1280
1380
  automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.
1281
1381
  Finding content never authorizes access to another target.
1282
1382
 
1383
+ Pair reviews cover exactly the two supplied findings. Linked parent tickets,
1384
+ duplicate targets, and related-ticket records are metadata, not additional
1385
+ findings to fetch or prerequisites for a verdict. An unsupplied duplicate target
1386
+ is neither automatically canonical nor an error; source-code investigation for
1387
+ the supplied pair remains allowed.
1388
+
1389
+ Incomplete supplied finding content can produce `DISTINCT` with the limitation
1390
+ explained. An execution, tool, or source-access blocker that prevents a required
1391
+ check instead uses `review_validator.submit_error` with a nonempty `reason`.
1392
+ That submission fails the review without a verdict or review checkpoint, so it
1393
+ cannot become a `DISTINCT` veto or a completed duplicate-group result. A failed
1394
+ optional lookup does not force failure or `DISTINCT` when other evidence suffices.
1395
+
1283
1396
  Decisions must arrive through the direct `review_validator.submit_decisions`
1284
1397
  tool; invalid submissions can be corrected in the same session. A final text
1285
- answer alone is insufficient. Every `SAME` decision, including screening
1286
- nominations, requires an assigned `canonicalFindingId` and a generated,
1287
- inclusive `mergedFinding`; missing or null values are rejected. Screening
1288
- canonicals must belong to the nominated pair. Sol reviews use only the complete
1289
- originals, never earlier merged findings. These review fields do not change
1290
- the command's ID-only result or stored findings.
1398
+ answer alone is insufficient. Luna screening returns a `SAME` or `DISTINCT`
1399
+ decision and rationale under each required host-assigned slot (`pair-1`,
1400
+ `pair-2`, and so on). The host binds each slot to its corresponding
1401
+ anchor-neighbor pair, so the model does not submit finding IDs. Luna does not
1402
+ select a canonical or generate a merged finding. Every
1403
+ Sol `SAME` decision requires an assigned `canonicalFindingId` and
1404
+ a generated, inclusive `mergedFinding`; missing or null values are rejected.
1405
+ Sol reviews use only the complete originals, never earlier model rationales or
1406
+ merged findings. These review fields do not change the command's ID-only result
1407
+ or stored findings.
1408
+
1409
+ Non-cancellation review failures throw `DeduplicationReviewError`. Its `metadata`
1410
+ contains only the review stage, model, failure category, attempt count, and a
1411
+ sanitized reason for diagnostics or an external support bundle; it does not
1412
+ contain findings, prompts, paths, thread IDs, or credentials.
1413
+
1414
+ If a completed turn has no accepted submission, whether it ended with text only
1415
+ or after rejected submissions, the runner sends one corrective instruction in
1416
+ the same conversation. This preserves the original assignment, source work, and
1417
+ tool feedback. Reviews are limited to two turns; `metadata.attempts` counts
1418
+ those turns (or the initial attempt if setup fails). Accepted results are not
1419
+ replayed. Cancellation, accepted `submit_error` reports, and model or transport
1420
+ failures remain terminal.
1421
+
1422
+ The SDK does not retain private review transcripts, subprocess stderr, or full
1423
+ provider/RPC error payloads, and ephemeral review state is removed after the
1424
+ session. The public metadata is a limited diagnostic summary, not a complete
1425
+ troubleshooting trace; it intentionally omits the original error cause. Private
1426
+ diagnostic retention is not currently implemented.
1291
1427
 
1292
1428
  Model calls run sequentially on the SDK/CLI host using its Codex sign-in or
1293
1429
  `OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model
@@ -1347,6 +1483,18 @@ precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using
1347
1483
  `CODEX_API_KEY` instead. Listing and empty imports do not require a key.
1348
1484
  A Codex ChatGPT login is not an embedding API credential.
1349
1485
 
1486
+ Set `CODEX_SECURITY_EMBEDDINGS_URL` to override the full embeddings endpoint URL,
1487
+ including its path and any query parameters. Unset or empty values use
1488
+ `https://api.openai.com/v1/embeddings`. Export it before `codex-security serve`,
1489
+ or set it in `.env` for Docker Compose, which passes it to the service. For example:
1490
+
1491
+ ```bash
1492
+ CODEX_SECURITY_EMBEDDINGS_URL=https://embeddings.example.com/v1/embeddings codex-security serve
1493
+ ```
1494
+
1495
+ The configured endpoint receives the finding inputs and the API key as a bearer
1496
+ token and must support the same OpenAI embeddings request and response format.
1497
+
1350
1498
  The service calls the OpenAI embeddings API with `text-embedding-3-large` and
1351
1499
  1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
1352
1500
  bundled `cl100k_base` encoding. Long inputs are split without truncation;
@@ -1376,8 +1524,8 @@ The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and
1376
1524
  `CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if
1377
1525
  changing these settings. Compose binds only to host loopback; the API has no
1378
1526
  authentication. Use an authenticated TLS proxy before sharing access. Finding
1379
- JSON is sent to `api.openai.com` over HTTPS for embeddings; the database and
1380
- generated embeddings stay in the local volume.
1527
+ JSON is sent to the configured embeddings endpoint (`api.openai.com` over HTTPS
1528
+ by default); the database and generated embeddings stay in the local volume.
1381
1529
 
1382
1530
  ### Upgrades and backups
1383
1531
 
@@ -1402,16 +1550,32 @@ migrated database.
1402
1550
 
1403
1551
  ### Running without Docker
1404
1552
 
1405
- To run locally, use Node.js and Python 3 as described in the prerequisites.
1406
- Export the API key in your shell; the server does not load `.env` automatically.
1407
- From `sdk/typescript`, install dependencies, build, and start:
1553
+ With Node.js and Python 3 installed:
1554
+
1555
+ ```bash
1556
+ npm install -g @openai/codex-security
1557
+ CODEX_SECURITY_STATE_DIR="$HOME/.codex-security-findings" codex-security serve --port 3000
1558
+ ```
1559
+
1560
+ `--port` overrides `PORT` (default: `3000`). Open
1561
+ `http://127.0.0.1:3000/dashboard`. Stop with Ctrl+C or SIGTERM.
1562
+
1563
+ Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
1564
+ Startup and listing need no key. The service does not load `.env` or authenticate
1565
+ requests; keep it on loopback or behind an authenticated TLS proxy.
1566
+
1567
+ From a source checkout's `sdk/typescript` directory:
1408
1568
 
1409
1569
  ```bash
1410
1570
  pnpm install --frozen-lockfile
1571
+ pnpm --dir ../../plugins/codex-security/mcp-app install --frozen-lockfile
1572
+ pnpm run build:plugin
1411
1573
  pnpm run build
1412
- pnpm run start:server
1574
+ node bin/codex-security.mjs serve --port 3000
1413
1575
  ```
1414
1576
 
1577
+ `pnpm run start:server` and `node dist/server/index.js` still work.
1578
+
1415
1579
  Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing
1416
1580
  `CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;
1417
1581
  without a state override, the service uses the same default state directory as
@@ -1431,11 +1595,24 @@ migration that also imports known associations from stored scan occurrences.
1431
1595
  New scan findings retain their target associations when indexed locally.
1432
1596
  The server entrypoint selects the concrete
1433
1597
  embedder and store, so either can be replaced independently.
1598
+
1599
+ For renewable embeddings credentials, import `OpenAiFindingEmbedder`,
1600
+ `SqliteFindingsStore`, and `startFindingsServer` from
1601
+ `@openai/codex-security/server`. The embedder's first argument accepts a static
1602
+ key or `() => string | Promise<string>`. It calls the callback before every
1603
+ HTTP batch, including subsequent calls to `embed`; callers own token acquisition.
1604
+ Pass `fetch` as the second argument and
1605
+ `process.env.CODEX_SECURITY_EMBEDDINGS_URL || undefined` as the third to use
1606
+ the same full endpoint URL and default as `codex-security serve`. Importing the
1607
+ server API does not start a listener.
1608
+
1434
1609
  The local workflow lives under `src/deduplication/`. `FindingDeduplicator`
1435
1610
  receives a candidate API client and a `DeduplicationReviewer`, keeping grouping
1436
1611
  separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts
1437
1612
  and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.
1438
- `deduplicateScan` validates saved scan artifacts before running the workflow.
1613
+ `deduplicateScan` validates saved scan artifacts before running the workflow;
1614
+ `deduplicateScanDirectory` performs the same validation for an explicit sealed
1615
+ scan directory without consulting local scan history.
1439
1616
  The SDK reuses the existing Codex runtime and credentials without additional
1440
1617
  runtime dependencies.
1441
1618
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-security",
3
- "version": "0.1.79",
3
+ "version": "0.1.94",
4
4
  "description": "Codex Security workflows for security scans, analysis, and investigation.",
5
5
  "author": {
6
6
  "name": "OpenAI"
@@ -14,6 +14,7 @@
14
14
  "CODEX_ELECTRON_RESOURCES_PATH",
15
15
  "CODEX_MANAGED_PACKAGE_ROOT",
16
16
  "CODEX_MCP_NODE_PATH",
17
+ "OPENAI_API_KEY",
17
18
  "OPENROUTER_API_KEY",
18
19
  "FIREWORKS_API_KEY",
19
20
  "AWS_BEARER_TOKEN_BEDROCK",
@@ -37,6 +37,16 @@ A sealed manifest records the terminal timestamp and hashes for the canonical do
37
37
 
38
38
  Only `completed` supports a completed-scan conclusion. For every stopped outcome, consumers must preserve retained findings and coverage while treating absence of findings as inconclusive.
39
39
 
40
+ ### Stopped Result Recovery
41
+
42
+ To validate and republish retained checkpoints for a failed, non-canceled workbench scan, run:
43
+
44
+ ```text
45
+ <python_command> <plugin_dir>/scripts/workbench_db.py recover-scan-results --scan-id <scan_id>
46
+ ```
47
+
48
+ Recovery can add only checkpoints that pass the stopped-scan source-integrity checks. It is not available for running, completed, or canceled scans. After cancellation, the owning continuation may retry publication only from the source set frozen at cancellation through `preserve-scan-results`; it cannot admit later checkpoints.
49
+
40
50
  ## Target Snapshots
41
51
 
42
52
  Choose the target kind based on the reviewed content, not the scan invocation:
@@ -496,7 +496,11 @@ def independent_review_progress(
496
496
  connection: sqlite3.Connection, scan_id: str
497
497
  ) -> dict[str, int | str] | None:
498
498
  run = connection.execute(
499
- "SELECT completion_sequence, phase, updated_at FROM deep_scan_runs WHERE scan_id = ?",
499
+ """
500
+ SELECT completion_sequence, phase, updated_at, max_discovery_runs
501
+ FROM deep_scan_runs
502
+ WHERE scan_id = ?
503
+ """,
500
504
  (scan_id,),
501
505
  ).fetchone()
502
506
  if run is None:
@@ -514,6 +518,7 @@ def independent_review_progress(
514
518
  return {
515
519
  "active": int(active),
516
520
  "completed": int(run["completion_sequence"]),
521
+ "maximum": int(run["max_discovery_runs"]),
517
522
  "consolidating": run["phase"] == "reducing",
518
523
  "updatedAt": str(run["updated_at"]),
519
524
  }
@@ -250,9 +250,7 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
250
250
  return normalized
251
251
 
252
252
 
253
- def _require_portable_relative_path(
254
- value: str, context: str, *, allow_dot: bool = False
255
- ) -> str:
253
+ def _require_portable_relative_path(value: str, context: str, *, allow_dot: bool = False) -> str:
256
254
  normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
257
255
  if any(_windows_unsafe_path_component(part) for part in value.split("/")):
258
256
  raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
@@ -288,10 +286,7 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
288
286
  resolved_parent.relative_to(scan_dir)
289
287
  except (OSError, RuntimeError, ValueError) as exc:
290
288
  raise ContractError(f"{relative_path}: expected a path inside the scan directory") from exc
291
- if (
292
- os.path.normcase(resolved_parent) != os.path.normcase(path.parent)
293
- or path.is_symlink()
294
- ):
289
+ if os.path.normcase(resolved_parent) != os.path.normcase(path.parent) or path.is_symlink():
295
290
  raise ContractError(
296
291
  f"{relative_path}: expected a non-symlink path inside the scan directory"
297
292
  )
@@ -341,10 +336,7 @@ def _open_verified_scan_directory(
341
336
  try:
342
337
  expected = scan_dir.lstat()
343
338
  observed_identity = (expected.st_dev, expected.st_ino)
344
- if (
345
- expected_root_identity is not None
346
- and observed_identity != expected_root_identity
347
- ):
339
+ if expected_root_identity is not None and observed_identity != expected_root_identity:
348
340
  raise ContractError("scan directory: changed after artifact restoration setup")
349
341
  canonical = _require_scan_directory(scan_dir)
350
342
  descriptor = os.open(
@@ -352,14 +344,11 @@ def _open_verified_scan_directory(
352
344
  os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
353
345
  )
354
346
  except OSError as exc:
355
- raise ContractError(
356
- "scan directory: expected an existing non-symlink directory"
357
- ) from exc
347
+ raise ContractError("scan directory: expected an existing non-symlink directory") from exc
358
348
  opened = os.fstat(descriptor)
359
349
  opened_identity = (opened.st_dev, opened.st_ino)
360
350
  if opened_identity != observed_identity or (
361
- expected_root_identity is not None
362
- and opened_identity != expected_root_identity
351
+ expected_root_identity is not None and opened_identity != expected_root_identity
363
352
  ):
364
353
  os.close(descriptor)
365
354
  raise ContractError("scan directory: changed while it was being opened")
@@ -372,9 +361,7 @@ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
372
361
  scan_dir = _require_scan_directory(scan_dir)
373
362
  if not _descriptor_relative_writes_available():
374
363
  if not _is_windows():
375
- raise ContractError(
376
- "scan-local output requires descriptor-relative file operations"
377
- )
364
+ raise ContractError("scan-local output requires descriptor-relative file operations")
378
365
  return _windows_scan_local_files().scan_root_identity(scan_dir)
379
366
  descriptor = _open_verified_scan_directory(scan_dir)
380
367
  try:
@@ -584,9 +571,7 @@ def write_scan_local_bytes(
584
571
  try:
585
572
  existing_fd = os.open(
586
573
  parts[-1],
587
- os.O_RDONLY
588
- | getattr(os, "O_NOFOLLOW", 0)
589
- | getattr(os, "O_NONBLOCK", 0),
574
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
590
575
  dir_fd=parent_fd,
591
576
  )
592
577
  except OSError as exc:
@@ -596,20 +581,13 @@ def write_scan_local_bytes(
596
581
  try:
597
582
  opened = os.fstat(existing_fd)
598
583
  if not stat.S_ISREG(opened.st_mode):
599
- raise ContractError(
600
- f"{relative_path}: expected a regular non-symlink file"
601
- )
584
+ raise ContractError(f"{relative_path}: expected a regular non-symlink file")
602
585
  if (opened.st_dev, opened.st_ino) != (
603
586
  metadata.st_dev,
604
587
  metadata.st_ino,
605
588
  ):
606
- raise ContractError(
607
- f"{relative_path}: changed while it was being opened"
608
- )
609
- if (
610
- expected_root_identity is not None
611
- and opened.st_size == len(payload)
612
- ):
589
+ raise ContractError(f"{relative_path}: changed while it was being opened")
590
+ if expected_root_identity is not None and opened.st_size == len(payload):
613
591
  try:
614
592
  with os.fdopen(existing_fd, "rb") as handle:
615
593
  existing_fd = -1
@@ -857,9 +835,9 @@ def _recover_unsealed_findings(
857
835
  try:
858
836
  if not isinstance(finding, dict):
859
837
  raise ContractError(f"{context}: expected an object")
860
- compatible_findings = _legacy_sealed_findings_for_validation(
861
- {"findings": [finding]}
862
- )["findings"]
838
+ compatible_findings = _legacy_sealed_findings_for_validation({"findings": [finding]})[
839
+ "findings"
840
+ ]
863
841
  compatible_finding = compatible_findings[0]
864
842
  normalized_legacy_details = compatible_finding != finding
865
843
  finding = compatible_finding
@@ -870,9 +848,7 @@ def _recover_unsealed_findings(
870
848
  ]
871
849
  if "instance" in identity:
872
850
  fields.append((identity, "instance", f"{context}.identity", "instance"))
873
- normalized_fields = (
874
- ["legacy finding details"] if normalized_legacy_details else []
875
- )
851
+ normalized_fields = ["legacy finding details"] if normalized_legacy_details else []
876
852
  for parent, field, field_context, label in fields:
877
853
  value = _require_str(parent, field, field_context)
878
854
  if SLUG_RE.fullmatch(value):
@@ -1649,10 +1625,7 @@ def _validate_schema_node(
1649
1625
  raise ContractError(f"{context}: array has too many items")
1650
1626
  if schema.get("uniqueItems") is True:
1651
1627
  for index, item in enumerate(value):
1652
- if any(
1653
- _schema_values_equal(item, candidate)
1654
- for candidate in value[:index]
1655
- ):
1628
+ if any(_schema_values_equal(item, candidate) for candidate in value[:index]):
1656
1629
  raise ContractError(f"{context}: array items must be unique")
1657
1630
  contains = schema.get("contains")
1658
1631
  if isinstance(contains, dict):
@@ -1671,9 +1644,7 @@ def _validate_schema_node(
1671
1644
  item_schema = schema.get("items")
1672
1645
  if isinstance(item_schema, dict):
1673
1646
  for index, item in enumerate(value):
1674
- _validate_schema_node(
1675
- item, item_schema, f"{context}[{index}]", root_schema
1676
- )
1647
+ _validate_schema_node(item, item_schema, f"{context}[{index}]", root_schema)
1677
1648
  if isinstance(value, dict):
1678
1649
  for item_schema in schema.get("allOf", []):
1679
1650
  _validate_schema_node(value, item_schema, context, root_schema)
@@ -1697,9 +1668,7 @@ def _validate_schema_node(
1697
1668
  for key, item in value.items():
1698
1669
  item_schema = properties.get(key)
1699
1670
  if isinstance(item_schema, dict):
1700
- _validate_schema_node(
1701
- item, item_schema, f"{context}.{key}", root_schema
1702
- )
1671
+ _validate_schema_node(item, item_schema, f"{context}.{key}", root_schema)
1703
1672
  elif additional_properties is False:
1704
1673
  raise ContractError(f"{context}.{key}: unexpected schema property")
1705
1674
  elif isinstance(additional_properties, dict):
@@ -1716,22 +1685,16 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
1716
1685
  _validate_schema_node(payload, schema, schema_path.stem, schema)
1717
1686
 
1718
1687
 
1719
- def _filter_unknown_legacy_evidence_refs(
1720
- section: dict[str, Any], evidence_ids: set[str]
1721
- ) -> None:
1688
+ def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
1722
1689
  for refs_field in ("evidenceRefs", "evidence_refs"):
1723
1690
  refs = section.get(refs_field)
1724
1691
  if isinstance(refs, list):
1725
1692
  section[refs_field] = [
1726
- ref
1727
- for ref in refs
1728
- if isinstance(ref, str) and ref.strip() and ref in evidence_ids
1693
+ ref for ref in refs if isinstance(ref, str) and ref.strip() and ref in evidence_ids
1729
1694
  ]
1730
1695
 
1731
1696
 
1732
- def _normalize_legacy_string_list_fields(
1733
- section: dict[str, Any], fields: tuple[str, ...]
1734
- ) -> None:
1697
+ def _normalize_legacy_string_list_fields(section: dict[str, Any], fields: tuple[str, ...]) -> None:
1735
1698
  for field in fields:
1736
1699
  if field not in section:
1737
1700
  continue
@@ -1739,9 +1702,7 @@ def _normalize_legacy_string_list_fields(
1739
1702
  if isinstance(value, str):
1740
1703
  normalized = [value] if value.strip() else []
1741
1704
  elif isinstance(value, list):
1742
- normalized = [
1743
- item for item in value if isinstance(item, str) and item.strip()
1744
- ]
1705
+ normalized = [item for item in value if isinstance(item, str) and item.strip()]
1745
1706
  else:
1746
1707
  normalized = []
1747
1708
  if normalized:
@@ -1754,9 +1715,7 @@ def _remove_unsupported_legacy_scalar_fields(
1754
1715
  section: dict[str, Any], fields: tuple[str, ...]
1755
1716
  ) -> None:
1756
1717
  for field in fields:
1757
- if field in section and (
1758
- not isinstance(section[field], str) or section[field] == ""
1759
- ):
1718
+ if field in section and (not isinstance(section[field], str) or section[field] == ""):
1760
1719
  section.pop(field)
1761
1720
 
1762
1721
 
@@ -1773,9 +1732,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1773
1732
  canonical_evidence_ids = {
1774
1733
  evidence["id"]
1775
1734
  for evidence in canonical_evidence
1776
- if isinstance(evidence, dict)
1777
- and isinstance(evidence.get("id"), str)
1778
- and evidence["id"]
1735
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1779
1736
  }
1780
1737
  legacy_evidence = finding.get("code_evidence")
1781
1738
  if isinstance(legacy_evidence, list):
@@ -1807,9 +1764,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1807
1764
  evidence_ids = canonical_evidence_ids | {
1808
1765
  evidence["id"]
1809
1766
  for evidence in compatible_legacy_evidence
1810
- if isinstance(evidence, dict)
1811
- and isinstance(evidence.get("id"), str)
1812
- and evidence["id"]
1767
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1813
1768
  }
1814
1769
  for section_name, list_fields in (
1815
1770
  ("rootCause", ("evidenceRefs", "evidence_refs")),
@@ -1891,12 +1846,8 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1891
1846
  for field in ("impact", "likelihood"):
1892
1847
  detail = attack_path.get(field)
1893
1848
  if isinstance(detail, dict):
1894
- _remove_unsupported_legacy_scalar_fields(
1895
- detail, ("level", "rationale", "why")
1896
- )
1897
- elif detail is not None and (
1898
- not isinstance(detail, str) or detail == ""
1899
- ):
1849
+ _remove_unsupported_legacy_scalar_fields(detail, ("level", "rationale", "why"))
1850
+ elif detail is not None and (not isinstance(detail, str) or detail == ""):
1900
1851
  attack_path.pop(field)
1901
1852
  return compatible
1902
1853
 
@@ -2805,9 +2756,7 @@ def _prepare_scan_finalization(
2805
2756
  _validate_sealed_coverage_receipts(scan, coverage)
2806
2757
  _validate_manifest(manifest)
2807
2758
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2808
- validate_against_schema(
2809
- findings_for_validation, schema_dir / "findings.schema.json"
2810
- )
2759
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2811
2760
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2812
2761
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2813
2762
  _validate_report_output_paths(scan_dir)