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: give each scanner import a focused guide (#2201)

Michael D'Angelo4694a0b07044
diff --git a/README.md b/README.md
index 31e80f761..6f4114a6c 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ 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 findings from external scanners](docs/scanner-imports/README.md), including Semgrep, Snyk, and Wiz.
+- Import Semgrep, Snyk, and Wiz findings locally or publish them to Codex Security Cloud. [All scanner import guides](docs/scanner-imports/README.md).
- 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.
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.md
index d9c554af5..619dd2506 100644
--- a/docs/scanner-imports/README.md
+++ b/docs/scanner-imports/README.md
@@ -1,23 +1,22 @@
# 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/CI JSON, self-contained SARIF, or selected Platform Web API responses (SDK) |
-| [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 |
+Choose the guide for your report. Each guide shows how to preview the findings
+in a local checkout and which source key to reuse on later imports.
+
+| Guide | Supported input |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [Amazon Inspector](inspector.md) | Inspector2 `ListFindings` JSON for one Code Security repository |
+| [Black Duck SCA](blackduck.md) | BOM component vulnerabilities for one project version |
+| [Endor Labs](endor.md) | Finding JSON from `endorctl`, or SARIF with finding UUIDs |
+| [GitHub code scanning](github-code-scanning.md) | Alerts selected for one repository and Git ref |
+| [GitHub Dependabot](github-dependabot.md) | Dependency alerts exported from one repository |
+| [GitHub Security Advisories](github-security-advisories.md) | Selected repository or global advisories |
+| [OpenGrep](opengrep.md) | Native scan JSON, optionally gzip-compressed |
+| [Semgrep Code](semgrep.md) | CLI/CI JSON, self-contained SARIF, or selected Platform API pages (local SDK) |
+| [Snyk Open Source](snyk.md) | CLI JSON, a Codex plugin export, or SARIF |
+| [SonarQube Cloud](sonar.md) | Issues selected with the signed-in Sonar CLI, or saved issue-search pages |
+| [Veracode Static Analysis](veracode.md) | Findings API pages for one application's policy flaws |
+| [Wiz](wiz.md) | Native JSON, normalized JSONL, or detailed repository package vulnerability CSV |
## Preview a report
@@ -28,22 +27,51 @@ 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.
+Follow your guide's quick start to collect or select the report. Run examples
+that use `--repository .` from the checkout root, or pass the same checkout
+path you used previously. Use `--dry-run` to review the repository, source key,
+findings, and exclusions.
+Keep the export private. In automation, direct stdout and stderr for collection,
+preview, confirmation, and readback to private files outside the checkout.
+For examples that use `mktemp -d` without a path, set `TMPDIR` to a private
+directory outside the checkout if temporary files would otherwise land inside it.
+
+## Save or publish and verify
+
+The steps below apply to `publish findings FILE`. For `import sonar`,
+[confirm the capture returned by the Sonar preview](sonar.md#import-and-verify).
+
+**Local workbench.** Run the same command with the same file, checkout, and
+source key. Remove `--dry-run` and confirm the prompt.
+For noninteractive use, add `--yes` after reviewing that preview. Read back
+the stored evidence using the checkout path from the preview:
+
+```sh
+codex-security findings imported /path/to/project --format json
+```
-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.
+**Codex Security Cloud.** Use a file-backed ChatGPT login for a deployment that
+accepts the provider and a repository environment you can publish to. See
+[Cloud setup](../../sdk/typescript/docs/cli.md#preview-and-publish). Keep the
+file, provider, source key, and scanner-specific options. Set `--to cloud` and
+replace the local checkout in `--repository` with the connected repository URL
+or Cloud repository ID. Use the ID if several connectors share the URL.
+Run with `--dry-run` first. Check that `cloudApiUrl`
+is the intended API endpoint, then review the account, repository, environments,
+and exclusions. Remove `--dry-run` and confirm, or use `--yes` after that
+review. Check `status`, the `verified` and
+`unacknowledged` counts, and the `failures` and `excluded` lists. For a `partial`
+result, correct exclusions or resolve version conflicts before starting a new
+submission. If an `interrupted` result includes `savedSubmission`,
+[resume from that checkpoint](schema-guide.md#retry-a-cloud-submission).
## 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.
+Imported records start with assessment state `not_assessed`. Use the source
+evidence to check whether a finding affects your repository. For the identity
+of a record, the fields each reader retains, and how repeat imports update
+evidence, see [Imported finding identity and evidence](schema-guide.md).
-- [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)
+For findings from a completed Codex scan, see
+[Track findings in Linear, Jira, or GitHub](../../plugins/codex-security/skills/track-findings/SKILL.md)
+or [Export findings for ServiceNow](../../sdk/typescript/docs/cli.md#export-findings-for-servicenow).
diff --git a/docs/scanner-imports/blackduck.md b/docs/scanner-imports/blackduck.md
index 3c2866936..5ee4c1555 100644
--- a/docs/scanner-imports/blackduck.md
+++ b/docs/scanner-imports/blackduck.md
@@ -1,18 +1,16 @@
# Import Black Duck SCA findings
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.
+Verify in the scan configuration which Git repository that version represents.
## Quick start
-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.
+[Enable external imports](README.md#preview-a-report) and use a read-only token to
+[export the BOM-6 collection](#export-the-bom-6-collection). From the matching
+checkout root, preview the saved file with the verified Git URL and a source key
+for this deployment, project, and version.
```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 \
@@ -22,26 +20,11 @@ codex-security publish findings /private/path/blackduck.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).
+Check the source Git URL against the checkout’s configured remotes or the
+authorized GitHub repository in Cloud. A project name or component download
+URL alone cannot establish that link.
+[Save or publish and verify](README.md#save-or-publish-and-verify) using the same
+source key for subsequent exports of this project version.
## Reference
diff --git a/docs/scanner-imports/endor.md b/docs/scanner-imports/endor.md
index b5e3c3034..034914c77 100644
--- a/docs/scanner-imports/endor.md
+++ b/docs/scanner-imports/endor.md
@@ -6,50 +6,43 @@ details reported by Endor.
## 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.
+[Enable external imports](README.md#preview-a-report) and
+[export the native findings](#native-finding-json) from the intended project
+and context. From the matching checkout root, preview the saved file. Replace
+the file path, namespace, and project UUID.
```sh
-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"
-```
-
-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" \
+codex-security publish findings /private/path/endor-findings.json \
--to local --repository . --provider endor \
--source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run --format json
```
-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.
-
## 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 findings imported . --format json
-```
-
-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.
+Confirm the project and context belong to this repository. The importer retains
+the project UUID but does not look up its Git repository.
+[Save or publish and verify](README.md#save-or-publish-and-verify) using the same
+source key for later exports from this context.
## Reference
### Native Finding JSON
+Authenticate `endorctl` for the namespace that owns the project. Replace
+`YOUR_NAMESPACE` and `PROJECT_UUID`, then export the findings.
+
+```sh
+out=$(mktemp -d) &&
+ endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
+ --filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
+ --list-all --output-type json > "$out/endor-findings.tmp" &&
+ mv "$out/endor-findings.tmp" "$out/endor-findings.json"
+```
+
+The filter selects default-branch findings. For another context, change both
+the filter and source key. Keep `--list-all` and omit `--field-mask` to export
+complete Finding objects. The saved file is `$out/endor-findings.json`.
+
The importer accepts a single Finding, an array, or a `ListFindingsResponse`
containing `list.objects`. An unfinished paginated response is rejected. Native
JSON retains the complete Finding and maps severity, dependency and advisory
@@ -69,8 +62,8 @@ 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.
+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
diff --git a/docs/scanner-imports/github-code-scanning.md b/docs/scanner-imports/github-code-scanning.md
new file mode 100644
index 000000000..dff873e76
--- /dev/null
+++ b/docs/scanner-imports/github-code-scanning.md
@@ -0,0 +1,47 @@
+# Import GitHub code scanning findings
+
+Import code scanning alerts from one repository and Git ref. The collector
+saves each alert with the instance that GitHub returned for the selected ref.
+
+## Quick start
+
+Sign in with `gh auth login`. A fine-grained token needs **Code scanning alerts: read**.
+A classic token needs `security_events`, or `public_repo` for a public repository.
+[GitHub API permissions](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository)
+For GitHub Enterprise, set `GH_HOST` to the host you signed in to.
+
+From the destination checkout root, set `repo` to its GitHub repository. Set
+`source_key` to your existing code scanning key exactly, including case. For a
+first import, choose a key for the host, repository and finding family. Replace
+`/path/to/private/reports` with an existing private directory outside the checkout,
+then preview the default branch’s open alerts.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+repo=OWNER/REPO
+source_key=github.com/example/project/code-scanning
+out=$(mktemp -d "/path/to/private/reports/github.XXXXXX") &&
+ codex-security import github "$repo" --format json > "$out/alerts.json" &&
+ codex-security publish findings "$out/alerts.json" \
+ --to local --repository . --provider github \
+ --source-key "$source_key" --dry-run --format json
+```
+
+## Import and verify
+
+Check the ref and alert numbers in the preview. The alert repository must match
+a comparable local Git remote when available or the selected Cloud repository.
+Reuse the source key when you [save or publish and verify](README.md#save-or-publish-and-verify).
+
+## Reference
+
+- To select another ref, add `--github-ref refs/heads/BRANCH` to the collector.
+ Use `--github-state all` to include fixed and dismissed alerts, or repeat
+ `--github-alert NUMBER` to select exact alerts regardless of state.
+- Save the collector’s complete JSON array. Omit field or token filters and
+ `--full-output` when saving it for the reader.
+- The GitHub host, repository, alert number and ref identify a finding, so the
+ same alert on two refs retains separate evidence. Missing security severity
+ stays `unknown`.
+- See the [GitHub SDK examples](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud)
+ for programmatic collection and destination-specific normalization.
diff --git a/docs/scanner-imports/github-dependabot.md b/docs/scanner-imports/github-dependabot.md
index 1ba322738..14b40bb81 100644
--- a/docs/scanner-imports/github-dependabot.md
+++ b/docs/scanner-imports/github-dependabot.md
@@ -5,61 +5,30 @@ dependency occurrence in a manifest. Its advisory describes the vulnerability.
## Quick start
-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
-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"
-)
-```
-
-After the export succeeds, preview the saved file in the same shell.
+[Enable external imports](README.md#preview-a-report) and
+[export the repository alerts](#export-repository-alerts). From the matching
+checkout root, replace the file path, hostname, and repository in this preview.
-```bash
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-codex-security publish findings "$out/dependabot.jsonl" \
+```sh
+codex-security publish findings /private/path/dependabot.jsonl \
--to local --repository . --provider github \
--source-key github.com/OWNER/REPO/dependabot --dry-run --format json
```
-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.
+The alert repository must match a configured network remote when one is
+available. For a checkout with only filesystem remotes or no remote, verify
+the export belongs to it. [Save or publish and verify](README.md#save-or-publish-and-verify)
+using the same source key for later exports from this repository.
## Reference
-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.
+### Identity and evidence
+
+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
@@ -68,7 +37,33 @@ 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.
-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),
+To investigate a local alert, use the
+[`$resolve-dependency-alert` skill](../../plugins/codex-security/skills/resolve-dependency-alert/SKILL.md)
+with the saved alert and checkout. GitHub [code scanning](github-code-scanning.md)
+and [security advisories](github-security-advisories.md) have separate guides.
+
+### Export repository alerts
+
+Authenticate the GitHub CLI with a fine-grained token or GitHub App installation
+that has read access to Dependabot alerts for the repository. Replace `github.com`
+and `OWNER/REPO` with the alert host and repository.
+
+```bash
+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"
+)
+```
+
+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 saved file is `$out/dependabot.jsonl`. See 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/github-security-advisories.md b/docs/scanner-imports/github-security-advisories.md
new file mode 100644
index 000000000..7be536744
--- /dev/null
+++ b/docs/scanner-imports/github-security-advisories.md
@@ -0,0 +1,57 @@
+# Import GitHub Security Advisories
+
+Import repository disclosures or selected entries from GitHub's global advisory
+database. Use the affected packages and version ranges to investigate whether
+a dependency in your checkout is affected.
+
+## Quick start
+
+Sign in with `gh auth login`. For GitHub Enterprise, set `GH_HOST` to the host
+you signed in to. From the destination checkout root, set `repo` to its GitHub
+repository and `source_key` to your existing advisories key exactly, including
+case. For a first import, choose a key for the host, repository and finding
+family. Replace `/path/to/private/reports` with an existing private directory
+outside the checkout. Collect published advisories as a complete JSON array
+without field or token filters or `--full-output`, then preview the saved file.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+repo=OWNER/REPO
+source_key=github.com/example/project/security-advisories
+out=$(mktemp -d "/path/to/private/reports/github.XXXXXX") &&
+ codex-security import github-advisories "$repo" --format json > "$out/advisories.json" &&
+ codex-security publish findings "$out/advisories.json" \
+ --to local --repository . --provider github \
+ --source-key "$source_key" --dry-run --format json
+```
+
+## Import and verify
+
+Check the advisory IDs and source in the preview. For repository advisories, the
+source must match a comparable local Git remote when available or the selected
+Cloud repository. Use a source key separate from code scanning and Dependabot
+when you [save or publish and verify](README.md#save-or-publish-and-verify).
+
+## Reference
+
+- **Repository advisories.** Repeat `--github-advisory GHSA-xxxx-xxxx-xxxx` to select exact
+ IDs. To list an unpublished state instead, pass `--github-state draft`,
+ `triage`, or `closed`. Private advisories require repository advisory read
+ permission and access to the disclosures.
+- **Global advisories.** Add `--github-advisory-source global` and at least one
+ `--github-advisory GHSA-xxxx-xxxx-xxxx` to the collector. The repository argument selects
+ the context for investigation. A global record has no source repository.
+- An advisory retains the GHSA ID, reported packages and affected version
+ ranges. Check the installed versions in your repository separately. For
+ programmatic imports, see the [advisory SDK examples](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately).
+
+To collect a specific global advisory, use the same shell and replace the
+example ID. Preview `"$out/global-advisories.json"` with the same command and
+advisories source key. Each finding’s ID already distinguishes global and
+repository scope.
+
+```sh
+codex-security import github-advisories "$repo" \
+ --github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
+ --format json > "$out/global-advisories.json"
+```
diff --git a/docs/scanner-imports/inspector.md b/docs/scanner-imports/inspector.md
index 28eeff029..ba72afe16 100644
--- a/docs/scanner-imports/inspector.md
+++ b/docs/scanner-imports/inspector.md
@@ -5,33 +5,15 @@ repository. Findings from EC2, ECR, Lambda, and network resources are excluded.
## Quick start
-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
-umask 077
-out=$(mktemp -d)
-aws inspector2 list-findings --region us-east-1 --output json \
- --filter-criteria '{
- "awsAccountId":[{"comparison":"EQUALS","value":"ACCOUNT_ID"}],
- "resourceType":[{"comparison":"EQUALS","value":"CODE_REPOSITORY"}],
- "resourceId":[{"comparison":"EQUALS","value":"REPOSITORY_RESOURCE_ID"}]
- }' > "$out/inspector.json.tmp"
-mv "$out/inspector.json.tmp" "$out/inspector.json"
-```
-
-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`.
+[Enable external imports](README.md#preview-a-report) and
+[export the repository findings](#export-repository-findings). In your SCM
+integration, verify the Inspector project ARN and set `VERIFIED_PROJECT_ARN`
+to that value. From the matching checkout root, preview the file with the
+verified Git URL and your source key. Omit `--inspector-project-arn` when the
+findings already include the matching native Git URL.
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-codex-security publish findings "$out/inspector.json" \
+codex-security publish findings /private/path/inspector.json \
--to local --repository . --provider inspector \
--source-repository-url https://github.com/example/project \
--inspector-project-arn "$VERIFIED_PROJECT_ARN" \
@@ -41,21 +23,14 @@ codex-security publish findings "$out/inspector.json" \
## Import and verify
-Check the destination, ready findings, and exclusions. Remove `--dry-run` to
-import, then read the stored evidence.
-
-```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.
+Check the finding ARNs and repository in the preview, then
+[save or publish and verify](README.md#save-or-publish-and-verify). For a Cloud
+retry, supply the same verified ARN and Git URL used to prepare the submission.
## Reference
+### Identity and repository mapping
+
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.
@@ -65,13 +40,6 @@ 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.
-Start an export on the first page with AWS CLI automatic pagination enabled.
-Omit `--starting-token`, `--no-paginate`, `--max-items`, and `--query`. The
-importer rejects continuation tokens but cannot distinguish a final page
-saved on its own from a complete export. See the
-[AWS CLI export](https://docs.aws.amazon.com/cli/latest/reference/inspector2/list-findings.html)
-and [Inspector repository fields](https://docs.aws.amazon.com/inspector/v2/APIReference/API_CodeRepositoryDetails.html).
-
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
@@ -79,3 +47,30 @@ 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.
+
+### Export repository findings
+
+In Inspector coverage, find the account, Region, and full resource ID for the
+repository. Project names can match several integrations. With
+`inspector2:ListFindings` permission, replace the example Region, account ID, and
+repository resource ID in this export.
+
+```bash
+set -eu
+umask 077
+out=$(mktemp -d)
+aws inspector2 list-findings --region us-east-1 --output json \
+ --filter-criteria '{
+ "awsAccountId":[{"comparison":"EQUALS","value":"ACCOUNT_ID"}],
+ "resourceType":[{"comparison":"EQUALS","value":"CODE_REPOSITORY"}],
+ "resourceId":[{"comparison":"EQUALS","value":"REPOSITORY_RESOURCE_ID"}]
+ }' > "$out/inspector.json.tmp" &&
+ mv "$out/inspector.json.tmp" "$out/inspector.json"
+```
+
+Start an export on the first page with AWS CLI automatic pagination enabled.
+Omit `--starting-token`, `--no-paginate`, `--max-items`, and `--query`. The
+importer rejects continuation tokens but cannot distinguish a final page
+saved on its own from a complete export. See the
+[AWS CLI export](https://docs.aws.amazon.com/cli/latest/reference/inspector2/list-findings.html)
+and [Inspector repository fields](https://docs.aws.amazon.com/inspector/v2/APIReference/API_CodeRepositoryDetails.html).
diff --git a/docs/scanner-imports/opengrep.md b/docs/scanner-imports/opengrep.md
index e6cb9199c..ec5978c30 100644
--- a/docs/scanner-imports/opengrep.md
+++ b/docs/scanner-imports/opengrep.md
@@ -1,103 +1,78 @@
# Import OpenGrep findings
-Import native OpenGrep JSON into the local workbench or Cloud. The reader
-accepts plain or gzipped reports and preserves OpenGrep observations, including
+Import native OpenGrep JSON, plain or gzipped, to retain observations,
available traces and scan diagnostics.
## Quick start
-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.
+[Enable external imports](README.md#preview-a-report). From the scanned
+checkout root, preview the saved JSON using its credential-free HTTP(S) repository
+URL and an OpenGrep-specific source key. To get a new report,
+[run OpenGrep locally](#diagnostics-and-coverage).
-```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.
+For an existing report, set its path in the same shell.
```sh
-report=
-report_dir=$(mktemp -d) &&
- opengrep scan --config /path/to/rules.yaml --json --output "$report_dir/opengrep.json" . &&
- report="$report_dir/opengrep.json"
+opengrep_report=../reports/opengrep.json
```
-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)
-
-After a successful scan, or with an existing report, preview the selected file locally.
+Preview the selected report.
```sh
-codex-security publish findings "$report" --to local --repository . \
- --provider opengrep --source-repository-url "$repo_url" \
- --source-key "$source_key" --dry-run --format json
+codex-security publish findings "$opengrep_report" --to local --repository . \
+ --provider opengrep --source-repository-url https://github.com/example/project \
+ --source-key opengrep/example/project/main --dry-run --format json
```
## 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 findings imported . --format json
-```
-
-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
-```
+Check the findings, exclusions and `report.errors`, including when the
+findings list is empty. Keep `--provider opengrep` for
+[local import or Cloud publication](README.md#save-or-publish-and-verify).
+Both destinations store `semgrep` as the provider and record OpenGrep in
+`details.scanner_origin`.
## Reference
### 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.
+Use a distinct OpenGrep source key for the organization, project and branch.
+The rule, path and range identify an occurrence. Moving a match or changing
+its Windows path spelling can create a new record.
-Multiple traces at one occurrence are grouped. 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)
+Multiple traces at one occurrence are grouped. Evidence retains the rule
+level, snippets, ignored state and fingerprints when supplied. Severity is
+`unknown` because OpenGrep levels such as `ERROR` describe rule matches.
+If individually valid traces together exceed the Cloud 256 KiB limit, the
+whole occurrence is excluded. [Imported evidence](schema-guide.md)
### Diagnostics and coverage
-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.
+To create a report, run OpenGrep with your rules from the repository root
+and save native JSON outside the checkout. Add `--verbose` for skipped-target
+details. Preview the file after the scan succeeds.
+[OpenGrep output options](https://github.com/opengrep/opengrep/blob/main/src/osemgrep/cli_scan/Scan_CLI.ml)
+
+```sh
+opengrep_report=
+report_dir=$(mktemp -d) &&
+ opengrep scan --config /path/to/rules.yaml --json --output "$report_dir/opengrep.json" . &&
+ opengrep_report="$report_dir/opengrep.json"
+```
-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)
+The reader accepts native JSON only. A report can contain matches alongside
+parse errors or timeouts. Check the scanner's exit status and retain the
+original JSON for run-wide details. The preview includes run metadata in
+`report`. Stored findings keep the version, raw observations in
+`source_data.results` and the diagnostic count in `source_data.scan_error_count`.
+Cloud needs at least one supported finding.
### 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)
+Use the local record's `id` with `listLocalExternalFindings({ repository, id })`.
+On a `CodexSecurity` instance, pass `record.evidence` to
+`security.validate({ repositoryPath, finding: record.evidence })` using the
+checkout for the scanned revision. This sends evidence to your configured
+model provider and returns a separate assessment. The stored import remains
+`not_assessed`. [SDK validation example](../../sdk/typescript/README.md#validate-an-existing-finding)
and [host-provided validation](../../sdk/typescript/docs/validate-records.md)
diff --git a/docs/scanner-imports/schema-guide.md b/docs/scanner-imports/schema-guide.md
index 6378ea25a..44d00991a 100644
--- a/docs/scanner-imports/schema-guide.md
+++ b/docs/scanner-imports/schema-guide.md
@@ -16,22 +16,22 @@ 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 CLI or CI reports](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. |
-| [Semgrep Platform SAST](semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk) | Deployment, project ID, SAST product, full Git ref and native finding ID. The same occurrence keeps its identity when its file moves. |
+| 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](wiz.md) | 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](github-code-scanning.md) | Host, repository, alert family and alert number. Code scanning also includes the selected ref. Two alerts citing one GHSA remain separate. |
+| [GitHub advisories](github-security-advisories.md) | 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 CLI or CI reports](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. |
+| [Semgrep Platform SAST](semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk) | Deployment, project ID, SAST product, full Git ref and native finding ID. The same occurrence keeps its identity when its file moves. |
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.
+remove details from the stored snapshot. If one export contains colliding IDs,
+inspect the reader’s exclusions or input error before retrying.
## Read the right field
diff --git a/docs/scanner-imports/semgrep.md b/docs/scanner-imports/semgrep.md
index a9b82f73b..56093a801 100644
--- a/docs/scanner-imports/semgrep.md
+++ b/docs/scanner-imports/semgrep.md
@@ -1,154 +1,163 @@
# Import Semgrep Code findings
-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.
-To import selected existing findings from the Platform API, use the
-[SDK example](#import-selected-semgrep-platform-sast-findings-with-the-sdk).
+Import native Code CLI or CI JSON to retain severities and available snippets.
+Self-contained Semgrep SARIF 2.1.0 is also supported. Either format can be gzipped.
+For selected findings from the Semgrep Platform API, use the
+[local SDK example](#import-selected-semgrep-platform-sast-findings-with-the-sdk).
## Quick start
-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.
+[Enable external imports](README.md#preview-a-report). From the scanned checkout root,
+preview a saved SAST report using the repository's credential-free HTTP(S) URL
+and a stable key for the organization, project and branch. If you need a report,
+[capture one with Semgrep](#ci-artifacts).
-```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.
+For an existing report, set its path in the same shell.
```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"
+semgrep_report=../reports/semgrep.json
```
-After a successful scan, or with an existing report, preview the selected file locally.
+Preview the selected report.
```sh
-codex-security publish findings "$report" --to local --repository . \
- --provider semgrep --source-repository-url "$repo_url" \
- --source-key "$source_key" --dry-run --format json
+codex-security publish findings "$semgrep_report" --to local --repository . \
+ --provider semgrep --source-repository-url https://github.com/example/project \
+ --source-key example/project/main --dry-run --format json
```
## 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.
-
-```sh
-codex-security findings imported . --format json
-```
-
-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 "$report" --to cloud --repository "$repo_url" \
- --provider semgrep --source-repository-url "$repo_url" \
- --source-key "$source_key" --dry-run --format json
-```
+Check the declared source URL against the checkout's Git remote. With an empty
+or wholly excluded report, the preview alone does not establish a repository match.
+[Save or publish and verify](README.md#save-or-publish-and-verify) using the
+same source URL and key. Cloud uses the `semgrep` provider.
## 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)
+Use a saved artifact from a Code-only `semgrep ci` job. Policy and baseline
+determine which matches it contains. Exit 1 can indicate blocking findings
+even when the report is valid. Check the job's product selection and exit status.
+
+To create a local report, run Semgrep from the repository root with your
+SAST rules. Write to a private directory outside the checkout. After a
+successful scan, use that file in the preview above. [Semgrep CLI reference](https://docs.semgrep.dev/cli-reference)
+
+```sh
+semgrep_report=
+report_dir=$(mktemp -d) &&
+ semgrep scan --config /path/to/sast-rules.yaml --json-output "$report_dir/semgrep.json" . &&
+ semgrep_report="$report_dir/semgrep.json"
+```
### Evidence and identity
-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.
+Native JSON retains the result, rule, CWE IDs, range, snippets and ignored
+state when supplied. SARIF retains the selected rule and result, including
+traces and fixes. SARIF `error` imports as high even if the original severity
+was critical. Check Cloud exclusions for deeply nested traces.
[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.
+The match ID uses JSON `extra.fingerprint` or SARIF `matchBasedId/v1`.
+Reimporting the same fingerprint under the same source key and repository
+updates its location. If the fingerprint is absent or says `requires login`,
+the ID uses rule, literal path and range. Moving the match then creates a new
+record. [Imported evidence and identity](schema-guide.md)
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.
+excluded, but SARIF can omit the product metadata. Scan errors or unsuccessful
+SARIF invocations stop import. Direct artifact URIs and native `%SRCROOT%`
+paths can supply locations. Indexed artifacts or unresolved bases remain in
+raw evidence and require a fingerprint for identity. Use the original report
+for run-wide inventories and timing.
+
+SDK callers pass `sourceRepositoryUrl` to the native or SARIF normalizer.
+When using `prepareNormalizedLocalImport` directly, pass the original SARIF
+repository references in the third argument's `sourceRepositories`. Use
+`{ url, platform: "github" }` for a verified custom GitHub host.
### Import selected Semgrep Platform SAST findings with the SDK
-Request `issue_type=sast` and keep the project lookup and findings pages as original
-[Semgrep Web API](https://docs.semgrep.dev/semgrep-appsec-platform/semgrep-api) response text. Pass each page separately. When a page contributes a selected ID, the
-SDK checks its rows for conflicting product evidence. If a page contains only fields
-shared by several products, its product depends on the original request filter.
-[Guardian for Codex](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex) and
-[Semgrep MCP](https://github.com/semgrep/semgrep/blob/fe209763a4a2ccfcdf6434e6c332edc24a2f586e/cli/src/semgrep/mcp/server.py) return different records.
-Pass a fully qualified ref, such as `refs/heads/topic` or `refs/tags/topic`, exactly as it appears in the findings.
-Supply the HTTP(S) repository URL you independently associate with the target checkout.
-The native `project.url` and any selected `finding.repository.url` must match this spelling. Legacy findings can
-omit the project ID. An exact URL then identifies the repository even if the
-display name has changed. If multiple Semgrep projects share that URL, select
-the IDs from the intended project: the URL alone can also match a sibling project
-on the same ref. A conflicting project ID is always rejected. A finding without a
-URL must carry the matching project ID and a name equal to the namespace-qualified,
-decoded path in the operator-supplied URL.
-The local importer checks the checkout using its existing repository rules.
-
-```ts
+Request `issue_type=sast` and save the original project lookup and findings
+pages as response text. Pass each findings page separately. The SDK checks
+every row on pages that contain a selected ID for conflicting product evidence.
+When a page contains only fields shared by several products, the original
+request filter identifies the product. Guardian and MCP return different
+records. [Semgrep Web API](https://docs.semgrep.dev/semgrep-appsec-platform/semgrep-api),
+[Guardian for Codex](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex),
+[Semgrep MCP](https://github.com/semgrep/semgrep/blob/fe209763a4a2ccfcdf6434e6c332edc24a2f586e/cli/src/semgrep/mcp/server.py)
+
+Use the full ref from the findings, such as `refs/heads/main` or
+`refs/tags/v1`. Supply the credential-free HTTP(S) repository URL you verified
+for the checkout. The native `project.url` and any selected
+`finding.repository.url` must match it exactly.
+
+- An exact finding URL is sufficient when `repository.id` is absent, even if
+ the display names differ. If several projects share the URL and ref, choose
+ the finding IDs from the intended project.
+- Any `repository.id` supplied must match `project.id`. When the finding has
+ no URL, it must include both the matching project ID and a `repository.name`
+ equal to the decoded, namespace-qualified path in the supplied URL, such as
+ `example/project`.
+
+[Enable external imports](README.md#preview-a-report). In a Node.js project
+you control outside the scanned checkout, install `@openai/codex-security`
+and save this script as `preview-semgrep.mjs`. Set the deployment, ref,
+repository URL, source key and finding IDs for your selection. Pass the IDs as
+positive decimal strings without leading zeros to preserve 64-bit IDs.
+
+```js
+import { readFile } from "node:fs/promises";
+import {
+ normalizeSelectedSemgrepPlatformFindings,
+ prepareNormalizedLocalImport,
+} from "@openai/codex-security";
+
+const [checkout, projectFile, ...findingsFiles] = process.argv.slice(2);
+const sourceRepositoryUrl = "https://github.com/example/project";
const selected = normalizeSelectedSemgrepPlatformFindings({
- deployment,
- ref,
+ deployment: "example",
+ ref: "refs/heads/main",
sourceRepositoryUrl,
- projectResponse,
- findingsResponses,
- findingIds,
+ projectResponse: await readFile(projectFile, "utf8"),
+ findingsResponses: await Promise.all(
+ findingsFiles.map((file) => readFile(file, "utf8")),
+ ),
+ findingIds: ["123"],
});
const prepared = await prepareNormalizedLocalImport(
selected,
- { provider: "semgrep", sourceKey, repository: checkout },
+ {
+ provider: "semgrep",
+ sourceKey: "example/project/platform/main",
+ repository: checkout,
+ },
{ sourceRepositories: [{ url: sourceRepositoryUrl }] },
);
-if (prepared.preview.excluded.length) {
- console.error(prepared.preview.excluded);
-} else {
- await prepared.import();
-}
+console.log(JSON.stringify(prepared.preview, null, 2));
```
-Keep the same source key on replay. Finding identity includes the deployment, project ID,
-SAST product, full ref, and native finding ID. Pass selected finding IDs as positive
-decimal strings without leading zeros. Semgrep emits 64-bit finding IDs. The adapter
-also accepts larger positive integer IDs in saved responses without rounding. The
-stored evidence includes the selected finding and the project's ID, name and URL.
-A record without a native rule name or message is excluded during preview.
+Run the script from your SDK project. Pass the checkout, project response and
+each saved findings page as absolute paths.
+
+```sh
+node preview-semgrep.mjs /path/to/checkout /path/to/reports/semgrep-project.json \
+ /path/to/reports/semgrep-findings-1.json
+```
-Changes to key order or equivalent numeric spellings such as `2` and `2.0` leave
-the stored record unchanged. Only repository-relative files become locations. Names
-with URI-like prefixes and directory-only paths remain in the native evidence.
+Review the repository, findings and exclusions. To save the selection, append
+`await prepared.import()` to a copy of the script in your SDK project and run
+that copy with the same inputs.
+[Read back the local records](README.md#save-or-publish-and-verify) using the
+checkout path from the preview.
+Keep the same source key on replay. Each occurrence is identified by deployment,
+project ID, SAST product, full ref and native finding ID.
+
+The stored evidence includes the selected finding and the project's ID, name
+and URL. Larger positive integer IDs are retained without rounding. Equivalent
+numeric spellings (`2` and `2.0`) and key order do not change the stored record.
+Preview excludes findings that lack both a native rule name and a message.
+Only repository-relative files become locations. URI-like and directory-only
+paths stay in the native evidence.
diff --git a/docs/scanner-imports/snyk.md b/docs/scanner-imports/snyk.md
index 2a387c026..fb2994e3b 100644
--- a/docs/scanner-imports/snyk.md
+++ b/docs/scanner-imports/snyk.md
@@ -1,126 +1,105 @@
# Import Snyk Open Source findings
-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.
+Import 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.
## Quick start
-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.
+[Enable external imports](README.md#preview-a-report). For a first local import,
+set the destination from the checkout root. Choose a key for the repository,
+branch, original scan target and format. If you ran Snyk in `services/api`,
+replace `root` in the example key with `services/api`.
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-report=../reports/snyk-open-source.json
-source_key=github.com/example/project/main/root/native-sca
+snyk_repository=$(pwd -P)
+snyk_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)
+For a repeat import, set `snyk_repository` and `snyk_source_key` to the
+previous local preview's exact `repository` and `source.source_key`. Keep the
+original destination even if it was a package subdirectory. Changing either
+value creates a separate set of records.
+
+Set `snyk_report` to the absolute path of your saved, ungrouped Open Source
+JSON report so it still resolves if you change directories.
```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
+snyk_report=/path/to/reports/snyk-open-source.json
```
-Preview the selected report locally.
+If you need a new report, [run the Snyk CLI](#native-cli-json) and keep the
+`snyk_report` it sets. Preview the selected report.
```sh
-codex-security publish findings "$report" --to local --repository . \
- --provider snyk --source-key "$source_key" --dry-run --format json
+codex-security publish findings "$snyk_report" --to local --repository "$snyk_repository" \
+ --provider snyk --source-key "$snyk_source_key" \
+ --dry-run --format json
```
## 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.
+Review coverage and exclusions, especially unsupported products and license
+records. Check the destination checkout when the report lacks a Git URL.
+[Save or publish and verify](README.md#save-or-publish-and-verify) with the
+same source key for subsequent exports in this format.
-```sh
-codex-security findings imported . --format json
-```
+## Reference
+
+### Native CLI JSON
-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)
+To create a report, run the authenticated Snyk CLI with the project's package
+tooling. For a project with `package.json`, run this from its root. Exit 1
+means findings. A higher exit code stops acquisition. [Snyk CLI test](https://docs.snyk.io/developer-tools/snyk-cli/commands/test)
```sh
-codex-security publish findings "$report" --to cloud \
- --repository https://github.com/example/project --provider snyk \
- --source-key "$source_key" --dry-run --format json
+snyk_report=
+report_dir=$(mktemp -d) || exit "$?"
+snyk_status=0
+snyk test --file=package.json --json-file-output="$report_dir/snyk-open-source.json" || snyk_status=$?
+if [ "$snyk_status" -gt 1 ]; then
+ exit "$snyk_status"
+fi
+snyk_report="$report_dir/snyk-open-source.json"
```
-## Reference
-
-### Native CLI JSON
-
-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)
+For several projects under one scan root, use `--all-projects --fail-fast`
+in place of `--file=package.json`. Without `--fail-fast`, Snyk can omit
+projects it could not scan. Project errors present in the input stop import.
+Keep independent scan roots in separate reports with separate keys.
A native occurrence is identified by package manager, manifest, advisory,
-package name and version, and dependency path. The reader retains the 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)
+package name and version, and dependency path. The reader retains the
+vulnerability, project context and suggested fixes. Manifest paths are
+target-relative. [Native result fields](https://github.com/snyk/cli/blob/main/src/lib/snyk-test/legacy.ts)
### Snyk plugin export
-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
-codex plugin marketplace add snyk/studio-recipes
-codex plugin add snyk@snyk-studio-recipes
-```
-
-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)
+From the repository's Git root, ask the Snyk plugin's `snyk-findings-export`
+skill to run an SCA-only scan and save the bundle outside the checkout.
+Use the bundle as input and a key ending in `plugin-sca`. The bundle retains
+collection context, ignored status and each selected MCP record. The mapper
+can shorten descriptions and omit alternate dependency paths. Paths are
+target-relative. A dirty workspace does not establish the scanned commit.
+[Install the Snyk plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
and [SCA mapper](https://github.com/snyk/studio-mcp/blob/main/internal/oss/map.go)
### SARIF compatibility
-For 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)
+For SARIF, replace `--json-file-output` with `--sarif-file-output` and keep the
+exit-code check above. Use a key ending in `sarif-sca`. SARIF groups an
+advisory's occurrences and exposes one package coordinate. The reader
+retains the rule, result and report context. Use a self-contained report. Manifest paths are
+optional. If present, use direct URIs. Indexed or base-relative manifest
+locations are unsupported. [Snyk Open Source SARIF formatter](https://github.com/snyk/cli/blob/main/src/lib/formatters/open-source-sarif-output.ts)
### Identities and provenance
-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.
+Native JSON, plugin bundles and SARIF produce different source IDs. Give
+each format a separate key. Changes in collection context such as a plugin
+scan's `issueCount` can update a stored snapshot even if the occurrence
+stays the same. [Imported evidence and identity](schema-guide.md)
+
+Known source Git URLs must match a comparable configured local remote when
+one is available, or the selected Cloud repository. Snyk Code, Container,
+IaC, SBOM results and hosted backlog responses use other formats.
diff --git a/docs/scanner-imports/sonar.md b/docs/scanner-imports/sonar.md
index ed5411596..702ddffa8 100644
--- a/docs/scanner-imports/sonar.md
+++ b/docs/scanner-imports/sonar.md
@@ -1,88 +1,87 @@
# Import SonarQube Cloud findings
-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.
+Collect security issues for one project and branch or pull request. The
+collector uses the authenticated Sonar CLI and saves the selection in a
+capture you can import locally or publish to Cloud.
## Quick start
-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.
+[Enable external imports](README.md#preview-a-report). From the matching
+checkout, sign in to the project's Sonar organization with browse access
+(`sonar auth login`). Preview a selection using project and issue keys from
+Sonar's Issues view or the SonarQube plugin for Codex.
+[Sonar CLI authentication](https://docs.sonarsource.com/sonarqube-cli/quickstart-guide#step-2-authenticate)
```sh
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
codex-security import sonar --sonar-project example_project --sonar-branch main \
--sonar-issue ISSUE_A --sonar-issue ISSUE_B --dry-run --format json
```
-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)
+A selection by key includes the requested security issues regardless of
+status. Omit `--sonar-issue` to preview open and confirmed security issues
+for the selected ref. For a pull request, replace `--sonar-branch main` with
+`--sonar-pull-request 42`. Omit both to use the project's main branch.
## 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.
+Review the repository, ref, issues and exclusions in the `import sonar`
+preview. Confirm using the private `capture` path it returned.
```sh
codex-security import sonar "/path/from/local-preview.json" --yes
-codex-security findings imported "/checkout/from/preview" --format json
```
-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.
+To import locally **and** publish to Cloud, start from the same checkout.
+Replay needs no Sonar login. Use a separate file-backed ChatGPT login with
+access to the connected Cloud repository and an authorized environment on a
+deployment that accepts the `sonar` provider. Review the Cloud account,
+repository and environment, then confirm with the **new Cloud capture**.
```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
```
-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)
+Read back the local records in the preview's `repository` and check the Cloud
+verification result if you published. Preview again if the checkout, state
+directory or destination changes. To resume an interrupted upload, reuse the
+approved capture and destination. [Readback and verification](README.md#save-or-publish-and-verify)
## Reference
### Project and repository selection
-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/)
+Omit `--sonar-project` only when the checkout's Git origin maps to exactly
+one project in the active organization. For monorepos, supply the project
+key. When a search exceeds 10,000 results, select issue keys.
+[SonarQube plugin](https://www.sonarsource.com/blog/now-available-sonarqube-plugin-for-codex/)
and [Codex Security import workflow](../../plugins/codex-security/skills/publish-findings/SKILL.md#sonarqube-cloud-issues)
If Sonar lacks a repository binding, the checkout uses an SSH host alias or
Cloud preview finds no usable remote, verify the project's Git URL in Sonar.
-Pass it as `--source-repository-url` when previewing the capture. When the
-checkout has comparable remotes, at least one must match. A changed fetch
-URL needs a new preview.
+Pass it as `--source-repository-url` when previewing the capture. At least
+one comparable remote must match if the checkout has any. A changed fetch
+URL requires a new preview.
Each Sonar issue key identifies one record within its source and repository.
-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.
+Reimport updates its evidence, including file ranges and available data flows.
+In a monorepo, repository-relative locations require a verified Sonar project
+base directory.
### Use a native JSON export
-For a saved `GET /api/issues/search` response, 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.
+For a saved `GET /api/issues/search` response, use a single page if it
+contains the complete result. Otherwise supply an array of all pages in
+order for the same project and ref. Pages can omit repository and ref context.
+Run the example from the checkout root and supply its verified repository URL.
+The example source key is for a new stream.
+
+To update issues from an earlier capture, use its preview's `repository` path
+for `--repository` and its exact `sourceKey` (`sonar:<hash>`) for `--source-key`.
+The local `publish findings` preview shows `source.source_key`, and each stored
+record has a `sourceKey`. Updating a matching issue replaces its evidence.
+Native pages can omit the issue URL and repository-relative locations. Replay
+the capture to preserve those fields, or use another key to store both versions.
```sh
codex-security publish findings ../reports/sonar-pages.json --provider sonar \
@@ -90,5 +89,5 @@ codex-security publish findings ../reports/sonar-pages.json --provider sonar \
--source-key sonarcloud.io/example/example_project/branch/main --dry-run --format json
```
-Review the preview, rerun without `--dry-run`, confirm and use
-`codex-security findings imported . --format json` to verify the local import.
+[Save and verify the native file](README.md#save-or-publish-and-verify) with the
+same `publish findings` command.
diff --git a/docs/scanner-imports/veracode.md b/docs/scanner-imports/veracode.md
index 40022fd5e..f70b68a16 100644
--- a/docs/scanner-imports/veracode.md
+++ b/docs/scanner-imports/veracode.md
@@ -1,19 +1,16 @@
# Import Veracode Static Analysis findings
-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.
+Import Findings API policy flaws from one Veracode application that maps to
+one source repository. Use the application context and `scan_type=STATIC`.
## Quick start
-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.
+[Enable external imports](README.md#preview-a-report) and
+[export the complete Findings API pages](#export-findings-api-pages) with read
+access to the application and Results API. From the matching checkout root,
+preview the file with its verified Git URL and a source key for this application.
```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 \
@@ -23,23 +20,10 @@ codex-security publish findings /private/path/policy-findings.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).
+Verify the application represents the destination repository. An application
+GUID or a backlog aggregated from several repositories cannot establish the
+mapping. [Save or publish and verify](README.md#save-or-publish-and-verify)
+using the same source key for repeat exports from this application and context.
## Reference
@@ -80,15 +64,16 @@ page=0
while :; do
http --ignore-stdin --check-status --body --timeout 20 --auth-type veracode_hmac GET \
"$api/appsec/v2/applications/$guid/findings" \
- scan_type==STATIC page=="$page" size==100 > "$out/page.tmp"
+ scan_type==STATIC page=="$page" size==100 > "$out/page.tmp" || exit "$?"
pages=$(jq -er --arg app "$application" --argjson n "$page" '
select(._links.application.href == $app and .page.number == $n) |
- .page.total_pages | numbers' "$out/page.tmp")
- cat "$out/page.tmp" >> "$out/pages.stream"
+ .page.total_pages | numbers' "$out/page.tmp") || exit "$?"
+ cat "$out/page.tmp" >> "$out/pages.stream" || exit "$?"
page=$((page + 1))
[ "$page" -lt "$pages" ] || break
done
-jq -s '.' "$out/pages.stream" > "$out/policy-findings.json"
+jq -s '.' "$out/pages.stream" > "$out/report.tmp" &&
+ mv "$out/report.tmp" "$out/policy-findings.json"
```
Keep each page intact. Apply any Findings API filters when downloading the
diff --git a/docs/scanner-imports/wiz.md b/docs/scanner-imports/wiz.md
new file mode 100644
index 000000000..54a786ca9
--- /dev/null
+++ b/docs/scanner-imports/wiz.md
@@ -0,0 +1,49 @@
+# Import Wiz findings
+
+Import saved Wiz package vulnerabilities, SAST findings, repository secrets or
+IaC findings. The file reader accepts native JSON, normalized JSONL and detailed
+repository package vulnerability CSV, including gzip-compressed files.
+
+## Quick start
+
+For a package vulnerability export, select the repository in Wiz **Vulnerability
+Findings**, choose **Save as → Report**, then select **Repository Branch**,
+**JSON** and **Detailed** columns. Download the completed report outside the
+checkout. From the destination checkout root, set the path and replace `TENANT_ID`
+with your stable Wiz tenant identifier.
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+report=../reports/wiz-packages.json
+codex-security publish findings "$report" \
+ --to local --repository . --provider wiz \
+ --source-key TENANT_ID/vulnerability-finding --dry-run --format json
+```
+
+## Import and verify
+
+Check that the preview covers the intended assets or builds and review excluded
+records. Reuse the source key for the same tenant and finding family across
+exports and project filters. [Save or publish and verify](README.md#save-or-publish-and-verify).
+
+## Reference
+
+- **Native JSON.** Package vulnerabilities accept individual records or
+ `data.vulnerabilityFindings.nodes`. SAST, repository secrets and IaC require
+ the named `data.sastFindings.nodes`, `data.secretInstances.nodes` or
+ `data.iacFindings.nodes` collection.
+- **Paginated API or MCP results.** Check every finding and inventory page for
+ GraphQL `errors`, even when the page contains nodes. If any page reports an
+ error, resolve it and collect a complete selection before combining pages.
+ Put the selected nodes under the original collection name in one JSON object. If
+ findings use inventory to identify their repository, finish the inventory
+ pages too and combine their nodes under `data.versionControlResources.nodes`
+ in the same object. Retain the final page info for each collection. An array
+ or JSONL stream of GraphQL page envelopes cannot be imported.
+- **CSV.** Use **Detailed** repository package vulnerability columns. The reader
+ requires a GitHub repository-branch URL and preserves each original cell.
+ Other finding families require native JSON or an explicit normalized mapping.
+- Package findings retain the Wiz occurrence ID. SAST, repository secrets and
+ IaC use `sast:`, `secret:` and `iac:` ID prefixes. See the
+ [Wiz format reference](../../plugins/codex-security/skills/publish-findings/references/wiz-import.md#finding-formats)
+ for required fields, repository mapping and normalized JSONL.
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 0261db320..c35d53f87 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -687,8 +687,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.
-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).
+For CLI examples and supported input formats, see the
+[scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
The SDK's `prepareLocalExternalImport(file, options)` returns a `preview` and a
separate `import()` operation. `prepareNormalizedLocalImport(findings,
@@ -698,9 +698,9 @@ remain unassessed source evidence, separate from native scan findings. Repeated
imports update the same repository/provider/source-key/source-ID record; omitted
records remain stored, and unknown evidence fields are not inferred.
-File imports forward repository references from the reader automatically. Direct
-normalized callers should provide additional known references in the third
-argument's `sourceRepositories` when they are absent from
+File imports forward repository references from the reader automatically. With
+`prepareNormalizedLocalImport()`, supply additional known references in the
+third argument's `sourceRepositories` when they are absent from
`evidence.details.repository.url`. For a known GitHub custom host, include
`platform: "github"`, for example `{ sourceRepositories: [{ url:
"https://git.example.test/example/project", platform: "github" }] }`. Named Wiz
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 247152a7a..511db291b 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1283,210 +1283,143 @@ Supply the validation prompt again when rerunning.
## Import vendor findings locally
-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:
-
-```bash
-export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
-```
-
-In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
-Only `1` enables the feature. Without it, `publish findings`, `findings imported`,
-`import sonar`, and `import github-advisories` are absent from command help and schemas and cannot
-run. The SDK's external publication, local import/readback, and advisory
-acquisition APIs require the same flag in their effective environment. An explicit
-`dependencies.environment` is used instead of the process environment. Pure
-normalizers and file readers remain available as library utilities.
-
-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`.
-
-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 \
- --to local --repository ./project --provider wiz \
- --source-key TENANT_ID/vulnerability-finding --dry-run --format json
-```
-
-Review the normalized evidence, repository, source namespace, and exclusions.
-Run the same command without `--dry-run` to confirm interactively, or add `--yes`
-after reviewing the preview. `--to` is required; there is no default destination.
-Local import uses the workbench SQLite database and requires no Cloud login,
-network connection, or model call. `--dry-run` does not write findings.
-
-Read the saved evidence with:
-
-```bash
-codex-security findings imported ./project --format json
-```
-
-The repository argument defaults to the current directory. Local imports are
-separate from the assessed findings shown by `findings list`: they remain
-`not_assessed`, retain the original vendor evidence, and do not create a completed
-scan or automatically validate or patch findings. Missing revisions, locations,
-and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
-Git remotes, the URL must match one of those remotes; the importer does not
-substitute the checkout's current commit for an unknown scanner revision.
-
-Repeated imports update the same record by repository, provider, source key, and
-source finding ID. The result reports created, updated, and unchanged counts.
-Keep the source key stable across exports. Records omitted from a later selection
-remain stored; omission does not resolve or delete a finding. Excluded records
-are reported, and an import with exclusions exits with status 1. Both destinations
-read the same vendor formats; Cloud's field, size and nesting limits do not apply
-to local file imports.
-
-`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.
+Choose an input in the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
+Each guide shows how to preview its input for a local repository. Follow the [shared procedure](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
+to confirm the import and read the resulting records.
+
+Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` to enable `publish findings`,
+`findings imported`, `import sonar`, and `import github-advisories`. Only `1`
+enables these commands in help and schemas. The SDK's corresponding operations
+require the flag in their effective environment. Pure normalizers, file readers,
+and the existing `import github` alert collector remain available independently.
+Disabling the flag retains saved records.
+
+For `publish findings`, `--to` is required. With `--to local`, `--repository`
+takes a checkout path. The reader detects the file format, and `--format json`
+selects the output format. A local preview writes no findings and needs no Cloud
+login, network connection, or model call.
+
+Local readback uses `findings imported [PATH]`. The path defaults to the current
+directory. Each imported record starts as `not_assessed`. Unknown revisions and
+locations stay unknown. Repository-scoped sources are checked against comparable
+configured Git remotes as described in the provider guide. Reimporting the same
+source key and finding ID reports created, updated, or unchanged records.
+Records omitted from the new selection stay stored. An import with exclusions
+exits with status 1. Local imports can retain evidence that exceeds Cloud's per-finding limits.
+
+For completed scans exported in the Codex Security JSON or CSV format, use
+[scan import](#import-findings-as-a-saved-scan).
## Import Endor Labs findings
-Use `--provider endor` for Findings from one project and context. Export complete
-native JSON with `endorctl` and preview it against the corresponding repository.
-
-```sh
-codex-security publish findings endor-findings.json --to local \
- --provider endor --repository ./project \
- --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
-```
-
-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).
+Use `--provider endor` for one Endor project and context. The
+[Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
+SARIF compatibility, and the local preview.
## Publish findings to Cloud
-### Import Snyk Open Source findings
-
-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.
+Use the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) to prepare a supported input
+and follow the [shared publication steps](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
+to preview and confirm it. The following settings and result fields apply to
+scanner publication across providers.
+
+### Preview and publish
+
+With `--to cloud`, `--repository` accepts a connected GitHub or GitHub Enterprise
+repository URL or Cloud repository ID. A unique URL and its ID resolve to the
+same destination and saved submission. Use the ID if several connectors share
+the URL. Use a file-backed ChatGPT login for the selected Cloud
+account. If you use your regular Codex login, set `cli_auth_credentials_store = "file"`
+in Codex `config.toml` and sign in again. API-key-only and keyring-only logins
+cannot publish. The destination needs an authorized environment. It can receive
+scanner findings before its first native scan.
+
+Cloud preview reads current source versions and lists the account, endpoint,
+repository, and environments. Existing source records keep their environment.
+New records use the repository's current authorized default. The terminal
+summarizes severities, shows up to five finding IDs and titles, and identifies
+the evidence file and exclusions. Inspect the full preview with `--dry-run --format json`.
+The interactive confirmation defaults to No and identifies skipped records.
+Without a terminal, uploading requires `--yes`.
+
+### Configure an alternate Cloud deployment
+
+Set `CODEX_SECURITY_CLOUD_BASE_URL` to the deployment's API root, such as
+`https://cloud.example.test/backend-api/aardvark`. Use a login issued by that
+deployment. Remote API roots require HTTPS. Loopback development also accepts
+HTTP on `localhost`, `127.0.0.0/8`, or `::1`. An empty or invalid setting
+stops preparation before authentication or network requests. Leaving it unset
+selects production. For testing, use an isolated `CODEX_SECURITY_STATE_DIR`.
+
+For a separately hosted Cloud UI, set `CODEX_SECURITY_CLOUD_WEB_URL` to the
+full app URL. The preview and result can then supply a repository-specific
+`cloudUrl`. With a custom API and no web URL, the CLI prints navigation
+instructions. API requests always use the API root. The older
+`CODEX_SECURITY_CLOUD_PUBLISH_URL` setting applies only to native scan publishing.
+
+### Resume interrupted imports
+
+The publisher saves request IDs and bodies privately in the configured state
+directory before uploading batches of up to 100 findings within Cloud payload
+limits. After a lost response, use the same input, destination, account, API
+endpoint, and state directory to resume. Deployments have separate checkpoints
+even if their account and repository IDs match. Check `cloudApiUrl` for the API
+endpoint and `savedSubmission` for the checkpoint. A repository reset retires
+the old request and requires a fresh preview and approval.
+[Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
+
+### Results and exit codes
+
+| Status | Exit code | Meaning |
+| ------------- | --------- | ----------------------------------------------------------------------- |
+| `complete` | 0 | All selected records were acknowledged and read back. |
+| `partial` | 1 | Some records were excluded locally or rejected by Cloud. |
+| `interrupted` | 2 | Upload, verification, or receipt persistence stopped after preparation. |
+| `failed` | 2 | Preparation failed before upload. |
+
+With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
+Failed and interrupted imports set `ok` to `false` and `error.code` to
+`IMPORT_FAILED`. Available results, receipts, and counts remain under `data`.
+Other formats reject `--full-output` before reading the file or contacting
+Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
+
+`verified` and `unacknowledged` are counts. Each receipt item identifies a
+request item by `client_id`. Each entry in `failures` identifies the vendor
+record by `source_finding_id`. A lost response can leave accepted records
+unacknowledged. Review `error` before retrying, and check `excluded` for local
+input errors. Counts include previously acknowledged batches in the same
+saved submission.
+
+Progress goes to stderr and JSON results to stdout. Lookups and readback use up
+to four concurrent requests. Uploads are sequential. Saved receipts and
+readback verify source-record identity and evidence. Codex assessment and
+visibility in the shared Cloud Findings view are separate. `cloudUrl`, when
+available, links to the destination repository in Cloud.
-```sh
-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
-```
+### Import Snyk Open Source findings
-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).
+Use `--provider snyk` for Open Source SCA vulnerabilities. Native CLI JSON, plugin
+exports, and Open Source SARIF can produce different occurrence IDs. Use a
+separate source key for each format. See the [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for
+collection and preview commands.
### Import Wiz findings
-Import selected Wiz package vulnerabilities, SAST findings, repository secrets,
-and IaC findings without creating a scan. Imported records retain vendor evidence
-and remain **not assessed by Codex**, including when Wiz marks them resolved or
-reports an AI verdict. Workload secrets, cloud configuration findings, and external
-network findings are not supported by this repository importer. Cloud destinations
-currently support connected GitHub and GitHub Enterprise repositories, including
-custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
+The [Wiz guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md) shows how to preview saved package vulnerabilities,
+SAST findings, repository secrets, or IaC findings. The format reference below
+describes the fields to preserve when preparing those exports.
#### Select findings and a destination
-Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
-connection to acquire findings and save the supported native JSON. A configured
-plugin may provide that connection; an official Codex plugin is not a prerequisite.
-The publisher reads the saved records. It does not fetch from Wiz or require a
-manual website download. The acquisition path still needs validation against
-actual responses from an authorized Wiz tenant; local parser checks do not
-establish that qualification.
-
-Inspect the connection's actual response before importing it. MCP summaries,
-Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
-this finding mapper. Keep the original occurrence IDs and evidence; use the
-named collections below when the response contains repository findings.
-
-Before the first import:
-
-1. Select an existing repository in Codex Security Cloud and copy its URL or
- Cloud repository ID. The repository needs an
- authorized environment, but does not need a completed native scan.
-2. Read the selected records through the authorized connection and save their
- JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
- `vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
- package, image, and source metadata. For SAST, repository secrets, and IaC,
- retain the named API collections and repository metadata described below.
- Complete the selected pages before importing; a summary or unfinished page
- is not a complete finding selection.
-3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
- for that Wiz tenant and finding class across exports. Do not create a new key
- for each project filter or import; that creates different source identities.
-4. Check the ChatGPT account used by your existing file-backed Codex Security
- login. API-key-only and keyring-only logins are not supported for Cloud
- publication. See the credential-storage instructions below.
-
-Prefer the supported native JSON. Existing package-vulnerability CSV reports are
-accepted as a compatibility input. **CSV support covers repository package
-vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
-Wiz code-to-cloud coverage.** The named JSON readers described below handle their
-respective finding families separately.
-
-When a UI report is needed, retain the repository and finding filters in Wiz
-**Vulnerability Findings**, choose **Save as → Report**, select **Repository
-Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
-report. CSV must use the columns described below and a comma delimiter. Plain and
-gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
-filename extension. **Raw Event** on Code & Build Scans contains scan metadata
-rather than findings.
-
-#### Configure an alternate Cloud deployment
-
-For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
-API root before previewing or uploading, for example
-`https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
-HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
-`::1`). Use a login issued by that deployment and an isolated
-`CODEX_SECURITY_STATE_DIR` for testing. The endpoint
-does not change your login or sign you into another deployment. An invalid or
-empty configured URL stops the import before authentication or network requests.
-With the variable unset, the existing production endpoint remains the default.
-The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
-publication endpoint; it does not route vendor imports.
-
-If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
-to the full Cloud app URL shown in the browser. The import handoff supplies both
-deployment settings. The preview and result include a repository-specific
-`cloudUrl`, and terminal completion prints the link. This setting only controls
-the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
-For custom API destinations without a configured app URL, completion retains
-the manual navigation guidance rather than guessing a UI host or port.
-
-#### Preview and publish
-
-Preview the selection and destination:
+Acquire selected findings through an authorized Wiz connection and save the
+complete native response. The publisher reads the saved file. MCP summaries,
+Wiz Issues, and local Wiz CLI scan results may have different shapes. Verify
+the selected response against the format for its finding family. Acquisition
+against a live Wiz tenant requires separate qualification.
-```bash
-codex-security publish findings selected-wiz.json \
- --to cloud --repository https://github.com/example/project --provider wiz \
- --source-key TENANT_ID/vulnerability-finding --dry-run --format json
-```
-
-`--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
-destination and resume the same saved submission. This command reads the
-authorized destination and current source versions during
-preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
-repository needs an existing environment; no native scan is required. Review the
-Cloud API endpoint, account, repository, environments, findings, and exclusions,
-then rerun without
-`--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
-reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
-occurs. Existing source findings keep their Cloud environment; new findings use
-the repository’s current authorized default. Preview shows the environments that
-will receive the selected findings. The terminal preview summarizes severities,
-shows up to five finding IDs and titles, and identifies the evidence file and
-exclusions. `--dry-run --format json` retains all normalized findings and complete
-evidence for inspection. A prompt explicitly includes any records that will be
-skipped.
+For saved reports, use the detailed repository package vulnerability export
+shown in the Wiz guide. Raw Event on Code & Build Scans contains scan
+metadata. For other CSV exports, see [Convert CSV reports](#convert-csv-reports).
#### Package vulnerability inputs
@@ -1498,6 +1431,10 @@ A response that advertises another page is rejected. Complete the requested page
or save only the explicitly selected records; retain the named collection for
SAST, repository secrets, and IaC.
+For native package records, include `id`, `name`, `detailedName`,
+`vulnerableAsset.id`, and `vendorSeverity` or `severity`. Retain any available
+package, image, and repository metadata.
+
The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
`CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
this profile; other Wiz report types use different fields.
@@ -1646,56 +1583,6 @@ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
integer range is rejected; export those values as strings to preserve them
exactly. Invalid records appear in `excluded` with their source ID and reason.
-#### Resume interrupted imports
-
-Requests contain at most 100 findings and respect the Cloud payload limits.
-Before uploading, the publisher saves request IDs and bodies privately under
-the configured Codex Security state directory. After an uncertain response,
-repeat the same command with unchanged input and Cloud API endpoint to resume those
-requests. Different deployments have separate saved submissions, including when
-their account and repository IDs match. The preview and result include
-`cloudApiUrl` so scripts can verify which API received the findings; this is an
-API endpoint, not a link to the Cloud UI. A reset
-retires the old request without republishing; review and explicitly approve a
-fresh invocation.
-
-#### Results and exit codes
-
-Results distinguish completion from partial or interrupted work:
-
-| Status | Exit code | Meaning |
-| ------------- | --------- | -------------------------------------------------------------------------------------------------- |
-| `complete` | 0 | All selected records were acknowledged and their source records read back. |
-| `partial` | 1 | The import finished, but some records were excluded locally or rejected by Cloud. |
-| `interrupted` | 2 | Upload, verification, or receipt persistence stopped; acknowledged work is included in the result. |
-| `failed` | 2 | Preparation failed before uploading; structured output includes the error. |
-
-For finding imports, `--full-output` requires `--format json` or `--format jsonl`.
-Failed and interrupted imports set the envelope's `ok` to `false`, with
-`error.code: "IMPORT_FAILED"`, while retaining available results, receipts, and
-counts under `data`. Other full-output format combinations are rejected before
-reading the input or contacting Cloud; omit `--full-output` to use those formats.
-
-Ctrl-C and SIGTERM retain exit codes 130 and 143. Interrupted JSON output preserves
-`receipts`, `counts`, `failures` with vendor source IDs, `excluded`, `verified`, and
-`unacknowledged`. A lost response can mean unacknowledged findings were accepted;
-resume the saved submission rather than treating them as never uploaded. When
-available, `savedSubmission` identifies the checkpoint to resume by repeating the
-same command. Review `error` before retrying; a repository reset retires the old
-submission and requires fresh approval. Correct local exclusions or final source
-conflicts before preparing a new submission.
-
-Counts are cumulative for the saved submission: a resumed result includes
-batches acknowledged by earlier invocations, not just the latest upload attempt.
-
-Terminal progress reports preparation, acknowledged uploads, and verification
-on stderr; JSON results stay on stdout. Lookups and readback use at most four
-concurrent requests, while uploads remain sequential. Successful receipts are
-saved locally. Verification reads the imported source records and checks their
-identities and evidence against the receipts. This does not establish a Codex
-assessment or visibility in the shared Cloud Findings view.
-When available, `cloudUrl` links to the destination repository in Cloud.
-
### Publish completed scans
Preview selected completed scans before uploading:
@@ -2350,102 +2237,29 @@ installation fails. The installer respects `core.hooksPath`.
## Import SonarQube Cloud issues
-Enable [external imports](#import-vendor-findings-locally) and run
-`codex-security import sonar` from the project's checkout to import open
-security issues from the active Sonar CLI connection. For issues selected in
-the SonarQube plugin, pass each issue key with `--sonar-issue`, its project
-with `--sonar-project`, and its branch or PR with `--sonar-branch` or
-`--sonar-pull-request`. The plugin and terminal use the same Sonar login.
-When you omit `--sonar-project`, Sonar must bind the checkout's Git origin to
-one project in that login's organization.
-
-```sh
-codex-security import sonar --sonar-project example_project --sonar-branch main \
- --sonar-issue ISSUE_A --sonar-issue ISSUE_B --dry-run --format json
-codex-security import sonar "/path/from/capture.json" --yes
-```
-
-`--dry-run` saves the reviewed selection and returns its path in `capture`.
-The default destination is the local workbench. For both local import and
-Cloud publication, preview with `--to cloud` and confirm with the exact
-`capture` path from the successful Cloud preview and `--to cloud --yes`.
-If the checkout or Cloud destination changes, preview again. For a structured
-success or error envelope, use `--full-output` with `--format json` or
-`--format jsonl`. You can publish a local import later
-without reconnecting to Sonar. See [Sonar import and replay](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md)
-for authentication, repository mapping, and native JSON input.
+The [SonarQube Cloud guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md) covers live collection, repository
+binding, saved issue-search pages, and replay. Unlike a saved-file
+`publish findings` preview, `import sonar --dry-run` writes a private capture
+and returns its path. Confirm with the capture from the preview for the intended
+destination. A Cloud confirmation imports the selected issues locally and
+publishes them to Cloud. Use `--full-output` with `--format json` or
+`--format jsonl` for a structured success or error envelope.
## Import GitHub findings locally or to Cloud
-Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
-The existing alert collector remains available without it.
-
-Acquire code-scanning findings with the existing `import github` collector and
-save its complete JSON output. In Codex, the official
-[GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
-can help select the repository, alert numbers and ref through GitHub's MCP
-server. Pass that selection to the collector. For Dependabot, use a token with
-**Dependabot alerts: read** and follow
-the [repository alert export guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md)
-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).
-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
-```
+Choose the [code scanning](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
+[Dependabot](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md), or
+[GitHub Security Advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md) guide to acquire
+and preview findings. All three use `--provider github`. Keep a separate source
+key for each family. Saving locally or publishing to Cloud requires the
+[external-import opt-in](#import-vendor-findings-locally).
-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
-```
-
-Or preview publication to a connected Cloud repository:
-
-```bash
-codex-security publish findings /path/outside/repository/alerts.json \
- --to cloud --provider github --repository https://github.com/example/project \
- --source-key github.com/example/project/code-scanning --dry-run --format json
-```
-
-The importer fetches every page, retrieves alert details, and retains the selected
-ref's instance. It writes the saved input for publication; no website download or
-hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
-selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
-the default branch. MCP list calls are paginated separately. Code-scanning
-imports require the saved collector output, which includes the selected instance.
-
-The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
-the plugin's connection does not sign in `gh`. Reading code-scanning alerts requires
-[code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
-**Code scanning alerts: read** for a fine-grained token, or `security_events` for
-a classic token (`public_repo` is sufficient for public repositories). The source
-repository must have code scanning available. For Cloud publication, the
-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 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.
-Cloud authentication, batching, saved receipts, partial results and
-interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
-JSON, JSONL and gzip are supported. Save complete import output without field or
-token filters or `--full-output`.
-
-Use a stable source key for the GitHub host, repository and finding family.
-Code-scanning identities include the selected ref, so branches retain separate
-evidence. The original alert, rule, scanner, location, revision and source state
-remain attached. An alert-wide dismissal takes precedence over the selected
-instance's open/fixed state. Missing security severity stays `unknown`;
-SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
-remains unassessed by Codex.
+The code-scanning collector uses the GitHub CLI login and `GH_HOST`. A GitHub
+plugin connection can select alerts but does not sign the CLI in.
+Collection retains the selected ref's instance. Branches keep separate
+evidence. An alert-wide dismissal takes precedence over the selected instance's
+open or fixed state. Missing security severity stays `unknown`. See
+[code-scanning access requirements](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository).
The SDK offers the same preview and publication boundary for Cloud:
@@ -2480,69 +2294,20 @@ to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings(
### Import GHSA advisories separately
-Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
-
-**Importing a GHSA advisory does not establish an installed dependency or
-applicability to the destination repository.** Repository advisories are
-disclosures maintained by a repository; global advisories describe affected
-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
-codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
-```
-
-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
-```
-
-For local storage, use the same advisory file, provider and source key with
-`--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
-to review, confirm and read the stored evidence.
-
-`--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
-to select exact IDs from that API, regardless of advisory state. Repository
-lists default to `--github-state published`; `draft`, `triage`, and `closed`
-require explicit selection. A nondefault state cannot be combined with exact
-IDs. Global selection requires at least one ID and never lists the advisory
-database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
-the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
-[repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
-require **Repository security advisories: read**, or the classic `repo` or
-`repository_advisories:read` scope, plus access to the advisory. Public records
-need no additional advisory permission.
-
-Review the saved evidence before local import or Cloud publication, including any
-selected private advisories. Acquisition failure returns no partial selection.
-Both destinations report invalid records as exclusions. Cloud publication retains
-acknowledged receipts if a later batch or readback fails.
-
-Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
-patched versions, source status and original JSON. It does not infer an installed
-version or source location. Global advisories omit a source repository; the
-explicit local or Cloud destination binds the import for investigation. Repository
-advisories retain their source repository and check it against the Cloud target
-or configured local Git remotes when available. Withdrawal remains vendor
-state, and all imported evidence remains not assessed by Codex. Use a separate
-source key from code-scanning alerts; shared advisory IDs do not combine source
-records from different providers.
+See the [GitHub Security Advisories guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md)
+to save repository advisories or selected global database records and preview
+them for the chosen destination. Advisories report affected ranges and
+available fixes. Verify installed dependencies and applicability in the
+destination repository separately.
+
+Repository lists default to published advisories. When selecting exact IDs, omit
+`--github-state`. Selecting a repository advisory by its GHSA ID can return a
+draft if you have access.
+Global collection requires one or more explicit IDs.
+Acquisition failure yields no partial selection. Access to private or
+unpublished repository advisories requires the repository advisory read
+permission and access to the record. See
+[GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
In the SDK, collect the advisories with `importGitHubAdvisories()`. For Cloud,
pass `normalizeGitHubAdvisories(advisories, "cloud")` to
@@ -2551,6 +2316,7 @@ pass `normalizeGitHubAdvisories(advisories, "cloud")` to
`importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
`{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
records. Both forms require `repository: "OWNER/REPO"` as source or target context.
+Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
## Import alerts from the CLI