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