@openai/codex-security 0.10.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/_bundled_plugin/.mcp.json +1 -0
  2. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  3. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  4. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  5. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  6. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  7. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  8. package/_bundled_plugin/references/access-advisory.md +1 -1
  9. package/_bundled_plugin/references/threat-model.md +1 -0
  10. package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -0
  11. package/_bundled_plugin/scripts/finalize_scan_contract.py +18 -6
  12. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +2 -0
  13. package/_bundled_plugin/scripts/workbench_db.py +16 -54
  14. package/_bundled_plugin/scripts/workbench_scan_history.py +23 -28
  15. package/_bundled_plugin/scripts/workbench_scan_start.py +65 -2
  16. package/_bundled_plugin/scripts/workbench_source_scopes.py +8 -0
  17. package/_bundled_plugin/scripts/workbench_target.py +17 -3
  18. package/_bundled_plugin/shared/workbench-history-repairs.json +5 -1
  19. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -2
  20. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +2 -2
  21. package/_bundled_plugin/skills/publish-findings/SKILL.md +3 -1
  22. package/dist/api.d.ts +1 -0
  23. package/dist/api.d.ts.map +1 -1
  24. package/dist/api.js +23 -4
  25. package/dist/api.js.map +1 -1
  26. package/dist/classify-severity-diagnostics.d.ts +10 -0
  27. package/dist/classify-severity-diagnostics.d.ts.map +1 -0
  28. package/dist/classify-severity-diagnostics.js +57 -0
  29. package/dist/classify-severity-diagnostics.js.map +1 -0
  30. package/dist/classify-severity-records.d.ts +4 -0
  31. package/dist/classify-severity-records.d.ts.map +1 -1
  32. package/dist/classify-severity-records.js +35 -8
  33. package/dist/classify-severity-records.js.map +1 -1
  34. package/dist/cli.d.ts +3 -0
  35. package/dist/cli.d.ts.map +1 -1
  36. package/dist/cli.js +99 -11
  37. package/dist/cli.js.map +1 -1
  38. package/dist/component-plan.d.ts.map +1 -1
  39. package/dist/component-plan.js +3 -3
  40. package/dist/component-plan.js.map +1 -1
  41. package/dist/continuum-aws.d.ts +6 -0
  42. package/dist/continuum-aws.d.ts.map +1 -0
  43. package/dist/continuum-aws.js +202 -0
  44. package/dist/continuum-aws.js.map +1 -0
  45. package/dist/continuum-collector.d.ts +44 -0
  46. package/dist/continuum-collector.d.ts.map +1 -0
  47. package/dist/continuum-collector.js +266 -0
  48. package/dist/continuum-collector.js.map +1 -0
  49. package/dist/continuum-findings.d.ts +31 -2
  50. package/dist/continuum-findings.d.ts.map +1 -1
  51. package/dist/continuum-findings.js +440 -64
  52. package/dist/continuum-findings.js.map +1 -1
  53. package/dist/contract.d.ts +1 -0
  54. package/dist/contract.d.ts.map +1 -1
  55. package/dist/contract.js +3 -0
  56. package/dist/contract.js.map +1 -1
  57. package/dist/crowdstrike-findings.d.ts +7 -0
  58. package/dist/crowdstrike-findings.d.ts.map +1 -0
  59. package/dist/crowdstrike-findings.js +210 -0
  60. package/dist/crowdstrike-findings.js.map +1 -0
  61. package/dist/external-findings-local.d.ts.map +1 -1
  62. package/dist/external-findings-local.js +26 -8
  63. package/dist/external-findings-local.js.map +1 -1
  64. package/dist/external-findings-publish.d.ts.map +1 -1
  65. package/dist/external-findings-publish.js +5 -1
  66. package/dist/external-findings-publish.js.map +1 -1
  67. package/dist/external-findings-read.d.ts +10 -2
  68. package/dist/external-findings-read.d.ts.map +1 -1
  69. package/dist/external-findings-read.js +26 -3
  70. package/dist/external-findings-read.js.map +1 -1
  71. package/dist/external-import-contract.d.ts +3 -0
  72. package/dist/external-import-contract.d.ts.map +1 -1
  73. package/dist/external-import-contract.js +6 -1
  74. package/dist/external-import-contract.js.map +1 -1
  75. package/dist/host-protocol.d.ts +6 -0
  76. package/dist/host-protocol.d.ts.map +1 -1
  77. package/dist/host-protocol.js +11 -1
  78. package/dist/host-protocol.js.map +1 -1
  79. package/dist/host-records-protocol.d.ts +2 -0
  80. package/dist/host-records-protocol.d.ts.map +1 -1
  81. package/dist/host-records-protocol.js +4 -0
  82. package/dist/host-records-protocol.js.map +1 -1
  83. package/dist/index.d.ts +2 -1
  84. package/dist/index.d.ts.map +1 -1
  85. package/dist/index.js +1 -0
  86. package/dist/index.js.map +1 -1
  87. package/dist/multiscan.d.ts.map +1 -1
  88. package/dist/multiscan.js +4 -2
  89. package/dist/multiscan.js.map +1 -1
  90. package/dist/project-config-schema.d.ts +2 -0
  91. package/dist/project-config-schema.d.ts.map +1 -1
  92. package/dist/project-config-schema.js +1 -0
  93. package/dist/project-config-schema.js.map +1 -1
  94. package/dist/project-config.d.ts +1 -0
  95. package/dist/project-config.d.ts.map +1 -1
  96. package/dist/project-config.js +3 -0
  97. package/dist/project-config.js.map +1 -1
  98. package/dist/runtime.d.ts.map +1 -1
  99. package/dist/runtime.js +4 -0
  100. package/dist/runtime.js.map +1 -1
  101. package/dist/scan-comparison.d.ts +20 -2
  102. package/dist/scan-comparison.d.ts.map +1 -1
  103. package/dist/scan-comparison.js +20 -3
  104. package/dist/scan-comparison.js.map +1 -1
  105. package/dist/scan-settings.d.ts +1 -0
  106. package/dist/scan-settings.d.ts.map +1 -1
  107. package/dist/scan-settings.js +1 -0
  108. package/dist/scan-settings.js.map +1 -1
  109. package/dist/severity-review.d.ts.map +1 -1
  110. package/dist/severity-review.js +1 -0
  111. package/dist/severity-review.js.map +1 -1
  112. package/dist/stored-finding-projection.d.ts.map +1 -1
  113. package/dist/stored-finding-projection.js +30 -5
  114. package/dist/stored-finding-projection.js.map +1 -1
  115. package/dist/targets.d.ts +2 -0
  116. package/dist/targets.d.ts.map +1 -1
  117. package/dist/targets.js +27 -0
  118. package/dist/targets.js.map +1 -1
  119. package/dist/trusted-executable.d.ts +1 -0
  120. package/dist/trusted-executable.d.ts.map +1 -1
  121. package/dist/trusted-executable.js +11 -3
  122. package/dist/trusted-executable.js.map +1 -1
  123. package/dist/value.js +3 -1
  124. package/dist/value.js.map +1 -1
  125. package/docs/classify-severity-records.md +30 -0
  126. package/docs/cli.md +164 -18
  127. package/docs/sdk.md +23 -8
  128. package/package.json +7 -2
  129. package/schemas/project-config.schema.json +5 -0
  130. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +0 -224
