Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

docs(imports): simplify scanner imports and clarify Cloud receipts (#2271)

Michael D'Angelo93d346eb769c
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.md
index b751600bd..e3172a3b8 100644
--- a/docs/scanner-imports/README.md
+++ b/docs/scanner-imports/README.md
@@ -1,16 +1,40 @@
# Import external scanner findings
-Choose the guide for your report. Each guide shows how to preview the findings
-in a local checkout and which source key to reuse on later imports.
-
-Use a supported report or retrieve the full records for the requested repository
-and ref with a connected tool or signed-in CLI. Fetch selected IDs directly when
-the provider supports it. If a saved report or collector covers more findings,
-use the provider's selection controls or retain only the selected native records
-where the report format permits. Check the accepted findings and their evidence
-in the JSON preview against the requested selection before saving or publishing.
-Use an API response only for an input and destination supported by the provider
-guide. Otherwise, ask for a supported report. A fresh scan produces new results.
+Preview a scanner report before saving its findings locally or sending them
+to Codex Security Cloud.
+
+## Preview a report
+
+[Install the CLI](../../README.md#quick-start), then enable imports in the shell
+where you run it or start Codex.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+```
+
+In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
+Keep reports and preview output in a private directory outside the checkout.
+For commands that use `mktemp`, set `TMPDIR` there if needed. In CI, redirect
+both stdout and stderr to private files.
+
+**In the terminal**, follow your scanner's guide. Run examples that use
+`--repository .` from the checkout root. For a saved report, `publish findings`
+with `--to local --dry-run` works offline without a Cloud login or model call.
+Add `--format json` to see every finding and exclusion.
+For repeat local file imports, reuse the preview's exact `repository` and
+`source.source_key` to update matching findings.
+
+**In Codex**, [enable the Codex Security plugin and start a new chat](../agent-workflows.md#get-started).
+Ask it to preview the report with your configured model.
+
+> Preview `../reports/endor-findings.json` for this checkout. Show me which
+> Endor findings the CLI would import and which it would skip. Stop there.
+
+## Choose your scanner
+
+Check your version with `codex-security --version`. Support for AWS Continuum,
+Black Duck, SonarQube Cloud, Veracode, the Semgrep Platform SDK example, and
+Cloud private inbox imports came after [version 0.8.2](https://github.com/openai/codex-security/blob/npm-v0.8.2/sdk/typescript/docs/cli.md#import-vendor-findings-locally).
| Guide | Supported input |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
@@ -23,65 +47,55 @@ guide. Otherwise, ask for a supported report. A fresh scan produces new results.
| [GitHub Security Advisories](github-security-advisories.md) | Selected repository or global advisories |
| [OpenGrep](opengrep.md) | Native scan JSON, optionally gzip-compressed |
| [Semgrep](semgrep.md) | CLI/CI JSON, SARIF, selected Guardian findings, or Platform Web API reports |
-| [Snyk Open Source](snyk.md) | CLI JSON, a Codex plugin export, or SARIF |
+| [Snyk](snyk.md) | CLI JSON, plugin exports, SARIF, or monitored Code and Open Source issues |
| [SonarQube Cloud](sonar.md) | Issues selected with the signed-in Sonar CLI, or saved issue-search pages |
| [Veracode Static Analysis](veracode.md) | Findings API pages for one application's policy flaws |
| [Wiz](wiz.md) | Native JSON, normalized JSONL, or detailed repository package vulnerability CSV |
-## Preview a report
+If you selected specific findings, compare the preview with your selection.
+Check for missing, duplicate, or unexpected occurrences and resolve any
+exclusions before importing.
-Enable external imports in the shell where you run the CLI.
+## Save or publish and verify
-```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-```
+These steps cover `publish findings FILE`. For `import sonar`, [use the capture
+from the preview for your destination](sonar.md#import-and-verify).
-In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
-Follow your guide's quick start to collect or select the report. Run examples
-that use `--repository .` from the checkout root, or pass the same checkout
-path you used previously. Use `--dry-run` to review the repository, source key,
-findings, and exclusions.
-Keep the export private. In automation, direct stdout and stderr for collection,
-preview, confirmation, and readback to private files outside the checkout.
-For examples that use `mktemp -d` without a path, set `TMPDIR` to a private
-directory outside the checkout if temporary files would otherwise land inside it.
+**Save locally.** Remove `--dry-run` and confirm. In automation, use `--yes`
+after reviewing the preview.
-## Save or publish and verify
+**Send to Cloud.** Keep your file, provider, source key, and scanner options.
+Set `--to cloud` and pass the connected repository URL or Cloud ID to
+`--repository`. Preview again with `--dry-run`. Check the account, endpoint,
+destination, findings, and exclusions. Remove `--dry-run` and confirm. [Cloud setup](../../sdk/typescript/docs/cli.md#preview-and-publish)
-The steps below apply to `publish findings FILE`. For `import sonar`,
-[confirm the capture returned by the Sonar preview](sonar.md#import-and-verify).
+### Verify the import
-**Local workbench.** Run the same command with the same file, checkout, and
-source key. Remove `--dry-run` and confirm the prompt.
-For noninteractive use, add `--yes` after reviewing that preview. Read back
-the stored evidence using the checkout path from the preview:
+For a local import, list the saved findings using the checkout path from the preview.
```sh
codex-security findings imported /path/to/project --format json
```
-**Codex Security Cloud.** Use a file-backed ChatGPT login for a deployment that
-accepts the provider and a repository environment you can publish to. See
-[Cloud setup](../../sdk/typescript/docs/cli.md#preview-and-publish). Keep the
-file, provider, source key, and scanner-specific options. Set `--to cloud` and
-replace the local checkout in `--repository` with the connected repository URL
-or Cloud repository ID. Use the ID if several connectors share the URL.
-Run with `--dry-run` first. Check that `cloudApiUrl`
-is the intended API endpoint, then review the account, repository, environments,
-and exclusions. Remove `--dry-run` and confirm, or use `--yes` after that
-review. Check `status`, the `verified` and
-`unacknowledged` counts, and the `failures` and `excluded` lists. For a `partial`
-result, correct exclusions or resolve version conflicts before starting a new
-submission. If an `interrupted` result includes `savedSubmission`,
-[resume from that checkpoint](schema-guide.md#retry-a-cloud-submission).
+For a Cloud import, check the receipt for the destination shown in the preview.
+
+| What the Cloud preview shows | How to verify the import |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Private inbox (`privateImport`) | Check the job status, errors, exclusions, and unprocessed count. Open a finding in your inbox to assess it before sharing. |
+| Repository publisher (environments in `requests`) | Check each receipt, the verified and unacknowledged counts, failures, and exclusions. |
+
+If `publish findings` stops and returns `savedSubmission`, [resume from that checkpoint](schema-guide.md#retry-a-cloud-submission).
## Work with imported findings
-Imported records start with assessment state `not_assessed`. Use the source
-evidence to check whether a finding affects your repository. For the identity
-of a record, the fields each reader retains, and how repeat imports update
-evidence, see [Imported finding identity and evidence](schema-guide.md).
+New local findings start as `not_assessed`. To check whether one affects your
+code, give its evidence and the matching checkout to the [triage workflow](../agent-workflows.md#choose-a-task).
+For a dependency alert, [check the installed version and trace the dependency](github-dependabot.md#identity-and-evidence).
+
+With the SDK, look up a local record by its `id` with
+`listLocalExternalFindings({ repository, id })`. Pass `record.evidence` and the
+matching checkout to [`security.validate()`](../../sdk/typescript/README.md#validate-an-existing-finding).
+Your configured model provider returns a separate assessment.
-For findings from a completed Codex scan, see
-[Track findings in Linear, Jira, or GitHub](../../plugins/codex-security/skills/track-findings/SKILL.md)
-or [Export findings for ServiceNow](../../sdk/typescript/docs/cli.md#export-findings-for-servicenow).
+See [Imported finding identity and evidence](schema-guide.md) for what each
+reader stores and how repeat imports work.
diff --git a/docs/scanner-imports/blackduck.md b/docs/scanner-imports/blackduck.md
index d64398a0d..462a13c32 100644
--- a/docs/scanner-imports/blackduck.md
+++ b/docs/scanner-imports/blackduck.md
@@ -1,73 +1,77 @@
# Import Black Duck SCA findings
-Import vulnerable BOM components from one Black Duck SCA project version.
-Verify in the scan configuration which Git repository that version represents.
+Use a BOM-6 export of vulnerable components from one Black Duck SCA project
+version. In the scan configuration, verify which Git repository that version
+represents. A project name or component download URL alone can't establish
+that link.
## Quick start
-[Enable external imports](README.md#preview-a-report) and use a read-only token to
-[export the BOM-6 collection](#export-the-bom-6-collection). From the matching
-checkout root, preview the saved file with the verified Git URL and a source key
-for this deployment, project, and version.
+[Enable external imports](README.md#preview-a-report), then open the matching
+checkout. Choose a saved report or export one.
+
+**Saved report.** Set `report` to the complete BOM-6 collection. For a selection,
+use an array of native rows that each identify the same project version.
```sh
-codex-security publish findings /private/path/blackduck.json \
- --to local --repository . --provider blackduck \
- --source-repository-url https://github.com/example/project \
+report=/private/path/blackduck.json
+```
+
+**Export from Black Duck.** Use a read-only token and the
+[BOM-6 export below](#export-the-bom-6-collection). Run it in the same shell
+to set `report`.
+
+**Preview the report.** Use the verified Git URL for `--source-repository-url`.
+It must match a comparable local remote when available, or the selected Cloud
+repository. Replace the source key with one for your deployment, project and
+version.
+
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider blackduck --source-repository-url https://github.com/example/project \
--source-key blackduck/deployment-alias/project-id/version-id \
--dry-run --format json
```
-## Import and verify
-
-Check the source Git URL against the checkout’s configured remotes or the
-authorized GitHub repository in Cloud. A project name or component download
-URL alone cannot establish that link.
-[Save or publish and verify](README.md#save-or-publish-and-verify) using the same
-source key for subsequent exports of this project version.
-
-## Reference
-
-### Identity and evidence
-
-Each occurrence is identified by its project version, component version,
-origin, advisory source, and advisory name. Package URLs and origin coordinates
-supply the package identity. The `advisory_ids` field preserves
-`vulnerabilityName` and any distinct `relatedVulnerability` verbatim, including
-Black Duck resource URLs. The original row retains its CWE, matched-files link,
-and remediation status. Imported records start unassessed. The importer does
-not infer a fix, Git revision, or source location. Aggregate product BOMs,
-image-only scans, license violations, and global advisory catalogs are outside
-this import.
-
-For SDK imports, select the `blackduck` provider when replaying retained BOM
-records. Reader-supplied repository references must agree with the repository
-on local findings. Opaque IDs and caller-authored text alone cannot establish
-repository ownership.
-
-### Export the BOM-6 collection
-
-The [Black Duck SCA MCP](https://github.com/blackducksoftware/sca-mcp#capabilities)
-can locate the project version with `search_projects_versions`. Its
-`fetch_project_vulnerabilities` tool returns a summary and CSV. Use the REST
-export below for BOM rows. The MCP’s `scan` starts a new scan. Coverity and
-Polaris reports use different formats.
-
-Request the project version’s `vulnerable-components` relation with media type
-`application/vnd.blackducksoftware.bill-of-materials-6+json`. The importer
-requires BOM-6. If the deployment only serves BOM-8 or another inventory format,
-it cannot supply this collection.
-
-Install the vendor’s `blackduck` Python client in a trusted virtual environment
-outside the checkout. Set `BLACKDUCK_URL` to the deployment’s HTTPS URL,
-`BLACKDUCK_TOKEN` to the read-only token, and `BLACKDUCK_PROJECT_ID` and
-`BLACKDUCK_VERSION_ID` to their UUIDs. Keep redirects disabled for the client
-session, including the token exchange.
-
-Save the script outside the checkout and run it with
-`/path/to/venv/bin/python -I /private/path/export.py` to keep checkout modules
-and `PYTHONPATH` off the import path. Redirect stdout to a private temporary file
-and rename it to `blackduck.json` after the script succeeds.
+In each finding's `evidence`, check `source_data.projectVersionUrl`,
+`packages` and `advisory_ids`. Review any excluded rows. Reuse this key for
+later exports of the same project version.
+[Save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+
+## Identity and evidence
+
+The project version, component version, origin, advisory source and advisory
+name identify each occurrence. Package URLs and origin coordinates identify
+the package. `advisory_ids` keeps `vulnerabilityName` and any distinct
+`relatedVulnerability` verbatim, including Black Duck resource URLs.
+
+Look in the original row for CWE, matched-files links and remediation
+status. The reader leaves fix verification, Git revision and source location
+unknown.
+Aggregate product BOMs, image-only scans, license violations and global
+advisory catalogs fall outside this import.
+
+For SDK replay, use the `blackduck` provider and keep the repository reference
+from the reader. It must match the repository on local findings. An opaque ID
+or a description alone can't establish repository ownership.
+
+## Export the BOM-6 collection
+
+In the [Black Duck SCA MCP](https://github.com/blackducksoftware/sca-mcp#capabilities),
+`search_projects_versions` can locate the project version.
+`fetch_project_vulnerabilities` returns a summary and CSV, and `scan` starts
+a new scan. To export existing BOM rows, request the project version's
+`vulnerable-components` relation with the BOM-6 media type shown below.
+This reader requires BOM-6. BOM-8 inventories, Coverity reports and Polaris
+reports use other formats.
+
+Install the vendor's `blackduck` Python client in a trusted virtual environment
+outside the checkout. Set `BLACKDUCK_URL` to the deployment's HTTPS URL,
+`BLACKDUCK_TOKEN` to a read-only token, and `BLACKDUCK_PROJECT_ID` and
+`BLACKDUCK_VERSION_ID` to the project and version UUIDs. Keep redirects disabled
+for the client session, including the token exchange.
+
+Save this script outside the checkout as `export.py`.
```python
import json
@@ -135,8 +139,17 @@ while True:
print(json.dumps({"_meta": {"href": url}, "totalCount": total, "items": items}))
```
-Keep the original rows and collection total. If the BOM changes during offset
-pagination, export it again after the scan finishes. For a selection, supply
-an array of native rows that each identify the same project version. See the
-[Black Duck Python client](https://github.com/blackducksoftware/hub-rest-api-python)
-and its [vulnerable BOM component example](https://github.com/blackducksoftware/hub-client-go/blob/5f78f7257c00fe9cebabf1bf89a6fc36a4d1f095/hubapi/testdata/vulnerableBomComponents.json).
+Run the script in isolated mode so Python loads packages from the trusted
+environment. Point `TMPDIR` to a private directory outside the checkout.
+
+```sh
+report=
+out=$(mktemp -d) &&
+ /path/to/venv/bin/python -I /private/path/export.py > "$out/blackduck.tmp" &&
+ mv "$out/blackduck.tmp" "$out/blackduck.json" &&
+ report="$out/blackduck.json"
+```
+
+Keep the original rows and collection total. If the BOM changes during
+pagination, export it again after the scan finishes.
+[Black Duck Python client](https://github.com/blackducksoftware/hub-rest-api-python) · [Vulnerable BOM component example](https://github.com/blackducksoftware/hub-client-go/blob/5f78f7257c00fe9cebabf1bf89a6fc36a4d1f095/hubapi/testdata/vulnerableBomComponents.json)
diff --git a/docs/scanner-imports/continuum.md b/docs/scanner-imports/continuum.md
index 4a37d5aed..659c0088a 100644
--- a/docs/scanner-imports/continuum.md
+++ b/docs/scanner-imports/continuum.md
@@ -1,70 +1,81 @@
# Import AWS Continuum code findings
-Import a saved JSON response from AWS Continuum for Code Vulnerabilities.
-Use a detailed finding for investigation or a list of summaries for an
-overview of one repository.
+Use `GetCodeFinding` JSON to investigate one finding with its locations,
+description, mitigation, and AWS validation evidence when available. Use
+`ListCodeFindings` JSON for summaries from an environment dedicated to one
+repository.
-## Export findings for one repository
+## Quick start
-Use an AWS CLI with the `continuum` commands, signed in to the account and
-Region where the environment lives. Set `ENVIRONMENT_ID` to that environment.
-Check its code sources against the repository you intend to import into. For
-an S3 source, verify which repository supplied the scanned archive.
-[AWS Continuum code sources](https://docs.aws.amazon.com/continuum/latest/userguide/cv-getting-started.html)
+[Enable external imports](README.md#preview-a-report) and open the matching
+checkout. Set `ENVIRONMENT_ID` to the Continuum environment ID. Verify which
+repository supplied the scanned code, including the archive for an S3 source.
+For a finding from another scanner, you can also check its repository in that
+scanner. [AWS Continuum code sources](https://docs.aws.amazon.com/continuum/latest/userguide/cv-getting-started.html)
-**One finding.** Check the finding against its scanned code source, then set
-`FINDING_ID` to its Continuum finding ID. For a finding from another scanner,
-you can also verify the repository in the originating scanner. The detail
-response can include code locations, descriptions, mitigation and AWS
-validation evidence.
-[AWS CLI get-code-finding](https://docs.aws.amazon.com/cli/latest/reference/continuum/get-code-finding.html)
+**Saved report.** Set `report` to a native detail response or a complete list
+response with its `items` array, then skip to the preview.
```sh
+report=/private/path/continuum.json
+```
+
+### Export findings for one repository
+
+To create a report, sign in to the environment's AWS account and Region with
+an AWS CLI that supports `continuum`. Choose one export.
+
+**One finding.** Set `FINDING_ID` to the Continuum ID of the finding you
+verified. In an environment with several repositories, use this command to
+export one verified finding at a time. [AWS CLI get-code-finding](https://docs.aws.amazon.com/cli/latest/reference/continuum/get-code-finding.html)
+
+```sh
+report=
out=$(mktemp -d) &&
aws continuum get-code-finding --environment-id "$ENVIRONMENT_ID" \
--finding-id "$FINDING_ID" --output json > "$out/continuum.tmp" &&
- mv "$out/continuum.tmp" "$out/continuum.json"
+ mv "$out/continuum.tmp" "$out/continuum.json" &&
+ report="$out/continuum.json"
```
-**All summaries.** For bulk import, use an environment dedicated to one
-repository and verify that the export belongs to that repository. Start on
-the first page with automatic pagination enabled. Keep the JSON object with
-its `items` array. In a mixed environment, export verified findings with
-`get-code-finding`.
-[AWS CLI list-code-findings](https://docs.aws.amazon.com/cli/latest/reference/continuum/list-code-findings.html)
+**All summaries.** Verify that the environment contains findings from just
+this repository. Start on the first page and let the AWS CLI fetch every
+page. [AWS CLI list-code-findings](https://docs.aws.amazon.com/cli/latest/reference/continuum/list-code-findings.html)
```sh
+report=
out=$(mktemp -d) &&
aws continuum list-code-findings --environment-id "$ENVIRONMENT_ID" \
--output json > "$out/continuum.tmp" &&
- mv "$out/continuum.tmp" "$out/continuum.json"
+ mv "$out/continuum.tmp" "$out/continuum.json" &&
+ report="$out/continuum.json"
```
-## Preview and import
+### Preview and import
-[Enable external imports](README.md#preview-a-report). From the matching
-checkout, preview the export with the verified Git URL and a stable source key
-for the environment and repository.
+Preview the report with the verified Git URL and a source key for this
+environment and repository.
```sh
-codex-security publish findings "$out/continuum.json" \
- --to local --repository . --provider continuum \
- --source-repository-url https://github.com/example/project \
+codex-security publish findings "$report" --to local --repository . \
+ --provider continuum --source-repository-url https://github.com/example/project \
--source-key "continuum/$ENVIRONMENT_ID/example/project" \
--dry-run --format json
```
-Check the destination, finding ARNs, reported paths and exclusions. In
-multi-repository environments, customer-supplied paths can start with a
-repository name. The reader preserves that prefix. Follow
-the shared steps to save locally or publish to a Cloud deployment that
-accepts the `continuum` provider. [Save or publish and verify](README.md#save-or-publish-and-verify)
-
-The finding ARN identifies the same occurrence in either export. With the
-same source key, importing a detail response after its summary updates the
-existing record. A subsequent summary replaces that richer evidence. Reuse
-`get-code-finding` for updates when you need the details.
-Both scanner-generated and customer-supplied code findings retain their AWS
-fields in `evidence.source_data.finding`. Continuum status and validation
-are vendor evidence. New findings start with a Codex assessment of
-`not_assessed`.
+Check the repository, finding ARNs, paths, and exclusions. In a
+multi-repository environment, a customer-supplied path can begin with a
+repository name. The reader keeps that prefix. If the preview matches,
+[save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+For Cloud, the deployment must accept the `continuum` provider.
+
+## Detail, summaries, and repeat imports
+
+Both formats use the finding ARN. With the same source key, importing a
+detail response after its summary updates the existing finding. A later
+summary replaces the richer evidence, so use `get-code-finding` for updates
+when you need those details.
+
+For both scanner-generated and customer-supplied findings,
+`evidence.source_data.finding` keeps the original AWS fields, including any
+Continuum status and validation results.
diff --git a/docs/scanner-imports/endor.md b/docs/scanner-imports/endor.md
index 8ee628268..860bd1ad2 100644
--- a/docs/scanner-imports/endor.md
+++ b/docs/scanner-imports/endor.md
@@ -1,77 +1,79 @@
# Import Endor Labs findings
-Import findings from one Endor Labs project and scan context. Native Finding
-JSON preserves the scanned commit, severity, and dependency and location
-details reported by Endor.
+Prefer Endor's native Finding JSON. It keeps the scanned commit,
+severity, package and advisory details, and primary SAST or AI SAST locations
+that Endor reports. You can also import self-contained `endorctl` SARIF 2.1.0
+with finding UUIDs.
## Quick start
-[Enable external imports](README.md#preview-a-report) and
-[export the native findings](#native-finding-json) from the intended project
-and context. From the matching checkout root, preview the saved file. Replace
-the file path, namespace, and project UUID.
+[Enable external imports](README.md#preview-a-report). In Endor, verify that
+the project and scan context match your checkout. A project UUID alone doesn't
+establish that link. From the checkout root, set the namespace and project
+UUID for this default-branch example.
```sh
-codex-security publish findings /private/path/endor-findings.json \
- --to local --repository . --provider endor \
- --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run --format json
+namespace=YOUR_NAMESPACE
+project=PROJECT_UUID
+source_key="$namespace/$project/main"
```
-## Import and verify
+For repeat imports, reuse the previous preview's exact source key. Choose a
+saved report or export one in the same shell.
-Confirm the project and context belong to this repository. The importer retains
-the project UUID but does not look up its Git repository.
-[Save or publish and verify](README.md#save-or-publish-and-verify) using the same
-source key for later exports from this context.
+**Saved report.** Set `report` to a private file outside the checkout. It can
+contain one Finding, an array of Findings, or a complete JSON response with
+`list.objects`. For selected UUIDs, save just those complete Findings in an array.
-## Reference
-
-### Native Finding JSON
+```sh
+report=/private/path/endor-findings.json
+```
-Authenticate `endorctl` for the namespace that owns the project. Replace
-`YOUR_NAMESPACE` and `PROJECT_UUID`, then export the findings.
+**Export from Endor.** Sign in to your namespace with `endorctl`. Use a
+private temporary directory outside the checkout. For another scan context,
+change both the filter and the source key. The Endor Labs Agent Kit can find
+UUIDs for a selection.
+[Agent Kit](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit) · [Filter syntax](https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/filters#values)
```sh
+filter="context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==\"$project\""
+# For selected UUIDs, uncomment and replace the example IDs.
+# filter="$filter"' and uuid in ["UUID_A","UUID_B"]'
+report=
out=$(mktemp -d) &&
- endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
- --filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
- --list-all --output-type json > "$out/endor-findings.tmp" &&
- mv "$out/endor-findings.tmp" "$out/endor-findings.json"
+ endorctl api list --resource Finding --namespace "$namespace" \
+ --filter "$filter" --list-all --output-type json > "$out/endor-findings.tmp" &&
+ mv "$out/endor-findings.tmp" "$out/endor-findings.json" &&
+ report="$out/endor-findings.json"
+```
+
+Keep `--list-all` to fetch every page. Omit `--field-mask` to keep every field.
+[Endor CLI API](https://docs.endorlabs.com/developers-api/cli/commands/api)
+
+**Preview the report.**
+
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider endor --source-key "$source_key" --dry-run --format json
```
-The filter selects default-branch findings. For another context, change both
-the filter and source key. Keep `--list-all` and omit `--field-mask` to export
-complete Finding objects. The saved file is `$out/endor-findings.json`.
-
-The importer accepts a single Finding, an array, or a `ListFindingsResponse`
-containing `list.objects`. An unfinished paginated response is rejected. Native
-JSON retains the complete Finding and maps severity, dependency and advisory
-details, scanned commit SHA, and primary SAST or AI SAST locations when
-available. See the [Endor CLI API](https://docs.endorlabs.com/developers-api/cli/commands/api)
-and [Finding model](https://github.com/endorlabs/endorlabs-sdk/blob/8a41756890c2dee3bb089fee881cae4f2adbde03/src/endorlabs/generated/models/finding_service.py).
-
-The [Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
-can identify UUIDs. For a fresh export, append `and uuid in ["UUID_A","UUID_B"]`
-to the project and context filter above, using the requested UUIDs. For a saved
-export, select their complete objects from `list.objects`. Before import, verify
-the preview contains each requested UUID once, no other IDs, and no exclusions.
-[Endor filter syntax](https://docs.endorlabs.com/developers-api/rest-api/using-the-rest-api/filters#values)
-
-### SARIF and repeat imports
-
-Self-contained `endorctl` SARIF 2.1.0 reports preserve finding UUIDs, links,
-direct repository paths, and reported SAST or Secrets lines. Native severity
-and scanned revision are unavailable. Diagnostic levels, CVSS, and indexed or
-base-relative artifact references stay in the original evidence. Unrelated run
-artifact inventories are omitted. For a new Cloud submission, declared
-repository URLs must match the selected repository. For local imports, they
-must match a comparable configured Git remote when one is available.
-
-Both formats identify a record by finding UUID within the repository and source
-key. Reimporting replaces its evidence snapshot. Importing SARIF after native
-JSON can clear commit, package, and advisory details and make severity unknown.
-For ongoing imports use native JSON and the same source key. Local records
-omitted from later imports remain stored.
-
-Upgrades, reachability, and dismissals remain Endor’s claims. Imported findings
-start unassessed and are separate from completed scans.
+Check the repository, source key, findings and exclusions. For selected UUIDs,
+verify that `findings[].source_finding_id` lists each requested UUID once and
+no others, and that `excluded` is empty. If the preview matches,
+[save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+New findings start as `not_assessed`. Upgrade recommendations, reachability
+and dismissals come from Endor.
+
+## SARIF and repeat imports
+
+Both formats identify findings by UUID. Importing SARIF after native JSON
+with the same destination and source key replaces the earlier evidence. You
+can lose the scanned commit, package and advisory details, and severity can
+become `unknown`. The local workbench keeps findings omitted from later exports.
+[Imported finding identity and evidence](schema-guide.md)
+
+SARIF keeps finding links, direct repository paths and reported SAST or
+Secrets lines. Look in the original evidence for diagnostic levels, CVSS and
+indexed or base-relative artifact references. If the report includes repository
+URLs, they must match a comparable local Git remote when available, or the
+selected repository for a new Cloud submission.
diff --git a/docs/scanner-imports/github-code-scanning.md b/docs/scanner-imports/github-code-scanning.md
index 1a6d91557..6b1a58576 100644
--- a/docs/scanner-imports/github-code-scanning.md
+++ b/docs/scanner-imports/github-code-scanning.md
@@ -1,48 +1,58 @@
# Import GitHub code scanning findings
-Import code scanning alerts from one repository and Git ref. The collector
-saves each alert with the instance that GitHub returned for the selected ref.
+Use the JSON array from `codex-security import github`. It includes each
+alert and the instance GitHub returned for the selected ref.
## Quick start
-Sign in with `gh auth login`. A fine-grained token needs **Code scanning alerts: read**.
-A classic token needs `security_events`, or `public_repo` for a public repository.
+[Enable external imports](README.md#preview-a-report). From the matching
+checkout, set the repository and source key. For GitHub Enterprise, export
+`GH_HOST` with your hostname first. For a repeat import, use the exact source
+key from your previous preview, including case.
+
+```sh
+repo=OWNER/REPO
+source_key="${GH_HOST:-github.com}/$repo/code-scanning"
+```
+
+**Saved report.** Set `report=/private/path/alerts.json` if you already have
+the collector's complete JSON array.
+
+**Export from GitHub.** Sign in to the selected host with `gh auth login`.
+A fine-grained token needs **Code scanning alerts: read**. A classic token
+needs `security_events`, or `public_repo` for a public repository.
[GitHub API permissions](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository)
-For GitHub Enterprise, set `GH_HOST` to the host you signed in to.
-If `gh` is unavailable, the SDK accepts `githubHost` and a `githubToken` for that host.
-From the destination checkout root, set `repo` to its GitHub repository. Set
-`source_key` to your existing code scanning key exactly, including case. For a
-first import, choose a key for the host, repository and finding family. Replace
-`/path/to/private/reports` with an existing private directory outside the checkout,
-then preview the default branch’s open alerts.
+This command selects open alerts on the default branch. For another branch,
+add `--github-ref refs/heads/BRANCH`. Use `--github-state all` to include
+fixed and dismissed alerts, or repeat `--github-alert NUMBER` to select
+specific alerts across states. Omit output filters, token limits and
+`--full-output` so the reader gets the complete array. Use a private
+temporary directory outside the checkout.
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-repo=OWNER/REPO
-source_key=github.com/example/project/code-scanning
-out=$(mktemp -d "/path/to/private/reports/github.XXXXXX") &&
+report=
+out=$(mktemp -d) &&
codex-security import github "$repo" --format json > "$out/alerts.json" &&
- codex-security publish findings "$out/alerts.json" \
- --to local --repository . --provider github \
- --source-key "$source_key" --dry-run --format json
+ report="$out/alerts.json"
+```
+
+**Preview the report.**
+
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider github --source-key "$source_key" --dry-run --format json
```
-## Import and verify
+Check the repository, ref and alert numbers against your selection. The alert
+repository must match a comparable local Git remote when available, or the
+selected Cloud repository. If the preview matches,
+[save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
-Check the ref and alert numbers in the preview. The alert repository must match
-a comparable local Git remote when available or the selected Cloud repository.
-Reuse the source key when you [save or publish and verify](README.md#save-or-publish-and-verify).
+## Identity and evidence
-## Reference
+The host, repository, alert number and ref identify a finding. The same alert
+on two refs keeps separate evidence. Missing security severity stays `unknown`.
-- To select another ref, add `--github-ref refs/heads/BRANCH` to the collector.
- Use `--github-state all` to include fixed and dismissed alerts, or repeat
- `--github-alert NUMBER` to select exact alerts regardless of state.
-- Save the collector’s complete JSON array. Omit field or token filters and
- `--full-output` when saving it for the reader.
-- The GitHub host, repository, alert number and ref identify a finding, so the
- same alert on two refs retains separate evidence. Missing security severity
- stays `unknown`.
-- See the [GitHub SDK examples](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud)
- for programmatic collection and destination-specific normalization.
+To collect with the SDK instead of `gh`, pass `githubHost` and a `githubToken`
+for that host. [GitHub SDK examples](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud)
diff --git a/docs/scanner-imports/github-dependabot.md b/docs/scanner-imports/github-dependabot.md
index da9015c73..eeaabaa61 100644
--- a/docs/scanner-imports/github-dependabot.md
+++ b/docs/scanner-imports/github-dependabot.md
@@ -1,68 +1,70 @@
# Import GitHub Dependabot findings
-Import Dependabot alerts from one GitHub repository. An alert identifies a
-dependency occurrence in a manifest. Its advisory describes the vulnerability.
+Import native Dependabot alerts from one repository. Each alert identifies a
+dependency occurrence. Its advisory describes the vulnerability.
## Quick start
-[Enable external imports](README.md#preview-a-report) and
-[export the repository alerts](#export-repository-alerts). From the matching
-checkout root, replace the file path, hostname, and repository in this preview.
+[Enable external imports](README.md#preview-a-report). From the matching
+checkout, set a private report path outside the checkout. Choose a source key
+for this host, repository and alert family, or reuse your existing Dependabot key.
```sh
-codex-security publish findings /private/path/dependabot.jsonl \
- --to local --repository . --provider github \
- --source-key github.com/OWNER/REPO/dependabot --dry-run --format json
+report=/private/path/dependabot.jsonl
+source_key=github.com/OWNER/REPO/dependabot
```
-## Import and verify
+**Saved report.** If you already have the complete REST alert objects,
+[preview the report](#preview-the-report).
-The alert repository must match a configured network remote when one is
-available. For a checkout with only filesystem remotes or no remote, verify
-the export belongs to it. [Save or publish and verify](README.md#save-or-publish-and-verify)
-using the same source key for later exports from this repository.
+### Export repository alerts
-## Reference
+In Codex, replace the host, repository and private output path in this request.
-### Identity and evidence
+> Export the native Dependabot alerts for https://HOST/OWNER/REPO across all
+> states and classifications. Follow the scoped GitHub read procedure in the
+> Codex Security triage-finding skill. Save each page as one compact JSON
+> array per line in a private temporary file beside /private/path/dependabot.jsonl.
+> Rename it to that path once you've verified and saved every page.
-The host, repository, and alert number identify an occurrence, so two alerts
-for one GHSA keep separate histories. Reimport updates included alerts and
-leaves omitted alerts in place.
+Keep every field, including `html_url`, `security_advisory` and
+`security_vulnerability`. Save an empty page as `[]`. Use the selected
+transport and identity, and ask before switching either.
+[Scoped GitHub read procedure](../../plugins/codex-security/skills/triage-finding/references/github-rest-intake.md#github-finding-retrieval)
-Each finding records the matched package, ecosystem, manifest path, vulnerable
-version range, first patched version when available, and advisory IDs. The
-native alert retains GitHub’s state and timestamps. An alert does not establish
-the installed version, an affected line, or a Codex assessment. The importer
-requires repository-relative manifest paths and rejects conflicts between
-alert identities, affected packages, or ranges.
+- **Connected app.** Confirm it returned unmodified REST alert objects and
+ enumerated every matching page.
+- **HTTPS.** Use a credential with Dependabot alerts read access. Request
+ `GET /repos/OWNER/REPO/dependabot/alerts?per_page=100` on the selected
+ host's API. Omit `state` and `classification` for all alerts the deployment
+ exposes. Note any unknown malware coverage. Reject redirects and rebuild
+ each page request on the same API origin and repository endpoint with the
+ requested filters. [Dependabot alerts endpoint](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository)
-To investigate a local alert, use the
-[`$resolve-dependency-alert` skill](../../plugins/codex-security/skills/resolve-dependency-alert/SKILL.md)
-with the saved alert and checkout. GitHub [code scanning](github-code-scanning.md)
-and [security advisories](github-security-advisories.md) have separate guides.
+### Preview the report
-### Export repository alerts
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider github --source-key "$source_key" --dry-run --format json
+```
+
+Check the alert numbers, packages and manifest paths. The repository must
+match a configured network remote when available. If the checkout has only
+filesystem remotes or no remote, verify the export belongs to it. Then
+[save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+
+## Identity and evidence
+
+The host, repository and alert number identify a dependency occurrence. Two
+alerts for the same GHSA keep separate histories. Repeat imports update the
+alerts you include and keep the ones you omit.
+
+Each finding records the matched package, ecosystem, manifest path, affected
+version range, advisory IDs and first patched version when available. The
+native alert retains GitHub's state and timestamps. The reader requires
+repository-relative manifest paths and rejects conflicting alert identities,
+packages or ranges.
-In Codex, replace the host, repository and private output path in this request:
-
-> Use the scoped GitHub read procedure in the Codex Security triage-finding skill.
-> Export the unmodified REST Dependabot alert objects for https://HOST/OWNER/REPO
-> across all states and classifications. Write each page as one compact JSON array
-> per line to a private temporary file beside /private/path/dependabot.jsonl.
-> Rename it to that destination only after verifying and saving every page.
-
-Follow the [scoped GitHub read procedure](../../plugins/codex-security/skills/triage-finding/references/github-rest-intake.md#github-finding-retrieval)
-for the selected transport and identity. Ask before changing either. A connected
-app must return complete, unmodified REST alert objects, including `html_url`,
-`security_advisory` and `security_vulnerability`, and confirm it enumerated every
-matching page. For HTTPS, use a credential with Dependabot alerts read access to request
-`GET /repos/OWNER/REPO/dependabot/alerts?per_page=100` on the selected host's API. Omit `state` and `classification` to export every alert
-the deployment exposes. Note any unknown malware coverage. For HTTPS,
-reject redirects and rebuild each next page on the same API origin and repository
-endpoint with the requested filters. [Dependabot alerts endpoint](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository)
-
-Keep every field. Write each successful page as one compact JSON array per line,
-including `[]` for an empty page. Write to a private temporary file in the
-destination directory outside the checkout, then rename it to the requested
-output path only after all pages have been verified and saved.
+Use the saved alert and checkout to check the installed version and trace
+whether the vulnerable code is used. An alert alone supplies no affected line
+or Codex assessment. [Resolve a dependency alert](../../plugins/codex-security/skills/resolve-dependency-alert/SKILL.md)
diff --git a/docs/scanner-imports/github-security-advisories.md b/docs/scanner-imports/github-security-advisories.md
index cbdcd0bf9..6742f5a43 100644
--- a/docs/scanner-imports/github-security-advisories.md
+++ b/docs/scanner-imports/github-security-advisories.md
@@ -1,60 +1,71 @@
# Import GitHub Security Advisories
-Import repository disclosures or selected entries from GitHub's global advisory
-database. Use the affected packages and version ranges to investigate whether
-a dependency in your checkout is affected.
+Use the JSON array from `codex-security import github-advisories` to import
+repository disclosures or selected GitHub global advisories. Each advisory
+lists the packages and version ranges it affects.
## Quick start
-Sign in with `gh auth login`. For GitHub Enterprise, set `GH_HOST` to the host
-you signed in to. If `gh` is unavailable, the SDK accepts `githubHost` and a
-`githubToken` for that host.
-
-From the destination checkout root, set `repo` to its GitHub
-repository and `source_key` to your existing advisories key exactly, including
-case. For a first import, choose a key for the host, repository and finding
-family. Replace `/path/to/private/reports` with an existing private directory
-outside the checkout. Collect published advisories as a complete JSON array
-without field or token filters or `--full-output`, then preview the saved file.
+[Enable external imports](README.md#preview-a-report). From the destination
+checkout, set the repository and source key. For GitHub Enterprise, export
+`GH_HOST` with your hostname first. For a repeat import, use the exact
+advisories key from your previous preview, including case.
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
repo=OWNER/REPO
-source_key=github.com/example/project/security-advisories
-out=$(mktemp -d "/path/to/private/reports/github.XXXXXX") &&
- codex-security import github-advisories "$repo" --format json > "$out/advisories.json" &&
- codex-security publish findings "$out/advisories.json" \
- --to local --repository . --provider github \
- --source-key "$source_key" --dry-run --format json
+source_key="${GH_HOST:-github.com}/$repo/security-advisories"
```
-## Import and verify
+**Saved report.** Set `report=/private/path/advisories.json` if you already
+have the collector's complete JSON array.
-Check the advisory IDs and source in the preview. For repository advisories, the
-source must match a comparable local Git remote when available or the selected
-Cloud repository. Use a source key separate from code scanning and Dependabot
-when you [save or publish and verify](README.md#save-or-publish-and-verify).
+**Export from GitHub.** Sign in to the selected host with `gh auth login`.
+Choose a repository or global export. Use a private temporary directory
+outside the checkout. Omit output filters, token limits and `--full-output`
+so the reader gets the complete array.
-## Reference
+For published repository advisories, run the command below. To list another
+state, add `--github-state draft`, `triage` or `closed`. To select specific
+IDs, repeat `--github-advisory GHSA-xxxx-xxxx-xxxx` and omit `--github-state`.
+Private advisories require repository advisory read permission and access to
+the disclosures.
-- **Repository advisories.** Repeat `--github-advisory GHSA-xxxx-xxxx-xxxx` to select exact
- IDs. To list an unpublished state instead, pass `--github-state draft`,
- `triage`, or `closed`. Private advisories require repository advisory read
- permission and access to the disclosures.
-- **Global advisories.** Add `--github-advisory-source global` and at least one
- `--github-advisory GHSA-xxxx-xxxx-xxxx` to the collector. The repository argument selects
- the context for investigation. A global record has no source repository.
-- An advisory retains the GHSA ID, reported packages and affected version
- ranges. Check the installed versions in your repository separately. For
- programmatic imports, see the [advisory SDK examples](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately).
+```sh
+report=
+out=$(mktemp -d) &&
+ codex-security import github-advisories "$repo" --format json > "$out/advisories.json" &&
+ report="$out/advisories.json"
+```
-To collect a specific global advisory, use the same shell and replace the
-example ID. Preview `"$out/global-advisories.json"` with the same command and
-advisories source key. Each finding’s ID already distinguishes global and
-repository scope.
+For global advisories, supply at least one GHSA ID. The repository argument
+names the repository where you'll investigate the advisory.
```sh
-codex-security import github-advisories "$repo" \
- --github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
- --format json > "$out/global-advisories.json"
+report=
+out=$(mktemp -d) &&
+ codex-security import github-advisories "$repo" --github-advisory-source global \
+ --github-advisory GHSA-2345-6789-cfgh --format json > "$out/advisories.json" &&
+ report="$out/advisories.json"
```
+
+**Preview the report.**
+
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider github --source-key "$source_key" --dry-run --format json
+```
+
+Check the GHSA IDs and whether each advisory came from the repository or the
+global database. Repository disclosures must match a comparable local Git
+remote when available, or the selected Cloud repository. If the preview
+matches, [save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+
+## Identity and evidence
+
+Repository and global advisories have distinct finding IDs, even when they
+share a GHSA ID and source key. A global advisory has no source repository.
+Compare the affected package ranges with the versions installed in your
+checkout to decide whether the advisory applies.
+
+To collect with the SDK instead of `gh`, pass `githubHost` and a `githubToken`
+for that host. [Advisory SDK examples](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately)
diff --git a/docs/scanner-imports/inspector.md b/docs/scanner-imports/inspector.md
index 88ae3d376..f527b7889 100644
--- a/docs/scanner-imports/inspector.md
+++ b/docs/scanner-imports/inspector.md
@@ -1,86 +1,85 @@
# Import Amazon Inspector findings
-Import package and code vulnerabilities from one Amazon Inspector Code Security
-repository. Findings from EC2, ECR, Lambda, and network resources are excluded.
+Import Inspector2 `ListFindings` JSON for one Code Security repository.
+Package and code vulnerabilities are supported. EC2, ECR, Lambda, and network
+findings are excluded.
## Quick start
-[Enable external imports](README.md#preview-a-report) and
-[export the repository findings](#export-repository-findings). In your SCM
-integration, verify the Inspector project ARN and set `VERIFIED_PROJECT_ARN`
-to that value. From the matching checkout root, preview the file with the
-verified Git URL and your source key. Omit `--inspector-project-arn` when the
-findings already include the matching native Git URL.
+[Enable external imports](README.md#preview-a-report) and open the matching
+checkout. Verify the repository's Git URL in your SCM integration. If
+Inspector identifies the repository by project ARN, set `VERIFIED_PROJECT_ARN`
+to the full ARN you verified there.
+
+**Saved report.** Use a complete repository export or select full native rows
+by ARN within its `findings` array. Set `report` and skip to the preview.
```sh
-codex-security publish findings /private/path/inspector.json \
- --to local --repository . --provider inspector \
- --source-repository-url https://github.com/example/project \
- --inspector-project-arn "$VERIFIED_PROJECT_ARN" \
- --source-key inspector/account-alias/us-east-1/example/project \
- --dry-run --format json
+report=/private/path/inspector.json
```
-## Import and verify
+### Export repository findings
-Check the finding ARNs and repository in the preview, then
-[save or publish and verify](README.md#save-or-publish-and-verify). For a Cloud
-retry, supply the same verified ARN and Git URL used to prepare the submission.
+With `inspector2:ListFindings` permission, replace the account, Region, and
+full repository resource ID below with values from Inspector coverage. Project
+names can match several integrations.
-## Reference
+```sh
+report=
+umask 077
+out=$(mktemp -d) &&
+ aws inspector2 list-findings --region us-east-1 --output json \
+ --filter-criteria '{
+ "awsAccountId":[{"comparison":"EQUALS","value":"ACCOUNT_ID"}],
+ "resourceType":[{"comparison":"EQUALS","value":"CODE_REPOSITORY"}],
+ "resourceId":[{"comparison":"EQUALS","value":"REPOSITORY_RESOURCE_ID"}]
+ }' > "$out/inspector.json.tmp" &&
+ mv "$out/inspector.json.tmp" "$out/inspector.json" &&
+ report="$out/inspector.json"
+```
-### Identity and repository mapping
+Start on the first page and let the AWS CLI fetch all pages. Omit
+`--starting-token`, `--no-paginate`, `--max-items`, and `--query`. The
+importer rejects continuation tokens. A final page saved on its own can look
+like a complete export. [AWS CLI export](https://docs.aws.amazon.com/cli/latest/reference/inspector2/list-findings.html) · [Inspector repository fields](https://docs.aws.amazon.com/inspector/v2/APIReference/API_CodeRepositoryDetails.html)
-A finding ARN identifies an occurrence within the source key. Reuse the key
-across exports to update matching ARNs. Omitted findings and empty exports
-leave earlier occurrences in place.
+For selected ARNs, keep the Region, account, and repository filters. Add a
+`findingArn` filter with one
+`{"comparison":"EQUALS","value":"FINDING_ARN"}` per ARN, up to 10 per request.
+Combine every batch's fully paginated `findings` array in one
+`{"findings":[...]}` report. [AWS Codex plugin](https://github.com/aws/agent-toolkit-for-aws#codex) · [Inspector filter limits](https://docs.aws.amazon.com/inspector/v2/APIReference/API_FilterCriteria.html#inspector2-Type-FilterCriteria-findingArn)
-Package findings retain the advisory and reported dependency versions. Code
-findings retain detector details and safe repository-relative locations when
-available. Native status, severity, and remediation remain source evidence.
-A closed or suppressed finding stays unassessed.
+### Import and verify
-Custom GitHub hosts need a native GitHub provider hint for Cloud publication.
-Self-managed GitLab is supported locally. If the GitLab web URL includes a
-prefix the SSH clone URL omits, use the verified HTTPS clone URL as a checkout
-remote. Keep the verified URL’s path casing on custom hosts. For home-relative
-SSH paths, verify the account when the URL omits the login. SDK callers can
-pass verified ARN-to-URL pairs through `inspectorProjectMap` for raw and
-normalized imports.
+Preview the report with your verified Git URL and source key. If the native
+findings already include the matching Git URL, omit `--inspector-project-arn`.
-### Export repository findings
-
-In Inspector coverage, find the account, Region, and full resource ID for the
-repository. Project names can match several integrations. With
-`inspector2:ListFindings` permission, replace the example Region, account ID, and
-repository resource ID in this export.
-
-For ARNs selected with the [AWS Codex plugin](https://github.com/aws/agent-toolkit-for-aws#codex),
-keep the Region, account, and repository filters below. Add a `findingArn` array
-with one `{"comparison":"EQUALS","value":"FINDING_ARN"}` per ARN, up to
-[10 per request](https://docs.aws.amazon.com/inspector/v2/APIReference/API_FilterCriteria.html#inspector2-Type-FilterCriteria-findingArn).
-Combine the native `findings` arrays from all fully paginated batches into one
-`{"findings":[...]}` report. From a saved scoped export, select those rows locally.
-If the selected rows cannot establish the repository together, request a native
-capture of those same ARNs with the missing evidence. Before import, verify the
-preview contains each requested ARN once, no other ARNs, and no exclusions.
-
-```bash
-set -eu
-umask 077
-out=$(mktemp -d)
-aws inspector2 list-findings --region us-east-1 --output json \
- --filter-criteria '{
- "awsAccountId":[{"comparison":"EQUALS","value":"ACCOUNT_ID"}],
- "resourceType":[{"comparison":"EQUALS","value":"CODE_REPOSITORY"}],
- "resourceId":[{"comparison":"EQUALS","value":"REPOSITORY_RESOURCE_ID"}]
- }' > "$out/inspector.json.tmp" &&
- mv "$out/inspector.json.tmp" "$out/inspector.json"
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider inspector --source-repository-url https://github.com/example/project \
+ --inspector-project-arn "$VERIFIED_PROJECT_ARN" \
+ --source-key inspector/account-alias/us-east-1/example/project \
+ --dry-run --format json
```
-Start an export on the first page with AWS CLI automatic pagination enabled.
-Omit `--starting-token`, `--no-paginate`, `--max-items`, and `--query`. The
-importer rejects continuation tokens but cannot distinguish a final page
-saved on its own from a complete export. See the
-[AWS CLI export](https://docs.aws.amazon.com/cli/latest/reference/inspector2/list-findings.html)
-and [Inspector repository fields](https://docs.aws.amazon.com/inspector/v2/APIReference/API_CodeRepositoryDetails.html).
+Check the repository and finding ARNs. For a selection, verify that each
+requested ARN appears once, with no other ARNs or exclusions. If the selected
+rows lack repository evidence, export those ARNs again with the missing fields.
+Then [save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+For Cloud retries, reuse the Git URL and any project ARN from the preview.
+
+## Identity and repository mapping
+
+Within a source key, reimporting an ARN updates the existing finding. Local
+findings omitted from later exports stay in the workbench. Package findings
+retain the advisory and dependency versions. Code findings retain detector
+details and reported repository-relative locations. Inspector status, severity, and
+remediation are source evidence. New closed or suppressed findings start as
+`not_assessed`.
+
+Custom GitHub hosts need a native GitHub provider hint for Cloud. For local
+imports from self-managed GitLab, use the verified HTTPS clone URL if SSH
+omits a web path prefix. Preserve path casing on custom hosts. For
+home-relative SSH paths that omit the login, verify the account. SDK callers
+can pass verified ARN-to-URL pairs through `inspectorProjectMap` for raw and
+normalized imports.
diff --git a/docs/scanner-imports/opengrep.md b/docs/scanner-imports/opengrep.md
index ec5978c30..d07922991 100644
--- a/docs/scanner-imports/opengrep.md
+++ b/docs/scanner-imports/opengrep.md
@@ -1,22 +1,33 @@
# Import OpenGrep findings
-Import native OpenGrep JSON, plain or gzipped, to retain observations,
-available traces and scan diagnostics.
+Use native OpenGrep JSON, plain or gzipped. A scan can return matches alongside
+parse errors or timeouts. The preview shows both.
## Quick start
-[Enable external imports](README.md#preview-a-report). From the scanned
-checkout root, preview the saved JSON using its credential-free HTTP(S) repository
-URL and an OpenGrep-specific source key. To get a new report,
-[run OpenGrep locally](#diagnostics-and-coverage).
+[Enable external imports](README.md#preview-a-report). From the scanned checkout
+root, choose a saved report or run OpenGrep in the same shell.
-For an existing report, set its path in the same shell.
+**Saved report.** Set the path to your OpenGrep JSON file.
```sh
opengrep_report=../reports/opengrep.json
```
-Preview the selected report.
+**Run OpenGrep.** Supply your rules and save the report outside the checkout.
+Add `--verbose` for details about skipped targets. Check the scan's exit status.
+[OpenGrep output options](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/cli_scan/Scan_CLI.ml)
+
+```sh
+opengrep_report=
+report_dir=$(mktemp -d) &&
+ opengrep scan --config /path/to/rules.yaml --json --output "$report_dir/opengrep.json" . &&
+ opengrep_report="$report_dir/opengrep.json"
+```
+
+**Preview the report.** Replace the example URL with the checkout's
+credential-free HTTP(S) URL. Choose a distinct OpenGrep source key for your
+organization, project and branch.
```sh
codex-security publish findings "$opengrep_report" --to local --repository . \
@@ -24,55 +35,26 @@ codex-security publish findings "$opengrep_report" --to local --repository . \
--source-key opengrep/example/project/main --dry-run --format json
```
-## Import and verify
-
-Check the findings, exclusions and `report.errors`, including when the
-findings list is empty. Keep `--provider opengrep` for
-[local import or Cloud publication](README.md#save-or-publish-and-verify).
-Both destinations store `semgrep` as the provider and record OpenGrep in
-`details.scanner_origin`.
-
-## Reference
+Check the findings, exclusions and `report.errors`, even if the findings list
+is empty. Cloud requires at least one supported finding. Keep `--provider opengrep`
+when you [save locally or publish to Cloud](README.md#save-or-publish-and-verify).
-### Provider identity and evidence
+## Provider identity and evidence
-Use a distinct OpenGrep source key for the organization, project and branch.
-The rule, path and range identify an occurrence. Moving a match or changing
-its Windows path spelling can create a new record.
-
-Multiple traces at one occurrence are grouped. Evidence retains the rule
-level, snippets, ignored state and fingerprints when supplied. Severity is
-`unknown` because OpenGrep levels such as `ERROR` describe rule matches.
-If individually valid traces together exceed the Cloud 256 KiB limit, the
-whole occurrence is excluded. [Imported evidence](schema-guide.md)
-
-### Diagnostics and coverage
-
-To create a report, run OpenGrep with your rules from the repository root
-and save native JSON outside the checkout. Add `--verbose` for skipped-target
-details. Preview the file after the scan succeeds.
-[OpenGrep output options](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/cli_scan/Scan_CLI.ml)
-
-```sh
-opengrep_report=
-report_dir=$(mktemp -d) &&
- opengrep scan --config /path/to/rules.yaml --json --output "$report_dir/opengrep.json" . &&
- opengrep_report="$report_dir/opengrep.json"
-```
+Both destinations store `semgrep` as the provider and `OpenGrep` in
+`details.scanner_origin`. The rule, path and range identify each occurrence.
+Moving a match or changing the spelling of a Windows path can create a new
+record. [Imported evidence](schema-guide.md)
-The reader accepts native JSON only. A report can contain matches alongside
-parse errors or timeouts. Check the scanner's exit status and retain the
-original JSON for run-wide details. The preview includes run metadata in
-`report`. Stored findings keep the version, raw observations in
-`source_data.results` and the diagnostic count in `source_data.scan_error_count`.
-Cloud needs at least one supported finding.
+The reader groups traces at the same occurrence. It keeps the rule level,
+snippets, ignored state and fingerprints when present. Severity is `unknown`
+because OpenGrep levels such as `ERROR` describe rule matches. Cloud excludes
+the whole occurrence if individually valid traces together exceed its 256 KiB
+evidence limit.
-### Assess an imported finding locally
+## Diagnostics and coverage
-Use the local record's `id` with `listLocalExternalFindings({ repository, id })`.
-On a `CodexSecurity` instance, pass `record.evidence` to
-`security.validate({ repositoryPath, finding: record.evidence })` using the
-checkout for the scanned revision. This sends evidence to your configured
-model provider and returns a separate assessment. The stored import remains
-`not_assessed`. [SDK validation example](../../sdk/typescript/README.md#validate-an-existing-finding)
-and [host-provided validation](../../sdk/typescript/docs/validate-records.md)
+Keep the original report for run-wide diagnostics. The preview includes the
+scan metadata in `report`. Each stored finding keeps the scanner version, the
+observations in `source_data.results` and the diagnostic count in
+`source_data.scan_error_count`.
diff --git a/docs/scanner-imports/semgrep.md b/docs/scanner-imports/semgrep.md
index 9a9e96af0..5a69c9598 100644
--- a/docs/scanner-imports/semgrep.md
+++ b/docs/scanner-imports/semgrep.md
@@ -1,8 +1,8 @@
# Import Semgrep findings
-Import native Code CLI or CI JSON to retain severities and available snippets.
-Self-contained Semgrep SARIF 2.1.0 is also supported. Either format can be gzipped.
-For selected findings from the Semgrep Platform API, use the
+Use native Semgrep Code CLI or CI JSON to keep severity and available snippets.
+You can also import self-contained Semgrep SARIF 2.1.0. Either format can be
+gzipped. For selected SAST findings from the Platform API, use the
[local SDK example](#import-selected-semgrep-platform-sast-findings-with-the-sdk).
## Quick start
@@ -10,18 +10,31 @@ For selected findings from the Semgrep Platform API, use the
In Codex, [import selected Guardian findings](#import-selected-guardian-findings) with your existing Semgrep sign-in.
For a whole project and ref, use the [Web API collector](#collect-a-platform-project-and-branch).
-[Enable external imports](README.md#preview-a-report). From the scanned checkout root,
-preview a saved SAST report using the repository's credential-free HTTP(S) URL
-and a stable key for the organization, project and branch. If you need a report,
-[capture one with Semgrep](#ci-artifacts).
+[Enable external imports](README.md#preview-a-report). From the scanned checkout
+root, choose a saved report or run Semgrep in the same shell.
-For an existing report, set its path in the same shell.
+**Saved report.** Set the path to your Code report. For a `semgrep ci`
+artifact, check that the job scanned only Code. The policy and baseline
+determine which matches the report contains. Exit 1 can mean the job found
+blocking matches and produced a valid report.
```sh
semgrep_report=../reports/semgrep.json
```
-Preview the selected report.
+**Run Semgrep.** Supply your SAST rules and write the JSON to a private
+directory outside the checkout. [Semgrep CLI reference](https://docs.semgrep.dev/cli-reference)
+
+```sh
+semgrep_report=
+report_dir=$(mktemp -d) &&
+ semgrep scan --config /path/to/sast-rules.yaml --json-output "$report_dir/semgrep.json" . &&
+ semgrep_report="$report_dir/semgrep.json"
+```
+
+**Preview the report.** Replace the example URL with the checkout's
+credential-free HTTP(S) URL. Use a stable source key for the organization,
+project and branch.
```sh
codex-security publish findings "$semgrep_report" --to local --repository . \
@@ -29,12 +42,9 @@ codex-security publish findings "$semgrep_report" --to local --repository . \
--source-key example/project/main --dry-run --format json
```
-## Import and verify
-
-Check the declared source URL against the checkout's Git remote. With an empty
-or wholly excluded report, the preview alone does not establish a repository match.
-[Save or publish and verify](README.md#save-or-publish-and-verify) using the
-same source URL and key. Cloud uses the `semgrep` provider.
+Check the findings, exclusions and source URL. If the preview has no accepted
+findings, verify the URL against the checkout's Git remote yourself. Keep the
+same URL and key when you [save locally or publish to Cloud](README.md#save-or-publish-and-verify).
## Import selected Guardian findings
@@ -292,58 +302,39 @@ to store the native finding as JSON text. Its local ID and source finding ID sta
the same, and its version increases once. Replaying the same evidence again
reports it as unchanged.
-## Reference
-
-### CI artifacts
-
-Use a saved artifact from a Code-only `semgrep ci` job. Policy and baseline
-determine which matches it contains. Exit 1 can indicate blocking findings
-even when the report is valid. Check the job's product selection and exit status.
-
-To create a local report, run Semgrep from the repository root with your
-SAST rules. Write to a private directory outside the checkout. After a
-successful scan, use that file in the preview above. [Semgrep CLI reference](https://docs.semgrep.dev/cli-reference)
-
-```sh
-semgrep_report=
-report_dir=$(mktemp -d) &&
- semgrep scan --config /path/to/sast-rules.yaml --json-output "$report_dir/semgrep.json" . &&
- semgrep_report="$report_dir/semgrep.json"
-```
-
-### Evidence and identity
+## Evidence and identity
Native JSON retains the result, rule, CWE IDs, range, snippets and ignored
-state when supplied. SARIF retains the selected rule and result, including
-traces and fixes. SARIF `error` imports as high even if the original severity
-was critical. Check Cloud exclusions for deeply nested traces.
+state when present. SARIF retains the selected rule and result, including
+traces and fixes. SARIF `error` imports as high even if Semgrep assigned
+critical severity. Check Cloud exclusions for deeply nested traces.
[Semgrep output fields](https://docs.semgrep.dev/semgrep-appsec-platform/json-and-sarif)
-The match ID uses JSON `extra.fingerprint` or SARIF `matchBasedId/v1`.
-Reimporting the same fingerprint under the same source key and repository
-updates its location. If the fingerprint is absent or says `requires login`,
-the ID uses rule, literal path and range. Moving the match then creates a new
-record. [Imported evidence and identity](schema-guide.md)
-
-For CLI/CI JSON and SARIF, use SAST-only rules. Identifiable Supply Chain and Secrets results are
-excluded, but SARIF can omit the product metadata. Scan errors or unsuccessful
-SARIF invocations stop import. Direct artifact URIs and native `%SRCROOT%`
-paths can supply locations. Indexed artifacts or unresolved bases remain in
-raw evidence and require a fingerprint for identity. Use the original report
-for run-wide inventories and timing.
-
-SDK callers pass `sourceRepositoryUrl` to the native or SARIF normalizer.
-When using `prepareNormalizedLocalImport` directly, pass the original SARIF
+The match ID comes from JSON `extra.fingerprint` or SARIF `matchBasedId/v1`.
+Under the same source key and repository, the fingerprint lets you update a
+match when it moves. If the fingerprint is missing or says `requires login`,
+the ID comes from the rule, literal path and range. Moving that match
+creates a new record. [Imported evidence and identity](schema-guide.md)
+
+For CLI/CI JSON and SARIF, use SAST-only rules. The reader excludes results
+it recognizes as Supply Chain or Secrets, but SARIF can omit product metadata.
+Scan errors or an unsuccessful SARIF invocation stop the import. Direct artifact URIs and native
+`%SRCROOT%` paths can supply locations. Indexed artifacts and unresolved bases
+stay in the raw evidence and need a fingerprint for identity. Keep the original
+report for run-wide inventories and timing.
+
+If you call the JSON or SARIF normalizer from the SDK, pass `sourceRepositoryUrl`.
+When calling `prepareNormalizedLocalImport` directly, pass the original SARIF
repository references in the third argument's `sourceRepositories`. Use
`{ url, platform: "github" }` for a verified custom GitHub host.
-### Import selected Semgrep Platform SAST findings with the SDK
+## Import selected Semgrep Platform SAST findings with the SDK
-Request `issue_type=sast` and save the original project lookup and findings
-pages as response text. Pass each findings page separately. The SDK checks
-every row on pages that contain a selected ID for conflicting product evidence.
-When a page contains only fields shared by several products, the original
-request filter identifies the product.
+**Collect the selection.** Request `issue_type=sast` and save the original
+project lookup and each findings page as response text. On any page with a
+selected ID, the SDK checks every row for conflicting product information.
+When rows contain only fields shared across products, the request filter
+establishes that the findings are SAST.
Use the IDs from the original Web API results for this SDK import. The SDK
accepts saved responses from an authorized operator. Fetching new Web API
@@ -351,23 +342,22 @@ responses requires read access. For selections made in Codex, use the
[Guardian workflow](#import-selected-guardian-findings).
[Findings Web API](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings)
-Use the full ref from the findings, such as `refs/heads/main` or
-`refs/tags/v1`. Supply the credential-free HTTP(S) repository URL you verified
-for the checkout. The native `project.url` and any selected
-`finding.repository.url` must match it exactly.
-
-- An exact finding URL is sufficient when `repository.id` is absent, even if
- the display names differ. If several projects share the URL and ref, choose
- the finding IDs from the intended project.
-- Any `repository.id` supplied must match `project.id`. When the finding has
- no URL, it must include both the matching project ID and a `repository.name`
- equal to the decoded, namespace-qualified path in the supplied URL, such as
- `example/project`.
-
-[Enable external imports](README.md#preview-a-report). In a Node.js project
-you control outside the scanned checkout, install `@openai/codex-security`
-and save this script as `preview-semgrep.mjs`. Set the deployment, ref,
-repository URL, source key and finding IDs for your selection. Pass the IDs as
+**Check the project and ref.** Use the full ref from the findings, such as
+`refs/heads/main` or `refs/tags/v1`. Verify the checkout's credential-free
+HTTP(S) URL. The native `project.url` must match it exactly. Check the
+repository fields on each selected finding.
+
+- If a finding has a `repository.url`, it must match the verified URL exactly.
+ That URL is enough when the ID is absent, even if display names differ.
+ If several projects share the URL and ref, choose IDs from the intended project.
+- If a finding supplies `repository.id`, it must match `project.id`. A finding
+ without a URL also needs the matching ID and a `repository.name` equal to
+ the decoded, namespace-qualified URL path, such as `example/project`.
+
+**Preview the selection.** [Enable external imports](README.md#preview-a-report).
+In a Node.js project you control outside the scanned checkout, install
+`@openai/codex-security` and save this script as `preview-semgrep.mjs`.
+Set the deployment, ref, repository URL, source key and finding IDs. Use
positive decimal strings without leading zeros to preserve 64-bit IDs.
```js
@@ -401,25 +391,24 @@ const prepared = await prepareNormalizedLocalImport(
console.log(JSON.stringify(prepared.preview, null, 2));
```
-Run the script from your SDK project. Pass the checkout, project response and
-each saved findings page as absolute paths.
+From your SDK project, pass the checkout, project response and each findings
+page as absolute paths.
```sh
node preview-semgrep.mjs /path/to/checkout /path/to/reports/semgrep-project.json \
/path/to/reports/semgrep-findings-1.json
```
-Review the repository, findings and exclusions. To save the selection, append
-`await prepared.import()` to a copy of the script in your SDK project and run
-that copy with the same inputs.
-[Read back the local records](README.md#save-or-publish-and-verify) using the
-checkout path from the preview.
-Keep the same source key on replay. Each occurrence is identified by deployment,
-project ID, SAST product, full ref and native finding ID.
-
-The stored evidence includes the selected finding and the project's ID, name
-and URL. Larger positive integer IDs are retained without rounding. Equivalent
-numeric spellings (`2` and `2.0`) and key order do not change the stored record.
-Preview excludes findings that lack both a native rule name and a message.
+Check the repository, findings and exclusions. To save the selection, append
+`await prepared.import()` to a copy of the script and run the copy with the
+same inputs. [Read back the local records](README.md#verify-the-import).
+
+Each occurrence uses the deployment, project ID, SAST product, full ref and
+native finding ID. Reuse the same source key for later imports. The stored
+evidence includes the selected finding and the project's ID, name and URL.
+The SDK preserves large positive IDs exactly. Key order and equivalent numeric
+spellings (such as `2` and `2.0`) leave the stored record unchanged.
+
+The preview excludes findings that lack both a native rule name and a message.
Only repository-relative files become locations. URI-like and directory-only
paths stay in the native evidence.
diff --git a/docs/scanner-imports/snyk.md b/docs/scanner-imports/snyk.md
index 1a417befb..88a4d4277 100644
--- a/docs/scanner-imports/snyk.md
+++ b/docs/scanner-imports/snyk.md
@@ -1,8 +1,8 @@
# Import Snyk findings
-Import dependency vulnerabilities from a saved `snyk test` JSON report, a
+Prefer native `snyk test` JSON for dependency vulnerabilities. It keeps
+individual dependency paths and remediation details. You can also import a
`snyk-findings-export/v1` plugin bundle or self-contained Open Source SARIF.
-Native CLI JSON preserves individual dependency paths and remediation details.
For existing monitored projects, collect Open Source or Code issues through the Snyk Issues API.
@@ -113,108 +113,105 @@ An already approved, pending request resumes with its saved evidence.
## Quick start
-[Enable external imports](README.md#preview-a-report). For a first local import,
-set the destination from the checkout root. Choose a key for the repository,
-branch, original scan target and format. If you ran Snyk in `services/api`,
-replace `root` in the example key with `services/api`.
+[Enable external imports](README.md#preview-a-report). From the checkout root,
+set the destination and choose a key for the repository, branch, original scan
+target and format. Replace `root` with your target if you scanned a
+subdirectory such as `services/api`.
```sh
snyk_repository=$(pwd -P)
snyk_source_key=github.com/example/project/main/root/native-sca
```
-For a repeat import, set `snyk_repository` and `snyk_source_key` to the
-previous local preview's exact `repository` and `source.source_key`. Keep the
-original destination even if it was a package subdirectory. Changing either
-value creates a separate set of records.
+For a repeat import, use the exact `repository` and `source.source_key` from
+your earlier local preview, even if you used a package subdirectory as the
+destination. Changing either value creates a separate set of records.
-Set `snyk_report` to the absolute path of your saved, ungrouped Open Source
-JSON report so it still resolves if you change directories.
+**Saved report.** Use an absolute path to the ungrouped Open Source JSON from
+the scan you want to import.
```sh
-snyk_report=/path/to/reports/snyk-open-source.json
+snyk_report=/private/path/snyk-open-source.json
```
-If you need a new report, [run the Snyk CLI](#native-cli-json) and keep the
-`snyk_report` it sets. Preview the selected report.
+**Scan with Snyk.** To collect a new report, run the authenticated Snyk CLI
+with the project's package tooling. From the directory containing
+`package.json`, run this in the same shell. Snyk exits with 1 when it finds
+vulnerabilities. A higher exit code stops the export.
+[Snyk CLI test](https://docs.snyk.io/developer-tools/snyk-cli/commands/test)
```sh
-codex-security publish findings "$snyk_report" --to local --repository "$snyk_repository" \
- --provider snyk --source-key "$snyk_source_key" \
- --dry-run --format json
+snyk_report=$(
+ snyk_dir=$(mktemp -d) || exit "$?"
+ file="$snyk_dir/snyk-open-source.json"
+ snyk_status=0
+ snyk test --file=package.json --json-file-output="$file" >&2 || snyk_status=$?
+ [ "$snyk_status" -le 1 ] || exit "$snyk_status"
+ [ -s "$file" ] && printf '%s\n' "$file"
+)
```
-## Import and verify
-
-Review coverage and exclusions, especially unsupported products and license
-records. Check the destination checkout when the report lacks a Git URL.
-[Save or publish and verify](README.md#save-or-publish-and-verify) with the
-same source key for subsequent exports in this format.
-
-## Reference
+For several projects under one scan root, replace `--file=package.json` with
+`--all-projects --fail-fast` so a scan failure stops collection. Without
+`--fail-fast`, Snyk can skip projects. An error in a saved project result
+stops import. Use separate reports and keys for independent scan roots.
-Use the saved report for an earlier scan. `snyk test` and the Studio plugin’s
-`snyk-findings-export` scan the current workspace. Evo MCP’s `query_issues`
-retrieves AI asset policy violations. [Studio export scope](https://github.com/snyk/studio-recipes/blob/3752dd05a462184dcce44af3c247f287b41e35de/plugins/codex/skills/snyk-findings-export/SKILL.md#L15-L20) · [Evo MCP tools](https://docs.snyk.io/agent-security/evo-by-snyk/platform-surfaces/evo-mcp-server#policies-and-issues)
-
-### Native CLI JSON
-
-To create a report, run the authenticated Snyk CLI with the project's package
-tooling. For a project with `package.json`, run this from its root. Exit 1
-means findings. A higher exit code stops acquisition. [Snyk CLI test](https://docs.snyk.io/developer-tools/snyk-cli/commands/test)
+**Preview the report.**
```sh
-snyk_report=
-report_dir=$(mktemp -d) || exit "$?"
-snyk_status=0
-snyk test --file=package.json --json-file-output="$report_dir/snyk-open-source.json" || snyk_status=$?
-if [ "$snyk_status" -gt 1 ]; then
- exit "$snyk_status"
-fi
-snyk_report="$report_dir/snyk-open-source.json"
+codex-security publish findings "$snyk_report" --to local --repository "$snyk_repository" \
+ --provider snyk --source-key "$snyk_source_key" \
+ --dry-run --format json
```
-For several projects under one scan root, use `--all-projects --fail-fast`
-in place of `--file=package.json`. Without `--fail-fast`, Snyk can omit
-projects it could not scan. Project errors present in the input stop import.
-Keep independent scan roots in separate reports with separate keys.
-
-A native occurrence is identified by package manager, manifest, advisory,
-package name and version, and dependency path. The reader retains the
-vulnerability, project context and suggested fixes. Manifest paths are
-target-relative. [Native result fields](https://github.com/snyk/cli/blob/main/src/lib/snyk-test/legacy.ts)
-
-### Snyk plugin export
-
-From the repository's Git root, ask the Snyk plugin's `snyk-findings-export`
-skill to run an SCA-only scan and save the bundle outside the checkout.
-Use the bundle as input and a key ending in `plugin-sca`. The bundle retains
-collection context, ignored status and each selected MCP record. The mapper
-can shorten descriptions and omit alternate dependency paths. Paths are
-target-relative. A dirty workspace does not establish the scanned commit.
-[Install the Snyk plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
-and [SCA mapper](https://github.com/snyk/studio-mcp/blob/main/internal/oss/map.go)
-
-### SARIF compatibility
-
-For SARIF, replace `--json-file-output` with `--sarif-file-output` and keep the
-exit-code check above. Use a key ending in `sarif-sca`. SARIF groups an
-advisory's occurrences and exposes one package coordinate. The reader
-retains the rule, result and report context. Use a self-contained report. Manifest paths are
-optional. If present, use direct URIs. Indexed or base-relative manifest
-locations are unsupported. [Snyk Open Source SARIF formatter](https://github.com/snyk/cli/blob/main/src/lib/formatters/open-source-sarif-output.ts)
-
-### Identities and provenance
+Check the expected advisories, package versions and excluded records,
+especially license findings. If the report lacks a Git URL, confirm the
+destination checkout yourself.
+[Save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
+
+## Native CLI JSON
+
+Package manager, manifest, advisory, package name and version, and dependency
+path identify each native occurrence. The reader keeps the vulnerability,
+project context and suggested fixes. Manifest paths are relative to the scan
+target. For native tests of a public GitHub URL, the reader checks the
+repository in the report's `path` against the destination. Any `#ref` stays
+in the original evidence.
+[Native result fields](https://github.com/snyk/cli/blob/main/src/lib/snyk-test/legacy.ts)
+
+## Snyk plugin export
+
+From the Git root, ask the Snyk plugin's `snyk-findings-export` skill to run
+an SCA-only scan and save the bundle outside the checkout. Set `snyk_report`
+to the bundle and use a key ending in `plugin-sca` for the preview. Like
+`snyk test`, the skill scans the current workspace. To import an earlier scan,
+use its saved report. Evo MCP's `query_issues` retrieves AI asset policy
+violations.
+[Install the plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex) · [Studio export scope](https://github.com/snyk/studio-recipes/blob/3752dd05a462184dcce44af3c247f287b41e35de/plugins/codex/skills/snyk-findings-export/SKILL.md#L15-L20) · [Evo MCP tools](https://docs.snyk.io/agent-security/evo-by-snyk/platform-surfaces/evo-mcp-server#policies-and-issues)
+
+The bundle keeps collection context, ignored status and each selected MCP
+record. The mapper can shorten descriptions and omit alternate dependency
+paths. Paths are relative to the scan target. The reader records a commit
+only for a clean workspace with a known revision.
+[SCA mapper](https://github.com/snyk/studio-mcp/blob/main/internal/oss/map.go)
+
+## SARIF compatibility
+
+Replace `--json-file-output` with `--sarif-file-output` in the scan command
+and keep the exit-code check. Use a source key ending in `sarif-sca`. Snyk
+groups an advisory's occurrences and reports one package coordinate. The
+reader keeps the rule, result and report context. Use self-contained SARIF
+with direct URIs for any manifest locations. Indexed and base-relative
+manifest locations are unsupported.
+[Snyk Open Source SARIF formatter](https://github.com/snyk/cli/blob/main/src/lib/formatters/open-source-sarif-output.ts)
+
+## Identities and provenance
Native JSON, plugin bundles and SARIF produce different source IDs. Give
-each format a separate key. Changes in collection context such as a plugin
-scan's `issueCount` can update a stored snapshot even if the occurrence
-stays the same. [Imported evidence and identity](schema-guide.md)
-
-For native tests of a public GitHub URL, the reader checks the repository in
-the report's `path` against the selected destination. Any `#ref` stays in the
-saved source evidence.
+each format a separate source key. A change in collection context, such as a
+plugin scan's `issueCount`, can update a stored snapshot of the same
+occurrence. [Imported evidence and identity](schema-guide.md)
-Known source Git URLs must match a comparable configured local remote when
-one is available, or the selected Cloud repository. Snyk Code, Container,
-IaC, SBOM results and hosted backlog responses use other formats.
+Known source Git URLs must match a comparable local remote when available,
+or the selected Cloud repository. Snyk Code, Container, IaC, SBOM results
+and hosted backlog responses use other formats.
diff --git a/docs/scanner-imports/sonar.md b/docs/scanner-imports/sonar.md
index 702ddffa8..8fddda6fe 100644
--- a/docs/scanner-imports/sonar.md
+++ b/docs/scanner-imports/sonar.md
@@ -1,87 +1,89 @@
# Import SonarQube Cloud findings
-Collect security issues for one project and branch or pull request. The
-collector uses the authenticated Sonar CLI and saves the selection in a
-capture you can import locally or publish to Cloud.
+Use `import sonar` to collect security issues for one project and branch or
+pull request. Replay its saved capture without signing in to Sonar. For
+issue-search JSON, [preview the native export](#use-a-native-json-export).
## Quick start
[Enable external imports](README.md#preview-a-report). From the matching
-checkout, sign in to the project's Sonar organization with browse access
-(`sonar auth login`). Preview a selection using project and issue keys from
-Sonar's Issues view or the SonarQube plugin for Codex.
-[Sonar CLI authentication](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide#step-2-authenticate)
+checkout, run `sonar auth login` with browse access to the project's Sonar
+organization. [Sonar CLI authentication](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide#step-2-authenticate)
+
+**Preview live issues.** Copy the project and issue keys from Sonar's Issues
+view or the SonarQube plugin for Codex. Replace the example keys and branch.
```sh
codex-security import sonar --sonar-project example_project --sonar-branch main \
--sonar-issue ISSUE_A --sonar-issue ISSUE_B --dry-run --format json
```
-A selection by key includes the requested security issues regardless of
-status. Omit `--sonar-issue` to preview open and confirmed security issues
-for the selected ref. For a pull request, replace `--sonar-branch main` with
+Repeated `--sonar-issue` selects the requested security issues regardless of
+status. Omit it to collect open and confirmed security issues for the selected
+ref. For a pull request, replace `--sonar-branch main` with
`--sonar-pull-request 42`. Omit both to use the project's main branch.
+Check the repository and ref. Compare the issue keys in
+`local.findings[].source_finding_id` and any `local.excluded` entries with
+your selection. Keep the private path returned in `capture`.
+
## Import and verify
-Review the repository, ref, issues and exclusions in the `import sonar`
-preview. Confirm using the private `capture` path it returned.
+**Save locally.** From the same checkout, pass the local preview's `capture`
+path. Omit `--yes` for an interactive prompt. In a script, use `--yes`
+after review.
```sh
codex-security import sonar "/path/from/local-preview.json" --yes
```
-To import locally **and** publish to Cloud, start from the same checkout.
-Replay needs no Sonar login. Use a separate file-backed ChatGPT login with
-access to the connected Cloud repository and an authorized environment on a
-deployment that accepts the `sonar` provider. Review the Cloud account,
-repository and environment, then confirm with the **new Cloud capture**.
+**Save locally and publish to Cloud.** [Sign in to Cloud](../../sdk/typescript/docs/cli.md#preview-and-publish)
+on a deployment that accepts the `sonar` provider. Preview the connected
+repository from the local capture.
```sh
codex-security import sonar "/path/from/local-preview.json" --to cloud --dry-run --format json
-codex-security import sonar "/path/from/cloud-preview.json" --to cloud --yes
```
-Read back the local records in the preview's `repository` and check the Cloud
-verification result if you published. Preview again if the checkout, state
-directory or destination changes. To resume an interrupted upload, reuse the
-approved capture and destination. [Readback and verification](README.md#save-or-publish-and-verify)
+Check the account, repository and any environment listed in `cloud`. Confirm
+with the new `capture` path from the successful Cloud preview.
+
+```sh
+codex-security import sonar "/path/from/cloud-preview.json" --to cloud --yes --format json
+```
-## Reference
+For [readback and verification](README.md#verify-the-import), use
+the preview's local `repository` path. Check `cloud` and any `cloudError`
+if you published.
-### Project and repository selection
+If the checkout, state directory or Cloud destination changes, preview the
+capture again. To resume an interrupted upload, reuse the approved capture
+and destination.
+
+## Project and repository selection
Omit `--sonar-project` only when the checkout's Git origin maps to exactly
-one project in the active organization. For monorepos, supply the project
-key. When a search exceeds 10,000 results, select issue keys.
-[SonarQube plugin](https://www.sonarsource.com/blog/now-available-sonarqube-plugin-for-codex/)
-and [Codex Security import workflow](../../plugins/codex-security/skills/publish-findings/SKILL.md#sonarqube-cloud-issues)
-
-If Sonar lacks a repository binding, the checkout uses an SSH host alias or
-Cloud preview finds no usable remote, verify the project's Git URL in Sonar.
-Pass it as `--source-repository-url` when previewing the capture. At least
-one comparable remote must match if the checkout has any. A changed fetch
-URL requires a new preview.
-
-Each Sonar issue key identifies one record within its source and repository.
+one project in the active organization. For a monorepo, supply the project
+key. If a search exceeds 10,000 results, select issue keys.
+[SonarQube plugin](https://www.sonarsource.com/blog/now-available-sonarqube-plugin-for-codex/) · [Codex Security import workflow](../../plugins/codex-security/skills/publish-findings/SKILL.md#sonarqube-cloud-issues)
+
+If Sonar lacks a repository binding, Git uses an SSH host alias or Cloud
+finds no usable remote, verify the project's Git URL in Sonar. Pass it as
+`--source-repository-url` when previewing the capture. At least one
+comparable remote must match if the checkout has any. Preview again if a
+fetch URL changes.
+
+Each issue key identifies one record within its source and repository.
Reimport updates its evidence, including file ranges and available data flows.
In a monorepo, repository-relative locations require a verified Sonar project
base directory.
-### Use a native JSON export
-
-For a saved `GET /api/issues/search` response, use a single page if it
-contains the complete result. Otherwise supply an array of all pages in
-order for the same project and ref. Pages can omit repository and ref context.
-Run the example from the checkout root and supply its verified repository URL.
-The example source key is for a new stream.
+## Use a native JSON export
-To update issues from an earlier capture, use its preview's `repository` path
-for `--repository` and its exact `sourceKey` (`sonar:<hash>`) for `--source-key`.
-The local `publish findings` preview shows `source.source_key`, and each stored
-record has a `sourceKey`. Updating a matching issue replaces its evidence.
-Native pages can omit the issue URL and repository-relative locations. Replay
-the capture to preserve those fields, or use another key to store both versions.
+Supply one complete `GET /api/issues/search` page or an ordered array of
+all pages for one project and ref. Pages can omit repository and ref context.
+Run this preview from the checkout root with the verified repository URL.
+The example starts a new source key.
```sh
codex-security publish findings ../reports/sonar-pages.json --provider sonar \
@@ -89,5 +91,10 @@ codex-security publish findings ../reports/sonar-pages.json --provider sonar \
--source-key sonarcloud.io/example/example_project/branch/main --dry-run --format json
```
-[Save and verify the native file](README.md#save-or-publish-and-verify) with the
-same `publish findings` command.
+To update issues from a capture, pass its preview's `repository` path and
+exact `sourceKey` (`sonar:<hash>`) as `--repository` and `--source-key`.
+Check `source.source_key` in the file preview or `sourceKey` on a stored
+record. Native pages replace matching evidence and can omit issue URLs and
+repository-relative locations. Replay the capture to retain those fields,
+or use another key to keep both versions.
+[Save or publish the native report and verify the result](README.md#save-or-publish-and-verify)
diff --git a/docs/scanner-imports/veracode.md b/docs/scanner-imports/veracode.md
index d105bd2ae..e15903568 100644
--- a/docs/scanner-imports/veracode.md
+++ b/docs/scanner-imports/veracode.md
@@ -1,56 +1,71 @@
# Import Veracode Static Analysis findings
-Import Findings API policy flaws from one Veracode application that maps to
-one source repository. Use the application context and `scan_type=STATIC`.
+Import existing policy flaws from Findings API pages for one Veracode
+application. Use the application context and `scan_type=STATIC`.
## Quick start
-[Enable external imports](README.md#preview-a-report) and
-[export the complete Findings API pages](#export-findings-api-pages) with read
-access to the application and Results API. From the matching checkout root,
-preview the file with its verified Git URL and a source key for this application.
+[Enable external imports](README.md#preview-a-report). Verify that the
+application maps to a single Git repository and open its checkout.
+
+**Saved report.** Set `report` to the complete Findings API page or array of
+pages for your selection. Preserve each page's HAL links and pagination fields.
```sh
-codex-security publish findings /private/path/policy-findings.json \
- --to local --repository . --provider veracode \
- --source-repository-url https://github.com/example/project \
- --source-key veracode/region/application-guid/static \
- --dry-run --format json
+report=/private/path/policy-findings.json
```
-## Import and verify
+**Export from Veracode.** With read access to the application and Results API,
+save and configure the [export script](#export-findings-api-pages). Capture
+the path it prints when the export succeeds.
+
+```sh
+report=$(bash "/private/path/export-veracode.sh")
+```
-Verify the application represents the destination repository. An application
-GUID or a backlog aggregated from several repositories cannot establish the
-mapping. [Save or publish and verify](README.md#save-or-publish-and-verify)
-using the same source key for repeat exports from this application and context.
+**Preview the report.** Use the verified Git URL and a source key for your
+region, application and scan context. The URL must match a comparable local
+remote when available, or the selected Cloud repository.
+
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider veracode --source-repository-url https://github.com/example/project \
+ --source-key veracode/region/application-guid/static \
+ --dry-run --format json
+```
-## Reference
+In each finding's `evidence.source_data`, check `applicationUrl` and the
+native `row.issue_id`. Review any excluded flaws. Reuse this key for exports
+from the same application and context.
+[Save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify).
-### Identity and evidence
+## Identity and evidence
-The API origin, application and context, and native `issue_id` identify one
-policy flaw. Build number, source line, CWE, and Pipeline flaw ID are separate
-fields. The original record retains numeric severity, CWE, flaw description,
-status, mitigation, and resolution. Location evidence includes the reported
-static analysis path, line, and module. The importer does not verify that the
-path exists in the checkout or infer a column or Git commit.
+The API origin, application, context and native `issue_id` identify a policy
+flaw. Build number, source line, CWE and Pipeline flaw ID are separate fields.
+The original row keeps the numeric severity, CWE, description, status,
+mitigation and resolution. Veracode reports the static analysis path, line
+and module. Check the path against the checkout yourself. The import supplies
+no column or Git commit.
-Imported findings start unassessed. Replaying an upstream resolution does not
-verify a fix. Omitted findings remain stored. `veracode static scan <package>`
-runs a new Pipeline Scan with different flaw IDs. Retrieve existing policy
-flaws with the Findings API export below. Sandbox, SCA, DAST, policy summaries,
-and converted SARIF also use other formats. [Veracode static scan](https://docs.veracode.com/r/veracode_static_scan)
+A Veracode resolution records upstream status. Assess the fix separately.
+The workbench keeps flaws omitted from later exports.
+`veracode static scan <package>` runs a new Pipeline Scan with different
+flaw IDs. Sandbox, SCA, DAST, policy summaries, converted SARIF and
+multi-repository backlogs fall outside this import.
+[Veracode static scan](https://docs.veracode.com/r/veracode_static_scan)
-For SDK replay with the Veracode provider, keep each finding’s original
-`source_finding_id` and `evidence.source_data` so the SDK can verify its
+For SDK replay, use the `veracode` provider and keep each finding's original
+`source_finding_id` and `evidence.source_data`. The SDK uses them to check the
application and repository.
-### Export Findings API pages
+## Export Findings API pages
-Set `VERACODE_APPLICATION_GUID` to the application GUID and `api` to the API
-origin for its region. This example uses HTTPie with the Veracode HMAC plugin
-and `jq`. It writes `policy-findings.json` in the temporary directory `$out`.
+Save this Bash script outside the checkout as `export-veracode.sh`. Export
+`VERACODE_APPLICATION_GUID` in your shell and set `api` in the script to the
+API origin for the application's region. The script uses HTTPie with the
+Veracode HMAC plugin and `jq`. Apply any Findings API filters in the request
+and keep the same selection on every page.
```bash
set -eu
@@ -74,12 +89,11 @@ while :; do
[ "$page" -lt "$pages" ] || break
done
jq -s '.' "$out/pages.stream" > "$out/report.tmp" &&
- mv "$out/report.tmp" "$out/policy-findings.json"
+ mv "$out/report.tmp" "$out/policy-findings.json" &&
+ printf '%s\n' "$out/policy-findings.json"
```
-Keep each page intact. Apply any Findings API filters when downloading the
-pages and use the same selection throughout. The importer checks page counts,
-application scope, and the selection reported in the HAL links. If the backlog
-changes during pagination, collect it again. See the
-[Veracode Findings API](https://docs.veracode.com/r/c_findings_v2_intro) and
-[policy and Pipeline conversion examples](https://github.com/veracode/veracode-pipeline-scan-results-to-sarif).
+Keep every page intact. The importer checks page counts, the application and
+the selection in the HAL links. If the backlog changes during pagination,
+collect the pages again.
+[Veracode Findings API](https://docs.veracode.com/r/c_findings_v2_intro) · [Policy and Pipeline conversion examples](https://github.com/veracode/veracode-pipeline-scan-results-to-sarif)
diff --git a/docs/scanner-imports/wiz.md b/docs/scanner-imports/wiz.md
index d31bb4d0f..d02b03bac 100644
--- a/docs/scanner-imports/wiz.md
+++ b/docs/scanner-imports/wiz.md
@@ -1,56 +1,59 @@
# Import Wiz findings
-Import saved Wiz package vulnerabilities, SAST findings, repository secrets or
-IaC findings. The file reader accepts native JSON, normalized JSONL and detailed
-repository package vulnerability CSV, including gzip-compressed files.
+Import Wiz package vulnerabilities, SAST findings, repository secrets or IaC
+findings from native JSON or normalized JSONL. For repository package
+vulnerabilities, you can also use a detailed CSV report. All three formats
+support gzip.
## Quick start
-For package vulnerabilities, apply the requested repository, branch or build,
-and finding filters where available in Wiz **Vulnerability Findings**. Choose
-**Save as → Report**, then **Repository Branch**,
-**JSON** and **Detailed** columns. Download the completed report outside the
-checkout. From the destination checkout root, set the path and replace `TENANT_ID`
-with your stable Wiz tenant identifier.
+[Enable external imports](README.md#preview-a-report). This example imports
+repository package vulnerabilities.
+
+**Saved report.** Choose the file for your repository and branch or build.
+With a connected Wiz account, list findings for the repository and family,
+then retrieve the selected records by Wiz finding ID. If a pull request
+scan event omits occurrence IDs, request a scoped native capture.
+
+**Export from Wiz.** In **Vulnerability Findings**, filter by repository,
+branch or build, and findings where available. Choose **Save as → Report**,
+then **Repository Branch**, **JSON** and **Detailed** columns. Download the
+completed report outside the checkout.
+
+**Preview the report.** From the checkout root, set the path and replace
+`TENANT_ID` with your Wiz tenant ID. Reuse the key for that tenant and
+finding family across exports and project filters.
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
report=../reports/wiz-packages.json
codex-security publish findings "$report" \
--to local --repository . --provider wiz \
--source-key TENANT_ID/vulnerability-finding --dry-run --format json
```
-## Import and verify
-
-For an explicit selection, proceed only if the JSON preview's `excluded` array
-is empty and `findings[].source_finding_id` lists each requested occurrence ID
-exactly once, with its family prefix where applicable, and no other IDs.
-Check that the preview covers the intended assets or builds and review excluded
-records. Reuse the source key for the same tenant and finding family across
-exports and project filters. [Save or publish and verify](README.md#save-or-publish-and-verify).
-
-## Reference
-
-- **Connected Wiz account.** List findings for the repository and family, then
- retrieve the selected records by Wiz finding ID. If a shared pull request scan
- event cannot identify each occurrence, request a scoped native capture.
-- **Native JSON.** Package vulnerabilities accept individual records or
- `data.vulnerabilityFindings.nodes`. SAST, repository secrets and IaC require
- the named `data.sastFindings.nodes`, `data.secretInstances.nodes` or
- `data.iacFindings.nodes` collection.
-- **Paginated API or MCP results.** Check every finding and inventory page for
- GraphQL `errors`, even when the page contains nodes. If any page reports an
- error, resolve it and collect a complete selection before combining pages.
- Put the selected nodes under the original collection name in one JSON object. If
- findings use inventory to identify their repository, finish the inventory
- pages too and combine their nodes under `data.versionControlResources.nodes`
- in the same object. Retain the final page info for each collection. An array
- or JSONL stream of GraphQL page envelopes cannot be imported.
-- **CSV.** Use **Detailed** repository package vulnerability columns. The reader
- requires a GitHub repository-branch URL and preserves each original cell.
- Other finding families require native JSON or an explicit normalized mapping.
-- Package findings retain the Wiz occurrence ID. SAST, repository secrets and
- IaC use `sast:`, `secret:` and `iac:` ID prefixes. See the
- [Wiz format reference](../../plugins/codex-security/skills/publish-findings/references/wiz-import.md#finding-formats)
- for required fields, repository mapping and normalized JSONL.
+Check the assets, builds and exclusions. For selected IDs, verify that
+`findings[].source_finding_id` lists each requested occurrence once and no
+others, and that `excluded` is empty. Include the family prefix shown below.
+[Save locally or publish to Cloud and verify the result](README.md#save-or-publish-and-verify)
+
+## Finding formats and IDs
+
+| Native JSON finding family | Where to put the records | Occurrence ID |
+| -------------------------- | -------------------------------------------------------- | ------------- |
+| Package vulnerabilities | Individual records or `data.vulnerabilityFindings.nodes` | Wiz ID |
+| SAST | `data.sastFindings.nodes` | `sast:<id>` |
+| Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
+| IaC | `data.iacFindings.nodes` | `iac:<id>` |
+
+**Paginated API or MCP results.** Check each finding and inventory page
+for GraphQL `errors`, even if it contains nodes. Resolve errors before
+combining pages. In one JSON object, put the selected nodes under their
+original collection name. If findings need inventory to identify their
+repository, include all inventory pages' nodes under
+`data.versionControlResources.nodes`. Keep the final page info for each
+collection.
+
+**CSV and normalized JSONL.** Detailed package CSV requires a GitHub
+repository-branch URL and preserves each original cell. For other families,
+use their named JSON collection or map the fields to normalized JSONL.
+[Wiz format reference and repository mapping](../../plugins/codex-security/skills/publish-findings/references/wiz-import.md#finding-formats)
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index dbaed41a8..87ef304ba 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1381,29 +1381,43 @@ SARIF compatibility, and the local preview.
## Publish findings to Cloud
-Use the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) to prepare a supported input
-and follow the [shared publication steps](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
-to preview and confirm it. The following settings and result fields apply to
-scanner publication across providers.
+Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
+If you're collecting live issues with `import sonar`, [publish from the Sonar preview's saved capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
### Preview and publish
-With `--to cloud`, `--repository` accepts a connected GitHub or GitHub Enterprise
-repository URL or Cloud repository ID. A unique URL and its ID resolve to the
-same destination and saved submission. Use the ID if several connectors share
-the URL. Use a file-backed ChatGPT login for the selected Cloud
-account. If you use your regular Codex login, set `cli_auth_credentials_store = "file"`
-in Codex `config.toml` and sign in again. API-key-only and keyring-only logins
-cannot publish. The destination needs an authorized environment. It can receive
-scanner findings before its first native scan.
-
-Cloud preview reads current source versions and lists the account, endpoint,
-repository, and environments. Existing source records keep their environment.
-New records use the repository's current authorized default. The terminal
-summarizes severities, shows up to five finding IDs and titles, and identifies
-the evidence file and exclusions. Inspect the full preview with `--dry-run --format json`.
-The interactive confirmation defaults to No and identifies skipped records.
-Without a terminal, uploading requires `--yes`.
+Set `--to cloud`. For `--repository`, use the connected GitHub or GitHub
+Enterprise repository URL or its Cloud ID. Either works for retries. If
+several connectors share the URL, use the ID. You can import before the
+repository's first native scan.
+
+Cloud requires a file-backed ChatGPT login. To use your regular Codex login,
+set `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in
+again with the ChatGPT account you want to use.
+
+### Review the Cloud destination
+
+Run the command with `--dry-run --format json`. Check `accountId`,
+`cloudApiUrl`, `destination` and `source.source_key`. Compare `findings` and
+`excluded` with the records you meant to import.
+
+- **Private findings inbox.** If the preview includes `privateImport`, the
+ report goes to your inbox. The repository and connector identify the
+ suggested assessment target. Check `format`, `bytes` and `sha256` in
+ `privateImport` to identify the upload. For an Endor Finding, an Endor
+ `list.objects` response or a Wiz vulnerability JSON export, the CLI can
+ send the original bytes when Cloud accepts the format and every record
+ matches your selection. Other inputs, including arrays of selected Endor
+ Findings, use `security.findings.v1`.
+- **Repository publisher.** Check `repository.environment_id` in each entry
+ of `requests`. The publisher checks the current source versions. Existing
+ records keep their environment. New records use the repository's authorized
+ default.
+
+To import, run the same command without `--dry-run` and confirm. The terminal
+shows the file, exclusions, severities and up to five finding IDs and titles.
+The prompt defaults to No. For a noninteractive import, add `--yes` after
+reviewing the full JSON preview.
### Configure an alternate Cloud deployment
@@ -1422,23 +1436,50 @@ instructions. API requests always use the API root. The older
### Resume interrupted imports
-The publisher saves request IDs and bodies privately in the configured state
-directory before uploading batches of up to 100 findings within Cloud payload
-limits. After a lost response, use the same input, destination, account, API
-endpoint, and state directory to resume. Deployments have separate checkpoints
-even if their account and repository IDs match. Check `cloudApiUrl` for the API
-endpoint and `savedSubmission` for the checkpoint. A repository reset retires
-the old request and requires a fresh preview and approval.
+If the result includes `savedSubmission`, keep that checkpoint. Rerun the
+original command with `--dry-run --format json` using the same input, account,
+destination, API endpoint and state directory. Check `cloudApiUrl`. If
+`resumed` is true, confirm to continue the saved submission. If it's false,
+review the new submission before confirming.
+
+- **Private inbox.** The CLI checks the report digest and reuses its saved
+ request IDs. It can read an accepted job even if the deployment has since
+ disabled uploads. After an inbox reset, check the new report format, size
+ and digest before confirming.
+- **Repository publisher.** The CLI saves each request privately before
+ sending up to 100 findings. Retries use the same publisher, request IDs and
+ bodies. If the repository has been reset, preview and confirm a fresh
+ submission.
+
[Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
### Results and exit codes
-| Status | Exit code | Meaning |
-| ------------- | --------- | ----------------------------------------------------------------------- |
-| `complete` | 0 | All selected records were acknowledged and read back. |
-| `partial` | 1 | Some records were excluded locally or rejected by Cloud. |
-| `interrupted` | 2 | Upload, verification, or receipt persistence stopped after preparation. |
-| `failed` | 2 | Preparation failed before upload. |
+| Status | Exit code | Meaning |
+| ------------- | --------- | -------------------------------------------------------------------------------------- |
+| `complete` | 0 | The inbox job processed every record successfully, or the publisher verified each one. |
+| `partial` | 1 | The import had exclusions or record errors, or the inbox job failed or was cancelled. |
+| `interrupted` | 2 | The CLI stopped while uploading, checking the result or saving a receipt. |
+| `failed` | 2 | Preparation failed before upload. |
+
+For a partial or interrupted import, check `excluded` and any `error` before
+retrying. Some records may already have reached Cloud.
+
+- **Private inbox.** In `privateJob`, check the job `status`, `counts.error`
+ and `counts.unprocessed`. The receipt also identifies the job (`id`) and the
+ uploaded file (`input.file_id`). The CLI reads the job receipt, so a
+ successful import can show `verified: 0`. To share a finding, open it in
+ your inbox, assess it against a pinned repository revision and publish the
+ reportable assessment.
+- **Repository publisher.** `verified` counts records whose identity the CLI
+ confirmed by reading them back. If the version matches the receipt, the CLI
+ also checks the evidence. A newer version can have different evidence and
+ still count as verified. `unacknowledged` counts records awaiting a receipt,
+ including records Cloud accepted if the response was lost. Use `client_id`
+ to match a receipt item to its request and `source_finding_id` in `failures`
+ to find a failed vendor record. Counts include earlier batches with receipts.
+ When present, `cloudUrl` opens the repository. Assessment and sharing are
+ separate steps.
With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
Failed and interrupted imports set `ok` to `false` and `error.code` to
@@ -1446,18 +1487,9 @@ Failed and interrupted imports set `ok` to `false` and `error.code` to
Other formats reject `--full-output` before reading the file or contacting
Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
-`verified` and `unacknowledged` are counts. Each receipt item identifies a
-request item by `client_id`. Each entry in `failures` identifies the vendor
-record by `source_finding_id`. A lost response can leave accepted records
-unacknowledged. Review `error` before retrying, and check `excluded` for local
-input errors. Counts include previously acknowledged batches in the same
-saved submission.
-
-Progress goes to stderr and JSON results to stdout. Lookups and readback use up
-to four concurrent requests. Uploads are sequential. Saved receipts and
-readback verify source-record identity and evidence. Codex assessment and
-visibility in the shared Cloud Findings view are separate. `cloudUrl`, when
-available, links to the destination repository in Cloud.
+Progress goes to stderr and JSON results to stdout. The repository publisher
+uploads sequentially and uses up to four concurrent requests for lookups and
+readback.
### Import Snyk findings
@@ -1479,32 +1511,6 @@ The [Wiz guide](https://github.com/openai/codex-security/blob/main/docs/scanner-
SAST findings, repository secrets, or IaC findings. The format reference below
describes the fields to preserve when preparing those exports.
-#### Review the Cloud destination
-
-The preview shows which Cloud destination will receive the selected records.
-When the deployment advertises private import for the scanner, the CLI puts a
-report in the signed-in account’s **private findings inbox**. The preview
-identifies its format and byte count. For complete Endor findings and Wiz
-vulnerability JSON exports, the CLI sends the original bytes when Cloud
-advertises the format and every record matches the reviewed selection. Other
-selections and in-memory collectors use `security.findings.v1`. The CLI
-attaches the selected repository and connector as a suggested assessment
-target. Review the selection, exclusions, source key and destination before
-confirming.
-
-The job receipt contains the file and job identifiers and record counts. To
-share a finding, open it in Cloud, assess it against a pinned repository
-revision, and explicitly publish a reportable assessment. An import can
-finish with record errors. Check the error and unprocessed counts in the
-receipt.
-
-Repeat the same command to recover an interrupted private import. The CLI
-checks the report digest, reuses its saved request IDs, and reads an accepted
-job even when new uploads are disabled. Resetting the inbox requires a new
-preview and confirmation. Deployments and scanners using the repository
-publisher continue to show the repository destination and per-finding receipts.
-An in-flight repository publication resumes on its original protocol.
-
#### Select findings and a destination
Acquire selected findings through an authorized Wiz connection and save the
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 5fcb31cd2..fb092a8fc 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -3660,7 +3660,7 @@ export async function main(
publication.command("findings", {
description:
"Preview and import a saved scanner report locally or to Cloud.",
- hint: "Choose the reader with --provider and keep --source-key stable for reimports. See the scanner import guide for accepted formats, repository requirements and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md. Gzip is supported. --to local stores unassessed evidence without Cloud login. --full-output requires --format json or --format jsonl.\nExample: codex-security publish findings selected-wiz.json --to local --repository ./project --provider wiz --source-key TENANT_ID/vulnerability-finding --dry-run --format json",
+ hint: "Choose your scanner with --provider. Reuse --source-key for later imports from the same source. See the scanner import guide for supported formats, repository setup, and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md. Gzip files are supported. Use --to local to save unassessed findings without a Cloud login. Use --full-output with --format json or --format jsonl.\nExample: codex-security publish findings selected-wiz.json --to local --repository ./project --provider wiz --source-key TENANT_ID/vulnerability-finding --dry-run --format json",
destructive: true,
mcp: false,
args: z.object({
diff --git a/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts b/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts
index 47844ac70..c19eee38b 100644
--- a/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts
+++ b/sdk/typescript/tests-ts/api-deep-scan-runtime-routing.test.ts
@@ -456,6 +456,8 @@ test.each([
}
});
+// These stock routing tests disable plugins so a background marketplace fetch
+// cannot hold the temporary Codex home open after the app-server exits.
test("stock Codex resolves ordered profile overrides and inherited transport policy in the scan", async () => {
const home = await temporaryDirectory();
const scanDir = await temporaryDirectory();
@@ -472,6 +474,7 @@ test("stock Codex resolves ordered profile overrides and inherited transport pol
config: {
"features.code_mode.enabled": true,
features: {
+ plugins: false,
code_mode: {
enabled: true,
direct_only_tool_namespaces: ["audit"],
@@ -525,6 +528,7 @@ for await (const line of createInterface({ input: process.stdin })) {
env: { CODEX_HOME: home },
config: {
features: {
+ plugins: false,
code_mode: {
enabled: true,
direct_only_tool_namespaces: ["audit"],
diff --git a/sdk/typescript/tests-ts/api-provider-isolation.test.ts b/sdk/typescript/tests-ts/api-provider-isolation.test.ts
index bfbfa2b22..80a4b1f6f 100644
--- a/sdk/typescript/tests-ts/api-provider-isolation.test.ts
+++ b/sdk/typescript/tests-ts/api-provider-isolation.test.ts
@@ -9,7 +9,7 @@ import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { createInterface } from "node:readline";
import { executablePathForSpawn, resolveCodexCommand } from "../src/runtime.js";
-import { PLUGIN_ROOT } from "./plugin-root.js";
+import { copyCredentialTestPlugin, PLUGIN_ROOT } from "./plugin-root.js";
import { profileConfigOverrides } from "../../../plugins/codex-security/scripts/codex_profile.mjs";
import { TestClient } from "./support/api-client.js";
import { preparedRuntime } from "./support/api-events.js";
@@ -1105,8 +1105,7 @@ test.each(["root", "profile"])(
);
async function createPluginProbe(root: string, report: string) {
- const plugin = join(root, "plugin");
- await cp(PLUGIN_ROOT, plugin, { recursive: true });
+ const plugin = await copyCredentialTestPlugin(root);
const probe = join(plugin, "environment-probe.mjs");
await writeFile(
probe,
diff --git a/sdk/typescript/tests-ts/plugin-root.ts b/sdk/typescript/tests-ts/plugin-root.ts
index 562e79600..a8329676f 100644
--- a/sdk/typescript/tests-ts/plugin-root.ts
+++ b/sdk/typescript/tests-ts/plugin-root.ts
@@ -28,6 +28,7 @@ export async function copyCredentialTestPlugin(root: string): Promise<string> {
"scripts/launch_codex_security_mcp",
"scripts/launch_codex_security_mcp.cmd",
"skills/security-scan/SKILL.md",
+ "skills/deep-security-scan/SKILL.md",
]) {
await cp(new URL(file, bundledPlugin), join(plugin, file));
}