@openai/codex-security 0.5.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -2
- package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +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/scripts/workbench_finding_workflows.py +2 -0
- package/_bundled_plugin/shared/workbench-migrations.json +16 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +16 -8
- package/_bundled_plugin/skills/publish-findings/SKILL.md +130 -0
- package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +6 -0
- package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
- package/dist/api.d.ts +3 -0
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +76 -38
- package/dist/api.js.map +1 -1
- package/dist/classify-severity-records.d.ts +5 -2
- package/dist/classify-severity-records.d.ts.map +1 -1
- package/dist/classify-severity-records.js +40 -34
- package/dist/classify-severity-records.js.map +1 -1
- package/dist/classify-severity.d.ts +5 -1
- package/dist/classify-severity.d.ts.map +1 -1
- package/dist/classify-severity.js +20 -30
- package/dist/classify-severity.js.map +1 -1
- package/dist/cli-help.d.ts.map +1 -1
- package/dist/cli-help.js +1 -0
- package/dist/cli-help.js.map +1 -1
- package/dist/cli.d.ts +7 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +412 -14
- package/dist/cli.js.map +1 -1
- package/dist/cloud-endpoint.d.ts +6 -0
- package/dist/cloud-endpoint.d.ts.map +1 -0
- package/dist/cloud-endpoint.js +51 -0
- package/dist/cloud-endpoint.js.map +1 -0
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +7 -5
- package/dist/cloud-publish.js.map +1 -1
- package/dist/default-severity-rubric.d.ts +3 -0
- package/dist/default-severity-rubric.d.ts.map +1 -0
- package/dist/default-severity-rubric.js +67 -0
- package/dist/default-severity-rubric.js.map +1 -0
- package/dist/endor-findings.d.ts +7 -0
- package/dist/endor-findings.d.ts.map +1 -0
- package/dist/endor-findings.js +233 -0
- package/dist/endor-findings.js.map +1 -0
- package/dist/external-findings-import.d.ts +5 -0
- package/dist/external-findings-import.d.ts.map +1 -0
- package/dist/external-findings-import.js +38 -0
- package/dist/external-findings-import.js.map +1 -0
- package/dist/external-findings-local.d.ts +63 -0
- package/dist/external-findings-local.d.ts.map +1 -0
- package/dist/external-findings-local.js +337 -0
- package/dist/external-findings-local.js.map +1 -0
- package/dist/external-findings-publish.d.ts +73 -0
- package/dist/external-findings-publish.d.ts.map +1 -0
- package/dist/external-findings-publish.js +713 -0
- package/dist/external-findings-publish.js.map +1 -0
- package/dist/external-findings-read.d.ts +6 -0
- package/dist/external-findings-read.d.ts.map +1 -0
- package/dist/external-findings-read.js +88 -0
- package/dist/external-findings-read.js.map +1 -0
- package/dist/external-findings.d.ts +21 -0
- package/dist/external-findings.d.ts.map +1 -0
- package/dist/external-findings.js +2 -0
- package/dist/external-findings.js.map +1 -0
- package/dist/external-import-contract.d.ts +13 -0
- package/dist/external-import-contract.d.ts.map +1 -0
- package/dist/external-import-contract.js +254 -0
- package/dist/external-import-contract.js.map +1 -0
- package/dist/external-import-models.d.ts +362 -0
- package/dist/external-import-models.d.ts.map +1 -0
- package/dist/external-import-models.js +3 -0
- package/dist/external-import-models.js.map +1 -0
- package/dist/finding-workflow.d.ts +1 -1
- package/dist/finding-workflow.d.ts.map +1 -1
- package/dist/finding-workflow.js +2 -1
- package/dist/finding-workflow.js.map +1 -1
- package/dist/github-advisories.d.ts +386 -0
- package/dist/github-advisories.d.ts.map +1 -0
- package/dist/github-advisories.js +131 -0
- package/dist/github-advisories.js.map +1 -0
- package/dist/github-findings.d.ts +10 -0
- package/dist/github-findings.d.ts.map +1 -0
- package/dist/github-findings.js +256 -0
- package/dist/github-findings.js.map +1 -0
- package/dist/hosted-remediation-protocol.d.ts +2 -1
- package/dist/hosted-remediation-protocol.d.ts.map +1 -1
- package/dist/hosted-remediation-protocol.js +17 -11
- package/dist/hosted-remediation-protocol.js.map +1 -1
- package/dist/hosted-remediation.d.ts +4 -0
- package/dist/hosted-remediation.d.ts.map +1 -1
- package/dist/hosted-remediation.js +3 -1
- package/dist/hosted-remediation.js.map +1 -1
- package/dist/hosted-scan.d.ts +16 -0
- package/dist/hosted-scan.d.ts.map +1 -1
- package/dist/hosted-scan.js +14 -2
- package/dist/hosted-scan.js.map +1 -1
- package/dist/index.d.ts +13 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -0
- package/dist/index.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 +2 -0
- package/dist/project-config.js.map +1 -1
- package/dist/remediation.d.ts +6 -0
- package/dist/remediation.d.ts.map +1 -1
- package/dist/remediation.js +16 -5
- package/dist/remediation.js.map +1 -1
- package/dist/result.d.ts +4 -0
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +10 -0
- package/dist/result.js.map +1 -1
- package/dist/runtime.d.ts +1 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +3 -1
- package/dist/runtime.js.map +1 -1
- package/dist/scan-owner-suggestions.d.ts +8 -0
- package/dist/scan-owner-suggestions.d.ts.map +1 -0
- package/dist/scan-owner-suggestions.js +33 -0
- package/dist/scan-owner-suggestions.js.map +1 -0
- package/dist/scan-settings.d.ts +1 -0
- package/dist/scan-settings.d.ts.map +1 -1
- package/dist/scan-settings.js +4 -0
- package/dist/scan-settings.js.map +1 -1
- package/dist/scanner-import.d.ts +20 -0
- package/dist/scanner-import.d.ts.map +1 -0
- package/dist/scanner-import.js +204 -0
- package/dist/scanner-import.js.map +1 -0
- package/dist/security-policy-diff.d.ts +2 -0
- package/dist/security-policy-diff.d.ts.map +1 -0
- package/dist/security-policy-diff.js +197 -0
- package/dist/security-policy-diff.js.map +1 -0
- package/dist/security-policy.d.ts +7 -3
- package/dist/security-policy.d.ts.map +1 -1
- package/dist/security-policy.js +10 -56
- package/dist/security-policy.js.map +1 -1
- package/dist/semgrep-findings.d.ts +9 -0
- package/dist/semgrep-findings.d.ts.map +1 -0
- package/dist/semgrep-findings.js +293 -0
- package/dist/semgrep-findings.js.map +1 -0
- package/dist/severity-review.d.ts +3 -0
- package/dist/severity-review.d.ts.map +1 -1
- package/dist/severity-review.js +19 -0
- package/dist/severity-review.js.map +1 -1
- package/dist/severity-store.js +7 -2
- package/dist/severity-store.js.map +1 -1
- package/dist/snyk-findings.d.ts +9 -0
- package/dist/snyk-findings.d.ts.map +1 -0
- package/dist/snyk-findings.js +349 -0
- package/dist/snyk-findings.js.map +1 -0
- package/dist/targets.d.ts +2 -2
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +12 -2
- package/dist/targets.js.map +1 -1
- package/dist/wiz-csv.d.ts +8 -0
- package/dist/wiz-csv.d.ts.map +1 -0
- package/dist/wiz-csv.js +116 -0
- package/dist/wiz-csv.js.map +1 -0
- package/dist/wiz-findings.d.ts +4 -0
- package/dist/wiz-findings.d.ts.map +1 -0
- package/dist/wiz-findings.js +460 -0
- package/dist/wiz-findings.js.map +1 -0
- package/docs/classify-severity-records.md +28 -10
- package/docs/cli.md +702 -31
- package/docs/hosted-remediation.md +24 -7
- package/docs/hosted-scans.md +12 -0
- package/package.json +6 -4
- package/schemas/external-findings.schema.json +1421 -0
- package/schemas/project-config.schema.json +4 -0
package/docs/cli.md
CHANGED
|
@@ -377,7 +377,16 @@ try {
|
|
|
377
377
|
`preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied
|
|
378
378
|
in-memory draft and escapes terminal controls; editing its saved file does not
|
|
379
379
|
change that object. `securityPolicyDiff()` returns a raw diff for files and other
|
|
380
|
-
non-terminal uses
|
|
380
|
+
non-terminal uses. Both preview methods compute the diff in Node without
|
|
381
|
+
discovering or launching Python; `pythonPath` and `PYTHON` do not affect previews.
|
|
382
|
+
|
|
383
|
+
The optional second argument to `securityPolicyDiff(draft, python, signal)` is
|
|
384
|
+
deprecated. Interpreter paths, including paths returned by a resolver callback,
|
|
385
|
+
no longer select an executable or get validated. For compatibility, an explicitly
|
|
386
|
+
supplied resolver is still awaited when the draft changes, and any error it throws
|
|
387
|
+
propagates. Omit that argument for new code, or pass `undefined` when supplying a
|
|
388
|
+
cancellation signal. Source freshness is checked before and after computing the
|
|
389
|
+
diff.
|
|
381
390
|
|
|
382
391
|
`generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
|
|
383
392
|
`maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives
|
|
@@ -391,6 +400,7 @@ codex-security scan .
|
|
|
391
400
|
codex-security scan . --path src --path tests
|
|
392
401
|
codex-security scan . --diff origin/main --json
|
|
393
402
|
codex-security scan . --working-tree
|
|
403
|
+
codex-security scan . --owner-suggestions
|
|
394
404
|
codex-security scan . --output-dir /path/outside/repository/results --dry-run
|
|
395
405
|
```
|
|
396
406
|
|
|
@@ -402,6 +412,13 @@ changes. Both require Git. Deep scans support whole repositories and path scopes
|
|
|
402
412
|
Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
|
|
403
413
|
be clean and at the commit recorded by the parent.
|
|
404
414
|
|
|
415
|
+
`--owner-suggestions` writes optional `owner-suggestions.json` after a completed
|
|
416
|
+
committed Git scan, using the same checkout, model, and reasoning effort. Owner
|
|
417
|
+
errors leave the base scan completed. The JSON result includes
|
|
418
|
+
`ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
|
|
419
|
+
manifest stay unchanged. This option is unsupported for working-tree and
|
|
420
|
+
directory snapshots, and is skipped with a warning when `--max-cost` is set.
|
|
421
|
+
|
|
405
422
|
Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
|
|
406
423
|
SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
|
|
407
424
|
explicit unsupported binary files are rejected. Bulk scans share this context
|
|
@@ -590,6 +607,9 @@ Import needs no model calls or authentication. `--dry-run` validates without
|
|
|
590
607
|
saving; `--output-dir` and `--archive-existing` control output. `scans rerun`
|
|
591
608
|
reimports the retained input.
|
|
592
609
|
|
|
610
|
+
For vendor exports, use [local vendor import](#import-vendor-findings-locally)
|
|
611
|
+
instead. That flow retains unassessed source evidence without creating a scan.
|
|
612
|
+
|
|
593
613
|
### Generate mock scan results
|
|
594
614
|
|
|
595
615
|
```bash
|
|
@@ -857,24 +877,26 @@ For filesystem and approval behavior, see the
|
|
|
857
877
|
|
|
858
878
|
### Environment variables
|
|
859
879
|
|
|
860
|
-
| Variable | Effect
|
|
861
|
-
| --------------------------------------------------------------------------- |
|
|
862
|
-
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence.
|
|
863
|
-
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts.
|
|
864
|
-
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it.
|
|
865
|
-
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`.
|
|
866
|
-
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers.
|
|
867
|
-
| `PYTHON` | Python interpreter unless an explicit option overrides it.
|
|
868
|
-
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output.
|
|
869
|
-
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank.
|
|
870
|
-
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination.
|
|
871
|
-
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key.
|
|
872
|
-
| `
|
|
873
|
-
| `
|
|
874
|
-
| `
|
|
875
|
-
| `
|
|
876
|
-
| `
|
|
877
|
-
| `
|
|
880
|
+
| Variable | Effect |
|
|
881
|
+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
882
|
+
| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
|
|
883
|
+
| `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
|
|
884
|
+
| `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
|
|
885
|
+
| `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
|
|
886
|
+
| `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
|
|
887
|
+
| `PYTHON` | Python interpreter unless an explicit option overrides it. |
|
|
888
|
+
| `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
|
|
889
|
+
| `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
|
|
890
|
+
| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
|
|
891
|
+
| `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
|
|
892
|
+
| `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
|
|
893
|
+
| `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
|
|
894
|
+
| `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
|
|
895
|
+
| `GH_HOST` | GitHub Enterprise host for bulk discovery. |
|
|
896
|
+
| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
|
|
897
|
+
| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
|
|
898
|
+
| `CI` | Disable interactive update notices. |
|
|
899
|
+
| `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
|
|
878
900
|
|
|
879
901
|
Custom Codex executables need thread source attribution for `exec` and
|
|
880
902
|
`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
|
|
@@ -1173,8 +1195,466 @@ failure or incomplete/invalid output fails the scan. Deferred candidates remain
|
|
|
1173
1195
|
follow-up notes and do not fail the scan. An incompatible plugin stops the scan.
|
|
1174
1196
|
Supply the validation prompt again when rerunning.
|
|
1175
1197
|
|
|
1198
|
+
## Import vendor findings locally
|
|
1199
|
+
|
|
1200
|
+
Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
|
|
1201
|
+
reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
|
|
1202
|
+
inputs only for providers and report profiles that support them. A JSON API
|
|
1203
|
+
summary is not automatically a supported report; follow the provider's acquisition
|
|
1204
|
+
instructions and retain the original records. The readers detect supported input
|
|
1205
|
+
formats; `--format json` selects command output, not the input format.
|
|
1206
|
+
|
|
1207
|
+
Keep the acquisition format consistent across imports. Depending on the provider,
|
|
1208
|
+
switching formats can create separate records for the same vulnerability or
|
|
1209
|
+
replace a richer evidence snapshot with less detail. The importer does not merge
|
|
1210
|
+
evidence or deduplicate equivalent vulnerabilities across different source IDs.
|
|
1211
|
+
|
|
1212
|
+
Use the same vendor input and parser as Cloud publication, selecting a local
|
|
1213
|
+
repository path instead of a Cloud repository ID or URL. Supported inputs include
|
|
1214
|
+
Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
|
|
1215
|
+
[Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
|
|
1216
|
+
[Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
|
|
1217
|
+
and [saved GitHub alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
|
|
1218
|
+
|
|
1219
|
+
```bash
|
|
1220
|
+
codex-security publish findings selected-wiz.json \
|
|
1221
|
+
--to local --repository ./project --provider wiz \
|
|
1222
|
+
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
1223
|
+
```
|
|
1224
|
+
|
|
1225
|
+
Review the normalized evidence, repository, source namespace, and exclusions.
|
|
1226
|
+
Run the same command without `--dry-run` to confirm interactively, or add `--yes`
|
|
1227
|
+
after reviewing the preview. `--to` is required; there is no default destination.
|
|
1228
|
+
Local import uses the workbench SQLite database and requires no Cloud login,
|
|
1229
|
+
network connection, or model call. `--dry-run` does not write findings.
|
|
1230
|
+
|
|
1231
|
+
Read the saved evidence with:
|
|
1232
|
+
|
|
1233
|
+
```bash
|
|
1234
|
+
codex-security findings imported ./project --format json
|
|
1235
|
+
```
|
|
1236
|
+
|
|
1237
|
+
The repository argument defaults to the current directory. Local imports are
|
|
1238
|
+
separate from the assessed findings shown by `findings list`: they remain
|
|
1239
|
+
`not_assessed`, retain the original vendor evidence, and do not create a completed
|
|
1240
|
+
scan or automatically validate or patch findings. Missing revisions, locations,
|
|
1241
|
+
and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
|
|
1242
|
+
Git remotes, the URL must match one of those remotes; the importer does not
|
|
1243
|
+
substitute the checkout's current commit for an unknown scanner revision.
|
|
1244
|
+
|
|
1245
|
+
Repeated imports update the same record by repository, provider, source key, and
|
|
1246
|
+
source finding ID. The result reports created, updated, and unchanged counts.
|
|
1247
|
+
Keep the source key stable across exports. Records omitted from a later selection
|
|
1248
|
+
remain stored; omission does not resolve or delete a finding. Excluded records
|
|
1249
|
+
are reported, and an import with exclusions exits with status 1. The same
|
|
1250
|
+
supported vendor formats and evidence requirements apply locally and in Cloud.
|
|
1251
|
+
|
|
1252
|
+
`scan import --json` and `scan import --csv` remain separate commands for importing
|
|
1253
|
+
Codex Security's findings schema as a saved scan; they do not accept vendor
|
|
1254
|
+
exports.
|
|
1255
|
+
|
|
1256
|
+
## Import Endor Labs findings
|
|
1257
|
+
|
|
1258
|
+
For local or Cloud import, prefer complete native Finding JSON from authenticated
|
|
1259
|
+
`endorctl`, scoped to one project and context. Omit `--field-mask` and use
|
|
1260
|
+
`--list-all` to finish pagination:
|
|
1261
|
+
|
|
1262
|
+
```sh
|
|
1263
|
+
endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
|
|
1264
|
+
--filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
|
|
1265
|
+
--list-all --output-type json > endor-findings.json
|
|
1266
|
+
codex-security publish findings endor-findings.json --to local \
|
|
1267
|
+
--provider endor --repository ./project \
|
|
1268
|
+
--source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
|
|
1269
|
+
```
|
|
1270
|
+
|
|
1271
|
+
Replace the example namespace, project UUID and local repository with your selection.
|
|
1272
|
+
Review the preview, remove `--dry-run` to confirm, then read the stored evidence
|
|
1273
|
+
with `codex-security findings imported ./project --format json`. To publish to
|
|
1274
|
+
Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
|
|
1275
|
+
file, provider and source key. The official
|
|
1276
|
+
[Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
|
|
1277
|
+
can help with setup and investigation, but summaries, counts and field-masked
|
|
1278
|
+
results do not replace complete Finding objects. `endorctl` reads the Endor API;
|
|
1279
|
+
the importer reads the saved export without maintaining an API connection or
|
|
1280
|
+
writing changes back to Endor.
|
|
1281
|
+
|
|
1282
|
+
Native JSON retains severity, package and advisory data, primary SAST/AI SAST
|
|
1283
|
+
locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
|
|
1284
|
+
reports are a lossy compatibility format, retaining finding links and UUIDs;
|
|
1285
|
+
unavailable severity and revisions stay unknown. Both formats use the Endor UUID
|
|
1286
|
+
within the selected repository and stable source key as identity. Importing SARIF
|
|
1287
|
+
after native JSON for that UUID updates the same record by replacing its evidence
|
|
1288
|
+
snapshot, not merging it. Native detail absent from SARIF is removed from the
|
|
1289
|
+
snapshot. Use native JSON consistently for ongoing imports.
|
|
1290
|
+
|
|
1291
|
+
Local and Cloud records remain unassessed source evidence. Local imports use the
|
|
1292
|
+
SQLite readback described above; Cloud imports use the login, preview,
|
|
1293
|
+
confirmation and retry flow below.
|
|
1294
|
+
|
|
1176
1295
|
## Publish findings to Cloud
|
|
1177
1296
|
|
|
1297
|
+
### Import Snyk Open Source findings
|
|
1298
|
+
|
|
1299
|
+
Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
|
|
1300
|
+
SBOM results and platform backlog ingestion are outside this adapter.
|
|
1301
|
+
|
|
1302
|
+
Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
|
|
1303
|
+
with its `snyk-findings-export` skill to collect SCA findings from the repository's
|
|
1304
|
+
Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
|
|
1305
|
+
it does not retrieve existing platform project findings.
|
|
1306
|
+
|
|
1307
|
+
The same saved bundle supports [local import](#import-vendor-findings-locally)
|
|
1308
|
+
without a Cloud login:
|
|
1309
|
+
|
|
1310
|
+
```sh
|
|
1311
|
+
codex-security publish findings snyk-findings.json --to local \
|
|
1312
|
+
--provider snyk --repository ./project \
|
|
1313
|
+
--source-key github.com/example/project/main/root/plugin-sca --dry-run
|
|
1314
|
+
```
|
|
1315
|
+
|
|
1316
|
+
Or preview publication to a connected Cloud repository:
|
|
1317
|
+
|
|
1318
|
+
```sh
|
|
1319
|
+
codex-security publish findings snyk-findings.json --to cloud \
|
|
1320
|
+
--provider snyk --repository https://github.com/example/project \
|
|
1321
|
+
--source-key github.com/example/project/main/root/plugin-sca --dry-run
|
|
1322
|
+
```
|
|
1323
|
+
|
|
1324
|
+
Check the collection's scan outcomes and limitations. Only Open Source SCA
|
|
1325
|
+
vulnerabilities are imported; other products and licenses are explicit exclusions.
|
|
1326
|
+
The importer retains the selected finding, native MCP record and collection
|
|
1327
|
+
context. MCP may shorten descriptions and omit dependency paths. Plugin paths
|
|
1328
|
+
remain in original evidence because v1 lacks their offset from the Git root.
|
|
1329
|
+
|
|
1330
|
+
For automation, prefer native JSON from
|
|
1331
|
+
`snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
|
|
1332
|
+
stop on other nonzero exits before importing. The existing `--provider snyk`
|
|
1333
|
+
autodetects a single project object or an `--all-projects` array; any project error
|
|
1334
|
+
stops the import. Use default ungrouped output, without `--group-issues`.
|
|
1335
|
+
Native JSON preserves individual dependency paths and remediation fields. Its
|
|
1336
|
+
paths remain original evidence because it does not establish their Git-root offset.
|
|
1337
|
+
|
|
1338
|
+
Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
|
|
1339
|
+
for compatibility. Its target-relative manifest paths and synthetic line numbers
|
|
1340
|
+
remain original evidence, without being projected as repository locations or
|
|
1341
|
+
package manifest paths. All three formats accept either destination. Use a consistent
|
|
1342
|
+
format and stable source key per repository, branch and scan target, for example
|
|
1343
|
+
`github.com/example/project/main/root/native-sca` for native JSON. Their source
|
|
1344
|
+
identities differ: use separate keys when switching acquisition formats. Imports
|
|
1345
|
+
do not deduplicate across formats or remove earlier imported records.
|
|
1346
|
+
|
|
1347
|
+
Known repository claims must
|
|
1348
|
+
match the selected Cloud repository or, when available, a configured local Git
|
|
1349
|
+
remote. Unknown repository context still requires selecting the correct target;
|
|
1350
|
+
the importer does not infer provenance from the current checkout.
|
|
1351
|
+
|
|
1352
|
+
Remove `--dry-run` from the selected command to review and confirm the import, or
|
|
1353
|
+
use `--yes` after reviewing the preview. Read local records with
|
|
1354
|
+
`codex-security findings imported ./project --format json`. Imported source
|
|
1355
|
+
evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
|
|
1356
|
+
[Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
|
|
1357
|
+
acquisition details.
|
|
1358
|
+
|
|
1359
|
+
### Import Wiz findings
|
|
1360
|
+
|
|
1361
|
+
Import selected Wiz package vulnerabilities, SAST findings, repository secrets,
|
|
1362
|
+
and IaC findings without creating a scan. Imported records retain vendor evidence
|
|
1363
|
+
and remain **not assessed by Codex**, including when Wiz marks them resolved or
|
|
1364
|
+
reports an AI verdict. Workload secrets, cloud configuration findings, and external
|
|
1365
|
+
network findings are not supported by this repository importer. Cloud destinations
|
|
1366
|
+
currently support connected GitHub and GitHub Enterprise repositories, including
|
|
1367
|
+
custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
|
|
1368
|
+
|
|
1369
|
+
Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
|
|
1370
|
+
connection to acquire findings and save the supported native JSON. A configured
|
|
1371
|
+
plugin may provide that connection; an official Codex plugin is not a prerequisite.
|
|
1372
|
+
The publisher reads the saved records. It does not fetch from Wiz or require a
|
|
1373
|
+
manual website download. The acquisition path still needs validation against
|
|
1374
|
+
actual responses from an authorized Wiz tenant; local parser checks do not
|
|
1375
|
+
establish that qualification.
|
|
1376
|
+
|
|
1377
|
+
Inspect the connection's actual response before importing it. MCP summaries,
|
|
1378
|
+
Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
|
|
1379
|
+
this finding mapper. Keep the original occurrence IDs and evidence; use the
|
|
1380
|
+
named collections below when the response contains repository findings.
|
|
1381
|
+
|
|
1382
|
+
Before the first import:
|
|
1383
|
+
|
|
1384
|
+
1. Select an existing repository in Codex Security Cloud and copy its URL or
|
|
1385
|
+
Cloud repository ID. The repository needs an
|
|
1386
|
+
authorized environment, but does not need a completed native scan.
|
|
1387
|
+
2. Read the selected records through the authorized connection and save their
|
|
1388
|
+
JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
|
|
1389
|
+
`vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
|
|
1390
|
+
package, image, and source metadata. For SAST, repository secrets, and IaC,
|
|
1391
|
+
retain the named API collections and repository metadata described below.
|
|
1392
|
+
Complete the selected pages before importing; a summary or unfinished page
|
|
1393
|
+
is not a complete finding selection.
|
|
1394
|
+
3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
|
|
1395
|
+
for that Wiz tenant and finding class across exports. Do not create a new key
|
|
1396
|
+
for each project filter or import; that creates different source identities.
|
|
1397
|
+
4. Check the ChatGPT account used by your existing file-backed Codex Security
|
|
1398
|
+
login. API-key-only and keyring-only logins are not supported for Cloud
|
|
1399
|
+
publication. See the credential-storage instructions below.
|
|
1400
|
+
|
|
1401
|
+
Prefer the supported native JSON. Existing package-vulnerability CSV reports are
|
|
1402
|
+
accepted as a compatibility input. **CSV support covers repository package
|
|
1403
|
+
vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
|
|
1404
|
+
Wiz code-to-cloud coverage.** The named JSON readers described below handle their
|
|
1405
|
+
respective finding families separately.
|
|
1406
|
+
|
|
1407
|
+
When a UI report is needed, retain the repository and finding filters in Wiz
|
|
1408
|
+
**Vulnerability Findings**, choose **Save as → Report**, select **Repository
|
|
1409
|
+
Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
|
|
1410
|
+
report. CSV must use the columns described below and a comma delimiter. Plain and
|
|
1411
|
+
gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
|
|
1412
|
+
filename extension. **Raw Event** on Code & Build Scans contains scan metadata
|
|
1413
|
+
rather than findings.
|
|
1414
|
+
|
|
1415
|
+
For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
|
|
1416
|
+
API root before previewing or uploading, for example
|
|
1417
|
+
`https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
|
|
1418
|
+
HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
|
|
1419
|
+
`::1`). Use a login issued by that deployment and an isolated
|
|
1420
|
+
`CODEX_SECURITY_STATE_DIR` for testing. The endpoint
|
|
1421
|
+
does not change your login or sign you into another deployment. An invalid or
|
|
1422
|
+
empty configured URL stops the import before authentication or network requests.
|
|
1423
|
+
With the variable unset, the existing production endpoint remains the default.
|
|
1424
|
+
The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
|
|
1425
|
+
publication endpoint; it does not route vendor imports.
|
|
1426
|
+
|
|
1427
|
+
If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
|
|
1428
|
+
to the full Cloud app URL shown in the browser. The import handoff supplies both
|
|
1429
|
+
deployment settings. The preview and result include a repository-specific
|
|
1430
|
+
`cloudUrl`, and terminal completion prints the link. This setting only controls
|
|
1431
|
+
the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
|
|
1432
|
+
For custom API destinations without a configured app URL, completion retains
|
|
1433
|
+
the manual navigation guidance rather than guessing a UI host or port.
|
|
1434
|
+
|
|
1435
|
+
Preview the selection and destination:
|
|
1436
|
+
|
|
1437
|
+
```bash
|
|
1438
|
+
codex-security publish findings selected-wiz.json \
|
|
1439
|
+
--to cloud --repository https://github.com/example/project --provider wiz \
|
|
1440
|
+
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
|
|
1441
|
+
```
|
|
1442
|
+
|
|
1443
|
+
`--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
|
|
1444
|
+
destination and resume the same saved submission. This command reads the
|
|
1445
|
+
authorized destination and current source versions during
|
|
1446
|
+
preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
|
|
1447
|
+
repository needs an existing environment; no native scan is required. Review the
|
|
1448
|
+
Cloud API endpoint, account, repository, environments, findings, and exclusions,
|
|
1449
|
+
then rerun without
|
|
1450
|
+
`--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
|
|
1451
|
+
reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
|
|
1452
|
+
occurs. Existing source findings keep their Cloud environment; new findings use
|
|
1453
|
+
the repository’s current authorized default. Preview shows the environments that
|
|
1454
|
+
will receive the selected findings. The terminal preview summarizes severities,
|
|
1455
|
+
shows up to five finding IDs and titles, and identifies the evidence file and
|
|
1456
|
+
exclusions. `--dry-run --format json` retains all normalized findings and complete
|
|
1457
|
+
evidence for inspection. A prompt explicitly includes any records that will be
|
|
1458
|
+
skipped.
|
|
1459
|
+
|
|
1460
|
+
Native package input can be a Wiz JSON vulnerability report, a vulnerability
|
|
1461
|
+
finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
|
|
1462
|
+
with one package record per line. The repository package-vulnerability CSV
|
|
1463
|
+
profile below is also supported. Plain and gzip-compressed files are accepted.
|
|
1464
|
+
A response that advertises another page is rejected. Complete the requested pages
|
|
1465
|
+
or save only the explicitly selected records; retain the named collection for
|
|
1466
|
+
SAST, repository secrets, and IaC.
|
|
1467
|
+
|
|
1468
|
+
The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
|
|
1469
|
+
`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
|
|
1470
|
+
this profile; other Wiz report types use different fields.
|
|
1471
|
+
For repository imports, `CloudPlatform` must identify GitHub and
|
|
1472
|
+
`CloudProviderURL` must identify a repository branch. The repository URL must
|
|
1473
|
+
match the selected Cloud repository or, for local import, one of the checkout's
|
|
1474
|
+
Git remotes when configured. This also applies when the parsed findings are saved and
|
|
1475
|
+
read again as normalized JSONL. Other resource types are excluded.
|
|
1476
|
+
|
|
1477
|
+
CSV imports use `ID` as the occurrence identity and retain every parsed field,
|
|
1478
|
+
including unknown columns and quoted multiline values, in `source_data.row`.
|
|
1479
|
+
Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
|
|
1480
|
+
Vendor resolution status stays in the original evidence. The importer does not
|
|
1481
|
+
derive a branch or revision from a tree URL, or treat last-detected time as a
|
|
1482
|
+
record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
|
|
1483
|
+
and duplicate occurrence IDs among otherwise importable records stop the import.
|
|
1484
|
+
Review any excluded records in the preview before publishing.
|
|
1485
|
+
|
|
1486
|
+
Normalized JSONL is also accepted:
|
|
1487
|
+
|
|
1488
|
+
```json
|
|
1489
|
+
{
|
|
1490
|
+
"source_finding_id": "vendor-finding-42",
|
|
1491
|
+
"evidence": {
|
|
1492
|
+
"title": "Vulnerable example package",
|
|
1493
|
+
"severity": "high",
|
|
1494
|
+
"source_data": { "id": "vendor-finding-42" }
|
|
1495
|
+
}
|
|
1496
|
+
}
|
|
1497
|
+
```
|
|
1498
|
+
|
|
1499
|
+
Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
|
|
1500
|
+
exports; a selected project filter does not change the vendor namespace. Confirm
|
|
1501
|
+
that the selected assets or builds map to this repository. The raw Wiz adapter
|
|
1502
|
+
retains each record in `source_data`, uses reported severity, and leaves unknown
|
|
1503
|
+
branch/revision empty. Repository-branch findings retain their repository-relative
|
|
1504
|
+
file paths; container and other workload paths remain vendor evidence rather than
|
|
1505
|
+
source-code locations. It does not
|
|
1506
|
+
fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
|
|
1507
|
+
Findings from external network scans are excluded from this package vulnerability
|
|
1508
|
+
mapping.
|
|
1509
|
+
|
|
1510
|
+
For SAST, repository secrets, and IaC, save the documented JSON API collection:
|
|
1511
|
+
|
|
1512
|
+
| Finding family | Collection | Raw occurrence identity |
|
|
1513
|
+
| ------------------ | ---------------------------- | ----------------------- |
|
|
1514
|
+
| SAST | `data.sastFindings.nodes` | `sast:<id>` |
|
|
1515
|
+
| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
|
|
1516
|
+
| IaC | `data.iacFindings.nodes` | `iac:<id>` |
|
|
1517
|
+
|
|
1518
|
+
The collection identifies the mapping. Bare arrays of these raw findings are
|
|
1519
|
+
excluded because their overlapping fields do not identify a family. An export
|
|
1520
|
+
may contain multiple named collections. GraphQL errors and unfinished pages stop
|
|
1521
|
+
the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
|
|
1522
|
+
relationship to source code does not make it a repository secret.
|
|
1523
|
+
|
|
1524
|
+
Each new finding needs a verified source repository URL. Supply `repository.url`
|
|
1525
|
+
in the finding's repository metadata, or include the matching repository inventory
|
|
1526
|
+
in `data.versionControlResources.nodes`. For secrets, repository metadata is under
|
|
1527
|
+
`resource.typedProperties.repository`. The importer joins the inventory's
|
|
1528
|
+
`repository.id` to that source ID and uses `repository.url`; inventory node IDs,
|
|
1529
|
+
`providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
|
|
1530
|
+
must agree with the inventory and with the selected Cloud repository before any
|
|
1531
|
+
finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
|
|
1532
|
+
establishes case-insensitive repository matching on custom GitHub Enterprise
|
|
1533
|
+
hosts. Fresh imports preserve the reported branch name literally. Duplicate
|
|
1534
|
+
entries for one repository ID must agree on their platform and repository URL.
|
|
1535
|
+
For example, this synthetic selection supplies the inventory alongside its SAST
|
|
1536
|
+
collection:
|
|
1537
|
+
|
|
1538
|
+
```json
|
|
1539
|
+
{
|
|
1540
|
+
"data": {
|
|
1541
|
+
"sastFindings": {
|
|
1542
|
+
"nodes": [
|
|
1543
|
+
{
|
|
1544
|
+
"id": "finding-42",
|
|
1545
|
+
"name": "Untrusted query construction",
|
|
1546
|
+
"severity": "HIGH",
|
|
1547
|
+
"repository": { "id": "source-repository-1" },
|
|
1548
|
+
"filePath": "src/query.ts",
|
|
1549
|
+
"startLine": 10,
|
|
1550
|
+
"endLine": 12
|
|
1551
|
+
}
|
|
1552
|
+
]
|
|
1553
|
+
},
|
|
1554
|
+
"versionControlResources": {
|
|
1555
|
+
"nodes": [
|
|
1556
|
+
{
|
|
1557
|
+
"repository": {
|
|
1558
|
+
"id": "source-repository-1",
|
|
1559
|
+
"url": "https://github.com/example/project"
|
|
1560
|
+
}
|
|
1561
|
+
}
|
|
1562
|
+
]
|
|
1563
|
+
}
|
|
1564
|
+
}
|
|
1565
|
+
}
|
|
1566
|
+
```
|
|
1567
|
+
|
|
1568
|
+
The adapters preserve each selected raw node exactly in `source_data`. Typed
|
|
1569
|
+
`evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
|
|
1570
|
+
and family-specific evidence:
|
|
1571
|
+
|
|
1572
|
+
| Family | Evidence retained in typed fields |
|
|
1573
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1574
|
+
| SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
|
|
1575
|
+
| Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
|
|
1576
|
+
| IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
|
|
1577
|
+
|
|
1578
|
+
Vendor status and verdict remain separate from Codex assessment. A secret's
|
|
1579
|
+
introduced commit is not its scanned revision. Missing source revisions and scan
|
|
1580
|
+
IDs stay unknown. A logical IaC resource is retained in the original record and
|
|
1581
|
+
does not establish that it is deployed. Precise original timestamps remain in
|
|
1582
|
+
`source_data`; only an explicit record-update timestamp maps to the whole-second
|
|
1583
|
+
`source_updated_at` field. SAST creation time and IaC last-seen time are not update
|
|
1584
|
+
timestamps.
|
|
1585
|
+
|
|
1586
|
+
Native SAST and secret report downloads can be CSV, including gzip-compressed
|
|
1587
|
+
CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
|
|
1588
|
+
for its actual column headers into normalized JSONL, preserving each original row
|
|
1589
|
+
in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
|
|
1590
|
+
verifying the source repository. Use the same prefixed occurrence ID shown above
|
|
1591
|
+
so API and report imports update the same finding; normalized IDs are accepted
|
|
1592
|
+
exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
|
|
1593
|
+
for a vendor occurrence ID. Missing IDs or severity must be corrected at the
|
|
1594
|
+
source rather than invented.
|
|
1595
|
+
|
|
1596
|
+
For repository-secret reports, select `path` and `lineNumber` for source
|
|
1597
|
+
navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
|
|
1598
|
+
as the introduced commit. The standard secret metadata API does not supply a
|
|
1599
|
+
path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
|
|
1600
|
+
`rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
|
|
1601
|
+
repository/branch metadata. Preserve the original fields; source locations must
|
|
1602
|
+
be repository-relative, and an end line requires a start line. Keep credential
|
|
1603
|
+
values out of the metadata selection; the importer does not retrieve or test
|
|
1604
|
+
credentials or apply remediation instructions.
|
|
1605
|
+
|
|
1606
|
+
Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
|
|
1607
|
+
integer range is rejected; export those values as strings to preserve them
|
|
1608
|
+
exactly. Invalid records appear in `excluded` with their source ID and reason.
|
|
1609
|
+
|
|
1610
|
+
Requests contain at most 100 findings and respect the Cloud payload limits.
|
|
1611
|
+
Before uploading, the publisher saves request IDs and bodies privately under
|
|
1612
|
+
the configured Codex Security state directory. After an uncertain response,
|
|
1613
|
+
repeat the same command with unchanged input and Cloud API endpoint to resume those
|
|
1614
|
+
requests. Different deployments have separate saved submissions, including when
|
|
1615
|
+
their account and repository IDs match. The preview and result include
|
|
1616
|
+
`cloudApiUrl` so scripts can verify which API received the findings; this is an
|
|
1617
|
+
API endpoint, not a link to the Cloud UI. A reset
|
|
1618
|
+
retires the old request without republishing; review and explicitly approve a
|
|
1619
|
+
fresh invocation.
|
|
1620
|
+
|
|
1621
|
+
Results distinguish completion from partial or interrupted work:
|
|
1622
|
+
|
|
1623
|
+
| Status | Exit code | Meaning |
|
|
1624
|
+
| ------------- | --------- | -------------------------------------------------------------------------------------------------- |
|
|
1625
|
+
| `complete` | 0 | All selected records were acknowledged and their source records read back. |
|
|
1626
|
+
| `partial` | 1 | The import finished, but some records were excluded locally or rejected by Cloud. |
|
|
1627
|
+
| `interrupted` | 2 | Upload, verification, or receipt persistence stopped; acknowledged work is included in the result. |
|
|
1628
|
+
| `failed` | 2 | Preparation failed before uploading; structured output includes the error. |
|
|
1629
|
+
|
|
1630
|
+
For finding imports, `--full-output` requires `--format json` or `--format jsonl`.
|
|
1631
|
+
Failed and interrupted imports set the envelope's `ok` to `false`, with
|
|
1632
|
+
`error.code: "IMPORT_FAILED"`, while retaining available results, receipts, and
|
|
1633
|
+
counts under `data`. Other full-output format combinations are rejected before
|
|
1634
|
+
reading the input or contacting Cloud; omit `--full-output` to use those formats.
|
|
1635
|
+
|
|
1636
|
+
Ctrl-C and SIGTERM retain exit codes 130 and 143. Interrupted JSON output preserves
|
|
1637
|
+
`receipts`, `counts`, `failures` with vendor source IDs, `excluded`, `verified`, and
|
|
1638
|
+
`unacknowledged`. A lost response can mean unacknowledged findings were accepted;
|
|
1639
|
+
resume the saved submission rather than treating them as never uploaded. When
|
|
1640
|
+
available, `savedSubmission` identifies the checkpoint to resume by repeating the
|
|
1641
|
+
same command. Review `error` before retrying; a repository reset retires the old
|
|
1642
|
+
submission and requires fresh approval. Correct local exclusions or final source
|
|
1643
|
+
conflicts before preparing a new submission.
|
|
1644
|
+
|
|
1645
|
+
Counts are cumulative for the saved submission: a resumed result includes
|
|
1646
|
+
batches acknowledged by earlier invocations, not just the latest upload attempt.
|
|
1647
|
+
|
|
1648
|
+
Terminal progress reports preparation, acknowledged uploads, and verification
|
|
1649
|
+
on stderr; JSON results stay on stdout. Lookups and readback use at most four
|
|
1650
|
+
concurrent requests, while uploads remain sequential. Successful receipts are
|
|
1651
|
+
saved locally. Verification reads the imported source records and checks their
|
|
1652
|
+
identities and evidence against the receipts. This does not establish a Codex
|
|
1653
|
+
assessment or visibility in the shared Cloud Findings view.
|
|
1654
|
+
When available, `cloudUrl` links to the destination repository in Cloud.
|
|
1655
|
+
|
|
1656
|
+
### Publish completed scans
|
|
1657
|
+
|
|
1178
1658
|
Preview selected completed scans before uploading:
|
|
1179
1659
|
|
|
1180
1660
|
```bash
|
|
@@ -1283,16 +1763,31 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
|
|
|
1283
1763
|
codex-security classify-severity --scan-dir /path/to/completed-scan --json
|
|
1284
1764
|
```
|
|
1285
1765
|
|
|
1286
|
-
For repository-free canonical records, use `classify-severity --records`
|
|
1766
|
+
For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
|
|
1287
1767
|
The [records protocol](classify-severity-records.md) accepts immutable Markdown and
|
|
1288
1768
|
report snapshots and delegates model execution to the host.
|
|
1289
1769
|
|
|
1290
1770
|
For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
|
|
1291
|
-
Omitting `--rubric`
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1771
|
+
Omitting `--rubric` runs classification with the [built-in severity rubric](../src/default-severity-rubric.ts).
|
|
1772
|
+
It evaluates attacker access, boundary crossing, additional harm, and evidence for
|
|
1773
|
+
Critical, High, Medium, Low, and Informational findings. Confidence remains separate
|
|
1774
|
+
from severity; missing proof alone does not justify a downgrade. An explicit
|
|
1775
|
+
`--rubric` replaces the default policy completely. Rubrics and repeatable
|
|
1776
|
+
`--knowledge-base` context accept text, PDF, DOCX, and directories.
|
|
1777
|
+
Each finding is classified three times by default. `--runs N` accepts
|
|
1778
|
+
an integer from 1 through 10; SDK options use `classificationRuns` with the same
|
|
1779
|
+
default and bounds. Each review runs in an independent read-only turn using the
|
|
1780
|
+
same report, rubric, and supplied context, without tools or source inspection.
|
|
1781
|
+
The most common normalized severity wins; the highest among tied top counts wins
|
|
1782
|
+
(`critical` > `high` > `medium` > `low` > `informational`). Exclusion is a separate
|
|
1783
|
+
vote: exclusions can win by count, but lose ties to assessed severities. The first answer matching the winner supplies its label, rationale,
|
|
1784
|
+
confidence, and review trigger. All requested reviews must succeed; failures or invalid
|
|
1785
|
+
answers fail that finding without saving a partial vote. This uses the requested number of model
|
|
1786
|
+
calls per uncached finding (three by default), including when no custom rubric is supplied, and
|
|
1787
|
+
requires the same Codex authentication and model access as custom classification.
|
|
1788
|
+
Codex retains usage for each independent turn. There is no fallback to scanner
|
|
1789
|
+
severity if classification fails.
|
|
1790
|
+
`--model` and `--effort` override Codex's configured model and the default medium effort.
|
|
1296
1791
|
|
|
1297
1792
|
Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,
|
|
1298
1793
|
the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
|
|
@@ -1300,10 +1795,17 @@ missing facts that could change the result. Exclusions have a null level.
|
|
|
1300
1795
|
Finding/occurrence IDs and input hashes bind each assessment to its evidence.
|
|
1301
1796
|
|
|
1302
1797
|
Successful assessments checkpoint immediately in local SQLite. Retries reuse
|
|
1303
|
-
matching evidence, rubric, and
|
|
1304
|
-
work.
|
|
1305
|
-
|
|
1306
|
-
|
|
1798
|
+
matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
|
|
1799
|
+
work. Default-rubric assessments use `source: "rubric"` and a content hash; former
|
|
1800
|
+
no-rubric inherited assessments have no rubric hash and are automatically
|
|
1801
|
+
reclassified on the next classification run. Changes to the bundled policy or
|
|
1802
|
+
switching between default and custom policies also invalidate matching checkpoints.
|
|
1803
|
+
The result and checkpoint record `classificationRuns`; changing the count, or
|
|
1804
|
+
reusing an older checkpoint with no recorded count, triggers fresh classification.
|
|
1805
|
+
Older results remain readable; publication does not silently run a model.
|
|
1806
|
+
Use `--reprocess` to replace assessments, including when changing only model
|
|
1807
|
+
or effort. A successful
|
|
1808
|
+
run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
|
|
1307
1809
|
unchanged.
|
|
1308
1810
|
|
|
1309
1811
|
Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
|
|
@@ -1374,8 +1876,9 @@ await publishScan(scanDirectory, {
|
|
|
1374
1876
|
```
|
|
1375
1877
|
|
|
1376
1878
|
`classifySeverity()` accepts `findingId`, `title`, `summary`, and available
|
|
1377
|
-
evidence/metadata. Imported reports may lack severity or occurrence IDs;
|
|
1378
|
-
|
|
1879
|
+
evidence/metadata. Imported reports may lack severity or occurrence IDs; omitting
|
|
1880
|
+
`rubricPath` uses the built-in policy even when a scanner severity is present.
|
|
1881
|
+
Scan wrappers persist checkpoints (including for
|
|
1379
1882
|
external directories), accept `reprocess: true`, and treat `findingIds: []` as an
|
|
1380
1883
|
empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
|
|
1381
1884
|
publication. Older JSON-only assessments need reclassification once. All
|
|
@@ -1487,6 +1990,7 @@ least eight characters.
|
|
|
1487
1990
|
| `scans match --all` | Match completed scans across worktrees/clones. |
|
|
1488
1991
|
| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
|
|
1489
1992
|
| `findings list [REPOSITORY]` | List open findings. |
|
|
1993
|
+
| `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
|
|
1490
1994
|
| `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
|
|
1491
1995
|
|
|
1492
1996
|
Without an ID, `scans show` selects the latest completed scan, while `scans logs`
|
|
@@ -1772,6 +2276,158 @@ record absolute Node/CLI paths. If those change, back up and remove the verified
|
|
|
1772
2276
|
generated hook, then reinstall with the same threshold. Restore the backup if
|
|
1773
2277
|
installation fails. The installer respects `core.hooksPath`.
|
|
1774
2278
|
|
|
2279
|
+
## Import GitHub findings locally or to Cloud
|
|
2280
|
+
|
|
2281
|
+
Acquire code-scanning findings with the existing `import github` collector and
|
|
2282
|
+
save its complete JSON output. In Codex, the official
|
|
2283
|
+
[GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
|
|
2284
|
+
can help select the repository, alert numbers and ref through GitHub's MCP
|
|
2285
|
+
server; pass that selection to the collector. This integration reads
|
|
2286
|
+
code-scanning alerts and GHSA advisories. It does not import Dependabot or
|
|
2287
|
+
secret-scanning alerts or write back to GitHub. Preview local storage with a
|
|
2288
|
+
repository path:
|
|
2289
|
+
|
|
2290
|
+
```bash
|
|
2291
|
+
codex-security import github example/project --format json > /path/outside/repository/alerts.json
|
|
2292
|
+
codex-security publish findings /path/outside/repository/alerts.json \
|
|
2293
|
+
--to local --provider github --repository ./project \
|
|
2294
|
+
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
2295
|
+
```
|
|
2296
|
+
|
|
2297
|
+
Or preview publication to a connected Cloud repository:
|
|
2298
|
+
|
|
2299
|
+
```bash
|
|
2300
|
+
codex-security publish findings /path/outside/repository/alerts.json \
|
|
2301
|
+
--to cloud --provider github --repository https://github.com/example/project \
|
|
2302
|
+
--source-key github.com/example/project/code-scanning --dry-run --format json
|
|
2303
|
+
```
|
|
2304
|
+
|
|
2305
|
+
The importer fetches every page, retrieves alert details, and retains the selected
|
|
2306
|
+
ref's instance. It writes the saved input for publication; no website download or
|
|
2307
|
+
hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
|
|
2308
|
+
selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
|
|
2309
|
+
the default branch. MCP list calls are paginated separately, and raw MCP/API
|
|
2310
|
+
responses are not the saved import format accepted by `--provider github`.
|
|
2311
|
+
|
|
2312
|
+
The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
|
|
2313
|
+
the plugin's connection does not sign in `gh`. Reading alerts requires
|
|
2314
|
+
[code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
|
|
2315
|
+
**Code scanning alerts: read** for a fine-grained token, or `security_events` for
|
|
2316
|
+
a classic token (`public_repo` is sufficient for public repositories). The source
|
|
2317
|
+
repository must have code scanning available. For Cloud publication, the
|
|
2318
|
+
destination must be connected in the selected Cloud account. For local import,
|
|
2319
|
+
the source repository must match a configured Git remote when remotes are
|
|
2320
|
+
available; no Cloud login is required to store the acquired evidence.
|
|
2321
|
+
|
|
2322
|
+
Review the destination, source, exclusions and evidence in the preview. Repeat the
|
|
2323
|
+
selected command without `--dry-run` and confirm it, or add `--yes` for a
|
|
2324
|
+
previously reviewed input. Local persistence and readback follow the
|
|
2325
|
+
[local import flow](#import-vendor-findings-locally); use
|
|
2326
|
+
`codex-security findings imported ./project --format json` to read the records.
|
|
2327
|
+
Cloud authentication, batching, saved receipts, partial results and
|
|
2328
|
+
interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
|
|
2329
|
+
JSON, JSONL and gzip are supported. Save complete import output without field or
|
|
2330
|
+
token filters or `--full-output`.
|
|
2331
|
+
|
|
2332
|
+
Use a stable source key for the GitHub host, repository and finding family.
|
|
2333
|
+
Code-scanning identities include the selected ref, so branches retain separate
|
|
2334
|
+
evidence. The original alert, rule, scanner, location, revision and source state
|
|
2335
|
+
remain attached. An alert-wide dismissal takes precedence over the selected
|
|
2336
|
+
instance's open/fixed state. Missing security severity stays `unknown`;
|
|
2337
|
+
SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
|
|
2338
|
+
remains unassessed by Codex.
|
|
2339
|
+
|
|
2340
|
+
The SDK offers the same preview and publication boundary for Cloud:
|
|
2341
|
+
|
|
2342
|
+
```ts
|
|
2343
|
+
import {
|
|
2344
|
+
importGitHubCodeScanningAlerts,
|
|
2345
|
+
normalizeGitHubCodeScanningAlerts,
|
|
2346
|
+
prepareNormalizedExternalPublication,
|
|
2347
|
+
} from "@openai/codex-security";
|
|
2348
|
+
|
|
2349
|
+
const alerts = await importGitHubCodeScanningAlerts({
|
|
2350
|
+
repository: "example/project",
|
|
2351
|
+
});
|
|
2352
|
+
const prepared = await prepareNormalizedExternalPublication(
|
|
2353
|
+
normalizeGitHubCodeScanningAlerts(alerts),
|
|
2354
|
+
{
|
|
2355
|
+
provider: "github",
|
|
2356
|
+
repository: "https://github.com/example/project",
|
|
2357
|
+
sourceKey: "github.com/example/project/code-scanning",
|
|
2358
|
+
},
|
|
2359
|
+
);
|
|
2360
|
+
console.log(prepared.preview);
|
|
2361
|
+
// After reviewing the preview:
|
|
2362
|
+
const receipt = await prepared.publish();
|
|
2363
|
+
```
|
|
2364
|
+
|
|
2365
|
+
For local storage, pass the same normalized evidence to
|
|
2366
|
+
`prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
|
|
2367
|
+
its preview, and call `import()`. `prepareLocalExternalImport()` accepts the saved
|
|
2368
|
+
import file directly. Read records with `listLocalExternalFindings({ repository })`.
|
|
2369
|
+
|
|
2370
|
+
### Import GHSA advisories separately
|
|
2371
|
+
|
|
2372
|
+
**Importing a GHSA advisory does not establish an installed dependency or
|
|
2373
|
+
applicability to the destination repository.** Repository advisories are
|
|
2374
|
+
disclosures maintained by a repository; global advisories describe affected
|
|
2375
|
+
software in GitHub's public advisory database. Both are evidence for
|
|
2376
|
+
investigation, not Dependabot alerts. Check the repository’s dependency versions
|
|
2377
|
+
and applicability separately.
|
|
2378
|
+
|
|
2379
|
+
```bash
|
|
2380
|
+
# Read only published advisories for this repository.
|
|
2381
|
+
codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
|
|
2382
|
+
|
|
2383
|
+
# Select individual public database records without enumerating the database.
|
|
2384
|
+
codex-security import github-advisories example/project \
|
|
2385
|
+
--github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
|
|
2386
|
+
--format json > /path/outside/repository/advisories.json
|
|
2387
|
+
|
|
2388
|
+
codex-security publish findings /path/outside/repository/advisories.json \
|
|
2389
|
+
--to cloud --provider github --repository https://github.com/example/project \
|
|
2390
|
+
--source-key github.com/example/project/security-advisories --dry-run --format json
|
|
2391
|
+
```
|
|
2392
|
+
|
|
2393
|
+
For local storage, use the same advisory file, provider and source key with
|
|
2394
|
+
`--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
|
|
2395
|
+
to review, confirm and read the stored evidence.
|
|
2396
|
+
|
|
2397
|
+
`--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
|
|
2398
|
+
to select exact IDs from that API, regardless of advisory state. Repository
|
|
2399
|
+
lists default to `--github-state published`; `draft`, `triage`, and `closed`
|
|
2400
|
+
require explicit selection. A nondefault state cannot be combined with exact
|
|
2401
|
+
IDs. Global selection requires at least one ID and never lists the advisory
|
|
2402
|
+
database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
|
|
2403
|
+
the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
|
|
2404
|
+
[repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
|
|
2405
|
+
require **Repository security advisories: read**, or the classic `repo` or
|
|
2406
|
+
`repository_advisories:read` scope, plus access to the advisory. Public records
|
|
2407
|
+
need no additional advisory permission.
|
|
2408
|
+
|
|
2409
|
+
Review the saved evidence before local import or Cloud publication, including any
|
|
2410
|
+
selected private advisories. Acquisition failure returns no partial selection.
|
|
2411
|
+
Both destinations report invalid records as exclusions. Cloud publication retains
|
|
2412
|
+
acknowledged receipts if a later batch or readback fails.
|
|
2413
|
+
|
|
2414
|
+
Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
|
|
2415
|
+
patched versions, source status and original JSON. It does not infer an installed
|
|
2416
|
+
version or source location. Global advisories omit a source repository; the
|
|
2417
|
+
explicit local or Cloud destination binds the import for investigation. Repository
|
|
2418
|
+
advisories retain their source repository and check it against the Cloud target
|
|
2419
|
+
or configured local Git remotes when available. Withdrawal remains vendor
|
|
2420
|
+
state, and all imported evidence remains not assessed by Codex. Use a separate
|
|
2421
|
+
source key from code-scanning alerts; shared advisory IDs do not combine source
|
|
2422
|
+
records from different providers.
|
|
2423
|
+
|
|
2424
|
+
In the SDK, call `importGitHubAdvisories()` and `normalizeGitHubAdvisories()`
|
|
2425
|
+
with `prepareNormalizedExternalPublication()` for Cloud or
|
|
2426
|
+
`prepareNormalizedLocalImport()` for local storage as described above.
|
|
2427
|
+
`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
|
|
2428
|
+
`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
|
|
2429
|
+
records. Both forms require `repository: "OWNER/REPO"` as source or target context.
|
|
2430
|
+
|
|
1775
2431
|
## Import alerts from the CLI
|
|
1776
2432
|
|
|
1777
2433
|
```bash
|
|
@@ -1968,6 +2624,18 @@ text/files, and Linear inputs. Paths resolve from the invocation directory, even
|
|
|
1968
2624
|
when the finding belongs to another repository. The file must be nonempty and
|
|
1969
2625
|
regular, is read before patching, and cannot combine with `--resume-pr`.
|
|
1970
2626
|
|
|
2627
|
+
Use `--verification-mode static` to assess a patch from source and diff evidence
|
|
2628
|
+
without installing dependencies or running builds, tests, reproducers, or the
|
|
2629
|
+
application. Validation instructions become questions for that source review.
|
|
2630
|
+
The default is `standard`, which retains the existing verification checks.
|
|
2631
|
+
Static results identify the evidence and state that runtime checks were not
|
|
2632
|
+
performed; material proof gaps can still block verification.
|
|
2633
|
+
|
|
2634
|
+
```bash
|
|
2635
|
+
codex-security patch finding.md --verification-mode static
|
|
2636
|
+
codex-security verify-fix finding.md --verification-mode static
|
|
2637
|
+
```
|
|
2638
|
+
|
|
1971
2639
|
`--assess-patch-risk` runs an advisory assessment after patching. Human-readable
|
|
1972
2640
|
output prints its report; saved-finding JSON includes `patchRisk.report`.
|
|
1973
2641
|
With `--create-pr`, the draft description includes the concise Markdown summary.
|
|
@@ -2031,6 +2699,9 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
|
|
|
2031
2699
|
finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
|
|
2032
2700
|
filter for completed Linear issues to check a finished backlog.
|
|
2033
2701
|
|
|
2702
|
+
`--verification-mode static` selects source-only assessment, as described above
|
|
2703
|
+
for `patch`. Omit it or use `--verification-mode standard` for the default checks.
|
|
2704
|
+
|
|
2034
2705
|
Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
|
|
2035
2706
|
`--json` returns structured output. Exit codes are `0` when all findings are
|
|
2036
2707
|
fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
|