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: organize external scanner integration guides (#2189)

Michael D'Angelo25bba53b4eb4
diff --git a/README.md b/README.md
index 0778fd269..31e80f761 100644
--- a/README.md
+++ b/README.md
@@ -17,8 +17,8 @@ Use its security workflows in Codex, or automate them with the
- Draft `SECURITY.md` policies and save threat models for later review.
- Browse saved scans and findings, identify duplicates, assess severity against
your own rubric, and suggest owners from source and Git history.
-- Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
- findings to Linear or a findings service.
+- [Import findings from external scanners](docs/scanner-imports/README.md), including Semgrep, Snyk, and Wiz.
+- Export SARIF, JSON, or CSV, and publish findings to Linear or a findings service.
- Automate scans across repositories or project components, including in CI and
containers.
@@ -272,7 +272,7 @@ for examples.
- [Online documentation](https://learn.chatgpt.com/docs/security/cli)
- [Agent workflows and recovery](docs/agent-workflows.md)
- [CLI reference](sdk/typescript/docs/cli.md)
-- [Scanner file import schema and capability guide](docs/scanner-imports/schema-guide.md)
+- [Imported finding identity and evidence](docs/scanner-imports/schema-guide.md)
- [Project configuration](docs/project-configuration.md)
- [Examples](examples/README.md)
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.md
new file mode 100644
index 000000000..4a1369bf4
--- /dev/null
+++ b/docs/scanner-imports/README.md
@@ -0,0 +1,49 @@
+# Import external scanner findings
+
+Use a scanner report to bring findings into the local Codex Security workbench or
+publish them to Codex Security Cloud. Start with the guide for your input. Each
+guide shows how to preview the findings before you save or publish them.
+
+| Source | Input |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| [Amazon Inspector](inspector.md) | Inspector2 `ListFindings` JSON for one Code Security repository |
+| [Black Duck SCA](blackduck.md) | BOM component vulnerability records for one project version |
+| [Endor Labs](endor.md) | Finding JSON from `endorctl`, or SARIF with finding UUIDs |
+| [GitHub code scanning](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud) | Selected alerts from a repository and Git ref |
+| [GitHub Dependabot](github-dependabot.md) | Dependency alerts exported from one repository |
+| [GitHub Security Advisories](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately) | Selected repository or global advisories |
+| [OpenGrep](opengrep.md) | Native scan JSON, optionally gzip-compressed |
+| [Semgrep Code](semgrep.md) | CLI or CI JSON, or a self-contained SARIF report |
+| [Snyk Open Source](snyk.md) | CLI JSON, a Codex plugin export, or SARIF |
+| [SonarQube Cloud](sonar.md) | Selected security issues from 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 ([local preview](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally), [formats and Cloud](../../sdk/typescript/docs/cli.md#import-wiz-findings)) | Native JSON, normalized JSONL or detailed repository package vulnerability CSV |
+
+## Preview a report
+
+Enable external imports in the shell where you run the CLI.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+```
+
+In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
+Follow the provider guide to capture or export the report. For a saved file,
+add `--dry-run` to the guide’s `codex-security publish findings FILE --to local`
+command. Review the destination, findings and exclusions. Repeat without
+`--dry-run` and confirm at the prompt. For noninteractive use, pass `--yes`
+after reviewing the same report and destination. Keep the source key for
+later exports from the same source.
+
+Preview, import and readback output can contain the full scanner evidence.
+Run these steps in a private terminal. In automation, direct standard output
+and diagnostics for each step to private files outside the checkout.
+
+## Work with imported findings
+
+Run `codex-security findings imported PATH` with the repository path shown in
+the local preview. Imported findings have assessment state `not_assessed`. Use
+the scanner evidence to check whether the issue affects your repository.
+
+- [CLI import options, destinations and confirmation](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally)
+- [How scanner records map to finding IDs and evidence](schema-guide.md)
diff --git a/docs/scanner-imports/blackduck.md b/docs/scanner-imports/blackduck.md
index 394cace65..3c2866936 100644
--- a/docs/scanner-imports/blackduck.md
+++ b/docs/scanner-imports/blackduck.md
@@ -1,28 +1,84 @@
-# Import Black Duck SCA repository vulnerabilities
+# Import Black Duck SCA findings
-Use `--provider blackduck` to import vulnerable BOM components from one Black Duck
-SCA project version. Check the scan configuration to confirm which Git repository
-the project version represents. Project names, API hosts and component download
-URLs cannot establish that mapping. Aggregate product BOMs, image-only scans,
-license violations and global advisory catalogs are outside this import.
+Import vulnerable BOM components from one Black Duck SCA project version.
+Verify in the scan configuration that the version represents the Git repository
+you want to import into. A project name or component download URL cannot
+establish that connection.
-## Export a complete collection
+## Quick start
-Use a read-only token and 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 serves only BOM-8 or another
-inventory format, stop the export.
+Use a read-only token to [export the BOM-6 collection](#export-the-bom-6-collection)
+to a private file outside the checkout. From the verified checkout root, replace the
+file path, Git URL and source key with values for your project version.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+codex-security publish findings /private/path/blackduck.json \
+ --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, destination, and excluded rows. Remove `--dry-run` to import
+the ready records, then read the stored evidence.
+
+```sh
+codex-security findings imported . --format json
+```
+
+Reuse the same source key for that deployment, project, and version. A later
+export updates matching occurrences and leaves omitted occurrences in place.
+
+For Cloud, replace `--to local --repository .` with
+`--to cloud --repository CLOUD_REPOSITORY_ID` on a deployment that accepts
+`blackduck`. Preview again before confirming. Cloud compares declared and
+retained source repository URLs with the authorized GitHub repository. Local
+import compares them with the checkout’s Git remotes when comparable remotes
+exist. Importing a saved report locally requires neither a Black Duck nor a
+Cloud login.
+
+If a Cloud upload is interrupted, follow the
+[Cloud retry procedure](schema-guide.md#retry-a-cloud-submission).
+
+## 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
+
+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 the two UUIDs. The client exchanges the token before
-reading the collection, so disable redirects for the entire session.
+`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 after the script succeeds.
+and rename it to `blackduck.json` after the script succeeds.
```python
import json
@@ -91,51 +147,7 @@ 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. To import only selected
-occurrences, supply an array of native rows that each identify the same project
-version.
-
-## Preview and repeat
-
-```bash
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-codex-security publish findings blackduck.json \
- --to local --repository ./project --provider blackduck \
- --source-repository-url https://github.com/example/project \
- --source-key blackduck/deployment-alias/project-id/version-id \
- --dry-run --format json
-```
-
-Check the source, destination and excluded rows before repeating the command
-without `--dry-run`. Reuse the source key for later exports from this deployment,
-project and version. For Cloud, select an authorized GitHub repository with
-`--to cloud` on a deployment that accepts `blackduck`. Reading a saved report
-requires no Black Duck login. Local imports also require no Cloud login.
-
-If an interrupted Cloud upload reports `result.savedSubmission`, keep its
-checkpoint and use the same build, state directory, account and import settings.
-Preview the original export with `--dry-run --format json`. Check `accountId`
-and `destination`. When `resumed` is false, review the new upload before approving it.
-For `prepareNormalizedExternalPublication`, pass your original normalized
-`ExternalFindings` and check `preview.resumed` before calling `publish()`.
-Different normalized findings prepare a new upload.
-
-Cloud checks retained and declared source repository URLs against the selected
-repository. For local SDK imports, reader-supplied repository references must
-agree with the repository on the findings. Local imports also check comparable
-Git remotes on the selected checkout. Select the `blackduck` provider for
-retained Black Duck BOM records. Caller-authored text and opaque IDs alone
-cannot establish repository ownership.
-
-Each occurrence is identified by its project version, component version, origin,
-advisory source and advisory name. Reimporting updates the occurrence when its
-evidence changes. Rows absent from a later export remain open.
-
-Supported package URLs and origin coordinates supply the package identity.
-`advisory_ids` preserves the vendor’s `vulnerabilityName` and any distinct
-`relatedVulnerability` value verbatim, including Black Duck resource URLs.
-The native row retains its CWE, matched-files link and remediation status.
-Findings start unassessed, with no inferred fix, Git revision or source location.
-
-References: [official Python REST client](https://github.com/blackducksoftware/hub-rest-api-python),
-[vendor example of vulnerable BOM components](https://github.com/blackducksoftware/hub-client-go/blob/5f78f7257c00fe9cebabf1bf89a6fc36a4d1f095/hubapi/testdata/vulnerableBomComponents.json).
+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).
diff --git a/docs/scanner-imports/endor.md b/docs/scanner-imports/endor.md
index c5ed85002..b5e3c3034 100644
--- a/docs/scanner-imports/endor.md
+++ b/docs/scanner-imports/endor.md
@@ -1,85 +1,82 @@
# Import Endor Labs findings
-Vendor finding import and readback require `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`.
-See the [opt-in instructions](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally)
-and [how saved scanner reports map to imported evidence](schema-guide.md).
+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.
-Use authenticated `endorctl` to export complete native Finding JSON through the
-[official CLI API](https://docs.endorlabs.com/developers-api/cli/commands/api).
-Scope the export to one project and context, omit `--field-mask`, and use
-`--list-all` to fetch every page. Replace the namespace and project UUID below
-to select the project's default-branch findings:
+## Quick start
+
+Authenticate `endorctl` for the namespace that owns the project. Confirm the
+project and context correspond to the checkout. The importer retains the
+project UUID but does not look up its repository. Run these commands from the
+checkout root, replacing `YOUR_NAMESPACE` and `PROJECT_UUID` in both commands.
```sh
-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 > endor-findings.json
+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.json"
+```
-codex-security publish findings endor-findings.json --to local \
- --provider endor --repository ./project \
- --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
+After the export succeeds, keep the file and preview it in the same shell.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+codex-security publish findings "$out/endor-findings.json" \
+ --to local --repository . --provider endor \
+ --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run --format json
```
-Use `--to local` with a local repository path to store unassessed source evidence
-without a Cloud login or model call. After reviewing the preview, remove
-`--dry-run` to confirm the import. Read the stored records with
-`codex-security findings imported ./project --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.
-To publish the same export to Cloud, select its connected repository instead:
+## Import and verify
+
+Check the destination, ready records, and exclusions. Rerun only the
+`publish findings` command without `--dry-run` to import that saved file.
+Local import needs no Cloud login or model call. Read back the stored evidence.
```sh
-codex-security publish findings endor-findings.json --to cloud \
- --provider endor --repository "CLOUD_REPOSITORY_ID" \
- --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
+codex-security findings imported . --format json
```
-Confirm that the selected Endor project and context correspond to the destination
-repository. Native JSON retains the project UUID, but the importer does not look
-it up to verify that association. For another branch or scan context, change the
-Endor filter and use a distinct, stable source key. An unfinished paginated
-response is rejected by the importer. Remove `--dry-run` to review and confirm
-the upload.
-
-The official [Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
-can help with setup and interactive investigation. Its Findings Browser summaries,
-counts and field-masked results do not replace the complete Finding objects used
-here. `endorctl` reads the Endor API; the Codex Security importer reads the saved
-export. It does not establish a persistent API connection or write changes back
-to Endor.
-
-Native JSON is the preferred import format: it preserves Endor severity,
-dependency and advisory details, the scanned commit SHA, primary SAST/AI SAST
-locations, and the complete original Finding. The importer accepts a single
-Finding, an array, or a `ListFindingsResponse` containing `list.objects`. Mapping
-follows Endor's public [Finding model](https://github.com/endorlabs/endorlabs-sdk/blob/8a41756890c2dee3bb089fee881cae4f2adbde03/src/endorlabs/generated/models/finding_service.py).
-
-Existing self-contained `endorctl` SARIF 2.1.0 reports are accepted as a lossy
-compatibility format. The importer retains finding UUIDs and links but does not
-infer native Endor severity or scanned revisions from SARIF. Diagnostic levels
-and CVSS stay in the original evidence;
-displayed severity remains unknown. Direct repository paths and reported SAST or
-Secrets lines are mapped. Indexed or base-relative artifact references remain in
-the original evidence. Run artifact inventories that are unrelated to the selected
-finding are omitted from its evidence. Declared SARIF repository URLs must
-match the selected Cloud repository for a new upload. For local imports, those
-URLs must match a configured Git remote when the checkout has remotes.
-
-Both formats use the native finding UUID as identity within the selected
-repository and source key. Keep the source key stable across repeated imports.
-Importing the same UUID from SARIF after native JSON updates the same source
-record: it replaces the evidence snapshot rather than merging it. Severity can
-become unknown, and commit, package, advisory and other native detail absent from
-SARIF is no longer present in that snapshot. Importing native JSON again replaces
-it with the richer native evidence. Use native JSON consistently for ongoing
-imports.
-
-Recommended upgrades, reachability, dismissals and other Endor assessments remain
-source claims. Local records remain unassessed and separate from completed scans;
-imports do not automatically investigate or patch them. Records omitted from a
-later local import remain stored. Saved Cloud requests retain their destination
-repository ID when resumed.
-
-The adapter can be tested with synthetic records and the public SARIF sample.
-Verifying acquisition requires an authenticated Endor namespace with findings.
-Verifying Cloud publication also requires a Cloud environment that supports
-finding imports.
+For Cloud, replace `--to local --repository .` with
+`--to cloud --repository CLOUD_REPOSITORY_ID` for the connected repository.
+Review the Cloud preview before confirming. If the repository is renamed, a
+saved submission can resume against the same Cloud repository ID.
+
+## Reference
+
+### Native Finding 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 help with setup or investigation. Findings Browser summaries, counts, and
+field-masked results omit fields needed for import. Codex Security reads the
+saved export offline. It does not change findings in Endor.
+
+### 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.
diff --git a/docs/scanner-imports/github-dependabot.md b/docs/scanner-imports/github-dependabot.md
index 75cc1ca74..1ba322738 100644
--- a/docs/scanner-imports/github-dependabot.md
+++ b/docs/scanner-imports/github-dependabot.md
@@ -1,64 +1,74 @@
-# Import GitHub Dependabot repository alerts
+# Import GitHub Dependabot findings
-A Dependabot alert identifies a vulnerable dependency in one repository. Its GHSA
-describes the affected software. GitHub code scanning and published security
-advisories have separate import formats.
+Import Dependabot alerts from one GitHub repository. An alert identifies a
+dependency occurrence in a manifest. Its advisory describes the vulnerability.
-## Export one repository
+## Quick start
-Use a fine-grained token or GitHub App installation with **Dependabot alerts: read**
-for the repository. The GitHub CLI reads the alerts. Codex Security imports the
-saved file offline. Keep the export outside the checkout.
+Authenticate the GitHub CLI with a fine-grained token or GitHub App installation
+that has read access to Dependabot alerts for the repository. From the destination
+checkout root, replace `github.com` and `OWNER/REPO` in the export and source key.
```bash
-set -eu
-umask 077
-out=$(mktemp -d)
-gh api --hostname github.com --method GET --paginate \
- -H 'Accept: application/vnd.github+json' \
- -H 'X-GitHub-Api-Version: 2022-11-28' \
- --jq 'if type == "array" then tojson else error("expected an alert page") end' \
- 'repos/OWNER/REPO/dependabot/alerts?per_page=100' > "$out/pages.tmp"
-test -s "$out/pages.tmp"
-mv "$out/pages.tmp" "$out/dependabot.jsonl"
+out=$(mktemp -d) && (
+ set -eu
+ umask 077
+ gh api --hostname github.com --method GET --paginate \
+ -H 'Accept: application/vnd.github+json' \
+ -H 'X-GitHub-Api-Version: 2022-11-28' \
+ --jq 'if type == "array" then tojson else error("expected an alert page") end' \
+ 'repos/OWNER/REPO/dependabot/alerts?per_page=100' > "$out/pages.tmp"
+ test -s "$out/pages.tmp"
+ mv "$out/pages.tmp" "$out/dependabot.jsonl"
+)
```
-Replace the hostname and `OWNER/REPO` in both examples. The command follows every
-page and includes open, fixed, dismissed, and auto-dismissed alerts. Each line
-contains one page, including `[]` for an empty collection. If a request fails,
-check repository access before retrying.
-
-## Preview and import
+After the export succeeds, preview the saved file in the same shell.
```bash
export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
codex-security publish findings "$out/dependabot.jsonl" \
- --to local --repository ./project --provider github \
+ --to local --repository . --provider github \
--source-key github.com/OWNER/REPO/dependabot --dry-run --format json
```
-Review the destination, ready records, and exclusions, then remove `--dry-run`.
-Use `--to cloud` with an authorized repository ID or URL for Cloud publication.
-For a local checkout, the alert repository must match a configured network
-remote when one is available. If the checkout has only filesystem remotes or
-no remote, verify the export belongs to it before importing.
+The export contains one JSON array per line, including `[]` for an empty page.
+It follows every page and includes open, fixed, dismissed, and auto-dismissed
+alerts. The importer reads the saved file offline.
+
+## Import and verify
+
+Check the destination, ready records, and exclusions. 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.
+Rerun only the `publish findings` command without `--dry-run` to import the
+reviewed `$out/dependabot.jsonl` file. Then read the local evidence.
+
+```sh
+codex-security findings imported . --format json
+```
+
+For Cloud, replace `--to local --repository .` with
+`--to cloud --repository CLOUD_REPOSITORY_ID` and preview again before confirming.
+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.
+
+## Reference
-Keep the export and reuse its source key for the same repository. The host,
-repository, and alert number identify an occurrence. Two alerts for the same
-GHSA keep separate histories. A later selection updates the alerts it includes
-and leaves omitted alerts in place.
+Reuse the source key for repeat exports from the same repository. 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.
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 identifies a
-manifest dependency without establishing the installed version, an affected
-line, or a Codex assessment. The importer rejects conflicts between alert
-identities, affected packages, or ranges, and requires repository-relative
-manifest paths.
+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.
-Read local evidence with `codex-security findings imported ./project --format json`.
-To trace the affected package and evaluate an upgrade in Codex, use
-[`$resolve-dependency-alert`](../../plugins/codex-security/skills/resolve-dependency-alert/SKILL.md)
-with the saved alert and the checkout.
-See the [GitHub Dependabot alerts endpoint](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository)
-and the [GitHub CLI pagination options](https://cli.github.com/manual/gh_api).
+GitHub code scanning and published security advisories have separate import
+formats. See the [scanner import guide](schema-guide.md), the
+[Dependabot alerts endpoint](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository),
+and [GitHub CLI pagination](https://cli.github.com/manual/gh_api).
diff --git a/docs/scanner-imports/inspector.md b/docs/scanner-imports/inspector.md
index e4942e917..28eeff029 100644
--- a/docs/scanner-imports/inspector.md
+++ b/docs/scanner-imports/inspector.md
@@ -1,13 +1,14 @@
-# Import Amazon Inspector repository findings
+# Import Amazon Inspector findings
Import package and code vulnerabilities from one Amazon Inspector Code Security
-repository. Each finding ARN identifies one occurrence within your source key.
+repository. Findings from EC2, ECR, Lambda, and network resources are excluded.
-## Export one repository
+## Quick start
-In Inspector coverage, find the account, Region and full resource ID for the
-repository. A project name alone can match several integrations. With
-`inspector2:ListFindings` permission, export the findings outside the checkout.
+In Inspector coverage, find the account, Region, and full resource ID for the
+repository. Project names can match several integrations. With
+`inspector2:ListFindings` permission, run this export from the destination
+checkout root. Replace the example Region, account ID, and repository resource ID.
```bash
set -eu
@@ -22,57 +23,59 @@ aws inspector2 list-findings --region us-east-1 --output json \
mv "$out/inspector.json.tmp" "$out/inspector.json"
```
-Start at the first page with 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.
-
-## Bind the Inspector project to a Git repository
-
-Inspector often reports a project ARN and a name such as `example/project`.
-That name can exist on multiple Git hosts. Verify the project ARN and its
-canonical Git URL in your SCM integration setup. Set `VERIFIED_PROJECT_ARN`
-to that ARN and pass the pair explicitly.
-Copying an ARN from the report alone cannot verify who owns the repository.
-When the findings already include a matching native Git URL, omit
+Verify the Inspector project ARN and its canonical Git URL in your SCM
+integration setup. Set `VERIFIED_PROJECT_ARN` to that ARN and replace the Git
+URL and source key below. The ARN in a report alone does not establish the
+mapping. If the findings already include the matching native Git URL, omit
`--inspector-project-arn`.
-## Preview, import and read back
-
-```bash
+```sh
export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
codex-security publish findings "$out/inspector.json" \
- --to local --repository ./project --provider inspector \
+ --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
```
-Review the destination, ready findings and exclusions. Remove `--dry-run` to
-import, then run `codex-security findings imported ./project --format json`.
-Reuse the source key across exports. Reimport updates an existing ARN.
-Omitted findings and empty exports leave earlier occurrences in place.
+## Import and verify
-For Cloud, use `--to cloud --repository CLOUD_REPOSITORY_ID` on a deployment
-that accepts the Inspector provider. Cloud checks the authorized GitHub
-destination. Custom GitHub hosts need a native GitHub provider hint.
-Self-managed GitLab is supported locally. If the GitLab web URL includes an
-installation prefix that the SSH clone URL omits, use the verified HTTPS clone
-URL as a checkout remote. Use the verified URL’s path casing on custom hosts.
-For home-relative SSH paths, verify the account when a URL omits the login.
+Check the destination, ready findings, and exclusions. Remove `--dry-run` to
+import, then read the stored evidence.
-Supply the same verified ARN and URL when resuming a Cloud submission prepared
-with that binding. SDK callers can pass verified ARN-to-URL pairs through the
-`inspectorProjectMap` option on raw and normalized imports.
+```sh
+codex-security findings imported . --format json
+```
+
+For Cloud, replace `--to local --repository .` with
+`--to cloud --repository CLOUD_REPOSITORY_ID` on a deployment that accepts
+`inspector`. Preview again before confirming. Cloud checks the authorized
+GitHub destination. Supply the same verified ARN and Git URL when resuming a
+submission prepared with that binding.
+
+## Reference
-## Evidence
+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.
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. EC2, ECR, Lambda and network
-findings are excluded.
+available. Native status, severity, and remediation remain source evidence.
+A closed or suppressed finding stays unassessed.
+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 [repository fields](https://docs.aws.amazon.com/inspector/v2/APIReference/API_CodeRepositoryDetails.html).
+and [Inspector repository fields](https://docs.aws.amazon.com/inspector/v2/APIReference/API_CodeRepositoryDetails.html).
+
+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.
diff --git a/docs/scanner-imports/opengrep.md b/docs/scanner-imports/opengrep.md
index 4270c1752..e6cb9199c 100644
--- a/docs/scanner-imports/opengrep.md
+++ b/docs/scanner-imports/opengrep.md
@@ -1,146 +1,103 @@
# Import OpenGrep findings
-Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` in the command environment to enable external imports.
+Import native OpenGrep JSON into the local workbench or Cloud. The reader
+accepts plain or gzipped reports and preserves OpenGrep observations, including
+available traces and scan diagnostics.
-Import native OpenGrep JSON, including gzip-compressed reports, into the local
-workbench or Cloud. This reader accepts scanner output, not SARIF, normalized
-JSONL, or an API summary. It preserves findings as unassessed scanner evidence.
+## Quick start
-From the source repository root, use a fresh report directory outside the
-checkout. The following commands use the shell's temporary directory:
+From the scanned repository's root, set `report` to the saved JSON and
+`repo_url` to its credential-free HTTP(S) repository URL. Choose an OpenGrep-specific source key
+for the organization, project and branch. Enable external imports for this shell.
```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+report=../reports/opengrep.json
+repo_url=https://github.com/example/project
+source_key=opengrep/example/project/main
+```
+
+If you need a new report, run OpenGrep in the repository root with your rules.
+Use a private temporary directory outside the checkout for this run.
+
+```sh
+report=
report_dir=$(mktemp -d) &&
-opengrep scan --config /path/to/rules.yaml --json --output "$report_dir/opengrep.json" . &&
-codex-security publish findings "$report_dir/opengrep.json" --to local \
- --provider opengrep --source-key opengrep/ORGANIZATION/PROJECT/BRANCH \
- --source-repository-url https://github.com/example/project \
- --repository . --dry-run --format json
+ opengrep scan --config /path/to/rules.yaml --json --output "$report_dir/opengrep.json" . &&
+ report="$report_dir/opengrep.json"
```
-Native JSON includes dataflow traces when the scanner produces them.
-`--dataflow-traces` controls text and SARIF rendering; it is not required for JSON.
-See OpenGrep's [output options](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/cli_scan/Scan_CLI.ml)
-and [JSON formatter](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/reporting/Cli_json_output.ml).
+Native JSON includes traces when available. Use `--verbose` for skipped-target
+details. SARIF and normalized JSONL are unsupported.
+[OpenGrep output options](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/cli_scan/Scan_CLI.ml)
+and [JSON formatter](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/reporting/Cli_json_output.ml)
-Review the source repository, findings, exclusions, diagnostics, and destination.
-Repeat the import without `--dry-run` to confirm interactively, or add `--yes`
-after reviewing the preview. Local imports require no Cloud login or model call.
-Read the stored evidence with:
+After a successful scan, or with an existing report, preview the selected file locally.
```sh
-codex-security findings imported . --format json
+codex-security publish findings "$report" --to local --repository . \
+ --provider opengrep --source-repository-url "$repo_url" \
+ --source-key "$source_key" --dry-run --format json
```
-For Cloud, use the same report and source namespace with a Cloud destination:
+## Import and verify
+
+Check the findings, exclusions and scan diagnostics. The declared source URL
+must match a comparable configured Git remote when one is available. Repeat the
+local command without `--dry-run`, confirm, then read back the stored evidence.
+Local import needs no Cloud login.
```sh
-codex-security publish findings "$report_dir/opengrep.json" --to cloud \
- --provider opengrep --source-key opengrep/ORGANIZATION/PROJECT/BRANCH \
- --source-repository-url https://github.com/example/project \
- --repository https://github.com/example/project --dry-run --format json
+codex-security findings imported . --format json
```
-`--source-repository-url` is required and declares where the report came from.
-The importer checks it against configured local Git remotes or the selected
-Cloud repository. It does not infer the scanner's revision from the current
-checkout. Cloud preview requires the existing ChatGPT login and an authorized
-repository and environment; review the preview before approving the upload.
-
-## Provider identity and evidence
-
-`--provider opengrep` selects the OpenGrep reader. Local storage and Cloud use the
-existing `semgrep` source-provider contract for compatibility, while typed
-`scanner_origin` identifies **OpenGrep**. The preview shows this mapping. This
-does not add a native OpenGrep provider to the Cloud service. Cloud publication
-requires that deployment to support the existing Semgrep import contract;
-successful local imports do not verify hosted availability.
-
-Keep an OpenGrep-specific source key, such as
-`opengrep/ORGANIZATION/PROJECT/BRANCH`, stable across runs. Occurrence IDs use the
-rule, path, and source range. The importer normalizes redundant slash-separated
-components in repository-relative paths and preserves literal backslashes in
-filenames. An unmapped path keeps its original spelling in the occurrence ID.
-Keep Windows path spellings consistent across runs because changing them can
-create a second record. Multiple dataflow traces for the same occurrence are
-grouped into one finding. For Cloud imports, check `excluded` for traces that
-could not fit. If independently valid traces exceed the 256 KiB limit together,
-the whole occurrence is excluded. Moving a match creates a new record and leaves
-its earlier record intact. The raw scanner
-fingerprints remain evidence and do not override this location-based identity.
-Omitting a finding from a later report does not close or delete it.
-
-The adapter retains rule metadata, source ranges, snippets, traces, ignored state,
-and original severity. Normalized severity is `unknown`: OpenGrep rule levels
-such as `ERROR` or `WARNING` are not a verified vulnerability severity. Ignored
-matches remain source evidence, separate from a Codex assessment. Importing a
-report does not assess findings, apply fixes, or create a completed Codex scan.
-
-## Diagnostics and coverage
-
-OpenGrep can return matches alongside parse failures, partial parsing, timeouts,
-and other diagnostics. Warning diagnostics can accompany exit code 0 with the
-default `--no-strict`; `--strict` changes warning handling, while `--error`
-separately makes findings produce exit code 1. Inspect the report's diagnostics
-and the scanner's exit status. Neither zero findings nor a successful exit
-establishes complete coverage. See OpenGrep's
-[error classification](https://github.com/opengrep/opengrep/blob/main/src/core/Core_error.ml).
-
-The JSON preview and result retain the native report envelope, without `results`,
-in `report`, including diagnostics and path metadata for an empty local report.
-Individual stored findings retain the original observations in
-`source_data.results` and a `source_data.scan_error_count`. Their compact
-`source_data.report` retains only the scanner version, keeping scan-wide metadata
-such as diagnostics and matching explanations outside each finding's evidence
-budget. Full report metadata is
-returned by the SDK and CLI; it is not saved as a separate durable scan record.
-Keep the original JSON if you need the complete run metadata later.
-Add OpenGrep's `--verbose` when collecting
-skipped-target details; its [output handling](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/reporting/Output.ml)
-can omit those details otherwise.
-
-Publication status describes import processing and acknowledged records, not
-scanner coverage. A `complete` publication does not resolve scan diagnostics or
-establish a clean security result. Cloud publication requires at least one
-supported finding; an empty report can still be previewed locally with its
-metadata. Review exclusions before approving either destination.
-
-## Assess an imported finding locally
-
-Copy an imported record's `id` from `findings imported --format json`. Use an
-authorized checkout corresponding to the report's revision, then pass its
-evidence to the existing SDK validator:
-
-```ts
-import {
- CodexSecurity,
- listLocalExternalFindings,
-} from "@openai/codex-security";
-
-const repositoryPath = "/path/to/repository";
-const [record] = await listLocalExternalFindings({
- repository: repositoryPath,
- id: "IMPORTED_FINDING_ID",
-});
-if (!record) throw new Error("Imported finding not found.");
-
-const security = new CodexSecurity();
-try {
- const assessment = await security.validate({
- repositoryPath,
- finding: record.evidence,
- });
- console.log(record.id, assessment.disposition);
- console.log(assessment.report);
-} finally {
- await security.close();
-}
+For Cloud, sign in to an account with access to the target repository and
+environment. The deployment must support the `semgrep` provider. Preview the
+same file, review the destination, then repeat without `--dry-run` and confirm.
+Check the result's `verified` count, failures and exclusions.
+
+```sh
+codex-security publish findings "$report" --to cloud --repository "$repo_url" \
+ --provider opengrep --source-repository-url "$repo_url" \
+ --source-key "$source_key" --dry-run --format json
```
-Validation sends the finding evidence, including snippets and traces, to the
-configured Codex model provider. A hosted provider requires network connectivity.
-The validator reads the checkout in a read-only tool sandbox with network access
-disabled. It returns an assessment and leaves the stored import `not_assessed`. See
-[standalone validation](../../sdk/typescript/README.md#validate-an-existing-finding)
-for dispositions and report handling. Hosts that already provide model execution
-can use [validateRecords](../../sdk/typescript/docs/validate-records.md) instead.
+## Reference
+
+### Provider identity and evidence
+
+`--provider opengrep` selects the reader. Both destinations store the source
+provider as `semgrep` and identify OpenGrep in `details.scanner_origin`. Keep a
+distinct OpenGrep source key. The rule, path and range identify an occurrence.
+Moving a match or changing its Windows path spelling can create another record.
+Omitted records remain stored.
+
+Multiple traces at one occurrence are grouped. The original rule level,
+snippets, ignored state and fingerprints remain in the evidence. Normalized
+severity is `unknown` because OpenGrep levels such as `ERROR` describe rule
+matches. For Cloud, review exclusions for oversized traces. If individually
+valid traces together exceed 256 KiB, the whole occurrence is excluded.
+[Imported evidence](schema-guide.md)
+
+### Diagnostics and coverage
+
+A report can contain matches alongside parse errors or timeouts. Check the
+scanner's exit status and the preview's `report.errors`, even when the findings
+list is empty. A successful import confirms storage only. Cloud requires at
+least one supported finding.
+
+The CLI returns run-wide metadata in `report`. Stored findings keep the scanner
+version, raw observations in `source_data.results` and diagnostic count in
+`source_data.scan_error_count`. Retain the original JSON for run-wide details.
+[OpenGrep error classification](https://github.com/opengrep/opengrep/blob/main/src/core/Core_error.ml)
+and [skipped targets](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/reporting/Output.ml)
+
+### Assess an imported finding locally
+
+Copy the record's `id` from local readback. Load the record with the SDK's
+`listLocalExternalFindings({ repository, id })`. On a `CodexSecurity` instance,
+call `security.validate({ repositoryPath, finding: record.evidence })` with
+`repositoryPath` set to the checkout for the scanned revision. Validation sends the 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)
diff --git a/docs/scanner-imports/schema-guide.md b/docs/scanner-imports/schema-guide.md
index 9d219ba6e..a2dcf1f03 100644
--- a/docs/scanner-imports/schema-guide.md
+++ b/docs/scanner-imports/schema-guide.md
@@ -1,210 +1,97 @@
-# How saved scanner reports map to imported evidence
+# Imported finding identity and evidence
-The **reader** selected by `publish findings --provider` interprets a saved
-scanner export. Acquisition produces the artifact:
-for example, `snyk test` scans a workspace, while `codex-security import github`
-retrieves selected code-scanning alerts. File ingestion reads the saved report.
-Use the mappings to decide what one record represents, whether a later export
-updates it, and what evidence a consumer can use. For setup and confirmation,
-see
-[import vendor findings locally](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally).
+See the [scanner import guides](README.md) for accepted inputs, repository
+requirements and export examples.
+This reference explains which records a repeat import updates, what the fields
+mean and how to interpret the result.
## Choose the record and source key
-A stored source record is scoped to **destination repository + provider + source
-key + source finding ID**. Choose the key for the stream you intend to replay,
-not the export date. A CVE or GHSA names an advisory; a CWE or rule ID describes
-a class of issue. Neither identifies a particular installed dependency, code
-location, or affected asset. Matching titles, packages or advisories are reasons
-to investigate records together, not instructions to merge them.
-
-| Reader and accepted input | Source finding ID basis | Keep the source key stable for |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| [Wiz package JSON or detailed CSV](../../sdk/typescript/docs/cli.md#package-vulnerability-inputs); CSV requires `CloudPlatform=GitHub` and `CloudProviderURL` for a GitHub repository `/tree/<ref>` | Vendor occurrence `id` (CSV: `ID`), not the CVE | Tenant and finding family |
-| [Wiz named repository collections](../../sdk/typescript/docs/cli.md#sast-repository-secrets-and-iac-inputs) | `sast:<id>`, `secret:<id>`, `iac:<id>` | Tenant and finding family |
-| [Endor Finding JSON or endorctl SARIF](endor.md) | Finding `uuid` or SARIF `properties["finding-uuid"]` | Namespace, project and context |
-| [Amazon Inspector Code Security ListFindings JSON](inspector.md) | Full Inspector finding ARN | AWS account, Region and repository project |
-| [Snyk Open Source CLI JSON, plugin v1 or SARIF](snyk.md) | CLI: manager, manifest, advisory, package/version and dependency path; plugin: supplied composite; SARIF: advisory, manifest set and project when known | Repository, branch, scan target and format |
-| [Semgrep Code CLI/CI JSON or SARIF](semgrep.md) | Fingerprint; otherwise rule, literal path and start/end lines and columns | Organization, project and branch |
-| [SonarQube Cloud capture or native issue-search pages](sonar.md) | Sonar issue key | Cloud instance, org, project and ref |
-| [GitHub Dependabot repository REST alerts](github-dependabot.md) | Host, repository and alert number | Host, repository and Dependabot family |
-| [GitHub saved `import github` output](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud) | Host, repository, alert number and hash of selected ref | Host, repository and code-scanning family |
-| [GitHub saved `import github-advisories` output](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately) | Host, repository **or** global scope, and GHSA ID | Separate advisory stream from alerts |
-| [Black Duck BOM-6 collection or selected rows](blackduck.md) | Project version, component version, origin, advisory source and advisory name | Deployment, project and version |
-| [Veracode Static Analysis Findings API pages](veracode.md) | API origin, application and context, and native issue ID | Deployment, application and static policy |
-
-Within **one input**, duplicate IDs are ambiguous, not corroboration. Wiz and
-GitHub reject a selection with duplicate accepted IDs. Endor, Snyk and Semgrep
-exclude every record with the colliding identity. Black Duck rejects duplicate occurrences in a complete collection, and excludes all colliding rows in an explicit selection.
-Veracode rejects a capture that repeats an issue ID for the same scan type.
-Inspect the source and select
-the intended occurrence; don't rename records simply to make them import. Across
-**separate local imports**, changed evidence updates the same record; omission
-does not delete or resolve it. Cloud publication sends an expected version;
-resuming a saved request keeps that value. An item error such as
-`version_conflict` or `stale_source_snapshot` can reject an update instead of
-replacing a newer report. Inspect the item error and current source report
-before preparing a fresh submission.
-
-## Interpret the provider evidence
-
-- **Wiz:** `detailedName`, version, advisory and fixed version describe a
- package occurrence. Repository-branch paths can be manifests; container paths
- cannot. JSON prefers `vendorSeverity` over `severity`; repository CSV uses
- `Severity`, then `VendorSeverity`, then `CVSSSeverity`. Keep named
- `sastFindings`, `secretInstances` or `iacFindings` nodes with a repository URL
- or matching inventory. SAST can map a range, snippet, CWE and vendor verdict;
- repository secrets map detector and validation metadata, not a scanned
- revision from the introduced commit; IaC maps expected/actual configuration,
- not proof of deployment. The Wiz file reader does not map workload secrets,
- cloud configuration or external network scans. It also accepts explicitly
- normalized JSONL: supply the reviewed `source_finding_id` and `evidence`,
- retaining the raw row. The reader does not infer a mapping for other CSV
- profiles.
-- **Amazon Inspector.** Supply a complete export for one repository project.
- A matching native URL or the operator's full project ARN mapping establishes
- the Git host. Local import and Cloud replay check the destination again.
- Each finding ARN identifies one occurrence. Duplicate ARNs exclude all
- colliding rows. Package and code evidence retain the native finding.
-- **Endor Labs:** Prefer a complete native Finding, array or `list.objects`.
- `spec.level`, dependency paths/versions, advisory aliases, source SHA and
- primary SAST/AI SAST locations map when present. The project UUID does not
- verify the repository. Proposed upgrades, reachability and dismissals remain
- source claims. SARIF keeps the rule/result and direct locations but reports
- `unknown` severity, not CVSS or diagnostic level. Importing SARIF over native
- JSON for the same UUID **replaces**, rather than enriches, its snapshot.
-- **Snyk CLI, plugin and Open Source SARIF:** Prefer ungrouped native
- `snyk test` JSON for package versions,
- dependency chains, advisory aliases and fix advice. A different dependency
- path can be another occurrence of the same advisory. Plugin evidence can be
- abbreviated; SARIF groups occurrences. Scan-target-relative manifests are not
- Git-root locations, and a synthetic SARIF line 1 is not a code finding. The
- formats do not reconcile their IDs. Licenses, Code, Container, IaC and
- platform backlog are outside these Open Source file formats.
-- **Semgrep Code CLI and SARIF:** Supply `--source-repository-url` for these
- file formats. JSON `extra.fingerprint` or
- SARIF `matchBasedId/v1` survives a location change; without a usable
- fingerprint, a move creates a new record. Use the mapped rule, range, snippet
- and CWE to locate code. Ignored/suppressed is source state. JSON distinguishes
- Critical from High; both become diagnostic `error`, mapped to High, in Semgrep
- SARIF. Inspect the selected result for trace/fix details. Platform/MCP
- envelopes and general Supply Chain/Secrets feeds are not Code CLI or SARIF exports.
-- **OpenGrep.** Use native JSON and supply `--source-repository-url`. The
- [OpenGrep guide](opengrep.md) covers export and occurrence identity.
-- **SonarQube Cloud.** Use [the Sonar import workflow](sonar.md) to capture
- security issues for one project and branch or PR through the authenticated
- Sonar CLI. Keep the capture to import and publish the same native evidence.
- The issue key identifies the occurrence. The rule identifies the check that
- raised it.
-- **GitHub:** For code scanning, the selected instance supplies path/range, ref
- and commit. The rule's `security_severity_level` supplies severity; diagnostic
- `error` alone means `unknown`. An alert-wide dismissal takes precedence over
- instance state. For GHSA, a repository disclosure identifies its publisher; a
- global disclosure has no source repository. Both can carry CVE aliases,
- affected ranges and patched versions. Neither proves installation or
- applicability. Both readers require saved collector output.
-- **GitHub Dependabot.** Use `gh api --paginate` to save native repository
- alert pages as JSONL for the `github` reader. Each alert identifies the
- matched package, manifest and vulnerable range. The embedded advisory supplies advisory IDs.
- Each alert number has its own history, including when several alerts cite the
- same GHSA. GitHub secret-scanning alerts remain outside the file reader.
+A source record is identified by its destination repository, stored provider,
+source key and source finding ID. Use the same source key for each export of the
+same stream, such as an organization, project and branch. A date or run ID in
+the key creates a new set of records on each run.
+
+The reader derives the source finding ID from the export. The differences matter
+when a finding moves, an advisory affects several packages, or the export format
+changes.
+
+| Report | What identifies one record |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Amazon Inspector](inspector.md), [Endor Labs](endor.md), [SonarQube Cloud](sonar.md) | Inspector finding ARN, Endor Finding UUID or Sonar issue key. Endor native JSON and SARIF use the same UUID. |
+| [Wiz](../../sdk/typescript/docs/cli.md#import-wiz-findings) | Package occurrence ID, or a SAST, repository-secret or IaC occurrence ID prefixed with its family. Normalized JSONL uses the supplied ID. |
+| [GitHub Dependabot](github-dependabot.md), [code scanning](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud) | Host, repository, alert family and alert number. Code scanning also includes the selected ref. Two alerts citing one GHSA remain separate. |
+| [GitHub advisories](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately) | Host, repository or global scope, and GHSA ID. This identifies a disclosure. Check installed packages separately. |
+| [Snyk Open Source](snyk.md) | Native CLI JSON distinguishes manifest, package manager, advisory, package name and version, and dependency path. Plugin and SARIF reports use different identities. |
+| [Black Duck SCA](blackduck.md), [Veracode Static Analysis](veracode.md) | Black Duck combines project version, component version, origin and advisory identity. Veracode scopes a native issue ID to its API origin, application and context. |
+| [Semgrep Code](semgrep.md), [OpenGrep](opengrep.md) | Semgrep prefers a fingerprint and falls back to rule, path and range. OpenGrep groups traces by rule, path and range. Both store provider `semgrep`. Use a separate OpenGrep source key. |
+
+Repeat local imports replace changed evidence for the same identity. Identical
+evidence is unchanged, and records omitted from a later report remain stored.
+For example, importing Endor SARIF after native JSON for the same UUID can
+remove details from the stored snapshot. When a single export contains colliding IDs, inspect the reader’s
+exclusions or input error before retrying.
## Read the right field
-- The
- [evidence schema](../../sdk/typescript/schemas/external-findings.schema.json)
- separates the source ID from `evidence`. Its required `title` and `severity`
- are reported evidence, not a Codex rating. Severity is one of `critical`,
- `high`, `medium`, `low`, `informational`, or `unknown`; source status,
- confidence, verdicts and fix advice do not change `assessment.state`.
-- `packages[].installed_version` is an observation; `vulnerable_version_range`
- is a claim about affected versions; `fixed_versions` is source guidance. Use
- `locations[].path/line` for repository navigation and optional
- `details.code.end_line` for the first location. Missing evidence stays
- missing; don't fill in a commit from the current checkout.
-- Optional `details.kind` is **not** a universal scanner taxonomy. Its values
- are `sast`, `secret`, `iac` and `advisory`. Package occurrences from Wiz/Snyk
- and native Endor findings use top-level fields without requiring a kind. For
- an advisory, inspect `details.advisory.source`, not the chosen destination, to
- distinguish repository and global scope.
-- Use `source_data` to inspect what the reader actually received: e.g. a Wiz
- row, Endor Finding, Snyk vulnerability plus project context, Semgrep result or
- GitHub collector envelope. It's selected evidence, not necessarily the whole
- export: unrelated scan inventories can be omitted and plugin or SARIF output
- may already be lossy. Retain the input privately if collection scope matters.
+Imported records start with `assessment.state` set to `not_assessed`. The
+[evidence schema](../../sdk/typescript/schemas/external-findings.schema.json)
+defines the fields the reader can populate.
+
+| Field | How to use it |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`, `severity` | Required source evidence. Severity can be `unknown`. A scanner verdict or suppression can be reported alongside it. |
+| `packages[]` | Compare an observed `installed_version` with the reported `vulnerable_version_range` and `fixed_versions`. An advisory may supply only a range or fix. |
+| `locations[]`, `code_revision` | Navigate to a reported repository path and line at the scanned revision when available. `details.code.end_line` extends the first location. |
+| `details` | Optional context for `sast`, `secret`, `iac` or `advisory` findings. For GHSA, `details.advisory.source` distinguishes repository and global disclosures. |
+| `source_data` | The vendor fields retained for this record. Keep the original export when you need scan-wide diagnostics or inventory. |
## Operate the two destinations
-Local readback returns `sourceKey`, `sourceFindingId`, `version`, `evidence` and
-`assessment` alongside the local record ID. The Cloud publisher sends
-`source.provider` and `source.source_key` with an expected version, source
-finding ID and evidence for each item. Receipt IDs for the source report,
-observation and canonical finding are **destination** references, not vendor
-occurrence IDs. Use the source report for evidence, not the receipt counts.
-
-**One project, local triage.** From a checkout with a saved native Snyk report
-outside it:
-
-```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-codex-security publish findings ../reports/snyk.json --to local --provider snyk \
- --repository . --source-key example/project/main/root/native-sca --dry-run --format json
-```
-
-Check the selected repository, IDs, evidence and exclusions. Repeat without
-`--dry-run` and confirm; then run
-`codex-security findings imported . --format json`. Workbench SQLite stores the
-snapshot and version. Repeating identical evidence is unchanged. A source
-repository claim is checked against configured remotes when available; when
-provenance is absent you must verify the target yourself. These records remain
-`not_assessed`, separate from `findings list` and completed scans. To
-investigate, compare the reported installed version or location against the
-selected revision; import alone is not validation.
-
-**Many repositories, reviewed publication.** Partition complete exports by
-repository and source namespace first; don't attach a fleet-wide export to one
-destination. For example, preview one Endor project and context against its
-connected repository:
-
-```sh
-codex-security publish findings ../reports/endor-project-main.json --to cloud \
- --repository https://github.com/example/project --provider endor \
- --source-key example-namespace/example-project/main --dry-run --format json
-```
-
-This reads authorized destination state; it doesn't upload. Check the account,
-repository, environments, eligible records and exclusions before confirming.
-Local file imports do not apply the Cloud evidence limits. Cloud limits include
-256 KiB per finding, depth 20 and 5 MiB per request; an oversized record is
-excluded, not truncated. For example, 240 eligible findings for one destination
-require at least three requests at the 100-item ceiling, possibly more for size
-or environment boundaries.
-
-Read the
-[result and recovery contract](../../sdk/typescript/docs/cli.md#results-and-exit-codes):
-`partial` (exit 1) can include acknowledged records alongside exclusions or item
-errors. Correct the rejected records; do not treat the whole selection as
-failed. After `interrupted` (exit 2), a lost response is **not** proof of
-rejection. A reset can also fail during preparation. Inspect the error,
-receipts, cumulative counts and unacknowledged items before choosing how to
-recover:
-
-- **`savedSubmission` identifies an existing checkpoint:** rerun the same
- approved command with unchanged input, source key, destination and endpoint to
- resume its saved requests. This also applies if the initial request was saved
- but persisting a later receipt failed.
-- **No resumable checkpoint:** a repository reset retires the old request, and
- an initial checkpoint-write failure may leave no request to resume. Inspect
- the destination and correct the error; run a fresh `--dry-run` and get fresh
- approval before publishing. Do not blindly replay a command containing
- `--yes`.
-
-Verified source-report readback is evidence of import, not a security
-assessment, UI visibility or a vendor state change.
-
-**Privacy.** Reports, full JSON previews, local state and saved Cloud request
-bodies can contain source snippets, secret metadata, internal paths, private
-advisories and vendor links. Select only authorized metadata (not credential
-values), keep artifacts outside the checkout with restricted access and review
-the destination before uploading. Don't paste raw evidence or checkpoints into
-public tickets, CI logs or PRs. The readers do not promise to redact them.
+**Local.** Run `codex-security findings imported PATH --format json` with the
+repository path from the preview. Each record includes
+`sourceKey`, `sourceFindingId`, `version`, `evidence` and `assessment`.
+
+**Cloud.** Each item includes a `source_finding_id` and an `expected_version`.
+Check the per-item result for conflicts. The receipt's source-report,
+observation and canonical-finding IDs identify Cloud records. Read the source
+report for the imported evidence.
+
+Cloud allows up to 256 KiB and 20 levels of nesting per finding. The publisher
+batches up to 100 items and 5 MiB per request. Local file imports do not apply
+these Cloud limits.
+
+Select only authorized scanner metadata when collecting a report. Exclude
+credential values before import. A reader can retain the entire selected record in
+`evidence.source_data`. Confirm the destination before publishing.
+
+Reports, output and saved requests can contain source snippets, private
+advisories and secret metadata. Keep the export, preview, import result and
+readback private. If a job captures terminal output, redirect standard output
+and diagnostics for all three commands to private files outside the checkout.
+Keep these files out of job logs and public issues.
+
+### Retry a Cloud submission
+
+A partial result can include accepted records. Inspect the receipts, item
+failures and exclusions. If the connection dropped, Cloud may have accepted a
+request before the response was lost.
+
+1. If the interrupted result includes `savedSubmission`, keep that checkpoint.
+ Preview the original export with `--dry-run --format json` using the same
+ build, state directory, Cloud account, endpoint and import settings.
+2. Check `accountId`, `destination` and `resumed` in the preview. When `resumed`
+ is true, confirm the command to continue with the saved request IDs, bodies
+ and expected versions. When it is false, review the fresh submission before
+ confirming. If a repository reset retires the old submission and preparation
+ returns an error, run `--dry-run` again and review the new destination and
+ environment before confirming.
+
+With the SDK, repeat the preparation call that created the submission, using
+the same options. For `prepareExternalPublication()`, supply the original
+export file. For `prepareNormalizedExternalPublication()`, supply the original
+`ExternalFindings`. Check `preview.resumed` before calling `publish()`.
+Changing the findings prepares a new submission.
+
+See [results and exit codes](../../sdk/typescript/docs/cli.md#results-and-exit-codes)
+for cumulative counts and interrupted readback.
diff --git a/docs/scanner-imports/semgrep.md b/docs/scanner-imports/semgrep.md
index f8b67dc7f..27752cea1 100644
--- a/docs/scanner-imports/semgrep.md
+++ b/docs/scanner-imports/semgrep.md
@@ -1,127 +1,109 @@
# Import Semgrep Code findings
-Vendor finding import and readback require `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`.
-See the [opt-in instructions](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally)
-and [how saved scanner reports map to imported evidence](schema-guide.md).
+Import a saved Semgrep Code CLI or CI report into the local workbench or Cloud.
+Native JSON preserves original severities and snippets when available. The reader
+also accepts self-contained Semgrep SARIF 2.1.0. Either format can be gzipped.
-Prefer native **Semgrep Code/SAST CLI or CI JSON** for this reader. It preserves
-the scanner's original severity and source evidence. Self-contained SARIF 2.1.0
-is a compatibility path. Both formats may be plain or gzip-compressed.
+## Quick start
-This reader does not accept Platform API, Guardian or MCP response envelopes,
-or a general Supply Chain or Secrets feed. Those products and acquisition
-contracts require separate mappings; installing a plugin does not change the
-formats accepted here.
+From the scanned repository's root, set `report` to the saved report and
+`repo_url` to its credential-free HTTP(S) repository URL. Choose a stable source key for this
+organization, project and branch. Enable external imports for this shell.
-To produce JSON locally, run the following from the source repository root with
-your selected SAST rules. This runs a new scan; it does not retrieve earlier
-findings from Semgrep AppSec Platform.
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+report=../reports/semgrep.json
+repo_url=https://github.com/example/project
+source_key=example/project/main
+```
+
+If you need a new report, run Semgrep in the repository root with your SAST
+rules. Use a private temporary directory outside the checkout for this run.
+
+```sh
+report=
+report_dir=$(mktemp -d) &&
+ semgrep scan --config /path/to/sast-rules.yaml --json-output "$report_dir/semgrep.json" . &&
+ report="$report_dir/semgrep.json"
+```
+
+After a successful scan, or with an existing report, preview the selected file locally.
```sh
-semgrep scan --config /path/to/sast-rules.yaml --json-output semgrep.json .
-codex-security publish findings semgrep.json --to local \
- --provider semgrep --source-key ORGANIZATION/PROJECT/BRANCH \
- --source-repository-url https://github.com/example/project \
- --repository . --dry-run --format json
+codex-security publish findings "$report" --to local --repository . \
+ --provider semgrep --source-repository-url "$repo_url" \
+ --source-key "$source_key" --dry-run --format json
```
-Existing CI jobs can add `--json-output semgrep.json` to their SAST scan and pass
-that artifact to the publisher. With authenticated `semgrep ci`, select `--code`;
-its output follows the job's policy and PR/baseline scope and may contain only new
-blocking findings. It is not a complete inventory of Platform findings.
-[CLI output and scope reference](https://docs.semgrep.dev/cli-reference).
+## Import and verify
+
+Review the source and destination repositories, findings and exclusions. The
+declared source URL must match a comparable configured Git remote when one
+is available. Rerun the local preview command without `--dry-run`, confirm
+the import, then read back the unassessed records. Local import needs no Cloud account.
-Review the findings, source repository and exclusions, then repeat the command
-without `--dry-run` and confirm the import, or add `--yes` after review. Local
-imports require no Cloud login and store unassessed evidence in the workbench
-SQLite database. Read it with `codex-security findings imported . --format json`.
-Repeated imports with the same source identity update the same records; omitted
-records remain stored. See the movement behavior under Evidence and identity.
-They do not create a completed scan or automatically assess or patch findings.
+```sh
+codex-security findings imported . --format json
+```
-For Cloud, use the same report and source selection with a Cloud destination:
+To publish the same report, sign in to a Cloud account with access to the
+repository and a deployment that accepts the `semgrep` provider. Preview the
+destination, repeat without `--dry-run` and confirm. Check the result's
+`verified` count and any exclusions or failures.
+[Cloud publication](../../sdk/typescript/docs/cli.md#publish-findings-to-cloud)
```sh
-codex-security publish findings semgrep.json --to cloud \
- --provider semgrep --source-key ORGANIZATION/PROJECT/BRANCH \
- --source-repository-url https://github.com/example/project \
- --repository https://github.com/example/project --dry-run --format json
+codex-security publish findings "$report" --to cloud --repository "$repo_url" \
+ --provider semgrep --source-repository-url "$repo_url" \
+ --source-key "$source_key" --dry-run --format json
```
-Keep the same source key for one organization, project and branch across runs.
-`--source-repository-url` declares where the report came from; the importer checks
-it against configured local Git remotes or the Cloud destination. Cloud requires
-an authorized repository and support for the `semgrep` provider. Local SARIF
-imports also check every original `versionControlProvenance.repositoryUri` on
-accepted findings. Unknown Git hosts keep case-sensitive repository paths.
-
-## Existing Platform findings
-
-Semgrep's official
-[Guardian Codex plugin](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex)
-can select and inspect existing findings. Its output is not accepted by this
-reader. A Platform importer needs a mapping qualified against the hosted tools'
-actual responses, repository/ref filters and pagination using an authorized test
-tenant. The separate local `semgrep mcp` server also exposes `semgrep_findings`,
-but its current tool
-returns a limited list without continuation metadata. It cannot establish a
-complete export. [Official MCP implementation](https://github.com/semgrep/semgrep/blob/fe209763a4a2ccfcdf6434e6c332edc24a2f586e/cli/src/semgrep/mcp/server.py).
-
-For an automated acquisition path, Semgrep's
-[findings API](https://docs.semgrep.dev/semgrep-appsec-platform/semgrep-api) supports
-pagination with a Web API token. Its Platform finding objects
-need their own mapping into the shared publisher; they are not CLI `results`
-objects. Do not rename an API/MCP response to `semgrep.json` or reconstruct a scan
-report from a summary. No manual website export is required for either path.
-
-## Evidence and identity
-
-JSON preserves original severity, rule, CWE IDs, source range, snippets when
-available and ignored state. SARIF retains its selected result and rule, including
-trace and fix evidence. Its Critical and High ratings both become diagnostic
-`error`, displayed here as High; prefer JSON when that distinction matters.
-Original evidence stays in `source_data`, and source state stays separate from a
-Codex assessment.
-
-Cloud imports apply the service's evidence limits, including a maximum JSON
-depth of 20. A deeply nested taint trace can exceed that bound and be excluded
-with a reason in the Cloud preview. Local storage does not impose the Cloud
-size or depth limits. Neither path flattens or truncates accepted traces.
-
-Keep the supplied JSON `extra.fingerprint` or SARIF `matchBasedId/v1`
-fingerprint. If a later report supplies the same fingerprint after the code
-moves, importing it under the same repository and source key updates that record
-with the new range; the raw fingerprint stays in `source_data`.
-
-Community Edition may omit the fingerprint or emit `requires login`. The fallback
-identity uses the rule, literal path and range. Moving such a finding creates a
-second record, and the earlier record remains stored. The importer does not
-infer that they are the same finding, merge them or delete the earlier record.
-Read back both with `codex-security findings imported . --format json` before
-selecting evidence for assessment. A current checkout does not establish the
-report's revision or branch.
-
-The adapter accepts SAST only. Select SAST rules or a Code-only CI scan, since
-SARIF may omit enough product metadata to distinguish Secrets. Identifiable
-Supply Chain and Secrets records are excluded. Reports with scan errors,
-unsuccessful SARIF invocations or scan-error notifications are rejected. The
-preview reports invalid findings and duplicate source identities before import.
-
-SARIF supports direct artifact URIs and Semgrep's native `%SRCROOT%` marker without
-a base definition. Native paths retain literal percent characters; direct URIs
-are decoded once. Indexed artifacts and unresolved bases remain in original
-evidence without mapped repository locations. CE records with these references
-are excluded because they lack a usable identity. JSON scan-wide path inventories
-and timing tables are omitted from individual findings. SARIF artifact inventories
-are omitted when they are unrelated to the selected finding; required inventories
-retain their original entries and indexes. Empty external-property reference
-containers are accepted, while actual external file references are rejected.
-
-SDK callers pass `{ sourceRepositoryUrl }` to `normalizeSemgrepFindings`,
-`normalizeSemgrepSarif`, or `readSemgrepFindings`. When passing that normalized
-output directly to `prepareNormalizedLocalImport`, supply the original SARIF
-repository references in the third argument's `sourceRepositories`; the file
-importer forwards them automatically. For an independently known GitHub custom
-host, use `{ url, platform: "github" }` for its references. The Semgrep file reader
-accepts native reports, not normalized JSON/JSONL exports.
-See the [native output fields](https://docs.semgrep.dev/semgrep-appsec-platform/json-and-sarif).
+## Reference
+
+### CI artifacts
+
+A saved native JSON report from a Code-only `semgrep ci` job is also accepted.
+The job's policy and baseline determine which matches the report contains.
+A job can exit 1 for blocking findings and still produce a valid report. Keep
+the CI job's product selection and exit status. From your workstation, set
+`report` to a private copy of the artifact and follow the local preview above.
+[Semgrep CLI reference](https://docs.semgrep.dev/cli-reference)
+
+### Evidence and identity
+
+Semgrep JSON retains the result, rule, CWE IDs, source range, snippets and
+ignored state when supplied. SARIF retains the selected rule and result,
+including trace and fix evidence. Critical and High both map to SARIF `error`,
+which imports as High. Deeply nested traces can exceed Cloud limits and appear
+in `excluded`. Keep the original report for run-wide inventories and timing.
+[Semgrep output fields](https://docs.semgrep.dev/semgrep-appsec-platform/json-and-sarif)
+and [imported evidence](schema-guide.md)
+
+The reader identifies a match by JSON `extra.fingerprint` or SARIF
+`matchBasedId/v1` when supplied. Reimporting the same fingerprint under the
+same source key and repository updates its location. When Community Edition
+omits the fingerprint or returns `requires login`, the rule, literal path and
+range identify the match. Moving it creates another record. Omitted records
+remain stored.
+
+Use SAST-only rules. Identifiable Supply Chain and Secrets results are
+excluded, and SARIF may lack enough product metadata to identify all of them.
+Scan errors or unsuccessful SARIF invocations prevent import. SARIF supports
+direct artifact URIs and Semgrep's native `%SRCROOT%` paths. Indexed artifacts
+or unresolved bases stay in raw evidence and need a fingerprint for identity.
+External property files are unsupported.
+
+SDK callers pass `sourceRepositoryUrl` to `normalizeSemgrepFindings`,
+`normalizeSemgrepSarif` or `readSemgrepFindings`. The file import forwards
+SARIF repository provenance automatically. When calling `prepareNormalizedLocalImport`
+directly, pass the original repository references in its third argument's
+`sourceRepositories`. Use `{ url, platform: "github" }` for a verified custom
+GitHub host.
+
+### Existing Platform findings
+
+This file reader accepts scan reports. Semgrep Guardian, MCP and the Platform
+findings API return different records. For this workflow, use a Code scan
+artifact. [Guardian for Codex](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex),
+[Semgrep MCP implementation](https://github.com/semgrep/semgrep/blob/fe209763a4a2ccfcdf6434e6c332edc24a2f586e/cli/src/semgrep/mcp/server.py)
+and [Platform findings API](https://docs.semgrep.dev/semgrep-appsec-platform/semgrep-api)
diff --git a/docs/scanner-imports/snyk.md b/docs/scanner-imports/snyk.md
index 3c05f9151..2a387c026 100644
--- a/docs/scanner-imports/snyk.md
+++ b/docs/scanner-imports/snyk.md
@@ -1,172 +1,126 @@
-# Snyk Open Source imports
+# Import Snyk Open Source findings
-Vendor finding import and readback require `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`.
-See the [opt-in instructions](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally)
-and [how saved scanner reports map to imported evidence](schema-guide.md).
+Import Open Source dependency vulnerabilities from a saved `snyk test` JSON report,
+a `snyk-findings-export/v1` plugin bundle or self-contained Open Source SARIF.
+Native CLI JSON preserves individual dependency paths and remediation details.
-Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
-to collect a fresh workspace scan. The existing
-[`publish findings` command](../../sdk/typescript/docs/cli.md#import-snyk-open-source-findings)
-accepts its `snyk-findings-export/v1` bundle with `--provider snyk` for local
-storage or Cloud publication. For CLI automation, prefer native JSON from
-`snyk test`; Open Source SARIF remains a compatibility input.
+## Quick start
-**Scope: Open Source SCA vulnerabilities only.** License findings, Snyk Code,
-Container, IaC, SBOM results and existing platform backlog ingestion are outside
-this adapter. License records in otherwise supported reports appear as explicit
-exclusions; they are not imported as vulnerabilities.
+From the repository root, set `report` to a saved native JSON report.
+Choose a stable source key for the repository, branch, scan target and format.
+For repeat imports, use the exact key from your previous run.
+Enable external imports and preview the local destination.
```sh
-codex plugin marketplace add snyk/studio-recipes
-codex plugin add snyk@snyk-studio-recipes
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+report=../reports/snyk-open-source.json
+source_key=github.com/example/project/main/root/native-sca
+```
+
+If you need a new report, use an authenticated Snyk CLI and the project's
+package tooling. For a project with `package.json`, run the following in the
+repository root. Use a private temporary directory outside the checkout for
+this run. Exit 1 means findings. Other nonzero exits stop acquisition.
+[Snyk CLI test](https://docs.snyk.io/developer-tools/snyk-cli/commands/test)
+
+```sh
+report_dir=$(mktemp -d) || exit "$?"
+report="$report_dir/snyk-open-source.json"
+snyk_status=0
+snyk test --file=package.json --json-file-output="$report" || snyk_status=$?
+if [ "$snyk_status" -gt 1 ]
+then
+ exit "$snyk_status"
+fi
+```
+
+Preview the selected report locally.
+
+```sh
+codex-security publish findings "$report" --to local --repository . \
+ --provider snyk --source-key "$source_key" --dry-run --format json
```
-Ask Codex: “Use snyk-findings-export to export SCA findings from this repository’s Git root to
-snyk-findings.json. Run SCA only.” The plugin uses the local Snyk MCP server and
-needs Snyk authentication and the package tooling required by the project. Check
-its scan coverage and limitations before importing. Preview local storage with a
-repository path; no Cloud login is required:
+## Import and verify
+
+Review the scan coverage, destination, findings and exclusions. Confirm the
+checkout matches the scanned project, especially when the report has no Git URL.
+Repeat the local command without `--dry-run`, confirm, then read back the
+unassessed records. Local import needs no Cloud login.
```sh
-codex-security publish findings snyk-findings.json --to local \
- --provider snyk --repository ./project \
- --source-key github.com/example/project/main/root/plugin-sca --dry-run
+codex-security findings imported . --format json
```
-Or preview publication to a connected Cloud repository:
+For Cloud, use a signed-in account with access to the connected repository.
+Preview the same file and source key, review the destination, then repeat
+without `--dry-run` and confirm. Check the result's `verified` count, failures
+and exclusions. [Cloud publication](../../sdk/typescript/docs/cli.md#publish-findings-to-cloud)
```sh
-codex-security publish findings snyk-findings.json --to cloud \
- --provider snyk --repository https://github.com/example/project \
- --source-key github.com/example/project/main/root/plugin-sca --dry-run
+codex-security publish findings "$report" --to cloud \
+ --repository https://github.com/example/project --provider snyk \
+ --source-key "$source_key" --dry-run --format json
```
-Remove `--dry-run` from the selected command to review and confirm the import.
-The existing `--yes` option allows an already approved, noninteractive import.
-Read local records with `codex-security findings imported ./project --format json`.
-See the common [local import flow](../../sdk/typescript/docs/cli.md#import-vendor-findings-locally)
-or [Cloud publication flow](../../sdk/typescript/docs/cli.md#import-wiz-findings)
-for destination requirements, confirmation and result handling. The publisher
-imports the saved evidence; it does not start another Snyk scan or assessment.
-
-This adapter imports Open Source SCA vulnerabilities. Other products, licenses
-and SBOM results in a mixed plugin bundle appear as exclusions. It preserves the
-complete selected finding, native MCP record, collection context, availability
-states and coverage limitations. Ignored status remains source evidence; it does
-not mark the finding fixed or assessed locally or in Cloud. A dirty workspace retains its
-revision in the original evidence without claiming it as the exact scanned commit.
-
-The MCP output is a projection: its SCA mapper shortens descriptions and can omit
-alternate dependency paths. The plugin cannot recover data its MCP server did
-not return. See the [official SCA mapper](https://github.com/snyk/studio-mcp/blob/main/internal/oss/map.go).
-The bundle's composite occurrence identity includes package version and dependency
-path. Keep the same source key for each repository, branch and scan target across
-exports. A change to the composite identity produces a new source ID; changing
-only the evidence preserves that ID. Plugin v1 paths are relative to the scan
-target and do not carry its Git-root offset. They remain in original evidence
-without being projected as repository locations or package manifest paths.
-
-### How to read import counts
-
-For the same repository and source key, `created` means a new source identity.
-For an existing identity, `updated` means the whole evidence snapshot changed;
-`unchanged` means it did not. These counts describe imported Snyk evidence, not
-new vulnerabilities, fixes, or Codex assessments.
-
-Each plugin finding retains its collection context. If a scan's `issueCount`
-falls from three to two, both remaining findings can get a new version even if
-neither occurrence changed. Their source IDs stay the same, and omitting the
-third finding does not close it. Native CLI JSON likewise retains the project's
-[`uniqueCount`](https://github.com/snyk/cli/blob/8b2d0a695c6b1b31f681e32039db958fba6f0c2f/src/lib/snyk-test/run-test.ts#L555)
-when supplied. It counts distinct vulnerabilities, not dependency-path
-occurrences: two paths to the same advisory contribute one to the count.
-Keep the original evidence; do not edit or strip scan metadata to suppress updates.
+## Reference
### Native CLI JSON
-For automation, use the [Snyk CLI](https://docs.snyk.io/developer-tools/snyk-cli/commands/test)
-with `--json-file-output`. This preserves native descriptions, dependency paths,
-identifiers and remediation evidence before the MCP or SARIF projections. For
-example, run from the selected repository root:
+Use ungrouped output. For several projects under one scan root, replace
+`--file=package.json` with `--all-projects --fail-fast` and handle exit codes
+as above. Without `--fail-fast`, Snyk can omit results for projects it could
+not scan. Project errors in the input stop the import. Keep independent scan
+roots in separate reports with separate keys. License records are excluded.
+[Snyk multi-project scan options](https://github.com/snyk/cli/blob/main/help/cli-commands/test.md#--fail-fast)
+
+A native occurrence is identified by package manager, manifest, advisory,
+package name and version, and dependency path. The reader retains the original
+vulnerability, project context and suggested fixes. Paths are target-relative.
+An exact Git revision or path from the repository root requires other evidence.
+[Native result fields](https://github.com/snyk/cli/blob/main/src/lib/snyk-test/legacy.ts)
+
+### Snyk plugin export
+
+Install the Snyk plugin in Codex and sign in to Snyk. From the repository's
+Git root, ask Codex to use `snyk-findings-export` to run an SCA-only scan and
+write its export to a file outside the checkout.
```sh
-snyk_status=0
-snyk test --file=package.json --json-file-output=snyk-open-source.json || snyk_status=$?
-if [ "$snyk_status" -gt 1 ]; then
- exit "$snyk_status"
-fi
-codex-security publish findings snyk-open-source.json --to cloud \
- --provider snyk --repository https://github.com/example/project \
- --source-key github.com/example/project/main/root/native-sca --dry-run
+codex plugin marketplace add snyk/studio-recipes
+codex plugin add snyk@snyk-studio-recipes
```
-Snyk exits 1 when it finds vulnerabilities. Other failures must stop acquisition;
-do not publish an older report after a failed scan. `snyk test --json` emits the
-same result to stdout. A single project object and the array produced by
-`--all-projects` under one scan root are supported. For multiple projects, replace
-`--file=package.json` with `--all-projects --fail-fast` and keep the exit-code
-handling above. Snyk's [`--fail-fast` option](https://github.com/snyk/cli/blob/main/help/cli-commands/test.md#--fail-fast)
-stops the scan when a project fails. Without it, Snyk continues and omits
-vulnerability results for projects it could not scan. Keep independent scan roots
-in separate reports and source keys; identical manifest and dependency paths from
-different roots otherwise have ambiguous identities. A project error in the
-supplied JSON stops the import, including an error mixed with successful results.
-A successful empty scan has zero findings; a license-only report instead lists
-its records as exclusions. Use the default ungrouped JSON output;
-`--group-issues` combines package and dependency-path fields and is not supported.
-
-The mapper follows the CLI's [native result types and dependency-path producer](https://github.com/snyk/cli/blob/main/src/lib/snyk-test/legacy.ts).
-It preserves the complete selected vulnerability and the surrounding project
-context. Identity uses the package manager, literal display manifest (falling back
-to the target file), advisory, package name/version and dependency path. Different
-occurrences remain separate. A duplicate identity is excluded rather than merged.
-Native JSON does not establish a Git-root offset, repository URL or exact scanned
-revision: paths and scan context stay in original evidence, without being claimed
-as repository locations or manifest paths. Suggested upgrades and fixed versions
-remain source advice, not verified patches.
-
-To store this JSON locally, use the same file, provider and source key with
-`--to local --repository .` from the repository root. No Cloud login is required.
+Use the saved bundle as `report` and a source key ending in `plugin-sca`.
+Check its coverage and limitations. The bundle retains collection context,
+ignored status and each selected MCP record. The MCP mapper can shorten
+descriptions and omit alternate dependency paths. Its paths are relative to
+the scan target. A dirty workspace does not establish an exact scanned commit.
+[Official 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
-Existing Open Source SARIF exports are still accepted. Generate one with
-`snyk test --file=package.json --sarif-file-output=snyk-open-source.sarif` and
-handle the exit code as above. For multiple projects, use `--all-projects --fail-fast`
-with the same exit-code handling. Import with `--provider snyk` and a stable source
-key ending in `sarif-sca`. The mapper follows the
-[Open Source SARIF formatter](https://github.com/snyk/cli/blob/main/src/lib/formatters/open-source-sarif-output.ts).
-It retains the selected rule, result and report context. Unrelated artifact
-inventories are omitted when direct manifest locations do not depend on them;
-indexed context and matching artifact metadata are retained. Empty
-external-reference containers are accepted; reports with actual external property
-references remain unsupported. SARIF groups an advisory's occurrences and exposes
-one package coordinate, so native JSON is preferable for preserving individual
-dependency paths and remediation fields. Manifest paths are literal target-relative
-paths, including percent characters, without a Git-root offset. They stay in
-original evidence with synthetic line numbers instead of being projected as
-repository locations or package manifest paths. Snyk
-Code, Container, IaC, external SARIF property files and indexed or base-relative
-manifest locations are unsupported.
+For Open Source SARIF, use `--sarif-file-output` instead of `--json-file-output`
+and handle exit codes as above. Use a source 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. It accepts direct
+manifest paths and self-contained reports. Indexed or base-relative manifest
+locations and external property files 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
-All three formats support either destination, but their source IDs differ. Use
-one acquisition format consistently for a repository, branch and scan target,
-with a stable source key. Use a separate key if switching formats; the importer
-does not guess equivalence between plugin occurrences, native JSON occurrences
-and SARIF advisory groups. Switching does not remove earlier imported records.
-
-Unsafe or absolute paths remain in original evidence. Known source repository
-claims must match the selected Cloud repository or, for local imports when Git
-remotes are configured, one of those remotes. For Cloud publication, standard SSH
-remotes on the selected connected GitHub or GitHub Enterprise host match its HTTPS
-repository when using the default SSH port or port 22. The public
-`ssh://[email protected]:443/owner/repository.git` endpoint also matches
-`github.com`. Other hosts, nondefault SSH ports and explicit HTTPS ports remain
-distinct; the importer does not infer an Enterprise host from the artifact alone.
-Unknown repository context requires the user to select the correct destination.
-Gzip and UTF-8 BOM input are supported. Records exceeding the destination's
-field or total-size limits appear as exclusions in the preview, without
-truncation. Inspect preview exclusions before importing. Synthetic tests do
-not establish live tenant, plugin-runtime or deployed Cloud compatibility.
+Use a separate source key for each acquisition format because each produces
+different source IDs. For a given repository and source key, a new ID creates a
+record. A changed evidence snapshot updates its version. For example, changing
+a plugin scan's `issueCount` can update records whose underlying occurrence
+stayed the same. Identical evidence is counted as `unchanged`. Omitting a record
+from a later report leaves it stored. The native CLI's `uniqueCount` counts
+distinct vulnerabilities across dependency paths. [Imported evidence and identity](schema-guide.md)
+and [Snyk count definition](https://github.com/snyk/cli/blob/8b2d0a695c6b1b31f681e32039db958fba6f0c2f/src/lib/snyk-test/run-test.ts#L555)
+
+Known source Git URLs must match a comparable configured Git remote when one
+is available locally, or the selected Cloud repository. Use the preview's exclusions to identify skipped
+records, including unsupported products and licenses. Snyk Code, Container,
+IaC, SBOM results and hosted backlog responses are outside this file import.
diff --git a/docs/scanner-imports/sonar.md b/docs/scanner-imports/sonar.md
index ca0982eef..ed5411596 100644
--- a/docs/scanner-imports/sonar.md
+++ b/docs/scanner-imports/sonar.md
@@ -1,29 +1,15 @@
-# Import SonarQube Cloud security issues
+# Import SonarQube Cloud findings
-Import the open security issues for a SonarQube Cloud project or the issues
-you selected in the SonarQube plugin for Codex. The live import uses the
-authenticated `sonar` CLI to read findings from the project's Issues view.
-Keep the same Sonar server and organization selected until the fetch finishes.
-A live fetch saves a capture so you can review and publish the same records later.
+Import selected security issues from one SonarQube Cloud project and branch or
+pull request. The live collector uses your authenticated Sonar CLI and saves the
+selection in a capture you can replay locally or publish to Cloud.
-## Start in Codex
+## Quick start
-In the checkout, ask the SonarQube plugin to show security issues on a branch
-or pull request. Then ask Codex Security to “import those two findings locally”
-or “import those two findings locally and publish them to Codex Security Cloud.”
-The [publish-findings skill](../../plugins/codex-security/skills/publish-findings/SKILL.md#sonarqube-cloud-issues)
-uses the project's key, the selected ref, and the original Sonar issue keys to
-retrieve the full records and preview the destination. You can also start in
-the terminal with those same identifiers. If you installed only the Codex
-Security plugin, install a version of `@openai/codex-security` that includes
-the Sonar importer from a trusted directory, then run that CLI in the checkout.
-
-## Preview a local import
-
-Run the command from the matching checkout. Enable external imports for the
-session. If you already use the Sonar plugin's issue list, the collector uses
-the same `sonar` login. For first-time setup, sign in with `sonar auth login`
-using an account that can browse the selected project.
+From the matching checkout root, use a Codex Security CLI with `import sonar` and
+a Sonar CLI signed in to the project's organization. Run `sonar auth login`
+if needed, using an account with project browse access. Keep the same Sonar
+server and organization selected while collecting.
```sh
export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
@@ -31,87 +17,78 @@ codex-security import sonar --sonar-project example_project --sonar-branch main
--sonar-issue ISSUE_A --sonar-issue ISSUE_B --dry-run --format json
```
-For a pull request, replace `--sonar-branch main` with, for example,
-`--sonar-pull-request 42`. With neither ref option, the collector reads the
-project's main branch. Omit the issue options to collect open security
-issues for the selected project and ref. If the search exceeds Sonar's
-10,000-result window, pass the keys of the issues you want to import.
-You can omit `--sonar-project` when
-Sonar binds the checkout's Git origin to exactly one project in the signed-in
-organization. For a monorepo with several Sonar projects, pass the project key
-you want to import. If Sonar cannot supply the project's
-repository binding, verify its Git URL in Sonar and retry the preview with
-`import sonar CAPTURE --source-repository-url GIT_URL --dry-run --format json`
-using the reported capture path. Check the target and selection before importing.
-
-If the checkout uses an SSH host alias, supply the project's verified HTTPS URL
-with `--source-repository-url` so the importer can compare the repository path.
-The saved preview remembers that mapping for this checkout and its configured
-fetch URLs, including when you preview the capture for Cloud. If the fetch URLs
-change, verify the new mapping and preview again. SDK callers can pass the same
-URL as `sourceRepositoryUrl` when preparing a local import.
-
-The preview saves a private copy even when the input is a file. Use the path
-it returns in `capture` to import the reviewed evidence into the local
-workbench. Use the preview's `repository` path to read the findings back:
+Use the project and issue keys from Sonar's Issues view or the SonarQube
+plugin for Codex. A selection by key includes the requested issues regardless
+of status. To preview open and confirmed security issues for the ref, omit
+the `--sonar-issue` flags. For a pull request use `--sonar-pull-request 42` in place
+of `--sonar-branch main`. If both are omitted, Sonar uses the main branch.
+[Sonar CLI authentication](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide#step-2-authenticate)
+
+## Import and verify
+
+Review the repository, ref, selected issues and exclusions. The preview
+returns a private `capture` file even for a file input. Pass that exact path
+to confirm. Read back the unassessed records from the preview's `repository`.
+A local import needs no Codex Security Cloud login.
```sh
-codex-security import sonar "/path/from/capture.json" --yes
+codex-security import sonar "/path/from/local-preview.json" --yes
codex-security findings imported "/checkout/from/preview" --format json
```
-For a portable capture, or if you change the checkout or Codex Security state
-directory, run `--dry-run` there first and pass the returned path to `--yes`.
-
-Codex Security keeps each Sonar issue key and its native evidence, including
-reported file ranges and available data-flow traces. For monorepos, Codex
-Security maps paths relative to the Sonar project when it can verify the
-project's base directory in the checkout. When the base is unknown, the
-native components, ranges and flows remain available in the evidence.
-Reimporting the same issue in the same source and repository updates its
-record. Imported records start as unassessed findings.
-
-## Publish the same capture to Cloud
-
-From the same checkout, preview the capture with your Codex Security Cloud
-login. Your Cloud account must be enabled for external imports, and the
-deployment must accept the `sonar` source provider. Review the Cloud account,
-repository, environments, counts, and exclusions before confirming. Use
-the `capture` path from this Cloud preview to confirm. If the destination
-changes, preview again and confirm using the new path. Replaying the capture
-works without a Sonar login. For a checkout without a usable Git remote,
-verify the Sonar project's repository and pass `--source-repository-url` to
-the Cloud preview. If the configured remotes point to another repository,
-use the matching checkout or add its verified upstream remote before previewing.
+To publish the same selection, sign in to a Cloud account enabled for
+external imports on a deployment that accepts `sonar`. From the same checkout,
+preview the saved file, review the Cloud account, repository, environments
+and exclusions, then use the **new capture path from the Cloud preview** to
+confirm. This command imports locally and publishes to Cloud. Check the local
+counts and Cloud verification result. Replay needs no Sonar login.
```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
```
-For a single local-and-Cloud workflow, add `--to cloud` to the first live
-preview and confirm using its saved capture. If Cloud authentication or
-repository selection fails, you can finish the local import, then rerun the
-Cloud preview with the saved capture. If an approved upload is interrupted,
-retry with the same file and destination.
+You can also start with `--to cloud` on the live preview. Preview again if
+the checkout, state directory or destination changes. If an approved upload
+is interrupted, retry with the same capture and destination.
+[Cloud publication](../../sdk/typescript/docs/cli.md#publish-findings-to-cloud)
+
+## Reference
-## Use a native JSON export
+### Project and repository selection
-If you already have the complete response from `GET /api/issues/search` for
-one project and ref, save the page object or an array containing every page.
-The file reader uses the repository URL you verified for that Sonar project:
+You may omit `--sonar-project` when Sonar maps the checkout's Git origin to
+exactly one project in the active organization. For monorepos, pass the project
+key explicitly. When a search exceeds the 10,000-result window, select issue
+keys. In Codex, you can ask to import the issues you selected in the SonarQube
+plugin. [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. When the
+checkout has comparable remotes, at least one must match. A changed fetch
+URL needs a new preview.
+
+Each Sonar issue key identifies one record within its source and repository.
+Reimport updates its evidence. File ranges and available data-flow traces
+stay in the evidence. In a monorepo, repository-relative locations also
+require a verified Sonar project base directory.
+
+### Use a native JSON export
+
+For a saved `GET /api/issues/search` response, pass a single page object only
+when it contains the entire result. Otherwise pass an array of every page, in
+order, for the same project and ref. Supply the verified repository URL and
+a stable source key for the Sonar instance, organization, project and ref.
+Native pages can omit that context. Use the exact key from a previous import
+to update the same records.
```sh
-codex-security publish findings "/path/to/sonar-pages.json" --provider sonar \
+codex-security publish findings ../reports/sonar-pages.json --provider sonar \
--to local --repository . --source-repository-url https://github.com/example/project \
--source-key sonarcloud.io/example/example_project/branch/main --dry-run --format json
```
-Keep the source key stable for the same Sonar instance, organization, project,
-and ref. For updates to a previous import, use its exact source key. The
-native page can omit the branch, project repository URL, and Sonar instance.
-Only a Codex Security capture carries the collector's context for offline replay.
-
-See [Sonar's Codex plugin](https://www.sonarsource.com/blog/now-available-sonarqube-plugin-for-codex/),
-[Sonar CLI authentication](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide#step-2-authenticate),
-and the [Codex Security Cloud publication guide](../../sdk/typescript/docs/cli.md#publish-findings-to-cloud).
+Review the preview, rerun without `--dry-run`, confirm and use
+`codex-security findings imported . --format json` to verify the local import.
diff --git a/docs/scanner-imports/veracode.md b/docs/scanner-imports/veracode.md
index aee3331f7..40022fd5e 100644
--- a/docs/scanner-imports/veracode.md
+++ b/docs/scanner-imports/veracode.md
@@ -1,18 +1,71 @@
-# Import Veracode Static Analysis policy findings
+# Import Veracode Static Analysis findings
-Use `--provider veracode` for the **Findings API** backlog of one Veracode
-application mapped to one source repository. This importer handles
-`scan_type=STATIC` in the application context. A Veracode application may
-aggregate multiple repositories or binary modules: do not bind that aggregate
-to a single checkout. Pipeline Scan JSON, sandboxes, SCA, DAST, policy pass/fail
-summaries and the findings converter's SARIF output are not this format.
+Import the Findings API policy backlog for one Veracode application that maps
+to one source repository. Choose the application context and `scan_type=STATIC`.
+An application that aggregates multiple repositories or binary modules cannot
+establish a mapping to one checkout.
-## Export unmodified Findings API pages
+## Quick start
-Set `VERACODE_APPLICATION_GUID` to the application you intend to import. Use a
-client with read access to that application and the Results API. This example
-uses HTTPie with the Veracode HMAC plugin and `jq`. Set `api` to the hostname
-for your region. Store the exported pages outside the checkout.
+With read access to the application and Results API,
+[export the complete Findings API pages](#export-findings-api-pages) to a private
+file outside the checkout. From the verified checkout root, replace the file path,
+Git URL, and source key with values for your application.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+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
+```
+
+## Import and verify
+
+Check the destination, count, and exclusions. The preview includes original
+evidence and any annotations in the selected rows. Remove `--dry-run` to
+import, then read the stored findings.
+
+```sh
+codex-security findings imported . --format json
+```
+
+Reuse the source key for exports from the same application and context. Local
+import compares the source URL with the checkout’s Git remotes when comparable
+remotes are configured. The application GUID alone cannot identify a Git URL.
+
+For Cloud, replace `--to local --repository .` with
+`--to cloud --repository CLOUD_REPOSITORY_ID` for the authorized GitHub
+repository on a deployment that accepts `veracode`. Preview again before
+confirming. For interrupted uploads, follow the
+[Cloud retry procedure](schema-guide.md#retry-a-cloud-submission).
+
+## Reference
+
+### 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.
+
+Imported findings start unassessed. Replaying an upstream resolution does not
+verify a fix. Omitted findings remain stored. Pipeline Scan JSON, sandbox
+findings, SCA, DAST, policy pass/fail summaries, and the findings converter’s
+SARIF output use other formats.
+
+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
+application and repository.
+
+### 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`.
```bash
set -eu
@@ -38,48 +91,9 @@ done
jq -s '.' "$out/pages.stream" > "$out/policy-findings.json"
```
-Collect every page from the configured API host and 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. Its preview includes the returned
-rows with their original evidence, including any annotations. If the backlog
-changes during pagination, collect it again.
-
-## Preview and import
-
-```bash
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-codex-security publish findings "$out/policy-findings.json" \
- --to local --repository ./project --provider veracode \
- --source-repository-url https://github.com/example/project \
- --source-key veracode/region/application-guid/static \
- --dry-run --format json
-```
-
-Review the destination, count and exclusions. Remove `--dry-run` to import.
-Use the same source key for later exports from the same application and
-context; an application GUID is not evidence of a Git URL. For Cloud use an
-authorized GitHub repository and a deployment that accepts provider `veracode`.
-
-Local import compares the source with the checkout’s Git remotes when
-comparable remotes are configured.
-
-If an interrupted Cloud upload reports `result.savedSubmission`, keep its
-checkpoint and use the same build, state directory, account and import settings.
-Preview the original export with `--dry-run --format json`. Check `accountId`
-and `destination`. When `resumed` is false, review the new upload before approving it.
-For `prepareNormalizedExternalPublication`, pass your original normalized
-`ExternalFindings` and check `preview.resumed` before calling `publish()`.
-Passing different normalized findings prepares a new upload. Save each finding
-with its original `source_finding_id` and `evidence.source_data` so the SDK can
-verify its application and repository when replayed with the Veracode provider.
-
-| Veracode evidence | What Codex Security tracks |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| API origin, application/context and `issue_id` | A stable policy flaw occurrence. Build number, line, CWE and the separate Pipeline flaw ID are not its identity. |
-| Native severity, CWE and flaw description | SAST evidence, preserving the original numeric severity, description and status in the raw record. |
-| Static analysis path, line and module | Reported evidence, not proof that a similarly named file exists in the checkout. No fabricated column or Git commit. |
-| Finding status, mitigation and resolution | Upstream workflow history, not a Codex assessment. Replaying an update does not mark a fix verified; omissions do not delete records. |
-
-References: [Veracode Findings API](https://docs.veracode.com/r/c_findings_v2_intro),
-[vendor-supported policy and Pipeline conversion examples](https://github.com/veracode/veracode-pipeline-scan-results-to-sarif).
+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).
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index c1457c17a..57d6c79a7 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -11,9 +11,8 @@ security plugin, and TypeScript declarations. It uses ES modules.
- Review saved findings, identify duplicates, classify severity, and suggest owners.
- Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
findings to Linear or a findings service.
-- Import [Snyk Open Source findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) from
- official plugin JSON or native CLI JSON locally or into Cloud; Open Source
- SARIF is also supported. License findings and other Snyk products are excluded.
+- Import saved scanner reports locally or publish them to Codex Security Cloud.
+ See the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) for supported vendors and formats.
- Automate scans across repositories and project components.
See the [CLI reference](docs/cli.md),
@@ -658,10 +657,12 @@ contributors. Suggestions do not assign tickets. See
`publish scan --to cloud` uploads selected findings to Codex Security Cloud.
It requires ChatGPT credentials; inference API keys and AWS credentials do not
-grant Cloud access. See [Cloud publication](docs/cli.md#publish-findings-to-cloud)
+grant Cloud access. See [Cloud publication](docs/cli.md#publish-completed-scans)
for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)
for issue creation.
+### Import external findings
+
External vendor imports are opt-in. Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`
to enable `publish findings`, `findings imported`, `import sonar`, `import github-advisories`, and
the SDK's external publication, local import/readback, Sonar issue collection, and advisory acquisition
@@ -684,70 +685,8 @@ use `ExternalPublicationOptions` for their supported formats. Both resolve the C
calling `publish()`. Imported evidence remains not assessed by Codex, and saved
requests and receipts support retries after interruption.
-Prefer each provider's supported native JSON for local and Cloud imports. Keep
-the same acquisition format for repeat imports: SARIF and CSV are compatibility
-options where supported, and changing formats can change record identities or
-replace richer evidence with less detail. See the
-[import guide](docs/cli.md#import-vendor-findings-locally) for format selection.
-
-For SonarQube Cloud, `codex-security import sonar` reads open security issues
-through the signed-in Sonar CLI. You can pass exact issue keys from the
-SonarQube plugin for Codex and save a local capture for later Cloud publication.
-See the [Sonar import commands](docs/cli.md#import-sonarqube-cloud-issues).
-
-For Amazon Inspector Code Security, use `--provider inspector` with a complete
-ListFindings JSON export and `--source-repository-url`. When the export identifies
-the repository by an ARN and name, pass `--inspector-project-arn ARN` with the ARN
-you verified for that Git URL in the SCM integration. See the
-[Inspector guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md).
-
-For Black Duck SCA, use `--provider blackduck` with a BOM-6 vulnerable-components
-export for one project version. Map that version to its source repository with
-`--source-repository-url`. See the
-[Black Duck guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/blackduck.md).
-
-For Veracode Static Analysis policy findings, use `--provider veracode` with
-every Findings API page from one application. Set `--source-repository-url`
-to the source repository mapped to that application. See the
-[Veracode guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/veracode.md).
-
-For OpenGrep, use `--provider opengrep` with native JSON or gzip and an explicit
-`--source-repository-url`. Local and Cloud imports retain unassessed OpenGrep
-evidence through the existing Semgrep source-provider contract. See the
-[OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md) for preview commands,
-coverage diagnostics, stable source identities, and local SDK assessment.
-
-For Wiz, prefer supported native JSON acquired through an authorized MCP or API
-connection. The [CSV compatibility reader](docs/cli.md#import-wiz-findings) covers
-repository package vulnerabilities (SCA) only; it does not add SAST, CSPM or
-complete code-to-cloud coverage. Both formats support gzip. The acquisition path
-still needs validation with an authorized Wiz tenant.
-
-For GitHub code scanning and GHSA advisories, save complete JSON from
-`import github` or `import github-advisories`, respectively. **GHSA import
-does not establish an installed dependency or applicability to the repository.**
-For Dependabot, save the native REST alert records from one repository using the
-[Dependabot export guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md).
-The GitHub file reader accepts all three families. Secret-scanning alerts and
-writeback to GitHub are outside its scope.
-
-Use `publish findings FILE --to local --repository PATH --provider wiz
---source-key KEY` to store the same vendor evidence in the local workbench SQLite
-database. Preview with `--dry-run --format json`, then confirm interactively or
-use `--yes`. Read it with `findings imported [REPOSITORY] --format json`; the
-repository defaults to the current directory. No Cloud login or model call is
-needed. Use `--provider snyk` for native CLI JSON, a Snyk plugin SCA bundle or
-Open Source SARIF. Prefer JSON, and keep one format and stable source key per scan
-target; switching formats creates separate source identities. See
-[local imports](docs/cli.md#import-vendor-findings-locally).
-
-Use `--provider endor` with native Endor Finding JSON; existing endorctl SARIF is
-accepted as a lossy compatibility format. See
-[Endor imports](docs/cli.md#import-endor-labs-findings).
-
-For saved GitHub code-scanning alerts, GHSA advisories, or Dependabot alerts, use
-`--provider github` with a separate stable source key for each finding family.
-See [local imports](docs/cli.md#import-vendor-findings-locally).
+For CLI examples, see [local import and readback](docs/cli.md#import-vendor-findings-locally)
+and [Cloud publication and confirmation](docs/cli.md#preview-and-publish).
The SDK's `prepareLocalExternalImport(file, options)` returns a `preview` and a
separate `import()` operation. `prepareNormalizedLocalImport(findings,
@@ -767,8 +706,6 @@ reports carry this platform in their repository inventory. If you export only th
normalized finding rows to JSONL, supply that metadata separately; the original
finding evidence does not include the surrounding inventory.
-See [Semgrep Code imports](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md) for native CLI/CI JSON, SARIF compatibility, and local or Cloud imports. Platform API and Guardian/MCP responses need a separate mapping.
-
## Findings storage and deduplication
Saved-scan deduplication uses local SQLite directly:
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 4976ceb10..df2b8cfba 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1283,7 +1283,8 @@ Supply the validation prompt again when rerunning.
## Import vendor findings locally
-Use the [scanner file import schema and capability guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md) to compare provider identities, mapped evidence and destination behavior before selecting a report.
+Store saved scanner findings in the local workbench. Choose your provider and
+export format in the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
External finding imports are disabled by default. Opt in for the current shell:
@@ -1303,30 +1304,12 @@ This flag does not affect `publish scan`, `publish check`, `scan import`, or the
existing `import github` alert collector. Disabling it retains previously imported
records; enable it again to read them with `findings imported`.
-Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
-reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
-inputs only for providers and report profiles that support them. A JSON API
-summary is not automatically a supported report; follow the provider's acquisition
-instructions and retain the original records. The readers detect supported input
-formats; `--format json` selects command output, not the input format.
-
-Keep the acquisition format consistent across imports. Depending on the provider,
-switching formats can create separate records for the same vulnerability or
-replace a richer evidence snapshot with less detail. The importer does not merge
-evidence or deduplicate equivalent vulnerabilities across different source IDs.
-
-Use the same vendor input and parser as Cloud publication, selecting a local
-repository path instead of a Cloud repository ID or URL. Supported inputs include
-Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
-[Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
-[Amazon Inspector repository findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md),
-[Black Duck SCA project-version vulnerabilities](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/blackduck.md),
-[Veracode Static Analysis policy findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/veracode.md),
-[Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
-[SonarQube Cloud issue-search pages](#import-sonarqube-cloud-issues),
-[OpenGrep native JSON](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md),
-[GitHub Dependabot repository alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md),
-and [saved GitHub code-scanning alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
+The reader detects the input format. Use `--format json` to see the full preview.
+Keep the same export format across imports. Switching formats can change the
+source finding ID or replace a detailed evidence snapshot with a shorter one.
+
+Use the same file and provider for local and Cloud imports. For local import,
+pass a checkout path to `--repository`. This example previews a saved Wiz report.
```bash
codex-security publish findings selected-wiz.json \
@@ -1362,121 +1345,41 @@ are reported, and an import with exclusions exits with status 1. Both destinatio
read the same vendor formats; Cloud's field, size and nesting limits do not apply
to local file imports.
-For OpenGrep, use `--provider opengrep` and supply `--source-repository-url`.
-The reader supports native JSON and gzip for both destinations. It uses the
-existing `semgrep` source-provider contract while retaining `OpenGrep` as the
-scanner origin; keep a stable OpenGrep-specific source key. Review report
-diagnostics as well as findings: import completion does not establish scan
-coverage. The [OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md)
-covers evidence identity, empty reports, and assessing an imported finding with
-the existing SDK validator.
-
`scan import --json` and `scan import --csv` remain separate commands for importing
Codex Security's findings schema as a saved scan; they do not accept vendor
exports.
## Import Endor Labs findings
-For local or Cloud import, prefer complete native Finding JSON from authenticated
-`endorctl`, scoped to one project and context. Omit `--field-mask` and use
-`--list-all` to finish pagination:
+Use `--provider endor` for Findings from one project and context. Export complete
+native JSON with `endorctl` and preview it against the corresponding repository.
```sh
-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 > endor-findings.json
codex-security publish findings endor-findings.json --to local \
--provider endor --repository ./project \
--source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
```
-Replace the example namespace, project UUID and local repository with your selection.
-Review the preview, remove `--dry-run` to confirm, then read the stored evidence
-with `codex-security findings imported ./project --format json`. To publish to
-Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
-file, provider and source key. The official
-[Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
-can help with setup and investigation, but summaries, counts and field-masked
-results do not replace complete Finding objects. `endorctl` reads the Endor API;
-the importer reads the saved export without maintaining an API connection or
-writing changes back to Endor.
-
-Native JSON retains severity, package and advisory data, primary SAST/AI SAST
-locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
-reports are a lossy compatibility format, retaining finding links and UUIDs;
-unavailable severity and revisions stay unknown. Both formats use the Endor UUID
-within the selected repository and stable source key as identity. Importing SARIF
-after native JSON for that UUID updates the same record by replacing its evidence
-snapshot, not merging it. Native detail absent from SARIF is removed from the
-snapshot. Use native JSON consistently for ongoing imports.
-
-Local and Cloud records remain unassessed source evidence. Local imports use the
-SQLite readback described above; Cloud imports use the login, preview,
-confirmation and retry flow below.
+For the export command, Cloud publication options and SARIF compatibility details, see the
+[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md).
## Publish findings to Cloud
### Import Snyk Open Source findings
-Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
-SBOM results and platform backlog ingestion are outside this adapter.
-
-Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
-with its `snyk-findings-export` skill to collect SCA findings from the repository's
-Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
-it does not retrieve existing platform project findings.
-
-The same saved bundle supports [local import](#import-vendor-findings-locally)
-without a Cloud login:
+Use `--provider snyk` for Open Source SCA vulnerabilities. The reader accepts
+native CLI JSON, a Snyk plugin export, or Open Source SARIF. For example, preview
+a native CLI report against a connected Cloud repository.
```sh
-codex-security publish findings snyk-findings.json --to local \
- --provider snyk --repository ./project \
- --source-key github.com/example/project/main/root/plugin-sca --dry-run
+codex-security publish findings snyk.json --to cloud \
+ --provider snyk --repository https://github.com/example/project \
+ --source-key github.com/example/project/main/root/native-sca --dry-run
```
-Or preview publication to a connected Cloud repository:
-
-```sh
-codex-security publish findings snyk-findings.json --to cloud \
- --provider snyk --repository https://github.com/example/project \
- --source-key github.com/example/project/main/root/plugin-sca --dry-run
-```
-
-Check the collection's scan outcomes and limitations. Only Open Source SCA
-vulnerabilities are imported; other products and licenses are explicit exclusions.
-The importer retains the selected finding, native MCP record and collection
-context. MCP may shorten descriptions and omit dependency paths. Plugin paths
-remain in original evidence because v1 lacks their offset from the Git root.
-
-For automation, prefer native JSON from
-`snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
-stop on other nonzero exits before importing. The existing `--provider snyk`
-autodetects a single project object or an `--all-projects` array; any project error
-stops the import. Use default ungrouped output, without `--group-issues`.
-Native JSON preserves individual dependency paths and remediation fields. Its
-paths remain original evidence because it does not establish their Git-root offset.
-
-Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
-for compatibility. Its target-relative manifest paths and synthetic line numbers
-remain original evidence, without being projected as repository locations or
-package manifest paths. All three formats accept either destination. Use a consistent
-format and stable source key per repository, branch and scan target, for example
-`github.com/example/project/main/root/native-sca` for native JSON. Their source
-identities differ: use separate keys when switching acquisition formats. Imports
-do not deduplicate across formats or remove earlier imported records.
-
-Known repository claims must
-match the selected Cloud repository or, when available, a configured local Git
-remote. Unknown repository context still requires selecting the correct target;
-the importer does not infer provenance from the current checkout.
-
-Remove `--dry-run` from the selected command to review and confirm the import, or
-use `--yes` after reviewing the preview. Read local records with
-`codex-security findings imported ./project --format json`. Imported source
-evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
-[Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
-acquisition details.
+Use a separate source key for each format because their occurrence IDs differ.
+For collection commands and the evidence available in each format, see the
+[Snyk Open Source guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md).
### Import Wiz findings
@@ -2487,10 +2390,15 @@ the [repository alert export guide](https://github.com/openai/codex-security/blo
to save the native REST records from one repository and preview them with
`--provider github`. For GHSA disclosures, use the
[advisory collector](#import-ghsa-advisories-separately).
-The following example previews local storage of a code-scanning export.
+Save the code-scanning export to a private file outside the checkout.
```bash
codex-security import github example/project --format json > /path/outside/repository/alerts.json
+```
+
+After collection succeeds, preview that file locally.
+
+```bash
codex-security publish findings /path/outside/repository/alerts.json \
--to local --provider github --repository ./project \
--source-key github.com/example/project/code-scanning --dry-run --format json
@@ -2521,8 +2429,8 @@ destination must be connected in the selected Cloud account. For local import,
the source repository must match a configured Git remote when remotes are
available; no Cloud login is required to store the acquired evidence.
-Review the destination, source, exclusions and evidence in the preview. Repeat the
-selected command without `--dry-run` and confirm it, or add `--yes` for a
+Review the destination, source, exclusions and evidence in the preview. Repeat only
+the selected `publish findings` command on the same file without `--dry-run` and confirm it, or add `--yes` for a
previously reviewed input. Local persistence and readback follow the
[local import flow](#import-vendor-findings-locally); use
`codex-security findings imported ./project --format json` to read the records.
@@ -2580,15 +2488,25 @@ software in GitHub's public advisory database. Both are evidence for
investigation, not Dependabot alerts. Check the repository’s dependency versions
and applicability separately.
+Choose the advisory source you need. To save published advisories for a
+repository, run the following command.
+
```bash
-# Read only published advisories for this repository.
codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
+```
-# Select individual public database records without enumerating the database.
+For selected records from the public advisory database, use this command instead.
+
+```bash
codex-security import github-advisories example/project \
--github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
--format json > /path/outside/repository/advisories.json
+```
+After collection succeeds, preview the saved file. To confirm, rerun only
+`publish findings` on that file without `--dry-run`.
+
+```bash
codex-security publish findings /path/outside/repository/advisories.json \
--to cloud --provider github --repository https://github.com/example/project \
--source-key github.com/example/project/security-advisories --dry-run --format json