package/docs/cli.md CHANGED
@@ -264,6 +264,27 @@ comparisons, and deduplication preserve that selection. Relative helper paths an
264
264
  `auth.cwd` resolve from `CODEX_HOME` (default `~/.codex`). Comparisons and reviews
265
265
  also honor the selected command provider in that home's `config.toml`.
266
266
 
267
+ For OrcaRouter, save this profile in `$CODEX_HOME/orcarouter.config.toml`
268
+ (default `~/.codex/orcarouter.config.toml`), then run
269
+ `codex-security scan . --codex 'profile="orcarouter"'`. Sign in to the 1Password CLI and
270
+ replace the secret reference below with the one for your router key.
271
+
272
+ ```toml
273
+ model = "orcarouter/fusion"
274
+ model_provider = "orcarouter"
275
+
276
+ [model_providers.orcarouter]
277
+ name = "OrcaRouter"
278
+ base_url = "https://api.orcarouter.ai/v1"
279
+ wire_api = "responses"
280
+
281
+ [model_providers.orcarouter.auth]
282
+ command = "op"
283
+ args = ["read", "op://Private/OrcaRouter/credential"]
284
+ ```
285
+
286
+ This profile was tested up to the outgoing Responses request using a local service.
287
+
267
288
  For other providers, set their key and select a model the provider supports:
268
289
 
269
290
  ```bash
@@ -277,6 +298,88 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
277
298
  codex-security scan . --provider cheaperinference --model gpt-5.4
278
299
  ```
279
300
 
