Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

feat(import): track Black Duck SCA project-version vulnerabilities (#2098)

Michael D'Angeloea1b18abd010
diff --git a/docs/scanner-imports/blackduck.md b/docs/scanner-imports/blackduck.md
new file mode 100644
index 000000000..394cace65
--- /dev/null
+++ b/docs/scanner-imports/blackduck.md
@@ -0,0 +1,141 @@
+# Import Black Duck SCA repository vulnerabilities
+
+Use `--provider blackduck` to import vulnerable BOM components from one Black Duck
+SCA project version. Check the scan configuration to confirm which Git repository
+the project version represents. Project names, API hosts and component download
+URLs cannot establish that mapping. Aggregate product BOMs, image-only scans,
+license violations and global advisory catalogs are outside this import.
+
+## Export a complete collection
+
+Use a read-only token and request the project version’s `vulnerable-components`
+relation with media type `application/vnd.blackducksoftware.bill-of-materials-6+json`.
+The importer requires BOM-6. If the deployment serves only BOM-8 or another
+inventory format, stop the export.
+
+Install the vendor’s `blackduck` Python client in a trusted virtual environment
+outside the checkout. Set `BLACKDUCK_URL` to the deployment’s HTTPS URL,
+`BLACKDUCK_TOKEN` to the read-only token and `BLACKDUCK_PROJECT_ID` and
+`BLACKDUCK_VERSION_ID` to the two UUIDs. The client exchanges the token before
+reading the collection, so disable redirects for the entire session.
+
+Save the script outside the checkout and run it with
+`/path/to/venv/bin/python -I /private/path/export.py` to keep checkout modules
+and `PYTHONPATH` off the import path. Redirect stdout to a private temporary file
+and rename it after the script succeeds.
+
+```python
+import json
+import os
+from hashlib import sha256
+from urllib.parse import parse_qs, urlsplit
+from uuid import UUID
+from blackduck import Client
+
+base = os.environ["BLACKDUCK_URL"].rstrip("/")
+parts = urlsplit(base)
+if (parts.scheme != "https" or not parts.hostname or parts.username is not None
+ or parts.password is not None or parts.query or parts.fragment):
+ raise ValueError("Use your trusted HTTPS Black Duck URL")
+project = UUID(os.environ["BLACKDUCK_PROJECT_ID"])
+version = UUID(os.environ["BLACKDUCK_VERSION_ID"])
+collection = f"{project}/versions/{version}/vulnerable-bom-components"
+url = f"{base}/api/projects/{collection}"
+paths = {f"{parts.path}/api/{relation}/{collection}" for relation in ("projects", "project")}
+
+def authority(url):
+ return url.netloc.lower().removesuffix(":443")
+
+client = Client(base_url=base + "/", token=os.environ["BLACKDUCK_TOKEN"])
+client.session.max_redirects = 0
+media_type = "application/vnd.blackducksoftware.bill-of-materials-6+json"
+items = []
+seen = set()
+total = None
+while True:
+ offset = len(items)
+ response = client.session.get(url, params={"offset": offset, "limit": 250},
+ headers={"Accept": media_type}, allow_redirects=False)
+ if response.status_code != 200:
+ raise ValueError(f"Black Duck returned HTTP {response.status_code}; refusing partial export")
+ received_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+ if received_type != media_type:
+ raise ValueError("Expected a BOM-6 response")
+ page = response.json()
+ href = urlsplit(page["_meta"]["href"])
+ if (href.scheme != "https" or authority(href) != authority(parts)
+ or href.fragment or href.path not in paths):
+ raise ValueError("Page identifies a different Black Duck collection")
+ query = parse_qs(href.query, keep_blank_values=True)
+ if "offset" in query and query["offset"] != [str(offset)]:
+ raise ValueError("Page identifies a different or ambiguous offset")
+ batch, declared = page["items"], page["totalCount"]
+ if not isinstance(batch, list) or type(declared) is not int or declared < 0:
+ raise ValueError("Invalid Black Duck collection")
+ if total is not None and declared != total:
+ raise ValueError("Collection changed; retry the export")
+ total = declared
+ for row in batch:
+ digest = sha256(json.dumps(row, sort_keys=True).encode()).digest()
+ if digest in seen:
+ raise ValueError("Repeated row; retry the export")
+ seen.add(digest)
+ items.extend(batch)
+ if len(items) == total:
+ if any(link.get("rel") == "next" for link in page["_meta"].get("links", [])):
+ raise ValueError("Final page has a next link; retry the export")
+ break
+ if not batch or len(items) > total:
+ raise ValueError("Incomplete or inconsistent Black Duck collection")
+print(json.dumps({"_meta": {"href": url}, "totalCount": total, "items": items}))
+```
+
+Keep the original rows and collection total. If the BOM changes during offset
+pagination, export it again after the scan finishes. To import only selected
+occurrences, supply an array of native rows that each identify the same project
+version.
+
+## Preview and repeat
+
+```bash
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+codex-security publish findings blackduck.json \
+ --to local --repository ./project --provider blackduck \
+ --source-repository-url https://github.com/example/project \
+ --source-key blackduck/deployment-alias/project-id/version-id \
+ --dry-run --format json
+```
+
+Check the source, destination and excluded rows before repeating the command
+without `--dry-run`. Reuse the source key for later exports from this deployment,
+project and version. For Cloud, select an authorized GitHub repository with
+`--to cloud` on a deployment that accepts `blackduck`. Reading a saved report
+requires no Black Duck login. Local imports also require no Cloud login.
+
+If an interrupted Cloud upload reports `result.savedSubmission`, keep its
+checkpoint and use the same build, state directory, account and import settings.
+Preview the original export with `--dry-run --format json`. Check `accountId`
+and `destination`. When `resumed` is false, review the new upload before approving it.
+For `prepareNormalizedExternalPublication`, pass your original normalized
+`ExternalFindings` and check `preview.resumed` before calling `publish()`.
+Different normalized findings prepare a new upload.
+
+Cloud checks retained and declared source repository URLs against the selected
+repository. For local SDK imports, reader-supplied repository references must
+agree with the repository on the findings. Local imports also check comparable
+Git remotes on the selected checkout. Select the `blackduck` provider for
+retained Black Duck BOM records. Caller-authored text and opaque IDs alone
+cannot establish repository ownership.
+
+Each occurrence is identified by its project version, component version, origin,
+advisory source and advisory name. Reimporting updates the occurrence when its
+evidence changes. Rows absent from a later export remain open.
+
+Supported package URLs and origin coordinates supply the package identity.
+`advisory_ids` preserves the vendor’s `vulnerabilityName` and any distinct
+`relatedVulnerability` value verbatim, including Black Duck resource URLs.
+The native row retains its CWE, matched-files link and remediation status.
+Findings start unassessed, with no inferred fix, Git revision or source location.
+
+References: [official Python REST client](https://github.com/blackducksoftware/hub-rest-api-python),
+[vendor example of vulnerable BOM components](https://github.com/blackducksoftware/hub-client-go/blob/5f78f7257c00fe9cebabf1bf89a6fc36a4d1f095/hubapi/testdata/vulnerableBomComponents.json).
diff --git a/docs/scanner-imports/schema-guide.md b/docs/scanner-imports/schema-guide.md
index 3c075e858..c2bfb4feb 100644
--- a/docs/scanner-imports/schema-guide.md
+++ b/docs/scanner-imports/schema-guide.md
@@ -29,10 +29,11 @@ to investigate records together, not instructions to merge them.
| [GitHub Dependabot repository REST alerts](github-dependabot.md) | Host, repository and alert number | Host, repository and Dependabot family |
| [GitHub saved `import github` output](../../sdk/typescript/docs/cli.md#import-github-findings-locally-or-to-cloud) | Host, repository, alert number and hash of selected ref | Host, repository and code-scanning family |
| [GitHub saved `import github-advisories` output](../../sdk/typescript/docs/cli.md#import-ghsa-advisories-separately) | Host, repository **or** global scope, and GHSA ID | Separate advisory stream from alerts |
+| [Black Duck BOM-6 collection or selected rows](blackduck.md) | Project version, component version, origin, advisory source and advisory name | Deployment, project and version |
Within **one input**, duplicate IDs are ambiguous, not corroboration. Wiz and
GitHub reject a selection with duplicate accepted IDs. Endor, Snyk and Semgrep
-exclude every record with the colliding identity. Inspect the source and select
+exclude every record with the colliding identity. Black Duck rejects duplicate occurrences in a complete collection, and excludes all colliding rows in an explicit selection. Inspect the source and select
the intended occurrence; don't rename records simply to make them import. Across
**separate local imports**, changed evidence updates the same record; omission
does not delete or resolve it. Cloud publication sends an expected version;
diff --git a/plugins/codex-security/skills/publish-findings/SKILL.md b/plugins/codex-security/skills/publish-findings/SKILL.md
index b675898f0..90817e8c2 100644
--- a/plugins/codex-security/skills/publish-findings/SKILL.md
+++ b/plugins/codex-security/skills/publish-findings/SKILL.md
@@ -35,6 +35,10 @@ Local records remain unassessed source evidence, separate from `findings list` a
Use `--provider inspector` and `--source-repository-url` with a complete Inspector2 ListFindings export for one Code Security repository. If it contains only a project ARN and name, pass the full `--inspector-project-arn ARN` verified for that Git URL in the SCM integration. Supply the same ARN when resuming a pending Cloud submission. Self-managed GitLab is supported locally.
+## Black Duck SCA project-version vulnerabilities
+
+Use `--provider blackduck` for a BOM-6 vulnerable-components export from one project version. Supply `--source-repository-url` after verifying the project version maps to that repository. Keep the same source key on replay and preview the destination before importing.
+
## Endor Labs findings
For Endor Labs imports, prefer native Finding JSON from authenticated `endorctl`, scoped to one project and context. Omit `--field-mask` and fetch all pages with `--list-all`:
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 070853478..22346abad 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -691,6 +691,11 @@ the repository by an ARN and name, pass `--inspector-project-arn ARN` with the A
you verified for that Git URL in the SCM integration. See the
[Inspector guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md).
+For Black Duck SCA, use `--provider blackduck` with a BOM-6 vulnerable-components
+export for one project version. Map that version to its source repository with
+`--source-repository-url`. See the
+[Black Duck guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/blackduck.md).
+
For OpenGrep, use `--provider opengrep` with native JSON or gzip and an explicit
`--source-repository-url`. Local and Cloud imports retain unassessed OpenGrep
evidence through the existing Semgrep source-provider contract. See the
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 0c40b04cd..99f7ed083 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1307,6 +1307,7 @@ repository path instead of a Cloud repository ID or URL. Supported inputs includ
Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
[Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
[Amazon Inspector repository findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md),
+[Black Duck SCA project-version vulnerabilities](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/blackduck.md),
[Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
[OpenGrep native JSON](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md),
[GitHub Dependabot repository alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md),
diff --git a/sdk/typescript/schemas/external-findings.schema.json b/sdk/typescript/schemas/external-findings.schema.json
index 8add329f4..5eadb5b1a 100644
--- a/sdk/typescript/schemas/external-findings.schema.json
+++ b/sdk/typescript/schemas/external-findings.schema.json
@@ -378,7 +378,15 @@
"additionalProperties": false,
"properties": {
"provider": {
- "enum": ["wiz", "endor", "snyk", "github", "semgrep", "inspector"],
+ "enum": [
+ "wiz",
+ "endor",
+ "snyk",
+ "github",
+ "semgrep",
+ "inspector",
+ "blackduck"
+ ],
"title": "Provider",
"type": "string"
},
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index 69af86328..dcd2621bb 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -30,6 +30,7 @@ const distModules = [
"scanner-import",
"inspector-findings",
"snyk-findings",
+ "scanner-repository-url",
"semgrep-findings",
"native-json-findings",
"opengrep-findings",
@@ -38,6 +39,7 @@ const distModules = [
"external-import-models",
"external-imports-feature",
"endor-findings",
+ "blackduck-findings",
"wiz-csv",
"wiz-findings",
"codex-prompt",
diff --git a/sdk/typescript/src/blackduck-findings.ts b/sdk/typescript/src/blackduck-findings.ts
new file mode 100644
index 000000000..61503861a
--- /dev/null
+++ b/sdk/typescript/src/blackduck-findings.ts
@@ -0,0 +1,521 @@
+import { z } from "zod";
+import { CodexSecurityError } from "./errors.js";
+import type { Provider } from "./external-import-models.js";
+import {
+ type ExternalImportTarget,
+ cloudRepositoryUrlKey,
+ repositoryUrlKey,
+ validateExternalEvidence,
+} from "./external-import-contract.js";
+import type {
+ ExternalFinding,
+ ExternalFindings,
+ ExternalSourceRepository,
+} from "./external-findings.js";
+import { canonicalJson, isRecord } from "./record.js";
+import {
+ array,
+ normalizeRecords,
+ readScannerJson,
+ record,
+ requiredText,
+ stableId,
+ text,
+} from "./scanner-import.js";
+import { FailureSeveritySchema } from "./scan-settings.js";
+import { declaredScannerRepositoryUrl } from "./scanner-repository-url.js";
+
+const format = "blackduck-bom-6";
+const componentVersionPath = /^components\/[^/]+\/versions\/[^/]+$/u;
+const nativeId = /^blackduck-bom:[a-f0-9]{64}$/u;
+
+export function projectedBlackDuckRepositoryUrl(
+ finding: ExternalFinding,
+ target: ExternalImportTarget,
+): string | undefined {
+ if (!nativeId.test(finding.source_finding_id)) return;
+ const url = finding.evidence.source_data?.["sourceRepositoryUrl"];
+ if (typeof url === "string")
+ return declaredScannerRepositoryUrl(url, "Black Duck", target);
+ return finding.evidence.details?.repository?.url ?? undefined;
+}
+
+function hasBlackDuckEvidence(data: unknown): boolean {
+ if (!isRecord(data)) return false;
+ return (
+ data["format"] === format ||
+ [data, data["row"]].some((row) => {
+ if (!isRecord(row) || !isRecord(row["vulnerabilityWithRemediation"]))
+ return false;
+ const resource = parseApiResource(text(row["componentVersion"]));
+ return resource !== undefined && componentVersionPath.test(resource.path);
+ })
+ );
+}
+
+function retainedRepository(
+ provider: Provider,
+ finding: ExternalFinding,
+ target: ExternalImportTarget,
+): { url: string; projectVersion?: string } | undefined {
+ const {
+ source_finding_id: id,
+ evidence: { source_data: data },
+ } = finding;
+ const nativeEvidence = hasBlackDuckEvidence(data);
+ if (provider !== "blackduck") {
+ if (nativeEvidence)
+ throw new CodexSecurityError(
+ "Retained Black Duck evidence requires the blackduck provider.",
+ );
+ const url = projectedBlackDuckRepositoryUrl(finding, target);
+ return url ? { url } : undefined;
+ }
+ const native = nativeEvidence || nativeId.test(id);
+ if (native && (!isRecord(data) || !isRecord(data["row"])))
+ throw new Error("Expected retained Black Duck BOM occurrence evidence.");
+ if (!isRecord(data) || (!native && !("sourceRepositoryUrl" in data))) return;
+ const url = declaredScannerRepositoryUrl(
+ data["sourceRepositoryUrl"],
+ "Black Duck",
+ target,
+ );
+ if (!native) return { url };
+ const resource = apiResource(
+ data["projectVersionUrl"],
+ "retained project-version URL",
+ );
+ if (
+ !/^projects\/[^/]+\/versions\/[^/]+$/u.test(resource.path) ||
+ resource.query.size
+ )
+ throw new Error("Invalid retained Black Duck project-version URL.");
+ const projectVersion = `${resource.base}/${resource.path}`;
+ const actual = occurrenceId(
+ scopedRow(data["row"], projectVersion, false),
+ projectVersion,
+ );
+ if (id !== actual)
+ throw new Error(
+ "Black Duck source finding ID contradicts the retained native occurrence.",
+ );
+ return { url, projectVersion };
+}
+
+export function blackDuckReportRepositories(
+ provider: Provider,
+ findings: readonly ExternalFinding[],
+ target: ExternalImportTarget,
+ sameRepositories: (urls: Iterable<string>) => boolean = (urls) =>
+ new Set(
+ Array.from(
+ urls,
+ target === "cloud" ? cloudRepositoryUrlKey : repositoryUrlKey,
+ ),
+ ).size <= 1,
+): Map<string, ExternalSourceRepository> {
+ const repositories = new Map<string, ExternalSourceRepository>();
+ const projects = new Set<string>();
+ const sources = new Set<string>();
+ for (const finding of findings) {
+ const { source_finding_id: id, evidence } = finding;
+ const retained = retainedRepository(provider, finding, target);
+ const declared = evidence.details?.repository?.url;
+ if (declared) sources.add(declared);
+ if (!retained) continue;
+ sources.add(retained.url);
+ if (
+ declared &&
+ declared !== retained.url &&
+ !sameRepositories([declared, retained.url])
+ )
+ throw new Error(
+ "Retained scanner repository does not match the normalized evidence repository.",
+ );
+ if (retained.projectVersion) projects.add(retained.projectVersion);
+ repositories.set(id, { url: retained.url });
+ }
+ if (provider !== "blackduck") return repositories;
+ if (
+ projects.size > 1 ||
+ ((target === "local" || projects.size > 0) &&
+ sources.size > 1 &&
+ !sameRepositories(sources))
+ )
+ throw new Error(
+ "Black Duck occurrences must belong to the same project version and source repository.",
+ );
+ return repositories;
+}
+
+function parseApiResource(href: string | null) {
+ const url = href && URL.parse(href);
+ const parts = url && /^(.*\/api)\/(.+?)\/?$/u.exec(url.pathname);
+ if (
+ !url ||
+ !parts ||
+ !["http:", "https:"].includes(url.protocol) ||
+ url.username ||
+ url.password ||
+ url.hash
+ )
+ return;
+ return {
+ base: url.origin + parts[1],
+ path: parts[2]!,
+ query: url.searchParams,
+ };
+}
+
+function apiResource(href: unknown, label: string) {
+ const resource = parseApiResource(requiredText(href, label));
+ if (!resource)
+ throw new Error(
+ `Expected a credential-free Black Duck API URL for ${label}.`,
+ );
+ return resource;
+}
+
+function links(meta: unknown): Record<string, unknown>[] {
+ if (meta === undefined) return [];
+ const value = record(meta, "Black Duck _meta")["links"];
+ return value === undefined
+ ? []
+ : array(value, "Black Duck _meta.links").map((entry) =>
+ record(entry, "Black Duck link"),
+ );
+}
+
+function collectionScope(collection: Record<string, unknown>) {
+ const meta = record(collection["_meta"], "Black Duck collection _meta");
+ const resource = apiResource(meta["href"], "collection href");
+ const project =
+ /^projects?\/([^/]+)\/versions\/([^/]+)\/vulnerable-bom-components$/u.exec(
+ resource.path,
+ );
+ if (!project)
+ throw new Error(
+ "Expected a Black Duck project-version vulnerable-bom-components collection.",
+ );
+ if (
+ resource.query.getAll("offset").some((offset) => !/^0+$/u.test(offset)) ||
+ links(meta).some((link) =>
+ ["next", "prev", "previous"].includes(String(link["rel"])),
+ )
+ )
+ throw new Error(
+ "Incomplete Black Duck collection page. Supply a complete export or explicitly selected rows.",
+ );
+ return `${resource.base}/projects/${project[1]}/versions/${project[2]}`;
+}
+
+function projectReference(
+ href: unknown,
+ relation: "remediation" | "matched-files",
+) {
+ const label =
+ relation === "remediation" ? "remediation URL" : "matched-files link";
+ const resource = apiResource(href, label);
+ const match =
+ /^(projects\/[^/]+\/versions\/[^/]+)\/(components\/[^/]+\/versions\/[^/]+)(?:\/origins\/([^/]+))?\/(matched-files|vulnerabilities\/[^/]+\/remediation)$/u.exec(
+ resource.path,
+ );
+ if (!match || !match[4]!.endsWith(relation))
+ throw new Error(`Invalid Black Duck project-version ${label}.`);
+ return {
+ scope: `${resource.base}/${match[1]}`,
+ component: `${resource.base}/${match[2]}`,
+ origin: match[3],
+ };
+}
+
+const bomComponent = z.object(
+ {
+ vulnerabilityWithRemediation: z.custom<Record<string, unknown>>(
+ isRecord,
+ "Black Duck vulnerabilityWithRemediation must be an object.",
+ ),
+ },
+ "Black Duck BOM component must be an object.",
+);
+
+function scopedRow(
+ value: unknown,
+ scope: string | undefined,
+ selected: boolean,
+) {
+ const row = isRecord(value) ? value : {};
+ const meta = row["_meta"];
+ const declared = isRecord(meta) ? meta["links"] : undefined;
+ const matched = (Array.isArray(declared) ? declared : [])
+ .filter(
+ (link): link is Record<string, unknown> =>
+ isRecord(link) && link["rel"] === "matched-files",
+ )
+ .map((link) => projectReference(link["href"], "matched-files"));
+ if (isRecord(meta) && meta["href"] !== undefined)
+ matched.push(projectReference(meta["href"], "remediation"));
+ if (selected && !matched.length)
+ throw new Error(
+ "Each selected Black Duck row must identify its project version with a remediation or matched-files link.",
+ );
+ for (const reference of matched) {
+ if (scope !== undefined && scope !== reference.scope)
+ throw new Error(
+ "Black Duck rows must belong to the same project version and server as the collection or selection.",
+ );
+ scope = reference.scope;
+ }
+ const component = bomComponent.safeParse(value);
+ return {
+ row,
+ matched,
+ scope,
+ // Shape errors are row exclusions; project-scope errors abort the report.
+ get vulnerability() {
+ if (!component.success)
+ throw new Error(component.error.issues[0]!.message);
+ return component.data.vulnerabilityWithRemediation;
+ },
+ };
+}
+
+function occurrenceId(
+ { row, vulnerability, matched }: ReturnType<typeof scopedRow>,
+ projectVersion: string,
+) {
+ const resource = apiResource(row["componentVersion"], "componentVersion");
+ const component = `${resource.base}/${resource.path}`;
+ if (
+ !componentVersionPath.test(resource.path) ||
+ resource.base !==
+ projectVersion.slice(0, projectVersion.lastIndexOf("/projects/"))
+ )
+ throw new Error(
+ "Black Duck componentVersion must identify a component version on the same server.",
+ );
+ const origins = new Set<string>();
+ for (const reference of matched) {
+ if (reference.component !== component)
+ throw new Error(
+ "Black Duck project-version link contradicts componentVersion.",
+ );
+ if (reference.origin) origins.add(reference.origin);
+ }
+ for (const link of links(row["_meta"]).filter(
+ (entry) => entry["rel"] === "vulnerabilities",
+ )) {
+ const reference = apiResource(link["href"], "vulnerabilities link");
+ const match =
+ /^(components\/[^/]+\/versions\/[^/]+)(?:\/origin\/([^/]+))?\/vulnerabilities$/u.exec(
+ reference.path,
+ );
+ if (!match) continue;
+ if (`${reference.base}/${match[1]}` !== component)
+ throw new Error(
+ "Black Duck vulnerabilities link contradicts componentVersion.",
+ );
+ if (match[2]) origins.add(match[2]);
+ }
+ const [origin] = origins;
+ if (!origin || origins.size !== 1)
+ throw new Error(
+ "Black Duck row must identify one unambiguous component-version origin.",
+ );
+ const source = requiredText(
+ vulnerability["source"],
+ "Black Duck advisory source",
+ );
+ if (source !== "BDSA" && source !== "NVD")
+ throw new Error(`Unsupported Black Duck advisory source: ${source}.`);
+ return stableId("blackduck-bom", [
+ projectVersion,
+ component,
+ origin,
+ source,
+ requiredText(
+ vulnerability["vulnerabilityName"],
+ "Black Duck vulnerability name",
+ ),
+ ]);
+}
+
+const nameVersionForges = new Map([
+ ["npmjs", "npm"],
+ ["pypi", "pypi"],
+ ["nuget", "nuget"],
+ ["rubygems", "gem"],
+ ["crates", "cargo"],
+]);
+
+function packageUrlName(ecosystem: string, parts: string[]) {
+ if (parts.some((part) => !part || part.includes("/"))) return;
+ if (ecosystem === "maven" || ecosystem === "composer")
+ return parts.length === 2
+ ? parts.join(ecosystem === "maven" ? ":" : "/")
+ : undefined;
+ if (
+ parts.length === 1 ||
+ ecosystem === "golang" ||
+ ecosystem === "generic" ||
+ (parts.length === 2 && ecosystem === "npm" && parts[0]!.startsWith("@"))
+ )
+ return parts.join("/");
+}
+
+function originPackage(row: Record<string, unknown>) {
+ const origin = text(row["componentVersionOriginName"])?.toLowerCase();
+ const id = text(row["componentVersionOriginId"]) ?? "";
+ if (origin === "maven") {
+ const coordinate = /^([^:\s/]+:[^:\s/]+):([^:\s/]+)$/u.exec(id);
+ if (coordinate)
+ return {
+ name: coordinate[1]!,
+ ecosystem: origin,
+ installed_version: coordinate[2]!,
+ };
+ }
+ const ecosystem = nameVersionForges.get(origin ?? "");
+ if (ecosystem) {
+ const coordinate = /^(?:(@[^/\s]+)\/)?([^/\s]+)\/([^/\s]+)$/u.exec(id);
+ if (coordinate && (!coordinate[1] || ecosystem === "npm"))
+ return {
+ name: id.slice(0, id.lastIndexOf("/")),
+ ecosystem,
+ installed_version: coordinate[3]!,
+ };
+ }
+}
+
+function blackDuckPackages(row: Record<string, unknown>) {
+ const origin = originPackage(row);
+ const purl =
+ /^pkg:([a-z][a-z0-9.+-]*)\/((?:@[^/@?#]+\/)?[^@?#]+)(?:@([^@?#]+))?(?:[?#].*)?$/iu.exec(
+ text(row["packageUrl"]) ?? "",
+ );
+ if (purl) {
+ try {
+ const ecosystem = purl[1]!.toLowerCase();
+ const name = packageUrlName(
+ ecosystem,
+ purl[2]!.split("/").map(decodeURIComponent),
+ );
+ if (name) {
+ if (!purl[3] && origin?.ecosystem === ecosystem && origin.name === name)
+ return [origin];
+ return [
+ {
+ name,
+ ecosystem,
+ installed_version: purl[3]
+ ? decodeURIComponent(purl[3])
+ : text(row["componentVersionName"]),
+ },
+ ];
+ }
+ } catch {
+ // A malformed escape does not invalidate the native origin coordinate.
+ }
+ }
+
+ return origin ? [origin] : [];
+}
+
+export function normalizeBlackDuckFindings(
+ input: unknown,
+ sourceRepositoryUrl: string,
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
+ const repository = declaredScannerRepositoryUrl(
+ sourceRepositoryUrl,
+ "Black Duck",
+ target,
+ );
+ const selected = Array.isArray(input);
+ let scope: string | undefined;
+ let items: unknown[];
+ if (selected) {
+ items = input;
+ } else {
+ const collection = record(input, "Black Duck collection");
+ items = array(collection["items"], "Black Duck items");
+ scope = collectionScope(collection);
+ if (collection["totalCount"] !== items.length)
+ throw new Error(
+ "Incomplete Black Duck collection: totalCount must equal the number of items. Supply a complete export or explicitly selected rows.",
+ );
+ }
+
+ const rows = items.map((value) => {
+ const entry = scopedRow(value, scope, selected);
+ scope = entry.scope;
+ return entry;
+ });
+ if (!scope)
+ throw new Error(
+ "An empty Black Duck selection cannot identify a project version. Supply its complete collection envelope.",
+ );
+ const projectVersion = scope;
+ const result = normalizeRecords(
+ rows,
+ ({ row, vulnerability }) => {
+ const advisory = requiredText(
+ vulnerability["vulnerabilityName"],
+ "Black Duck vulnerability name",
+ );
+ const name = requiredText(
+ row["componentName"],
+ "Black Duck component name",
+ );
+ const severity = text(vulnerability["severity"])?.toLowerCase();
+ const related = text(vulnerability["relatedVulnerability"]);
+ return validateExternalEvidence(
+ {
+ title: `${advisory} in ${name}`,
+ description: text(vulnerability["description"]),
+ severity: FailureSeveritySchema.safeParse(severity).data ?? "unknown",
+ advisory_ids:
+ related && related !== advisory ? [advisory, related] : [advisory],
+ packages: blackDuckPackages(row),
+ source_data: {
+ format,
+ sourceRepositoryUrl: repository,
+ projectVersionUrl: projectVersion,
+ row: structuredClone(row),
+ },
+ },
+ target,
+ );
+ },
+ (entry) => occurrenceId(entry, projectVersion),
+ target,
+ );
+ if (!selected) {
+ // normalizeRecords excludes every collision. An unidentified row can also
+ // repeat across pages, so compare its original JSON when it has no ID.
+ const seen = new Set<string>();
+ for (const excluded of result.excluded) {
+ const key =
+ excluded.source_finding_id ??
+ canonicalJson(items[excluded.position - 1]);
+ if (seen.has(key))
+ throw new CodexSecurityError(
+ "Duplicate row in a collection with a declared total; pages may overlap. Retrieve the complete export again.",
+ );
+ seen.add(key);
+ }
+ }
+ return result;
+}
+
+export async function readBlackDuckFindings(
+ path: string,
+ sourceRepositoryUrl: string,
+ target: ExternalImportTarget = "cloud",
+): Promise<ExternalFindings> {
+ return normalizeBlackDuckFindings(
+ await readScannerJson(path),
+ sourceRepositoryUrl,
+ target,
+ );
+}
diff --git a/sdk/typescript/src/external-findings-import.ts b/sdk/typescript/src/external-findings-import.ts
index f2a402522..599c92133 100644
--- a/sdk/typescript/src/external-findings-import.ts
+++ b/sdk/typescript/src/external-findings-import.ts
@@ -11,7 +11,10 @@ import {
prepareLocalImport,
type LocalExternalImportDependencies,
} from "./external-findings-local.js";
-import { snapshotImportOptions } from "./external-findings.js";
+import {
+ snapshotImportOptions,
+ snapshotSourceRepositories,
+} from "./external-findings.js";
import { abortable } from "./targets.js";
import { requireExternalImports } from "./external-imports-feature.js";
@@ -24,6 +27,9 @@ export async function prepareLocalExternalImport(
dependencies.signal?.throwIfAborted();
requireExternalImports(dependencies.environment);
const settings = snapshotImportOptions(options);
+ const readerSources = snapshotSourceRepositories(
+ dependencies.sourceRepositories,
+ );
const parsed = await abortable(
() => readExternalFindings(path, settings, "local"),
dependencies.signal,
@@ -37,7 +43,7 @@ export async function prepareLocalExternalImport(
// The Cloud reader allows custom GitHub casing. Local provenance must also
// agree with the caller's source URL when the checkout has no remote.
const source = settings.sourceRepositoryUrl!;
- const knownGitHub = dependencies.sourceRepositories?.some(
+ const knownGitHub = readerSources.some(
({ url, platform }) =>
platform === "github" &&
cloudRepositoryUrlKey(url) === cloudRepositoryUrlKey(source),
@@ -58,13 +64,12 @@ export async function prepareLocalExternalImport(
})),
];
}
- const { environment, ...workbench } = dependencies;
- return prepareLocalImport(parsed.findings, normalizedOptions, {
- ...workbench,
- environment,
- sourceRepositories: [
- ...(dependencies.sourceRepositories ?? []),
- ...sourceRepositories,
- ],
- });
+ const { environment, runWorkbench, signal } = dependencies;
+ return prepareLocalImport(
+ parsed.findings,
+ normalizedOptions,
+ { environment, runWorkbench, signal },
+ readerSources,
+ sourceRepositories,
+ );
}
diff --git a/sdk/typescript/src/external-findings-local.ts b/sdk/typescript/src/external-findings-local.ts
index 1916e8897..863f3b270 100644
--- a/sdk/typescript/src/external-findings-local.ts
+++ b/sdk/typescript/src/external-findings-local.ts
@@ -9,6 +9,7 @@ import {
} from "./external-imports-feature.js";
import {
snapshotImportOptions,
+ snapshotSourceRepositories,
type ExternalFindings,
type ExternalSourceRepository,
} from "./external-findings.js";
@@ -21,6 +22,11 @@ import type {
ExternalFindingEvidence,
Provider,
} from "./external-import-models.js";
+import { localFindingRepositories } from "./external-findings-read.js";
+import {
+ blackDuckReportRepositories,
+ projectedBlackDuckRepositoryUrl,
+} from "./blackduck-findings.js";
import { isGitHubCloudHost, parseGitRemote } from "./git-remote.js";
import { inspectorReportRepository } from "./inspector-findings.js";
import { isRecord } from "./record.js";
@@ -118,11 +124,17 @@ const gitTransportPorts: Readonly<Record<string, string>> = {
};
/** Compare transport forms without changing retained scanner evidence. */
+interface RemoteRepositoryIdentity {
+ key: string;
+ account?: string;
+ homeRelative?: boolean;
+}
+
function remoteRepository(
value: string,
provider: Provider,
bound: boolean,
-): { key: string; account?: string; homeRelative?: boolean } | undefined {
+): RemoteRepositoryIdentity | undefined {
if (/^[A-Za-z]:[\\/]/u.test(value)) return undefined;
const transport = bound
? /^(?:ssh|git\+ssh|ssh\+git|git):\/\/([^/]*)(.*)$/isu.exec(value)
@@ -224,6 +236,62 @@ function remoteRepository(
};
}
+function matchingRemote(
+ left: RemoteRepositoryIdentity,
+ right: RemoteRepositoryIdentity,
+) {
+ return (
+ left.key === right.key &&
+ (left.homeRelative === undefined ||
+ right.homeRelative === undefined ||
+ left.homeRelative === right.homeRelative) &&
+ ((left.homeRelative === false && right.homeRelative === false) ||
+ left.account === undefined ||
+ right.account === undefined ||
+ left.account === right.account)
+ );
+}
+
+function localRepositoryPlatform(
+ provider: Provider,
+ sources: readonly ExternalSourceRepository[],
+ bound: boolean,
+) {
+ const githubKey = (url: string) =>
+ remoteRepository(url, "github", bound)?.key;
+ const githubRepositories = new Set(
+ sources.flatMap((source) => {
+ if (source.platform !== "github") return [];
+ const key = githubKey(source.url);
+ return key === undefined ? [] : [key];
+ }),
+ );
+ return (source: ExternalSourceRepository): Provider => {
+ if (source.platform === "github") return "github";
+ if (githubRepositories.size === 0) return provider;
+ const key = githubKey(source.url);
+ return key !== undefined && githubRepositories.has(key)
+ ? "github"
+ : provider;
+ };
+}
+
+function sameBlackDuckRepositories(
+ remotes: Iterable<RemoteRepositoryIdentity>,
+): boolean {
+ let known: RemoteRepositoryIdentity | undefined;
+ for (const remote of remotes) {
+ if (known && !matchingRemote(known, remote)) return false;
+ // HTTPS does not specify the login or path interpretation carried by SSH.
+ known = {
+ key: remote.key,
+ account: remote.account ?? known?.account,
+ homeRelative: remote.homeRelative ?? known?.homeRelative,
+ };
+ }
+ return true;
+}
+
async function bareMetadataRoots(
repository: string,
signal?: AbortSignal,
@@ -416,6 +484,8 @@ async function requireMatchingRepository(
repository: string,
provider: Provider,
sources: readonly ExternalSourceRepository[],
+ strictSources: ReadonlyMap<string, Provider>,
+ strictPlatformFor: (source: ExternalSourceRepository) => Provider,
protectedRoots: WorkbenchCommandOptions["protectedRoot"],
environment: WorkbenchCommandOptions["environment"],
signal?: AbortSignal,
@@ -469,41 +539,18 @@ async function requireMatchingRepository(
const urls = await readGit(["remote", "get-url", "--all", "--", name]);
remotes.push(...urls.split(/\r?\n/u));
}
- const identity = (value: string, platform: Provider) =>
- remoteRepository(value, platform, provider === "inspector");
- const githubRepositories = new Set(
- sources.flatMap((source) => {
- if (source.platform !== "github") return [];
- const key = identity(source.url, "github")?.key;
- return key === undefined ? [] : [key];
- }),
- );
+ const boundProvider = provider === "inspector" || provider === "blackduck";
+ const loosePlatformFor = localRepositoryPlatform(provider, sources, false);
for (const source of sources) {
- const githubKey = identity(source.url, "github")?.key;
- const sourceProvider =
- source.platform === "github" ||
- (githubKey !== undefined && githubRepositories.has(githubKey))
- ? "github"
- : provider;
- const targets = remotes.flatMap(
- (remote) => identity(remote, sourceProvider) ?? [],
- );
+ const bound = boundProvider || strictSources.has(source.url);
+ const platform = bound
+ ? (strictSources.get(source.url) ?? strictPlatformFor(source))
+ : loosePlatformFor(source);
+ const identity = (url: string) => remoteRepository(url, platform, bound);
+ const targets = remotes.flatMap((remote) => identity(remote) ?? []);
if (!targets.length) continue;
- const target = identity(source.url, sourceProvider);
- if (
- !target ||
- !targets.some(
- ({ key, account, homeRelative }) =>
- key === target.key &&
- (homeRelative === undefined ||
- target.homeRelative === undefined ||
- homeRelative === target.homeRelative) &&
- ((homeRelative === false && target.homeRelative === false) ||
- account === undefined ||
- target.account === undefined ||
- account === target.account),
- )
- )
+ const target = identity(source.url);
+ if (!target || !targets.some((remote) => matchingRemote(remote, target)))
throw new CodexSecurityError(
`Imported repository ${JSON.stringify(source.url)} does not match a configured remote of ${repository}. Select the matching local repository.`,
);
@@ -586,6 +633,8 @@ export async function prepareLocalImport(
input: ExternalFindings,
options: NormalizedLocalImportOptions,
dependencies: LocalExternalImportDependencies,
+ readerSources = snapshotSourceRepositories(dependencies.sourceRepositories),
+ parsedSources: readonly ExternalSourceRepository[] = [],
): Promise<PreparedLocalExternalImport> {
requireIdentity(options.sourceKey, "Source key");
const current = structuredClone(input);
@@ -623,16 +672,128 @@ export async function prepareLocalImport(
dependencies,
);
const sources = new Map<string, ExternalSourceRepository>();
- for (const finding of current.findings) {
- const url = finding.evidence.details?.repository?.url;
- if (url) sources.set(url, { url });
- }
+ const references = [...readerSources, ...parsedSources];
const inspector = inspectorReportRepository(
options.provider,
current.findings,
"local",
options.inspectorProjectMap,
);
+ const projected =
+ options.provider === "blackduck"
+ ? []
+ : current.findings.filter((finding) =>
+ projectedBlackDuckRepositoryUrl(finding, "local"),
+ );
+ const mixed = projected.length > 0 && readerSources.length > 0;
+ const nativeSources = new Map(
+ (mixed ? current.findings : projected)
+ .filter(
+ ({ evidence }) =>
+ options.provider !== "endor" ||
+ isRecord(evidence.source_data?.["runContext"]),
+ )
+ .map(
+ (finding) =>
+ [
+ finding,
+ localFindingRepositories(options.provider, finding),
+ ] as const,
+ ),
+ );
+ const platformFor = localRepositoryPlatform(
+ options.provider,
+ options.inspectorProjectMap
+ ? []
+ : [
+ ...references,
+ ...Array.from(nativeSources.values()).flat(),
+ ...(inspector ? [inspector] : []),
+ ],
+ true,
+ );
+ const identify = (url: string) =>
+ remoteRepository(url, platformFor({ url }), true) ?? { key: url };
+ // A hint from an independent reader applies across projected rows. A native
+ // GitHub asset in one row only identifies the platform of that row's claims.
+ const operatorPlatform = localRepositoryPlatform(
+ options.provider,
+ readerSources,
+ true,
+ );
+ const bound = blackDuckReportRepositories(
+ options.provider,
+ current.findings,
+ "local",
+ (urls) => sameBlackDuckRepositories(Array.from(urls, identify)),
+ );
+ const strictSources = new Map<string, Provider>();
+ const known = new Set<string>(parsedSources.map(({ url }) => url));
+ for (const finding of current.findings) {
+ const { evidence, source_finding_id: id } = finding;
+ const url = evidence.details?.repository?.url;
+ if (url) sources.set(url, { url });
+ const retained = bound.get(id);
+ const native = nativeSources.get(finding) ?? [];
+ if (retained) {
+ const claims = [
+ retained.url,
+ ...(url ? [url] : []),
+ ...native.map((ref) => ref.url),
+ ];
+ const rowPlatform = (claim: string) =>
+ options.provider !== "wiz"
+ ? platformFor({ url: claim })
+ : native.some((source) => source.platform === "github")
+ ? "github"
+ : operatorPlatform({ url: claim });
+ if (
+ !sameBlackDuckRepositories(
+ claims.map(
+ (claim) =>
+ remoteRepository(claim, rowPlatform(claim), true) ?? {
+ key: claim,
+ },
+ ),
+ )
+ )
+ throw new CodexSecurityError(
+ "The retained scanner repository does not match the original provider finding.",
+ );
+ for (const source of [retained, ...native])
+ sources.set(source.url, source);
+ for (const claim of claims) {
+ const platform = rowPlatform(claim);
+ if (!strictSources.has(claim) || platform !== "github")
+ strictSources.set(claim, platform);
+ }
+ }
+ for (const source of native) known.add(source.url);
+ }
+ if (mixed) {
+ // A caller reference with no matching row spelling can still be a Git alias.
+ const rows = [...sources.keys(), ...known].map(identify);
+ const byKey = Map.groupBy(rows, (remote) => remote.key);
+ const represented = new Set(rows.map((remote) => JSON.stringify(remote)));
+ const aliases = readerSources
+ .map(({ url }) => identify(url))
+ .filter((remote) => !represented.has(JSON.stringify(remote)));
+ for (const [key, group] of Map.groupBy(aliases, (remote) => remote.key)) {
+ const candidates = byKey.get(key);
+ if (!candidates || !sameBlackDuckRepositories([...candidates, ...group]))
+ throw new CodexSecurityError(
+ "Reader repository does not match a source in the normalized findings.",
+ );
+ }
+ }
+ if (strictSources.size && options.provider !== "blackduck") {
+ const keys = new Set(
+ Array.from(strictSources.keys(), (url) => identify(url).key),
+ );
+ for (const source of references)
+ if (!strictSources.has(source.url) && keys.has(identify(source.url).key))
+ strictSources.set(source.url, platformFor(source));
+ }
if (inspector) {
const platform = inspector.platform ?? options.provider;
const native = remoteRepository(inspector.url, platform, true);
@@ -643,10 +804,7 @@ export async function prepareLocalImport(
);
}
}
- for (const source of [
- ...(inspector ? [inspector] : []),
- ...(dependencies.sourceRepositories ?? []),
- ]) {
+ for (const source of [...(inspector ? [inspector] : []), ...references]) {
// A reader's platform must not loosen an operator-supplied Inspector map.
if (sources.get(source.url)?.platform !== "github")
sources.set(
@@ -654,6 +812,15 @@ export async function prepareLocalImport(
options.inspectorProjectMap ? { url: source.url } : source,
);
}
+ if (
+ options.provider === "blackduck" &&
+ current.findings.length &&
+ sources.size > 1 &&
+ !sameBlackDuckRepositories(Array.from(sources.keys(), identify))
+ )
+ throw new CodexSecurityError(
+ "Black Duck occurrences must belong to the same project version and source repository.",
+ );
if (dependabotSource)
sources.set(dependabotSource, {
url: dependabotSource,
@@ -663,6 +830,8 @@ export async function prepareLocalImport(
repository,
options.provider,
[...sources.values()],
+ strictSources,
+ platformFor,
workbenchOptions.protectedRoot,
workbenchOptions.environment,
dependencies.signal,
diff --git a/sdk/typescript/src/external-findings-publish.ts b/sdk/typescript/src/external-findings-publish.ts
index a47ab0e95..7ce12fbb1 100644
--- a/sdk/typescript/src/external-findings-publish.ts
+++ b/sdk/typescript/src/external-findings-publish.ts
@@ -32,9 +32,14 @@ import {
} from "./external-findings-read.js";
import { canonicalJson } from "./record.js";
import { wizCsvRepositoryUrl } from "./wiz-csv.js";
+import { wizFindingRepository } from "./wiz-findings.js";
import { dependabotRepository } from "./github-dependabot-findings.js";
import { snykRepositoryUrls } from "./snyk-findings.js";
import { endorRepositoryUrls } from "./endor-findings.js";
+import {
+ blackDuckReportRepositories,
+ projectedBlackDuckRepositoryUrl,
+} from "./blackduck-findings.js";
import { inspectorReportRepository } from "./inspector-findings.js";
import {
snapshotImportOptions,
@@ -738,14 +743,6 @@ async function preparePublicationInput(
);
function checkRepositories(findings: ExternalFindings["findings"]) {
- // Validated non-Inspector checkpoints retain their original provider and repository ID.
- if (saved && options.provider !== "inspector") return;
- const binding = inspectorReportRepository(
- options.provider,
- findings,
- "cloud",
- inspectorProjectMap,
- );
function requireDestination(id: string, url: string | null | undefined) {
if (
url &&
@@ -755,12 +752,35 @@ async function preparePublicationInput(
`Finding ${JSON.stringify(id)} belongs to ${JSON.stringify(url)}, which does not match the selected Cloud repository ${JSON.stringify(destination.url)}. Verify the source repository mapping before publishing.`,
);
}
- if (binding) requireDestination(binding.findingId, binding.url);
+ // Historical checkpoints already fixed the provider and request bytes.
+ // Recheck any projected source against the destination discovered for this retry.
+ const replay = saved && options.provider !== "blackduck";
+ const repositories = replay
+ ? undefined
+ : blackDuckReportRepositories(options.provider, findings, "cloud");
+ if (!replay || options.provider === "inspector") {
+ const binding = inspectorReportRepository(
+ options.provider,
+ findings,
+ "cloud",
+ inspectorProjectMap,
+ );
+ if (binding) requireDestination(binding.findingId, binding.url);
+ }
for (const finding of findings) {
const { source_finding_id: id, evidence } = finding;
+ const projected = repositories
+ ? repositories.get(id)?.url
+ : projectedBlackDuckRepositoryUrl(finding, "cloud");
+ if (replay && !projected && options.provider !== "inspector") continue;
const urls = [
+ projected,
evidence.details?.repository?.url,
- ...(options.provider === "wiz" ? [wizCsvRepositoryUrl(evidence)] : []),
+ options.provider === "wiz"
+ ? projected
+ ? wizFindingRepository(evidence, "cloud")?.url
+ : wizCsvRepositoryUrl(evidence)
+ : undefined,
...(options.provider === "snyk"
? snykRepositoryUrls(evidence.source_data, {
cloudRepositoryUrl: destination.url,
diff --git a/sdk/typescript/src/external-findings-read.ts b/sdk/typescript/src/external-findings-read.ts
index 36c8a731f..2b40fcf85 100644
--- a/sdk/typescript/src/external-findings-read.ts
+++ b/sdk/typescript/src/external-findings-read.ts
@@ -1,20 +1,24 @@
import type {
+ ExternalFinding,
ExternalFindings,
ExternalPublicationInput,
ExternalSourceRepository,
} from "./external-findings.js";
import type { Provider } from "./external-import-models.js";
import type { ExternalImportTarget } from "./external-import-contract.js";
-import { wizCsvRepositoryUrl } from "./wiz-csv.js";
import { readSnykFindings, snykRepositoryUrls } from "./snyk-findings.js";
import { readSemgrepFindings } from "./semgrep-findings.js";
import { readOpenGrepFindings } from "./opengrep-findings.js";
import { readEndorFindings, endorRepositoryUrls } from "./endor-findings.js";
+import { dependabotRepository } from "./github-dependabot-findings.js";
import { readGitHubFindings } from "./github-findings.js";
+import { readBlackDuckFindings } from "./blackduck-findings.js";
import { readInspectorFindings } from "./inspector-findings.js";
-import { isGitHubCloudHost } from "./git-remote.js";
import { isRecord } from "./record.js";
-import { readVendorFindingsForPublication } from "./wiz-findings.js";
+import {
+ readVendorFindingsForPublication,
+ wizFindingRepository,
+} from "./wiz-findings.js";
/** File reader names mapped to their stored and Cloud source provider. */
export const EXTERNAL_FINDINGS_PROVIDERS = {
@@ -26,6 +30,7 @@ export const EXTERNAL_FINDINGS_PROVIDERS = {
endor: "endor",
github: "github",
inspector: "inspector",
+ blackduck: "blackduck",
} as const satisfies Record<string, Provider>;
export type ExternalFindingsReader = keyof typeof EXTERNAL_FINDINGS_PROVIDERS;
@@ -49,6 +54,29 @@ export interface ReadExternalFindings {
sourceRepositories?: ExternalSourceRepository[];
}
+/** Repository references retained by a provider's individual finding. */
+export function localFindingRepositories(
+ provider: Provider,
+ finding: ExternalFinding,
+): ExternalSourceRepository[] {
+ const { evidence } = finding;
+ if (provider === "snyk")
+ return snykRepositoryUrls(evidence.source_data, {
+ normalizeGitRemote: false,
+ }).map((url) => ({ url }));
+ if (provider === "endor")
+ return endorRepositoryUrls(evidence.source_data).map((url) => ({ url }));
+ if (provider === "wiz") {
+ const repository = wizFindingRepository(evidence);
+ return repository ? [repository] : [];
+ }
+ if (provider === "github") {
+ const url = dependabotRepository(finding);
+ if (url) return [{ url, platform: "github" }];
+ }
+ return [];
+}
+
/** @internal Read vendor evidence for the local and Cloud import entrypoints. */
export async function readExternalFindings(
path: string,
@@ -66,14 +94,16 @@ export async function readExternalFindings(
sourceRepositories: [{ url: sourceRepositoryUrl }],
};
}
- if (options.provider === "snyk") {
- const findings = await readSnykFindings(path, target);
+ if (options.provider === "snyk" || options.provider === "endor") {
+ const provider = options.provider;
+ const findings =
+ provider === "snyk"
+ ? await readSnykFindings(path, target)
+ : await readEndorFindings(path, target);
return {
findings,
- sourceRepositories: findings.findings.flatMap(({ evidence }) =>
- snykRepositoryUrls(evidence.source_data, {
- normalizeGitRemote: false,
- }).map((url) => ({ url })),
+ sourceRepositories: findings.findings.flatMap((finding) =>
+ localFindingRepositories(provider, finding),
),
};
}
@@ -102,60 +132,24 @@ export async function readExternalFindings(
});
return { findings, sourceRepositories };
}
- if (options.provider === "endor") {
- const parsed = await readEndorFindings(path, target);
- return {
- findings: parsed,
- sourceRepositories: parsed.findings.flatMap((finding) =>
- endorRepositoryUrls(finding.evidence.source_data).map((url) => ({
- url,
- })),
- ),
- };
- }
if (options.provider === "github")
return { findings: await readGitHubFindings(path, target) };
- if (options.provider === "inspector") {
+ if (options.provider === "inspector" || options.provider === "blackduck") {
const url = options.sourceRepositoryUrl ?? "";
- return {
- findings: await readInspectorFindings(
- path,
- url,
- target,
- options.inspectorProjectMap,
- ),
- sourceRepositories: [{ url }],
- };
+ const findings =
+ options.provider === "inspector"
+ ? await readInspectorFindings(
+ path,
+ url,
+ target,
+ options.inspectorProjectMap,
+ )
+ : await readBlackDuckFindings(path, url, target);
+ return { findings, sourceRepositories: [{ url }] };
}
const publication = await readVendorFindingsForPublication(path, target);
- // Raw package exports keep repository-branch URLs in retained source data.
- const sourceRepositories = publication.current.findings.flatMap(
- ({ evidence }) => {
- const csvUrl = wizCsvRepositoryUrl(evidence);
- if (csvUrl) return [{ url: csvUrl, platform: "github" as const }];
- const asset = evidence.source_data?.["vulnerableAsset"];
- if (!isRecord(asset) || typeof asset["cloudProviderURL"] !== "string")
- return [];
- const url = URL.parse(asset["cloudProviderURL"]);
- if (!url) return [];
- const github =
- asset["nativeType"] === "github#repositoryBranch" ||
- (asset["type"] === "REPOSITORY_BRANCH" &&
- isGitHubCloudHost(url.hostname));
- if (!github)
- return asset["type"] === "REPOSITORY_BRANCH"
- ? [{ url: asset["cloudProviderURL"] }]
- : [];
- const [, owner, repository] = url.pathname.split("/");
- return owner && repository
- ? [
- {
- url: `${url.origin}/${owner}/${repository}`,
- platform: "github" as const,
- },
- ]
- : [];
- },
+ const sourceRepositories = publication.current.findings.flatMap((finding) =>
+ localFindingRepositories("wiz", finding),
);
return {
findings: publication.current,
diff --git a/sdk/typescript/src/external-findings.ts b/sdk/typescript/src/external-findings.ts
index 1b717a16d..619f2ef51 100644
--- a/sdk/typescript/src/external-findings.ts
+++ b/sdk/typescript/src/external-findings.ts
@@ -14,6 +14,12 @@ export interface ExternalSourceRepository {
platform?: "github";
}
+export function snapshotSourceRepositories(
+ references: readonly ExternalSourceRepository[] = [],
+): ExternalSourceRepository[] {
+ return references.map(({ url, platform }) => ({ url, platform }));
+}
+
export interface ExternalFindings {
read: number;
/** Reader-retained run metadata, including diagnostics for empty reports. */
diff --git a/sdk/typescript/src/external-import-models.ts b/sdk/typescript/src/external-import-models.ts
index 8ea786f61..663b89845 100644
--- a/sdk/typescript/src/external-import-models.ts
+++ b/sdk/typescript/src/external-import-models.ts
@@ -6,7 +6,7 @@ export type RepoConnectorId = string;
export type EnvironmentId = string;
export type ResetMarker = string;
export type Provider =
- "wiz" | "endor" | "snyk" | "github" | "semgrep" | "inspector";
+ "wiz" | "endor" | "snyk" | "github" | "semgrep" | "inspector" | "blackduck";
export type SourceKey = string;
export type ClientId = string;
export type SourceFindingId = string;
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index f3d752e32..14e57044a 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -331,6 +331,10 @@ export {
readOpenGrepFindings,
type OpenGrepImportOptions,
} from "./opengrep-findings.js";
+export {
+ normalizeBlackDuckFindings,
+ readBlackDuckFindings,
+} from "./blackduck-findings.js";
export {
normalizeInspectorFindings,
readInspectorFindings,
diff --git a/sdk/typescript/src/scanner-repository-url.ts b/sdk/typescript/src/scanner-repository-url.ts
new file mode 100644
index 000000000..315b92ad4
--- /dev/null
+++ b/sdk/typescript/src/scanner-repository-url.ts
@@ -0,0 +1,41 @@
+import type { ExternalImportTarget } from "./external-import-contract.js";
+import { requiredText } from "./scanner-import.js";
+
+function repositorySegment(encoded: string): 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)
+ );
+ } catch {
+ return false;
+ }
+}
+
+export function declaredScannerRepositoryUrl(
+ value: unknown,
+ provider: string,
+ target: ExternalImportTarget = "cloud",
+): string {
+ const source = requiredText(value, `${provider} --source-repository-url`);
+ const url = URL.parse(source);
+ const parts = /^https?:\/\/([^/?#\\]+)\/([^?#\\]+)$/iu.exec(source);
+ const segments = parts?.[2]?.replace(/\/$/u, "").split("/") ?? [];
+ if (
+ !url ||
+ !parts ||
+ parts[1]!.includes("@") ||
+ /[\s\p{Cc}]/u.test(source) ||
+ url.username ||
+ url.password ||
+ segments.length < (target === "local" ? 1 : 2) ||
+ !segments.every(repositorySegment)
+ )
+ throw new Error(
+ `${provider} --source-repository-url requires an HTTP(S) repository path without credentials, query, fragment, or ambiguous path segments.`,
+ );
+ return source;
+}
diff --git a/sdk/typescript/src/wiz-findings.ts b/sdk/typescript/src/wiz-findings.ts
index 96ff423c9..684e7ffa4 100644
--- a/sdk/typescript/src/wiz-findings.ts
+++ b/sdk/typescript/src/wiz-findings.ts
@@ -5,7 +5,8 @@ import {
type ExternalImportTarget,
} from "./external-import-contract.js";
import { parseJsonOrJsonl, readScannerText } from "./scanner-import.js";
-import { readWizCsv, wizCsvFinding } from "./wiz-csv.js";
+import { isGitHubCloudHost } from "./git-remote.js";
+import { readWizCsv, wizCsvFinding, wizCsvRepositoryUrl } from "./wiz-csv.js";
import type {
ExternalFinding as VendorFinding,
ExternalFindings as VendorFindings,
@@ -457,6 +458,37 @@ function records(payload: unknown): FindingInput {
);
}
+/** The source repository retained by a Wiz package finding or CSV row. */
+export function wizFindingRepository(
+ evidence: VendorFinding["evidence"],
+ target: ExternalImportTarget = "local",
+): ExternalSourceRepository | undefined {
+ const csvUrl = wizCsvRepositoryUrl(evidence);
+ if (csvUrl) return { url: csvUrl, platform: "github" };
+ const asset = object(evidence.source_data?.["vulnerableAsset"]);
+ if (!asset || typeof asset["cloudProviderURL"] !== "string") return;
+ const url = URL.parse(asset["cloudProviderURL"]);
+ if (!url) return;
+ const github =
+ asset["nativeType"] === "github#repositoryBranch" ||
+ (asset["type"] === "REPOSITORY_BRANCH" && isGitHubCloudHost(url.hostname));
+ if (!github)
+ return asset["type"] === "REPOSITORY_BRANCH"
+ ? { url: asset["cloudProviderURL"] }
+ : undefined;
+ const [, owner, repository] = url.pathname.split("/");
+ if (!owner || !repository) return;
+ // URL.origin drops explicit default ports, which the Cloud catalog retains.
+ const port =
+ target === "cloud"
+ ? /^https?:\/\/[^/?#\\]*:(\d+)(?:[/?#]|$)/iu.exec(
+ asset["cloudProviderURL"],
+ )?.[1]
+ : undefined;
+ const origin = port ? `${url.protocol}//${url.hostname}:${port}` : url.origin;
+ return { url: `${origin}/${owner}/${repository}`, platform: "github" };
+}
+
export async function readVendorFindings(
path: string,
target: ExternalImportTarget = "cloud",
diff --git a/sdk/typescript/tests-ts/blackduck-findings.test.ts b/sdk/typescript/tests-ts/blackduck-findings.test.ts
new file mode 100644
index 000000000..e1e178f66
--- /dev/null
+++ b/sdk/typescript/tests-ts/blackduck-findings.test.ts
@@ -0,0 +1,644 @@
+import { expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+import {
+ blackDuckReportRepositories,
+ normalizeBlackDuckFindings,
+ readBlackDuckFindings,
+} from "../src/blackduck-findings.js";
+import {
+ blackDuckBomReport,
+ blackDuckBomRow,
+} from "./support/blackduck-import-fixtures.js";
+import { scopedTemporaryDirectory } from "./support/temporary-directories.js";
+
+const repository = "https://vcs.example.test/team/application";
+
+function retainedUrl(
+ source_data: Record<string, unknown> | undefined,
+ source_finding_id = "sdk-key",
+) {
+ const repositories = blackDuckReportRepositories(
+ "blackduck",
+ [
+ {
+ source_finding_id,
+ evidence: { title: "Example", severity: "unknown", source_data },
+ },
+ ],
+ "cloud",
+ );
+ return repositories.get(source_finding_id)?.url;
+}
+
+test("retains the complete BOM row, project version and caller's repository, not a fix or assessment", () => {
+ const row = {
+ ...blackDuckBomRow(),
+ ignored: true,
+ packageUrl: "pkg:maven/example/[email protected]",
+ license: { licenseDisplay: "Example license" },
+ vulnerabilityWithRemediation: {
+ ...blackDuckBomRow().vulnerabilityWithRemediation,
+ remediationStatus: "REMEDIATION_COMPLETE",
+ description: "Vendor description",
+ cweId: "CWE-79",
+ relatedVulnerability:
+ "https://scanner.example.test/api/vulnerabilities/CVE%2D2099-1000",
+ vulnerabilityUpdatedDate: "2026-01-01T00:00:00Z",
+ extension: { values: [42] },
+ },
+ };
+ const input = {
+ ...blackDuckBomReport([row]),
+ appliedFilters: ["ignored:true"],
+ };
+ const original = structuredClone(row);
+ const result = normalizeBlackDuckFindings(input, repository);
+ expect(result).toEqual(normalizeBlackDuckFindings([row], repository));
+ expect(result).toEqual(
+ normalizeBlackDuckFindings(input, repository, "local"),
+ );
+ expect(result.excluded).toEqual([]);
+ const evidence = result.findings[0]!.evidence;
+ expect(evidence).toMatchObject({
+ title: "BDSA-2099-0001 in Example Library",
+ severity: "high",
+ description: "Vendor description",
+ advisory_ids: [
+ "BDSA-2099-0001",
+ row.vulnerabilityWithRemediation.relatedVulnerability,
+ ],
+ packages: [
+ {
+ name: "example:library",
+ ecosystem: "maven",
+ installed_version: "1.0",
+ fixed_versions: [],
+ manifest_path: null,
+ },
+ ],
+ locations: [],
+ source_updated_at: null,
+ });
+ expect(evidence.source_data).toEqual({
+ format: "blackduck-bom-6",
+ sourceRepositoryUrl: repository,
+ projectVersionUrl:
+ "https://scanner.example.test/api/projects/project-a/versions/release-a",
+ row: original,
+ });
+ expect(evidence.details).toBeUndefined();
+ row.vulnerabilityWithRemediation.extension.values.push(99);
+ expect(evidence.source_data?.["row"]).toEqual(original);
+});
+
+test("replay keeps native occurrence identity when package coordinates and advisory aliases change", () => {
+ const row = blackDuckBomRow();
+ const original = normalizeBlackDuckFindings([row], repository).findings[0]!;
+ expect(original.evidence.packages).toMatchObject([
+ { name: "example:library", ecosystem: "maven", installed_version: "1.0" },
+ ]);
+ const updated = {
+ ...row,
+ componentName: "Renamed library",
+ componentVersionOriginName: "npmjs",
+ componentVersionOriginId: "@example/library/2.0",
+ vulnerabilityWithRemediation: {
+ ...row.vulnerabilityWithRemediation,
+ relatedVulnerability: row.vulnerabilityWithRemediation.vulnerabilityName,
+ },
+ };
+ const replay = normalizeBlackDuckFindings([updated], repository).findings[0]!;
+ expect(replay.source_finding_id).toBe(original.source_finding_id);
+ expect(replay.evidence.advisory_ids).toEqual(["BDSA-2099-0001"]);
+ expect(replay.evidence.packages).toMatchObject([
+ { name: "@example/library", ecosystem: "npm", installed_version: "2.0" },
+ ]);
+ for (const scope of ["%40example", "@example"]) {
+ const purl = {
+ ...updated,
+ packageUrl: `pkg:npm/${scope}/[email protected]?tag=preview#dist`,
+ };
+ expect(
+ normalizeBlackDuckFindings([purl], repository).findings[0]!.evidence
+ .packages,
+ ).toMatchObject([
+ { name: "@example/other", ecosystem: "npm", installed_version: "3.0" },
+ ]);
+ }
+ const opaque = {
+ ...updated,
+ componentVersionOriginName: "custom",
+ componentVersionOriginId: "opaque",
+ };
+ const finding = normalizeBlackDuckFindings([opaque], repository).findings[0]!;
+ expect(finding.source_finding_id).toBe(original.source_finding_id);
+ expect(finding.evidence.packages).toEqual([]);
+ expect(finding.evidence.source_data?.["row"]).toEqual(opaque);
+});
+
+test("uses the full generic package path and keeps the origin fallback for an invalid namespace", () => {
+ const row = blackDuckBomRow();
+ const packages = (packageUrl: string) =>
+ normalizeBlackDuckFindings([{ ...row, packageUrl }], repository)
+ .findings[0]!.evidence.packages;
+ expect(packages("pkg:generic/tools/example/[email protected]")).toMatchObject([
+ {
+ name: "tools/example/library",
+ ecosystem: "generic",
+ installed_version: "2.0",
+ },
+ ]);
+ for (const invalid of [
+ "pkg:npm/unscoped/[email protected]",
+ "pkg:maven/extra/group/[email protected]",
+ "pkg:pypi/extra/[email protected]",
+ "pkg:pypi/extra%[email protected]",
+ "pkg:composer/[email protected]",
+ ])
+ expect(packages(invalid)).toMatchObject([
+ { name: "example:library", ecosystem: "maven", installed_version: "1.0" },
+ ]);
+});
+
+test("uses the matching native coordinate for a versionless package URL", () => {
+ const row = { ...blackDuckBomRow(), componentVersionName: "display label" };
+ const packages = (packageUrl: string) =>
+ normalizeBlackDuckFindings([{ ...row, packageUrl }], repository)
+ .findings[0]!.evidence.packages;
+ expect(packages("pkg:maven/example/library")).toMatchObject([
+ { name: "example:library", installed_version: "1.0" },
+ ]);
+ expect(packages("pkg:maven/another/library")).toMatchObject([
+ { name: "another:library", installed_version: "display label" },
+ ]);
+});
+
+test("adding or omitting an unrelated row and changing collection paging metadata do not version retained evidence", () => {
+ const row = blackDuckBomRow();
+ const other = blackDuckBomRow("BDSA-2099-0002");
+ const report = blackDuckBomReport([row, other]);
+ report._meta.href += "?offset=0&limit=250";
+ for (const target of ["cloud", "local"] as const) {
+ const retained = normalizeBlackDuckFindings([row], repository, target)
+ .findings[0];
+ expect(
+ normalizeBlackDuckFindings(report, repository, target).findings[0],
+ ).toEqual(retained);
+ expect(
+ normalizeBlackDuckFindings(blackDuckBomReport([row]), repository, target)
+ .findings[0],
+ ).toEqual(retained);
+ }
+});
+
+test("only a complete project-version collection can establish an empty selection", () => {
+ const empty = blackDuckBomReport([]);
+ expect(normalizeBlackDuckFindings(empty, repository)).toEqual({
+ read: 0,
+ findings: [],
+ excluded: [],
+ });
+ for (const totalCount of [5, -1, "0", null, undefined])
+ expect(() =>
+ normalizeBlackDuckFindings({ ...empty, totalCount }, repository),
+ ).toThrow(/totalCount/);
+ for (const input of [
+ [],
+ {},
+ { items: [], totalCount: 0 },
+ { scanStatus: "SUCCESS" },
+ ])
+ expect(() => normalizeBlackDuckFindings(input, repository)).toThrow();
+ for (const suffix of ["?offset=1", "?offset=0&offset=3"])
+ expect(() =>
+ normalizeBlackDuckFindings(
+ { ...empty, _meta: { href: empty._meta.href + suffix } },
+ repository,
+ ),
+ ).toThrow(/page/);
+ for (const rel of ["next", "prev"])
+ expect(() =>
+ normalizeBlackDuckFindings(
+ {
+ ...empty,
+ _meta: {
+ ...empty._meta,
+ links: [{ rel, href: "https://elsewhere.example.test/page" }],
+ },
+ },
+ repository,
+ ),
+ ).toThrow(/page/);
+ expect(() =>
+ normalizeBlackDuckFindings(
+ {
+ ...empty,
+ _meta: {
+ href: empty._meta.href.replace(
+ "vulnerable-bom-components",
+ "components",
+ ),
+ },
+ },
+ repository,
+ ),
+ ).toThrow(/vulnerable-bom-components/);
+});
+
+test("selected array replay keeps distinct advisories, origins and sources; evidence edits keep identity", () => {
+ const first = blackDuckBomRow();
+ const second = blackDuckBomRow("BDSA-2099-0002");
+ const alternateSource = {
+ ...first,
+ vulnerabilityWithRemediation: {
+ ...first.vulnerabilityWithRemediation,
+ source: "NVD",
+ },
+ };
+ const alternateOrigin = blackDuckBomRow();
+ alternateOrigin._meta.links[0]!.href =
+ alternateOrigin._meta.links[0]!.href.replace("origin-a", "origin-b");
+ const rows = [first, second, alternateSource, alternateOrigin];
+ const result = normalizeBlackDuckFindings(
+ blackDuckBomReport(rows),
+ repository,
+ );
+ const ids = result.findings.map((finding) => finding.source_finding_id);
+ expect(new Set(ids).size).toBe(4);
+ first.vulnerabilityWithRemediation.severity = "LOW";
+ first.vulnerabilityWithRemediation.remediationStatus = "IGNORED";
+ const selection = normalizeBlackDuckFindings(rows.toReversed(), repository);
+ expect(
+ selection.findings.map((finding) => finding.source_finding_id),
+ ).toEqual(ids.toReversed());
+ expect(
+ selection.findings.map(({ evidence }) => evidence.source_data?.["row"]),
+ ).toEqual(rows.toReversed());
+ expect(selection.findings.at(-1)!.evidence.severity).toBe("low");
+ const duplicated = normalizeBlackDuckFindings(
+ [first, second, first],
+ repository,
+ );
+ expect(duplicated.findings).toHaveLength(1);
+ expect(() =>
+ normalizeBlackDuckFindings(
+ blackDuckBomReport([first, second, first]),
+ repository,
+ ),
+ ).toThrow(/pages may overlap/i);
+ expect(
+ duplicated.excluded.map(({ position, source_finding_id }) => [
+ position,
+ source_finding_id,
+ ]),
+ ).toEqual([
+ [1, ids[0]!],
+ [3, ids[0]!],
+ ]);
+});
+
+test("rejects overlapping complete pages even when a repeated row has no occurrence ID", () => {
+ const row = blackDuckBomRow();
+ const incomplete = { ...row, _meta: { links: [] } };
+ const reversed = Object.fromEntries(Object.entries(incomplete).reverse());
+ const report = blackDuckBomReport([row, incomplete]);
+ expect(normalizeBlackDuckFindings(report, repository).excluded).toHaveLength(
+ 1,
+ );
+ expect(() =>
+ normalizeBlackDuckFindings(
+ { ...report, totalCount: 3, items: [...report.items, reversed] },
+ repository,
+ ),
+ ).toThrow(/pages may overlap/);
+});
+
+test("unrelated provider columns can share Black Duck field names", () => {
+ const finding = {
+ source_finding_id: "wiz-finding",
+ evidence: {
+ title: "Example",
+ severity: "unknown" as const,
+ source_data: {
+ row: {
+ componentVersion: "1.0",
+ vulnerabilityWithRemediation: { status: "open" },
+ },
+ },
+ },
+ };
+ expect(blackDuckReportRepositories("wiz", [finding], "cloud").size).toBe(0);
+});
+
+test("collection and every selected occurrence must identify the same server, project and version", () => {
+ const row = blackDuckBomRow();
+ for (const key of ["scanner.example.test", "project-a", "release-a"]) {
+ const other = blackDuckBomRow();
+ other._meta.links[0]!.href = other._meta.links[0]!.href.replace(
+ key,
+ "other",
+ );
+ for (const input of [
+ blackDuckBomReport([other]),
+ [row, other],
+ [other, row],
+ ])
+ expect(() => normalizeBlackDuckFindings(input, repository)).toThrow(
+ /same project version/,
+ );
+ }
+ const envelope = blackDuckBomReport([row]);
+ envelope._meta.href = envelope._meta.href.replace("/projects/", "/project/");
+ expect(
+ normalizeBlackDuckFindings(envelope, repository).findings[0]!
+ .source_finding_id,
+ ).toBe(
+ normalizeBlackDuckFindings([row], repository).findings[0]!
+ .source_finding_id,
+ );
+ const origin = {
+ rel: "vulnerabilities",
+ href: `${row.componentVersion}/origin/origin-a/vulnerabilities`,
+ };
+ const unscoped = { ...row, _meta: { links: [origin] } };
+ expect(() => normalizeBlackDuckFindings([row, unscoped], repository)).toThrow(
+ /Each selected/,
+ );
+ expect(
+ normalizeBlackDuckFindings(blackDuckBomReport([unscoped]), repository)
+ .findings[0]!.source_finding_id,
+ ).toBe(
+ normalizeBlackDuckFindings([row], repository).findings[0]!
+ .source_finding_id,
+ );
+ row._meta.links.push({
+ ...origin,
+ href: origin.href.replace("origin-a", "origin-b"),
+ });
+ expect(
+ normalizeBlackDuckFindings([row], repository).excluded[0]!.reason,
+ ).toMatch(/unambiguous/);
+});
+
+test("invalid components and non-vulnerability rows are diagnosed without inventing occurrences", () => {
+ const row = blackDuckBomRow();
+ const report = blackDuckBomReport();
+ const noOrigin = { ...row, _meta: { links: [] } };
+ const result = normalizeBlackDuckFindings(
+ {
+ ...report,
+ items: [
+ row,
+ { license: {} },
+ { policyStatus: "IN_VIOLATION" },
+ {
+ ...row,
+ componentVersion: row.componentVersion.replace(
+ "component-a",
+ "component-b",
+ ),
+ },
+ noOrigin,
+ { ...row, _meta: { links: null } },
+ ],
+ totalCount: 6,
+ },
+ repository,
+ );
+ expect(result.findings).toHaveLength(1);
+ expect(result.excluded.map(({ position }) => position)).toEqual([
+ 2, 3, 4, 5, 6,
+ ]);
+ expect(result.excluded.map(({ reason }) => reason)).toEqual([
+ expect.stringContaining("vulnerabilityWithRemediation"),
+ expect.stringContaining("vulnerabilityWithRemediation"),
+ expect.stringContaining("contradicts"),
+ expect.stringContaining("origin"),
+ expect.stringContaining("_meta.links"),
+ ]);
+ const other = blackDuckBomRow(undefined, "release-b");
+ expect(() =>
+ normalizeBlackDuckFindings(
+ {
+ ...report,
+ items: [{ ...other, _meta: { links: [null, ...other._meta.links] } }],
+ },
+ repository,
+ ),
+ ).toThrow(/same project version/);
+ const large = { ...row, extra: "x".repeat(270_000) };
+ expect(normalizeBlackDuckFindings([large], repository).excluded).toHaveLength(
+ 1,
+ );
+ expect(
+ normalizeBlackDuckFindings([large], repository, "local").findings[0]!
+ .evidence.source_data?.["row"],
+ ).toEqual(large);
+});
+
+test.each([
+ "",
+ "not a URL",
+ "file:///team/repo",
+ "https:vcs.example.test/team/repo",
+ "https://vcs.example.test",
+ "https://vcs.example.test/",
+ "https://vcs.example.test/team/",
+ "https://@vcs.example.test/team/repo",
+ "https://user:[email protected]/team/repo",
+ `${repository}?token=example`,
+ `${repository}#branch`,
+ `${repository}?`,
+ `${repository}#`,
+ "https://vcs.example.test/team//repo",
+ "https://vcs.example.test/team/./repo",
+ "https://vcs.example.test/team/../repo",
+ "https://vcs.example.test/team/.git",
+ "https://vcs.example.test/team/...git",
+ "https://vcs.example.test/team/%2e%2E/repo",
+ "https://vcs.example.test/team/%252e%252e/repo",
+ `${repository}\\other`,
+ `${repository}%2Fother`,
+ `${repository}%5cother`,
+ `${repository}%00`,
+ `${repository}%3Fbranch`,
+ `${repository}%23branch`,
+ `${repository}%zz`,
+ "https://vcs.example.test/team/%20",
+])("rejects ambiguous repository binding %j even without rows", (source) => {
+ expect(() =>
+ normalizeBlackDuckFindings(blackDuckBomReport([]), source),
+ ).toThrow(/source-repository-url/);
+ expect(() => retainedUrl({ sourceRepositoryUrl: source })).toThrow(
+ /source-repository-url/,
+ );
+});
+
+test("accepts a nested repository URL and retains it independently of the mutable evidence projection", () => {
+ const url =
+ "http://vcs.example.test:8080/org/subgroup/Example%20Repository.git/";
+ const finding = normalizeBlackDuckFindings([blackDuckBomRow()], url)
+ .findings[0]!;
+ const data = finding.evidence.source_data;
+ expect(retainedUrl(data, finding.source_finding_id)).toBe(url);
+ const otherComponent = blackDuckBomRow();
+ otherComponent.componentVersion = otherComponent.componentVersion.replace(
+ "component-a",
+ "component-b",
+ );
+ expect(() => retainedUrl({ ...data, row: otherComponent })).toThrow(
+ /contradicts/,
+ );
+ const projectVersionUrl = data?.["projectVersionUrl"];
+ expect(retainedUrl({ projectVersionUrl })).toBeUndefined();
+ expect(retainedUrl({ sourceRepositoryUrl: url, projectVersionUrl })).toBe(
+ url,
+ );
+ expect(retainedUrl(undefined)).toBeUndefined();
+ expect(() => retainedUrl({ row: blackDuckBomRow() })).toThrow(
+ /source-repository-url/,
+ );
+ const row = blackDuckBomRow();
+ expect(() =>
+ retainedUrl({
+ sourceRepositoryUrl: repository,
+ projectVersionUrl:
+ "https://scanner.example.test/api/projects/project-a/versions/release-b",
+ row,
+ }),
+ ).toThrow(/same project version/);
+ row.vulnerabilityWithRemediation.source = "UNRECOGNIZED";
+ expect(
+ normalizeBlackDuckFindings([row], repository).excluded[0]!.reason,
+ ).toMatch(/advisory source/);
+});
+
+test("normalized input cannot relabel one native occurrence with another finding's ID", () => {
+ const [first, second] = normalizeBlackDuckFindings(
+ [blackDuckBomRow(), blackDuckBomRow("BDSA-2099-0002")],
+ repository,
+ ).findings;
+ const data = first!.evidence.source_data;
+ expect(retainedUrl(data, first!.source_finding_id)).toBe(repository);
+ expect(() => retainedUrl(data, second!.source_finding_id)).toThrow(
+ /source finding ID/,
+ );
+ for (const incomplete of [{ ...data, row: null }, { arbitrary: true }]) {
+ expect(() => retainedUrl(incomplete, first!.source_finding_id)).toThrow(
+ /retained Black Duck/,
+ );
+ }
+ expect(retainedUrl({ arbitrary: true })).toBeUndefined();
+});
+
+test("reads JSON and gzip by content and rejects a truncated collection in either target", async () => {
+ await using directory = await scopedTemporaryDirectory("blackduck-bom-");
+ const path = join(directory.path, "report");
+ const items = [blackDuckBomRow(), blackDuckBomRow("BDSA-2099-0002")];
+ const expected = normalizeBlackDuckFindings(items, repository);
+ for (const bytes of [
+ Buffer.from(JSON.stringify(items)),
+ gzipSync(JSON.stringify(items)),
+ ]) {
+ await writeFile(path, bytes);
+ for (const target of ["cloud", "local"] as const)
+ expect(await readBlackDuckFindings(path, repository, target)).toEqual(
+ expected,
+ );
+ }
+ await writeFile(
+ path,
+ JSON.stringify({ ...blackDuckBomReport(items), totalCount: 5 }),
+ );
+ for (const target of ["cloud", "local"] as const)
+ await expect(
+ readBlackDuckFindings(path, repository, target),
+ ).rejects.toThrow(/totalCount/);
+});
+
+test("checks the component even when a vulnerabilities link omits the origin", () => {
+ const row = blackDuckBomRow();
+ const link = {
+ rel: "vulnerabilities",
+ href: row.componentVersion + "/vulnerabilities",
+ };
+ row._meta.links.push(link);
+ expect(normalizeBlackDuckFindings([row], repository).excluded).toEqual([]);
+ link.href = link.href.replace("component-a", "component-b");
+ expect(
+ normalizeBlackDuckFindings([row], repository).excluded[0]!.reason,
+ ).toMatch(/contradicts componentVersion/);
+});
+
+test("binds row remediation URLs to the project version, component version and origin", () => {
+ const row = blackDuckBomRow();
+ const matched = row._meta.links[0]!.href;
+ const href = matched.replace(
+ "/matched-files",
+ "/vulnerabilities/native-vulnerability-id/remediation",
+ );
+ const origin = {
+ rel: "vulnerabilities",
+ href: row.componentVersion + "/origin/origin-a/vulnerabilities",
+ };
+ const baseline = normalizeBlackDuckFindings([row], repository).findings[0]!
+ .source_finding_id;
+ for (const self of [href, href.replace("/origins/origin-a", "")]) {
+ const onlySelf = { ...row, _meta: { href: self, links: [origin] } };
+ expect(
+ normalizeBlackDuckFindings([onlySelf], repository).findings[0]!
+ .source_finding_id,
+ ).toBe(baseline);
+ expect(() =>
+ normalizeBlackDuckFindings(
+ {
+ ...blackDuckBomReport(),
+ items: [
+ {
+ ...row,
+ _meta: {
+ href: self.replace("release-a", "release-b"),
+ links: [origin],
+ },
+ },
+ ],
+ },
+ repository,
+ ),
+ ).toThrow(/same project version/);
+ }
+ for (const [from, to] of [
+ ["component-a", "component-b"],
+ ["origin-a", "origin-b"],
+ ] as const) {
+ const conflicting = {
+ ...row,
+ _meta: { href: href.replace(from, to), links: row._meta.links },
+ };
+ expect(
+ normalizeBlackDuckFindings([conflicting], repository).excluded,
+ ).toHaveLength(1);
+ }
+ const componentLink = {
+ rel: "matched-files",
+ href: matched.replace("/origins/origin-a", ""),
+ };
+ const partial = { ...row, _meta: { links: [componentLink] } };
+ expect(
+ normalizeBlackDuckFindings(
+ { ...blackDuckBomReport(), items: [row, partial], totalCount: 2 },
+ repository,
+ ),
+ ).toMatchObject({
+ findings: [{ source_finding_id: baseline }],
+ excluded: [{ position: 2 }],
+ });
+ expect(
+ normalizeBlackDuckFindings(
+ [{ ...partial, _meta: { links: [componentLink, origin] } }],
+ repository,
+ ).findings[0]!.source_finding_id,
+ ).toBe(baseline);
+});
diff --git a/sdk/typescript/tests-ts/blackduck-repository-import.test.ts b/sdk/typescript/tests-ts/blackduck-repository-import.test.ts
new file mode 100644
index 000000000..0e5ac6cff
--- /dev/null
+++ b/sdk/typescript/tests-ts/blackduck-repository-import.test.ts
@@ -0,0 +1,437 @@
+import { expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+import { normalizeBlackDuckFindings } from "../src/blackduck-findings.js";
+import { prepareLocalExternalImport } from "../src/external-findings-import.js";
+import {
+ listLocalExternalFindings,
+ prepareNormalizedLocalImport,
+} from "../src/external-findings-local.js";
+import type { ExternalFinding } from "../src/external-findings.js";
+import { readVendorFindings } from "../src/wiz-findings.js";
+import { normalizeInspectorFindings } from "../src/inspector-findings.js";
+import {
+ localFindingsFixture,
+ localReportFixture,
+} from "./external-findings-local-helpers.js";
+import { githubDependabotAlert } from "./support/github-dependabot-fixtures.js";
+import {
+ inspectorPackageFinding,
+ inspectorRepositoryUrl,
+} from "./support/inspector-import-fixtures.js";
+import {
+ blackDuckBomReport,
+ blackDuckBomRow,
+} from "./support/blackduck-import-fixtures.js";
+
+test("Black Duck keeps package occurrences unassessed across replay, mitigation, and missing rows", async () => {
+ const sourceRepositoryUrl = "https://git.example.test/project.git";
+ await using fixture = await localFindingsFixture({
+ remote: sourceRepositoryUrl,
+ });
+ const path = join(fixture.root, "vulnerable-components.json.gz");
+ const options = {
+ provider: "blackduck" as const,
+ sourceRepositoryUrl,
+ repository: fixture.repository,
+ sourceKey: "scanner/project-a/release-a",
+ };
+ const dependencies = { environment: fixture.environment };
+ const prepare = async (input: unknown) => {
+ await writeFile(path, gzipSync(JSON.stringify(input)));
+ return prepareLocalExternalImport(path, options, dependencies);
+ };
+ const row = {
+ ...blackDuckBomRow(),
+ packageUrl: "pkg:golang/git.example.test/team/module/[email protected]",
+ };
+ const first = await prepare(blackDuckBomReport([row]));
+ expect((await first.import()).counts.created).toBe(1);
+ expect((await (await prepare([row])).import()).counts.unchanged).toBe(1);
+ const mitigated = {
+ ...row,
+ vulnerabilityWithRemediation: {
+ ...row.vulnerabilityWithRemediation,
+ remediationStatus: "MITIGATED",
+ },
+ };
+ expect(
+ (await (await prepare(blackDuckBomReport([mitigated]))).import()).counts
+ .updated,
+ ).toBe(1);
+ await expect(
+ prepare({ ...blackDuckBomReport([row]), totalCount: 20 }),
+ ).rejects.toThrow();
+ expect(
+ (await (await prepare(blackDuckBomReport([]))).import()).counts,
+ ).toEqual({
+ created: 0,
+ updated: 0,
+ unchanged: 0,
+ });
+ const records = await listLocalExternalFindings(options, dependencies);
+ expect(records).toHaveLength(1);
+ expect(records[0]).toMatchObject({
+ provider: "blackduck",
+ sourceFindingId: first.preview.findings[0]!.source_finding_id,
+ version: 2,
+ evidence: {
+ packages: [
+ {
+ name: "git.example.test/team/module/v2",
+ ecosystem: "golang",
+ installed_version: "v2.1.0",
+ },
+ ],
+ },
+ assessment: { state: "not_assessed" },
+ });
+ const mixed = structuredClone(first.preview);
+ mixed.findings.push(
+ ...normalizeBlackDuckFindings(
+ [blackDuckBomRow(undefined, "release-b")],
+ sourceRepositoryUrl,
+ "local",
+ ).findings,
+ );
+ await expect(
+ prepareNormalizedLocalImport(mixed, options, dependencies),
+ ).rejects.toThrow(/same project version/);
+ const altered = structuredClone(first.preview);
+ altered.findings[0]!.evidence.details = {
+ kind: "sast",
+ repository: { url: "https://github.com/example/other" },
+ };
+ await expect(
+ prepareNormalizedLocalImport(altered, options, dependencies),
+ ).rejects.toThrow(/retained scanner repository/i);
+ const remote = sourceRepositoryUrl + "?repo=other";
+ execFileSync("git", ["remote", "set-url", "origin", remote], {
+ cwd: fixture.repository,
+ });
+ await expect(
+ prepareNormalizedLocalImport(first.preview, options, dependencies),
+ ).rejects.toThrow(/does not match a configured remote/);
+});
+
+test("Black Duck binds normalized summaries to native findings and comparable remotes", async () => {
+ const source = "https://git.example.test/team/application";
+ await using fixture = await localFindingsFixture({ remote: source });
+ const other = "https://git.example.test/team/other";
+ const report = normalizeBlackDuckFindings(
+ [blackDuckBomRow()],
+ source,
+ "local",
+ );
+ const native = report.findings[0]!;
+ const sourceRepositories: { url: string; platform: "github" }[] = [];
+ const prepare = (...findings: typeof report.findings) =>
+ prepareNormalizedLocalImport(
+ { read: findings.length, findings, excluded: [] },
+ {
+ provider: "blackduck",
+ sourceKey: "example",
+ repository: fixture.repository,
+ },
+ { environment: fixture.environment, sourceRepositories },
+ );
+
+ execFileSync(
+ "git",
+ ["remote", "add", "upstream", other + "?repo=different"],
+ {
+ cwd: fixture.repository,
+ },
+ );
+ const typed = (id: string, url: string) => ({
+ source_finding_id: id,
+ evidence: {
+ title: "Example",
+ severity: "unknown" as const,
+ details: { kind: "sast" as const, repository: { url } },
+ },
+ });
+ for (const alias of [
+ "ssh://[email protected]/team/application.git",
+ "https://git.example.test:443/team/application.git",
+ ]) {
+ const summary = typed("sdk-source", alias);
+ await prepare(native, summary);
+ await prepare({
+ ...native,
+ evidence: { ...native.evidence, details: summary.evidence.details },
+ });
+ }
+ for (const declaration of [
+ { details: { kind: "sast" as const, repository: { url: other } } },
+ { source_data: { sourceRepositoryUrl: other } },
+ ]) {
+ const summary = {
+ source_finding_id: "sdk-summary",
+ evidence: {
+ title: "Example",
+ severity: "unknown" as const,
+ ...declaration,
+ },
+ };
+ await expect(prepare(summary, typed("sdk-source", source))).rejects.toThrow(
+ /same project version/,
+ );
+ await expect(prepare(summary, native)).rejects.toThrow(
+ /same project version/,
+ );
+ await expect(prepare(summary)).rejects.toThrow(
+ /does not match a configured remote/,
+ );
+ }
+
+ // An HTTPS row between two SSH rows cannot erase a conflicting login or path mode.
+ for (const conflicting of [
+ "[email protected]:team/application.git",
+ "ssh://[email protected]/team/application.git",
+ ]) {
+ await expect(
+ prepare(
+ typed("first", "[email protected]:team/application.git"),
+ native,
+ typed("second", conflicting),
+ ),
+ ).rejects.toThrow(/same project version/);
+ }
+
+ const alias = typed(
+ "case-alias",
+ "https://git.example.test/Team/Application",
+ );
+ await expect(prepare(native, alias)).rejects.toThrow(/same project version/);
+ sourceRepositories.push({ url: source, platform: "github" });
+ await prepare(native, alias);
+ await prepare(typed("sdk-source", source), alias);
+
+ execFileSync("git", ["remote", "set-url", "upstream", other], {
+ cwd: fixture.repository,
+ });
+ const reference = { url: other, platform: "github" as const };
+ sourceRepositories.push(reference);
+ const pending = prepare(native);
+ reference.url = source;
+ await expect(pending).rejects.toThrow(/same project version/);
+
+ const projected = {
+ source_finding_id: native.source_finding_id,
+ evidence: {
+ title: "Example",
+ severity: "unknown" as const,
+ source_data: { sourceRepositoryUrl: source },
+ },
+ };
+ const prepareWiz = (findings: typeof report.findings, urls: string[]) =>
+ prepareNormalizedLocalImport(
+ { read: findings.length, findings, excluded: [] },
+ { provider: "wiz", sourceKey: "example", repository: fixture.repository },
+ {
+ environment: fixture.environment,
+ sourceRepositories: urls.map((url) => ({ url })),
+ },
+ );
+ const second = typed("wiz-row", other);
+ await expect(
+ prepareWiz(
+ [
+ {
+ ...projected,
+ evidence: { ...projected.evidence, details: second.evidence.details },
+ },
+ ],
+ [],
+ ),
+ ).rejects.toThrow(/retained scanner repository/i);
+ await expect(prepareWiz([projected], [other])).rejects.toThrow(
+ /reader repository/i,
+ );
+ await expect(prepareWiz([projected], [source, other])).rejects.toThrow(
+ /reader repository/i,
+ );
+ await prepareWiz([projected, second], [source, other]);
+});
+
+function projection(url: string): ExternalFinding {
+ return {
+ source_finding_id: "blackduck-bom:" + "a".repeat(64),
+ evidence: {
+ title: "Projected package",
+ severity: "high",
+ source_data: { sourceRepositoryUrl: url },
+ },
+ };
+}
+
+test.each([
+ [
+ "https://git.example.test/Team/Project",
+ "https://git.example.test/Team/Project?repo=other",
+ ],
+ [
+ "https://git.example.test/Team/Project%20data",
+ "[email protected]:Team/Project%20data",
+ ],
+])(
+ "projected source %s cannot use checkout remote %s",
+ async (source, remote) => {
+ await using f = await localFindingsFixture({ remote });
+ await expect(
+ prepareNormalizedLocalImport(
+ { read: 1, findings: [projection(source)], excluded: [] },
+ { provider: "wiz", repository: f.repository, sourceKey: "example" },
+ { environment: f.environment },
+ ),
+ ).rejects.toThrow(/does not match a configured remote/);
+ },
+);
+
+test("a Wiz file can combine projected and native package repositories", async () => {
+ await using f = await localReportFixture("wiz.json", {
+ provider: "wiz",
+ sourceKey: "example",
+ });
+ const record = {
+ id: "wiz-1",
+ name: "CVE-2099-0001",
+ detailedName: "example",
+ vendorSeverity: "HIGH",
+ vulnerableAsset: {
+ id: "branch-1",
+ nativeType: "github#repositoryBranch",
+ cloudProviderURL: "https://github.com/example/other/tree/main",
+ },
+ };
+ await f.writeJson([projection(inspectorRepositoryUrl), record]);
+ expect((await (await f.prepare()).import()).counts.created).toBe(2);
+
+ const source = "https://git.example.test/Team/Project";
+ const remote = source.toLowerCase();
+ execFileSync("git", ["-C", f.repository, "remote", "add", "origin", remote]);
+ record.vulnerableAsset.cloudProviderURL = remote + "/tree/main";
+ const projected = {
+ ...record,
+ id: projection(source).source_finding_id,
+ sourceRepositoryUrl: source,
+ };
+ const normalized = async () =>
+ prepareNormalizedLocalImport(
+ await readVendorFindings(f.file, "local"),
+ { provider: "wiz", sourceKey: f.sourceKey, repository: f.repository },
+ { environment: f.environment, sourceRepositories: [{ url: remote }] },
+ );
+ for (const prepare of [() => f.prepare(), normalized]) {
+ await f.writeJson([
+ { ...projected, vulnerableAsset: { id: "other-asset" } },
+ record,
+ ]);
+ await expect(prepare()).rejects.toThrow(
+ /does not match a configured remote/,
+ );
+ await f.writeJson([projected, record]);
+ expect((await prepare()).preview.findings).toHaveLength(2);
+ }
+});
+
+test("GitHub owns the casing of a projected Enterprise repository", async () => {
+ const source = "https://git.example.test/Team/Project";
+ await using f = await localFindingsFixture({ remote: source });
+ const report = { read: 1, findings: [projection(source)], excluded: [] };
+ const settings = { repository: f.repository, sourceKey: "example" };
+ const dependencies = {
+ environment: f.environment,
+ sourceRepositories: [{ url: source.toLowerCase() }],
+ };
+ await expect(
+ prepareNormalizedLocalImport(
+ report,
+ { ...settings, provider: "wiz" },
+ dependencies,
+ ),
+ ).rejects.toThrow(/reader repository/i);
+ await prepareNormalizedLocalImport(
+ report,
+ { ...settings, provider: "github" },
+ dependencies,
+ );
+});
+
+test.each(["github", "inspector"] as const)(
+ "%s native repository also binds the projected source",
+ async (provider) => {
+ await using f = await localFindingsFixture();
+ const findings = (url: string) => {
+ const row = projection(url);
+ if (provider === "inspector")
+ return [
+ ...normalizeInspectorFindings(
+ { findings: [inspectorPackageFinding()] },
+ inspectorRepositoryUrl,
+ "local",
+ ).findings,
+ row,
+ ];
+ row.evidence.url = githubDependabotAlert().html_url;
+ return [row];
+ };
+ const prepare = (url: string) => {
+ const rows = findings(url);
+ return prepareNormalizedLocalImport(
+ { read: rows.length, findings: rows, excluded: [] },
+ { provider, sourceKey: "example", repository: f.repository },
+ { environment: f.environment },
+ );
+ };
+ await prepare(inspectorRepositoryUrl);
+ await expect(prepare("https://github.com/example/other")).rejects.toThrow(
+ /repository|Dependabot alert/i,
+ );
+ },
+);
+
+test.each(["snyk", "endor"] as const)(
+ "%s provenance binds its own projected row and allows separate repository rows",
+ async (provider) => {
+ await using f = await localFindingsFixture();
+ const a = "https://git.example.test/team/a";
+ const b = "https://git.example.test/team/b";
+ const provenance =
+ provider === "snyk"
+ ? {
+ format: "snyk-findings-export/v1",
+ collection: { target: { repository: b } },
+ }
+ : { runContext: { versionControlProvenance: [{ repositoryUri: b }] } };
+ const prepare = (findings: ExternalFinding[], urls: string[] = []) =>
+ prepareNormalizedLocalImport(
+ { read: findings.length, findings, excluded: [] },
+ { provider, repository: f.repository, sourceKey: "example" },
+ {
+ environment: f.environment,
+ sourceRepositories: urls.map((url) => ({ url })),
+ },
+ );
+ const row = projection(a);
+ await prepare(
+ [
+ row,
+ {
+ source_finding_id: "metadata",
+ evidence: { ...row.evidence, source_data: { runContext: "nightly" } },
+ },
+ {
+ source_finding_id: "native",
+ evidence: { ...row.evidence, source_data: provenance },
+ },
+ ],
+ [a, b],
+ );
+ row.evidence.source_data = { ...row.evidence.source_data, ...provenance };
+ await expect(prepare([row])).rejects.toThrow(/original provider finding/);
+ },
+);
diff --git a/sdk/typescript/tests-ts/external-findings-publish.test.ts b/sdk/typescript/tests-ts/external-findings-publish.test.ts
index 5da2deb4d..1803513b4 100644
--- a/sdk/typescript/tests-ts/external-findings-publish.test.ts
+++ b/sdk/typescript/tests-ts/external-findings-publish.test.ts
@@ -70,6 +70,11 @@ import {
inspectorPackageFinding,
inspectorRepositoryUrl,
} from "./support/inspector-import-fixtures.js";
+import { normalizeBlackDuckFindings } from "../src/blackduck-findings.js";
+import {
+ blackDuckBomReport,
+ blackDuckBomRow,
+} from "./support/blackduck-import-fixtures.js";
const cleanups: (() => Promise<void>)[] = [];
afterEach(async () => {
@@ -1211,6 +1216,265 @@ test("a normalized Inspector retry checks its typed repository without native ev
expect(f.posts).toHaveLength(1);
});
+test.each([
+ ["wiz", "2dfdb44c2c7494f4eed20e59244df967598fc3a284589ec2f6c3a24bfff7b2d0"],
+ [
+ "inspector",
+ "d0ba21fbe6c5927206db937694c98f69ad59e33fc390cae6eb6bd01249b5ca10",
+ ],
+ [
+ "github",
+ "2dc327e13b7b9548e828b0fe3193988a26c53c9c956b364c69990abdb418c298",
+ ],
+] as const)(
+ "checks a saved %s request from before Black Duck provider checks",
+ async (provider, checkpointKey) => {
+ const f = await fixture();
+ const settings = { ...options, provider };
+ const environment: NodeJS.ProcessEnv = { ...f.environment };
+ // These persisted keys came from the default deployment.
+ delete environment["CODEX_SECURITY_CLOUD_BASE_URL"];
+ delete environment["CODEX_SECURITY_CLOUD_WEB_URL"];
+ const alert = provider === "github" ? githubDependabotAlert() : undefined;
+ const other = "https://github.com/example/different";
+ const row = normalized();
+ const finding = {
+ source_finding_id: alert
+ ? "blackduck-bom:" + "a".repeat(64)
+ : row.source_finding_id,
+ evidence: validateExternalEvidence(
+ alert
+ ? {
+ title: "Dependabot alert",
+ severity: "high",
+ url: alert.html_url,
+ source_data: { ...alert, sourceRepositoryUrl: other },
+ }
+ : { ...row.evidence, source_data: { format: "blackduck-bom-6" } },
+ ),
+ };
+ const input = { read: 1, excluded: [], findings: [finding] };
+ const prepare = () =>
+ prepareNormalizedExternalPublication(input, settings, {
+ ...f.deps,
+ environment,
+ });
+
+ // The previous publisher accepted this opaque evidence. Keep its checkpoint
+ // filename and digests so this exercises recovery across the provider change.
+ const directory = join(
+ f.environment.CODEX_SECURITY_STATE_DIR,
+ "external-finding-publications",
+ );
+ const digest = alert
+ ? "abe417c10599f27dc9adc599465af29f693069deaca7942f79c952871216070e"
+ : "d3001de83673b0f42b1d1d42cb19ea546869d41ed99504ca213b303267bb1346";
+ const request = {
+ request_id: "efbc3c2e-0462-4411-89aa-9ced1d34223c",
+ repository: {
+ id: options.repository,
+ repo_connector_id: "github",
+ environment_id: f.state.environmentId,
+ reset_marker: f.state.marker,
+ },
+ source: { provider, source_key: options.sourceKey },
+ items: [{ client_id: "item-1", ...finding, expected_version: 0 }],
+ };
+ await mkdir(directory, { recursive: true, mode: 0o700 });
+ await writeFile(
+ join(directory, `${checkpointKey}.pending.json`),
+ JSON.stringify({
+ accountId: "synthetic-account",
+ requests: [request],
+ inputProjection: { inputDigest: digest, savedEvidenceDigest: digest },
+ }),
+ { mode: 0o600 },
+ );
+
+ if (alert) {
+ // The original publisher selected the alert's repository. Changing the
+ // catalog to match the projection must not permit replay to another repo.
+ const originalRepository = f.state.repositoryUrl;
+ f.state.repositoryUrl = other;
+ await expect(prepare()).rejects.toThrow(
+ `belongs to "${originalRepository}"`,
+ );
+ expect(f.posts).toHaveLength(0);
+ return;
+ }
+ const retry = await prepare();
+ expect(retry.preview.resumed).toBe(true);
+ expect((await retry.publish()).counts.created).toBe(1);
+ expect(f.posts.map((body) => JSON.parse(body))).toEqual([request]);
+ await expect(prepare()).rejects.toThrow("requires the blackduck provider");
+ },
+);
+
+test.each(["wiz", "inspector"] as const)(
+ "rechecks a projected Black Duck repository on a saved %s publication",
+ async (provider) => {
+ const f = await fixture();
+ const source = f.state.repositoryUrl;
+ const input = normalizeBlackDuckFindings([blackDuckBomRow()], source);
+ input.findings[0]!.evidence.source_data = { sourceRepositoryUrl: source };
+ const prepare = () =>
+ prepareNormalizedExternalPublication(
+ input,
+ { ...options, provider },
+ f.deps,
+ );
+
+ f.state.loseResponse = true;
+ await expect((await prepare()).publish()).rejects.toThrow(
+ "resume the saved request",
+ );
+ f.state.repositoryUrl = "https://github.com/example/different";
+ await expect(prepare()).rejects.toThrow(
+ "does not match the selected Cloud repository",
+ );
+ expect(f.posts).toHaveLength(1);
+ f.state.repositoryUrl = source;
+ const retry = await prepare();
+ expect(retry.preview.resumed).toBe(true);
+ await retry.publish();
+ expect(f.posts).toHaveLength(2);
+ expect(f.posts[1]).toBe(f.posts[0]);
+ },
+);
+
+test("Black Duck Cloud replay preserves package occurrence and rejects a different destination", async () => {
+ const row = {
+ ...blackDuckBomRow(),
+ packageUrl: "pkg:composer/example/[email protected]",
+ };
+ const report = blackDuckBomReport([row]);
+ const correct = await fixture(report);
+ const selected = {
+ ...options,
+ provider: "blackduck" as const,
+ sourceKey: "scanner/project-a/release-a",
+ sourceRepositoryUrl: "https://github.com/example/project",
+ };
+ const prepare = () =>
+ prepareExternalPublication(correct.file, selected, correct.deps);
+ const first = await prepare();
+ expect(correct.posts).toHaveLength(0);
+ expect(first.preview.requests[0]!.source.provider).toBe("blackduck");
+ first.preview.requests[0]!.items[0]!.evidence.source_data![
+ "sourceRepositoryUrl"
+ ] = "https://git.example.test/example/project";
+ correct.state.loseResponse = true;
+ await expect(first.publish()).rejects.toThrow("resume the saved request");
+ expect([...correct.reports.values()][0]!.evidence.source_data).toMatchObject({
+ sourceRepositoryUrl: selected.sourceRepositoryUrl,
+ });
+ const retry = await prepare();
+ expect(retry.preview.resumed).toBe(true);
+ expect((await retry.publish()).counts.created).toBe(1);
+ expect(correct.posts).toHaveLength(2);
+ expect(correct.posts[1]).toBe(correct.posts[0]);
+ expect([...correct.reports.values()][0]!.evidence.packages).toMatchObject([
+ {
+ name: "example/library",
+ ecosystem: "composer",
+ installed_version: "2.0",
+ },
+ ]);
+ expect((await (await prepare()).publish()).counts.unchanged).toBe(1);
+ const foreign = await fixture(report, "https://github.com/example/other");
+ await expect(
+ prepareExternalPublication(foreign.file, selected, foreign.deps),
+ ).rejects.toThrow(/does not match/i);
+ expect(foreign.posts).toHaveLength(0);
+ const native = normalizeBlackDuckFindings(
+ report,
+ selected.sourceRepositoryUrl,
+ );
+ const mixed = structuredClone(native);
+ mixed.findings.push(
+ ...normalizeBlackDuckFindings(
+ [blackDuckBomRow(undefined, "release-b")],
+ selected.sourceRepositoryUrl,
+ ).findings,
+ );
+ mixed.read = mixed.findings.length;
+ await expect(
+ prepareNormalizedExternalPublication(mixed, selected, correct.deps),
+ ).rejects.toThrow(/same project version/);
+ await expect(
+ prepareNormalizedExternalPublication(
+ native,
+ { ...selected, provider: "wiz" },
+ foreign.deps,
+ ),
+ ).rejects.toThrow(/requires the blackduck provider/);
+ const stripped = structuredClone(native);
+ const data = stripped.findings[0]!.evidence.source_data!;
+ delete data["row"];
+ delete data["format"];
+ const wiz = { ...selected, provider: "wiz" as const };
+ const matching = await fixture();
+ for (const sourceData of [
+ data,
+ { sourceRepositoryUrl: selected.sourceRepositoryUrl },
+ ]) {
+ stripped.findings[0]!.evidence.source_data = sourceData;
+ await expect(
+ prepareNormalizedExternalPublication(stripped, wiz, foreign.deps),
+ ).rejects.toThrow(/does not match the selected Cloud repository/);
+ await prepareNormalizedExternalPublication(stripped, wiz, matching.deps);
+ }
+ for (const url of [
+ "ssh://[email protected]/team/project.git",
+ ` ${selected.sourceRepositoryUrl}`,
+ ]) {
+ stripped.findings[0]!.evidence.source_data = { sourceRepositoryUrl: url };
+ await expect(
+ prepareNormalizedExternalPublication(stripped, wiz, foreign.deps),
+ ).rejects.toThrow();
+ }
+ expect(foreign.posts).toHaveLength(0);
+ stripped.findings[0]!.evidence.source_data = { upstream: data };
+ await prepareNormalizedExternalPublication(stripped, wiz, foreign.deps);
+ delete stripped.findings[0]!.evidence.source_data;
+ await expect(
+ prepareNormalizedExternalPublication(stripped, selected, foreign.deps),
+ ).rejects.toThrow(/retained Black Duck/);
+ const normalized = structuredClone(native);
+ normalized.findings[0]!.source_finding_id = "sdk-id";
+ normalized.findings[0]!.evidence.source_data = {
+ sourceRepositoryUrl: selected.sourceRepositoryUrl,
+ projectVersionUrl: "https://scanner.example.test/dashboard/version",
+ };
+ await prepareNormalizedExternalPublication(
+ normalized,
+ selected,
+ correct.deps,
+ );
+
+ const summary = normalized.findings[0]!;
+ delete summary.evidence.source_data;
+ summary.evidence.details = {
+ kind: "sast",
+ repository: { url: selected.sourceRepositoryUrl },
+ };
+ const prepareSummary = () =>
+ prepareNormalizedExternalPublication(normalized, selected, correct.deps);
+ const prepared = await prepareSummary();
+ const expected = JSON.stringify(prepared.preview.requests[0]);
+ correct.state.loseResponse = true;
+ await expect(prepared.publish()).rejects.toThrow("resume the saved request");
+ const posted = correct.posts.length;
+ correct.state.repositoryUrl = foreign.state.repositoryUrl;
+ await expect(prepareSummary()).rejects.toThrow(/does not match/);
+ expect(correct.posts).toHaveLength(posted);
+ correct.state.repositoryUrl = selected.sourceRepositoryUrl;
+ const resumed = await prepareSummary();
+ expect(resumed.preview.resumed).toBe(true);
+ await resumed.publish();
+ expect(correct.posts.slice(-2)).toEqual([expected, expected]);
+});
+
test("CLI preview and rejected confirmation never POST or persist an upload", async () => {
const f = await fixture();
const cli = createCliTest(main);
diff --git a/sdk/typescript/tests-ts/support/blackduck-import-fixtures.ts b/sdk/typescript/tests-ts/support/blackduck-import-fixtures.ts
new file mode 100644
index 000000000..ee3e7bd05
--- /dev/null
+++ b/sdk/typescript/tests-ts/support/blackduck-import-fixtures.ts
@@ -0,0 +1,38 @@
+const api = "https://scanner.example.test/api";
+const projectVersion = `${api}/projects/project-a/versions/release-a`;
+const component = "components/component-a/versions/version-a";
+
+export function blackDuckBomRow(
+ advisory = "BDSA-2099-0001",
+ version = "release-a",
+) {
+ return {
+ componentVersion: `${api}/${component}`,
+ componentName: "Example Library",
+ componentVersionName: "1.0",
+ componentVersionOriginName: "maven",
+ componentVersionOriginId: "example:library:1.0",
+ vulnerabilityWithRemediation: {
+ source: "BDSA",
+ vulnerabilityName: advisory,
+ severity: "HIGH",
+ remediationStatus: "NEW",
+ },
+ _meta: {
+ links: [
+ {
+ rel: "matched-files",
+ href: `${api}/projects/project-a/versions/${version}/${component}/origins/origin-a/matched-files`,
+ },
+ ],
+ },
+ };
+}
+
+export function blackDuckBomReport(items = [blackDuckBomRow()]) {
+ return {
+ totalCount: items.length,
+ items,
+ _meta: { href: `${projectVersion}/vulnerable-bom-components`, links: [] },
+ };
+}