@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.
- package/_bundled_plugin/.mcp.json +1 -0
- package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
- package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
- package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
- package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
- package/_bundled_plugin/mcp/server.mjs.br +0 -0
- package/_bundled_plugin/references/access-advisory.md +1 -1
- package/_bundled_plugin/references/threat-model.md +1 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +18 -6
- package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +2 -0
- package/_bundled_plugin/scripts/workbench_db.py +16 -54
- package/_bundled_plugin/scripts/workbench_scan_history.py +23 -28
- package/_bundled_plugin/scripts/workbench_scan_start.py +65 -2
- package/_bundled_plugin/scripts/workbench_source_scopes.py +8 -0
- package/_bundled_plugin/scripts/workbench_target.py +17 -3
- package/_bundled_plugin/shared/workbench-history-repairs.json +5 -1
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -2
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +2 -2
- package/_bundled_plugin/skills/publish-findings/SKILL.md +3 -1
- package/dist/api.d.ts +1 -0
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +23 -4
- package/dist/api.js.map +1 -1
- package/dist/classify-severity-diagnostics.d.ts +10 -0
- package/dist/classify-severity-diagnostics.d.ts.map +1 -0
- package/dist/classify-severity-diagnostics.js +57 -0
- package/dist/classify-severity-diagnostics.js.map +1 -0
- package/dist/classify-severity-records.d.ts +4 -0
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +35 -8
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +99 -11
- package/dist/cli.js.map +1 -1
- package/dist/component-plan.d.ts.map +1 -1
- package/dist/component-plan.js +3 -3
- package/dist/component-plan.js.map +1 -1
- package/dist/continuum-aws.d.ts +6 -0
- package/dist/continuum-aws.d.ts.map +1 -0
- package/dist/continuum-aws.js +202 -0
- package/dist/continuum-aws.js.map +1 -0
- package/dist/continuum-collector.d.ts +44 -0
- package/dist/continuum-collector.d.ts.map +1 -0
- package/dist/continuum-collector.js +266 -0
- package/dist/continuum-collector.js.map +1 -0
- package/dist/continuum-findings.d.ts +31 -2
- package/dist/continuum-findings.d.ts.map +1 -1
- package/dist/continuum-findings.js +440 -64
- package/dist/continuum-findings.js.map +1 -1
- package/dist/contract.d.ts +1 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +3 -0
- package/dist/contract.js.map +1 -1
- package/dist/crowdstrike-findings.d.ts +7 -0
- package/dist/crowdstrike-findings.d.ts.map +1 -0
- package/dist/crowdstrike-findings.js +210 -0
- package/dist/crowdstrike-findings.js.map +1 -0
- package/dist/external-findings-local.d.ts.map +1 -1
- package/dist/external-findings-local.js +26 -8
- package/dist/external-findings-local.js.map +1 -1
- package/dist/external-findings-publish.d.ts.map +1 -1
- package/dist/external-findings-publish.js +5 -1
- package/dist/external-findings-publish.js.map +1 -1
- package/dist/external-findings-read.d.ts +10 -2
- package/dist/external-findings-read.d.ts.map +1 -1
- package/dist/external-findings-read.js +26 -3
- package/dist/external-findings-read.js.map +1 -1
- package/dist/external-import-contract.d.ts +3 -0
- package/dist/external-import-contract.d.ts.map +1 -1
- package/dist/external-import-contract.js +6 -1
- package/dist/external-import-contract.js.map +1 -1
- package/dist/host-protocol.d.ts +6 -0
- package/dist/host-protocol.d.ts.map +1 -1
- package/dist/host-protocol.js +11 -1
- package/dist/host-protocol.js.map +1 -1
- package/dist/host-records-protocol.d.ts +2 -0
- package/dist/host-records-protocol.d.ts.map +1 -1
- package/dist/host-records-protocol.js +4 -0
- package/dist/host-records-protocol.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +4 -2
- package/dist/multiscan.js.map +1 -1
- package/dist/project-config-schema.d.ts +2 -0
- package/dist/project-config-schema.d.ts.map +1 -1
- package/dist/project-config-schema.js +1 -0
- package/dist/project-config-schema.js.map +1 -1
- package/dist/project-config.d.ts +1 -0
- package/dist/project-config.d.ts.map +1 -1
- package/dist/project-config.js +3 -0
- package/dist/project-config.js.map +1 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +4 -0
- package/dist/runtime.js.map +1 -1
- package/dist/scan-comparison.d.ts +20 -2
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +20 -3
- package/dist/scan-comparison.js.map +1 -1
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +1 -0
- package/dist/scan-settings.js.map +1 -1
- package/dist/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +1 -0
- package/dist/severity-review.js.map +1 -1
- package/dist/stored-finding-projection.d.ts.map +1 -1
- package/dist/stored-finding-projection.js +30 -5
- package/dist/stored-finding-projection.js.map +1 -1
- package/dist/targets.d.ts +2 -0
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +27 -0
- package/dist/targets.js.map +1 -1
- package/dist/trusted-executable.d.ts +1 -0
- package/dist/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +11 -3
- package/dist/trusted-executable.js.map +1 -1
- package/dist/value.js +3 -1
- package/dist/value.js.map +1 -1
- package/docs/classify-severity-records.md +30 -0
- package/docs/cli.md +164 -18
- package/docs/sdk.md +23 -8
- package/package.json +7 -2
- package/schemas/project-config.schema.json +5 -0
- 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.
|
|
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
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1440
|
-
attempt
|
|
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.
|
|
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
|
|
1560
|
-
| ------------------------------------------------------------ |
|
|
1561
|
-
| Save vendor evidence for a checkout | `publish findings FILE --to local`
|
|
1562
|
-
| Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud)
|
|
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)
|
|
1565
|
-
| Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan)
|
|
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
|
-
|
|
2318
|
-
|
|
2319
|
-
|
|
2320
|
-
|
|
2321
|
-
|
|
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,
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
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.
|
|
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": "
|
|
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())
|