301
+ For Opper, save this profile in `$CODEX_HOME/opper.config.toml`
302
+ (default `~/.codex/opper.config.toml`). Opper requires `web_search = "disabled"`.
303
+
304
+ ```toml
305
+ model_provider = "opper"
306
+ model = "anthropic/claude-sonnet-4-6"
307
+ web_search = "disabled"
308
+
309
+ [model_providers.opper]
310
+ name = "Opper"
311
+ base_url = "https://api.opper.ai/v3/compat"
312
+ wire_api = "responses"
313
+ env_key = "OPPER_API_KEY"
314
+ ```
315
+
316
+ Set `OPPER_API_KEY` in your environment and run
317
+ `codex-security scan . --codex 'profile="opper"'`. Choose a model that supports
318
+ tool calling and streaming. Verification covered profile loading and a request to
319
+ a local Responses endpoint.
320
+ See [Opper's Codex setup guide](https://docs.opper.ai/integrations/coding-agents/codex).
321
+
322
+ ### xAI Responses API through a local gateway
323
+
324
+ Codex 0.167.0 sends collaboration and Codex Security MCP tools as `namespace`
325
+ declarations. A direct scan against xAI can pass `--dry-run` and then fail with
326
+ HTTP 422 on the first model request. CLIProxyAPI's xAI adapter exposes each
327
+ namespace member to xAI as a plain function and restores the namespace when
328
+ Codex receives a tool call. Both connections use the Responses API.
329
+ [Direct xAI provider support](https://github.com/openai/codex-security/issues/2412)
330
+
331
+ Install CLIProxyAPI v8.0.59 and save this gateway config outside the scanned
332
+ repository in a file readable only by the gateway user. Replace the placeholders
333
+ with a private client key of your choice and your xAI API key.
334
+ [CLIProxyAPI release](https://github.com/router-for-me/CLIProxyAPI/releases/tag/v8.0.59)
335
+
336
+ ```yaml
337
+ config-version: 8
338
+ server:
339
+ host: "127.0.0.1"
340
+ port: 8317
341
+ access:
342
+ api-keys: ["<gateway-client-key>"]
343
+ api-keys:
344
+ xai:
345
+ - name: scan
346
+ base-url: "https://api.x.ai/v1"
347
+ models:
348
+ - name: "grok-4.7"
349
+ keys:
350
+ - api-key: "<xai-api-key>"
351
+ oauth:
352
+ auth-dir: "~/.cli-proxy-api-xai"
353
+ ```
354
+
355
+ Start the gateway in one shell.
356
+
357
+ ```bash
358
+ cli-proxy-api -config /path/to/private/config.yaml -local-model
359
+ ```
360
+
361
+ In a second shell on the same machine or in the same container, set
362
+ `CODEX_API_KEY` to the client key from `access.api-keys` and run the scan.
363
+
364
+ ```bash
365
+ codex-security scan . --auth api-key --model grok-4.7 --effort low \
366
+ --codex "model_provider='xai'" \
367
+ --codex "model_providers.xai.name='xAI'" \
368
+ --codex "model_providers.xai.base_url='http://127.0.0.1:8317/v1'" \
369
+ --codex "model_providers.xai.wire_api='responses'" \
370
+ --codex "model_providers.xai.env_key='CODEX_API_KEY'" \
371
+ --codex 'features.multi_agent_v2.max_concurrent_threads_per_session=1'
372
+ ```
373
+
374
+ The one-thread setting keeps Standard scans from spawning subagents. Without it,
375
+ the gateway can forward a subagent's `agent_message` on a later request, which
376
+ xAI rejects with HTTP 422. A contributor completed a live Standard scan with
377
+ this setting. Deep Scan workers have separate concurrency settings and remain
378
+ unverified with this gateway.
379
+
380
+ The SDK has no built-in price for `grok-4.7`, so it rejects `--max-cost` for this
381
+ model before starting a scan.
382
+
280
383
  ### Hugging Face compatibility
281
384
 
282
385
  In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
@@ -508,13 +611,21 @@ callback, questions remain unresolved.
508
611
  ```bash
509
612
  codex-security scan .
510
613
  codex-security scan . --path src --path tests
614
+ codex-security scan . --exclude-path examples/
511
615
  codex-security scan . --diff origin/main --json
512
616
  codex-security scan . --working-tree
513
617
  codex-security scan . --owner-suggestions
514
618
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
515
619
  ```
516
620
 
517
- `--path` selects files or directories. The scan summary and saved scan details
621
+ `--path` selects files or directories. Repeat `--exclude-path` to exclude literal
622
+ repository-relative files or directories, including all descendants of a directory.
623
+ Exclusions take precedence over `--path`, also apply to diff and Deep scans, and
624
+ default to none. For persistent exclusions, set `scan.exclude_paths` in a selected
625
+ project config. CLI exclusions replace that configured list. Excluded files remain
626
+ readable as context, but findings whose locations are all excluded are removed
627
+ from scan results.
628
+ The scan summary and saved scan details
518
629
  show requested paths and exclusions. `coverage.deferred` records unfinished
519
630
  requested work separately from optional `coverage.openQuestions` follow-up.
520
631
  Human-readable output quotes ambiguous paths, while JSON retains their original strings.
@@ -1434,10 +1545,10 @@ Use `-c FILE` for shared settings; CSV mode/scope override file values.
1434
1545
  `--post-scan-prompt-file` runs a follow-up even after failure, but not after
1435
1546
  cancellation or a cost stop.
1436
1547
 
1437
- Concurrency defaults to four repositories. `--max-attempts` defaults to one
1438
- attempt per pending repository per invocation. Repeating the command continues
1439
- the campaign, skips completed results, and starts pending attempts. Occupied
1440
- attempt directories stop that repository and suggest `--recover`.
1548
+ By default, `bulk-scan` runs up to four repositories concurrently and tries each
1549
+ unfinished CSV row once per run. With `--max-attempts 2`, a row that fails
1550
+ attempts 1 and 2 gets up to two more attempts (3 and 4) on the next run.
1551
+ An occupied attempt directory stops that row and prompts for `--recover`.
1441
1552
  If an ordinary attempt finds its checkout path already occupied, it stops before
1442
1553
  fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
1443
1554
  existing checkout before an ordinary retry.
@@ -1480,7 +1591,7 @@ failed or interrupted attempt:
1480
1591
  revision, preserving old artifacts and checkouts.
1481
1592
 
1482
1593
  Each nonempty committed line in `results.jsonl` must be valid JSON with a string
1483
- task ID and a positive safe integer attempt number. If a line fails these checks,
1594
+ task ID from the manifest and a positive safe integer attempt number. For an invalid line,
1484
1595
  the command reports its line number and preserves the ledger. Restore a complete
1485
1596
  ledger backup that includes every committed attempt, or start a separate campaign
1486
1597
  in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
@@ -1556,13 +1667,13 @@ Supply the validation prompt again when rerunning.
1556
1667
 
1557
1668
  Choose the command by what you want to keep. [Scanner guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) list the accepted vendor formats.
1558
1669
 
1559
- | Input and goal | Command | Service contacted | Where to find the result |
1560
- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1561
- | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1562
- | Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
1563
- | Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
1564
- | Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
1565
- | Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
1670
+ | Input and goal | Command | Service contacted | Where to find the result |
1671
+ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1672
+ | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1673
+ | Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
1674
+ | Collect upstream records to a file | `import continuum`, `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
1675
+ | Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
1676
+ | Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
1566
1677
 
1567
1678
  For `publish findings`, `--to` is required. With `--to local`, `--repository`
1568
1679
  takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
@@ -1579,8 +1690,13 @@ codex-security publish findings /private/path/endor-findings.json --provider end
1579
1690
  After reviewing the findings and exclusions, rerun the command without
1580
1691
  `--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
1581
1692
 
1693
+ When you pass `--source-repository-url` to `publish findings`, the command warns
1694
+ on stderr to verify that every finding belongs to the repository you specify.
1695
+
1582
1696
  For Tenable One Code Repository findings, use `--provider tenable --to local` and set `--source-repository-url` to the checkout’s verified HTTPS remote. [Tenable export and import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/tenable.md)
1583
1697
 
1698
+ For CrowdStrike FCS CLI 4.x IaC reports, use `--provider crowdstrike --to local` and select the directory where FCS ran with `--repository`. It does not need to be a Git checkout, but each scanned file must be unchanged since the scan. Add `--source-repository-url` to record the repository; it must match a fetch remote when the directory is a Git checkout. A `git::https://` report names its repository, and a different `--source-repository-url` stops the import. [CrowdStrike import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/crowdstrike.md)
1699
+
1584
1700
  Local readback uses `findings imported [PATH]`. The path defaults to the current
1585
1701
  directory. Each imported record starts as `not_assessed`. Unknown revisions and
1586
1702
  locations stay unknown. Repository-scoped sources are checked against comparable
@@ -1611,6 +1727,33 @@ Use `--provider endor` for one Endor project and context. The
1611
1727
  [Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
1612
1728
  SARIF compatibility, and the local preview.
1613
1729
 
1730
+ ## Collect AWS Continuum issues
1731
+
1732
+ `import continuum ENVIRONMENT_ID --format json` writes one report to standard
1733
+ output after collecting every issue page and fetching each issue's linked
1734
+ findings, prevalidation signals (`EVIDENCE`), and validation results
1735
+ (`VALIDATION_EVIDENCE`). Install AWS CLI v2.38.5 or later outside the checkout.
1736
+ The command requires exactly one configured Git repository and records it in the
1737
+ report. It collects patches when Git is the only source.
1738
+ S3 sources are allowed alongside that repository.
1739
+ Collection covers the whole environment. Pass the short
1740
+ Continuum environment ID. Optional
1741
+ `--aws-profile PROFILE` and `--aws-region REGION` override the AWS CLI's
1742
+ credential and Region selection. Preview and import the report separately
1743
+ with `publish findings FILE --provider continuum`. Pass
1744
+ `--source-repository-url URL` when the report has no saved repository URL.
1745
+
1746
+ For one finding, its matching validation evidence, and its generated patches, add `--finding-id FINDING_ID` and
1747
+ `--source-root CHECKOUT` with the absolute checkout path. The CLI uses
1748
+ `GetEnvironment` to verify that the environment has exactly one Git repository
1749
+ and no S3 sources before including unnamed patches. Pass
1750
+ `--repository-name AWS_SOURCE_NAME` for other environments to keep patches
1751
+ with that exact AWS source name. Validation is matched by AWS finding ID. When a
1752
+ validation artifact has no per-finding breakdown, the CLI uses `GetCodeIssue` to
1753
+ check that the issue covers just the selected finding. This mode accepts the same AWS profile and
1754
+ Region overrides and writes the finding-based JSON format for `publish findings`.
1755
+ [Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
1756
+
1614
1757
  ## Import SonarQube Cloud issues
1615
1758
 
1616
1759
  `import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
@@ -1918,6 +2061,7 @@ codex-security classify-severity --scan-dir /path/to/completed-scan --json
1918
2061
  ```
1919
2062
 
1920
2063
  For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
2064
+ A records host can opt in to the CLI’s structured diagnostic records on its existing JSON-RPC connection. See the [records diagnostic protocol](classify-severity-records.md#cli-diagnostic-records).
1921
2065
  The [records protocol](classify-severity-records.md) accepts immutable Markdown and
1922
2066
  report snapshots and delegates model execution to the host.
1923
2067
 
@@ -2304,6 +2448,7 @@ Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the mod
2304
2448
  and save its matching decisions. Pass `--force` to recompute saved matches.
2305
2449
  The older `scans match BEFORE AFTER` spelling is also supported.
2306
2450
  Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
2451
+ The SDK accepts matching plans with inline findings and asks compatible workbenches to send each scan’s findings once.
2307
2452
  Comparisons classify findings as new, persisting, reopened, not observed, resolved,
2308
2453
  or unknown. An absent finding in the later scope is not observed; absence alone
2309
2454
  does not verify remediation. A finding is resolved only after it was explicitly
@@ -2314,11 +2459,12 @@ One comparison ID is compared with the latest completed scan.
2314
2459
  codex-security scans match --all --force --model gpt-6.1-sol --effort high
2315
2460
  ```
2316
2461
 
2317
- When a saved Standard scan and a Deep scan have the same recorded target,
2318
- revision, and snapshot digest, matching flags findings that have different
2319
- anchors but share a unique rule, first displayed source range, and optional
2320
- instance. Matching preserves the case of saved paths. Codex can request the
2321
- saved evidence to distinguish separate causes at that site. Automatic matching
2462
+ Standard and Deep scans can identify matching candidates in a single target or
2463
+ corresponding paths in linked worktrees with the same saved repository
2464
+ generation. When the revision and snapshot digest agree, matching flags findings
2465
+ with different anchors that share a unique rule, first displayed source range,
2466
+ and optional instance. Matching preserves the case of saved paths. Codex can
2467
+ request the saved evidence to distinguish separate causes at that site. Automatic matching
2322
2468
  under a cost limit keeps its single comparison call.
2323
2469
 
2324
2470
  Only high-confidence root-cause matches are grouped. Uncertain and related
package/docs/sdk.md CHANGED
@@ -174,6 +174,7 @@ assume an open `CodexSecurity` client named `security`; close it when finished.
174
174
  ```ts
175
175
  const result = await security.run("/path/to/repository", {
176
176
  target: ["src", "tests"],
177
+ excludePaths: ["src/examples"],
177
178
  knowledgeBasePaths: ["/path/to/architecture.md"],
178
179
  scanPrompt: "Focus on authentication and authorization.",
179
180
  outputDir: "/path/outside/repository/results",
@@ -181,6 +182,10 @@ const result = await security.run("/path/to/repository", {
181
182
  });
182
183
  ```
183
184
 
185
+ `excludePaths` takes literal repository-relative files or directories. A directory
186
+ excludes all descendants, and exclusions take precedence over `target`. The default
187
+ is no exclusions. Requested exclusions are recorded in `result.manifest.scan.scope.excludePaths`.
188
+
184
189
  | Option | Use |
185
190
  | ------------------------------------------- | ------------------------------------------------------------------------------ |
186
191
  | `target` | Whole repository (default), repository-relative paths, or a `DiffTarget`. |
@@ -308,6 +313,10 @@ console.log(plan);
308
313
  `preflight()` checks local inputs without starting Codex or using the network. The returned `stateDirectory` identifies the checked storage root, including when the final scan directory will be allocated automatically.
309
314
  It does not verify credentials, model access, Python, or the plugin. The CLI
310
315
  equivalent is `scan --dry-run`.
316
+ Neither preflight starts a Deep Scan worker or executes a command under its
317
+ generated permissions, so neither qualifies the worker sandbox. See [Deep Scan
318
+ sandbox qualification](../../../docs/project-configuration.md#deep-scan-sandbox-qualification)
319
+ for the boundary and the limits of what these checks establish.
311
320
 
312
321
  ### Set investigation time
313
322
 
@@ -767,16 +776,22 @@ Omit `issueKeys` to collect the project's open security issues. An empty list is
767
776
  If you know the source repository, pass its Git URL in `options.sourceRepositoryUrl`
768
777
  to check the Sonar binding before fetching issues.
769
778
 
770
- For AWS Continuum, pass a collector capture, native detail, array of selected
771
- details or captures, or complete list response to `readContinuumFindings` (file
772
- path) or `normalizeContinuumFindings` (parsed JSON). The second argument is
773
- the verified Git repository URL. Pass `"local"` as the third argument to retain
774
- full patch contents locally. The default Cloud projection records
775
- `contentOmitted: "cloud_evidence_limit"` on patches whose contents exceed the
776
- finding evidence budget. Read the native finding at `evidence.source_data.finding`
777
- and its available patches at `evidence.source_data.patches`.
779
+ For AWS Continuum, use `readContinuumFindings(path, sourceRepositoryUrl)` with a
780
+ saved issue export, single-finding capture, or native finding response. Use
781
+ `normalizeContinuumFindings(input, sourceRepositoryUrl)` with parsed JSON.
782
+ Issue exports with a saved repository URL can omit the second argument.
783
+ For other reports, pass the verified source repository URL.
778
784
  [Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
779
785
 
786
+ Pass `"local"` as the third argument to retain full patch contents in collector
787
+ captures. The Cloud projection records `contentOmitted: "cloud_evidence_limit"`
788
+ when the patch contents exceed the evidence budget. Available patches are in
789
+ `evidence.source_data.patches`. Single-finding captures provide their matching
790
+ validation artifacts in `evidence.source_data.evidence_artifacts`. The local
791
+ projection retains each validation body, and Cloud marks omitted bodies with
792
+ the same `contentOmitted` value. When even the validation descriptors exceed
793
+ the budget, Cloud omits them and preserves the finding and its fitting patches.
794
+
780
795
  For a saved Checkmarx One CLI JSON or CxSAST XML report, use
781
796
  `readCheckmarxFindings(path, sourceRepositoryUrl, "local")` to inspect its evidence.
782
797
  To prepare a local import, pass `provider: "checkmarx"` and the verified
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openai/codex-security",
3
- "version": "0.10.0",
3
+ "version": "0.10.1",
4
4
  "description": "TypeScript SDK and CLI for Codex Security",
5
5
  "license": "Apache-2.0",
6
6
  "author": "OpenAI",
@@ -17,6 +17,11 @@
17
17
  },
18
18
  "main": "./dist/index.js",
19
19
  "types": "./dist/index.d.ts",
20
+ "imports": {
21
+ "#classify-severity-records-logs": {
22
+ "codex-security-records-logs-v1": "./dist/classify-severity-diagnostics.js"
23
+ }
24
+ },
20
25
  "exports": {
21
26
  "./server": {
22
27
  "types": "./dist/server/api.d.ts",
@@ -102,7 +107,7 @@
102
107
  "prettier": "3.9.10",
103
108
  "typescript": "7.0.2"
104
109
  },
105
- "gitHead": "f465432bc4c8882a8b667985a9f68045483ed796",
110
+ "gitHead": "9293f253bb979fd470d91e7ba1117362c0b304a3",
106
111
  "scripts": {
107
112
  "audit:prod": "pnpm audit --prod --audit-level high",
108
113
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -91,6 +91,11 @@
91
91
  }
92
92
  ]
93
93
  },
94
+ "exclude_paths": {
95
+ "description": "Literal files or directories relative to the selected repository. Exclusions take precedence over inclusions.",
96
+ "type": "array",
97
+ "items": { "type": "string", "minLength": 1 }
98
+ },
94
99
  "knowledge_base": {
95
100
  "description": "Context files or directories, relative to this file. An empty list selects no additional context.",
96
101
  "type": "array",
@@ -1,224 +0,0 @@
1
- """Export one AWS Continuum finding and its selected repository's generated patches."""
2
-
3
- import argparse
4
- import json
5
- import os
6
- import subprocess
7
- import sys
8
- from pathlib import Path
9
-
10
- # Isolated Python does not put the installed script directory on sys.path.
11
- sys.path.insert(0, str(Path(__file__).resolve().parent))
12
- from collector_paths import in_source, source_root # noqa: E402
13
-
14
- # Credential helpers may use any interpreter. Forward AWS and host settings
15
- # explicitly so a helper cannot inherit language-specific startup hooks.
16
- ACCOUNT_DIRECTORIES = {"HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "XDG_CONFIG_HOME"}
17
- HOST_SETTINGS = ACCOUNT_DIRECTORIES | {
18
- "ALL_PROXY",
19
- "CURL_CA_BUNDLE",
20
- "HOMEDRIVE",
21
- "HOMEPATH",
22
- "HTTP_PROXY",
23
- "HTTPS_PROXY",
24
- "LANG",
25
- "LANGUAGE",
26
- "LOGNAME",
27
- "NO_PROXY",
28
- "REQUESTS_CA_BUNDLE",
29
- "SSH_AUTH_SOCK",
30
- "SSL_CERT_DIR",
31
- "SSL_CERT_FILE",
32
- "SYSTEMROOT",
33
- "TEMP",
34
- "TMP",
35
- "TMPDIR",
36
- "TZ",
37
- "USER",
38
- "USERNAME",
39
- "WINDIR",
40
- }
41
-
42
-
43
- def checked_model_path(path: Path, source: Path | None, levels: int) -> None:
44
- if in_source(path, source) or (source is not None and source.is_relative_to(path.resolve())):
45
- raise ValueError(f"Use an AWS model path separate from the selected checkout: {path}")
46
- if levels and path.is_dir():
47
- # AWS reads global models and service/<version>/*.json[.gz]. Version
48
- # names come from the filesystem; even a new version can override AWS.
49
- for child in path.iterdir():
50
- if child.name.lower().endswith((".json", ".json.gz")) or (
51
- levels > 1 and child.is_dir()
52
- ):
53
- checked_model_path(child, source, levels - 1)
54
-
55
-
56
- def pinned_setting(name: str, path: Path) -> str:
57
- # Preserve paths expanded from parent-only variables; the CLI expands the
58
- # forwarded value again and splits its model path on the platform separator.
59
- value = str(path)
60
- if os.path.expandvars(value) != value or (name == "AWS_DATA_PATH" and os.pathsep in value):
61
- raise ValueError(f"Use a fully expanded file path for {name}.")
62
- return value
63
-
64
-
65
- def aws_environment(source: Path | None, cwd: Path, directories: list[str]) -> dict[str, str]:
66
- env = {
67
- name: value
68
- for name, value in os.environ.items()
69
- if name.startswith(("AWS_", "LC_")) or name.upper() in HOST_SETTINGS
70
- }
71
- env["PATH"] = os.pathsep.join(directories)
72
- for name in ACCOUNT_DIRECTORIES:
73
- if env.get(name) and in_source(cwd / env[name], source):
74
- raise ValueError(f"Use an account {name} directory outside the selected checkout.")
75
-
76
- # AWS can run credential_process from either profile file and shell commands
77
- # from its per-account alias file. Check the paths AWS will actually read.
78
- for name, default in (
79
- ("AWS_CONFIG_FILE", "~/.aws/config"),
80
- ("AWS_SHARED_CREDENTIALS_FILE", "~/.aws/credentials"),
81
- ):
82
- filename = os.path.expanduser(os.path.expandvars(env.get(name, default)))
83
- path = cwd / filename
84
- if in_source(path, source):
85
- raise ValueError(f"Use an {name} file outside the selected checkout.")
86
- if name in env:
87
- env[name] = pinned_setting(name, path)
88
- if in_source(cwd / os.path.expanduser("~/.aws/cli/alias"), source):
89
- raise ValueError("Use an AWS CLI alias file outside the selected checkout.")
90
- checked_model_path(cwd / os.path.expanduser("~/.aws/models"), source, 3)
91
- if "AWS_DATA_PATH" in env:
92
- paths = []
93
- for entry in env["AWS_DATA_PATH"].split(os.pathsep):
94
- directory = os.path.expanduser(os.path.expandvars(entry))
95
- if directory:
96
- path = cwd / directory
97
- checked_model_path(path, source, 3)
98
- paths.append(pinned_setting("AWS_DATA_PATH", path))
99
- env["AWS_DATA_PATH"] = os.pathsep.join(paths)
100
- return env
101
-
102
-
103
- def installed_aws(target: Path) -> tuple[Path, dict[str, str], Path]:
104
- source = source_root(target)
105
- name = "aws.exe" if os.name == "nt" else "aws"
106
- executable = None
107
- directories = []
108
- for entry in os.get_exec_path():
109
- if os.name == "nt" and entry.startswith('"') and entry.endswith('"'):
110
- entry = entry[1:-1]
111
- directory = Path(entry)
112
- if not directory.is_absolute():
113
- continue
114
- try:
115
- # Also exclude a host directory whose aws links through the checkout.
116
- if in_source(directory / name, source):
117
- continue
118
- directory = directory.resolve(strict=True)
119
- if not directory.is_dir():
120
- continue
121
- candidate = directory / name
122
- if executable is None and candidate.is_file() and os.access(candidate, os.X_OK):
123
- resolved = candidate.resolve(strict=True)
124
- if os.name == "nt" and resolved.suffix.lower() != ".exe":
125
- continue
126
- executable = resolved
127
- directories.append(str(directory))
128
- except OSError:
129
- continue
130
- if executable is None:
131
- raise ValueError("Could not find an installed AWS CLI outside the selected checkout.")
132
-
133
- # Credential helpers inherit the same lookup boundary, including on Windows
134
- # where executable searches can also use the current directory.
135
- cwd = executable.parent if in_source(Path.cwd(), source) else Path.cwd()
136
- return executable, aws_environment(source, cwd, directories), cwd
137
-
138
-
139
- def collect(
140
- environment_id: str, finding_id: str, repository_name: str | None, target: Path
141
- ) -> dict:
142
- executable, child_env, cwd = installed_aws(target)
143
-
144
- def aws(operation: str, *arguments: str) -> dict:
145
- return json.loads(
146
- subprocess.check_output(
147
- [
148
- str(executable),
149
- "continuum",
150
- operation,
151
- *arguments,
152
- "--output",
153
- "json",
154
- "--no-cli-pager",
155
- ],
156
- env=child_env,
157
- cwd=cwd,
158
- )
159
- )
160
-
161
- environment = ["--environment-id", environment_id]
162
- finding = aws("get-code-finding", *environment, "--finding-id", finding_id)
163
- issue_id = finding.get("createdIssueId") or finding.get("duplicateOfIssueId")
164
- if not issue_id:
165
- return finding
166
-
167
- issue = [*environment, "--issue-id", issue_id]
168
- # With JSON output the AWS CLI combines all pages into one items array.
169
- artifacts = aws("list-code-issue-artifacts", *issue, "--artifact-type", "PATCH")
170
- patches = []
171
- for artifact_id in sorted(item["artifactId"] for item in artifacts["items"]):
172
- artifact = aws("get-code-issue-artifact", *issue, "--artifact-id", artifact_id)
173
- body = artifact["body"].get("patch")
174
- if body is None:
175
- raise ValueError(f"Continuum artifact {artifact_id} has no projected patch body.")
176
- if repository_name is not None and body.get("repositoryName") != repository_name:
177
- if not body.get("repositoryName"):
178
- print(
179
- f"Skipped Continuum patch {artifact_id}: AWS did not identify its repository.",
180
- file=sys.stderr,
181
- )
182
- continue
183
- patch = {key: body[key] for key in ("patch", "patchSha256", "sizeBytes")}
184
- for key in ("format", "repositoryName"):
185
- if key in body:
186
- patch[key] = body[key]
187
- patches.append({"artifactId": artifact_id, **patch})
188
-
189
- return {"finding": finding, "patches": patches} if patches else finding
190
-
191
-
192
- def main() -> int:
193
- parser = argparse.ArgumentParser(description=__doc__)
194
- parser.add_argument(
195
- "--source-root",
196
- type=Path,
197
- required=True,
198
- help="Absolute path to the selected local checkout to exclude from executable lookup.",
199
- )
200
- parser.add_argument("--environment-id", required=True)
201
- parser.add_argument("--finding-id", required=True)
202
- scope = parser.add_mutually_exclusive_group(required=True)
203
- scope.add_argument(
204
- "--single-repository",
205
- action="store_true",
206
- help="The selected environment has been verified to contain only this repository.",
207
- )
208
- scope.add_argument("--repository-name", help="Exact Continuum build repository name.")
209
- args = parser.parse_args()
210
- try:
211
- report = collect(
212
- args.environment_id, args.finding_id, args.repository_name, args.source_root
213
- )
214
- except subprocess.CalledProcessError as error:
215
- # The AWS CLI already wrote the diagnostic to stderr.
216
- return error.returncode
217
- except (KeyError, OSError, ValueError) as error:
218
- sys.exit(f"Could not export Continuum finding: {error}")
219
- print(json.dumps(report))
220
- return 0
221
-
222
-
223
- if __name__ == "__main__":
224
- sys.exit(main())