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