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
feat(imports): collect Semgrep findings through Guardian and the Web API (#2167)
Michael D'Angelo6548b1c993c1
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.mdindex d71be20ba..b751600bd 100644--- a/docs/scanner-imports/README.md+++ b/docs/scanner-imports/README.md@@ -22,7 +22,7 @@ guide. Otherwise, ask for a supported report. A fresh scan produces new results.| [GitHub Dependabot](github-dependabot.md) | Dependency alerts exported from one repository || [GitHub Security Advisories](github-security-advisories.md) | Selected repository or global advisories || [OpenGrep](opengrep.md) | Native scan JSON, optionally gzip-compressed |-| [Semgrep Code](semgrep.md) | CLI/CI JSON, self-contained SARIF, or selected Platform API pages (local SDK) |+| [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 || [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 |diff --git a/docs/scanner-imports/schema-guide.md b/docs/scanner-imports/schema-guide.mdindex 625373a9f..5ddf4de99 100644--- a/docs/scanner-imports/schema-guide.md+++ b/docs/scanner-imports/schema-guide.md@@ -33,7 +33,8 @@ changes.| [Snyk Open Source](snyk.md) | Native CLI JSON distinguishes manifest, package manager, advisory, package name and version, and dependency path. Plugin and SARIF reports use different identities. || [Black Duck SCA](blackduck.md), [Veracode Static Analysis](veracode.md) | Black Duck combines project version, component version, origin and advisory identity. Veracode scopes a native issue ID to its API origin, application and context. || [Semgrep CLI or CI reports](semgrep.md), [OpenGrep](opengrep.md) | Semgrep prefers a fingerprint and falls back to rule, path and range. OpenGrep groups traces by rule, path and range. Both store provider `semgrep`. Use a separate OpenGrep source key. |-| [Semgrep Platform SAST](semgrep.md#existing-platform-findings) | Deployment, project ID, SAST product, full Git ref and native finding ID. The same occurrence keeps its identity when its file moves. |+| [Semgrep Guardian selections](semgrep.md#import-selected-guardian-findings) | Deployment, repository name, Guardian tool, full ref and exact string ID. Guardian records stay separate from Web API occurrences. |+| [Semgrep Platform findings](semgrep.md#existing-platform-findings) | Deployment, project ID, product, full Git ref and native finding ID. Web API SAST selections and full SAST collections share IDs. |Repeat local imports replace changed evidence for the same identity. Identicalevidence is unchanged, and records omitted from a later report remain stored.diff --git a/docs/scanner-imports/semgrep.md b/docs/scanner-imports/semgrep.mdindex 6d1c87fb8..174e76878 100644--- a/docs/scanner-imports/semgrep.md+++ b/docs/scanner-imports/semgrep.md@@ -1,4 +1,4 @@-# Import Semgrep Code findings+# Import Semgrep findingsImport 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.@@ -7,7 +7,8 @@ For selected findings from the Semgrep Platform API, use the## Quick start-For local import of selected existing Code findings, see [Existing Platform findings](#existing-platform-findings).+In Codex, [import selected Guardian findings](#import-selected-guardian-findings) with your existing Semgrep sign-in.+For a whole project and ref, use the [Web API collector](#collect-a-platform-project-and-branch).[Enable external imports](README.md#preview-a-report). From the scanned checkout root,preview a saved SAST report using the repository's credential-free HTTP(S) URL@@ -35,11 +36,69 @@ or wholly excluded report, the preview alone does not establish a repository mat[Save or publish and verify](README.md#save-or-publish-and-verify) using thesame source URL and key. Cloud uses the `semgrep` provider.+## Import selected Guardian findings++Enable [external imports](README.md#preview-a-report) and sign in to+[Semgrep Guardian for Codex](https://docs.semgrep.dev/semgrep-guardian/quickstart).+Ask Codex to import the selected Code or Supply Chain findings from Guardian+into the local workbench. Specify the deployment, repository and full Git ref.+Guardian handles authentication through its existing connection.++Codex calls `get_semgrep_sast_findings` or `get_semgrep_supply_chain_findings`+with that scope. If you already selected rows from that tool, Codex can reuse+the successful response. It saves the exact string IDs and original selected+rows from `structuredContent.findings`. Guardian returns only the repository+name, so confirm its SCM URL against the checkout before saving the capture.+A missing or ambiguous selected ID stops the import. Guardian defaults to 20+open or reviewing results and returns at most 1,000 per call.++For SDK callers, `guardianClient` below is your connected Guardian MCP client.+Pass the filters used for your selection, including states for any closed or+ignored findings. Save the capture in a private directory outside the checkout.++```js+import { writeFile } from "node:fs/promises";+import { collectSelectedSemgrepGuardianFindings } from "@openai/codex-security";++const capture = await collectSelectedSemgrepGuardianFindings(+ {+ request: {+ name: "get_semgrep_sast_findings",+ arguments: {+ deployment_name: "example",+ repository_name: "example/project",+ ref: "refs/heads/topic",+ },+ },+ findingIds: ["123"],+ sourceRepositoryUrl: "https://github.com/example/project",+ },+ { callTool: (request) => guardianClient.callTool(request) },+);+await writeFile("guardian.json", JSON.stringify(capture), {+ flag: "wx",+ mode: 0o600,+});+```++Preview before confirming the import. Use the same file and source key on replay.++```sh+codex-security publish findings /path/to/private/guardian.json --provider semgrep \+ --to local --repository /path/to/project --source-key example/project/topic --dry-run --format json+```++Guardian records retain the original MCP fields. The summary omits end lines,+CWEs, package versions and fix versions. Guardian and Web API records keep+separate identities even when their IDs look identical. To verify a pair,+identify the same occurrence independently by deployment, mapped project,+product, full ref, rule and location. Then compare the complete ID strings,+preserving every digit.+## Existing Platform findings-Use the SDK to select exact IDs from **Semgrep Code (SAST)**. The official-[Guardian Codex plugin](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex)-can help identify them. For import, save the native+Use the SDK to select exact Web API IDs from **Semgrep Code (SAST)** when you+have original Web API responses. For this format, save the native[project response](https://docs.semgrep.dev/api-reference/v1/projectsservice/get-project-details)and the [Findings API pages](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings)for that deployment, project ID and fully qualified Git ref (for example,@@ -120,6 +179,91 @@ When passing normalized findings to the SDK, keep each generated Semgrepcaller-managed identity, use an opaque ID of your own. The generated Semgrep IDrequires the original scoped evidence on every import.+In a marked Platform export or selection, a partial legacy v1 object in+`source_data.finding` must retain its original collection scope when it+contains a repository ID, URL or name, a `ref` value (including `null`), or a+recognized `product` or `issue_type` (`sast`, `code`, `sca`, or `ai_sast`).+A non-null `found_dependency` or `vulnerability_identifier` also identifies+a Supply Chain finding, even when the row omits its product.+Keep the deployment, project, ref and product alongside the native finding,+including when you change its storage ID. For rows with canonical+`source_data.semgrepPlatformFindingJson`, the SDK checks that serialized+native finding. If unrelated SDK metadata uses the same v1 fields, move it to+another key such as `source_data.ticket`, or submit those rows in an ordinary+normalized batch without the Platform report marker or scope.++## Collect a Platform project and branch++With a Web API token in `SEMGREP_APP_TOKEN`, collect all findings returned for a+project, exact ref and product. The collector looks up the project ID, requests+every page with server-side deduplication disabled, and stops on a failed or+overlapping page. Offset pagination does not provide a point-in-time snapshot.+For a multi-page result the collector also checks whether the first page's+membership has changed. Retry the collection if it reports a change.++A finding that identifies its repository only by name can use the project name,+the Git URL path, or the final path component of either. For any other name,+at least one finding in the collection must pair that name with the project's+repository ID or a matching repository URL. That finding can appear on any+page. Collection fails if the name has no such match. When one finding proves another+finding’s alias, the importer saves the verified label and resolved project ID in+`source_data.repositoryWitnessJson` on the name-only finding. The proving finding+retains its original repository fields in `source_data.semgrepPlatformFindingJson`.++SDK callers can pass a verified GitHub Enterprise repository as+`sourceRepositories: [{ url, platform: "github" }]` to+`collectSemgrepPlatformFindings` and the local reader. The reference must match+the selected project. It allows equivalent GitHub path casing, `.git` suffixes+and supported SSH URLs on that host.++Run the following commands from a trusted working directory outside the project+checkout. Each collection gets a new owner-only file. A failed collection+leaves earlier exports available for replay.++```sh+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1+report=$(mktemp ./semgrep-backlog.XXXXXX) &&+ codex-security import semgrep example/project --semgrep-deployment example \+ --semgrep-ref refs/heads/topic --semgrep-product sast --format json > "$report" &&+ codex-security publish findings "$report" --to local --repository /path/to/project \+ --provider semgrep --source-key example/project/topic --dry-run --format json+```++Use `--semgrep-product sca` for Supply Chain or `ai_sast` for AI-powered+detection. The default is `sast`. Use `--source-repository-url` on collection+when the project has no repository URL. In that case the report records the mapping in+`sourceRepositoryUrl`, and stored finding evidence retains a null native project URL.+For SSH projects, the report keeps the original address in `nativeProjectUrl` alongside the resolved HTTP(S) address in `project.url`, and records any supplied mapping separately.+Save the complete output from a successful+command; the local importer checks the recorded finding count and repository/ref+claims. It retains each original finding as JSON text so large IDs survive replay. The reader also accepts saved v1 project exports with native object rows and decimal type witnesses.++To import a collected backlog with the TypeScript SDK, pass the normalized+report to the local importer. Reuse the source key when replaying the report.+You may filter the normalized findings array and retain the original read count.+Only submitted findings are imported.++```ts+const findings = normalizeSemgrepPlatformFindings(report);+const prepared = await prepareNormalizedLocalImport(findings, {+ provider: "semgrep",+ sourceKey: "example/project/topic",+ repository: checkout,+});+await prepared.import();+```++Supply Chain findings include native package versions, matching fix recommendations+and advisory IDs when Semgrep supplies them. With the same source key, importing identical Code findings that qualify for individual+selection reports them as unchanged when switching between a selection and a full collection.+See the [Semgrep Findings API](https://docs.semgrep.dev/api-reference/v1/findingsservice/list-code-supply-chain-or-ai-powered-detection-findings).++If you previously imported a v1 export with the development version that stored+each finding as an object, the first replay updates the existing SQLite record+to store the native finding as JSON text. Its local ID and source finding ID stay+the same, and its version increases once. Replaying the same evidence again+reports it as unchanged.+## Reference### CI artifacts@@ -153,7 +297,7 @@ 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 newrecord. [Imported evidence and identity](schema-guide.md)-Use SAST-only rules. Identifiable Supply Chain and Secrets results are+For CLI/CI JSON and SARIF, use SAST-only rules. Identifiable Supply Chain and Secrets results areexcluded, but SARIF can omit the product metadata. Scan errors or unsuccessfulSARIF invocations stop import. Direct artifact URIs and native `%SRCROOT%`paths can supply locations. Indexed artifacts or unresolved bases remain in@@ -173,14 +317,10 @@ every row on pages that contain a selected ID for conflicting product evidence.When a page contains only fields shared by several products, the originalrequest filter identifies the product.-To find existing Code findings in Codex, sign in to Guardian and ask for the-deployment, project and full ref you want to inspect. Guardian returns a-selection for review. For this SDK import, confirm the candidate findings in-the original Web API results and use the IDs from those records. The SDK also-accepts saved responses from an authorized operator. Fetching new responses-directly requires Web API read access.-[Guardian sign-in](https://docs.semgrep.dev/semgrep-guardian/quickstart) ·-[Query existing findings](https://semgrep.dev/products/product-updates/query-your-semgrep-findings-by-asking-guardian/) ·+Use the IDs from the original Web API results for this SDK import. The SDK+accepts saved responses from an authorized operator. Fetching new Web API+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` ordiff --git a/plugins/codex-security/skills/publish-findings/SKILL.md b/plugins/codex-security/skills/publish-findings/SKILL.mdindex bc0462051..5317520b2 100644--- a/plugins/codex-security/skills/publish-findings/SKILL.md+++ b/plugins/codex-security/skills/publish-findings/SKILL.md@@ -86,11 +86,15 @@ Retain package versions, reported fixed versions, provenance and original eviden## Semgrep Code-Prefer native Code/SAST CLI or CI JSON for this reader; use self-contained SARIF 2.1.0 as a compatibility path. JSON retains the original severity better than SARIF. The reader does not accept Platform API, Guardian or MCP response envelopes, or a general Supply Chain or Secrets feed. Select SAST rules or Code-only CI output; identifiable non-SAST records are excluded, but SARIF may omit the product metadata needed to distinguish Secrets.+Prefer native Code/SAST CLI or CI JSON for this reader; use self-contained SARIF 2.1.0 as a compatibility path. JSON retains the original severity better than SARIF. Use the selected Guardian workflow below for existing Code or Supply Chain findings. Select SAST rules or Code-only CI output; identifiable non-SAST records are excluded, but SARIF may omit the product metadata needed to distinguish Secrets.For a user-requested new scan, use the installed Semgrep CLI from the source repository root with the selected SAST rules: `semgrep scan --config /path/to/sast-rules.yaml --json-output /path/to/semgrep.json .`. Existing CI jobs can produce the same artifact using `--json-output`; authenticated `semgrep ci --code` follows the job's policy and baseline scope. Explain that this generates fresh scan findings, and do not substitute it for a request to retrieve existing Platform findings.-For selected Semgrep Platform SAST findings, follow the [local SDK example](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk). It takes the original Web API project response, SAST findings pages and selected IDs. The [Semgrep Guardian Codex plugin](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex) can help select and inspect findings. Guardian and the `semgrep_findings` MCP tool return different records from the SDK inputs. For CLI import, [save and preview the selected findings locally](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings) with the same source key on replay.+For a selection of existing Code or Supply Chain findings in Codex, use the signed-in [Semgrep Guardian plugin](https://docs.semgrep.dev/semgrep-guardian/quickstart). Call its `get_semgrep_sast_findings` or `get_semgrep_supply_chain_findings` tool with the selected `deployment_name`, `repository_name` and full `ref`. Preserve any state and severity filters used for that selection. Reuse an existing successful tool result when its scope is explicit. If a selected ID is missing, report it and check the query scope and filters with the user. A project-wide fetch is a separate request.++Save a private JSON capture outside the checkout with `format: "semgrep-guardian-selection/v1"`, the verified `sourceRepositoryUrl`, the MCP `request` (tool `name` and `arguments`), the exact selected string `findingIds`, and `structuredContent: { findings: [...] }` containing the original selected tool rows. Match IDs exactly and keep the tool's repository, ref and evidence. Guardian returns a repository name, so confirm its mapping to the selected checkout URL. Use the [Guardian preview command](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-guardian-findings) and confirm the selection locally. Guardian handles sign-in for this workflow. Guardian and Web API IDs remain separate even when the strings match.++For a whole project and ref, use the [Web API collector](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#collect-a-platform-project-and-branch) with its read-capable token. If the user supplies [saved Web API responses](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings), use the IDs from those records.Import the native report with `--provider semgrep`, a stable organization/project/branch `--source-key`, and `--source-repository-url` identifying the actual source repository. Use `--to local --repository /path/to/project` for local storage or `--to cloud --repository URL_OR_ID` for Cloud. The source URL is checked against configured local Git remotes or the Cloud destination. Preview with `--dry-run --format json` before confirming the import.diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 7936c61af..630fb8beb 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -703,9 +703,12 @@ with a saved list or detail response, or `normalizeContinuumFindings(input, sourwith parsed JSON. Verify the repository for the selected findings before passing its Git URL.[Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)+Use `collectSelectedSemgrepGuardianFindings` with a connected Guardian MCP client to+[capture selected Code or Supply Chain findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-guardian-findings) using the user's Guardian sign-in.Use `normalizeSelectedSemgrepPlatformFindings` for selected SAST findings from savedSemgrep Web API responses. See the [Semgrep SDK example](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk).Use `selectSemgrepPlatformFindings` to [save a selection for the local CLI](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings).+Use `collectSemgrepPlatformFindings` to [collect one project at an explicit ref](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#collect-a-platform-project-and-branch) for a single product (default `sast`).This does not affect scan publishing or the existing GitHub alert collector.The SDK also exposes `prepareExternalPublication(file, options)` for supporteddiff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 8c36bd3df..b7015ffdb 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -1340,7 +1340,7 @@ Each guide shows how to preview its input for a local repository. Follow the [shto confirm the import and read the resulting records.Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` to enable `publish findings`,-`findings imported`, `import sonar`, and `import github-advisories`. Only `1`+`findings imported`, `import sonar`, `import semgrep`, and `import github-advisories`. Only `1`enables these commands in help and schemas. The SDK's corresponding operationsrequire the flag in their effective environment. Pure normalizers, file readers,and the existing `import github` alert collector remain available independently.@@ -1359,7 +1359,12 @@ source key and finding ID reports created, updated, or unchanged records.Records omitted from the new selection stay stored. An import with exclusionsexits with status 1. Local imports can retain evidence that exceeds Cloud's per-finding limits.-Use `--provider semgrep` for a [saved Semgrep Platform selection](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings).+Use `publish findings FILE --provider semgrep --to local` for a+[selected Guardian MCP capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-guardian-findings)+or a [saved Semgrep Web API selection](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings).+Guardian uses its existing sign-in. Its imported IDs are separate from Web API IDs.+To [collect a full Semgrep project and branch](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#collect-a-platform-project-and-branch), use+`import semgrep PROJECT --semgrep-deployment SLUG --semgrep-ref REF [--semgrep-product sast|sca|ai_sast]`.For completed scans exported in the Codex Security JSON or CSV format, use[scan import](#import-findings-as-a-saved-scan).diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjsindex 49ff0fdf1..120b25654 100644--- a/sdk/typescript/scripts/package-dist-files.mjs+++ b/sdk/typescript/scripts/package-dist-files.mjs@@ -35,9 +35,14 @@ const distModules = ["snyk-findings","scanner-repository-url","semgrep-findings",+ "semgrep-guardian-findings","semgrep-platform-findings","hosted-git-remotes","hosted-git-repository",+ "semgrep-platform-collector",+ "hosted-scanner-http",+ "hosted-scanner-v1",+ "semgrep-platform-v1","sonar-findings","sonar-collector","sonar-import",diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 8b027b31d..40628c955 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -232,6 +232,12 @@ import {GITHUB_ADVISORY_STATES,importGitHubAdvisories,} from "./github-advisories.js";+import type { HostedScannerHttpOptions } from "./hosted-scanner-http.js";+import { semgrepPlatformFormat } from "./semgrep-platform-findings.js";+import {+ collectSemgrepPlatformFindings,+ SEMGREP_PLATFORM_PRODUCTS,+} from "./semgrep-platform-collector.js";import {GITHUB_ALERT_STATES,importGitHubCodeScanningAlerts,@@ -327,6 +333,7 @@ import {type PolicyPrompt,type PolicySecurity,} from "./security-policy-cli.js";+import { formatSecurityPolicyText as escapeTerminalText } from "./security-policy.js";import type { PatchSelection } from "./patch-tui.js";import {scanPhaseLabel as scanPhase,@@ -1340,6 +1347,7 @@ interface CliDependencies {linearClient?: LinearClientFactory;importGitHubAlerts?: typeof importGitHubCodeScanningAlerts;importGitHubAdvisories?: typeof importGitHubAdvisories;+ hostedScannerFetch?: HostedScannerHttpOptions["fetch"];importScan?: typeof importScan;readSavedFindings?: typeof readSavedFindings;runWorkbench(@@ -2120,6 +2128,7 @@ export async function main(let frameworkExit: number | undefined;const frameworkCapture = captureOutput();let rawExportOutput = false;+ let escapeSemgrepOutput = false;let batchedVerification = false;let deferredVerificationDiagnostic: string | undefined;let streamedLogs: Awaited<ReturnType<typeof readSavedScanLogs>> | undefined;@@ -3976,7 +3985,7 @@ export async function main(});const imports = Cli.create("import", {description: importsEnabled- ? "Import Sonar security issues or read GitHub security findings."+ ? "Import Sonar security issues or read hosted Semgrep and GitHub findings.": "Read GitHub code scanning alerts.",}).command("github", {description: "Read GitHub code scanning alerts without changing GitHub.",@@ -4058,7 +4067,48 @@ export async function main(}},});- function registerGitHubAdvisories() {+ function registerOptInCollectors() {+ async function collect<T>(+ provider: "GitHub advisory" | "Semgrep",+ fail: (error: {+ code: string;+ message: string;+ exitCode: number;+ }) => never,+ run: (signal: AbortSignal) => Promise<T>,+ ) {+ const controller = new AbortController();+ const removeSignals = listenForAbort(dependencies, controller);+ try {+ if (!importsEnabled)+ throw new CodexSecurityError(externalImportsDisabledMessage);+ return await run(controller.signal);+ } catch (error) {+ const interrupted = interruptedExitCode(controller.signal);+ exitCode = interrupted ?? 2;+ const message = diagnosticValue(error);+ const diagnostic = interrupted+ ? `${provider} import ${interrupted === 130 ? "canceled" : "terminated"}.`+ : message;+ errorOutput.write(+ `codex-security: ${provider === "Semgrep" ? escapeTerminalText(diagnostic) : diagnostic}\n`,+ );+ if (argv.includes("--full-output")) {+ structuredError = true;+ return fail({+ code:+ provider === "GitHub advisory"+ ? "GITHUB_IMPORT_FAILED"+ : "HOSTED_IMPORT_FAILED",+ message: provider === "Semgrep" ? errorMessage(error) : message,+ exitCode,+ });+ }+ return undefined;+ } finally {+ removeSignals();+ }+ }imports.command("github-advisories", {description: "Read GitHub security advisories without changing GitHub.",hint: "Defaults to published repository advisories. Use --github-advisory-source global with explicit --github-advisory IDs to select public database entries. Advisories do not establish an installed dependency or applicability to the selected repository.",@@ -4110,50 +4160,93 @@ export async function main(}),).optional(),- async run({ args, options, error: incurError }) {- const controller = new AbortController();- const removeSignals = listenForAbort(dependencies, controller);- try {- if (!importsEnabled)- throw new CodexSecurityError(externalImportsDisabledMessage);- return await (- dependencies.importGitHubAdvisories ?? importGitHubAdvisories- )(+ run: ({ args, options, error }) =>+ collect("GitHub advisory", error, (signal) =>+ (dependencies.importGitHubAdvisories ?? importGitHubAdvisories)({repository: args.repository,advisoryIds: options.githubAdvisory,source: options.githubAdvisorySource,state: options.githubState,- signal: controller.signal,+ signal,},{environment: dependencies.environment,currentDirectory: dependencies.currentDirectory(),},- );- } catch (error) {- const signal = controller.signal.reason;- if (signal === "SIGINT" || signal === "SIGTERM") {- exitCode = signal === "SIGINT" ? 130 : 143;- errorOutput.write(- `codex-security: GitHub advisory import ${signal === "SIGINT" ? "canceled" : "terminated"}.\n`,- );- } else {- exitCode = 2;- errorOutput.write(`codex-security: ${diagnosticValue(error)}\n`);- }- if (argv.includes("--full-output")) {- structuredError = true;- return incurError({- code: "GITHUB_IMPORT_FAILED",- message: diagnosticValue(error),- exitCode,- });- }- return undefined;- } finally {- removeSignals();- }+ ),+ ),+ });+ const http = {+ environment: dependencies.environment,+ fetch: dependencies.hostedScannerFetch,+ };+ const semgrepReport = z+ .object({+ format: z.literal(semgrepPlatformFormat),+ deployment: z.string(),+ nativeProjectUrl: z.string().optional(),+ sourceRepositoryUrl: z.string().optional(),+ project: z.object({+ id: z.string(),+ name: z.string(),+ url: z.string(),+ }),+ ref: z.string(),+ product: z.enum(SEMGREP_PLATFORM_PRODUCTS),+ repositoryAliases: z.array(z.string()),+ findingCount: z.number().int().nonnegative(),+ findings: z.array(+ z.string().describe("JSON text of a native Semgrep finding."),+ ),+ })+ .optional();+ imports.command("semgrep", {+ description:+ "Read a full Semgrep Platform project and ref through the Web API.",+ hint: "Requires SEMGREP_APP_TOKEN with Web API access. Import the saved --format json output or a selected Guardian MCP capture with publish findings --to local --provider semgrep.",+ destructive: false,+ mcp: false,+ args: z.object({+ project: z+ .string()+ .min(1)+ .describe("Exact Semgrep project name, typically owner/repository."),+ }),+ options: z.object({+ semgrepDeployment: optionValue("--semgrep-deployment").describe(+ "Semgrep deployment slug.",+ ),+ semgrepRef: optionValue("--semgrep-ref").describe(+ "Exact source ref, for example refs/heads/main.",+ ),+ semgrepProduct: z+ .enum(SEMGREP_PLATFORM_PRODUCTS)+ .default("sast")+ .describe("Semgrep Findings API issue type."),+ sourceRepositoryUrl: optionValue("--source-repository-url")+ .optional()+ .describe(+ "Explicit mapping when the Semgrep project has no SCM URL.",+ ),+ }),+ output: semgrepReport,+ run: ({ args, options, error, format }) => {+ escapeSemgrepOutput =+ format === "md" || (format === "toon" && output.isTTY === true);+ return collect("Semgrep", error, (signal) =>+ collectSemgrepPlatformFindings(+ {+ project: args.project,+ deployment: options.semgrepDeployment,+ ref: options.semgrepRef,+ product: options.semgrepProduct,+ sourceRepositoryUrl: options.sourceRepositoryUrl,+ signal,+ },+ http,+ ),+ );},});}@@ -4399,7 +4492,7 @@ export async function main(});}if (importsEnabled) {- registerGitHubAdvisories();+ registerOptInCollectors();registerSonarImport();}const infoOutput = z.object({@@ -7149,9 +7242,12 @@ export async function main(command === "publish" ||command === "import";const subcommand = nestedCommand ? argv[commandIndex + 1] : undefined;+ const optInCollector =+ command === "import" &&+ ["github-advisories", "semgrep", "sonar"].includes(subcommand ?? "");if (command === "import" &&- (subcommand === "github" || subcommand === "github-advisories") &&+ subcommand !== "sonar" &&frameworkFlags.rawCollector) {// Incur's skill-sync notice turns a saved collector array into an object.@@ -7161,8 +7257,7 @@ export async function main(!importsEnabled &&((command === "publish" && subcommand === "findings") ||(command === "findings" && subcommand === "imported") ||- (command === "import" &&- (subcommand === "github-advisories" || subcommand === "sonar")))+ optInCollector)) {if (process.env["COMPLETE"] ||@@ -7183,7 +7278,7 @@ export async function main(cliOptions.sync = false;if (command === "publish") registerFindingPublication();else if (subcommand === "sonar") registerSonarImport();- else registerGitHubAdvisories();+ else registerOptInCollectors();valueOptions = cliValueOptions(commands);}}@@ -7435,6 +7530,8 @@ export async function main(renderedOutput = failureOutput.text();}let frameworkOutput = frameworkCapture.text();+ if (escapeSemgrepOutput)+ frameworkOutput = escapeTerminalText(frameworkOutput, true);const writeUpdateNotice = () => {if (notice === undefined || batchedVerification) return;try {diff --git a/sdk/typescript/src/external-findings-import.ts b/sdk/typescript/src/external-findings-import.tsindex dea493c7a..e0ff7e119 100644--- a/sdk/typescript/src/external-findings-import.ts+++ b/sdk/typescript/src/external-findings-import.ts@@ -41,6 +41,7 @@ export async function prepareLocalExternalImport(let sourceRepositories = parsed.sourceRepositories ?? [];if (normalizedOptions.provider === "semgrep" &&+ parsed.sourceRepositories &&settings.sourceRepositoryUrl) {// The Cloud reader allows custom GitHub casing. Local provenance must alsodiff --git a/sdk/typescript/src/external-findings-local.ts b/sdk/typescript/src/external-findings-local.tsindex 90135590b..5afd42aa5 100644--- a/sdk/typescript/src/external-findings-local.ts+++ b/sdk/typescript/src/external-findings-local.ts@@ -1,7 +1,10 @@import {- isSemgrepSelectionEvidence,+ semgrepLegacyRepositoryWitnesses,+ semgrepPlatformFindingBinding,+ semgrepPlatformReportScope,+ semgrepPlatformRepositoryReference,+ isSemgrepPlatformEvidence,semgrepReferenceMatches,- semgrepSelectionRepository,} from "./semgrep-platform-findings.js";import {gitPathToHttpPath,@@ -35,6 +38,7 @@ import {localFindingRepositories,semgrepSarifRepositories,} from "./external-findings-read.js";+import { guardianSelectionFormat } from "./semgrep-guardian-findings.js";import {hasGitMetadata,localGitProtectionRoots,@@ -750,6 +754,17 @@ export async function prepareLocalImport(dependencies,);const sources = new Map<string, ExternalSourceRepository>();+ if (+ options.provider === "semgrep" &&+ current.report?.["format"] === guardianSelectionFormat+ ) {+ const url = declaredScannerRepositoryUrl(+ current.report["repositoryUrl"],+ "Guardian",+ "local",+ );+ sources.set(url, { url });+ }const references = [...readerSources, ...parsedSources];const inspector = inspectorReportRepository(options.provider,@@ -824,28 +839,77 @@ export async function prepareLocalImport(}const strictSources = new Map<string, Provider>();const hostedSources = new Map<string, ExternalSourceRepository>();+ const semgrepReportScope = semgrepPlatformReportScope(+ current,+ options.provider,+ readerSources,+ );+ const semgrepPlatformRepositoryUrl = semgrepReportScope?.url;+ function addSemgrepSource(url: string) {+ if (options.provider !== "semgrep")+ throw new CodexSecurityError(+ "Use the semgrep provider for Semgrep Platform findings.",+ );+ const source = semgrepPlatformRepositoryReference(url, readerSources);+ if (+ semgrepPlatformRepositoryUrl &&+ semgrepPlatformRepositoryUrl !== url &&+ !semgrepReferenceMatches(source, semgrepPlatformRepositoryUrl)+ )+ throw new CodexSecurityError(+ "The Semgrep report repository does not match the native finding's project.",+ );+ hostedSources.set(source.url, source);+ }+ if (semgrepPlatformRepositoryUrl)+ addSemgrepSource(semgrepPlatformRepositoryUrl);const known = new Set<string>(parsedSources.map(({ url }) => url));+ const legacyWitnesses = semgrepLegacyRepositoryWitnesses(+ current.findings,+ options.provider,+ readerSources,+ );const hasPlatformEvidence =options.provider === "semgrep" &&- current.findings.some(isSemgrepSelectionEvidence);+ (semgrepReportScope !== undefined ||+ current.findings.some((row) =>+ isSemgrepPlatformEvidence(row, options.provider),+ ));let hasOrdinaryRows = false;let ordinaryRowNeedsReferences = false;for (const finding of current.findings) {- const semgrep = semgrepSelectionRepository(finding, readerSources);- if (semgrep && options.provider !== "semgrep")- throw new CodexSecurityError(- "Use the semgrep provider for Semgrep Platform selections.",+ const retained = bound.get(finding.source_finding_id);+ const native = nativeSources.get(finding) ?? [];+ const sarif = hasPlatformEvidence ? semgrepSarifRepositories(finding) : [];+ const semgrep = semgrepPlatformFindingBinding(+ finding,+ options.provider,+ readerSources,+ legacyWitnesses,+ semgrepReportScope,+ [retained, ...native, ...sarif],+ );+ if (semgrep) {+ addSemgrepSource(semgrep.url);+ if (semgrep.sourceData) finding.evidence.source_data = semgrep.sourceData;+ if (semgrep.migration) Object.assign(finding.evidence, semgrep.migration);+ } else hasOrdinaryRows = true;+ const { evidence } = finding;+ if (+ options.provider === "semgrep" &&+ evidence.source_data?.["format"] === guardianSelectionFormat+ ) {+ const url = declaredScannerRepositoryUrl(+ evidence.source_data["sourceRepositoryUrl"],+ "Guardian",+ "local",);- if (semgrep) hostedSources.set(semgrep.url, semgrep);- else hasOrdinaryRows = true;- const { evidence, source_finding_id: id } = finding;+ sources.set(url, { url });+ }const url = evidence.details?.repository?.url;- const retained = bound.get(id);- const native = nativeSources.get(finding) ?? [];// A selected row's projected URL was already verified against its hosted source.if (!semgrep && url) sources.set(url, { url });if (hasPlatformEvidence && !semgrep && !retained && !native.length) {- const sarif = semgrepSarifRepositories(finding);for (const source of sarif) sources.set(source.url, source);if (!url && !sarif.length) ordinaryRowNeedsReferences = true;if (!url && references.length) {diff --git a/sdk/typescript/src/external-findings-publish.ts b/sdk/typescript/src/external-findings-publish.tsindex 0b084c69e..aaf1099d5 100644--- a/sdk/typescript/src/external-findings-publish.ts+++ b/sdk/typescript/src/external-findings-publish.ts@@ -27,12 +27,16 @@ import {type PrivateImportJob,} from "./private-finding-import.js";import { readCloudCredentials } from "./cloud-publish.js";+import { guardianSelectionFormat } from "./semgrep-guardian-findings.js";import {cloudBaseUrl,cloudFindingsUrl,DEFAULT_CLOUD_BASE_URL,} from "./cloud-endpoint.js";-import { isSemgrepSelectionEvidence } from "./semgrep-platform-findings.js";+import {+ isSemgrepPlatformEvidence,+ semgrepPlatformReportRepository,+} from "./semgrep-platform-findings.js";import { CodexSecurityError, errorMessage } from "./errors.js";import { requireExternalImports } from "./external-imports-feature.js";import {@@ -506,21 +510,32 @@ function storedFindingId(finding: ExternalFinding): string {return "";}-function rejectLocalSelections(input: ExternalFindings): void {- const rows = input?.findings;- if (!Array.isArray(rows)) return;+function rejectLocalSemgrepReports(+ input: ExternalFindings,+ provider: string,+): void {+ if (!input || (typeof input !== "object" && typeof input !== "function"))+ return;+ const isPlatform = (row: ExternalFinding) => {+ if (!row) return false;+ const id = storedFindingId(row);+ const evidence = row.evidence;+ return (+ /^semgrep-guardian:[0-9a-f]{64}$/u.test(id) ||+ ownData(ownData(evidence, "source_data"), "format") ===+ guardianSelectionFormat ||+ isSemgrepPlatformEvidence({ source_finding_id: id, evidence }, provider)+ );+ };+ const hasPlatformRows = (rows: ExternalFinding[]) =>+ Array.isArray(rows) && rows.some(isPlatform);if (- rows.some(- (row) =>- row &&- isSemgrepSelectionEvidence({- source_finding_id: storedFindingId(row),- evidence: row.evidence,- }),- )+ ownData(ownData(input, "report"), "format") === guardianSelectionFormat ||+ semgrepPlatformReportRepository(input, provider, isPlatform) ||+ hasPlatformRows(input.findings))throw new CodexSecurityError(- "Semgrep Platform selections require a local import.",+ "Semgrep Platform findings require a local import.",);}@@ -532,9 +547,10 @@ export async function prepareExternalPublication(requireExternalImports(dependencies.environment);const settings = snapshotImportOptions(options);const parsed = await readExternalFindings(path, settings);- rejectLocalSelections(parsed.findings);+ rejectLocalSemgrepReports(parsed.findings, settings.provider);return preparePublicationInput(- parsed.publication ?? normalizedPublicationInput(parsed.findings),+ parsed.publication ??+ normalizedPublicationInput(parsed.findings, settings.provider),{ ...settings, provider: EXTERNAL_FINDINGS_PROVIDERS[settings.provider] },dependencies,path,@@ -548,10 +564,10 @@ export async function prepareNormalizedExternalPublication(dependencies: ExternalPublicationDependencies = {},): Promise<PreparedExternalPublication> {requireExternalImports(dependencies.environment);- rejectLocalSelections(input);const settings = snapshotImportOptions(options);+ rejectLocalSemgrepReports(input, settings.provider);return preparePublicationInput(- normalizedPublicationInput(input),+ normalizedPublicationInput(input, settings.provider),settings,dependencies,);@@ -736,6 +752,7 @@ function historicalPublication(function normalizedPublicationInput(input: ExternalFindings,+ provider: string,): PublicationSelection {const nativeDiagnostics = new Map<number, Error>();let native: ExternalFindings | undefined;@@ -810,7 +827,7 @@ function normalizedPublicationInput(: undefined;if (reader) native = reader.snapshot;const original = historicalPublication(native);- if (original) rejectLocalSelections(original.parsed);+ if (original) rejectLocalSemgrepReports(original.parsed, provider);try {validatePublicationFindings(current, validateExternalEvidence);} catch (error) {@@ -823,7 +840,7 @@ function normalizedPublicationInput(// Only the old selection can be reviewed when fresh validation failed.current = { read: original.parsed.read, findings: [], excluded: [] };}- rejectLocalSelections(current);+ rejectLocalSemgrepReports(current, provider);const identity = publicationIdentity(current);return {current,@@ -1170,7 +1187,7 @@ async function preparePublicationInput(!verifiableLegacyMetadata(originalParsed, true))throw unmatchedPreviousNumbers();- rejectLocalSelections({ ...parsed, findings: saved });+ rejectLocalSemgrepReports({ ...parsed, findings: saved }, options.provider);return content;}@@ -1205,7 +1222,7 @@ async function preparePublicationInput(!verifiableLegacyMetadata(originalParsed, false))throw unmatchedPreviousNumbers();- rejectLocalSelections({ ...parsed, findings: saved });+ rejectLocalSemgrepReports({ ...parsed, findings: saved }, options.provider);content.legacyApproval = true;content.inputProjection = {identityFormat: 2,diff --git a/sdk/typescript/src/external-findings-read.ts b/sdk/typescript/src/external-findings-read.tsindex 25f8c2a89..951cb0e45 100644--- a/sdk/typescript/src/external-findings-read.ts+++ b/sdk/typescript/src/external-findings-read.ts@@ -11,6 +11,7 @@ import {isSemgrepSarifDriver,readSemgrepFindings,} from "./semgrep-findings.js";+import { semgrepPlatformReportRepository } from "./semgrep-platform-findings.js";import { readOpenGrepFindings } from "./opengrep-findings.js";import { readEndorFindings, endorRepositoryUrls } from "./endor-findings.js";import { dependabotRepository } from "./github-dependabot-findings.js";@@ -90,7 +91,7 @@ export function localFindingRepositories(/** Repository claims retained by the Semgrep SARIF reader. */export function semgrepSarifRepositories({evidence,-}: ExternalFinding): ExternalSourceRepository[] {+}: ExternalFinding): { url: string; branch?: string }[] {const data = evidence.source_data;const document = data?.["documentContext"];const driver = data?.["driverContext"];@@ -112,7 +113,14 @@ export function semgrepSarifRepositories({isRecord(reference) &&typeof reference["repositoryUri"] === "string" &&reference["repositoryUri"].trim()- ? [{ url: reference["repositoryUri"] }]+ ? [+ {+ url: reference["repositoryUri"],+ ...(typeof reference["branch"] === "string" && {+ branch: reference["branch"],+ }),+ },+ ]: [],): [];@@ -162,11 +170,12 @@ export async function readExternalFindings(const findings = await readSemgrepFindings(path,{- sourceRepositoryUrl: options.sourceRepositoryUrl ?? "",+ sourceRepositoryUrl: options.sourceRepositoryUrl,sourceRepositories: references,},target,);+ if (semgrepPlatformReportRepository(findings)) return { findings };const sourceRepositories = findings.findings.flatMap(semgrepSarifRepositories,);diff --git a/sdk/typescript/src/external-import-contract.ts b/sdk/typescript/src/external-import-contract.tsindex fdc64fdb7..3785e3027 100644--- a/sdk/typescript/src/external-import-contract.ts+++ b/sdk/typescript/src/external-import-contract.ts@@ -277,6 +277,16 @@ export function validateExternalReport(serializeImportJson(report, checkReportNumber);}+export function validateCodeLineRange(+ firstLine: number | null | undefined,+ endLine: number | null | undefined,+) {+ if (endLine != null && (firstLine == null || endLine < firstLine))+ throw new Error(+ "The code end line requires a first source location line and cannot precede it.",+ );+}+export function validateExternalEvidenceFields(input: unknown,target: ExternalImportTarget = "cloud",@@ -313,14 +323,10 @@ export function validateExternalEvidenceFields(throw new Error("Advisory source context requires advisory evidence.");}}- const endLine = result.details?.code?.end_line;- if (endLine !== null && endLine !== undefined) {- const firstLine = result.locations?.[0]?.line;- if (firstLine === null || firstLine === undefined || endLine < firstLine)- throw new Error(- "The code end line requires a first source location line and cannot precede it.",- );- }+ validateCodeLineRange(+ result.locations?.[0]?.line,+ result.details?.code?.end_line,+ );const urls = [result.url,result.details?.repository?.url,diff --git a/sdk/typescript/src/external-imports-feature.ts b/sdk/typescript/src/external-imports-feature.tsindex 190212fa0..011244e0c 100644--- a/sdk/typescript/src/external-imports-feature.ts+++ b/sdk/typescript/src/external-imports-feature.ts@@ -3,9 +3,12 @@ import { CodexSecurityError } from "./errors.js";const flag = "CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS";export const externalImportsDisabledMessage = `External findings imports are disabled. Set ${flag}=1 to enable them.`;-function externalImportSetting<Value>(environment: Record<string, Value>) {- const exact = environment[flag];- if (process.platform !== "win32") return { key: flag, value: exact };+export function importEnvironmentSetting<Value>(+ environment: Record<string, Value>,+ requested: string,+) {+ const exact = environment[requested];+ if (process.platform !== "win32") return { key: requested, value: exact };// A scan can override a case-insensitive process.env with its own spelling.function callerDeclares(key: string): boolean {for (@@ -17,23 +20,23 @@ function externalImportSetting<Value>(environment: Record<string, Value>) {}return false;}- if (exact !== undefined && callerDeclares(flag))- return { key: flag, value: exact };+ if (exact !== undefined && callerDeclares(requested))+ return { key: requested, value: exact };// Node includes enumerable prototype keys and sorts competing spellings.const keys: string[] = [];for (const name in environment) {- if (name.toUpperCase() === flag) keys.push(name);+ if (name.toUpperCase() === requested) keys.push(name);}keys.sort();const key = keys.find(callerDeclares) ?? keys[0];if (key !== undefined)- return { key, value: key === flag ? exact : environment[key] };+ return { key, value: key === requested ? exact : environment[key] };}export function externalImportsEnabled(environment: NodeJS.ProcessEnv = process.env,): boolean {- return externalImportSetting(environment)?.value === "1";+ return importEnvironmentSetting(environment, flag)?.value === "1";}/** Preserve the selected flag while copying a caller's environment for a child. */@@ -41,7 +44,7 @@ export function forwardExternalImportSetting<Value>(source: Record<string, Value | undefined>,child: Record<string, Value>,): void {- const selected = externalImportSetting(source);+ const selected = importEnvironmentSetting(source, flag);if (selected === undefined) return;if (process.platform === "win32") {for (const name of Object.keys(child)) {diff --git a/sdk/typescript/src/hosted-scanner-http.ts b/sdk/typescript/src/hosted-scanner-http.tsnew file mode 100644index 000000000..455fcca7a--- /dev/null+++ b/sdk/typescript/src/hosted-scanner-http.ts@@ -0,0 +1,123 @@+import { CodexSecurityError } from "./errors.js";+import { normalizeHostedGitRepositoryUrl } from "./hosted-git-repository.js";+import { importEnvironmentSetting } from "./external-imports-feature.js";+import { isRecord } from "./record.js";+import { declaredScannerRepositoryUrl } from "./scanner-repository-url.js";++export interface HostedScannerHttpOptions {+ environment?: NodeJS.ProcessEnv;+ fetch?: (url: URL, init: RequestInit) => Promise<Response>;+ signal?: AbortSignal;+}++// Our minimum Node runtime provides source-aware JSON parsing. Our SDK targets ES2022 types.+const wireJson = JSON as JSON & {+ rawJSON(source: string): { rawJSON: string };+ isRawJSON(value: unknown): value is { rawJSON: string };+};+export function hostedNumberToken(value: unknown): string | undefined {+ return wireJson.isRawJSON(value) ? value.rawJSON : undefined;+}++/** Keep vendor numeric IDs and evidence exact when a response is saved as JSON. */+export function parseHostedScannerJson(source: string): unknown {+ return JSON.parse(+ source,+ (_key: string, value: unknown, context?: { source?: string }) => {+ if (typeof value === "number") return wireJson.rawJSON(context!.source!);+ // Identical vendor evidence can arrive with a different member order on replay.+ return isRecord(value)+ ? Object.fromEntries(+ Object.keys(value)+ .sort()+ .map((key) => [key, value[key]]),+ )+ : value;+ },+ );+}++export function hostedRepositoryUrl(value: unknown, label: string): string {+ // Hosted Git URLs retain %23 and %3F as path bytes; a literal query or fragment is rejected.+ return declaredScannerRepositoryUrl(value, label, "local", {+ allowEncodedQueryAndFragment: true,+ });+}++/** Normalize the provider's HTTP or independently identified SSH repository address. */+export function hostedNativeRepositoryUrl(+ value: unknown,+ label: string,+ additionalGitHost?: string,+): string {+ const source = additionalGitHost ? `https://${additionalGitHost}` : undefined;+ const normalized =+ typeof value === "string" && value.trim() === value+ ? normalizeHostedGitRepositoryUrl(value, source, source !== undefined)+ : value;+ return hostedRepositoryUrl(normalized, label);+}++/** Use the selected vendor credential only with its configured service origin. */+export function hostedScannerToken(+ environment: NodeJS.ProcessEnv,+ tokenName: string,+ explicitToken: string | undefined,+ origin: string,+ ...originNames: string[]+): string | undefined {+ const token =+ explicitToken ?? importEnvironmentSetting(environment, tokenName)?.value;+ if (token) {+ for (const name of originNames) {+ const configured = importEnvironmentSetting(environment, name)?.value;+ if (!configured) continue;+ if (URL.parse(configured)?.origin !== origin)+ throw new Error(+ `${name} does not match ${origin}. Select a matching API origin and ${tokenName} before collecting findings.`,+ );+ break;+ }+ }+ return token;+}++export function hostedScannerHttp(+ dependencies: HostedScannerHttpOptions,+ callerSignal?: AbortSignal,+) {+ const { signal: transportSignal } = dependencies;+ const signal =+ callerSignal && transportSignal+ ? AbortSignal.any([callerSignal, transportSignal])+ : (callerSignal ?? transportSignal);+ signal?.throwIfAborted();+ const request = dependencies.fetch?.bind(dependencies) ?? fetch;+ async function getJson(url: URL, authorization: string): Promise<unknown> {+ signal?.throwIfAborted();+ if (/[\0\r\n]/u.test(authorization))+ throw new Error("Scanner API token cannot contain a NUL or line break.");+ const response = await request(url, {+ method: "GET",+ headers: {+ accept: "application/vnd.api+json, application/json",+ authorization,+ },+ redirect: "error",+ signal,+ });+ if (!response.ok) {+ const retry = response.headers.get("retry-after");+ const detail = await response.text();+ throw new CodexSecurityError(+ `GET ${url.origin}${url.pathname} failed (HTTP ${response.status})${retry ? `; Retry-After: ${retry}` : ""}${detail ? `: ${detail}` : "."}`,+ );+ }+ return parseHostedScannerJson(+ new TextDecoder("utf-8", { fatal: true }).decode(+ await response.arrayBuffer(),+ ),+ );+ }+ return { signal, getJson };+}diff --git a/sdk/typescript/src/hosted-scanner-v1.ts b/sdk/typescript/src/hosted-scanner-v1.tsnew file mode 100644index 000000000..cb0a81ecb--- /dev/null+++ b/sdk/typescript/src/hosted-scanner-v1.ts@@ -0,0 +1,78 @@+import {+ hostedNumberToken,+ parseHostedScannerJson,+} from "./hosted-scanner-http.js";+import { isRecord } from "./record.js";++const decimalToken = /^-?(0|[1-9]\d*)(?:\.(\d+))?(?:e([+-]?\d+))?$/iu;++// Compare decimal values and check integral IDs without expanding unbounded exponents.+function magnitude(token: string) {+ const parts = decimalToken.exec(token);+ if (!parts) return;+ const fraction = parts[2] ?? "";+ const digits = (parts[1]! + fraction).replace(/^0+/u, "");+ const point = digits.length+ ? digits.length - fraction.length + Number(parts[3] ?? 0)+ : 0;+ let end = digits.length;+ while (end > 0 && digits[end - 1] === "0") end--;+ return { digits: digits.slice(0, end), point };+}++export function legacyDecimalInteger(token: string): string | undefined {+ const value = magnitude(token);+ if (!value || token.startsWith("-")) return;+ const { digits, point } = value;+ if (!digits || point < digits.length || point > 19) return;+ const id = digits.padEnd(point, "0");+ return point < 19 || id <= "9223372036854775807" ? id : undefined;+}++/** A legacy export needs a type witness when JSON.parse cannot preserve a decimal. */+export function isLegacyWitness(token: string): boolean {+ const exact = magnitude(token);+ if (!exact) return false;+ const parsed = Number(token);+ if (+ !Number.isFinite(parsed) ||+ (Number.isInteger(parsed) && !Number.isSafeInteger(parsed))+ )+ return true;+ const rounded = magnitude(String(parsed))!;+ return rounded.point !== exact.point || rounded.digits !== exact.digits;+}++function restoreField(value: unknown, witness: unknown): unknown {+ if (typeof witness === "string") {+ if (value !== witness || !isLegacyWitness(witness))+ throw new Error("Invalid exact scanner number.");+ return parseHostedScannerJson(witness);+ }+ if (+ !isRecord(witness) ||+ hostedNumberToken(witness) !== undefined ||+ (!Array.isArray(value) &&+ (!isRecord(value) || hostedNumberToken(value) !== undefined))+ )+ throw new Error("Invalid scanner numeric fields.");+ const restored = Array.isArray(value) ? [...value] : { ...value };+ const fields = restored as Record<string, unknown>;+ for (const [key, child] of Object.entries(witness)) {+ if (!Object.hasOwn(restored, key))+ throw new Error("Invalid scanner numeric field.");+ fields[key] = restoreField(fields[key], child);+ }+ return restored;+}++/** Original hosted exports saved imprecise JSON numbers as text plus a sparse type witness. */+export function restoreLegacyHostedNumbers(+ document: Record<string, unknown>,+): Record<string, unknown> {+ const fields = document["numericFields"];+ if (fields === undefined) return document;+ if (!isRecord(fields) || Object.hasOwn(fields, "numericFields"))+ throw new Error("Invalid scanner numeric fields.");+ return restoreField(document, fields) as Record<string, unknown>;+}diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex 3befeaad2..e6664c2a8 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -366,9 +366,17 @@ export {readSemgrepFindings,type SemgrepImportOptions,} from "./semgrep-findings.js";+export { collectSemgrepPlatformFindings } from "./semgrep-platform-collector.js";+export { collectSelectedSemgrepGuardianFindings } from "./semgrep-guardian-findings.js";+export type {+ SemgrepPlatformOptions,+ SemgrepPlatformReport,+} from "./semgrep-platform-collector.js";+export type { HostedScannerHttpOptions } from "./hosted-scanner-http.js";export {normalizeSelectedSemgrepPlatformFindings,selectSemgrepPlatformFindings,+ normalizeSemgrepPlatformFindings,type SemgrepPlatformSelection,} from "./semgrep-platform-findings.js";export {diff --git a/sdk/typescript/src/scanner-import.ts b/sdk/typescript/src/scanner-import.tsindex 2dc6bb71e..723f479bf 100644--- a/sdk/typescript/src/scanner-import.ts+++ b/sdk/typescript/src/scanner-import.ts@@ -5,6 +5,7 @@ import { promisify } from "node:util";import { gunzip } from "node:zlib";import { CodexSecurityError, errorMessage } from "./errors.js";import type { ExternalFinding, ExternalFindings } from "./external-findings.js";+import { SCAN_SEVERITIES } from "./scan-settings.js";import { isRecord } from "./record.js";import { previousAdmission } from "./external-import-contract.js";import { rememberPreviousSelection } from "./reader-selection.js";@@ -30,6 +31,10 @@ export function requiredText(value: unknown, label: string): string {return result;}+export function scannerSeverity(value: string | null | undefined) {+ return SCAN_SEVERITIES.find((severity) => severity === value) ?? "unknown";+}+export function strings(value: unknown): string[] {return Array.isArray(value)? value.filter((v): v is string => text(v) !== null)@@ -48,6 +53,14 @@ export function relativePath(value: unknown): string | null {: null;}+// Hosted findings do not identify the scanner operating system or its path separator.+export function hostedRepositoryPath(value: unknown) {+ const path = text(value);+ return path && !path.includes("\\") && !path.includes("://")+ ? relativePath(path)+ : null;+}+export function repositoryFilePath(value: unknown): string | null {const relative = relativePath(value);if (!relative) return null;@@ -89,6 +102,7 @@ export function parseJsonOrJsonl(contents: string): unknown {export async function readScannerJson(path: string | FileHandle,+ parse: (json: string) => unknown = JSON.parse,): Promise<unknown> {const bytes = await readScannerBytes(path);let decoded: string;@@ -101,7 +115,7 @@ export async function readScannerJson();}try {- return JSON.parse(decoded.replace(/^\uFEFF/u, ""));+ return parse(decoded.replace(/^\uFEFF/u, ""));} catch (error) {throw new CodexSecurityError(`Scanner JSON could not be parsed. ${errorMessage(error)}`,diff --git a/sdk/typescript/src/scanner-repository-url.ts b/sdk/typescript/src/scanner-repository-url.tsindex 5ab68791f..fb3969307 100644--- a/sdk/typescript/src/scanner-repository-url.ts+++ b/sdk/typescript/src/scanner-repository-url.ts@@ -10,30 +10,33 @@ import type {} from "./external-findings.js";import { requiredText } from "./scanner-import.js";-function repositorySegment(encoded: string): boolean {+function repositorySegment(+ encoded: string,+ allowEncodedQueryAndFragment: boolean,+): boolean {try {const segment = decodeURIComponent(encoded);return (Boolean(segment) &&segment.trim() === segment &&!["", ".", ".."].includes(segment.replace(/\.git$/iu, "")) &&- !/[/\\?#\p{Cc}]|%[\da-f]{2}/iu.test(segment)+ !/[/\\\p{Cc}]|%[\da-f]{2}/iu.test(segment) &&+ (allowEncodedQueryAndFragment || !/[?#]/u.test(segment)));} catch {return false;}}-export function declaredScannerRepositoryUrl(- value: unknown,- provider: string,- target: ExternalImportTarget = "cloud",-): string {- const source = requiredText(value, `${provider} --source-repository-url`);+export function validScannerRepositoryUrl(+ source: string,+ target: ExternalImportTarget,+ allowEncodedQueryAndFragment = false,+): boolean {const url = URL.parse(source);const parts = /^https?:\/\/([^/?#\\]+)\/([^?#\\]+)$/iu.exec(source);const segments = parts?.[2]?.replace(/\/$/u, "").split("/") ?? [];- if (+ return !(!url ||!parts ||parts[1]!.includes("@") ||@@ -41,8 +44,22 @@ export function declaredScannerRepositoryUrl(url.username ||url.password ||segments.length < (target === "local" ? 1 : 2) ||- !segments.every(repositorySegment)- )+ !segments.every((segment) =>+ repositorySegment(segment, allowEncodedQueryAndFragment),+ )+ );+}++export function declaredScannerRepositoryUrl(+ value: unknown,+ provider: string,+ target: ExternalImportTarget = "cloud",+ {+ allowEncodedQueryAndFragment = false,+ }: { allowEncodedQueryAndFragment?: boolean } = {},+): string {+ const source = requiredText(value, `${provider} --source-repository-url`);+ if (!validScannerRepositoryUrl(source, target, allowEncodedQueryAndFragment))throw new Error(`${provider} --source-repository-url requires an HTTP(S) repository path without credentials, query, fragment, or ambiguous path segments.`,);diff --git a/sdk/typescript/src/semgrep-findings.ts b/sdk/typescript/src/semgrep-findings.tsindex 0bf795366..90037a4d0 100644--- a/sdk/typescript/src/semgrep-findings.ts+++ b/sdk/typescript/src/semgrep-findings.ts@@ -1,7 +1,15 @@import {- normalizeSemgrepPlatformSelection,- semgrepSelectionFormat,+ normalizeSemgrepPlatformFindings,+ isSemgrepPlatformFormat,+ semgrepPlatformLegacyFormat,+ semgrepPlatformFormat,} from "./semgrep-platform-findings.js";+import { isRecord } from "./record.js";+import {+ guardianSelectionFormat,+ normalizeGuardianSelection,+} from "./semgrep-guardian-findings.js";+import { parseHostedScannerJson } from "./hosted-scanner-http.js";import type { ExternalImportTarget } from "./external-import-contract.js";import {cloudRepositoryUrlKey,@@ -41,7 +49,7 @@ export interface SemgrepImportOptions {sourceRepositoryUrl: string;}-function sourceRepository(options: SemgrepImportOptions): string {+function sourceRepository(options: Partial<SemgrepImportOptions>): string {return sourceRepositoryUrl(options?.sourceRepositoryUrl, "Semgrep");}@@ -156,14 +164,17 @@ function sarifIdentity(export function normalizeSemgrepFindings(input: unknown,- options: SemgrepImportOptions,+ options: Partial<SemgrepImportOptions> = {},target: ExternalImportTarget = "cloud",): ExternalFindings {const document = record(input, "Semgrep report");- if (document["format"] === semgrepSelectionFormat) {+ if (document["format"] === guardianSelectionFormat) {if (target !== "local")- throw new Error("Semgrep Platform selections require a local import.");- return normalizeSemgrepPlatformSelection(+ throw new Error("Import Guardian selections into the local workbench.");+ return normalizeGuardianSelection(document, options.sourceRepositoryUrl);+ }+ if (isSemgrepPlatformFormat(document["format"])) {+ return normalizeSemgrepPlatformFindings(document,options?.sourceRepositoryUrl,target,@@ -171,7 +182,11 @@ export function normalizeSemgrepFindings();}if (document["version"] === "2.1.0" && document["runs"] !== undefined)- return normalizeSemgrepSarif(document, options, target);+ return normalizeSemgrepSarif(+ document,+ { ...options, sourceRepositoryUrl: options?.sourceRepositoryUrl ?? "" },+ target,+ );const repositoryUrl = sourceRepository(options);requiredText(document["version"], "Semgrep version");if (array(document["errors"] ?? [], "Semgrep errors").length)@@ -346,8 +361,25 @@ export function normalizeSemgrepSarif(export async function readSemgrepFindings(path: string,- options: SemgrepImportOptions,+ options: Partial<SemgrepImportOptions> = {},target: ExternalImportTarget = "cloud",): Promise<ExternalFindings> {- return normalizeSemgrepFindings(await readScannerJson(path), options, target);+ const report = await readScannerJson(path, (json) => {+ // Pick a parser before allocating the findings array. Verify the root:+ // the member can be nested in a native report or escaped in a Platform one.+ const parser = /"format"\s*:\s*"semgrep-platform-findings\/v[12]"/u.test(+ json,+ )+ ? parseHostedScannerJson+ : JSON.parse;+ const parsed: unknown = parser(json);+ const requiredParser =+ isRecord(parsed) &&+ (parsed["format"] === semgrepPlatformLegacyFormat ||+ parsed["format"] === semgrepPlatformFormat)+ ? parseHostedScannerJson+ : JSON.parse;+ return parser === requiredParser ? parsed : requiredParser(json);+ });+ return normalizeSemgrepFindings(report, options, target);}diff --git a/sdk/typescript/src/semgrep-guardian-findings.ts b/sdk/typescript/src/semgrep-guardian-findings.tsnew file mode 100644index 000000000..63ee75993--- /dev/null+++ b/sdk/typescript/src/semgrep-guardian-findings.ts@@ -0,0 +1,236 @@+import {+ repositoryUrlKey,+ validateExternalEvidence,+} from "./external-import-contract.js";+import { requireExternalImports } from "./external-imports-feature.js";+import { isRecord } from "./record.js";+import {+ array,+ normalizeRecords,+ record,+ requiredText,+ scannerSeverity,+ stableId,+ text,+} from "./scanner-import.js";+import { declaredScannerRepositoryUrl } from "./scanner-repository-url.js";+import {+ platformLocationPath,+ requireSemgrepFullRef,+} from "./semgrep-platform-findings.js";++export const guardianSelectionFormat = "semgrep-guardian-selection/v1";++type GuardianTool =+ "get_semgrep_sast_findings" | "get_semgrep_supply_chain_findings";++/** The request passed to the signed-in Guardian MCP client. */+interface GuardianRequest {+ name: GuardianTool;+ arguments: {+ deployment_name: string;+ repository_name: string;+ ref: string;+ states?: string[] | null;+ severities?: string[] | null;+ max_num_findings?: number;+ };+}++function selectionScope(request: unknown, findingIds: unknown) {+ const tool = record(request, "Guardian tool request");+ const name = tool["name"];+ if (+ name !== "get_semgrep_sast_findings" &&+ name !== "get_semgrep_supply_chain_findings"+ )+ throw new Error("Select a Guardian SAST or Supply Chain findings tool.");+ const args = record(tool["arguments"], "Guardian tool arguments");+ const deployment = requiredText(+ args["deployment_name"],+ "Guardian deployment",+ );+ const repository = requiredText(+ args["repository_name"],+ "Guardian repository",+ );+ const ref = requiredText(args["ref"], "Guardian Git ref");+ requireSemgrepFullRef(ref);+ const ids = new Set(+ array(findingIds, "Guardian finding IDs").map((id) =>+ requiredText(id, "Guardian finding ID"),+ ),+ );+ if (!ids.size) throw new Error("Select at least one Guardian finding ID.");+ return { tool: name, deployment, repository, ref, ids };+}++function selectedRows(+ scope: ReturnType<typeof selectionScope>,+ structuredContent: unknown,+) {+ const { findings } = record(structuredContent, "Guardian structuredContent");+ const rows = new Map<string, Record<string, unknown>>();+ for (const row of array(findings ?? [], "Guardian findings")) {+ if (+ !isRecord(row) ||+ typeof row["id"] !== "string" ||+ !scope.ids.has(row["id"])+ )+ continue;+ const id = row["id"];+ if (rows.has(id))+ throw new Error(`Guardian returned duplicate finding ID ${id}.`);+ const repository = record(row["repository"], "Guardian finding repository");+ if (+ repository["name"] !== scope.repository ||+ (row["ref"] != null && row["ref"] !== scope.ref)+ )+ throw new Error(+ `Guardian finding ${id} does not match the selected repository and ref.`,+ );+ const expected =+ scope.tool === "get_semgrep_sast_findings" ? "sast" : "sca";+ if (+ row["issueType"] != null &&+ text(row["issueType"])+ ?.toLowerCase()+ .replace(/^issue_type_/u, "") !== expected+ )+ throw new Error(+ `Guardian finding ${id} does not match the selected product.`,+ );+ rows.set(id, row);+ }+ return Array.from(scope.ids, (id) => {+ const row = rows.get(id);+ if (!row)+ throw new Error(`Guardian did not return selected finding ${id}.`);+ return row;+ });+}++/** Use the caller's connected Guardian MCP client. Only selected rows enter the saved capture. */+export async function collectSelectedSemgrepGuardianFindings(+ selection: {+ request: GuardianRequest;+ findingIds: readonly string[];+ sourceRepositoryUrl: string;+ },+ dependencies: {+ callTool: (request: GuardianRequest) => Promise<unknown>;+ environment?: NodeJS.ProcessEnv;+ },+) {+ requireExternalImports(dependencies.environment);+ const query = structuredClone(selection.request);+ const scope = selectionScope(query, selection.findingIds);+ const sourceRepositoryUrl = declaredScannerRepositoryUrl(+ selection.sourceRepositoryUrl,+ "Guardian",+ "local",+ );+ const result = record(+ await dependencies.callTool(query),+ "Guardian MCP result",+ );+ if (result["isError"]) {+ const content = result["content"];+ const messages = Array.isArray(content)+ ? content+ .map((part: unknown) =>+ isRecord(part) && part["type"] === "text"+ ? text(part["text"])+ : null,+ )+ .filter(Boolean)+ : [];+ throw new Error(messages.join("\n") || "Guardian MCP request failed.");+ }+ return {+ format: guardianSelectionFormat,+ sourceRepositoryUrl,+ request: query,+ findingIds: [...scope.ids],+ structuredContent: {+ findings: selectedRows(scope, result["structuredContent"]),+ },+ };+}++export function normalizeGuardianSelection(+ document: Record<string, unknown>,+ declaredUrl?: string,+) {+ // Guardian returns a repository name. The caller supplies its verified SCM mapping.+ const url = declaredScannerRepositoryUrl(+ document["sourceRepositoryUrl"],+ "Guardian",+ "local",+ );+ if (+ declaredUrl !== undefined &&+ repositoryUrlKey(+ declaredScannerRepositoryUrl(declaredUrl, "Guardian", "local"),+ ) !== repositoryUrlKey(url)+ )+ throw new Error(+ "Guardian selection does not match the declared source repository URL.",+ );+ const scope = selectionScope(document["request"], document["findingIds"]);+ const { tool, deployment, repository, ref } = scope;+ return normalizeRecords(+ selectedRows(scope, document["structuredContent"]),+ (finding) => {+ const rule = text(finding["rulePath"]);+ const message = text(finding["message"]);+ const path = platformLocationPath(finding["filePath"]);+ const line = finding["line"];+ return validateExternalEvidence(+ {+ title: rule ?? message ?? `Semgrep finding ${finding["id"]}`,+ description: message,+ severity: scannerSeverity(+ text(finding["severity"])+ ?.toLowerCase()+ .replace(/^severity_/u, ""),+ ),+ branch: ref,+ locations: path+ ? [{ path, line: line === 0 ? null : (line ?? null) }]+ : [],+ ...(tool === "get_semgrep_sast_findings" && {+ details: {+ kind: "sast",+ scanner_origin: "Semgrep",+ repository: { name: repository, url },+ rule: rule ? { id: rule } : null,+ source_status: text(finding["status"]),+ },+ }),+ source_data: {+ format: guardianSelectionFormat,+ tool,+ deployment,+ repository,+ ref,+ sourceRepositoryUrl: url,+ finding,+ },+ },+ "local",+ );+ },+ // Guardian's string ID has not been verified against Web API occurrence IDs.+ (finding) =>+ stableId("semgrep-guardian", [+ deployment,+ repository,+ tool,+ ref,+ finding["id"],+ ]),+ "local",+ { report: { format: guardianSelectionFormat, repositoryUrl: url } },+ );+}diff --git a/sdk/typescript/src/semgrep-platform-collector.ts b/sdk/typescript/src/semgrep-platform-collector.tsnew file mode 100644index 000000000..d9ddbcd08--- /dev/null+++ b/sdk/typescript/src/semgrep-platform-collector.ts@@ -0,0 +1,198 @@+import {+ snapshotSourceRepositories,+ type ExternalSourceRepository,+} from "./external-findings.js";+import { requireExternalImports } from "./external-imports-feature.js";+import {+ hostedScannerToken,+ hostedRepositoryUrl,+ hostedScannerHttp,+ type HostedScannerHttpOptions,+} from "./hosted-scanner-http.js";+import {+ checkSemgrepPlatformRow,+ projectAliases,+ responseRecord,+ semgrepPlatformFormat,+ selectionRepository,+ semgrepNativeProjectUrl,+ semgrepProjectUrlEvidence,+ semgrepPlatformId,+ semgrepPlatformIdOrUndefined,+ stringifySemgrepFinding,+ SEMGREP_PLATFORM_PRODUCTS,+ type SemgrepPlatformProduct,+ type SemgrepPlatformScope,+} from "./semgrep-platform-findings.js";+import { array, requiredText, stableId, text } from "./scanner-import.js";++export { SEMGREP_PLATFORM_PRODUCTS };++export interface SemgrepPlatformOptions {+ deployment: string;+ project: string;+ ref: string;+ product?: SemgrepPlatformProduct;+ sourceRepositoryUrl?: string;+ sourceRepositories?: readonly ExternalSourceRepository[];+ token?: string;+ signal?: AbortSignal;+}++export interface SemgrepPlatformReport extends SemgrepPlatformScope {+ /** The original transport address when the provider supplied an SSH repository. */+ nativeProjectUrl?: string;+ /** The operator's binding when the native URL is missing or uses SSH. */+ sourceRepositoryUrl?: string;+ format: typeof semgrepPlatformFormat;+ findingCount: number;+ findings: string[];+ repositoryAliases: string[];+}++export async function collectSemgrepPlatformFindings(+ options: SemgrepPlatformOptions,+ dependencies: HostedScannerHttpOptions = {},+): Promise<SemgrepPlatformReport> {+ const environment = dependencies.environment ?? process.env;+ requireExternalImports(environment);+ const token = requiredText(+ hostedScannerToken(+ environment,+ "SEMGREP_APP_TOKEN",+ options.token,+ "https://semgrep.dev",+ "SEMGREP_URL",+ "SEMGREP_APP_URL",+ ),+ "Semgrep Web API token (SEMGREP_APP_TOKEN)",+ );+ const { getJson, signal } = hostedScannerHttp(dependencies, options.signal);+ const deployment = requiredText(options.deployment, "Semgrep deployment");+ const name = requiredText(options.project, "Semgrep project name");+ if (+ deployment.includes("/") ||+ [deployment, name].some((part) => part === "." || part === "..")+ )+ throw new Error("Invalid Semgrep deployment slug or project name.");+ const ref = requiredText(options.ref, "Semgrep ref");+ const { sourceRepositoryUrl } = options;+ const sourceRepositories = snapshotSourceRepositories(+ options.sourceRepositories,+ );+ const product = options.product ?? "sast";+ if (!SEMGREP_PLATFORM_PRODUCTS.includes(product))+ throw new Error("Select a Semgrep Platform product: sast, sca or ai_sast.");++ const base = `https://semgrep.dev/api/v1/deployments/${encodeURIComponent(deployment)}`;+ const get = async (url: URL) =>+ responseRecord(+ await getJson(url, `Bearer ${token}`),+ "Semgrep API response",+ );+ const lookup = await get(+ new URL(`${base}/projects/${encodeURIComponent(name)}`),+ );+ const native = responseRecord(lookup["project"], "Semgrep project");+ if (native["name"] !== name)+ throw new Error("Semgrep returned a different project than requested.");+ const nativeUrl = semgrepNativeProjectUrl(native["url"], sourceRepositories);+ const mappedUrl = hostedRepositoryUrl(+ sourceRepositoryUrl ?? nativeUrl,+ "Semgrep project repository",+ );+ const url = nativeUrl ?? mappedUrl;+ const source = selectionRepository(url, sourceRepositories);+ if (source.key(mappedUrl) !== source.key(url))+ throw new Error(+ "Semgrep project does not match the selected source repository URL.",+ );+ const project = { id: semgrepPlatformId(native["id"]), name, url };+ const scope = { deployment, project, ref, product };+ const endpoint = new URL(`${base}/findings`);+ const pageSize = 3000;+ endpoint.search = new URLSearchParams({+ repository_ids: project.id,+ issue_type: product,+ ref,+ dedup: "false",+ page_size: String(pageSize),+ }).toString();+ const names = projectAliases(name, url, sourceRepositories);+ const witnessed = new Set<string>();+ const verified = {+ has: (label: string) => names.has(label) || witnessed.has(label),+ };+ const observed = new Set<string>();+ async function readPage(page: number, collecting = true) {+ endpoint.searchParams.set("page", String(page));+ const document = await get(new URL(endpoint));+ return array(document["findings"], "Semgrep findings").map((entry) => {+ const finding = responseRecord(entry, "Semgrep finding");+ const repository = responseRecord(+ finding["repository"] ?? {},+ "Semgrep finding repository",+ );+ const label = text(repository["name"]);+ if (collecting && label) observed.add(label);+ checkSemgrepPlatformRow(+ finding,+ scope,+ collecting ? observed : verified,+ source,+ );+ if (+ collecting &&+ label &&+ (repository["id"] != null || text(repository["url"]))+ )+ witnessed.add(label);+ const raw = JSON.stringify(finding);+ return {+ key:+ semgrepPlatformIdOrUndefined(finding["id"]) ??+ stringifySemgrepFinding(finding),+ raw,+ };+ });+ }++ const pageId = (batch: Awaited<ReturnType<typeof readPage>>) =>+ stableId("page", batch.map((row) => row.key).sort());+ const findings: string[] = [];+ const previousKeys = new Set<string>();+ let firstPage: string | undefined;+ for (let page = 0; ; page++) {+ const batch = await readPage(page);+ // Compare only with prior pages; same-page ambiguities are reported per finding on import.+ if (batch.some((row) => previousKeys.has(row.key)))+ throw new Error(+ "Semgrep Platform repeated findings across pages; retry the collection.",+ );+ for (const row of batch) findings.push(row.raw);+ if (batch.length < pageSize) break;+ for (const row of batch) previousKeys.add(row.key);+ if (page === 0) firstPage = pageId(batch);+ }+ // A name-only finding can precede the row that binds this label to the project.+ for (const label of observed) {+ if (!verified.has(label))+ throw new Error(+ `Semgrep finding repository name "${label}" has no matching project name, repository ID or URL.`,+ );+ }+ // Offset pagination can skip a row if the first page changes between reads.+ if (firstPage && firstPage !== pageId(await readPage(0, false)))+ throw new Error(+ "Semgrep Platform findings changed across pages; retry the collection.",+ );+ signal?.throwIfAborted();+ return {+ format: semgrepPlatformFormat,+ ...scope,+ ...semgrepProjectUrlEvidence(native["url"], nativeUrl, sourceRepositoryUrl),+ repositoryAliases: [...observed].sort(),+ findingCount: findings.length,+ findings,+ };+}diff --git a/sdk/typescript/src/semgrep-platform-findings.ts b/sdk/typescript/src/semgrep-platform-findings.tsindex 8e1583052..c3c0c4c12 100644--- a/sdk/typescript/src/semgrep-platform-findings.ts+++ b/sdk/typescript/src/semgrep-platform-findings.ts@@ -1,4 +1,5 @@import {+ validateCodeLineRange,canonicalNumber,validateExternalEvidence,type ExternalImportTarget,@@ -9,40 +10,163 @@ import type {ExternalSourceRepository,} from "./external-findings.js";import {- gitServiceHostname,hostedRepositoryMatches,+ normalizeHostedGitRepositoryUrl,hostedRepositoryUrlKey,+ isPublicGitHost as publicGitHost,+ gitServiceHostname,} from "./hosted-git-repository.js";import { isGitHubCloudHost } from "./git-remote.js";-import { isRecord } from "./record.js";import { position, weaknessIds } from "./native-json-findings.js";import {array,+ hostedRepositoryPath,normalizeRecords,record,relativePath,repositoryFilePath,+ scannerSeverity,+ strings,requiredText,stableId,text,} from "./scanner-import.js";-import { declaredScannerRepositoryUrl } from "./scanner-repository-url.js";+import {+ hostedNumberToken,+ hostedNativeRepositoryUrl,+ hostedRepositoryUrl,+} from "./hosted-scanner-http.js";+import { isRecord } from "./record.js";+import {+ declaredScannerRepositoryUrl,+ validScannerRepositoryUrl,+} from "./scanner-repository-url.js";+import {+ legacyDecimalInteger,+ restoreLegacyHostedNumbers,+} from "./hosted-scanner-v1.js";+import {+ semgrepV1Id,+ upgradeSemgrepPlatformReport,+} from "./semgrep-platform-v1.js";+import type { SemgrepImportOptions } from "./semgrep-findings.js";++export const semgrepPlatformFormat = "semgrep-platform-findings/v2";+export const semgrepPlatformLegacyFormat = "semgrep-platform-findings/v1";+export const SEMGREP_PLATFORM_PRODUCTS = ["sast", "sca", "ai_sast"] as const;+export type SemgrepPlatformProduct = (typeof SEMGREP_PLATFORM_PRODUCTS)[number];export const semgrepSelectionFormat = "semgrep-platform-selection/v1";+export function isSemgrepPlatformFormat(+ format: unknown,+): format is+ | typeof semgrepSelectionFormat+ | typeof semgrepPlatformFormat+ | typeof semgrepPlatformLegacyFormat {+ return (+ format === semgrepSelectionFormat ||+ format === semgrepPlatformFormat ||+ format === semgrepPlatformLegacyFormat+ );+}++function selectedProjectUrl(value: unknown, label: string) {+ return declaredScannerRepositoryUrl(value, label, "local");+}++/** Recover the native collection scope, including when every row was excluded. */+export function semgrepPlatformReportScope(+ input: ExternalFindings,+ provider?: string,+ references: readonly ExternalSourceRepository[] = [],+ isPlatform = (row: ExternalFinding) =>+ isSemgrepPlatformEvidence(row, provider),+) {+ const format = "sourceFormat" in input ? input.sourceFormat : undefined;+ if (+ "semgrepPlatformScope" in input &&+ input.semgrepPlatformScope !== undefined &&+ !isSemgrepPlatformFormat(format)+ )+ throw new Error(+ "A normalized Semgrep Platform report scope requires its source format.",+ );+ if (+ format === undefined &&+ provider === "semgrep" &&+ "sourceRepositoryUrl" in input &&+ input.sourceRepositoryUrl !== undefined &&+ (input.findings.length === 0 || input.findings.some(isPlatform))+ ) {+ // The object-row SDK retained only the binding on the envelope, including empty reports.+ return {+ url: hostedRepositoryUrl(input.sourceRepositoryUrl, "Semgrep Platform"),+ };+ }+ if (!isSemgrepPlatformFormat(format)) return;+ const scope = record(+ "semgrepPlatformScope" in input ? input.semgrepPlatformScope : undefined,+ "Normalized Semgrep report scope",+ );+ const readUrl =+ format === semgrepSelectionFormat+ ? selectedProjectUrl+ : hostedRepositoryUrl;+ const url = readUrl(+ "sourceRepositoryUrl" in input ? input.sourceRepositoryUrl : undefined,+ "Semgrep Platform",+ );+ if (format !== semgrepSelectionFormat && references.length)+ selectionRepository(url, references);++ return {+ format,+ deployment: requiredText(scope["deployment"], "Semgrep deployment"),+ projectId: savedPlatformId(+ requiredText(scope["projectId"], "Semgrep project ID"),+ ),+ ref: requiredText(scope["ref"], "Semgrep ref"),+ product: scopeProduct(scope["product"], format !== semgrepSelectionFormat),+ url,+ };+}++export function semgrepPlatformReportRepository(+ input: ExternalFindings,+ provider?: string,+ isPlatform?: (row: ExternalFinding) => boolean,+) {+ return semgrepPlatformReportScope(input, provider, [], isPlatform)?.url;+}+export interface SemgrepPlatformScope {deployment: string;project: { id: string; name: string; url: string };ref: string;- product: "sast";+ product: SemgrepPlatformProduct;}+type ResolvedScope = SemgrepPlatformScope & {+ sourceRepositoryUrl?: string;+ nativeProjectUrl?: string;+};+export interface SemgrepPlatformSelection extends SemgrepPlatformScope {+ product: "sast";format: typeof semgrepSelectionFormat;/** Each native finding is JSON text so numbers retain their exact wire values through replay. */findings: string[];}+// Raw JSON numbers are represented as JavaScript objects during lossless parsing.+export function responseRecord(value: unknown, label: string) {+ return record(+ hostedNumberToken(value) === undefined ? value : undefined,+ label,+ );+}+// These v1 Findings API response fields belong only to AI detections or Supply Chain.const nonSastFields = ["ai_impact",@@ -74,22 +198,18 @@ const wireJson = JSON as JSON & {isRawJSON(value: unknown): value is { rawJSON: string };};-// A retained JSON number is represented as an object in JavaScript.-function responseRecord(value: unknown, label: string) {- return record(wireJson.isRawJSON(value) ? undefined : value, label);-}--function sourceLine(value: unknown): number | null {+function sourceLine(value: unknown, coerceStrings: boolean): number | null {if (value == null) return null;- if (!wireJson.isRawJSON(value)) return position(value, "Semgrep source line");- const exact = canonicalNumber(value.rawJSON);+ const token = hostedNumberToken(value);+ // A long fraction can round to an integer if it is converted before checking its decimal value.+ if (token !== undefined)+ return position(Number(legacyDecimalInteger(token)), "Semgrep source line");return position(- /^\d+$/u.test(exact) ? Number(exact) : undefined,+ coerceStrings ? Number(semgrepPlatformId(value)) : value,"Semgrep source line",);}-/** Keep original number tokens, including adjacent int64 IDs above Number.MAX_SAFE_INTEGER. */export function parseSemgrepResponse(json: string): Record<string, unknown> {return responseRecord(JSON.parse(@@ -101,7 +221,9 @@ export function parseSemgrepResponse(json: string): Record<string, unknown> {);}-function platformId(value: unknown): string | undefined {+export function semgrepPlatformIdOrUndefined(+ value: unknown,+): string | undefined {let token: string;if (wireJson.isRawJSON(value)) token = value.rawJSON;else if (typeof value === "string" && /^[1-9][0-9]*$/u.test(value))@@ -117,8 +239,9 @@ function platformId(value: unknown): string | undefined {}export function semgrepPlatformId(value: unknown): string {- const id = platformId(value);- if (!id) throw new Error("Expected an exact, positive Semgrep Platform ID.");+ const id = semgrepPlatformIdOrUndefined(value);+ if (id === undefined)+ throw new Error("Expected an exact, positive Semgrep Platform ID.");return id;}@@ -132,29 +255,125 @@ function archivedPlatformId(value: unknown): string {: semgrepPlatformId(value);}+function savedPlatformId(value: unknown): string {+ if (typeof value !== "string") return semgrepPlatformId(value);+ const canonical = semgrepPlatformId(wireJson.rawJSON(value));+ if (canonical !== value && !/^[1-9][0-9]*$/u.test(value))+ throw new Error("Invalid saved Semgrep project ID.");+ return value;+}+function scopeOf(deployment: unknown,project: unknown,ref: unknown,-): SemgrepPlatformScope {+ readId = semgrepPlatformId,+ readUrl = hostedRepositoryUrl,+) {const row = responseRecord(project, "Semgrep project");- const id = semgrepPlatformId(row["id"]);+ const id = readId(row["id"]);return {deployment: requiredText(deployment, "Semgrep deployment"),project: {id: text(row["id"]) ?? id,name: requiredText(row["name"], "Semgrep project name"),- url: declaredScannerRepositoryUrl(- row["url"],- "Semgrep Platform",- "local",- ),+ url: readUrl(row["url"], "Semgrep Platform"),},ref: requiredText(ref, "Semgrep ref"),- product: "sast",+ product: "sast" as const,+ };+}++export function projectAliases(+ name: string,+ url: string,+ references: SemgrepRepositoryReference = [],+ earlyV1 = false,+) {+ const { hostname, pathname } = new URL(url);+ const path = pathname.slice(1).replace(/\/$/u, "");+ const decodePath = (decode: (value: string) => string) =>+ path+ .split("/")+ .map((segment) => {+ try {+ // Keep encoded separators within their original segment.+ const label = decode(segment);+ return /[/\\]/u.test(label) ? segment : label;+ } catch {+ return segment;+ }+ })+ .join("/");+ const { name: key, source } = repositoryContext(url, references);+ const paths = [path, decodePath(decodeURIComponent)];+ const publicHost = publicGitHost(gitServiceHostname(hostname));+ const knownGitSuffix =+ source.platform === "github" || source.platform === "gitlab" || publicHost;+ if (knownGitSuffix)+ paths.push(...paths.map((path) => path.replace(/\.git$/u, "")));+ const pathKeys = new Set(+ paths.flatMap((path) => [+ key(path),+ key(path.slice(path.lastIndexOf("/") + 1)),+ ]),+ );+ const shortName = name.slice(name.lastIndexOf("/") + 1);+ const historicalPaths: string[] = [];+ if (earlyV1) {+ // Older exports used decodeURI, which preserves escaped reserved delimiters.+ for (const historical of [path, decodePath(decodeURI)]) {+ if (!publicGitHost(hostname)) historicalPaths.push(historical);+ if (publicHost || source.platform === "github")+ historicalPaths.push(historical.replace(/\.git$/u, ""));+ }+ }+ const hasHistoricalPath = (label: string) =>+ historicalPaths.some(+ (path) =>+ label === path || label === path.slice(path.lastIndexOf("/") + 1),+ );+ return {+ hasHistoricalPath,+ has: (label: string) =>+ label === name ||+ label === shortName ||+ pathKeys.has(key(label)) ||+ hasHistoricalPath(label),};}+/** Older captures could derive a row label from their verified HTTP mapping for an SSH project. */+export function legacyProjectAliases(+ name: string,+ url: string,+ references: SemgrepRepositoryReference,+ mapping: string | undefined,+) {+ const native = projectAliases(name, url, references, true);+ const mapped =+ mapping && mapping !== url+ ? projectAliases(name, mapping, references, true)+ : undefined;+ return {+ has: (label: string) =>+ native.has(label) || !!mapped?.hasHistoricalPath(label),+ };+}++/** Compare HTTP origins canonically without folding paths on independent custom Git hosts. */+export function semgrepRepositoryUrlKey(value: string): string {+ return hostedRepositoryUrlKey(nativeHttp(value));+}++export type SemgrepRepositoryReference =+ readonly ExternalSourceRepository[] | ((url: string) => string);++/** A real HTTP URL can elide its default port. Git transport serializations retain explicit ports. */+function nativeHttp(url: string) {+ return URL.parse(url)?.href ?? url;+}+/** Readers may pass the SCM web link from the project response or its equivalent Git transport. */export function semgrepReferenceMatches(source: ExternalSourceRepository,@@ -170,22 +389,20 @@ export function semgrepReferenceMatches(if (hostedRepositoryMatches(source, url)) return true;try {// Serialize only a valid repository link. Git checkout URLs retain their original bytes.- const link = declaredScannerRepositoryUrl(url, "Semgrep", "local");+ const link = hostedRepositoryUrl(url, "Semgrep");return hostedRepositoryMatches(source, new URL(link).href);} catch {return false;}}-function repositoryContext(- scope: SemgrepPlatformScope,- references: readonly ExternalSourceRepository[] = [],-) {- // Apply HTTP serialization to native HTTP URLs only. Git's SSH port has its own meaning.- const http = (value: string) => URL.parse(value)?.href ?? value;- const projectUrl = http(scope.project.url);+export function semgrepPlatformRepositoryReference(+ url: string,+ references: readonly ExternalSourceRepository[],+): ExternalSourceRepository {+ const projectUrl = nativeHttp(url);const source: ExternalSourceRepository = { url: projectUrl };- const nativeHost = gitServiceHostname(new URL(projectUrl).hostname);+ const nativeHost = gitServiceHostname(URL.parse(url)?.hostname ?? "");const ownPlatformMatches = ({ url, platform }: ExternalSourceRepository) =>platform !== undefined &&semgrepReferenceMatches({ url: projectUrl, platform }, url);@@ -206,20 +423,87 @@ function repositoryContext("Conflicting SCM platforms for the selected Semgrep repository.",);}+ return source;+}++/** Keep provider transport spelling independently of its resolved HTTP repository. */+export function semgrepProjectUrlEvidence(+ raw: unknown,+ resolved: string | undefined,+ mapping: string | undefined,+) {+ if (resolved === undefined) return { sourceRepositoryUrl: mapping };+ if (typeof raw === "string" && raw !== resolved)+ return {+ nativeProjectUrl: raw,+ ...(mapping && { sourceRepositoryUrl: mapping }),+ };+ return {};+}++/** Interpret a project's native SSH spelling only when its Git host is known. */+export function semgrepNativeProjectUrl(+ value: unknown,+ references: SemgrepRepositoryReference,+) {+ if (value == null || value === "") return;+ const label = "Semgrep project repository";+ if (+ typeof value === "string" &&+ value.trim() === value &&+ typeof references !== "function" &&+ references.length+ ) {+ // Derive only a candidate from the native SSH spelling. The reader's Git fetch address must match.+ const candidate = normalizeHostedGitRepositoryUrl(value, undefined, true);+ if (+ candidate !== value &&+ references.some(+ ({ platform, url }) =>+ (platform === "github" || platform === "gitlab") &&+ semgrepReferenceMatches({ url: candidate, platform }, url),+ )+ )+ return hostedRepositoryUrl(candidate, label);+ }+ return hostedNativeRepositoryUrl(value, label);+}++function referenceRepositoryKey(+ references: readonly ExternalSourceRepository[],+) {+ return (url: string) => repositoryContext(url, references).key(url);+}++function repositoryContext(+ projectUrl: string,+ references: SemgrepRepositoryReference = [],+) {+ const source = semgrepPlatformRepositoryReference(+ projectUrl,+ typeof references === "function" ? [] : references,+ );const github = source.platform === "github";return {source,+ selectableProject: validScannerRepositoryUrl(projectUrl, "local"),key: (url: string) =>- hostedRepositoryUrlKey(http(url), github, source.platform === "gitlab"),- name: (value: string) => (github ? value.toLowerCase() : value),+ typeof references === "function"+ ? references(nativeHttp(url))+ : hostedRepositoryUrlKey(+ nativeHttp(url),+ github,+ source.platform === "gitlab",+ ),+ name: (name: string) => (github ? name.toLowerCase() : name),};}-function selectionRepository(- scope: SemgrepPlatformScope,+export function selectionRepository(+ projectUrl: string,references: readonly ExternalSourceRepository[] = [],) {- const repository = repositoryContext(scope, references);+ const repository = repositoryContext(projectUrl, references);if (!references.every(({ url }) =>semgrepReferenceMatches(repository.source, url),@@ -231,56 +515,150 @@ function selectionRepository(return repository;}-function checkRow(+function repositoryWithOnlyAlias(finding: Record<string, unknown>,- scope: SemgrepPlatformScope,- repository: Pick<ReturnType<typeof repositoryContext>, "name" | "key">,+ names: Pick<ReadonlySet<string>, "has">,+): string | undefined {+ const repo = record(+ finding["repository"] ?? {},+ "Semgrep finding repository",+ );+ const label = text(repo["name"]);+ return label && !names.has(label) && repo["id"] == null && !text(repo["url"])+ ? label+ : undefined;+}++function hasSemgrepScaEvidence(finding: Record<string, unknown>): boolean {+ return (+ finding["found_dependency"] != null ||+ finding["vulnerability_identifier"] != null+ );+}++/** Complete reports record the repository labels returned by the project-ID-scoped request. */+export function checkSemgrepPlatformRow(+ finding: Record<string, unknown>,+ scope: ResolvedScope,+ aliases?: Pick<ReadonlySet<string>, "has">,+ repository = repositoryContext(scope.project.url),+ readId = semgrepPlatformId,+ repositoryUrl = hostedNativeRepositoryUrl,capture = false,) {- semgrepPlatformId(finding["id"]);const repo = responseRecord(- finding["repository"],+ finding["repository"] ?? (aliases ? {} : undefined),"Semgrep finding repository",);- const repositoryId =- repo["id"] == null ? undefined : semgrepPlatformId(repo["id"]);- const url =- repo["url"] == null- ? null- : declaredScannerRepositoryUrl(repo["url"], "Semgrep finding", "local");+ const repositoryId = repo["id"] == null ? undefined : readId(repo["id"]);+ const hasUrl = repo["url"] != null && (!aliases || repo["url"] !== "");const name = repo["name"];- const rowName = typeof name === "string" ? repository.name(name) : null;const encodedPath = new URL(scope.project.url).pathname.replace(/^\/|\/$/gu,"",);+ const decodedPath = decodeURIComponent(encodedPath);// Archived captures may retain the encoded path spelling as their repository name.- const qualifiedName =- rowName?.includes("/") &&- (rowName === repository.name(decodeURIComponent(encodedPath)) ||- (!capture && rowName === repository.name(encodedPath)));+ const matchesQualifiedName = (normalize: typeof repository.name) => {+ const label = typeof name === "string" ? normalize(name) : null;+ return (+ !!label?.includes("/") &&+ (label === normalize(decodedPath) ||+ (!capture && label === normalize(encodedPath)))+ );+ };+ const selectionRepositoryMatches =+ hasUrl ||+ (repo["url"] == null &&+ repositoryId !== undefined &&+ matchesQualifiedName(repository.name));+ if (!aliases) {+ readId(finding["id"]);+ if (!selectionRepositoryMatches)+ throw new Error(+ "Semgrep finding repository does not match the selected project and ref.",+ );+ }if (- finding["ref"] !== scope.ref ||- (repositoryId !== undefined &&- repositoryId !== semgrepPlatformId(wireJson.rawJSON(scope.project.id))) ||- (url !== null- ? repository.key(url) !== repository.key(scope.project.url)- : repositoryId === undefined || !qualifiedName)+ repositoryId !== undefined &&+ repositoryId !== semgrepPlatformId(wireJson.rawJSON(scope.project.id)))throw new Error(- "Semgrep finding does not belong to the selected project and ref.",+ "Semgrep finding repository does not match the selected project and ref.",);+ const declaredProduct =+ scope.product === "sast" ? ["sast", "code"] : [scope.product];for (const product of [finding["issue_type"], finding["product"]]) {if (product != null &&(typeof product !== "string" ||- !["sast", "code"].includes(product.toLowerCase()))+ !declaredProduct.includes(product.toLowerCase())))- throw new Error("Select Semgrep Code (SAST) findings.");+ throw new Error(+ scope.product === "sast"+ ? "Select Semgrep Code (SAST) findings."+ : "Semgrep finding does not match the selected product.",+ );+ }+ if (+ (!aliases || finding["ref"] !== undefined) &&+ finding["ref"] !== scope.ref+ )+ throw new Error(+ "Semgrep finding does not belong to the selected project and ref.",+ );+ if (hasUrl) {+ const url = repositoryUrl(+ repo["url"],+ "Semgrep finding repository",+ repository.source.platform === "github" ||+ repository.source.platform === "gitlab"+ ? new URL(repository.source.url).hostname+ : undefined,+ );+ if (repository.key(url) !== repository.key(scope.project.url))+ throw new Error(+ "Semgrep finding repository does not match the selected project and ref.",+ );}- // Saved rows and normalized evidence have no original page to check.- if (!capture && identifiesNonSastProduct(finding))+ // A verified ID or URL can identify a bulk row whose optional display name is blank.+ const alias =+ typeof name === "string" && (repositoryId !== undefined || hasUrl)+ ? text(name)+ : name;+ if (+ aliases &&+ alias != null &&+ !aliases.has(requiredText(alias, "Semgrep repository name"))+ )+ throw new Error(+ "Semgrep finding repository does not match the selected project and ref.",+ );+ if (+ (scope.product === "sast" &&+ !capture &&+ identifiesNonSastProduct(finding)) ||+ (scope.product === "ai_sast" && hasSemgrepScaEvidence(finding))+ )throw new Error("Select Semgrep Code (SAST) findings.");+ return (+ scope.product === "sast" &&+ repository.selectableProject &&+ // A replayable selection requires a repository on the native project response.+ (scope.sourceRepositoryUrl === undefined ||+ scope.nativeProjectUrl !== undefined) &&+ finding["ref"] === scope.ref &&+ selectionRepositoryMatches &&+ [finding["id"], repo["id"]].every(+ (id) => id == null || semgrepPlatformIdOrUndefined(id) !== undefined,+ ) &&+ // Before a reader hint promotes a backlog row, check its complete selected projection.+ (!aliases ||+ hasUrl ||+ matchesQualifiedName(repositoryContext(scope.project.url).name) ||+ normalizePlatformRows([{ finding, selectable: true }], scope, "local")+ .excluded.length === 0)+ );}interface SemgrepSelectionInput {@@ -291,33 +669,40 @@ interface SemgrepSelectionInput {findingIds: readonly string[];}-function selectedRows(- options: SemgrepSelectionInput,- repositoryFor: (- scope: SemgrepPlatformScope,- ) => Pick<ReturnType<typeof repositoryContext>, "name" | "key">,-) {- const scope = scopeOf(- options.deployment,- parseSemgrepResponse(options.projectResponse)["project"],- options.ref,- );+export function requireSemgrepFullRef(ref: string) {// git-check-ref-format distinguishes literal branch/tag names from revision expressions.- const refParts = scope.ref.split("/");+ const refParts = ref.split("/");if (refParts[0] !== "refs" ||refParts.length < 2 ||refParts.some((part) => !part || part.startsWith(".") || part.endsWith(".lock"),) ||- scope.ref.endsWith(".") ||- scope.ref.includes("..") ||- scope.ref.includes("@{") ||- /[\u0000-\u0020\u007f~^:?*\[\\]/u.test(scope.ref)+ ref.endsWith(".") ||+ ref.includes("..") ||+ ref.includes("@{") ||+ /[\u0000-\u0020\u007f~^:?*\[\\]/u.test(ref))throw new Error("Use a fully qualified Semgrep ref such as refs/heads/topic.",);+}++function selectedRows(+ options: SemgrepSelectionInput,+ repositoryFor: (+ scope: SemgrepPlatformScope,+ ) => ReturnType<typeof repositoryContext>,+ repositoryUrl = hostedNativeRepositoryUrl,+) {+ const scope = scopeOf(+ options.deployment,+ parseSemgrepResponse(options.projectResponse)["project"],+ options.ref,+ semgrepPlatformId,+ selectedProjectUrl,+ );+ requireSemgrepFullRef(scope.ref);const repository = repositoryFor(scope);const wanted = new Set(options.findingIds.map((id) =>@@ -338,11 +723,19 @@ function selectedRows(const previousCount = selected.size;for (const finding of findings) {if (!isRecord(finding)) continue;- const id = platformId(finding["id"]);+ const id = semgrepPlatformIdOrUndefined(finding["id"]);if (!id || !wanted.has(id)) continue;if (selected.has(id))throw new Error(`Duplicate selected Semgrep finding ${id}.`);- checkRow(finding, scope, repository, true);+ checkSemgrepPlatformRow(+ finding,+ scope,+ undefined,+ repository,+ semgrepPlatformId,+ repositoryUrl,+ true,+ );selected.set(id, finding);}// The v1 findings endpoint returns a single product per response page.@@ -370,7 +763,7 @@ export function selectSemgrepPlatformFindings(},): SemgrepPlatformSelection {const { scope, rows } = selectedRows(options, (scope) =>- selectionRepository(scope, options.sourceRepositories),+ selectionRepository(scope.project.url, options.sourceRepositories),);return {format: semgrepSelectionFormat,@@ -385,154 +778,823 @@ export function normalizeSelectedSemgrepPlatformFindings(sourceRepositoryUrl: string;},): ExternalFindings {- const url = declaredScannerRepositoryUrl(- options.sourceRepositoryUrl,- "Semgrep",+ const url = hostedRepositoryUrl(options.sourceRepositoryUrl, "Semgrep");+ const { scope, rows } = selectedRows(+ options,+ (scope) => {+ if (scope.project.url !== url)+ throw new Error(+ "Selected Semgrep project does not match the operator's source repository URL.",+ );+ const exact = (value: string) => value;+ return {+ source: { url },+ selectableProject: true,+ key: exact,+ name: exact,+ };+ },+ hostedRepositoryUrl,+ );+ return normalizePlatformRows(+ rows.map((finding) => ({ finding, selectable: true })),+ scope,"local",);- const { scope, rows } = selectedRows(options, (scope) => {- if (scope.project.url !== url)- throw new Error(- "Selected Semgrep project does not match the operator's source repository URL.",- );- const exact = (value: string) => value;- return { key: exact, name: exact };- });- return normalizeSelectionRows(rows, scope, "local");}function sourceId(scope: SemgrepPlatformScope,finding: Record<string, unknown>,- idOf = semgrepPlatformId,+ readId = semgrepPlatformId,) {// Keep the same tuple for a selected import and a subsequent scoped Platform collection.const exact = (id: string) =>Number.isSafeInteger(Number(id)) ? Number(id) : id;return stableId("semgrep-platform", [scope.deployment,- exact(idOf(wireJson.rawJSON(scope.project.id))),+ exact(readId(wireJson.rawJSON(scope.project.id))),scope.product,scope.ref,- exact(idOf(finding["id"])),+ exact(readId(finding["id"])),]);}-function readScope(input: Record<string, unknown>) {- if (input["product"] !== "sast")- throw new Error("Select Semgrep Code (SAST) findings.");- const project = record(input["project"], "Semgrep project");- // The selector emits decimal strings; ordinary file JSON parsing would round numeric IDs.- const id = requiredText(project["id"], "Semgrep selected project ID");- const scope = scopeOf(- input["deployment"],- { ...project, id: wireJson.rawJSON(id) },- input["ref"],- );- if (scope.project.id !== id && !/^[1-9][0-9]*$/u.test(id))- throw new Error("Invalid saved Semgrep project ID.");- scope.project.id = id;- return scope;+function scopeProduct(native: unknown, complete: boolean) {+ const product = SEMGREP_PLATFORM_PRODUCTS.find((value) => value === native);+ if (!product || (!complete && product !== "sast"))+ throw new Error(+ "Select a supported Semgrep Platform product for this report.",+ );+ return product;}-const generatedId = /^semgrep-platform:[0-9a-f]{64}$/u;+function readScope(+ input: Record<string, unknown>,+ references: SemgrepRepositoryReference,+) {+ const complete =+ input["format"] === semgrepPlatformFormat ||+ input["format"] === semgrepPlatformLegacyFormat;+ const product = scopeProduct(input["product"], complete);+ const project = responseRecord(input["project"], "Semgrep project");+ if (+ input["format"] === semgrepPlatformFormat &&+ typeof project["id"] !== "string"+ )+ throw new Error(+ "A Semgrep Platform v2 project ID must be a positive decimal string.",+ );+ if (!complete) requiredText(project["id"], "Semgrep selected project ID");+ const mapping =+ complete && input["sourceRepositoryUrl"] !== undefined+ ? hostedRepositoryUrl(+ input["sourceRepositoryUrl"],+ "Semgrep source repository",+ )+ : undefined;+ // Captures expose an HTTP URL; stored occurrences retain the provider's SSH spelling.+ const projectUrl = project["url"];+ const suppliedNative = complete ? input["nativeProjectUrl"] : undefined;+ const raw =+ suppliedNative !== undefined+ ? requiredText(suppliedNative, "Semgrep native project URL")+ : complete &&+ typeof projectUrl === "string" &&+ !/^https?:\/\//iu.test(projectUrl)+ ? projectUrl+ : undefined;+ const native =+ raw === undefined ? undefined : semgrepNativeProjectUrl(raw, references);+ if (+ suppliedNative !== undefined &&+ (!native || native === raw || native !== projectUrl)+ )+ throw new Error(+ "Semgrep native project URL does not match its recorded HTTP repository.",+ );+ if (mapping && projectUrl != null) {+ const key = native && repositoryContext(native, references).key;+ if (key ? key(native!) !== key(mapping) : projectUrl !== mapping)+ throw new Error(+ "Semgrep project does not match its recorded source repository URL.",+ );+ }+ const scope = {+ ...scopeOf(+ input["deployment"],+ { ...project, url: native ?? mapping ?? project["url"] },+ input["ref"],+ savedPlatformId,+ complete ? hostedRepositoryUrl : selectedProjectUrl,+ ),+ ...(mapping && { sourceRepositoryUrl: mapping }),+ ...(native && { nativeProjectUrl: raw }),+ product,+ };+ const aliases = complete+ ? new Set(+ array(input["repositoryAliases"], "Semgrep repository aliases").map(+ (value) => requiredText(value, "Semgrep repository alias"),+ ),+ )+ : undefined;+ return { scope, aliases };+}++function matchesNativeInteger(+ value: unknown,+ expected: number | null | undefined,+): boolean {+ if (expected == null) return value == null;+ const token = hostedNumberToken(value);+ if (token === undefined) return value === expected;+ return expected === 0+ ? /^-?0(?:\.0+)?(?:e[+-]?\d+)?$/iu.test(token)+ : legacyDecimalInteger(token) === String(expected);+}-/** Recognize retained Platform evidence after an SDK caller projects away wrapper fields. */-export function isSemgrepSelectionEvidence(finding: ExternalFinding): boolean {+const generatedId = /^semgrep-platform:[0-9a-f]{64}$/u;+/** Current occurrences carry a provider-specific key; older v1 rows retain their native scope and finding. */+export function isSemgrepPlatformEvidence(+ finding: ExternalFinding,+ provider?: string,+): boolean {const data = finding.evidence?.source_data;+ if (generatedId.test(finding.source_finding_id)) return true;+ if (!data) return false;+ if (+ isSemgrepPlatformFormat(data["format"]) ||+ Object.hasOwn(data, "semgrepPlatformFindingJson")+ )+ return true;+ // Other scanners can use the same project and finding fields, including numeric IDs.+ if (provider !== "semgrep") return false;+ const project = data["project"];+ const row = data["finding"];return (- generatedId.test(finding.source_finding_id) ||- data?.["format"] === semgrepSelectionFormat ||- (data != null && Object.hasOwn(data, "semgrepPlatformFindingJson"))+ isRecord(row) &&+ "id" in row &&+ isRecord(project) &&+ project["id"] != null &&+ typeof project["name"] === "string" &&+ typeof data["ref"] === "string" &&+ typeof data["deployment"] === "string" &&+ SEMGREP_PLATFORM_PRODUCTS.some((product) => product === data["product"]));}-/** Recheck the source repository when an SDK caller supplies normalized evidence directly. */-export function semgrepSelectionRepository(- finding: ExternalFinding,- references: readonly ExternalSourceRepository[] = [],-): ExternalSourceRepository | undefined {- if (!isSemgrepSelectionEvidence(finding)) return;- const data = record(- finding.evidence.source_data,- "Semgrep Platform source data",+function upgradeOriginalSemgrepFinding(+ data: Record<string, unknown>,+ references: SemgrepRepositoryReference,+): Record<string, unknown> {+ const {+ numericFields: _witness,+ finding: original,+ ...context+ } = restoreLegacyHostedNumbers(data);+ const converted = upgradeSemgrepPlatformReport(+ { ...context, findings: [original], findingCount: 1 },+ undefined,+ typeof references === "function"+ ? references+ : referenceRepositoryKey(references),+ references,);- const scope = readScope(data);+ return {+ ...converted,+ semgrepPlatformFindingJson: array(+ converted["findings"],+ "Semgrep findings",+ )[0],+ };+}++/** Keep caller-supplied metadata while replacing the scanner's old wire representation. */+function canonicalSourceDataWithExtensions(+ retained: Record<string, unknown>,+ canonical: ReturnType<typeof platformSourceData>,+ original: boolean,+) {+ const extensions = (+ original: Record<string, unknown>,+ verified: Record<string, unknown>,+ replaced: string[] = [],+ ) =>+ Object.fromEntries(+ Object.entries(original).filter(+ ([key]) => !Object.hasOwn(verified, key) && !replaced.includes(key),+ ),+ );+ return {+ ...canonical,+ ...extensions(retained, canonical, [+ ...(original ? ["finding", "numericFields", "sourceRepositoryUrl"] : []),+ "nativeProjectUrl",+ "repositoryAliases",+ "repositoryWitnessJson",+ "idEncoding",+ ]),+ project: {+ ...canonical.project,+ ...extensions(+ record(retained["project"], "Semgrep project"),+ canonical.project,+ ),+ },+ };+}++function legacyWitnessKey(+ scope: SemgrepPlatformScope,+ projectUrlKey: string,+ label: string,+) {+ return JSON.stringify([+ scope.deployment,+ scope.project.id,+ scope.product,+ scope.ref,+ projectUrlKey,+ label,+ ]);+}++function nativeOccurrence(+ retained: Record<string, unknown>,+ references: SemgrepRepositoryReference,+) {+ let data = !isSemgrepPlatformFormat(retained["format"])+ ? {+ ...retained,+ format:+ (!Object.hasOwn(retained, "semgrepPlatformFindingJson") &&+ "finding" in retained) ||+ retained["idEncoding"] === "v1-decimal"+ ? semgrepPlatformLegacyFormat+ : "repositoryAliases" in retained+ ? semgrepPlatformFormat+ : semgrepSelectionFormat,+ }+ : retained;+ const legacy = data["format"] === semgrepPlatformLegacyFormat;+ const original = legacy && !Object.hasOwn(data, "semgrepPlatformFindingJson");+ if (original) data = upgradeOriginalSemgrepFinding(data, references);+ const { scope, aliases } = readScope(data, references);+ const repository = repositoryContext(scope.project.url, references);const row = parseSemgrepResponse(requiredText(data["semgrepPlatformFindingJson"], "Semgrep finding JSON"),);- const repository = repositoryContext(scope, references);- checkRow(row, scope, repository);+ return { data, legacy, original, scope, aliases, repository, row };+}++/** Original v1 occurrences could keep only the observed repository label on a row. */+export function semgrepLegacyRepositoryWitnesses(+ findings: readonly ExternalFinding[],+ provider: string,+ references: SemgrepRepositoryReference = [],+): ReadonlyMap<string, string> {+ const witnesses = new Map<string, string>();+ // Current occurrences carry their own witness. Only original rows need a sibling lookup.if (- generatedId.test(finding.source_finding_id) &&- finding.source_finding_id !== sourceId(scope, row) &&- finding.source_finding_id !== sourceId(scope, row, archivedPlatformId)+ !findings.some(({ evidence }) =>+ isRecord(evidence.source_data?.["finding"]),+ )+ )+ return witnesses;+ for (const finding of findings) {+ const data = finding.evidence.source_data;+ if (!data || !isSemgrepPlatformEvidence(finding, provider)) continue;+ const { scope, aliases, repository, row, legacy } = nativeOccurrence(+ data,+ references,+ );+ const repo = row["repository"];+ if (!isRecord(repo)) continue;+ const label = text(repo["name"]);+ if (!label || (repo["id"] == null && !text(repo["url"]))) continue;+ checkSemgrepPlatformRow(+ row,+ scope,+ aliases,+ repository,+ legacy ? semgrepV1Id : semgrepPlatformId,+ );+ witnesses.set(+ legacyWitnessKey(scope, repository.key(scope.project.url), label),+ JSON.stringify({ id: scope.project.id, name: label }),+ );+ }+ return witnesses;+}++/** Recheck the source repository when an SDK caller supplies normalized evidence directly. */+export function semgrepPlatformFindingRepository(+ finding: ExternalFinding,+ provider: string,+ references: SemgrepRepositoryReference = [],+ legacyWitnesses?: ReadonlyMap<string, string>,+): string | undefined {+ return semgrepPlatformFindingBinding(+ finding,+ provider,+ references,+ legacyWitnesses,+ )?.url;+}++export function platformLocationPath(value: unknown) {+ const path = text(value);+ const relative = relativePath(path);+ return relative && !relative.endsWith("/.") && repositoryFilePath(relative)+ ? path+ : null;+}++function platformLocation(+ location: Record<string, unknown>,+ product: SemgrepPlatformScope["product"],+ selectable: boolean,+ bulk?: { legacy: boolean },+) {+ const path = platformLocationPath(location["file_path"]);+ const oldPath = bulk?.legacy+ ? hostedRepositoryPath(location["file_path"])+ : null;+ const unprojected = { locations: [], endLine: null };+ if (!path && !oldPath) return unprojected;+ // V1 retained coordinates for unprojected paths without validating them.+ const newlyProjectable = !!bulk?.legacy && !oldPath;+ const coerce = newlyProjectable || (!!bulk && !bulk.legacy && !selectable);+ try {+ const line = sourceLine(location["line"], coerce);+ const endLine =+ line !== null && product !== "sca"+ ? sourceLine(location["end_line"], coerce)+ : null;+ if (bulk?.legacy && oldPath !== path) validateCodeLineRange(line, endLine);+ return path ? { locations: [{ path, line }], endLine } : unprojected;+ } catch (error) {+ if (newlyProjectable) return unprojected;+ throw error;+ }+}++function platformSeverity(value: unknown, selectable: boolean) {+ const severity = text(value)?.toLowerCase();+ return scannerSeverity(+ selectable && severity === "informational" ? null : severity,+ );+}++/** Upgrade only values produced by the original object-row reader; keep SDK-authored evidence. */+function migrateLegacyProjection(+ evidence: ExternalFinding["evidence"],+ row: Record<string, unknown>,+ scope: SemgrepPlatformScope,+ selectable: boolean,+ references: SemgrepRepositoryReference,+) {+ const severity = text(row["severity"]);+ const oldSeverity = scannerSeverity(+ severity === "informational" ? null : severity,+ );+ const upgradeSeverity =+ evidence.severity === oldSeverity &&+ oldSeverity !== scannerSeverity(severity?.toLowerCase());+ const location = isRecord(row["location"]) ? row["location"] : {};+ const oldPath = hostedRepositoryPath(location["file_path"]);+ const first = evidence.locations?.[0];+ // Only replace the exact location and end line produced by the original object-row reader.+ const oldLocation =+ oldPath !== platformLocationPath(location["file_path"]) &&+ (oldPath+ ? evidence.locations?.length === 1 &&+ first?.path === oldPath &&+ matchesNativeInteger(location["line"], first.line)+ : evidence.locations?.length === 0) &&+ matchesNativeInteger(+ oldPath && scope.product !== "sca" && first?.line != null+ ? location["end_line"]+ : null,+ evidence.details?.code?.end_line,+ );+ if (!upgradeSeverity && !oldLocation) return;+ const projected = normalizePlatformRows(+ [{ finding: row, selectable }],+ scope,+ "local",+ {+ legacy: true,+ projectNames: projectAliases(+ scope.project.name,+ scope.project.url,+ references,+ ),+ },+ ).findings[0]?.evidence;+ if (!projected) return;+ return {+ ...(upgradeSeverity && { severity: projected.severity }),+ ...(oldLocation && { locations: projected.locations }),+ ...(oldLocation &&+ evidence.details?.code &&+ projected.details?.code && {+ details: {+ ...evidence.details,+ code: {+ ...evidence.details.code,+ end_line: projected.details.code.end_line,+ },+ },+ }),+ };+}++function qualifiedBranch(ref: string) {+ return ref.startsWith("refs/") ? ref : `refs/heads/${ref}`;+}++function checkProjectedProduct(+ finding: ExternalFinding,+ product?: SemgrepPlatformProduct,+ native = false,+) {+ const kind = finding.evidence.details?.kind;+ if (+ (product === "sca" && kind === "sast") ||+ (native && (kind === "secret" || kind === "iac")))throw new Error(- "The generated Semgrep finding ID does not match its native occurrence.",+ "The projected finding kind does not match the Semgrep report product.",);+}++/** A marked report reserves the v1 finding's repository, ref and product for Semgrep scope. */+function hasRetainedSemgrepScope(finding: unknown): boolean {+ if (!isRecord(finding)) return false;+ const repository = finding["repository"];+ if (+ finding["ref"] !== undefined ||+ hasSemgrepScaEvidence(finding) ||+ (isRecord(repository) &&+ (repository["id"] != null ||+ !!text(repository["url"]) ||+ !!text(repository["name"])))+ )+ return true;+ return [finding["product"], finding["issue_type"]].some((value) => {+ if (typeof value !== "string") return false;+ const product = value.toLowerCase();+ return (+ product === "code" ||+ SEMGREP_PLATFORM_PRODUCTS.some((known) => known === product)+ );+ });+}++export function semgrepPlatformFindingBinding(+ finding: ExternalFinding,+ provider: string,+ references: SemgrepRepositoryReference = [],+ legacyWitnesses?: ReadonlyMap<string, string>,+ reportScope?: ReturnType<typeof semgrepPlatformReportScope>,+ projectedSources: readonly (+ { url?: string; branch?: string } | undefined+ )[] = [],+) {+ const retained = finding.evidence.source_data;+ if (!isSemgrepPlatformEvidence(finding, provider)) {+ if (+ provider === "semgrep" &&+ reportScope?.format !== undefined &&+ hasRetainedSemgrepScope(retained?.["finding"])+ )+ throw new Error(+ "Retained Semgrep finding scope requires the original collection scope in a marked Platform report.",+ );+ if (reportScope && reportScope.format !== semgrepSelectionFormat) {+ const source = repositoryContext(reportScope.url, references).source;+ const claims = [+ {+ url: finding.evidence.details?.repository?.url,+ branch: finding.evidence.branch,+ },+ ...projectedSources,+ ];+ if (+ claims.some(+ (claim) => claim?.url && !semgrepReferenceMatches(source, claim.url),+ )+ )+ throw new Error(+ "The projected repository does not match the Semgrep report repository.",+ );+ const ref = reportScope.ref && qualifiedBranch(reportScope.ref);+ if (+ ref &&+ claims.some(+ (claim) => claim?.branch && qualifiedBranch(claim.branch) !== ref,+ )+ )+ throw new Error(+ "The projected branch does not match the Semgrep report ref.",+ );+ checkProjectedProduct(finding, reportScope.product);+ }+ return;+ }+ if (!retained)+ throw new Error("Missing the original Semgrep finding evidence.");+ const { data, legacy, original, scope, aliases, repository, row } =+ nativeOccurrence(retained, references);+ checkProjectedProduct(finding, scope.product, true);+ if (+ reportScope?.deployment !== undefined &&+ (scope.deployment !== reportScope.deployment ||+ scope.project.id !== reportScope.projectId ||+ scope.ref !== reportScope.ref ||+ scope.product !== reportScope.product)+ )+ throw new Error(+ "The Semgrep report repository scope does not match the finding's deployment, project ID, ref, or product.",+ );++ const selectable = checkSemgrepPlatformRow(+ row,+ scope,+ aliases,+ repository,+ legacy ? semgrepV1Id : semgrepPlatformId,+ );+ if (reportScope?.format === semgrepSelectionFormat && !selectable)+ throw new Error(+ "Semgrep finding does not belong to the selected project and ref.",+ );+ let occurrenceId = legacy ? semgrepV1Id : semgrepPlatformId;+ const nativeId = sourceId(scope, row, occurrenceId);+ if (+ generatedId.test(finding.source_finding_id) &&+ finding.source_finding_id !== nativeId+ ) {+ if (+ legacy ||+ finding.source_finding_id !== sourceId(scope, row, archivedPlatformId)+ )+ throw new Error(+ "The generated Semgrep finding ID does not match its native occurrence.",+ );+ occurrenceId = archivedPlatformId;+ }+ const { name, url } = scope.project;+ let namedOnly =+ aliases && repositoryWithOnlyAlias(row, projectAliases(name, url));+ const raw = original+ ? namedOnly &&+ legacyWitnesses?.get(+ legacyWitnessKey(scope, repository.key(url), namedOnly),+ )+ : data["repositoryWitnessJson"];+ // Only rely on the reader's platform hint when there is no independent proof.+ if (+ namedOnly &&+ raw === undefined &&+ projectAliases(name, url, references).has(namedOnly)+ )+ namedOnly = undefined;+ const legacyPath =+ original &&+ namedOnly &&+ legacyProjectAliases(name, url, references, scope.sourceRepositoryUrl).has(+ namedOnly,+ );+ if (raw !== undefined || (namedOnly && !legacyPath)) {+ const label = text(+ record(row["repository"], "Semgrep finding repository")["name"],+ );+ const witness = parseSemgrepResponse(+ requiredText(raw, "Semgrep repository alias witness"),+ );+ if (+ !label ||+ witness["name"] !== label ||+ (witness["id"] == null && !text(witness["url"]))+ )+ throw new Error(+ "Semgrep repository alias lacks a matching project ID or URL.",+ );+ checkSemgrepPlatformRow(+ { repository: witness },+ scope,+ aliases ?? new Set([label]),+ repository,+ legacy+ ? semgrepV1Id+ : (id) => semgrepPlatformId(wireJson.rawJSON(savedPlatformId(id))),+ );+ }const claimed = finding.evidence.details?.repository?.url;if (finding.evidence.branch !== scope.ref ||- !claimed ||- repository.key(- declaredScannerRepositoryUrl(claimed, "Semgrep", "local"),- ) !== repository.key(scope.project.url)+ (!claimed && scope.product !== "sca") ||+ (!!claimed &&+ repository.key(+ hostedRepositoryUrl(claimed, "Semgrep evidence repository"),+ ) !== repository.key(scope.project.url)))throw new Error("The normalized finding does not match its original Semgrep repository and ref.",);- return repository.source;+ const canonical = platformSourceData(+ row,+ scope,+ selectable,+ aliases ? { legacy } : undefined,+ namedOnly,+ occurrenceId,+ );+ let migration = original+ ? migrateLegacyProjection(+ finding.evidence,+ row,+ scope,+ selectable,+ references,+ )+ : undefined;+ if (+ !original &&+ data["format"] === semgrepPlatformFormat &&+ canonical.format === semgrepSelectionFormat+ ) {+ const selectedSeverity = platformSeverity(row["severity"], true);+ if (+ selectedSeverity !== finding.evidence.severity &&+ finding.evidence.severity === platformSeverity(row["severity"], false)+ )+ migration = { severity: selectedSeverity };+ }+ // The original reader projected the HTTP mapping when the native project URL used SSH.+ const oldMappedUrl =+ original &&+ scope.product !== "sca" &&+ scope.nativeProjectUrl !== undefined &&+ claimed === scope.sourceRepositoryUrl &&+ claimed !== scope.project.url;+ const details = migration?.details ?? finding.evidence.details;+ return {+ url: scope.project.url,+ migration:+ oldMappedUrl && details?.repository+ ? {+ ...migration,+ details: {+ ...details,+ repository: { ...details.repository, url: scope.project.url },+ },+ }+ : migration,+ sourceData: canonicalSourceDataWithExtensions(+ retained,+ canonical,+ original,+ ),+ };}-export function normalizeSemgrepPlatformSelection(- input: Record<string, unknown>,- declaredUrl?: string,+/** Normalize a saved selection or a scoped Platform project export for local replay. */+export function normalizeSemgrepPlatformFindings(+ report: unknown,+ options: string | Partial<SemgrepImportOptions> = {},target: ExternalImportTarget = "local",- references: readonly ExternalSourceRepository[] = [],+ references: readonly ExternalSourceRepository[] = typeof options === "object"+ ? (options.sourceRepositories ?? [])+ : [],) {- const scope = readScope(input);- const repository = selectionRepository(scope, references);+ if (target !== "local")+ throw new Error("Semgrep Platform findings require a local import.");+ const declaredUrl =+ typeof options === "string" ? options : options.sourceRepositoryUrl;+ const saved = record(report, "Semgrep Platform report");+ const sourceFormat = saved["format"];+ if (!isSemgrepPlatformFormat(sourceFormat))+ throw new Error("Expected a Semgrep Platform selection or project export.");+ const legacy = sourceFormat === semgrepPlatformLegacyFormat;+ const readId = legacy ? semgrepV1Id : semgrepPlatformId;+ const input = legacy+ ? upgradeSemgrepPlatformReport(+ saved,+ declaredUrl,+ referenceRepositoryKey(references),+ references,+ )+ : saved;+ const { scope, aliases } = readScope(input, references);+ const repository = selectionRepository(scope.project.url, references);if (declaredUrl &&- repository.key(- declaredScannerRepositoryUrl(declaredUrl, "Semgrep", "local"),- ) !== repository.key(scope.project.url)+ repository.key(hostedRepositoryUrl(declaredUrl, "Semgrep")) !==+ repository.key(scope.project.url))throw new Error("Semgrep project does not match the declared source repository URL.",);- const selected = array(input["findings"], "Semgrep selected findings");- if (!selected.length)+ const verifiedLabels = new Set<string>();+ const projectNames = projectAliases(+ scope.project.name,+ scope.project.url,+ references,+ );+ const entries = array(input["findings"], "Semgrep Platform findings");+ if (!aliases && !entries.length)throw new Error("A saved Semgrep selection must contain at least one finding.",);- const rows = selected.map((value) => {+ const rows = entries.map((value) => {const raw = requiredText(value, "Semgrep finding JSON");const finding = parseSemgrepResponse(raw);- checkRow(finding, scope, repository);- return finding;+ const selectable = checkSemgrepPlatformRow(+ finding,+ scope,+ aliases,+ repository,+ readId,+ );+ if (aliases) {+ const repo = record(+ finding["repository"] ?? {},+ "Semgrep finding repository",+ );+ const label = text(repo["name"]);+ if (label && (repo["id"] != null || text(repo["url"])))+ verifiedLabels.add(label);+ }+ return { finding, selectable };});- return normalizeSelectionRows(rows, scope, target, archivedPlatformId);+ if (aliases && !matchesNativeInteger(input["findingCount"], rows.length))+ throw new Error(+ "Incomplete Semgrep Platform export: finding count does not match.",+ );+ if (aliases) {+ // v1 also accepted decodeURI path labels. Keep a witness for their current-format replay.+ const archiveNames = legacy+ ? legacyProjectAliases(+ scope.project.name,+ scope.project.url,+ references,+ scope.sourceRepositoryUrl,+ )+ : projectNames;+ for (const { finding } of rows) {+ const name = repositoryWithOnlyAlias(finding, archiveNames);+ if (name && !verifiedLabels.has(name))+ throw new Error(+ "Semgrep finding repository lacks a matching project name, ID or URL.",+ );+ }+ }+ const unhintedNames = projectAliases(scope.project.name, scope.project.url);+ const result = normalizePlatformRows(+ rows,+ scope,+ target,+ aliases+ ? {+ legacy,+ projectNames: {+ has: (name) =>+ (verifiedLabels.has(name) ? unhintedNames : projectNames).has(+ name,+ ),+ },+ }+ : undefined,+ aliases ? readId : archivedPlatformId,+ );+ return {+ ...result,+ sourceFormat,+ sourceRepositoryUrl: scope.project.url,+ semgrepPlatformScope: {+ deployment: scope.deployment,+ projectId: scope.project.id,+ ref: scope.ref,+ product: scope.product,+ },+ };}-function stringifySemgrepFinding(+export function stringifySemgrepFinding(finding: Record<string, unknown>,- idOf = semgrepPlatformId,+ idOf: (id: unknown) => string | undefined = semgrepPlatformIdOrUndefined,): string {- const repository = responseRecord(- finding["repository"],- "Semgrep finding repository",- );- const nativeIds = [finding["id"], repository["id"]];+ const repo = finding["repository"];+ const nativeIds = [finding["id"], isRecord(repo) ? repo["id"] : undefined];return JSON.stringify(finding, (_key, value: unknown) => {- if (wireJson.isRawJSON(value))- return wireJson.rawJSON(- nativeIds.includes(value)- ? idOf(value)- : canonicalNumber(value.rawJSON),- );- // Stable evidence only needs the retained row's object keys to be ordered.+ if (wireJson.isRawJSON(value)) {+ const id = nativeIds.includes(value) ? idOf(value) : undefined;+ return wireJson.rawJSON(id ?? canonicalNumber(value.rawJSON));+ }if (isRecord(value))return Object.fromEntries(Object.keys(value)@@ -543,15 +1605,76 @@ function stringifySemgrepFinding(});}-function normalizeSelectionRows(- rows: Record<string, unknown>[],- scope: SemgrepPlatformScope,- target: ExternalImportTarget,+function platformSourceData(+ finding: Record<string, unknown>,+ scope: ResolvedScope,+ selectable: boolean,+ bulk?: { legacy: boolean },+ namedOnly?: string | null,idOf = semgrepPlatformId,) {+ const repo = record(+ finding["repository"] ?? {},+ "Semgrep finding repository",+ );+ const label = text(repo["name"]);+ // Ordinary v1 and v2 rows share one stored representation on replay.+ // Preserve the legacy discriminator only when reopening the raw IDs needs it.+ const { nativeProjectUrl, ...evidenceScope } = scope;+ const nativeBulkScope =+ !selectable ||+ scope.sourceRepositoryUrl !== undefined ||+ nativeProjectUrl !== undefined;+ const needsLegacyId =+ bulk?.legacy &&+ [finding["id"], repo["id"]].some(+ (id) =>+ typeof id === "string" &&+ semgrepPlatformIdOrUndefined(id) === undefined,+ );+ // Native SAST rows with their own repository and ref replay identically in either import mode.+ const needsBulkScope = bulk && (nativeBulkScope || needsLegacyId);+ return {+ format: needsLegacyId+ ? semgrepPlatformLegacyFormat+ : needsBulkScope+ ? semgrepPlatformFormat+ : semgrepSelectionFormat,+ ...evidenceScope,+ project: {+ ...scope.project,+ url:+ nativeProjectUrl ??+ (scope.sourceRepositoryUrl ? null : scope.project.url),+ },+ ...(needsLegacyId && { idEncoding: "v1-decimal" }),+ ...(needsBulkScope && { repositoryAliases: label ? [label] : [] }),+ // Store the verified binding independently of the native fields retained on its proving row.+ ...(namedOnly && {+ repositoryWitnessJson: JSON.stringify({+ id: scope.project.id,+ name: namedOnly,+ }),+ }),+ semgrepPlatformFindingJson: stringifySemgrepFinding(finding, idOf),+ };+}++// Selected rows and complete captures share their evidence projection and identity tuple.+function normalizePlatformRows(+ rows: { finding: Record<string, unknown>; selectable: boolean }[],+ scope: ResolvedScope,+ target: ExternalImportTarget,+ bulk?: {+ legacy: boolean;+ projectNames: Pick<ReadonlySet<string>, "has">;+ },+ readId = bulk?.legacy ? semgrepV1Id : semgrepPlatformId,+) {+ const legacy = bulk?.legacy;return normalizeRecords(rows,- (finding) => {+ ({ finding, selectable }) => {const rule = responseRecord(finding["rule"] ?? {}, "Semgrep rule");const name = text(rule["name"]) ?? text(finding["rule_name"]);const description =@@ -560,23 +1683,79 @@ function normalizeSelectionRows(finding["location"] ?? {},"Semgrep location",);- const rawPath = text(location["file_path"]);- const relative = relativePath(rawPath);- const path =- relative && !relative.endsWith("/.") && repositoryFilePath(relative)- ? rawPath- : null;- const severity = text(finding["severity"])?.toLowerCase() ?? "";- const startLine = path ? sourceLine(location["line"]) : null;+ const { locations, endLine } = platformLocation(+ location,+ scope.product,+ selectable,+ bulk,+ );+ const namedOnly =+ bulk && repositoryWithOnlyAlias(finding, bulk.projectNames);+ const common = {+ description,+ severity: platformSeverity(finding["severity"], selectable),+ locations,+ branch: scope.ref,+ source_data: platformSourceData(+ finding,+ scope,+ selectable,+ bulk,+ namedOnly,+ readId,+ ),+ };+ const messageTitle =+ description ??+ (legacy || scope.product === "sast"+ ? null+ : `Semgrep finding ${readId(finding["id"])}`);+ if (scope.product === "sca") {+ const dependency = responseRecord(+ finding["found_dependency"] ?? {},+ "Semgrep found dependency",+ );+ const packages = [];+ if (dependency["package"] !== undefined) {+ const name = requiredText(+ dependency["package"],+ "Semgrep package name",+ );+ const fixes = array(+ finding["fix_recommendations"] ?? [],+ "Semgrep fix recommendations",+ );+ packages.push({+ name,+ ecosystem: text(dependency["ecosystem"]),+ installed_version: text(dependency["version"]),+ fixed_versions: strings(+ fixes.flatMap((fix) =>+ isRecord(fix) && fix["package"] === name+ ? [fix["version"]]+ : [],+ ),+ ),+ });+ }+ const advisory = text(finding["vulnerability_identifier"]);+ return validateExternalEvidence(+ {+ ...common,+ title: requiredText(+ name ?? advisory ?? packages[0]?.name ?? messageTitle,+ "Semgrep finding title",+ ),+ advisory_ids: advisory ? [advisory] : [],+ packages,+ },+ target,+ );+ }return validateExternalEvidence({- title: requiredText(name ?? description, "Semgrep finding title"),- description,- severity: ["low", "medium", "high", "critical"].includes(severity)- ? severity- : "unknown",- locations: path ? [{ path, line: startLine }] : [],- branch: scope.ref,+ ...common,+ title: requiredText(name ?? messageTitle, "Semgrep finding title"),details: {kind: "sast",repository: { url: scope.project.url },@@ -584,22 +1763,13 @@ function normalizeSelectionRows(rule: name ? { id: name } : null,source_status: text(finding["status"]),weakness_ids: weaknessIds(rule["cwe_names"]),- code: {- end_line:- startLine !== null ? sourceLine(location["end_line"]) : null,- },- },- source_data: {- format: semgrepSelectionFormat,- ...scope,- project: { ...scope.project },- semgrepPlatformFindingJson: stringifySemgrepFinding(finding, idOf),+ code: { end_line: endLine },},},target,);},- (finding) => sourceId(scope, finding, idOf),+ ({ finding }) => sourceId(scope, finding, readId),target,);}diff --git a/sdk/typescript/src/semgrep-platform-v1.ts b/sdk/typescript/src/semgrep-platform-v1.tsnew file mode 100644index 000000000..31f2a6303--- /dev/null+++ b/sdk/typescript/src/semgrep-platform-v1.ts@@ -0,0 +1,132 @@+import { hostedNumberToken } from "./hosted-scanner-http.js";+import { hostedRepositoryUrl } from "./hosted-scanner-http.js";+import {+ legacyDecimalInteger,+ restoreLegacyHostedNumbers,+} from "./hosted-scanner-v1.js";+import { array, record, requiredText, text } from "./scanner-import.js";+import {+ legacyProjectAliases,+ semgrepNativeProjectUrl,+ semgrepProjectUrlEvidence,+ type SemgrepRepositoryReference,+ semgrepPlatformId,+ semgrepRepositoryUrlKey,+} from "./semgrep-platform-findings.js";++/** Early v1 exports also admitted positive integral decimal spellings stored as text. */+export function semgrepV1Id(value: unknown): string {+ if (typeof value === "number" && Number.isSafeInteger(value))+ return semgrepPlatformId(String(value));+ const token = hostedNumberToken(value);+ if (token !== undefined && !/^[1-9][0-9]*$/u.test(token))+ return semgrepPlatformId(legacyDecimalInteger(token));+ return semgrepPlatformId(+ typeof value === "string" ? legacyDecimalInteger(value) : value,+ );+}++function isLossyNumber(value: unknown): boolean {+ return (+ typeof value === "number" &&+ (!Number.isFinite(value) ||+ (Number.isInteger(value) && !Number.isSafeInteger(value)))+ );+}++/** Translate a saved object-row export into lossless per-finding JSON for the current reader. */+export function upgradeSemgrepPlatformReport(+ input: Record<string, unknown>,+ declaredUrl?: string,+ repositoryKey = semgrepRepositoryUrlKey,+ references: SemgrepRepositoryReference = [],+): Record<string, unknown> {+ const report = restoreLegacyHostedNumbers(input);+ const project = record(report["project"], "Semgrep project");+ const name = requiredText(project["name"], "Semgrep project name");+ const mapping = report["sourceRepositoryUrl"] ?? declaredUrl;+ const bound =+ mapping === undefined+ ? undefined+ : hostedRepositoryUrl(mapping, "Semgrep source repository");+ const native = semgrepNativeProjectUrl(project["url"], references);+ const url = hostedRepositoryUrl(+ native ?? bound,+ "Semgrep project repository",+ );+ for (const other of [bound, declaredUrl]) {+ if (+ other !== undefined &&+ repositoryKey(hostedRepositoryUrl(other, "Semgrep repository")) !==+ repositoryKey(url)+ )+ throw new Error(+ "Semgrep project does not match the declared source repository URL.",+ );+ }+ // For a resolved native URL, retain only the mapping saved in the report.+ const urlEvidence = semgrepProjectUrlEvidence(+ project["url"],+ native,+ native === undefined || report["sourceRepositoryUrl"] != null+ ? bound+ : undefined,+ );+ const entries = array(report["findings"], "Semgrep findings");+ let aliases = report["repositoryAliases"];+ if (aliases === undefined) {+ const derived = legacyProjectAliases(+ name,+ url,+ references,+ urlEvidence.sourceRepositoryUrl,+ );+ const observed = new Set<string>();+ for (const entry of entries) {+ const row = record(entry, "Semgrep finding");+ const repo = record(+ row["repository"] ?? {},+ "Semgrep finding repository",+ );+ const label = text(repo["name"]);+ if (!label) continue;+ // Without the later alias list, each row must independently identify the project.+ if (+ repo["id"] == null &&+ (repo["url"] == null || repo["url"] === "") &&+ !derived.has(label)+ )+ throw new Error(+ "Semgrep finding repository does not match the selected project.",+ );+ observed.add(label);+ }+ aliases = Array.from(observed);+ }+ return {+ format: "semgrep-platform-findings/v2",+ deployment: report["deployment"],+ project: { id: semgrepV1Id(project["id"]), name, url },+ ...urlEvidence,+ product: report["product"],+ ref: report["ref"],+ findingCount: report["findingCount"],+ repositoryAliases: aliases,+ findings: entries.map((entry) => {+ const row = record(entry, "Semgrep finding");+ const repository = record(+ row["repository"] ?? {},+ "Semgrep finding repository",+ );+ if ([row["id"], repository["id"]].some(isLossyNumber))+ throw new Error("Expected an exact, positive Semgrep Platform ID.");+ return JSON.stringify(row, (_key, value: unknown) => {+ if (isLossyNumber(value))+ throw new Error(+ "Cannot retain an unsafe Semgrep finding number. Read the original Semgrep export to preserve its JSON numbers.",+ );+ return value;+ });+ }),+ };+}diff --git a/sdk/typescript/tests-ts/cli-external-imports-feature.test.ts b/sdk/typescript/tests-ts/cli-external-imports-feature.test.tsindex 12d2f0651..cb5448d6f 100644--- a/sdk/typescript/tests-ts/cli-external-imports-feature.test.ts+++ b/sdk/typescript/tests-ts/cli-external-imports-feature.test.ts@@ -35,6 +35,25 @@ const publishLocal = ["--yes",];+test("Semgrep import advertises its saved report format and native finding JSON strings", async () => {+ const cli = createCliTest(main);+ const code = await cli.runCli(+ ["import", "semgrep", "--schema", "--json"],+ dependencies({+ environment: { CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS: "1" },+ }),+ );+ expect(code).toBe(0);+ expect(JSON.parse(cli.stdout.text()).output).toMatchObject({+ properties: {+ format: { const: "semgrep-platform-findings/v2" },+ project: { properties: { id: { type: "string" } } },+ product: { enum: ["sast", "sca", "ai_sast"] },+ findings: { type: "array", items: { type: "string" } },+ },+ });+});+test("disabled commands distinguish discovery requests from filter values", async () => {const deps = dependencies({ environment: {} });for (const flag of ["--schema", "--llms-full", "--help"]) {diff --git a/sdk/typescript/tests-ts/external-findings-local-helpers.ts b/sdk/typescript/tests-ts/external-findings-local-helpers.tsindex bfb91e6eb..89c625713 100644--- a/sdk/typescript/tests-ts/external-findings-local-helpers.ts+++ b/sdk/typescript/tests-ts/external-findings-local-helpers.ts@@ -1,7 +1,10 @@import { expect } from "bun:test";+import type { ExternalFindings } from "../src/external-findings.js";+import { EXTERNAL_FINDINGS_PROVIDERS } from "../src/external-findings-read.js";import { prepareLocalExternalImport } from "../src/external-findings-import.js";import {listLocalExternalFindings,+ prepareNormalizedLocalImport,type StoredExternalFinding,} from "../src/external-findings-local.js";import type { ExternalPublicationOptions } from "../src/external-findings-publish.js";@@ -69,6 +72,10 @@ export async function localReportFixture(const fixture = await localFindingsFixture(checkout);const file = join(fixture.root, filename);const options = { ...source, repository: fixture.repository };+ const normalizedOptions = {+ ...options,+ provider: EXTERNAL_FINDINGS_PROVIDERS[source.provider],+ };const dependencies = { environment: fixture.environment };return {...fixture,@@ -81,10 +88,23 @@ export async function localReportFixture({ ...options, ...overrides },dependencies,),+ prepareNormalized: (input: ExternalFindings) =>+ prepareNormalizedLocalImport(input, normalizedOptions, dependencies),read: () => listLocalExternalFindings(options, dependencies),};}+export function isolatedGitReportFixture(+ filename: string,+ source: Omit<ExternalPublicationOptions, "repository">,+ checkout: Checkout = {},+) {+ return localReportFixture(filename, source, {+ ...checkout,+ isolatedGit: true,+ });+}+type LocalReportFixture = Awaited<ReturnType<typeof localReportFixture>>;export async function createAndReplayFinding(fixture: LocalReportFixture) {diff --git a/sdk/typescript/tests-ts/semgrep-findings-local.test.ts b/sdk/typescript/tests-ts/semgrep-findings-local.test.tsindex ba21d3aa4..360c8a993 100644--- a/sdk/typescript/tests-ts/semgrep-findings-local.test.ts+++ b/sdk/typescript/tests-ts/semgrep-findings-local.test.ts@@ -8,6 +8,7 @@ import {prepareNormalizedLocalImport,} from "../src/external-findings-local.js";import {+ normalizeSemgrepFindings,normalizeSemgrepSarif,readSemgrepFindings,} from "../src/semgrep-findings.js";@@ -19,6 +20,11 @@ import {semgrepJson,semgrepSarif,} from "./support/semgrep-import-fixtures.js";+import { normalizeOpenGrepFindings } from "../src/opengrep-findings.js";+import {+ opengrepJson,+ opengrepTraceJson,+} from "./support/opengrep-import-fixtures.js";import { temporaryDirectory } from "./support/temporary-directories.js";const repositoryUrl = "https://github.com/example/project";@@ -63,6 +69,40 @@ function report(return input;}+test("a marked Platform report accepts the Semgrep and OpenGrep readers' ordinary findings", async () => {+ await using fixture = await localReportFixture(+ "report.json",+ {+ provider: "semgrep",+ sourceKey: "example/topic",+ },+ { remote: repositoryUrl, isolatedGit: true },+ );+ const options = { sourceRepositoryUrl: repositoryUrl };+ for (const ordinary of [+ normalizeSemgrepFindings(semgrepJson(), options, "local"),+ normalizeSemgrepFindings(semgrepSarif(), options, "local"),+ normalizeOpenGrepFindings(opengrepJson(), options, "local"),+ normalizeOpenGrepFindings(opengrepTraceJson(), options, "local"),+ ]) {+ expect(ordinary.findings.length).toBeGreaterThan(0);+ const input = {+ ...ordinary,+ ...options,+ sourceFormat: "semgrep-platform-findings/v1",+ semgrepPlatformScope: {+ deployment: "example",+ projectId: "14",+ ref: "refs/heads/topic",+ product: "sast",+ },+ };+ expect((await fixture.prepareNormalized(input)).preview.findings).toEqual(+ ordinary.findings,+ );+ }+});+test("Semgrep file reader rejects malformed SARIF repository provenance", async () => {const directory = await temporaryDirectory("semgrep-reader-");try {diff --git a/sdk/typescript/tests-ts/semgrep-guardian-findings.test.ts b/sdk/typescript/tests-ts/semgrep-guardian-findings.test.tsnew file mode 100644index 000000000..06c8be1f4--- /dev/null+++ b/sdk/typescript/tests-ts/semgrep-guardian-findings.test.ts@@ -0,0 +1,225 @@+import { expect, mock, test } from "bun:test";+import { prepareNormalizedExternalPublication } from "../src/external-findings-publish.js";+import { collectSelectedSemgrepGuardianFindings } from "../src/semgrep-guardian-findings.js";+import { normalizeSemgrepFindings } from "../src/semgrep-findings.js";+import { collectSemgrepPlatformFindings } from "../src/semgrep-platform-collector.js";+import { isolatedGitReportFixture } from "./external-findings-local-helpers.js";++const sourceRepositoryUrl = "https://github.com/example/service";+const ref = "refs/heads/topic";+const project = "example/service";+const deployment = "example";+const id = "9007199254740993";+const selection = {+ request: {+ name: "get_semgrep_sast_findings" as const,+ arguments: {+ deployment_name: deployment,+ repository_name: project,+ ref,+ states: ["fixed"],+ },+ },+ sourceRepositoryUrl,+ findingIds: [id],+};+const row = {+ id,+ repository: { name: project },+ ref,+ issueType: "sast",+ rulePath: "example.rule",+ message: "Example match",+ status: "fixed",+ severity: "HIGH",+ filePath: "src/main.ts",+ line: 3,+};+const environment = { CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS: "1" };+const capture = {+ format: "semgrep-guardian-selection/v1",+ ...selection,+ structuredContent: { findings: [row] },+};++test("a signed-in Guardian selection and Web API collection keep independent rows on replay", async () => {+ const callTool = mock(async (_request: unknown) => ({+ structuredContent: { findings: [{ ...row, id: "9007199254740992" }, row] },+ }));+ const selected = await collectSelectedSemgrepGuardianFindings(selection, {+ callTool,+ environment,+ });+ expect(callTool.mock.calls).toEqual([[selection.request]]);+ expect(selected).toEqual(capture);++ await using fixture = await isolatedGitReportFixture(+ "report.json",+ { provider: "semgrep", sourceKey: "example/topic" },+ { remote: sourceRepositoryUrl },+ );+ await fixture.writeJson(selected);+ const preview = await fixture.prepare();+ expect(preview.preview.excluded).toEqual([]);+ expect(preview.preview.findings[0]!.evidence).toMatchObject({+ title: row.rulePath,+ severity: "high",+ branch: ref,+ locations: [{ path: row.filePath, line: 3 }],+ source_data: { finding: row },+ });+ expect(await fixture.read()).toHaveLength(0);+ expect((await preview.import()).counts.created).toBe(1);++ // Guardian returns a string; the Web API can send the same digits as a JSON integer.+ const webId = (JSON as JSON & { rawJSON(value: string): unknown }).rawJSON(+ id,+ );+ const web = await collectSemgrepPlatformFindings(+ { deployment, project, ref },+ {+ environment: { ...environment, SEMGREP_APP_TOKEN: "synthetic" },+ fetch: async (url) =>+ Response.json(+ url.pathname.endsWith("/findings")+ ? {+ findings: [+ {+ id: webId,+ repository: {+ id: 4,+ name: project,+ url: sourceRepositoryUrl,+ },+ ref,+ rule: {+ name: row.rulePath,+ message: row.message,+ cwe_names: ["CWE-79"],+ },+ location: { file_path: row.filePath, line: 3, end_line: 5 },+ },+ ],+ }+ : { project: { id: 4, name: project, url: sourceRepositoryUrl } },+ ),+ },+ );+ await fixture.writeJson(web);+ expect((await (await fixture.prepare()).import()).counts.created).toBe(1);+ await fixture.writeJson(selected);+ expect((await (await fixture.prepare()).import()).counts.unchanged).toBe(1);+ const stored = await fixture.read();+ expect(stored).toHaveLength(2);+ const platform = stored.find((item) =>+ item.sourceFindingId.startsWith("semgrep-platform:"),+ );+ expect(+ platform?.evidence.source_data?.["semgrepPlatformFindingJson"],+ ).toContain(`"id":${id},`);+ expect(platform?.evidence.details?.code?.end_line).toBe(5);+ expect(stored.every((item) => item.version === 1)).toBe(true);+});++test("the capture reader selects exact IDs and rejects missing, ambiguous or conflicting evidence", () => {+ function read(findings: unknown[]) {+ return normalizeSemgrepFindings(+ { ...capture, structuredContent: { findings } },+ {},+ "local",+ );+ }+ expect(read([row, { ...row, id: "other", ref: "unrelated" }]).read).toBe(1);+ expect(() => read([{ ...row, id: "9007199254740992" }])).toThrow(+ /did not return/,+ );+ expect(() => read([row, row])).toThrow(/duplicate/);+ expect(() => read([{ ...row, id: "0" + id }])).toThrow(/did not return/);+ expect(() =>+ read([{ ...row, repository: { name: "other/project" } }]),+ ).toThrow(/repository and ref/);+ expect(() => read([{ ...row, ref: "refs/tags/topic" }])).toThrow(+ /repository and ref/,+ );+ expect(() => read([{ ...row, issueType: "secrets" }])).toThrow(/product/);+});++test("Guardian Supply Chain retains its summary and checks the operator's checkout mapping", async () => {+ const sca = {+ ...capture,+ request: {+ ...selection.request,+ name: "get_semgrep_supply_chain_findings",+ },+ structuredContent: {+ findings: [+ { ...row, issueType: "ISSUE_TYPE_SCA", filePath: "../outside" },+ ],+ },+ };+ const normalized = normalizeSemgrepFindings(sca, {}, "local");+ expect(() => normalizeSemgrepFindings(sca)).toThrow(/local workbench/);+ await expect(+ prepareNormalizedExternalPublication(+ {+ ...normalized,+ report: {},+ findings: [{ ...normalized.findings[0]!, source_finding_id: "custom" }],+ },+ { repository: project, provider: "semgrep", sourceKey: "example/topic" },+ {+ environment,+ credentials: async () => {+ throw new Error("Unexpected credential lookup");+ },+ },+ ),+ ).rejects.toThrow(/local import/);+ expect(normalized.findings[0]!.evidence).toMatchObject({+ locations: [],+ source_data: { finding: sca.structuredContent.findings[0] },+ });+ expect(normalized.findings[0]!.evidence.packages ?? []).toEqual([]);+ expect(normalized.findings[0]!.source_finding_id).not.toBe(+ normalizeSemgrepFindings(capture, {}, "local").findings[0]!+ .source_finding_id,+ );+ const other = "https://github.com/other/service";+ expect(() =>+ normalizeSemgrepFindings(sca, { sourceRepositoryUrl: other }, "local"),+ ).toThrow(/declared source/);+ await using fixture = await isolatedGitReportFixture(+ "guardian.json",+ { provider: "semgrep", sourceKey: "test" },+ { remote: other },+ );+ await fixture.writeJson(sca);+ await expect(fixture.prepare()).rejects.toThrow(/configured remote/);+ expect(await fixture.read()).toHaveLength(0);+});++test("empty selections and disabled imports do not call Guardian; tool errors retain their message", async () => {+ const callTool = mock(async () => ({+ isError: true,+ content: [{ type: "text", text: "Guardian login expired" }],+ }));+ await expect(+ collectSelectedSemgrepGuardianFindings(+ { ...selection, findingIds: [] },+ { callTool, environment },+ ),+ ).rejects.toThrow(/at least one/);+ await expect(+ collectSelectedSemgrepGuardianFindings(selection, {+ callTool,+ environment: {},+ }),+ ).rejects.toThrow(/disabled/);+ expect(callTool).not.toHaveBeenCalled();+ await expect(+ collectSelectedSemgrepGuardianFindings(selection, {+ callTool,+ environment,+ }),+ ).rejects.toThrow("Guardian login expired");+});diff --git a/sdk/typescript/tests-ts/semgrep-platform-collector.test.ts b/sdk/typescript/tests-ts/semgrep-platform-collector.test.tsnew file mode 100644index 000000000..eb1ed7469--- /dev/null+++ b/sdk/typescript/tests-ts/semgrep-platform-collector.test.ts@@ -0,0 +1,2114 @@+import { expect, mock, test } from "bun:test";+import { execFileSync } from "node:child_process";+import { parse as parseYaml } from "yaml";+import { collectSemgrepPlatformFindings } from "../src/semgrep-platform-collector.js";+import { main } from "../src/cli.js";+import {+ isSemgrepPlatformEvidence,+ normalizeSelectedSemgrepPlatformFindings,+ normalizeSemgrepPlatformFindings,+ selectSemgrepPlatformFindings,+ semgrepPlatformFindingBinding,+ semgrepPlatformFindingRepository,+} from "../src/semgrep-platform-findings.js";+import { prepareNormalizedLocalImport } from "../src/external-findings-local.js";+import { hostedRepositoryUrlKey } from "../src/hosted-git-repository.js";+import { normalizeSemgrepFindings } from "../src/semgrep-findings.js";+import { dependencies } from "./cli-fixtures.js";+import { createCliTest } from "./support/cli-run.js";+import { semgrepSarif } from "./support/semgrep-import-fixtures.js";+import { isolatedGitReportFixture as localReportFixture } from "./external-findings-local-helpers.js";++const url = "https://github.com/example/service";+const project = { name: "example/service", id: 77, url };+const options = {+ project: project.name,+ deployment: "example",+ ref: "refs/heads/topic",+};+const environment = {+ CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS: "1",+ SEMGREP_APP_TOKEN: "synthetic",+};+const fullPage = Array.from({ length: 3000 }, (_, index) => ({+ id: index + 1,+}));++/** Serve a project lookup followed by consecutive findings responses. */+function responses(...pages: Response[]) {+ const pending = [Response.json({ project }), ...pages];+ return {+ environment,+ fetch: async () => {+ const next = pending.shift();+ if (!next) throw new Error("Unexpected additional request");+ return next;+ },+ };+}++test.each(["%23", "%3F"])(+ "a Git project path containing %s stays in the complete report",+ async (encoded) => {+ const native = {+ ...project,+ url: `https://git.example.test/team/tool${encoded}one`,+ };+ const numeric = {+ id: 23,+ ref: options.ref,+ repository: { url: native.url },+ rule_name: "example.rule",+ severity: "informational",+ location: { file_path: "src/main.ts", line: 2 },+ };+ const quoted = {+ ...numeric,+ id: 24,+ location: { ...numeric.location, line: "2" },+ };+ const rows = [numeric, quoted];+ const report = await collectSemgrepPlatformFindings(options, {+ environment,+ fetch: async (endpoint) =>+ Response.json(+ endpoint.pathname.endsWith("/findings")+ ? { findings: rows }+ : { project: native },+ ),+ });+ const input = {+ ...options,+ projectResponse: JSON.stringify({ project: native }),+ findingsResponses: [JSON.stringify({ findings: rows })],+ findingIds: ["23", "24"],+ };+ expect(() => selectSemgrepPlatformFindings(input)).toThrow(+ /repository path/,+ );+ expect(() =>+ normalizeSelectedSemgrepPlatformFindings({+ ...input,+ sourceRepositoryUrl: native.url,+ }),+ ).toThrow(/repository path/);+ expect(() =>+ normalizeSemgrepPlatformFindings({+ ...report,+ format: "semgrep-platform-selection/v1",+ }),+ ).toThrow(/repository path/);+ const batch = normalizeSemgrepPlatformFindings(report);+ expect(batch.excluded).toEqual([]);+ expect(batch.findings).toHaveLength(2);+ for (const row of batch.findings) {+ expect(row.evidence).toMatchObject({+ severity: "informational",+ locations: [{ path: "src/main.ts", line: 2 }],+ source_data: { format: report.format },+ });+ expect(semgrepPlatformFindingRepository(row, "semgrep")).toBe(native.url);+ }+ const legacy = normalizeSemgrepPlatformFindings({+ ...report,+ format: "semgrep-platform-findings/v1",+ project: native,+ findings: rows,+ });+ expect(legacy.excluded.map((item) => item.position)).toEqual([2]);+ expect(legacy.findings).toEqual([batch.findings[0]!]);+ },+);++test("a supplied empty repository URL remains bulk-only on capture and replay", async () => {+ const row = {+ id: 12,+ ref: options.ref,+ rule_name: "demo",+ repository: { ...project, url: "" },+ };+ const page = { findings: [row] };+ const selection = {+ ...options,+ sourceRepositoryUrl: url,+ projectResponse: JSON.stringify({ project }),+ findingsResponses: [JSON.stringify(page)],+ findingIds: ["12"],+ };+ expect(() => selectSemgrepPlatformFindings(selection)).toThrow(/repository/);+ expect(() => normalizeSelectedSemgrepPlatformFindings(selection)).toThrow(+ /repository/,+ );+ const bulk = await collectSemgrepPlatformFindings(+ options,+ responses(Response.json(page)),+ );+ expect(() =>+ normalizeSemgrepPlatformFindings({+ ...bulk,+ format: "semgrep-platform-selection/v1",+ }),+ ).toThrow(/repository/);+ for (const input of [+ bulk,+ { ...bulk, format: "semgrep-platform-findings/v1", findings: [row] },+ ]) {+ const [finding] = normalizeSemgrepPlatformFindings(input).findings;+ expect(finding!.evidence.source_data?.["format"]).toBe(bulk.format);+ expect(semgrepPlatformFindingRepository(finding!, "semgrep")).toBe(url);+ }+});++test("an opaque bulk finding ID still requires the original native occurrence ID", async () => {+ const report = await collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({ findings: [{ id: 9, rule_name: "example.rule" }] }),+ ),+ );+ const row = normalizeSemgrepFindings(report, {}, "local").findings[0]!;+ row.source_finding_id = "assigned-id";+ expect(semgrepPlatformFindingRepository(row, "semgrep")).toBe(url);+ row.evidence.source_data!["semgrepPlatformFindingJson"] = "{}";+ expect(() => semgrepPlatformFindingRepository(row, "semgrep")).toThrow(+ /exact, positive Semgrep Platform ID/,+ );+});++test("integer-valued native IDs replay identically through selected and bulk imports", async () => {+ const page = `{"findings":[{"id":1e1,"repository":{"id":77.0,"url":"${url}"},"ref":"${options.ref}","rule_name":"example.rule"}]}`;+ const input = {+ ...options,+ projectResponse: JSON.stringify({ project }),+ findingsResponses: [page],+ findingIds: ["10"],+ sourceRepositoryUrl: url,+ };+ const direct = normalizeSelectedSemgrepPlatformFindings(input);+ expect(direct.excluded).toEqual([]);+ expect(direct.findings).toHaveLength(1);+ const finding = direct.findings[0]!;+ expect(finding.evidence.source_data).toMatchObject({+ format: "semgrep-platform-selection/v1",+ semgrepPlatformFindingJson: JSON.stringify({+ id: 10,+ ref: options.ref,+ repository: { id: 77, url },+ rule_name: "example.rule",+ }),+ });+ const selected = selectSemgrepPlatformFindings(input);+ const bulk = await collectSemgrepPlatformFindings(+ options,+ responses(new Response(page)),+ );+ for (const saved of [selected, bulk]) {+ const replay = normalizeSemgrepFindings(saved, {}, "local");+ expect(replay.excluded).toEqual([]);+ expect(replay.findings).toEqual(direct.findings);+ }+ expect(semgrepPlatformFindingRepository(finding, "semgrep")).toBe(url);+});++test("a retagged Semgrep row still requires its provider after assigning an opaque ID", async () => {+ const report = await collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({+ findings: [+ {+ id: 9,+ ref: options.ref,+ repository: project,+ rule_name: "example.rule",+ },+ ],+ }),+ ),+ );+ const normalized = normalizeSemgrepFindings(report, {}, "local");+ const row = normalized.findings[0]!;+ row.source_finding_id = "assigned-id";+ row.evidence.source_data!["format"] = "snyk-rest-issues/v2";+ const source = { provider: "wiz" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("findings.json", source, {+ remote: url,+ });+ await expect(fixture.prepareNormalized(normalized)).rejects.toThrow(+ /semgrep provider/i,+ );++ row.evidence.source_data = {+ format: "snyk-rest-issues/v2",+ projectJson: "{}",+ targetJson: "{}",+ issueJson: '{"id":"native-issue","type":"issue"}',+ };+ expect(isSemgrepPlatformEvidence(row, "snyk")).toBe(false);+});++test("a normalized Platform report binds native rows even when both projects have checkout remotes", async () => {+ const report = await collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({ findings: [{ id: 9, rule_name: "example.rule" }] }),+ ),+ );+ const upstream = "https://git.example.test/service/upstream";+ const fork = "https://git.example.test/service/fork";+ const normalize = (+ url: string,+ id: string,+ scope: Partial<Pick<typeof report, "deployment" | "product" | "ref">> = {},+ ) =>+ normalizeSemgrepPlatformFindings({+ ...report,+ ...scope,+ project: { ...report.project, id, url },+ });+ const upstreamReport = normalize(upstream, "77");+ const forkReport = normalize(fork, "88");+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("findings.json", source, {+ remote: upstream,+ });+ execFileSync(+ "git",+ ["-C", fixture.repository, "remote", "add", "fork", fork],+ {+ env: fixture.environment,+ },+ );+ const prepare = fixture.prepareNormalized;+ const nativeProject = { ...report.project, url: upstream };+ const row = {+ id: 9,+ rule_name: "example.rule",+ ref: report.ref,+ repository: { id: nativeProject.id, url: nativeProject.url },+ };+ const selection = normalizeSemgrepPlatformFindings(+ selectSemgrepPlatformFindings({+ deployment: report.deployment,+ ref: report.ref,+ projectResponse: JSON.stringify({ project: nativeProject }),+ findingsResponses: JSON.stringify({ findings: [row] }),+ findingIds: ["9"],+ }),+ );+ const strong = normalizeSemgrepPlatformFindings({+ ...report,+ project: nativeProject,+ findings: [JSON.stringify(row)],+ });+ expect((await prepare(upstreamReport)).preview.findings).toHaveLength(1);+ expect(+ (await prepare({ ...selection, findings: strong.findings })).preview+ .findings,+ ).toEqual(selection.findings);+ await expect(+ prepare({ ...selection, findings: upstreamReport.findings }),+ ).rejects.toThrow(/selected project and ref/i);++ await expect(+ prepare({ ...upstreamReport, findings: forkReport.findings }),+ ).rejects.toThrow(/report repository/i);+ for (const foreign of [+ normalize(upstream, "88"),+ normalize(upstream, "77", { deployment: "other" }),+ normalize(upstream, "77", { ref: "refs/heads/other" }),+ normalize(upstream, "77", { product: "ai_sast" }),+ ]) {+ await expect(+ prepare({+ ...upstreamReport,+ read: 2,+ findings: [...upstreamReport.findings, ...foreign.findings],+ }),+ ).rejects.toThrow(/scope|project|deployment|product|ref/i);+ }++ const incomplete = { ...upstreamReport, sourceFormat: undefined };+ await expect(prepare(incomplete)).rejects.toThrow(/scope.*source format/i);++ const ordinary = structuredClone(upstreamReport.findings[0]!);+ ordinary.source_finding_id = "ordinary";+ delete ordinary.evidence.source_data;+ ordinary.evidence.branch = "topic";+ await expect(+ prepareNormalizedLocalImport(+ { ...incomplete, findings: [ordinary] },+ { ...source, provider: "wiz", repository: fixture.repository },+ { environment: fixture.environment },+ ),+ ).rejects.toThrow(/scope.*source format/i);++ expect(+ (+ await prepare({+ ...upstreamReport,+ read: 2,+ findings: [...upstreamReport.findings, ordinary],+ })+ ).preview.findings,+ ).toHaveLength(2);+ const matching = normalizeSemgrepFindings(+ semgrepSarif(),+ { sourceRepositoryUrl: upstream },+ "local",+ ).findings[0]!;+ const combined = {+ ...upstreamReport,+ read: 2,+ findings: [...upstreamReport.findings, matching],+ };+ await expect(+ prepareNormalizedLocalImport(+ combined,+ { ...source, repository: fixture.repository },+ {+ environment: fixture.environment,+ sourceRepositories: [{ url: upstream }, { url: fork }],+ },+ ),+ ).rejects.toThrow(/source repository.*selected Semgrep project/i);+ const supplyChain = normalize(upstream, "77", { product: "sca" });+ for (const product of ["sast", "ai_sast", "sca"] as const) {+ const branded = normalize(upstream, "77", { product }).findings[0]!;+ const batch = { read: 1, excluded: [], findings: [branded] };+ for (const kind of ["secret", "iac"] as const) {+ branded.evidence.details = { kind, repository: { url: upstream } };+ await expect(prepare(batch)).rejects.toThrow(/product/);+ }+ branded.evidence.advisory_ids = ["CVE-2025-0001"];+ branded.evidence.details = {+ kind: "advisory",+ repository: { url: upstream },+ advisory: { source: "repository" },+ };+ expect((await prepare(batch)).preview.findings[0]!.evidence).toMatchObject({+ advisory_ids: branded.evidence.advisory_ids,+ details: branded.evidence.details,+ });+ }+ const genericSecret = structuredClone(ordinary);+ genericSecret.evidence.details = {+ kind: "secret",+ repository: { url: upstream },+ };+ expect(+ (+ await prepare({+ ...supplyChain,+ read: 2,+ findings: [...supplyChain.findings, genericSecret],+ })+ ).preview.findings,+ ).toHaveLength(2);+ const nativeAdvisory = structuredClone(supplyChain.findings[0]!);+ nativeAdvisory.evidence.details = matching.evidence.details;+ await expect(+ prepare({ read: 1, excluded: [], findings: [nativeAdvisory] }),+ ).rejects.toThrow(/product/);++ await expect(+ prepare({ ...supplyChain, findings: [matching] }),+ ).rejects.toThrow(/product/);+ for (const claim of [{ url: fork }, { branch: "refs/heads/other" }]) {+ const projected = structuredClone(ordinary);+ if (claim.url) projected.evidence.details!.repository!.url = claim.url;+ if (claim.branch) projected.evidence.branch = claim.branch;+ const mixed = {+ read: 2,+ excluded: [],+ findings: [...upstreamReport.findings, projected],+ };+ expect((await prepare(mixed)).preview.findings).toHaveLength(2);+ await expect(prepare({ ...upstreamReport, ...mixed })).rejects.toThrow(+ /repository|scope|branch|ref/i,+ );+ }+ const retainedBranch = (branch: string) => {+ const sarif = semgrepSarif();+ Object.assign(sarif.runs[0]!, {+ versionControlProvenance: [{ repositoryUri: upstream, branch }],+ });+ return normalizeSemgrepFindings(+ sarif,+ { sourceRepositoryUrl: upstream },+ "local",+ ).findings[0]!;+ };+ const sarifRow = retainedBranch("topic");+ expect(sarifRow.evidence.branch ?? null).toBeNull();+ expect(+ (await prepare({ ...upstreamReport, findings: [sarifRow] })).preview+ .findings,+ ).toHaveLength(1);+ const tagRow = retainedBranch("refs/tags/topic");+ await expect(+ prepare({ ...upstreamReport, findings: [tagRow] }),+ ).rejects.toThrow(/branch.*ref/);+ await expect(+ prepare({ ...upstreamReport, findings: [retainedBranch("main")] }),+ ).rejects.toThrow(/branch.*ref/);+ const tagScope = normalize(upstream, "77", { ref: "refs/tags/topic" });+ expect(+ (await prepare({ ...tagScope, findings: [tagRow] })).preview.findings,+ ).toHaveLength(1);+ expect(+ (await prepare({ read: 1, excluded: [], findings: [tagRow] })).preview+ .findings,+ ).toHaveLength(1);+ const duck = structuredClone(ordinary);+ duck.source_finding_id = `blackduck-bom:${"a".repeat(64)}`;+ duck.evidence.source_data = { sourceRepositoryUrl: fork };+ const nativeSarif = semgrepSarif();+ Object.assign(nativeSarif.runs[0]!, {+ versionControlProvenance: [{ repositoryUri: fork }],+ });+ const sarif = normalizeSemgrepFindings(+ nativeSarif,+ { sourceRepositoryUrl: fork },+ "local",+ ).findings[0]!;+ for (const projected of [duck, sarif]) {+ delete projected.evidence.details;+ await expect(+ prepare({ ...upstreamReport, findings: [projected] }),+ ).rejects.toThrow(/report repository/i);+ }+ const batch = {+ read: 2,+ excluded: [],+ findings: [...upstreamReport.findings, ...forkReport.findings],+ };+ expect((await prepare(batch)).preview.findings).toHaveLength(2);+});++test("a marked Platform report requires scope for caller-managed partial v1 findings", async () => {+ const native = {+ id: 9,+ rule_name: "example.rule",+ repository: { url },+ ref: options.ref,+ product: "sast",+ };+ const report = normalizeSemgrepPlatformFindings({+ ...options,+ project,+ product: "sast",+ format: "semgrep-platform-findings/v1",+ findingCount: 1,+ findings: [native],+ });+ const partial = structuredClone(report.findings[0]!);+ partial.source_finding_id = "caller-managed";+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("findings.json", source, {+ remote: url,+ });+ const marked = (row: typeof partial) =>+ fixture.prepareNormalized({+ ...report,+ read: 2,+ findings: [...report.findings, row],+ });+ for (const finding of [+ { id: native.id, repository: { url: "https://github.com/example/other" } },+ { id: native.id, repository: native.repository },+ { id: native.id, ref: native.ref },+ { id: native.id, product: native.product },+ { id: native.id, ref: "refs/heads/other" },+ { id: native.id, ref: null },+ { id: native.id, product: "sca" },+ { id: native.id, issue_type: "Code" },+ { id: native.id, found_dependency: { package: "example-package" } },+ { id: native.id, vulnerability_identifier: "CVE-2099-0001" },+ { id: native.id, ref: "HEAD" },+ { repository: native.repository, ref: "HEAD" },+ ]) {+ partial.evidence.source_data = { finding };+ await expect(marked(partial)).rejects.toThrow(/scope/i);+ }+ const format = "issue-tracker/v1";+ partial.evidence.source_data = {+ format,+ finding: { id: native.id, ref: native.ref },+ };+ await expect(marked(partial)).rejects.toThrow(/scope/i);+ const issue = { number: 9, remediationBranch: "refs/heads/topic" };+ const fields = { id: issue.number, ref: issue.remediationBranch };+ const ticket = {+ source_finding_id: "caller-managed",+ evidence: {+ ...report.findings[0]!.evidence,+ source_data: { format, finding: fields },+ },+ };+ expect(JSON.stringify(ticket)).toBe(JSON.stringify(partial));+ await expect(marked(ticket)).rejects.toThrow(/scope/i);+ const ordinary = { read: 1, findings: [ticket], excluded: [] };+ expect((await fixture.prepareNormalized(ordinary)).preview.findings).toEqual([+ ticket,+ ]);+ for (const data of [+ { format, ticket: fields },+ { format, finding: { id: issue.number, ref: undefined } },+ {+ format,+ finding: { found_dependency: null, vulnerability_identifier: null },+ },+ {+ format,+ finding: { id: issue.number, title: "Ticket", product: "widget" },+ },+ ]) {+ const migrated = {+ ...ticket,+ evidence: { ...ticket.evidence, source_data: data },+ };+ expect((await marked(migrated)).preview.findings[1]).toEqual(migrated);+ }+});++test("a v1 normalized report binds its object rows and empty results to the declared checkout", async () => {+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("v1.json", source, {+ remote: url,+ });+ const prepare = (+ input: Parameters<typeof prepareNormalizedLocalImport>[0],+ provider: "semgrep" | "wiz" = "semgrep",+ ) =>+ prepareNormalizedLocalImport(+ input,+ { ...source, provider, repository: fixture.repository },+ { environment: fixture.environment },+ );++ const native = { id: 9, rule_name: "example.rule" };+ const scope = {+ deployment: options.deployment,+ ref: options.ref,+ project,+ product: "sast",+ format: "semgrep-platform-findings/v1",+ };+ const projected = normalizeSemgrepPlatformFindings({+ ...scope,+ findingCount: 1,+ findings: [native],+ }).findings[0]!;+ projected.evidence.source_data = { ...scope, finding: native };+ // This is the envelope returned by the v1 reader, including when it accepted no rows.+ const legacy = {+ sourceRepositoryUrl: url,+ read: 1,+ findings: [projected],+ excluded: [],+ };+ const other = "https://github.com/example/fork";+ expect((await prepare(legacy)).preview.findings).toHaveLength(1);+ const rowOnly = { ...legacy, sourceRepositoryUrl: undefined };+ expect((await prepare(rowOnly)).preview.findings).toHaveLength(1);+ for (const findings of [[projected], []]) {+ const wrong = {+ ...legacy,+ read: findings.length,+ findings,+ sourceRepositoryUrl: other,+ };+ await expect(prepare(wrong)).rejects.toThrow(/repository|remote/i);+ }+ const ordinary = structuredClone(projected);+ ordinary.source_finding_id = "generic";+ delete ordinary.evidence.source_data;+ const foreign = structuredClone(ordinary);+ foreign.evidence.details!.repository!.url = other;+ await expect(+ prepare({ ...legacy, read: 2, findings: [projected, foreign] }),+ ).rejects.toThrow(/report repository/i);+ expect(+ (await prepare({ ...legacy, findings: [ordinary] }, "wiz")).preview+ .findings,+ ).toHaveLength(1);+ const sarif = normalizeSemgrepFindings(+ semgrepSarif(),+ { sourceRepositoryUrl: url },+ "local",+ );+ expect(+ (await prepare({ ...legacy, ...sarif })).preview.findings,+ ).toHaveLength(1);+});++test("hosted repository comparison accepts an opaque Git remote alias", () => {+ expect(hostedRepositoryUrlKey("invalid alias")).toBe("invalid alias");+});++test("file and normalized Platform reports keep their Git binding with no accepted findings", async () => {+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: "ssh://[email protected]:443/example/service.git",+ });+ const prepare = fixture.prepareNormalized;+ for (const [findings, ready, excluded] of [+ [['{"id":42,"rule_name":"example.rule"}'], 1, 0],+ [['{"id":null}'], 0, 1],+ [[], 0, 0],+ ] as const) {+ const report = {+ ...options,+ format: "semgrep-platform-findings/v2",+ project: {+ ...project,+ id: String(project.id),+ url: "https://gitlab.com/example/service",+ },+ product: "sast",+ repositoryAliases: [],+ findingCount: findings.length,+ findings,+ };+ await fixture.writeJson(report);+ const { preview } = await fixture.prepare({+ sourceRepositoryUrl: "https://gitlab.com:443/example/service",+ });+ expect(preview.findings).toHaveLength(ready);+ expect(preview.excluded).toHaveLength(excluded);+ if (ready) continue;++ const native = normalizeSemgrepPlatformFindings(report);+ expect(native).toMatchObject({+ semgrepPlatformScope: {+ deployment: report.deployment,+ projectId: report.project.id,+ product: report.product,+ ref: report.ref,+ },+ });+ const replay = await prepare(JSON.parse(JSON.stringify(native)));+ expect(replay.preview.excluded).toHaveLength(excluded);+ expect((await replay.import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 0,+ });++ const other = {+ ...report,+ project: { ...report.project, url: "https://gitlab.com/example/other" },+ };+ await fixture.writeJson(other);+ await expect(fixture.prepare()).rejects.toThrow("configured remote");+ await expect(+ prepare(structuredClone(normalizeSemgrepPlatformFindings(other))),+ ).rejects.toThrow("configured remote");+ }+});++test("walks the selected project and ref, then rechecks page zero for offset drift", async () => {+ const pages: string[] = [];+ const report = await collectSemgrepPlatformFindings(options, {+ environment,+ fetch: async (endpoint, init) => {+ expect(endpoint.origin).toBe("https://semgrep.dev");+ expect(init.redirect).toBe("error");+ expect(new Headers(init.headers).get("authorization")).toBe(+ "Bearer synthetic",+ );+ if (+ endpoint.pathname ===+ "/api/v1/deployments/example/projects/example%2Fservice"+ )+ return Response.json({ project });+ expect(endpoint.pathname).toBe("/api/v1/deployments/example/findings");+ const page = endpoint.searchParams.get("page")!;+ expect(Object.fromEntries(endpoint.searchParams)).toEqual({+ page,+ page_size: "3000",+ ref: options.ref,+ issue_type: "sast",+ repository_ids: "77",+ dedup: "false",+ });+ pages.push(page);+ return Response.json({+ findings: page === "1" ? [{ id: 3001 }] : fullPage,+ });+ },+ });+ expect(pages).toEqual(["0", "1", "0"]);+ expect(report.findingCount).toBe(3001);+ expect(JSON.parse(report.findings[3000]!)).toEqual({ id: 3001 });++ await expect(+ collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({ findings: fullPage }),+ Response.json({ findings: [] }),+ Response.json({ findings: [...fullPage.slice(1), { id: 3001 }] }),+ ),+ ),+ ).rejects.toThrow(/changed across pages/);+});++test("rejects numeric API finding rows before returning an unreadable export", async () => {+ await expect(+ collectSemgrepPlatformFindings(+ options,+ responses(Response.json({ findings: [{ id: 7 }, 42] })),+ ),+ ).rejects.toThrow("Semgrep finding must be an object");+});++test("an explicit SDK token respects the configured Semgrep origin", async () => {+ const fetch = mock(async () => {+ throw new Error("Unexpected HTTP request");+ });+ for (const setting of ["SEMGREP_URL", "SEMGREP_APP_URL"]) {+ await expect(+ collectSemgrepPlatformFindings(+ { ...options, token: "synthetic-explicit" },+ {+ environment: {+ CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS: "1",+ [setting]: "https://private.example.test",+ },+ fetch,+ },+ ),+ ).rejects.toThrow(setting);+ }+ expect(fetch).not.toHaveBeenCalled();+});++test("rejects failed, overlapping or wrong-scope pages without returning a partial report", async () => {+ for (const [second, error] of [+ [new Response("rate limited", { status: 429 }), /HTTP 429/],+ [Response.json({ findings: [{ id: 3000 }] }), /repeated/],+ [+ Response.json({ findings: [{ id: 3001, ref: "refs/heads/main" }] }),+ /ref/,+ ],+ [+ Response.json({+ findings: [+ { id: 3001, repository: { url: "https://github.com/other/service" } },+ ],+ }),+ /repository/i,+ ],+ ] as const) {+ await expect(+ collectSemgrepPlatformFindings(+ options,+ responses(Response.json({ findings: fullPage }), second),+ ),+ ).rejects.toThrow(error);+ }+});++test.each([null, "[email protected]:example/service.git"])(+ "snapshots the requested project mapping and ref for native URL %s",+ checkProjectMapping,+);++async function checkProjectMapping(raw: string | null) {+ const resolved = raw ? url + ".git" : url;+ const row = {+ id: 1,+ rule_name: "example.rule",+ severity: "informational",+ ref: options.ref,+ repository: { url },+ };+ const requested = { ...options, sourceRepositoryUrl: url };+ const pending = collectSemgrepPlatformFindings(requested, {+ environment,+ fetch: async (endpoint) => {+ if (endpoint.pathname.endsWith("/findings")) {+ expect(endpoint.searchParams.get("ref")).toBe(options.ref);+ return Response.json({ findings: [row] });+ }+ return Response.json({ project: { ...project, url: raw } });+ },+ });+ requested.project = "other/service";+ requested.sourceRepositoryUrl = "https://github.com/other/service";+ requested.ref = "main";+ const saved = await pending;+ expect(saved.project).toEqual({+ ...project,+ id: String(project.id),+ url: resolved,+ });+ expect(saved.nativeProjectUrl).toBe(raw ?? undefined);+ expect(saved.ref).toBe(options.ref);+ expect(saved).toMatchObject({ sourceRepositoryUrl: url });+ const legacy = {+ deployment: options.deployment,+ ref: options.ref,+ sourceRepositoryUrl: url,+ product: "sast",+ findingCount: 1,+ format: "semgrep-platform-findings/v1",+ project: { ...saved.project, url: raw },+ findings: [row],+ };+ await using fixture = await localReportFixture(+ "semgrep.json",+ { provider: "semgrep", sourceKey: "example/topic" },+ { remote: url },+ );+ for (const report of [saved, legacy]) {+ await fixture.writeJson(report);+ const prepared = await fixture.prepare();+ expect(prepared.preview.findings[0]?.evidence).toMatchObject({+ severity: raw ? "unknown" : "informational",+ details: { repository: { url: resolved } },+ source_data: { project: { url: raw }, sourceRepositoryUrl: url },+ });+ expect((await prepared.import()).counts).toEqual(+ report === saved+ ? { created: 1, updated: 0, unchanged: 0 }+ : { created: 0, updated: 0, unchanged: 1 },+ );+ }+ if (raw)+ expect(() =>+ normalizeSemgrepFindings(+ { ...saved, nativeProjectUrl: "[email protected]:other/project" },+ {},+ "local",+ ),+ ).toThrow(/repository/);+ expect(() =>+ normalizeSemgrepFindings(+ { ...saved, sourceRepositoryUrl: "https://github.com/other/service" },+ {},+ "local",+ ),+ ).toThrow(/repository/);+}++test("a mapped project keeps backlog lines and severity with a private GitHub reference", async () => {+ const remote = "https://git.example.test/Team/Repo";+ const name = "team/repo";+ const row = {+ id: 1,+ ref: options.ref,+ repository: { id: project.id, name },+ rule_name: "example.rule",+ severity: "informational",+ location: { file_path: "src/app.ts", line: "3" },+ };+ const report = {+ ...options,+ format: "semgrep-platform-findings/v2",+ product: "sast",+ project: { ...project, id: String(project.id), url: remote },+ sourceRepositoryUrl: remote,+ repositoryAliases: [name],+ findings: [JSON.stringify(row)],+ findingCount: 1,+ };+ const sourceRepositories = [{ url: remote, platform: "github" as const }];+ const hinted = normalizeSemgrepFindings(+ report,+ { sourceRepositories },+ "local",+ );+ expect(hinted.findings[0]?.evidence).toMatchObject({+ severity: "informational",+ locations: [{ path: "src/app.ts", line: 3 }],+ source_data: { project: { url: null }, sourceRepositoryUrl: remote },+ });+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote,+ });+ await fixture.writeJson(report);+ const first = await fixture.prepare();+ expect((await first.import()).counts.created).toBe(1);+ const replay = await prepareNormalizedLocalImport(+ { read: 1, findings: first.preview.findings, excluded: [] },+ { ...source, repository: fixture.repository },+ { environment: fixture.environment, sourceRepositories },+ );+ expect(replay.preview.findings).toEqual(hinted.findings);+ expect((await replay.import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 1,+ });+});++test("replays a direct occurrence with a collector-style SSH project binding", () => {+ const report = {+ ...options,+ product: "sast",+ format: "semgrep-platform-findings/v2",+ project: { ...project, id: String(project.id), url: url + ".git" },+ nativeProjectUrl: "[email protected]:example/service.git",+ sourceRepositoryUrl: url,+ repositoryAliases: [],+ findingCount: 1,+ findings: ['{"id":2,"rule_name":"example.rule"}'],+ };+ const row = normalizeSemgrepPlatformFindings(report).findings[0]!;+ const canonical = { ...row.evidence.source_data, annotation: "reviewed" };+ const direct = {+ ...canonical,+ project: report.project,+ nativeProjectUrl: report.nativeProjectUrl,+ };+ row.evidence.source_data = direct;+ const rebound = semgrepPlatformFindingBinding(row, "semgrep")!;+ row.evidence.source_data = rebound.sourceData;+ expect(row.evidence.source_data).not.toHaveProperty("nativeProjectUrl");+ expect(row.evidence.source_data).toMatchObject({+ annotation: "reviewed",+ project: { url: report.nativeProjectUrl },+ });+ expect(semgrepPlatformFindingRepository(row, "semgrep")).toBe(+ report.project.url,+ );+ row.evidence.source_data = {+ ...direct,+ nativeProjectUrl: "[email protected]:example/other",+ };+ expect(() => semgrepPlatformFindingRepository(row, "semgrep")).toThrow(+ /repository/,+ );+});++test("matches GitHub project-path aliases across casing in collected, v1 and normalized rows", async () => {+ const name = "semgrep-logical/Prod";+ const native = {+ name,+ id: project.id,+ url: "https://github.com/Example/Service",+ };+ const row = {+ id: 1,+ rule_name: "example.rule",+ repository: { name: "example/service" },+ };+ async function collect(projectUrl: string, findings: unknown[] = [row]) {+ return collectSemgrepPlatformFindings(+ { ...options, project: name },+ {+ environment,+ fetch: async (endpoint) =>+ Response.json(+ endpoint.pathname.endsWith("/findings")+ ? { findings }+ : { project: { ...native, url: projectUrl } },+ ),+ },+ );+ }+ const saved = await collect(native.url);+ expect(saved.repositoryAliases).toEqual([row.repository.name]);+ const { repositoryAliases: _aliases, ...v1 } = saved;+ const legacy = {+ ...v1,+ format: "semgrep-platform-findings/v1",+ findings: [row],+ };+ // The Semgrep project label and any witnessed display label retain their original casing.+ const named = (name: string) => ({ ...row, repository: { name } });+ const exact = await collect(native.url, [named("Prod")]);+ expect(normalizeSemgrepFindings(exact, {}, "local").findings).toHaveLength(1);+ const proof = { id: 2, repository: { name: "Prod", url: native.url } };+ for (const label of ["prod", "SEMGREP-LOGICAL/PROD"]) {+ const findings = [proof, named(label)];+ await expect(collect(native.url, findings)).rejects.toThrow(/repository/);+ expect(() =>+ normalizeSemgrepFindings(+ {+ ...saved,+ repositoryAliases: ["Prod", label],+ findingCount: findings.length,+ findings: findings.map((row) => JSON.stringify(row)),+ },+ {},+ "local",+ ),+ ).toThrow(/repository/);+ expect(() =>+ selectSemgrepPlatformFindings({+ ...options,+ projectResponse: JSON.stringify({ project: native }),+ findingIds: ["1"],+ findingsResponses: JSON.stringify({+ findings: [+ {+ ...row,+ ref: options.ref,+ repository: { name: label, id: native.id },+ },+ ],+ }),+ }),+ ).toThrow(/repository/);+ }+ const custom = "https://git.example.test/Example/Service";+ await expect(collect(custom)).rejects.toThrow(/repository/);+ for (const report of [saved, legacy]) {+ const finding = normalizeSemgrepFindings(report, {}, "local").findings[0]!;+ expect(semgrepPlatformFindingRepository(finding, "semgrep")).toBe(+ native.url,+ );+ expect(+ finding.evidence.source_data?.["repositoryWitnessJson"],+ ).toBeUndefined();+ const mapped = { ...report, project: { ...report.project, url: custom } };+ expect(() => normalizeSemgrepFindings(mapped, {}, "local")).toThrow(+ /repository/,+ );+ const options = {+ sourceRepositories: [{ url: custom, platform: "github" as const }],+ };+ const verified = normalizeSemgrepFindings(mapped, options, "local")+ .findings[0]!;+ expect(+ semgrepPlatformFindingRepository(+ verified,+ "semgrep",+ options.sourceRepositories,+ ),+ ).toBe(custom);+ }+});++test("a URL-less SAST row uses its Git path for selection and keeps other verified labels in the full report", () => {+ const project = {+ id: "77",+ name: "Logical/Service",+ url: "https://github.com/team/service%2Bapi",+ };+ const selection = "semgrep-platform-selection/v1";+ const full = "semgrep-platform-findings/v2";+ for (const [name, expectedFormat, captureAllowed] of [+ ["team/service+api", selection, true],+ ["team/service%2Bapi", selection, false],+ [project.name, full, false],+ ] as const) {+ const row = {+ id: 8,+ ref: options.ref,+ rule_name: "example.rule",+ repository: { id: 77, name },+ };+ const saved = {+ ...options,+ project,+ product: "sast",+ format: full,+ repositoryAliases: [name],+ findingCount: 1,+ findings: [JSON.stringify(row)],+ };+ const read = (report: unknown) =>+ normalizeSemgrepFindings(report, {}, "local");+ const finding = read(saved).findings[0]!;+ expect(finding.evidence.source_data?.["format"]).toBe(expectedFormat);+ expect(semgrepPlatformFindingRepository(finding, "semgrep")).toBe(+ project.url,+ );+ const archive = () => read({ ...saved, format: selection });+ if (expectedFormat === selection)+ expect(archive().findings).toEqual([finding]);+ else expect(archive).toThrow("project and ref");+ const capture = () =>+ selectSemgrepPlatformFindings({+ ...options,+ projectResponse: JSON.stringify({ project }),+ findingsResponses: [JSON.stringify({ findings: [row] })],+ findingIds: ["8"],+ });+ if (captureAllowed) expect(read(capture()).findings).toEqual([finding]);+ else expect(capture).toThrow("project and ref");+ }+});++test("repository path aliases retain a literal .git suffix and use verified GitHub SSH bindings", () => {+ const project = {+ id: "77",+ name: "project-label",+ url: "https://git.example.test/team/Service.git",+ };+ const labels = ["team/Service.git", "Service.git", "team/service", "service"];+ const rows = labels.map((name, index) => ({+ id: index + 1,+ rule_name: "example.rule",+ repository: { name },+ }));+ const report = {+ format: "semgrep-platform-findings/v2",+ deployment: "example",+ ref: options.ref,+ product: "sast",+ project,+ repositoryAliases: labels,+ findingCount: rows.length,+ findings: rows.map((row) => JSON.stringify(row)),+ };+ const verified = {+ sourceRepositories: [{ url: project.url, platform: "github" as const }],+ };+ const publicReport = {+ ...report,+ project: { ...project, url: "https://github.com/team/Service.git" },+ };+ expect(+ normalizeSemgrepFindings(publicReport, {}, "local").findings,+ ).toHaveLength(4);+ expect(+ normalizeSemgrepFindings(report, verified, "local").findings,+ ).toHaveLength(4);+ const encodedRow = { ...rows[0], repository: { name: "C++" } };+ const encoded = {+ ...report,+ project: { ...project, url: "https://github.com/team/C%2B%2B" },+ repositoryAliases: ["C++"],+ findings: [JSON.stringify(encodedRow)],+ findingCount: 1,+ };+ expect(normalizeSemgrepFindings(encoded, {}, "local").findings).toHaveLength(+ 1,+ );+ const firstRow = {+ ...rows[0],+ repository: { url: "[email protected]:team/service.git" },+ };+ const native = {+ ...report,+ findings: [JSON.stringify(firstRow)],+ findingCount: 1,+ };+ const result = normalizeSemgrepFindings(native, verified, "local")+ .findings[0]!;+ expect(+ semgrepPlatformFindingRepository(+ result,+ "semgrep",+ verified.sourceRepositories,+ ),+ ).toBe(project.url);+ for (const candidate of [report, native]) {+ expect(() => normalizeSemgrepFindings(candidate, {}, "local")).toThrow(+ /repository/,+ );+ expect(() =>+ normalizeSemgrepFindings(+ candidate,+ {+ sourceRepositories: [+ { url: "https://git.example.test/team/other", platform: "github" },+ ],+ },+ "local",+ ),+ ).toThrow(/repository/);+ }+});+test("blank display names replay when a native ID or URL binds the repository", async () => {+ const findings = [+ { id: project.id, url, name: "" },+ { id: project.id, name: " " },+ { url, name: "" },+ ].map((repository, index) => ({+ id: index + 1,+ repository,+ ref: options.ref,+ rule_name: "example.rule",+ }));+ const page = JSON.stringify({ findings });+ const saved = await collectSemgrepPlatformFindings(+ options,+ responses(new Response(page)),+ );+ expect(saved.repositoryAliases).toEqual([]);+ const { repositoryAliases: _aliases, ...legacy } = saved;+ const prior = {+ ...legacy,+ format: "semgrep-platform-findings/v1",+ findings,+ project,+ };+ for (const report of [saved, prior]) {+ const normalized = normalizeSemgrepFindings(report, {}, "local");+ expect(normalized.excluded).toEqual([]);+ expect(+ normalized.findings.map((row) =>+ semgrepPlatformFindingRepository(row, "semgrep"),+ ),+ ).toEqual([url, url, url]);+ }+ const selected = {+ ...options,+ projectResponse: JSON.stringify({ project }),+ findingsResponses: [page],+ };+ expect(+ selectSemgrepPlatformFindings({ ...selected, findingIds: ["1"] }).findings,+ ).toHaveLength(1);+ expect(() =>+ selectSemgrepPlatformFindings({ ...selected, findingIds: ["2"] }),+ ).toThrow("project and ref");+ for (const repository of [+ { name: "" },+ { id: 999, url, name: "" },+ { id: project.id, url: "https://github.com/other/service", name: "" },+ ]) {+ await expect(+ collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({ findings: [{ ...findings[0], repository }] }),+ ),+ ),+ ).rejects.toThrow(/repository/);+ }+});++test("uses independently verified project aliases for name-only rows", async () => {+ const label = "display",+ alias = { name: label };+ for (const proof of [{ url }, { id: project.id }]) {+ const findings = [+ { id: 1, repository: { name: project.name } },+ { id: 2, repository: { name: "service" } },+ { id: 3, repository: { ...alias, ...proof } },+ { id: 4, repository: alias },+ ];+ const report = await collectSemgrepPlatformFindings(+ options,+ responses(Response.json({ findings })),+ );+ expect(report.repositoryAliases).toEqual([label, project.name, "service"]);+ expect(report.findingCount).toBe(4);+ }+ for (const repository of [+ 2,+ alias,+ { ...alias, id: 99 },+ { ...alias, url: "https://github.com/other/service" },+ ]) {+ await expect(+ collectSemgrepPlatformFindings(+ options,+ responses(Response.json({ findings: [{ id: 1, repository }] })),+ ),+ ).rejects.toThrow(/repository/i);+ }+});++test("accepts a name-only repository alias verified on a later page", async () => {+ const name = "project display name";+ const first = [{ id: 1, repository: { name } }, ...fullPage.slice(1)];+ const report = await collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({ findings: first }),+ Response.json({+ findings: [{ id: 3001, repository: { name, id: project.id } }],+ }),+ Response.json({ findings: first }),+ ),+ );+ expect(report.repositoryAliases).toEqual([name]);+ expect(report.findingCount).toBe(3001);+});++test("cross-page ID-less findings compare original numeric values and member order", async () => {+ const first = [+ ...fullPage.slice(1),+ { vendor: { score: 1 }, rule_name: "example.rule" },+ ];+ const collect = (score: string) =>+ collectSemgrepPlatformFindings(+ options,+ responses(+ Response.json({ findings: first }),+ new Response(+ `{"findings":[{"rule_name":"example.rule","vendor":{"score":${score}}},{"id":3001}]}`,+ ),+ Response.json({ findings: first }),+ ),+ );+ await expect(collect("1.0")).rejects.toThrow(+ /repeated findings across pages/,+ );+ expect((await collect("2")).findingCount).toBe(3002);+});++test("keeps unrelated valid findings on a page with missing or duplicate source IDs", async () => {+ const findings = [null, 2, 2, 3].map((id) => ({+ id,+ rule_name: "example.rule",+ }));+ const saved = await collectSemgrepPlatformFindings(+ options,+ responses(Response.json({ findings })),+ );+ expect(saved.findingCount).toBe(4);+ const result = normalizeSemgrepFindings(saved, {}, "local");+ expect(result.findings).toHaveLength(1);+ expect(result.excluded.map((row) => row.position).sort()).toEqual([1, 2, 3]);+});++test("replaying two native SAST findings across selected and full imports leaves SQLite unchanged", async () => {+ const ids = ["9223372036854775805", "9223372036854775806"];+ const projectId = "9223372036854775807";+ const projectResponse = `{"project":{"id":${projectId},"name":"${project.name}","url":"${url}"}}`;+ const repositories = [+ JSON.stringify({ url }),+ `{"id":${projectId},"name":"${project.name}"}`,+ ];+ const rows = ids.map(+ (id, index) =>+ `{"id":${id},"score":10,"rule":{"name":"example.rule"},"status":"open","severity":"low","repository":${repositories[index]},"ref":"${options.ref}"}`,+ );+ const page = `{"findings":[${rows.join(",")}]}`;+ const input = {+ deployment: options.deployment,+ ref: options.ref,+ projectResponse,+ findingsResponses: [page],+ findingIds: ids,+ };+ const selection = selectSemgrepPlatformFindings(input);+ const selected = normalizeSelectedSemgrepPlatformFindings({+ ...input,+ sourceRepositoryUrl: url,+ });+ const collect = (data: string) =>+ collectSemgrepPlatformFindings(+ {+ ...options,+ sourceRepositoryUrl: "https://github.com/Example/Service.git",+ },+ {+ environment,+ fetch: async (endpoint) =>+ new Response(+ endpoint.pathname.endsWith("/findings") ? data : projectResponse,+ ),+ },+ );+ const report = await collect(page.replaceAll('"score":10', '"score":1e1'));+ await using fixture = await localReportFixture(+ "semgrep.json",+ {+ provider: "semgrep",+ sourceKey: "example/topic",+ sourceRepositoryUrl: url,+ },+ { remote: url },+ );+ await fixture.writeJson(selection);+ const prepared = await fixture.prepare();+ expect(prepared.preview.excluded).toEqual([]);+ expect((await prepared.import()).counts).toEqual({+ created: 2,+ updated: 0,+ unchanged: 0,+ });+ const direct = await prepareNormalizedLocalImport(+ selected,+ {+ provider: "semgrep",+ sourceKey: fixture.sourceKey,+ repository: fixture.repository,+ },+ { environment: fixture.environment, sourceRepositories: [{ url }] },+ );+ expect((await direct.import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ const saved = await fixture.read();+ expect(new Set(saved.map((row) => row.sourceFindingId)).size).toBe(2);+ for (const replay of [report, selection, report]) {+ await fixture.writeJson(replay);+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ }+ expect(await fixture.read()).toEqual(saved);+ const changedPage = page.replace('"severity":"low"', '"severity":"high"');+ const changed = await collect(changedPage);+ await fixture.writeJson(changed);+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 1,+ unchanged: 1,+ });+ const revised = await fixture.read();+ expect(+ revised.find((row) => row.evidence.severity === "high")?.sourceFindingId,+ ).toBe(prepared.preview.findings[0]!.source_finding_id);+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ expect(await fixture.read()).toEqual(revised);+ for (const [index, id] of ids.entries())+ expect(report.findings[index]).toContain(`"id":${id}`);+});++test("excludes malformed Supply Chain dependencies and preserves findings without a package", async () => {+ const row = { id: 11, rule_name: "example.rule" };+ const report = await collectSemgrepPlatformFindings(+ { ...options, product: "sca" },+ responses(+ Response.json({+ findings: [+ { ...row, found_dependency: 42 },+ { ...row, id: 12, found_dependency: { package: 42 } },+ { ...row, id: 13, found_dependency: { package: " " } },+ { ...row, id: 14, found_dependency: { package: null } },+ { ...row, id: 15, found_dependency: { package: "example-package" } },+ { ...row, id: 16, found_dependency: {}, fix_recommendations: 42 },+ ],+ }),+ ),+ );+ const result = normalizeSemgrepFindings(report, {}, "local");+ expect(result.excluded).toMatchObject([+ { position: 1, reason: "Semgrep found dependency must be an object." },+ ...[2, 3, 4].map((position) => ({+ position,+ reason: "Semgrep package name must be nonempty text.",+ })),+ ]);+ expect(+ result.findings.map(({ evidence }) =>+ evidence.packages?.map(({ name }) => name),+ ),+ ).toEqual([["example-package"], []]);+});++test("projects Supply Chain evidence and distinguishes AI SAST from SAST on replay", async () => {+ await using fixture = await localReportFixture(+ "semgrep.json",+ {+ provider: "semgrep",+ sourceKey: "example/topic",+ sourceRepositoryUrl: url,+ },+ { remote: url },+ );+ const row = {+ id: 11,+ rule: { name: "example.rule", message: "Synthetic finding" },+ ref: options.ref,+ repository: { name: project.name, url },+ };+ async function read(product: "sast" | "ai_sast" | "sca") {+ const finding =+ product === "sca"+ ? {+ ...row,+ vulnerability_identifier: "CVE-2025-0001",+ found_dependency: {+ package: "example-package",+ ecosystem: "npm",+ version: "1.0.0",+ },+ fix_recommendations: [+ { package: "example-package", version: "1.1.0" },+ { package: "other", version: "2.0.0" },+ ],+ }+ : row;+ const report = await collectSemgrepPlatformFindings(+ { ...options, product },+ responses(Response.json({ findings: [finding] })),+ );+ await fixture.writeJson(report);+ const { preview } = await fixture.prepare();+ expect(preview.excluded).toEqual([]);+ return preview.findings[0]!;+ }+ const sca = await read("sca");+ expect(sca.evidence.packages).toEqual([+ {+ name: "example-package",+ ecosystem: "npm",+ installed_version: "1.0.0",+ manifest_path: null,+ fixed_versions: ["1.1.0"],+ },+ ]);+ expect(sca.evidence.advisory_ids).toEqual(["CVE-2025-0001"]);+ const ai = await read("ai_sast");+ const sast = await read("sast");+ expect(ai.evidence.details?.kind).toBe("sast");+ expect(+ new Set([ai, sast, sca].map((finding) => finding.source_finding_id)).size,+ ).toBe(3);+});++test.each(["gitlab.com", "bitbucket.org"])(+ "imports informational Semgrep findings through the %s SSH-over-443 checkout remote",+ async (host) => {+ const alternate = "altssh." + host;+ const native = `ssh://git@${alternate}:443/example/service.git`;+ const report = await collectSemgrepPlatformFindings(options, {+ environment,+ fetch: async (endpoint) =>+ Response.json(+ endpoint.pathname.endsWith("/findings")+ ? {+ findings: [+ {+ id: 9,+ rule_name: "example.rule",+ severity: "informational",+ },+ ],+ }+ : { project: { ...project, url: native } },+ ),+ });+ expect(report.project.url).toBe(`https://${host}/example/service.git`);+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ // Git decodes the escaped path in an ssh:// URL before requesting upload-pack.+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: native.replace("/service.git", "/%73ervice.git"),+ });+ await fixture.writeJson(report);+ const { preview } = await fixture.prepare();+ expect(preview.findings[0]?.evidence.severity).toBe("informational");+ for (const remote of [+ native.replace("git@", "other@"),+ native.replace(":443/", ":22/"),+ ]) {+ await using other = await localReportFixture("semgrep.json", source, {+ remote,+ });+ await other.writeJson(report);+ await expect(other.prepare()).rejects.toThrow(/does not match/);+ }+ },+);++const cliArgs = [+ "import",+ "semgrep",+ options.project,+ "--semgrep-deployment",+ options.deployment,+ "--semgrep-ref",+ options.ref,+ "--semgrep-product",+ "ai_sast",+ "--format",+ "json",+];++test("CLI emits a replayable report for the requested product", async () => {+ const row = {+ id: 42,+ repository: { url },+ ref: options.ref,+ rule_name: "example.rule",+ };+ const cli = createCliTest(main);+ const code = await cli.runCli([...cliArgs, "--source-repository-url", url], {+ ...dependencies({ environment }),+ hostedScannerFetch: async (endpoint) =>+ Response.json(+ endpoint.pathname.endsWith("/findings")+ ? { findings: [row] }+ : { project: { ...project, url: null } },+ ),+ });+ expect(code).toBe(0);+ expect(cli.stderr.text()).toBe("");+ const report = JSON.parse(cli.stdout.text());+ expect(report).toMatchObject({+ project: { id: "77", name: project.name, url },+ ref: options.ref,+ product: "ai_sast",+ sourceRepositoryUrl: url,+ findingCount: 1,+ });+ expect(report.findings.map((raw: string) => JSON.parse(raw))).toEqual([row]);+});++test("CLI escapes human-readable output while retaining native JSON and YAML", async () => {+ const alias = "display\u001b[2Jname\u009b2J\u202e";+ const row = { id: 42, repository: { id: project.id, name: alias } };+ for (const [format, tty] of [+ [undefined, true],+ ["toon", true],+ ["toon", false],+ ["md", true],+ ["md", false],+ ["json", true],+ ["yaml", false],+ ] as const) {+ const cli = createCliTest(main, { stdout: tty });+ const args =+ format === undefined ? cliArgs.slice(0, -2) : cliArgs.with(-1, format);+ const code = await cli.runCli(args, {+ ...dependencies({ environment }),+ hostedScannerFetch: responses(Response.json({ findings: [row] })).fetch,+ });+ expect(code).toBe(0);+ const output = cli.stdout.text();+ if (format === undefined || format === "md" || (format === "toon" && tty)) {+ expect(output).not.toContain("\u001b");+ expect(output).not.toContain("\u009b");+ expect(output).not.toContain("\u202e");+ expect(output).toContain("\\u009b2J\\u202e");+ } else if (format === "toon") {+ expect(output).toContain("name\u009b2J\u202e");+ } else {+ const report = format === "json" ? JSON.parse(output) : parseYaml(output);+ expect(report.repositoryAliases).toEqual([alias]);+ expect(JSON.parse(report.findings[0]).repository.name).toBe(alias);+ }+ }+});++test("CLI preserves native Semgrep error details in structured output and escapes the terminal diagnostic", async () => {+ const cli = createCliTest(main);+ const detail = "scope \u202edenied\npermissions:\tread";+ const code = await cli.runCli([...cliArgs, "--full-output"], {+ ...dependencies({ environment }),+ hostedScannerFetch: responses(new Response(detail, { status: 403 })).fetch,+ });+ expect(code).toBe(2);+ expect(cli.stderr.text()).toContain("scope \\u202edenied permissions: read");+ expect(JSON.parse(cli.stdout.text()).error.message).toContain(detail);+});++test("CLI checks opt-in and token origin before fetching", async () => {+ const fetch = mock(() => {+ throw new Error("Unexpected HTTP call");+ });+ for (const [env, diagnostic] of [+ [{}, "CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS"],+ [+ { ...environment, SEMGREP_URL: "https://other.example.test" },+ "SEMGREP_URL",+ ],+ ] as const) {+ const cli = createCliTest(main);+ const code = await cli.runCli(cliArgs, {+ ...dependencies({ environment: env }),+ hostedScannerFetch: fetch,+ });+ expect(code).toBe(2);+ expect(cli.stdout.text() + cli.stderr.text()).toContain(diagnostic);+ }+ expect(fetch).not.toHaveBeenCalled();+});++test("saved v1 findings keep exact source IDs and original JSON numeric types on local replay", async () => {+ const ids = ["9007199254740992", "9007199254740993"];+ const tokens = [ids[0]!, "9.007199254740993e15"];+ const row = {+ rule: { name: "example.rule" },+ ref: options.ref,+ repository: { name: "service" },+ };+ const v1 = {+ format: "semgrep-platform-findings/v1",+ deployment: options.deployment,+ project: { name: project.name, id: ids[1], url: null },+ sourceRepositoryUrl: url,+ ref: options.ref,+ product: "sast",+ findingCount: 2,+ findings: tokens.map((id) => ({+ ...row,+ id,+ vendor: { score: ["1.00000000000000001"], label: id },+ })),+ numericFields: {+ project: { id: ids[1] },+ findings: Object.fromEntries(+ tokens.map((id, i) => [+ i,+ { id, vendor: { score: { 0: "1.00000000000000001" } } },+ ]),+ ),+ },+ };+ await using fixture = await localReportFixture(+ "semgrep.json",+ {+ provider: "semgrep",+ sourceKey: "example/topic",+ },+ { remote: url },+ );+ await fixture.writeJson(v1);+ const prepared = await fixture.prepare();+ const { preview } = prepared;+ expect(preview.excluded).toEqual([]);+ const numericRows = ids.map(+ (id) =>+ `{"id":${id},"rule":{"name":"example.rule"},"ref":"${options.ref}","repository":{"url":"${url}"}}`,+ );+ const selection = selectSemgrepPlatformFindings({+ deployment: options.deployment,+ ref: options.ref,+ projectResponse: `{"project":{"name":"${project.name}","id":${ids[1]},"url":"${url}"}}`,+ findingsResponses: [`{"findings":[${numericRows.join(",")}]}`],+ findingIds: ids,+ });+ const selected = normalizeSemgrepFindings(+ selection,+ { sourceRepositoryUrl: url },+ "local",+ );+ const sourceIds = (rows: typeof preview.findings) =>+ rows.map((row) => row.source_finding_id);+ expect(new Set(sourceIds(preview.findings)).size).toBe(2);+ expect(sourceIds(preview.findings)).toEqual(sourceIds(selected.findings));+ for (const [i, finding] of preview.findings.entries()) {+ const raw = finding.evidence.source_data?.["semgrepPlatformFindingJson"];+ expect(raw).toContain(`"id":${ids[i]}`);+ expect(raw).toContain('"score":[1.00000000000000001]');+ expect(raw).toContain(`"label":"${tokens[i]}"`);+ }+ expect((await prepared.import()).counts).toEqual({+ created: 2,+ updated: 0,+ unchanged: 0,+ });+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ const v2 = {+ ...v1,+ format: "semgrep-platform-findings/v2",+ repositoryAliases: ["service"],+ findings: ids.map(+ (id, i) =>+ `{"id":${id},"rule":{"name":"example.rule"},"ref":"${options.ref}","repository":{"name":"service"},"vendor":{"score":[1.00000000000000001],"label":"${tokens[i]}"}}`,+ ),+ };+ for (const equivalent of [v2, v1]) {+ await fixture.writeJson(equivalent);+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ }+ await fixture.writeJson({+ ...v1,+ numericFields: { findings: { 0: { id: ids[1] } } },+ });+ await expect(fixture.prepare()).rejects.toThrow(/exact scanner number/);+ await fixture.writeJson({+ ...v1,+ findings: v1.findings.map((row) => ({+ ...row,+ repository: { name: "other" },+ })),+ });+ await expect(fixture.prepare()).rejects.toThrow(/repository/);+ await fixture.writeJson({+ ...v1,+ project: { ...v1.project, url: "https://github.com/other/service" },+ });+ await expect(fixture.prepare()).rejects.toThrow(/repository/);+ expect(() =>+ normalizeSemgrepFindings(+ {+ ...v1,+ project: { ...v1.project, url: "[email protected]:team/service" },+ sourceRepositoryUrl: "https://git.example.test/team/service",+ },+ {},+ "local",+ ),+ ).toThrow(/HTTP\(S\) repository/);+});++test("a verified alias remains replayable with or without a reader platform hint", async () => {+ const remote = "https://git.example.test/Team/Repo";+ const repository = { name: "repo" };+ const dependent = { id: 1, repository, rule_name: "example.rule" };+ const proof = {+ id: 2,+ rule_name: "example.proof",+ repository: { ...repository, url: remote },+ };+ const report = {+ ...options,+ project: { name: "logical", id: "77", url: remote },+ format: "semgrep-platform-findings/v2",+ product: "sast",+ repositoryAliases: [repository.name],+ findingCount: 2,+ findings: [dependent, proof].map((row) => JSON.stringify(row)),+ };+ const source = { provider: "semgrep" as const, sourceKey: "example/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote,+ });+ const settings = { ...source, repository: fixture.repository };+ const sourceRepositories = [{ url: remote, platform: "github" as const }];+ const dependencies = { environment: fixture.environment, sourceRepositories };+ await fixture.writeJson(report);+ const first = await fixture.prepare();+ expect((await first.import()).counts.created).toBe(2);+ const row = first.preview.findings[0]!;+ const input = { read: 1, findings: [row], excluded: [] };+ const direct = await prepareNormalizedLocalImport(+ input,+ settings,+ dependencies,+ );+ expect((await direct.import()).counts.unchanged).toBe(1);+ expect(+ semgrepPlatformFindingRepository(direct.preview.findings[0]!, "semgrep"),+ ).toBe(remote);+ expect(+ JSON.parse(+ row.evidence.source_data!["semgrepPlatformFindingJson"] as string,+ ),+ ).toEqual(dependent);+ const read = (saved: typeof report) =>+ normalizeSemgrepFindings(saved, { sourceRepositories }, "local");+ expect(read(report).findings[0]).toEqual(row);++ const withoutProof = read({+ ...report,+ findingCount: 1,+ findings: [report.findings[0]!],+ }).findings[0]!;+ expect(withoutProof.evidence.source_data).not.toHaveProperty(+ "repositoryWitnessJson",+ );+ expect(() =>+ semgrepPlatformFindingRepository(withoutProof, "semgrep"),+ ).toThrow(/witness/);+ for (const witness of [+ { name: "other", id: "77" },+ { ...repository, id: "99" },+ ]) {+ const forged = structuredClone(input);+ forged.findings[0]!.evidence.source_data!["repositoryWitnessJson"] =+ JSON.stringify(witness);+ await expect(+ prepareNormalizedLocalImport(forged, settings, dependencies),+ ).rejects.toThrow(/alias|repository/);+ }++ // This target's own name establishes the name, so it needs no witness.+ const target = read({+ ...report,+ project: { ...report.project, id: "20", name: repository.name },+ findings: [report.findings[0]!],+ findingCount: 1,+ }).findings[0]!;+ target.source_finding_id = "caller-managed";+ const data = target.evidence.source_data!;+ const prepare = () =>+ prepareNormalizedLocalImport(+ { read: 1, findings: [target], excluded: [] },+ settings,+ dependencies,+ );+ const firstTarget = await prepare();+ expect((await firstTarget.import()).counts.created).toBe(1);+ data["repositoryWitnessJson"] = JSON.stringify({ ...repository, id: "20" });+ expect((await (await prepare()).import()).counts.unchanged).toBe(1);+ for (const raw of [+ row.evidence.source_data!["repositoryWitnessJson"],+ JSON.stringify({+ ...repository,+ url: "https://git.example.test/Other/Project",+ }),+ ]) {+ data["repositoryWitnessJson"] = raw;+ await expect(prepare()).rejects.toThrow(/repository/);+ }+});++test("changing the proof for an alias leaves its dependent SQLite finding unchanged", async () => {+ const label = "display label";+ const id = "9007199254740993";+ const byUrl = JSON.stringify({+ id: 1,+ rule_name: "example.url",+ repository: { name: label, url },+ });+ const byId = `{"id":2,"rule_name":"example.id","repository":{"name":"${label}","id":${id}}}`;+ const both = `{"id":3,"rule_name":"example.both","repository":{"metadata":"vendor-only","id":${id},"name":"${label}","url":"${url}"}}`;+ const dependent = (message: string) =>+ JSON.stringify({+ id: 4,+ rule_message: message,+ repository: { name: label },+ });+ const original = dependent("original");+ await using fixture = await localReportFixture(+ "semgrep.json",+ { provider: "semgrep", sourceKey: "example/topic" },+ { remote: url },+ );+ async function importRows(findings: string[]) {+ await fixture.writeJson({+ ...options,+ format: "semgrep-platform-findings/v2",+ project: { ...project, id },+ product: "sast",+ repositoryAliases: [label],+ findingCount: findings.length,+ findings,+ });+ const prepared = await fixture.prepare();+ expect(prepared.preview.excluded).toEqual([]);+ return (await prepared.import()).counts;+ }+ expect(await importRows([byUrl, original])).toEqual({+ created: 2,+ updated: 0,+ unchanged: 0,+ });+ const initial = (await fixture.read()).find(+ (row) => row.evidence.title === "original",+ )!;+ expect(initial.version).toBe(1);+ expect(initial.evidence.source_data?.["repositoryWitnessJson"]).toBe(+ JSON.stringify({ id, name: label }),+ );++ for (const rows of [+ [original, byUrl, byId, both],+ [both, byId, original, byUrl],+ [byId, original],+ [original, both],+ ]) {+ expect((await importRows(rows)).updated).toBe(0);+ }+ const stored = await fixture.read();+ expect(stored.find((row) => row.id === initial.id)).toEqual(initial);+ const native = stored.find((row) => row.evidence.title === "example.both")!+ .evidence.source_data?.["semgrepPlatformFindingJson"];+ expect(native).toContain('"metadata":"vendor-only"');+ expect(native).toContain(`"id":${id}`);++ const revised = [dependent("revised"), both];+ expect(await importRows(revised)).toEqual({+ created: 0,+ updated: 1,+ unchanged: 1,+ });+ expect(await importRows(revised)).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ expect(+ (await fixture.read()).find((row) => row.id === initial.id),+ ).toMatchObject({+ version: 2,+ evidence: { title: "revised" },+ });+});++test("collects private GitHub and GitLab rows with an independently supplied repository", async () => {+ const name = "scanner-project";+ const native = "https://git.example.test/Org/Repo";+ const rowUrl = "https://git.example.test/org/repo.git";+ const findings = [+ { id: 1, rule_name: "example.rule", repository: { url: rowUrl } },+ { id: 2, rule_name: "example.rule", repository: { name: "repo" } },+ ];+ function collect(+ projectUrl: string,+ sourceRepositories: { url: string; platform: "github" | "gitlab" }[] = [],+ rows = findings,+ ) {+ return collectSemgrepPlatformFindings(+ { ...options, project: name, sourceRepositories },+ {+ environment,+ fetch: async (endpoint) =>+ Response.json(+ endpoint.pathname.endsWith("/findings")+ ? { findings: rows }+ : { project: { id: project.id, name, url: projectUrl } },+ ),+ },+ );+ }+ const scp = "[email protected]:Org/Repo";+ const ssh = "ssh://[email protected]/org/repo.git";+ for (const [projectUrl, referenceUrl] of [+ [native, rowUrl],+ [scp, rowUrl],+ [scp, ssh],+ [ssh, scp],+ ] as const) {+ const reference = {+ url: referenceUrl as string,+ platform: "github" as const,+ };+ const pending = collect(projectUrl, [reference]);+ reference.url = "https://git.example.test/Org/Other";+ const report = await pending;+ expect(report.project.url).toBe(projectUrl === ssh ? rowUrl : native);+ expect(JSON.parse(report.findings[0]!)).toEqual(findings[0]);+ expect(+ normalizeSemgrepFindings(+ report,+ { sourceRepositories: [{ url: rowUrl, platform: "github" }] },+ "local",+ ).findings,+ ).toHaveLength(2);+ await expect(collect(projectUrl)).rejects.toThrow(/repository/);+ await expect(collect(projectUrl, [reference])).rejects.toThrow(+ /repository/,+ );+ }+ const gitlabRows = [{ ...findings[0]!, repository: { url: scp } }];+ for (const url of [native, "https::" + native]) {+ const gitlab = { url, platform: "gitlab" as const };+ const report = await collect(scp, [gitlab], gitlabRows);+ expect(+ normalizeSemgrepFindings(+ report,+ { sourceRepositories: [gitlab] },+ "local",+ ).findings,+ ).toHaveLength(1);+ for (const other of [+ url.toLowerCase(),+ url.replace("/Repo", "/Other"),+ url.replace("git.example", "other.example"),+ ]) {+ await expect(+ collect(scp, [{ ...gitlab, url: other }], gitlabRows),+ ).rejects.toThrow(/repository/);+ }+ }+ await expect(+ collect(scp, [+ { url: ssh.replace("git.example", "other.example"), platform: "github" },+ ]),+ ).rejects.toThrow(/repository/);+});diff --git a/sdk/typescript/tests-ts/semgrep-platform-selection-file.test.ts b/sdk/typescript/tests-ts/semgrep-platform-selection-file.test.tsindex bd88ff6d3..21668a2e4 100644--- a/sdk/typescript/tests-ts/semgrep-platform-selection-file.test.ts+++ b/sdk/typescript/tests-ts/semgrep-platform-selection-file.test.ts@@ -1048,7 +1048,7 @@ test("direct SDK imports respect the native source even with a caller-selected I};await expect(prepareNormalizedExternalPublication(- { ...normalized, findings: [exported] },+ { read: 1, excluded: [], findings: [exported] },options,{ ...deps, fetch },),diff --git a/sdk/typescript/tests-ts/semgrep-platform-v1-compat.test.ts b/sdk/typescript/tests-ts/semgrep-platform-v1-compat.test.tsnew file mode 100644index 000000000..107d8490a--- /dev/null+++ b/sdk/typescript/tests-ts/semgrep-platform-v1-compat.test.ts@@ -0,0 +1,1318 @@+import { expect, test } from "bun:test";+import { mkdtemp, rm, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { gzipSync } from "node:zlib";+import { semgrepJson } from "./support/semgrep-import-fixtures.js";+import { prepareLocalExternalImport } from "../src/external-findings-import.js";+import { prepareNormalizedLocalImport } from "../src/external-findings-local.js";+import { prepareNormalizedExternalPublication } from "../src/external-findings-publish.js";+import { bundledPluginRoot, runWorkbench } from "../src/runtime.js";+import {+ cloudRepositoryUrlKey,+ validateExternalEvidence,+} from "../src/external-import-contract.js";+import { isolatedGitReportFixture as localReportFixture } from "./external-findings-local-helpers.js";+import {+ normalizeSemgrepFindings,+ readSemgrepFindings,+} from "../src/semgrep-findings.js";+import {+ selectSemgrepPlatformFindings,+ semgrepPlatformFindingRepository,+} from "../src/semgrep-platform-findings.js";++const url = "https://github.com/example/project";+const scope = {+ deployment: "demo",+ project: { id: "10", name: "example/project", url },+ ref: "refs/heads/topic",+ product: "sast",+};+const code = {+ ref: scope.ref,+ repository: { url },+ rule: { name: "fixture.rule" },+};++test("strongly bound current SAST rows have identical selection and backlog exclusions", () => {+ const location = { file_path: "src/service.ts", line: 2, end_line: 3 };+ const rows = [+ { ...code, id: 11, severity: "unrecognized" },+ { ...code, id: 12, location: { ...location, line: "2" } },+ { ...code, id: 13, location: { ...location, end_line: "3" } },+ ];+ const read = (format: string, findings: unknown[]) =>+ normalizeSemgrepFindings(+ {+ ...scope,+ format,+ findingCount: findings.length,+ findings,+ repositoryAliases: [],+ },+ {},+ "local",+ );+ const json = rows.map((row) => JSON.stringify(row));+ const selection = read("semgrep-platform-selection/v1", json);+ const backlog = read("semgrep-platform-findings/v2", json);+ expect(selection.excluded.map((row) => row.position)).toEqual([2, 3]);+ expect(backlog.excluded).toEqual(selection.excluded);+ expect(backlog.findings).toEqual(selection.findings);+ expect(selection.findings).toHaveLength(1);+ const evidence = selection.findings[0]!.evidence;+ expect(evidence.severity).toBe("unknown");+ expect(+ JSON.parse(String(evidence.source_data?.["semgrepPlatformFindingJson"]))+ .severity,+ ).toBe("unrecognized");+ const legacy = read("semgrep-platform-findings/v1", rows);+ expect(legacy.excluded.map((row) => row.position)).toEqual([2, 3]);+ expect(legacy.findings[0]!.evidence.severity).toBe("unknown");+ const weak = read(+ "semgrep-platform-findings/v2",+ rows.map((row) => JSON.stringify({ ...row, ref: undefined })),+ );+ expect(weak.excluded).toEqual([]);+ expect(weak.findings[0]!.evidence.severity).toBe("unknown");+ expect(weak.findings[1]!.evidence.locations?.[0]?.line).toBe(2);+ expect(weak.findings[2]!.evidence.details!.code!.end_line).toBe(3);+});++test("a GitHub mapping reprojects generated severity when a backlog finding becomes selectable", async () => {+ const url = "https://git.example.test/Team/Repo";+ const native = {+ ...code,+ id: 12,+ repository: { id: 10, name: "team/repo" },+ severity: "informational",+ };+ const rows = [+ native,+ { ...native, id: 13, location: { file_path: "src/service.ts", line: "3" } },+ {+ ...native,+ id: 14,+ location: { file_path: "src/service.ts", line: 3, end_line: "5" },+ },+ ];+ const report = {+ ...scope,+ project: { ...scope.project, name: "Project", url },+ format: "semgrep-platform-findings/v2",+ repositoryAliases: [native.repository.name],+ findingCount: rows.length,+ findings: rows.map((row) => JSON.stringify(row)),+ };+ const batch = normalizeSemgrepFindings(report, {}, "local");+ expect(batch.findings[0]!.evidence).toMatchObject({+ severity: "informational",+ source_data: { format: report.format },+ });+ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: url,+ });+ const options = { ...source, repository: fixture.repository };+ const dependencies = {+ environment: fixture.environment,+ sourceRepositories: [{ url, platform: "github" as const }],+ };+ await fixture.writeJson(report);+ const file = await prepareLocalExternalImport(+ fixture.file,+ options,+ dependencies,+ );+ const direct = () =>+ prepareNormalizedLocalImport(batch, options, dependencies);+ expect(file.preview.findings[0]!.evidence).toMatchObject({+ severity: "unknown",+ source_data: { format: "semgrep-platform-selection/v1" },+ });+ for (const row of file.preview.findings.slice(1)) {+ expect(row.evidence).toMatchObject({+ severity: "informational",+ locations: [{ path: "src/service.ts", line: 3 }],+ source_data: { format: report.format },+ });+ }+ expect(file.preview.excluded).toEqual([]);+ expect((await file.import()).counts.created).toBe(rows.length);+ expect((await (await direct()).import()).counts.unchanged).toBe(rows.length);+ expect((await file.import()).counts.unchanged).toBe(rows.length);+ expect((await fixture.read()).map((row) => row.version)).toEqual([1, 1, 1]);+ batch.findings[0]!.evidence.severity = "high";+ expect((await direct()).preview.findings[0]!.evidence.severity).toBe("high");+});++test.each(["sca", "weak SAST", "selected SAST"])(+ "%s file and normalized SDK replays retain equivalent native number values once",+ async (kind) => {+ const strong = kind === "selected SAST";+ const product = kind === "sca" ? "sca" : "sast";+ const id = strong ? "12" : "1.2e1";+ const repository = strong ? JSON.stringify({ id: 10, url }) : '{"id":1e1}';+ const ref = strong ? `,"ref":${JSON.stringify(scope.ref)}` : "";+ const rule = product === "sast" ? ',"rule_name":"example.rule"' : "";+ const native = `{"id":${id}${rule},"repository":${repository},"metadata":{"source":"demo","score":10.0}${ref}}`;+ const replayRepository = strong ? repository : '{"id":10.0}';+ const equivalent = `{"metadata":{"score":1e1,"source":"demo"},"repository":${replayRepository},"id":12${rule}${ref}}`;+ const report = (row: string) => ({+ ...scope,+ format: "semgrep-platform-findings/v2",+ product,+ repositoryAliases: [],+ findingCount: 1,+ findings: [row],+ });+ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: url,+ });+ await fixture.writeJson(report(native));+ const initial = await fixture.prepare();+ expect((await initial.import()).counts.created).toBe(1);+ const result = normalizeSemgrepFindings(report(native), {}, "local");+ const data = result.findings[0]!.evidence.source_data!;+ const prepare = () => fixture.prepareNormalized(result);+ const unchanged = { created: 0, updated: 0, unchanged: 1 };+ data["semgrepPlatformFindingJson"] = equivalent;+ for (const format of strong+ ? [data["format"], undefined, "another-format"]+ : [data["format"]]) {+ if (format === undefined) delete data["format"];+ else data["format"] = format;+ expect((await (await prepare()).import()).counts).toEqual(unchanged);+ }+ await fixture.writeJson(report(equivalent));+ expect((await (await fixture.prepare()).import()).counts).toEqual(+ unchanged,+ );+ const [stored] = await fixture.read();+ expect(stored?.version).toBe(1);+ if (!strong) {+ const raw = stored!.evidence.source_data!["semgrepPlatformFindingJson"];+ expect(raw).toContain('"id":12,');+ expect(raw).toContain('"repository":{"id":10}');+ }++ data["callerAnnotation"] = { group: "demo" };+ expect((await (await prepare()).import()).counts.updated).toBe(1);+ expect((await (await prepare()).import()).counts).toEqual(unchanged);+ expect(+ (await fixture.read())[0]?.evidence.source_data?.["callerAnnotation"],+ ).toEqual({ group: "demo" });+ },+);++test.each(["sast", "ai_sast", "sca"])(+ "v1 %s requires the original title sources",+ (product) => {+ const untitled = { id: 11, ref: scope.ref, repository: { url } };+ const rows = [+ untitled,+ { id: 12, rule: { name: "named", message: "description" } },+ { id: 13, rule_message: "message" },+ ...(product === "sca"+ ? [+ {+ id: 14,+ vulnerability_identifier: "advisory",+ found_dependency: { package: "dependency" },+ rule_message: "description",+ },+ {+ id: 15,+ found_dependency: { package: "dependency" },+ rule_message: "description",+ },+ ]+ : []),+ ];+ const report = { ...scope, product, findingCount: rows.length };+ const legacy = normalizeSemgrepFindings(+ { ...report, format: "semgrep-platform-findings/v1", findings: rows },+ {},+ "local",+ );+ expect(legacy.excluded).toMatchObject([+ { position: 1, reason: "Semgrep finding title must be nonempty text." },+ ]);+ expect(legacy.findings.map((row) => row.evidence.title)).toEqual([+ "named",+ "message",+ ...(product === "sca" ? ["advisory", "dependency"] : []),+ ]);+ for (const format of [+ "semgrep-platform-findings/v2",+ ...(product === "sast" ? ["semgrep-platform-selection/v1"] : []),+ ]) {+ const current = normalizeSemgrepFindings(+ {+ ...report,+ format,+ findingCount: 1,+ findings: [JSON.stringify(untitled)],+ repositoryAliases: [],+ },+ {},+ "local",+ );+ if (product === "sast") {+ expect(current.findings).toEqual([]);+ expect(current.excluded).toEqual(legacy.excluded);+ } else {+ expect(current.findings[0]?.evidence.title).toBe("Semgrep finding 11");+ }+ }+ },+);++test("a v1 project SSH URL requires a matching GitHub Enterprise reader reference", () => {+ const source = {+ url: "https://git.example.test/team/service",+ platform: "github" as const,+ };+ const report = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ sourceRepositoryUrl: source.url + ".git",+ project: { ...scope.project, url: "[email protected]:team/service" },+ findingCount: 1,+ findings: [+ {+ id: 12,+ rule_name: "example.rule",+ repository: { name: "service.git" },+ },+ ],+ };+ const read = (sourceRepositories: (typeof source)[]) =>+ normalizeSemgrepFindings(report, { sourceRepositories }, "local");+ for (const reference of [+ source.url,+ "[email protected]:team/service",+ "ssh://[email protected]/team/service",+ ]) {+ expect(read([{ ...source, url: reference }]).findings).toHaveLength(1);+ }+ const [stored] = read([source]).findings;+ expect(semgrepPlatformFindingRepository(stored!, "semgrep", [source])).toBe(+ source.url,+ );+ stored!.evidence.source_data = { ...report, finding: report.findings[0] };+ expect(semgrepPlatformFindingRepository(stored!, "semgrep", [source])).toBe(+ source.url,+ );+ for (const repository of [+ { name: "unrelated.git" },+ { name: "service.git", id: 999 },+ ]) {+ expect(() =>+ normalizeSemgrepFindings(+ { ...report, findings: [{ ...report.findings[0], repository }] },+ { sourceRepositories: [source] },+ "local",+ ),+ ).toThrow(/repository/);+ }+ expect(() => read([])).toThrow(/repository/);+ for (const foreign of [+ "[email protected]:team/other",+ "ssh://[email protected]/team/service",+ ]) {+ expect(() => read([{ ...source, url: foreign }])).toThrow(/repository/);+ }+});++test("legacy SSH repository projections replay unchanged alongside file imports", async () => {+ const original = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ project: { ...scope.project, url: "[email protected]:example/project.git" },+ sourceRepositoryUrl: url,+ };+ const row = {+ ...code,+ id: 12,+ location: { file_path: "src\\service.ts", line: 2, end_line: 4 },+ };+ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("v1.json", source, {+ remote: url,+ });+ await fixture.writeJson({ ...original, findings: [row], findingCount: 1 });+ const file = await fixture.prepare();+ expect((await file.import()).counts.created).toBe(1);+ const batch = structuredClone(file.preview);+ const evidence = batch.findings[0]!.evidence;+ evidence.source_data = { ...original, finding: row };+ evidence.details!.repository!.url = url;+ evidence.locations = [];+ evidence.details!.code!.end_line = null;+ const prepare = () => fixture.prepareNormalized(batch);+ const direct = await prepare();+ expect(direct.preview.findings[0]!.evidence.details).toMatchObject({+ code: { end_line: 4 },+ repository: { url: url + ".git" },+ });+ expect((await direct.import()).counts.unchanged).toBe(1);+ expect((await (await fixture.prepare()).import()).counts.unchanged).toBe(1);++ const override = "https://github.com/Example/Project";+ evidence.details!.repository!.url = override;+ expect(+ (await prepare()).preview.findings[0]!.evidence.details?.repository?.url,+ ).toBe(override);+ evidence.details!.repository!.url = "https://github.com/example/other";+ await expect(prepare()).rejects.toThrow(/repository and ref/);+ // Replaying the same unmapped archive with a matching declaration keeps its version.+ const { sourceRepositoryUrl: _saved, ...unmapped } = original;+ await fixture.writeJson({ ...unmapped, findings: [row], findingCount: 1 });+ for (const [i, declared] of [undefined, url, undefined].entries()) {+ const replay = await fixture.prepare({ sourceRepositoryUrl: declared });+ expect(replay.preview.findings[0]!.evidence.source_data).not.toHaveProperty(+ "sourceRepositoryUrl",+ );+ expect((await replay.import()).counts).toMatchObject({+ created: 0,+ unchanged: i === 0 ? 0 : 1,+ });+ }+});++test("v1 files preserve native JSON numbers without witnesses and reject a rounded finding count", async () => {+ const dir = await mkdtemp(join(tmpdir(), "semgrep-v1-"));+ const path = join(dir, "report.gz");+ try {+ const first = "9007199254740992",+ second = "9007199254740993";+ const rows = [first, second].map(+ (id) =>+ `{"id":${id},"metadata":{"score":1.00000000000000001,"key":${id}},"rule":{"name":"fixture.rule"}}`,+ );+ const report = (count: string) =>+ `{"format":"semgrep-platform-findings/v1","deployment":"demo","project":{"id":9007199254740993,"name":"example/project","url":"${url}"},"ref":"refs/heads/topic","product":"sast","findings":[${rows}],"findingCount":${count}}`;+ await writeFile(path, gzipSync(report("2")));+ const result = await readSemgrepFindings(path, {}, "local");+ expect(result.excluded).toEqual([]);+ expect(new Set(result.findings.map((f) => f.source_finding_id)).size).toBe(+ 2,+ );+ for (const [index, finding] of result.findings.entries()) {+ const retained = finding.evidence.source_data!;+ expect(retained["project"]).toMatchObject({ id: second });+ expect(retained["semgrepPlatformFindingJson"]).toContain(+ '"score":1.00000000000000001',+ );+ expect(retained["semgrepPlatformFindingJson"]).toContain(+ `"key":${[first, second][index]}`,+ );+ }+ await writeFile(+ path,+ gzipSync(+ report("2").replace(+ '"metadata"',+ '"repository":{"id":9007199254740992},"metadata"',+ ),+ ),+ );+ await expect(readSemgrepFindings(path, {}, "local")).rejects.toThrow(+ "repository",+ );+ // A direct SDK input that already went through JSON.parse cannot recover an unsafe ID.+ const rounded = {+ ...scope,+ project: { ...scope.project, id: first },+ format: "semgrep-platform-findings/v1",+ findingCount: 1,+ findings: [JSON.parse('{"id":1,"repository":{"id":9007199254740993}}')],+ };+ expect(() => normalizeSemgrepFindings(rounded, {}, "local")).toThrow(+ "exact, positive",+ );+ await writeFile(path, gzipSync(report("2.00000000000000001")));+ await expect(readSemgrepFindings(path, {}, "local")).rejects.toThrow(+ "finding count",+ );+ const mixed = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ findingCount: 2,+ findings: [+ { ...code, id: 1.5 },+ { ...code, id: 12 },+ ],+ };+ await writeFile(path, gzipSync(JSON.stringify(mixed)));+ const file = await readSemgrepFindings(path, {}, "local");+ expect(file.findings).toHaveLength(1);+ expect(file.excluded).toMatchObject([{ position: 1 }]);+ expect(normalizeSemgrepFindings(mixed, {}, "local")).toEqual(file);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test("a legacy object witness cannot turn a native number into repository evidence", async () => {+ const dir = await mkdtemp(join(tmpdir(), "semgrep-v1-witness-"));+ try {+ const path = join(dir, "report.json");+ await writeFile(+ path,+ JSON.stringify({+ ...scope,+ format: "semgrep-platform-findings/v1",+ findingCount: 1,+ findings: [{ ...code, id: 12, repository: 42 }],+ numericFields: { findings: { 0: { repository: {} } } },+ }),+ );+ await expect(readSemgrepFindings(path, {}, "local")).rejects.toThrow(+ "Invalid scanner numeric fields",+ );+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test("v1 SDK rows reject numbers that cannot be retained exactly", () => {+ const report = (token: string) => ({+ ...scope,+ format: "semgrep-platform-findings/v1",+ findingCount: 1,+ findings: [+ { ...code, id: 12, metadata: { values: JSON.parse(`[${token}]`) } },+ ],+ });+ for (const token of ["9007199254740993", "1e400"]) {+ expect(() => normalizeSemgrepFindings(report(token), {}, "local")).toThrow(+ "original Semgrep export",+ );+ }+ const result = normalizeSemgrepFindings(report("0.125"), {}, "local");+ expect(+ result.findings[0]!.evidence.source_data?.["semgrepPlatformFindingJson"],+ ).toContain('"values":[0.125]');+});++test("textual decimal and exponent IDs stay specific to v1 artifacts", () => {+ const historical = normalizeSemgrepFindings(+ {+ ...scope,+ project: { ...scope.project, id: "1e1" },+ format: "semgrep-platform-findings/v1",+ findings: [{ ...code, id: "1.2e1", repository: { url, id: "1e1" } }],+ findingCount: 1,+ },+ {},+ "local",+ );+ const v2 = (id: string | number) => ({+ ...scope,+ format: "semgrep-platform-findings/v2",+ findingCount: 1,+ repositoryAliases: [],+ findings: [JSON.stringify({ ...code, id })],+ });+ const modern = normalizeSemgrepFindings(v2(12), {}, "local");+ expect(historical.excluded).toEqual([]);+ expect(historical.findings[0]!.source_finding_id).toBe(+ modern.findings[0]!.source_finding_id,+ );+ const raw =+ historical.findings[0]!.evidence.source_data?.[+ "semgrepPlatformFindingJson"+ ];+ expect(raw).toContain('"id":"1.2e1"');+ expect(raw).toContain('"id":"1e1"');+ expect(+ semgrepPlatformFindingRepository(historical.findings[0]!, "semgrep"),+ ).toBe(url);+ expect(+ normalizeSemgrepFindings(v2("1.2e1"), {}, "local").findings,+ ).toHaveLength(0);+ expect(() =>+ selectSemgrepPlatformFindings({+ deployment: scope.deployment,+ ref: scope.ref,+ projectResponse: JSON.stringify({ project: scope.project }),+ findingsResponses: [JSON.stringify({ findings: [{ ...code, id: 12 }] })],+ findingIds: ["1.2e1"],+ }),+ ).toThrow("exact, positive");+});++test("v1 files, original projected rows and v2 share one local occurrence version", async () => {+ const rows = [+ { ...code, id: 12, repository: { name: "display", id: "10" } },+ { ...code, id: "13", repository: { name: "display" } },+ ];+ // In a Git HTTP path these escapes are repository name bytes, never a query or a fragment.+ const project = { ...scope.project, url: url + "%23topic%3Fone" };+ const report = {+ ...scope,+ project,+ repositoryAliases: ["display"],+ findingCount: 2,+ };+ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: project.url,+ });+ await fixture.writeJson({+ ...report,+ format: "semgrep-platform-findings/v1",+ sourceRepositoryUrl: "https://github.com/Example/Project%23topic%3Fone.git",+ findings: rows,+ });+ const original = await fixture.prepare();+ expect((await original.import()).counts).toEqual({+ created: 2,+ updated: 0,+ unchanged: 0,+ });+ const projected = structuredClone(original.preview);+ for (const [i, finding] of projected.findings.entries()) {+ finding.evidence.source_data = {+ ...scope,+ project,+ format: "semgrep-platform-findings/v1",+ repositoryAliases: report.repositoryAliases,+ finding: rows[i],+ };+ }+ const prepareProjected = () => fixture.prepareNormalized(projected);+ const unchanged = { created: 0, updated: 0, unchanged: 2 };+ expect((await (await prepareProjected()).import()).counts).toEqual(unchanged);+ expect((await (await fixture.prepare()).import()).counts).toEqual(unchanged);+ expect((await fixture.read()).map((row) => row.version)).toEqual([1, 1]);+ await fixture.writeJson({+ ...report,+ format: "semgrep-platform-findings/v2",+ findings: rows.map((row) => JSON.stringify(row)),+ });+ const replay = await fixture.prepare();+ expect(replay.preview.findings).toEqual(original.preview.findings);+ expect((await replay.import()).counts).toEqual(unchanged);++ // A change in the retained vendor row is meaningful even when its title and location stay the same.+ projected.findings[0]!.evidence.source_data!["finding"] = {+ ...rows[0],+ metadata: { revision: 2 },+ };+ expect((await (await prepareProjected()).import()).counts).toEqual({+ created: 0,+ updated: 1,+ unchanged: 1,+ });+ expect((await fixture.read()).map((row) => row.version).sort()).toEqual([+ 1, 2,+ ]);+});++test("original v1 normalized rows can bind a name-only alias through a sibling in the same scope", async () => {+ const label = "display";+ const legacy = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ repositoryAliases: [label],+ };+ const native = [+ { ...code, id: 12, repository: { name: label } },+ { ...code, id: 13, repository: { name: label, id: scope.project.id, url } },+ ];+ const batch = normalizeSemgrepFindings(+ { ...legacy, findingCount: native.length, findings: native },+ {},+ "local",+ );+ const currentWitness = structuredClone(+ batch.findings[1]!.evidence.source_data!,+ );+ for (const [i, finding] of batch.findings.entries()) {+ // #2085 stored the vendor object without the later per-row witness string.+ finding.evidence.source_data = { ...legacy, finding: native[i] };+ finding.source_finding_id = "retained-" + i;+ }+ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("v1.json", source, {+ remote: url,+ });+ const prepare = fixture.prepareNormalized;+ const retained = {+ ...legacy,+ finding: native[0],+ sourceRepositoryUrl: url,+ operatorNote: "reviewed",+ repositoryWitnessJson: "stale",+ idEncoding: "stale",+ project: {+ ...scope.project,+ url: null,+ labels: { group: "demo", sequence: 1 },+ },+ };+ batch.findings[0]!.evidence.source_data = retained;+ batch.findings[0]!.evidence.title = "Title chosen by the caller";+ const first = await prepare(batch);+ const preparedData = first.preview.findings[0]!.evidence.source_data!;+ expect(preparedData["repositoryWitnessJson"]).toBe(+ JSON.stringify({ id: scope.project.id, name: label }),+ );+ expect(preparedData).not.toHaveProperty("idEncoding");+ expect((await first.import()).counts).toEqual({+ created: 2,+ updated: 0,+ unchanged: 0,+ });+ // A partially migrated batch retains the same independent repository proof.+ batch.findings[1]!.evidence.source_data = currentWitness;+ expect((await (await prepare(batch)).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ expect(+ (await fixture.read()).find((row) => row.sourceFindingId === "retained-0"),+ ).toMatchObject({+ version: 1,+ evidence: {+ title: "Title chosen by the caller",+ source_data: {+ operatorNote: "reviewed",+ sourceRepositoryUrl: url,+ project: { url: null, labels: { group: "demo", sequence: 1 } },+ },+ },+ });+ expect(batch.findings[0]!.evidence.source_data?.["finding"]).toEqual(+ native[0],+ );++ retained.project.labels.sequence++;+ expect((await (await prepare(batch)).import()).counts).toEqual({+ created: 0,+ updated: 1,+ unchanged: 1,+ });+ expect((await (await prepare(batch)).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ expect(+ (await fixture.read()).find((row) => row.sourceFindingId === "retained-0"),+ ).toMatchObject({+ version: 2,+ evidence: {+ source_data: { project: { labels: { group: "demo", sequence: 2 } } },+ },+ });++ for (const other of [+ { ...scope, deployment: "other" },+ { ...scope, project: { ...scope.project, id: "11" } },+ { ...scope, ref: "refs/heads/other" },+ {+ ...scope,+ project: { ...scope.project, url: "https://github.com/other/project" },+ },+ ]) {+ const foreign = structuredClone(batch);+ const witness = foreign.findings[1]!.evidence;+ witness.source_data = {+ ...legacy,+ ...other,+ finding: {+ ...native[1],+ ref: other.ref,+ repository: {+ name: label,+ id: other.project.id,+ url: other.project.url,+ },+ },+ };+ witness.branch = other.ref;+ witness.details!.repository!.url = other.project.url;+ await expect(prepare(foreign)).rejects.toThrow(/alias|witness|repository/i);+ }+});++test("a stored decimal witness remains equivalent to its canonical binding on local replay", async () => {+ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: url,+ });+ await fixture.writeJson({+ ...scope,+ format: "semgrep-platform-findings/v1",+ repositoryAliases: ["display"],+ findingCount: 2,+ findings: [+ { ...code, id: 12, repository: { name: "display", id: "1e1" } },+ { ...code, id: 13, repository: { name: "display" } },+ ],+ });+ const saved = await fixture.prepare();+ expect((await saved.import()).counts.created).toBe(2);+ const result = saved.preview;+ expect(result.excluded).toEqual([]);+ expect(result.findings).toHaveLength(2);+ const [proof, dependent] = result.findings;+ expect(proof!.evidence.source_data?.["format"]).toBe(+ "semgrep-platform-findings/v1",+ );+ expect(dependent!.evidence.source_data?.["format"]).toBe(+ "semgrep-platform-findings/v2",+ );+ for (const finding of result.findings)+ expect(semgrepPlatformFindingRepository(finding, "semgrep")).toBe(url);++ const previous = structuredClone(dependent!);+ Object.assign(previous.evidence.source_data!, {+ format: "semgrep-platform-findings/v1",+ idEncoding: "v1-decimal",+ repositoryWitnessJson: JSON.stringify({ name: "display", id: "1e1" }),+ });+ expect(semgrepPlatformFindingRepository(previous, "semgrep")).toBe(url);+ const direct = await fixture.prepareNormalized({+ read: 1,+ findings: [previous],+ excluded: [],+ });+ expect((await direct.import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 1,+ });+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 2,+ });+ expect(+ (await fixture.read()).find(+ (row) => row.sourceFindingId === previous.source_finding_id,+ )?.version,+ ).toBe(1);+});++test("a legacy report verifies each display label against that row's repository ID or URL", async () => {+ const name = "display";+ const row = (repository: Record<string, unknown>, id = 12) => ({+ ...code,+ id,+ repository,+ });+ const report = (...findings: ReturnType<typeof row>[]) => ({+ ...scope,+ format: "semgrep-platform-findings/v1",+ findings,+ findingCount: findings.length,+ });+ await using fixture = await localReportFixture(+ "v1.json",+ { provider: "semgrep", sourceKey: "demo/topic" },+ { remote: url },+ );+ await fixture.writeJson(report(row({ name, id: 10 })));+ const prepared = await fixture.prepare();+ expect((await prepared.import()).counts).toEqual({+ created: 1,+ updated: 0,+ unchanged: 0,+ });+ for (const rows of [+ [row({ name, id: 11, url })],+ [row({ name, id: 10, url: "https://github.com/example/other" })],+ [row({ name, url }), row({ name }, 13)],+ ]) {+ await fixture.writeJson(report(...rows));+ await expect(fixture.prepare()).rejects.toThrow(/repository/);+ }+});++test("v1 repository labels retain decodeURI spellings without trusting unrelated labels", () => {+ const archive = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ project: {+ ...scope.project,+ name: "logical",+ url: "https://scm.example.test/group/R%C3%A9po%2B",+ },+ findingCount: 1,+ };+ const name = "group/Répo%2B";+ const row = { ...code, id: 12, repository: { name } };+ const source = { ...archive, findings: [row] };+ for (const aliases of [{}, { repositoryAliases: [name] }]) {+ const [finding] = normalizeSemgrepFindings(+ { ...source, ...aliases },+ {},+ "local",+ ).findings;+ expect(semgrepPlatformFindingRepository(finding!, "semgrep")).toBe(+ archive.project.url,+ );+ finding!.evidence.source_data = { ...archive, ...aliases, finding: row };+ expect(semgrepPlatformFindingRepository(finding!, "semgrep")).toBe(+ archive.project.url,+ );+ }+ for (const invalid of [+ {+ ...source,+ repositoryAliases: ["group/Other%2B"],+ findings: [{ ...row, repository: { name: "group/Other%2B" } }],+ },+ { ...source, findings: [{ ...row, repository: { name, id: 11 } }] },+ {+ ...source,+ findings: [+ {+ ...row,+ repository: { name, url: "https://scm.example.test/other/repo" },+ },+ ],+ },+ {+ ...source,+ format: "semgrep-platform-findings/v2",+ findings: [JSON.stringify(row)],+ repositoryAliases: [name],+ },+ ]) {+ expect(() => normalizeSemgrepFindings(invalid, {}, "local")).toThrow(+ /repository/,+ );+ }+});++test("projected legacy textual IDs retain their verified occurrence", () => {+ const report = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ findings: [{ ...code, id: "1.2e1" }],+ findingCount: 1,+ };+ const [finding] = normalizeSemgrepFindings(report, {}, "local").findings;+ const data = finding!.evidence.source_data!;+ delete data["format"];+ expect(semgrepPlatformFindingRepository(finding!, "semgrep")).toBe(url);+ data["format"] = "semgrep-platform-findings/v2";+ expect(() => semgrepPlatformFindingRepository(finding!, "semgrep")).toThrow(+ "exact, positive",+ );+});++test("direct historic object-row evidence honors the caller's repository comparator", () => {+ const lower = "https://ghe.example.test/org/service";+ const upper = "https://ghe.example.test/ORG/Service";+ const original = { ...code, id: 12, repository: { url: upper } };+ const report = {+ ...scope,+ format: "semgrep-platform-findings/v1",+ project: { ...scope.project, url: upper },+ sourceRepositoryUrl: lower,+ };+ const [finding] = normalizeSemgrepFindings(+ { ...report, findings: [original], findingCount: 1 },+ {+ sourceRepositoryUrl: lower,+ sourceRepositories: [{ url: lower, platform: "github" }],+ },+ "local",+ ).findings;+ finding!.evidence.source_data = { ...report, finding: original };+ expect(() => semgrepPlatformFindingRepository(finding!, "semgrep")).toThrow(+ /repository/,+ );+ expect(+ semgrepPlatformFindingRepository(+ finding!,+ "semgrep",+ cloudRepositoryUrlKey,+ ),+ ).toBe(upper);+});++test("the retained repository witness stays stable when the API returns rows in another order", () => {+ const name = "display";+ const dependent = { ...code, id: 12, repository: { name } };+ const byId = { ...code, id: 13, repository: { name, id: 10 } };+ const byUrl = { ...code, id: 14, repository: { name, url } };+ const project = (witnesses: (typeof byId | typeof byUrl)[]) =>+ normalizeSemgrepFindings(+ {+ ...scope,+ format: "semgrep-platform-findings/v2",+ findingCount: 3,+ repositoryAliases: [name],+ findings: [dependent, ...witnesses].map((row) => JSON.stringify(row)),+ },+ {},+ "local",+ ).findings[0]!;+ const first = project([byId, byUrl]);+ expect(first.evidence.source_data?.["repositoryWitnessJson"]).toBeDefined();+ expect(project([byUrl, byId])).toEqual(first);+});++test("the chosen provider distinguishes unmarked v1 scopes from generic Wiz evidence", async () => {+ const options = {+ provider: "wiz" as const,+ sourceKey: "demo/topic",+ repository: url,+ };+ const dependencies = {+ environment: { CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS: "1" },+ credentials: async () => {+ throw new Error("Reached Cloud credential lookup");+ },+ };+ const report = (+ id: string | number | null,+ projectUrl: string | null,+ format?: string,+ ) => ({+ read: 1,+ excluded: [],+ findings: [+ {+ source_finding_id: "opaque",+ evidence: {+ title: "Example",+ severity: "low" as const,+ source_data: {+ ...scope,+ ...(format && { format }),+ project: { ...scope.project, id: 10, url: projectUrl },+ finding: { id },+ },+ },+ },+ ],+ });+ await expect(+ prepareNormalizedExternalPublication(+ report("1.2e1", null),+ { ...options, provider: "semgrep" },+ dependencies,+ ),+ ).rejects.toThrow("local import");+ await expect(+ prepareNormalizedExternalPublication(+ report(null, null),+ { ...options, provider: "semgrep" },+ dependencies,+ ),+ ).rejects.toThrow("local import");+ await expect(+ prepareNormalizedExternalPublication(+ report(12, url, "normalized/v1"),+ { ...options, provider: "semgrep" },+ dependencies,+ ),+ ).rejects.toThrow("local import");+ const original = report(12, null, "semgrep-platform-findings/v1");+ await expect(+ prepareNormalizedExternalPublication(original, options, dependencies),+ ).rejects.toThrow("local import");+ const unmarked = report(12, null);+ await expect(+ prepareNormalizedExternalPublication(unmarked, options, dependencies),+ ).rejects.toThrow("Reached Cloud credential lookup");+ unmarked.findings[0]!.source_finding_id =+ "semgrep-platform:" + "1".repeat(64);+ await expect(+ prepareNormalizedExternalPublication(unmarked, options, dependencies),+ ).rejects.toThrow("local import");+ const branded = report(12, url, "wiz-findings/v1");+ expect(+ semgrepPlatformFindingRepository(branded.findings[0]!, "wiz"),+ ).toBeUndefined();+ await expect(+ prepareNormalizedExternalPublication(branded, options, dependencies),+ ).rejects.toThrow("Reached Cloud credential lookup");+ const generic = report("WIZ-1", url);+ await expect(+ prepareNormalizedExternalPublication(generic, options, dependencies),+ ).rejects.toThrow("Reached Cloud credential lookup");+});+test("v2 files require exact counts and string project IDs", async () => {+ const dir = await mkdtemp(join(tmpdir(), "semgrep-v2-controls-"));+ const path = join(dir, "report.json");+ const report = (projectId: string, count: string, rows: string[]) =>+ `{"deployment":"demo","project":{"id":${projectId},"name":"example/project","url":"${url}"},"ref":"refs/heads/topic","product":"sast","repositoryAliases":[],"findingCount":${count},"format":"semgrep-platform-findings/v2","metadata":{"findingCount":1},"findings":${JSON.stringify(rows)}}`;+ const rows = [JSON.stringify({ ...code, id: 12 })];+ try {+ await writeFile(path, report('"10"', "1e0", rows));+ expect(+ (await readSemgrepFindings(path, {}, "local")).findings,+ ).toHaveLength(1);+ await writeFile(path, report('"10"', "0", []));+ expect((await readSemgrepFindings(path, {}, "local")).findings).toEqual([]);+ // An escaped format name is still the same Platform document.+ const rounded = report('"10"', "1.00000000000000001", rows);+ for (const json of [+ rounded,+ rounded.replace(+ "semgrep-platform-findings",+ "\\u0073emgrep-platform-findings",+ ),+ ]) {+ await writeFile(path, json);+ await expect(readSemgrepFindings(path, {}, "local")).rejects.toThrow(+ "finding count",+ );+ }+ for (const projectId of ["10", "10.00000000000000001"]) {+ await writeFile(path, report(projectId, "1", rows));+ await expect(readSemgrepFindings(path, {}, "local")).rejects.toThrow(+ /project ID/i,+ );+ }+ const native = semgrepJson();+ Object.assign(native.results[0]!.extra.metadata, {+ nested: { format: "semgrep-platform-findings/v2", number: 42 },+ });+ await writeFile(path, JSON.stringify(native));+ expect(+ await readSemgrepFindings(path, { sourceRepositoryUrl: url }, "local"),+ ).toEqual(+ normalizeSemgrepFindings(native, { sourceRepositoryUrl: url }, "local"),+ );+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++const historicalPaths = [+ ["src\\service.ts", null, "src\\service.ts", "all", 3, 5],+ ["src\\backlog.ts", null, "src\\backlog.ts", "backlog", "3", "5"],+ ["src\\strong.ts", null, "src\\strong.ts", "legacy", "3", "5"],+ ["src\\zero.ts", null, null, "legacy", 0, 5],+ ["src\\reversed.ts", null, null, "legacy", 3, 2],+ ["pkg:service.ts", "pkg:service.ts", null, "all", 3, 5],+ ["src/", "src/", null, "all", 3, 5],+] as const;++test.each(historicalPaths)(+ "migrates persisted Semgrep location %s once across historical and current replays",+ verifyLegacyLocationReplay,+);++async function verifyLegacyLocationReplay(+ path: string,+ oldPath: string | null,+ newPath: string | null,+ mode: "all" | "legacy" | "backlog",+ line: string | number,+ endLine: string | number,+) {+ const backlogOnly = mode === "backlog";+ const legacyOnly = mode === "legacy";+ const locations = (path: string | null) => (path ? [{ path, line: 3 }] : []);++ const source = { provider: "semgrep" as const, sourceKey: "demo/topic" };+ await using fixture = await localReportFixture("semgrep.json", source, {+ remote: url,+ });+ const row = {+ repository: code.repository,+ rule: code.rule,+ ...(backlogOnly ? {} : { ref: scope.ref }),+ id: 12,+ severity: "HIGH",+ location: { file_path: path, line, end_line: endLine },+ };+ const legacy = {+ ...scope,+ project: { ...scope.project, id: 10 },+ format: "semgrep-platform-findings/v1",+ findingCount: 1,+ findings: [row],+ };+ // The original object-row reader hashed numeric IDs, mapped HIGH to unknown, and used its hosted path rules.+ const id =+ "semgrep-platform:a7db3d7539422c25f776693a34ab2f916e31cc218f407c8c7faa7f209cad7ba3";+ const original = {+ source_finding_id: id,+ evidence: validateExternalEvidence(+ {+ title: code.rule.name,+ severity: "unknown",+ branch: scope.ref,+ locations: locations(oldPath),+ details: {+ kind: "sast",+ scanner_origin: "Semgrep",+ repository: { url },+ rule: { id: code.rule.name },+ code: { end_line: oldPath ? 5 : null },+ },+ source_data: {+ format: legacy.format,+ deployment: scope.deployment,+ project: legacy.project,+ ref: scope.ref,+ product: scope.product,+ finding: row,+ },+ },+ "local",+ ),+ };+ await runWorkbench(+ {+ pluginRoot: await bundledPluginRoot(),+ environment: fixture.environment,+ stateDirectory: fixture.stateDirectory,+ },+ ["store-external-findings"],+ JSON.stringify({+ ...source,+ repository: fixture.repository,+ findings: [original],+ }),+ );+ const [historical] = await fixture.read();+ expect(historical).toMatchObject({+ sourceFindingId: id,+ version: 1,+ evidence: { severity: "unknown", locations: locations(oldPath) },+ });+ const direct = (finding = original) =>+ fixture.prepareNormalized({ read: 1, excluded: [], findings: [finding] });+ const next = await direct();+ expect((await next.import()).counts).toEqual({+ created: 0,+ updated: 1,+ unchanged: 0,+ });+ const [stored] = await fixture.read();+ expect(stored).toMatchObject({+ id: historical!.id,+ sourceFindingId: id,+ version: 2,+ evidence: {+ severity: "high",+ locations: locations(newPath),+ details: { code: { end_line: newPath ? 5 : null } },+ },+ });+ const raw = stored!.evidence.source_data!["semgrepPlatformFindingJson"];+ expect(JSON.parse(String(raw)).location).toEqual(row.location);+ const modern = {+ ...scope,+ repositoryAliases: [],+ findingCount: 1,+ findings: [JSON.stringify(row)],+ format: "semgrep-platform-findings/v2",+ };+ const selected = { ...modern, format: "semgrep-platform-selection/v1" };+ if (backlogOnly)+ expect(() => normalizeSemgrepFindings(selected, {}, "local")).toThrow(+ /ref/u,+ );+ const unchanged = { created: 0, updated: 0, unchanged: 1 };+ for (const report of [+ legacy,+ modern,+ ...(backlogOnly ? [] : [selected]),+ legacy,+ ]) {+ await fixture.writeJson(report);+ const file = await fixture.prepare();+ if (legacyOnly && report !== legacy) {+ expect(file.preview.excluded.map((row) => row.reason)).toEqual([+ typeof endLine === "number" && endLine < Number(line)+ ? "The code end line requires a first source location line and cannot precede it."+ : "Semgrep source line must be a positive integer.",+ ]);+ expect((await file.import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 0,+ });+ } else {+ expect((await file.import()).counts).toEqual(unchanged);+ }+ if (backlogOnly && report === modern)+ expect(+ (await (await direct(file.preview.findings[0]!)).import()).counts,+ ).toEqual(unchanged);+ expect((await (await direct()).import()).counts).toEqual(unchanged);+ }+ if (legacyOnly && !newPath) {+ // Both spellings were projected by the original reader and required valid coordinates.+ for (const file_path of ["src/service.ts", "pkg:service.ts"]) {+ await fixture.writeJson({+ ...legacy,+ findings: [{ ...row, location: { ...row.location, file_path } }],+ });+ const rejected = await fixture.prepare();+ expect(rejected.preview.excluded).toHaveLength(1);+ expect((await rejected.import()).counts).toEqual({+ created: 0,+ updated: 0,+ unchanged: 0,+ });+ }+ }+ expect(await fixture.read()).toEqual([stored!]);+ if (oldPath) {+ const extended = structuredClone(original);+ extended.evidence.locations!.push({ path: "another.ts", line: 7 });+ expect(+ (await direct(extended)).preview.findings[0]!.evidence.locations,+ ).toEqual(extended.evidence.locations);+ }+ const authored = structuredClone(original);+ authored.evidence.source_data!["finding"] = {+ ...row,+ severity: "informational",+ };+ authored.evidence.severity = "informational";+ expect((await direct(authored)).preview.findings[0]!.evidence).toMatchObject({+ severity: "informational",+ locations: locations(newPath),+ details: { code: { end_line: newPath ? 5 : null } },+ });+ const custom = structuredClone(original);+ if (!legacyOnly) custom.evidence.severity = "low";+ custom.evidence.locations = [{ path: "manual.ts", line: 7 }];+ custom.evidence.details!.code!.end_line = 9;+ const manual = (await direct(custom)).preview.findings[0]!.evidence;+ expect(manual).toMatchObject({+ severity: legacyOnly ? "high" : "low",+ locations: custom.evidence.locations,+ details: { code: { end_line: 9 } },+ });+ const changed = { ...row, severity: "CRITICAL" };+ await fixture.writeJson(+ legacyOnly+ ? { ...legacy, findings: [changed] }+ : { ...modern, findings: [JSON.stringify(changed)] },+ );+ expect((await (await fixture.prepare()).import()).counts).toEqual({+ created: 0,+ updated: 1,+ unchanged: 0,+ });+ expect((await (await fixture.prepare()).import()).counts).toEqual(unchanged);+ expect(await fixture.read()).toMatchObject([+ {+ id: historical!.id,+ sourceFindingId: id,+ version: 3,+ evidence: { severity: "critical" },+ },+ ]);+}