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

fix(import): preserve complete local vendor evidence (#1886)

Michael D'Angelo8f19b16b82e4
diff --git a/sdk/typescript/src/endor-findings.ts b/sdk/typescript/src/endor-findings.ts
index 9568566be..9b78d760c 100644
--- a/sdk/typescript/src/endor-findings.ts
+++ b/sdk/typescript/src/endor-findings.ts
@@ -1,3 +1,4 @@
+import type { ExternalImportTarget } from "./external-import-contract.js";
import { validateExternalEvidence } from "./external-import-contract.js";
import type { ExternalFindings } from "./external-findings.js";
import { isRecord } from "./record.js";
@@ -31,10 +32,13 @@ export function endorRepositoryUrls(sourceData: unknown): string[] {
}
/** Saved Endor Finding objects, an array, or an unmasked ListFindingsResponse. */
-export function normalizeEndorFindings(input: unknown): ExternalFindings {
+export function normalizeEndorFindings(
+ input: unknown,
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
const root = Array.isArray(input) ? null : record(input, "Endor report");
if (root?.["version"] === "2.1.0" && root["runs"] !== undefined)
- return normalizeEndorSarif(root);
+ return normalizeEndorSarif(root, target);
const list =
root?.["list"] === undefined ? null : record(root["list"], "Endor list");
if (list) {
@@ -136,34 +140,39 @@ export function normalizeEndorFindings(input: unknown): ExternalFindings {
const updated = text(meta["update_time"]);
return {
source_finding_id: id,
- evidence: validateExternalEvidence({
- title: requiredText(meta["name"], "Endor finding title"),
- description:
- [
- text(spec["summary"]),
- text(spec["explanation"]),
- text(spec["remediation"]),
- ]
- .filter(Boolean)
- .join("\n\n") || text(meta["description"]),
- severity,
- branch:
- context["type"] === "CONTEXT_TYPE_REF" ? text(context["id"]) : null,
- code_revision: text(
- record(
- spec["source_code_version"] ?? {},
- "Endor source code version",
- )["sha"],
- ),
- source_updated_at:
- updated === null ? null : Math.floor(Date.parse(updated) / 1000),
- advisory_ids: [
- ...new Set([...(advisory ? [advisory] : []), ...aliases]),
- ],
- packages,
- locations,
- source_data: structuredClone(finding),
- }),
+ evidence: validateExternalEvidence(
+ {
+ title: requiredText(meta["name"], "Endor finding title"),
+ description:
+ [
+ text(spec["summary"]),
+ text(spec["explanation"]),
+ text(spec["remediation"]),
+ ]
+ .filter(Boolean)
+ .join("\n\n") || text(meta["description"]),
+ severity,
+ branch:
+ context["type"] === "CONTEXT_TYPE_REF"
+ ? text(context["id"])
+ : null,
+ code_revision: text(
+ record(
+ spec["source_code_version"] ?? {},
+ "Endor source code version",
+ )["sha"],
+ ),
+ source_updated_at:
+ updated === null ? null : Math.floor(Date.parse(updated) / 1000),
+ advisory_ids: [
+ ...new Set([...(advisory ? [advisory] : []), ...aliases]),
+ ],
+ packages,
+ locations,
+ source_data: structuredClone(finding),
+ },
+ target,
+ ),
};
},
(value) =>
@@ -171,11 +180,15 @@ export function normalizeEndorFindings(input: unknown): ExternalFindings {
record(value, "Endor finding")["uuid"],
"Endor finding uuid",
),
+ target,
);
}
/** Endor's documented SARIF producer uses properties.finding-uuid, not its rule name. */
-export function normalizeEndorSarif(input: unknown): ExternalFindings {
+export function normalizeEndorSarif(
+ input: unknown,
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
const document = record(input, "Endor SARIF");
if (document["version"] !== "2.1.0")
throw new Error("Expected Endor SARIF 2.1.0.");
@@ -300,37 +313,43 @@ export function normalizeEndorSarif(input: unknown): ExternalFindings {
});
return {
source_finding_id: id,
- evidence: validateExternalEvidence({
- title: text(short["text"]) ?? text(rule["name"]) ?? ruleId,
- url: text(properties["finding-url"]),
- description: [
- text(message["markdown"]) ?? text(message["text"]),
- text(full["text"]),
- text(help["markdown"]) ?? text(help["text"]),
- ]
- .filter(Boolean)
- .join("\n\n"),
- // Diagnostic level and CVSS are not Endor's finding severity. Keep both as source evidence.
- severity: "unknown",
- locations: [
- ...new Map(
- locations.map((location) => [JSON.stringify(location), location]),
- ).values(),
- ],
- source_data: structuredClone({
- ...context,
- runContext: sarifRunContextForResult(
- context.runContext,
- result,
+ evidence: validateExternalEvidence(
+ {
+ title: text(short["text"]) ?? text(rule["name"]) ?? ruleId,
+ url: text(properties["finding-url"]),
+ description: [
+ text(message["markdown"]) ?? text(message["text"]),
+ text(full["text"]),
+ text(help["markdown"]) ?? text(help["text"]),
+ ]
+ .filter(Boolean)
+ .join("\n\n"),
+ // Diagnostic level and CVSS are not Endor's finding severity. Keep both as source evidence.
+ severity: "unknown",
+ locations: [
+ ...new Map(
+ locations.map((location) => [
+ JSON.stringify(location),
+ location,
+ ]),
+ ).values(),
+ ],
+ source_data: structuredClone({
+ ...context,
+ runContext: sarifRunContextForResult(
+ context.runContext,
+ result,
+ rule,
+ context.documentContext,
+ context.driverContext,
+ context.toolContext,
+ ),
rule,
- context.documentContext,
- context.driverContext,
- context.toolContext,
- ),
- rule,
- result,
- }),
- }),
+ result,
+ }),
+ },
+ target,
+ ),
};
},
({ result }) =>
@@ -341,11 +360,13 @@ export function normalizeEndorSarif(input: unknown): ExternalFindings {
)["finding-uuid"],
"Endor finding-uuid",
),
+ target,
);
}
export async function readEndorFindings(
path: string,
+ target: ExternalImportTarget = "cloud",
): Promise<ExternalFindings> {
- return normalizeEndorFindings(await readScannerJson(path));
+ return normalizeEndorFindings(await readScannerJson(path), target);
}
diff --git a/sdk/typescript/src/external-findings-import.ts b/sdk/typescript/src/external-findings-import.ts
index dd4391256..b06ad5f1c 100644
--- a/sdk/typescript/src/external-findings-import.ts
+++ b/sdk/typescript/src/external-findings-import.ts
@@ -18,7 +18,7 @@ export async function prepareLocalExternalImport(
) {
dependencies.signal?.throwIfAborted();
const parsed = await abortable(
- () => readExternalFindings(path, options),
+ () => readExternalFindings(path, options, "local"),
dependencies.signal,
);
let sourceRepositories = parsed.sourceRepositories ?? [];
diff --git a/sdk/typescript/src/external-findings-read.ts b/sdk/typescript/src/external-findings-read.ts
index 00230860e..a50e6292e 100644
--- a/sdk/typescript/src/external-findings-read.ts
+++ b/sdk/typescript/src/external-findings-read.ts
@@ -3,6 +3,7 @@ import type {
ExternalPublicationInput,
ExternalSourceRepository,
} from "./external-findings.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";
@@ -30,9 +31,10 @@ export interface ReadExternalFindings {
export async function readExternalFindings(
path: string,
options: ExternalFindingsReaderOptions,
+ target: ExternalImportTarget = "cloud",
): Promise<ReadExternalFindings> {
if (options.provider === "snyk") {
- const findings = await readSnykFindings(path);
+ const findings = await readSnykFindings(path, target);
return {
findings,
sourceRepositories: findings.findings.flatMap(({ evidence }) =>
@@ -43,9 +45,13 @@ export async function readExternalFindings(
};
}
if (options.provider === "semgrep") {
- const findings = await readSemgrepFindings(path, {
- sourceRepositoryUrl: options.sourceRepositoryUrl ?? "",
- });
+ const findings = await readSemgrepFindings(
+ path,
+ {
+ sourceRepositoryUrl: options.sourceRepositoryUrl ?? "",
+ },
+ target,
+ );
const sourceRepositories = findings.findings.flatMap(({ evidence }) => {
const context = evidence.source_data?.["runContext"];
const references = isRecord(context)
@@ -64,7 +70,7 @@ export async function readExternalFindings(
return { findings, sourceRepositories };
}
if (options.provider === "endor") {
- const parsed = await readEndorFindings(path);
+ const parsed = await readEndorFindings(path, target);
return {
findings: parsed,
sourceRepositories: parsed.findings.flatMap((finding) =>
@@ -75,8 +81,8 @@ export async function readExternalFindings(
};
}
if (options.provider === "github")
- return { findings: await readGitHubFindings(path) };
- const publication = await readVendorFindingsForPublication(path);
+ return { findings: await readGitHubFindings(path, target) };
+ const publication = await readVendorFindingsForPublication(path, target);
// Raw package exports keep repository-branch URLs in retained source data.
const sourceRepositories = publication.current.findings.flatMap(
({ evidence }) => {
diff --git a/sdk/typescript/src/external-import-contract.ts b/sdk/typescript/src/external-import-contract.ts
index 4cb105895..e384fdeb6 100644
--- a/sdk/typescript/src/external-import-contract.ts
+++ b/sdk/typescript/src/external-import-contract.ts
@@ -15,6 +15,15 @@ const ajv = new Ajv2020({
validateFormats: false,
useDefaults: true,
});
+
+/** Local storage accepts complete evidence; Cloud publication has payload limits. */
+export type ExternalImportTarget = "local" | "cloud";
+
+const localSchema = JSON.parse(
+ JSON.stringify(schema, (key, value: unknown) =>
+ key === "maxLength" || key === "maxItems" ? undefined : value,
+ ),
+) as typeof schema;
const STRING_BYTE_LIMITS: Readonly<Record<string, number>> = {
description: 65536,
snippet: 65536,
@@ -56,10 +65,13 @@ export function cloudRepositoryUrlKey(value: string): string {
// Cloud ImportModel applies these constraints to both requests and responses.
// Its UTF-8 limits are not exported as JSON Schema character limits: even a
// plain string field such as a receipt error message inherits the 512-byte bound.
-function validateModelStrings(input: unknown): void {
+function validateModelStrings(
+ input: unknown,
+ target: ExternalImportTarget,
+): void {
if (input === null || typeof input !== "object") return;
if (Array.isArray(input)) {
- for (const item of input) validateModelStrings(item);
+ for (const item of input) validateModelStrings(item, target);
return;
}
for (const [field, value] of Object.entries(input)) {
@@ -73,7 +85,7 @@ function validateModelStrings(input: unknown): void {
`${field} must be nonempty and contain no NUL characters.`,
);
const limit = STRING_BYTE_LIMITS[field] ?? 512;
- if (Buffer.byteLength(value) > limit)
+ if (target === "cloud" && Buffer.byteLength(value) > limit)
throw new Error(
`${field} exceeds its Cloud limit of ${limit} UTF-8 bytes.`,
);
@@ -81,11 +93,14 @@ function validateModelStrings(input: unknown): void {
Array.isArray(value) &&
value.every((item) => typeof item === "string")
) {
- if (value.some((item) => Buffer.byteLength(item) > 512))
+ if (
+ target === "cloud" &&
+ value.some((item) => Buffer.byteLength(item) > 512)
+ )
throw new Error(
`${field} entries exceed the Cloud limit of 512 UTF-8 bytes.`,
);
- } else validateModelStrings(value);
+ } else validateModelStrings(value, target);
}
}
@@ -95,7 +110,6 @@ type ModelSchema = {
properties?: Record<string, ModelSchema>;
[key: string]: unknown;
};
-const modelSchemas: Record<string, ModelSchema> = schema.$defs;
const detailValidators = new Map<string, ReturnType<typeof ajv.compile>>();
/** AJV does not apply defaults through nullable anyOf references. Validate the
@@ -104,6 +118,7 @@ const detailValidators = new Map<string, ReturnType<typeof ajv.compile>>();
function materializeDetailDefaults(
value: unknown,
fieldSchema: ModelSchema,
+ target: ExternalImportTarget,
): void {
if (value === null || typeof value !== "object" || Array.isArray(value))
return;
@@ -111,11 +126,14 @@ function materializeDetailDefaults(
fieldSchema.$ref ?? fieldSchema.anyOf?.find((branch) => branch.$ref)?.$ref;
if (!reference) return;
const name = reference.split("/").at(-1)!;
- const definition = modelSchemas[name]!;
- let check = detailValidators.get(reference);
+ const modelSchema = target === "local" ? localSchema : schema;
+ const definition: ModelSchema =
+ modelSchema.$defs[name as keyof typeof schema.$defs]!;
+ const key = `${target}:${reference}`;
+ let check = detailValidators.get(key);
if (!check) {
- check = ajv.compile({ $defs: schema.$defs, $ref: reference });
- detailValidators.set(reference, check);
+ check = ajv.compile({ $defs: modelSchema.$defs, $ref: reference });
+ detailValidators.set(key, check);
}
if (!check(value))
throw new Error(`${name}: ${ajv.errorsText(check.errors)}`);
@@ -125,10 +143,14 @@ function materializeDetailDefaults(
materializeDetailDefaults(
(value as Record<string, unknown>)[field],
childSchema,
+ target,
);
}
-function normalizeEvidenceDetails(value: unknown): void {
+function normalizeEvidenceDetails(
+ value: unknown,
+ target: ExternalImportTarget,
+): void {
if (value !== null && typeof value === "object") {
const fields = value as Record<string, unknown>;
// Cloud omits these new optional fields when null. Preserve every legacy
@@ -151,38 +173,47 @@ function normalizeEvidenceDetails(value: unknown): void {
delete (details as Record<string, unknown>)[field];
materializeDetailDefaults(
fields["details"],
- modelSchemas["ImportedFindingEvidence"]!.properties!["details"]!,
+ schema.$defs.ImportedFindingEvidence.properties.details,
+ target,
);
}
}
}
-function validator<T>(name: keyof typeof schema.$defs) {
+function validator<T>(
+ name: keyof typeof schema.$defs,
+ target: ExternalImportTarget = "cloud",
+) {
const check = ajv.compile<T>({
- $defs: schema.$defs,
+ $defs: (target === "local" ? localSchema : schema).$defs,
$ref: `#/$defs/${name}`,
});
return (input: unknown): T => {
- if (name === "ImportedFindingEvidence") normalizeEvidenceDetails(input);
+ if (name === "ImportedFindingEvidence")
+ normalizeEvidenceDetails(input, target);
else if (input && typeof input === "object") {
if (name === "SourceReport" && "evidence" in input)
- normalizeEvidenceDetails(input.evidence);
+ normalizeEvidenceDetails(input.evidence, target);
if (
name === "FindingImportRequest" &&
"items" in input &&
Array.isArray(input.items)
)
for (const item of input.items)
- normalizeEvidenceDetails(item?.evidence);
+ normalizeEvidenceDetails(item?.evidence, target);
}
if (!check(input))
throw new Error(`${name}: ${ajv.errorsText(check.errors)}`);
- validateModelStrings(input);
+ validateModelStrings(input, target);
return input;
};
}
const evidence = validator<ExternalFindingEvidence>("ImportedFindingEvidence");
+const localEvidence = validator<ExternalFindingEvidence>(
+ "ImportedFindingEvidence",
+ "local",
+);
const request = validator<FindingImportRequest>("FindingImportRequest");
export const validateImportReceipt = validator<FindingImportReceipt>(
"FindingImportReceipt",
@@ -196,8 +227,9 @@ export const validateSourceReport = validator<SourceReport>("SourceReport");
export function validateExternalEvidence(
input: unknown,
+ target: ExternalImportTarget = "cloud",
): ExternalFindingEvidence {
- const result = evidence(input);
+ const result = (target === "local" ? localEvidence : evidence)(input);
for (const location of result.locations ?? []) {
const path = location.path.replaceAll("\\", "/");
if (
@@ -271,11 +303,13 @@ export function validateExternalEvidence(
"Evidence URLs must be HTTP(S) links without credentials.",
);
}
+ // Local evidence still has to be serializable JSON, including acyclic source data.
+ if (target === "local") JSON.stringify(result);
let numericByteAdjustment = 0;
const pending: [unknown, number][] = [[result, 0]];
while (pending.length > 0) {
const [value, depth] = pending.pop()!;
- if (depth > 20)
+ if (target === "cloud" && depth > 20)
throw new Error("Evidence exceeds the Cloud JSON depth limit of 20.");
if (value !== null && typeof value === "object") {
for (const child of Object.values(value))
@@ -298,8 +332,9 @@ export function validateExternalEvidence(
}
}
if (
+ target === "cloud" &&
Buffer.byteLength(JSON.stringify(result)) + numericByteAdjustment >
- 256 * 1024
+ 256 * 1024
)
throw new Error("Evidence exceeds the Cloud limit of 256 KiB.");
return result;
diff --git a/sdk/typescript/src/github-findings.ts b/sdk/typescript/src/github-findings.ts
index 91df1104c..f998cdd45 100644
--- a/sdk/typescript/src/github-findings.ts
+++ b/sdk/typescript/src/github-findings.ts
@@ -1,3 +1,4 @@
+import type { ExternalImportTarget } from "./external-import-contract.js";
import { hash } from "node:crypto";
import { CodexSecurityError, errorMessage } from "./errors.js";
import { validateExternalEvidence } from "./external-import-contract.js";
@@ -48,7 +49,10 @@ function severity(value: unknown): string {
: "unknown";
}
-function codeScanningFinding(record: Record<string, unknown>): ExternalFinding {
+function codeScanningFinding(
+ record: Record<string, unknown>,
+ target: ExternalImportTarget = "cloud",
+): ExternalFinding {
const repository = repositoryName(record["repository"]);
const alert = object(record["alert"]);
const number = record["number"];
@@ -104,43 +108,51 @@ function codeScanningFinding(record: Record<string, unknown>): ExternalFinding {
const sourceId = `${host}/${repository.toLowerCase()}/code-scanning/${number}/${hash("sha256", ref)}`;
return {
source_finding_id: sourceId,
- evidence: validateExternalEvidence({
- title:
- text(rule?.["name"]) ??
- text(rule?.["description"]) ??
- `GitHub code-scanning alert #${number}`,
- severity: severity(rule?.["security_severity_level"]),
- description:
- [...new Set([message, description].filter(Boolean))].join("\n\n") ||
- null,
- url,
- locations: path ? [{ path, line: location?.["start_line"] ?? null }] : [],
- branch: ref,
- code_revision: text(instance?.["commit_sha"]),
- source_updated_at: sourceTimestamp(alert["updated_at"]),
- source_data: record,
- details: {
- kind: "sast",
- repository: {
- url: `${origin}/${repository}`,
- name: repository,
+ evidence: validateExternalEvidence(
+ {
+ title:
+ text(rule?.["name"]) ??
+ text(rule?.["description"]) ??
+ `GitHub code-scanning alert #${number}`,
+ severity: severity(rule?.["security_severity_level"]),
+ description:
+ [...new Set([message, description].filter(Boolean))].join("\n\n") ||
+ null,
+ url,
+ locations: path
+ ? [{ path, line: location?.["start_line"] ?? null }]
+ : [],
+ branch: ref,
+ code_revision: text(instance?.["commit_sha"]),
+ source_updated_at: sourceTimestamp(alert["updated_at"]),
+ source_data: record,
+ details: {
+ kind: "sast",
+ repository: {
+ url: `${origin}/${repository}`,
+ name: repository,
+ },
+ // Dismissal covers every branch; detection state belongs to the selected ref.
+ source_status:
+ alert["state"] === "dismissed"
+ ? "dismissed"
+ : (text(instance?.["state"]) ?? text(alert["state"])),
+ scanner_origin: text(tool?.["name"]),
+ rule: { id: text(rule?.["id"]), name: text(rule?.["name"]) },
+ weakness_ids: weaknessIds,
+ remediation_instructions: text(rule?.["help"]),
+ code: path ? { end_line: location?.["end_line"] ?? null } : null,
},
- // Dismissal covers every branch; detection state belongs to the selected ref.
- source_status:
- alert["state"] === "dismissed"
- ? "dismissed"
- : (text(instance?.["state"]) ?? text(alert["state"])),
- scanner_origin: text(tool?.["name"]),
- rule: { id: text(rule?.["id"]), name: text(rule?.["name"]) },
- weakness_ids: weaknessIds,
- remediation_instructions: text(rule?.["help"]),
- code: path ? { end_line: location?.["end_line"] ?? null } : null,
},
- }),
+ target,
+ ),
};
}
-function advisoryFinding(record: Record<string, unknown>): ExternalFinding {
+function advisoryFinding(
+ record: Record<string, unknown>,
+ target: ExternalImportTarget = "cloud",
+): ExternalFinding {
const repository = repositoryName(record["repository"]);
const advisory = object(record["advisory"]);
const id = text(record["ghsaId"]);
@@ -212,40 +224,46 @@ function advisoryFinding(record: Record<string, unknown>): ExternalFinding {
const cwes = Array.isArray(advisory["cwes"]) ? advisory["cwes"] : [];
return {
source_finding_id: `${host}/${selection === "repository" ? repository.toLowerCase() : "global"}/security-advisory/${id.toUpperCase()}`,
- evidence: validateExternalEvidence({
- title: text(advisory["summary"]) ?? id,
- severity: severity(advisory["severity"]),
- description: text(advisory["description"]),
- url,
- advisory_ids: [...new Set(advisoryIds)],
- packages,
- source_updated_at: sourceTimestamp(advisory["updated_at"]),
- source_data: record,
- details: {
- kind: "advisory",
- advisory: { source: selection },
- ...(selection === "repository"
- ? {
- repository: {
- url: `${origin}/${repository}`,
- name: repository,
- },
- }
- : {}),
- source_status: text(advisory["withdrawn_at"])
- ? "withdrawn"
- : (text(advisory["state"]) ??
- (selection === "global" ? "published" : null)),
- scanner_origin: "GitHub Security Advisories",
- weakness_ids: cwes
- .map((value) => text(object(value)?.["cwe_id"]))
- .filter((value): value is string => value !== null),
+ evidence: validateExternalEvidence(
+ {
+ title: text(advisory["summary"]) ?? id,
+ severity: severity(advisory["severity"]),
+ description: text(advisory["description"]),
+ url,
+ advisory_ids: [...new Set(advisoryIds)],
+ packages,
+ source_updated_at: sourceTimestamp(advisory["updated_at"]),
+ source_data: record,
+ details: {
+ kind: "advisory",
+ advisory: { source: selection },
+ ...(selection === "repository"
+ ? {
+ repository: {
+ url: `${origin}/${repository}`,
+ name: repository,
+ },
+ }
+ : {}),
+ source_status: text(advisory["withdrawn_at"])
+ ? "withdrawn"
+ : (text(advisory["state"]) ??
+ (selection === "global" ? "published" : null)),
+ scanner_origin: "GitHub Security Advisories",
+ weakness_ids: cwes
+ .map((value) => text(object(value)?.["cwe_id"]))
+ .filter((value): value is string => value !== null),
+ },
},
- }),
+ target,
+ ),
};
}
-function normalizeRecords(records: readonly unknown[]): ExternalFindings {
+function normalizeRecords(
+ records: readonly unknown[],
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
const result: ExternalFindings = {
read: records.length,
findings: [],
@@ -258,9 +276,9 @@ function normalizeRecords(records: readonly unknown[]): ExternalFindings {
if (!record) throw new Error("GitHub finding must be an object.");
let finding: ExternalFinding;
if (record["source"] === "github-code-scanning")
- finding = codeScanningFinding(record);
+ finding = codeScanningFinding(record, target);
else if (record["source"] === "github-security-advisory")
- finding = advisoryFinding(record);
+ finding = advisoryFinding(record, target);
else
throw new Error(
"Expected saved output from import github or import github-advisories; raw or incomplete API responses need an explicit mapping.",
@@ -286,24 +304,30 @@ function normalizeRecords(records: readonly unknown[]): ExternalFindings {
/** Map selected code-scanning instances while retaining complete upstream evidence. */
export function normalizeGitHubCodeScanningAlerts(
alerts: readonly ImportedGitHubCodeScanningAlert[],
+ target: ExternalImportTarget = "cloud",
): ExternalFindings {
- return normalizeRecords(alerts);
+ return normalizeRecords(alerts, target);
}
/** Map advisory disclosures without asserting an installed vulnerable dependency. */
export function normalizeGitHubAdvisories(
advisories: readonly ImportedGitHubAdvisory[],
+ target: ExternalImportTarget = "cloud",
): ExternalFindings {
- return normalizeRecords(advisories);
+ return normalizeRecords(advisories, target);
}
/** Read unfiltered JSON/JSONL output saved by the read-only GitHub import commands. */
export async function readGitHubFindings(
path: string,
+ target: ExternalImportTarget = "cloud",
): Promise<ExternalFindings> {
try {
const payload = parseJsonOrJsonl(await readScannerText(path));
- return normalizeRecords(Array.isArray(payload) ? payload : [payload]);
+ return normalizeRecords(
+ Array.isArray(payload) ? payload : [payload],
+ target,
+ );
} catch (cause) {
throw new CodexSecurityError(
`Could not read GitHub findings as UTF-8 JSON or JSONL: ${errorMessage(cause)}`,
diff --git a/sdk/typescript/src/scanner-import.ts b/sdk/typescript/src/scanner-import.ts
index 9fd7d9fd1..2172dd6ab 100644
--- a/sdk/typescript/src/scanner-import.ts
+++ b/sdk/typescript/src/scanner-import.ts
@@ -176,6 +176,7 @@ export function normalizeRecords<T>(
records: T[],
normalize: (record: T, id: string) => ExternalFinding,
identify: (record: T) => string,
+ target: "local" | "cloud" = "cloud",
): ExternalFindings {
const result: ExternalFindings = {
read: records.length,
@@ -187,9 +188,15 @@ export function normalizeRecords<T>(
for (const [index, value] of records.entries()) {
try {
const id = identify(value);
- if (!id.trim() || id.includes("\0") || Buffer.byteLength(id) > 512)
+ if (
+ !id.trim() ||
+ id.includes("\0") ||
+ (target === "cloud" && Buffer.byteLength(id) > 512)
+ )
throw new Error(
- "Source finding ID must contain 1–512 UTF-8 bytes and no NUL characters.",
+ target === "cloud"
+ ? "Source finding ID must contain 1–512 UTF-8 bytes and no NUL characters."
+ : "Source finding ID must be nonempty and contain no NUL characters.",
);
identified.push({ position: index + 1, value, id });
counts.set(id, (counts.get(id) ?? 0) + 1);
diff --git a/sdk/typescript/src/semgrep-findings.ts b/sdk/typescript/src/semgrep-findings.ts
index 205428a3a..9002d9f76 100644
--- a/sdk/typescript/src/semgrep-findings.ts
+++ b/sdk/typescript/src/semgrep-findings.ts
@@ -1,3 +1,4 @@
+import type { ExternalImportTarget } from "./external-import-contract.js";
import {
cloudRepositoryUrlKey,
validateExternalEvidence,
@@ -180,10 +181,11 @@ function sarifIdentity(
export function normalizeSemgrepFindings(
input: unknown,
options: SemgrepImportOptions,
+ target: ExternalImportTarget = "cloud",
): ExternalFindings {
const document = record(input, "Semgrep report");
if (document["version"] === "2.1.0" && document["runs"] !== undefined)
- return normalizeSemgrepSarif(document, options);
+ return normalizeSemgrepSarif(document, options, target);
const repositoryUrl = sourceRepository(options);
requiredText(document["version"], "Semgrep version");
if (array(document["errors"] ?? [], "Semgrep errors").length)
@@ -221,39 +223,44 @@ export function normalizeSemgrepFindings(
const path = relativePath(rawPath);
return {
source_finding_id: sourceFindingId,
- evidence: validateExternalEvidence({
- title: rule,
- description: messageText(extra["message"]),
- severity: severity(extra["severity"]),
- locations: path ? [{ path, line }] : [],
- details: {
- kind: "sast",
- repository: { url: repositoryUrl },
- scanner_origin: "Semgrep",
- rule: { id: rule },
- weakness_ids: weaknessIds(metadata["cwe"]),
- code: {
- end_line: path ? endLine : null,
- snippet: ungatedText(extra["lines"]),
+ evidence: validateExternalEvidence(
+ {
+ title: rule,
+ description: messageText(extra["message"]),
+ severity: severity(extra["severity"]),
+ locations: path ? [{ path, line }] : [],
+ details: {
+ kind: "sast",
+ repository: { url: repositoryUrl },
+ scanner_origin: "Semgrep",
+ rule: { id: rule },
+ weakness_ids: weaknessIds(metadata["cwe"]),
+ code: {
+ end_line: path ? endLine : null,
+ snippet: ungatedText(extra["lines"]),
+ },
+ source_status:
+ typeof extra["is_ignored"] === "boolean"
+ ? extra["is_ignored"]
+ ? "ignored"
+ : "open"
+ : null,
},
- source_status:
- typeof extra["is_ignored"] === "boolean"
- ? extra["is_ignored"]
- ? "ignored"
- : "open"
- : null,
+ source_data: structuredClone({ report: context, result }),
},
- source_data: structuredClone({ report: context, result }),
- }),
+ target,
+ ),
};
},
jsonIdentity,
+ target,
);
}
export function normalizeSemgrepSarif(
input: unknown,
options: SemgrepImportOptions,
+ target: ExternalImportTarget = "cloud",
): ExternalFindings {
const repositoryUrl = sourceRepository(options);
const document = record(input, "Semgrep SARIF");
@@ -409,58 +416,63 @@ export function normalizeSemgrepSarif(
rawPath === null || absoluteUri ? null : relativePath(rawPath);
return {
source_finding_id: sourceFindingId,
- evidence: validateExternalEvidence({
- title: ruleId,
- description:
- text(message["markdown"]) ?? messageText(message["text"]),
- severity: mappedSeverity,
- locations: path ? [{ path, line }] : [],
- details: {
- kind: "sast",
- repository: { url: repositoryUrl },
- scanner_origin: "Semgrep",
- rule: { id: ruleId },
- weakness_ids: weaknessIds(
- record(rule?.["properties"] ?? {}, "Rule properties")["tags"],
- ),
- code: {
- end_line: path ? endLine : null,
- snippet: ungatedText(
- record(region["snippet"] ?? {}, "Snippet")["text"],
+ evidence: validateExternalEvidence(
+ {
+ title: ruleId,
+ description:
+ text(message["markdown"]) ?? messageText(message["text"]),
+ severity: mappedSeverity,
+ locations: path ? [{ path, line }] : [],
+ details: {
+ kind: "sast",
+ repository: { url: repositoryUrl },
+ scanner_origin: "Semgrep",
+ rule: { id: ruleId },
+ weakness_ids: weaknessIds(
+ record(rule?.["properties"] ?? {}, "Rule properties")["tags"],
),
+ code: {
+ end_line: path ? endLine : null,
+ snippet: ungatedText(
+ record(region["snippet"] ?? {}, "Snippet")["text"],
+ ),
+ },
+ source_status:
+ Array.isArray(result["suppressions"]) &&
+ result["suppressions"].some((value) => {
+ const status = record(value, "Suppression")["status"];
+ return status === undefined || status === "accepted";
+ })
+ ? "suppressed"
+ : null,
},
- source_status:
- Array.isArray(result["suppressions"]) &&
- result["suppressions"].some((value) => {
- const status = record(value, "Suppression")["status"];
- return status === undefined || status === "accepted";
- })
- ? "suppressed"
- : null,
- },
- source_data: structuredClone({
- ...context,
- runContext: sarifRunContextForResult(
- context.runContext,
+ source_data: structuredClone({
+ ...context,
+ runContext: sarifRunContextForResult(
+ context.runContext,
+ result,
+ rule,
+ context.driverContext,
+ context.toolContext,
+ context.documentContext,
+ ),
+ ...(rule ? { rule } : {}),
result,
- rule,
- context.driverContext,
- context.toolContext,
- context.documentContext,
- ),
- ...(rule ? { rule } : {}),
- result,
- }),
- }),
+ }),
+ },
+ target,
+ ),
};
},
({ result, runContext }) => sarifIdentity(result, runContext),
+ target,
);
}
export async function readSemgrepFindings(
path: string,
options: SemgrepImportOptions,
+ target: ExternalImportTarget = "cloud",
): Promise<ExternalFindings> {
- return normalizeSemgrepFindings(await readScannerJson(path), options);
+ return normalizeSemgrepFindings(await readScannerJson(path), options, target);
}
diff --git a/sdk/typescript/src/snyk-findings.ts b/sdk/typescript/src/snyk-findings.ts
index 3799bfe85..f2482c714 100644
--- a/sdk/typescript/src/snyk-findings.ts
+++ b/sdk/typescript/src/snyk-findings.ts
@@ -1,3 +1,4 @@
+import type { ExternalImportTarget } from "./external-import-contract.js";
import { validateExternalEvidence } from "./external-import-contract.js";
import type { ExternalFindings } from "./external-findings.js";
import { isRecord } from "./record.js";
@@ -59,7 +60,10 @@ function pluginIdentity(value: unknown): string {
}
/** Import the official Snyk Codex plugin's documented local SCA bundle. */
-export function normalizeSnykFindingsExport(input: unknown): ExternalFindings {
+export function normalizeSnykFindingsExport(
+ input: unknown,
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
const document = record(input, "Snyk plugin export");
if (
document["format"] !== "snyk-findings-export/v1" ||
@@ -67,7 +71,7 @@ export function normalizeSnykFindingsExport(input: unknown): ExternalFindings {
)
throw new Error("Expected a snyk-findings-export/v1 bundle from Snyk.");
const collection = record(document["collection"], "Snyk collection");
- const target = record(collection["target"], "Snyk target");
+ const sourceTarget = record(collection["target"], "Snyk target");
const { findings: _findings, ...context } = document;
return normalizeRecords(
array(document["findings"], "Snyk findings"),
@@ -94,45 +98,50 @@ export function normalizeSnykFindingsExport(input: unknown): ExternalFindings {
const severity = text(
record(finding["severity"], "Snyk severity")["value"],
)?.toLowerCase();
- const revision = text(target["revision"]);
+ const revision = text(sourceTarget["revision"]);
return {
source_finding_id: sourceFindingId,
- evidence: validateExternalEvidence({
- title: requiredText(finding["title"], "Snyk title"),
- description: text(
- record(finding["description"] ?? {}, "Snyk description")["text"],
- ),
- severity: ["critical", "high", "medium", "low"].includes(
- severity ?? "",
- )
- ? severity
- : "unknown",
- advisory_ids: [
- ...new Set([
- requiredText(rule["id"], "Snyk advisory ID"),
- ...strings(aliases["cve"]),
- ]),
- ],
- packages: [
- {
- name: requiredText(pkg["name"], "Snyk package name"),
- ecosystem: text(pkg["ecosystem"]),
- installed_version: text(pkg["version"]),
- // Plugin v1 manifests are target-relative, without a Git-root offset.
- manifest_path: null,
- fixed_versions: strings(remediation["fixedIn"]),
- },
- ],
- locations: [],
- code_revision:
- target["workingTreeDirty"] === false && revision !== "unknown"
- ? revision
- : null,
- source_data: structuredClone({ ...context, finding }),
- }),
+ evidence: validateExternalEvidence(
+ {
+ title: requiredText(finding["title"], "Snyk title"),
+ description: text(
+ record(finding["description"] ?? {}, "Snyk description")["text"],
+ ),
+ severity: ["critical", "high", "medium", "low"].includes(
+ severity ?? "",
+ )
+ ? severity
+ : "unknown",
+ advisory_ids: [
+ ...new Set([
+ requiredText(rule["id"], "Snyk advisory ID"),
+ ...strings(aliases["cve"]),
+ ]),
+ ],
+ packages: [
+ {
+ name: requiredText(pkg["name"], "Snyk package name"),
+ ecosystem: text(pkg["ecosystem"]),
+ installed_version: text(pkg["version"]),
+ // Plugin v1 manifests are target-relative, without a Git-root offset.
+ manifest_path: null,
+ fixed_versions: strings(remediation["fixedIn"]),
+ },
+ ],
+ locations: [],
+ code_revision:
+ sourceTarget["workingTreeDirty"] === false &&
+ revision !== "unknown"
+ ? revision
+ : null,
+ source_data: structuredClone({ ...context, finding }),
+ },
+ target,
+ ),
};
},
pluginIdentity,
+ target,
);
}
@@ -232,7 +241,10 @@ export function snykRepositoryUrls(
}
/** Snyk Open Source's formatter groups all dependency paths for an advisory in a project. */
-export function normalizeSnykSarif(input: unknown): ExternalFindings {
+export function normalizeSnykSarif(
+ input: unknown,
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
const document = record(input, "Snyk SARIF");
if (document["version"] !== "2.1.0")
throw new Error("Expected Snyk Open Source SARIF 2.1.0.");
@@ -363,46 +375,53 @@ export function normalizeSnykSarif(input: unknown): ExternalFindings {
// Use the project, advisory group, and literal manifest set within the caller's namespace.
return {
source_finding_id: sourceFindingId,
- evidence: validateExternalEvidence({
- title,
- description,
- severity,
- advisory_ids: [
- ...new Set([
- id,
- ...(text(
- record(rule["fullDescription"] ?? {}, "Full description")[
- "text"
- ],
- )?.match(/\bCVE-\d{4}-\d+\b/gu) ?? []),
- ]),
- ],
- packages,
- // Snyk emits target-relative paths without a Git-root offset and may
- // synthesize startLine=1. Keep both only in the original evidence.
- locations: [],
- source_data: structuredClone({
- document: documentContext,
- run: sarifRunContextForResult(
- runContext,
- result,
+ evidence: validateExternalEvidence(
+ {
+ title,
+ description,
+ severity,
+ advisory_ids: [
+ ...new Set([
+ id,
+ ...(text(
+ record(rule["fullDescription"] ?? {}, "Full description")[
+ "text"
+ ],
+ )?.match(/\bCVE-\d{4}-\d+\b/gu) ?? []),
+ ]),
+ ],
+ packages,
+ // Snyk emits target-relative paths without a Git-root offset and may
+ // synthesize startLine=1. Keep both only in the original evidence.
+ locations: [],
+ source_data: structuredClone({
+ document: documentContext,
+ run: sarifRunContextForResult(
+ runContext,
+ result,
+ rule,
+ driverContext,
+ documentContext,
+ ),
+ driver: driverContext,
rule,
- driverContext,
- documentContext,
- ),
- driver: driverContext,
- rule,
- result,
- }),
- }),
+ result,
+ }),
+ },
+ target,
+ ),
};
},
({ result, project }) => snykIdentity(result, project),
+ target,
);
}
/** Import native `snyk test --json` Open Source vulnerability occurrences. */
-export function normalizeSnykJson(input: unknown): ExternalFindings {
+export function normalizeSnykJson(
+ input: unknown,
+ target: ExternalImportTarget = "cloud",
+): ExternalFindings {
const projects = Array.isArray(input) ? input : [input];
const entries = projects.flatMap((value) => {
const project = record(value, "Snyk Open Source project");
@@ -443,39 +462,42 @@ export function normalizeSnykJson(input: unknown): ExternalFindings {
const severity = text(vulnerability["severity"])?.toLowerCase();
return {
source_finding_id: sourceFindingId,
- evidence: validateExternalEvidence({
- title: requiredText(
- vulnerability["title"],
- "Snyk vulnerability title",
- ),
- description: text(vulnerability["description"]),
- severity: ["critical", "high", "medium", "low"].includes(
- severity ?? "",
- )
- ? severity
- : "unknown",
- advisory_ids: [
- ...new Set([
- requiredText(vulnerability["id"], "Snyk advisory ID"),
- ...strings(identifiers["CVE"]),
- ]),
- ],
- packages: [
- {
- name: requiredText(
- vulnerability["name"] ?? vulnerability["packageName"],
- "Snyk package name",
- ),
- ecosystem: manager,
- installed_version: text(vulnerability["version"]),
- // Native test paths are scan-target-relative, without a Git-root offset.
- manifest_path: null,
- fixed_versions: strings(vulnerability["fixedIn"]),
- },
- ],
- locations: [],
- source_data: structuredClone({ project: context, vulnerability }),
- }),
+ evidence: validateExternalEvidence(
+ {
+ title: requiredText(
+ vulnerability["title"],
+ "Snyk vulnerability title",
+ ),
+ description: text(vulnerability["description"]),
+ severity: ["critical", "high", "medium", "low"].includes(
+ severity ?? "",
+ )
+ ? severity
+ : "unknown",
+ advisory_ids: [
+ ...new Set([
+ requiredText(vulnerability["id"], "Snyk advisory ID"),
+ ...strings(identifiers["CVE"]),
+ ]),
+ ],
+ packages: [
+ {
+ name: requiredText(
+ vulnerability["name"] ?? vulnerability["packageName"],
+ "Snyk package name",
+ ),
+ ecosystem: manager,
+ installed_version: text(vulnerability["version"]),
+ // Native test paths are scan-target-relative, without a Git-root offset.
+ manifest_path: null,
+ fixed_versions: strings(vulnerability["fixedIn"]),
+ },
+ ],
+ locations: [],
+ source_data: structuredClone({ project: context, vulnerability }),
+ },
+ target,
+ ),
};
},
({ value, manager, manifest }) => {
@@ -494,17 +516,20 @@ export function normalizeSnykJson(input: unknown): ExternalFindings {
),
]);
},
+ target,
);
}
export async function readSnykFindings(
path: string,
+ target: ExternalImportTarget = "cloud",
): Promise<ExternalFindings> {
const input = await readScannerJson(path);
- if (Array.isArray(input)) return normalizeSnykJson(input);
+ if (Array.isArray(input)) return normalizeSnykJson(input, target);
const document = record(input, "Snyk findings");
if (document["format"] === "snyk-findings-export/v1")
- return normalizeSnykFindingsExport(document);
- if (document["version"] === "2.1.0") return normalizeSnykSarif(document);
- return normalizeSnykJson(document);
+ return normalizeSnykFindingsExport(document, target);
+ if (document["version"] === "2.1.0")
+ return normalizeSnykSarif(document, target);
+ return normalizeSnykJson(document, target);
}
diff --git a/sdk/typescript/src/wiz-csv.ts b/sdk/typescript/src/wiz-csv.ts
index 5dc1dd7f2..04b521359 100644
--- a/sdk/typescript/src/wiz-csv.ts
+++ b/sdk/typescript/src/wiz-csv.ts
@@ -1,3 +1,4 @@
+import type { ExternalImportTarget } from "./external-import-contract.js";
import Papa from "papaparse";
import { validateExternalEvidence } from "./external-import-contract.js";
import type { ExternalFindingEvidence } from "./external-import-models.js";
@@ -87,6 +88,7 @@ export function wizCsvRepositoryUrl(
export function wizCsvFinding(
row: Record<string, unknown>,
sourceFindingId: string,
+ target: ExternalImportTarget = "cloud",
): VendorFinding {
repositoryUrl(row);
const name = text(row["Name"]);
@@ -106,31 +108,34 @@ export function wizCsvFinding(
.toLowerCase();
return {
source_finding_id: sourceFindingId,
- evidence: validateExternalEvidence({
- title: [packageName, text(row["Version"]), name]
- .filter(Boolean)
- .join(" "),
- description: text(row["Description"]),
- severity,
- url: text(row["WizURL"]),
- advisory_ids: [name],
- packages: [
- {
- name: packageName,
- ecosystem: null,
- installed_version: text(row["Version"]),
- manifest_path: path,
- fixed_versions: fixedVersion ? [fixedVersion] : [],
- },
- ],
- locations: path ? [{ path }] : [],
- // A tree URL does not distinguish a slash-containing ref from a directory.
- branch: null,
- code_revision: null,
- source_scan_id: null,
- source_updated_at: null,
- image_digests: [],
- source_data: { format: profile, row },
- }),
+ evidence: validateExternalEvidence(
+ {
+ title: [packageName, text(row["Version"]), name]
+ .filter(Boolean)
+ .join(" "),
+ description: text(row["Description"]),
+ severity,
+ url: text(row["WizURL"]),
+ advisory_ids: [name],
+ packages: [
+ {
+ name: packageName,
+ ecosystem: null,
+ installed_version: text(row["Version"]),
+ manifest_path: path,
+ fixed_versions: fixedVersion ? [fixedVersion] : [],
+ },
+ ],
+ locations: path ? [{ path }] : [],
+ // A tree URL does not distinguish a slash-containing ref from a directory.
+ branch: null,
+ code_revision: null,
+ source_scan_id: null,
+ source_updated_at: null,
+ image_digests: [],
+ source_data: { format: profile, row },
+ },
+ target,
+ ),
};
}
diff --git a/sdk/typescript/src/wiz-findings.ts b/sdk/typescript/src/wiz-findings.ts
index 126dafc38..f14d08b7b 100644
--- a/sdk/typescript/src/wiz-findings.ts
+++ b/sdk/typescript/src/wiz-findings.ts
@@ -2,6 +2,7 @@ import { CodexSecurityError } from "./errors.js";
import {
repositoryUrlKey,
validateExternalEvidence,
+ type ExternalImportTarget,
} from "./external-import-contract.js";
import { parseJsonOrJsonl, readScannerText } from "./scanner-import.js";
import { readWizCsv, wizCsvFinding } from "./wiz-csv.js";
@@ -26,22 +27,31 @@ function text(value: unknown): string | null {
return typeof value === "string" && value.trim() ? value : null;
}
-function sourceFindingId(value: unknown): string {
+function sourceFindingId(value: unknown, target: ExternalImportTarget): string {
const id = text(value);
- if (!id || id.includes("\0") || Buffer.byteLength(id) > 512)
+ if (
+ !id ||
+ id.includes("\0") ||
+ (target === "cloud" && Buffer.byteLength(id) > 512)
+ )
throw new Error(
- "Source finding id must contain 1–512 UTF-8 bytes and no NUL characters.",
+ target === "cloud"
+ ? "Source finding id must contain 1–512 UTF-8 bytes and no NUL characters."
+ : "Source finding id must be nonempty and contain no NUL characters.",
);
return id;
}
/** Keep a Wiz vulnerability occurrence intact; advisory names are not identities. */
-function wizFinding(record: Record<string, unknown>): VendorFinding {
+function wizFinding(
+ record: Record<string, unknown>,
+ target: ExternalImportTarget,
+): VendorFinding {
if (record["detectionMethod"] === "EXTERNAL_NETWORK_SCAN")
throw new Error(
"Wiz external network findings are not supported by the package vulnerability mapping.",
);
- const id = sourceFindingId(record["id"]);
+ const id = sourceFindingId(record["id"], target);
const name = text(record["name"]);
const packageName = text(record["detailedName"]);
const version = text(record["version"]);
@@ -106,7 +116,7 @@ function wizFinding(record: Record<string, unknown>): VendorFinding {
};
return {
source_finding_id: id,
- evidence: validateExternalEvidence(evidence),
+ evidence: validateExternalEvidence(evidence, target),
};
}
@@ -223,8 +233,9 @@ function repositoryFinding(
record: Record<string, unknown>,
repositories: FindingInput["repositories"],
legacy = false,
+ target: ExternalImportTarget = "cloud",
): VendorFinding {
- const id = sourceFindingId(record["id"]);
+ const id = sourceFindingId(record["id"], target);
const resource = object(record["resource"]);
if (kind === "secret" && resource?.["type"] !== "REPOSITORY_BRANCH")
throw new Error(
@@ -299,25 +310,28 @@ function repositoryFinding(
return {
// Existing package occurrence IDs remain unchanged. New families cannot
// collide with one another when the same tenant source key is used.
- source_finding_id: sourceFindingId(`${kind}:${id}`),
- evidence: validateExternalEvidence({
- title: text(record["name"]) ?? text(rule?.["name"]),
- severity: text(record["severity"])?.toLowerCase(),
- description: text(record["description"]) ?? text(rule?.["description"]),
- url: text(record["wizUrl"]) ?? text(record["portalUrl"]),
- locations: path ? [{ path, line: line ?? null }] : [],
- branch: sourceBranch(branch, repository, legacy),
- code_revision: null,
- source_scan_id: null,
- source_updated_at:
- kind === "secret"
- ? updatedAt(record["lastUpdatedAt"], "lastUpdatedAt")
- : kind === "iac"
- ? updatedAt(record["updatedAt"], "updatedAt")
- : null,
- source_data: record,
- details,
- }),
+ source_finding_id: sourceFindingId(`${kind}:${id}`, target),
+ evidence: validateExternalEvidence(
+ {
+ title: text(record["name"]) ?? text(rule?.["name"]),
+ severity: text(record["severity"])?.toLowerCase(),
+ description: text(record["description"]) ?? text(rule?.["description"]),
+ url: text(record["wizUrl"]) ?? text(record["portalUrl"]),
+ locations: path ? [{ path, line: line ?? null }] : [],
+ branch: sourceBranch(branch, repository, legacy),
+ code_revision: null,
+ source_scan_id: null,
+ source_updated_at:
+ kind === "secret"
+ ? updatedAt(record["lastUpdatedAt"], "lastUpdatedAt")
+ : kind === "iac"
+ ? updatedAt(record["updatedAt"], "updatedAt")
+ : null,
+ source_data: record,
+ details,
+ },
+ target,
+ ),
};
}
@@ -443,12 +457,16 @@ function records(payload: unknown): FindingInput {
export async function readVendorFindings(
path: string,
+ target: ExternalImportTarget = "cloud",
): Promise<VendorFindings> {
- return normalizeFindings(await readFindingInput(path));
+ return normalizeFindings(await readFindingInput(path), target);
}
/** @internal Preserve older inventory projections only for saved publication replay. */
-export async function readVendorFindingsForPublication(path: string): Promise<{
+export async function readVendorFindingsForPublication(
+ path: string,
+ target: ExternalImportTarget = "cloud",
+): Promise<{
current: VendorFindings;
legacy: VendorFindings;
currentIdentity: unknown[];
@@ -457,9 +475,10 @@ export async function readVendorFindingsForPublication(path: string): Promise<{
}> {
const input = await readFindingInput(path);
const normalized = new WeakSet<VendorFinding>();
- const current = normalizeFindings(input, normalized);
+ const current = normalizeFindings(input, target, normalized);
const legacy = normalizeFindings(
{ ...input, repositories: input.legacyRepositories ?? input.repositories },
+ target,
normalized,
true,
);
@@ -530,6 +549,7 @@ async function readFindingInput(path: string): Promise<FindingInput> {
function normalizeFindings(
input: FindingInput,
+ target: ExternalImportTarget,
normalized?: WeakSet<VendorFinding>,
legacy = false,
): VendorFindings {
@@ -545,7 +565,11 @@ function normalizeFindings(
if (!record) throw new Error("Finding must be an object.");
let finding: VendorFinding;
if (item.kind === "sca_csv") {
- finding = wizCsvFinding(record, sourceFindingId(record["ID"]));
+ finding = wizCsvFinding(
+ record,
+ sourceFindingId(record["ID"], target),
+ target,
+ );
} else if ("source_finding_id" in record) {
if (
Object.keys(record).some(
@@ -557,8 +581,11 @@ function normalizeFindings(
);
}
finding = {
- source_finding_id: sourceFindingId(record["source_finding_id"]),
- evidence: validateExternalEvidence(record["evidence"]),
+ source_finding_id: sourceFindingId(
+ record["source_finding_id"],
+ target,
+ ),
+ evidence: validateExternalEvidence(record["evidence"], target),
};
} else if (item.kind === "cloud_configuration") {
throw new Error(
@@ -570,6 +597,7 @@ function normalizeFindings(
record,
input.repositories,
legacy,
+ target,
);
} else {
if (
@@ -581,7 +609,7 @@ function normalizeFindings(
throw new Error(
"Raw SAST, secret, and IaC records require their named sastFindings, secretInstances, or iacFindings collection. Bare arrays do not identify the finding family; use normalized JSONL for an explicit mapping.",
);
- finding = wizFinding(record);
+ finding = wizFinding(record, target);
}
if (identities.has(finding.source_finding_id)) {
throw new CodexSecurityError(
diff --git a/sdk/typescript/tests-ts/external-findings-import.test.ts b/sdk/typescript/tests-ts/external-findings-import.test.ts
index 4218cfa88..a378a3832 100644
--- a/sdk/typescript/tests-ts/external-findings-import.test.ts
+++ b/sdk/typescript/tests-ts/external-findings-import.test.ts
@@ -89,7 +89,7 @@ test("Wiz JSON imports retain parsed evidence through SQLite readback and update
sourceKey: "example-project/main",
};
const dependencies = { environment: fixture.environment };
- const parsed = await readVendorFindings(file);
+ const parsed = await readVendorFindings(file, "local");
const prepared = await prepareLocalExternalImport(
file,
options,
@@ -195,7 +195,7 @@ test.each([
file,
format === "gzip JSON" ? gzipSync(contents) : contents,
);
- const parsed = await readVendorFindings(file);
+ const parsed = await readVendorFindings(file, "local");
if (format.includes("normalized JSONL")) {
const normalized = parsed.findings
.map((finding) => JSON.stringify(finding))
@@ -263,7 +263,7 @@ test.each(["raw JSON", "normalized JSONL"])(
async function writeSelection(url: string) {
record.vulnerableAsset.cloudProviderURL = url;
await writeFile(file, JSON.stringify([record]));
- const parsed = await readVendorFindings(file);
+ const parsed = await readVendorFindings(file, "local");
if (format === "normalized JSONL")
await writeFile(
file,
@@ -380,7 +380,7 @@ for (const kind of [
sourceKey: "named-project/main",
};
const dependencies = { environment: fixture.environment };
- const parsed = await readVendorFindings(file);
+ const parsed = await readVendorFindings(file, "local");
expect(parsed.findings).toHaveLength(1);
expect(parsed.excluded).toHaveLength(1);
execFileSync(
diff --git a/sdk/typescript/tests-ts/external-findings-local-limits.test.ts b/sdk/typescript/tests-ts/external-findings-local-limits.test.ts
new file mode 100644
index 000000000..c90ffea73
--- /dev/null
+++ b/sdk/typescript/tests-ts/external-findings-local-limits.test.ts
@@ -0,0 +1,430 @@
+import { expect, mock, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { prepareLocalExternalImport } from "../src/external-findings-import.js";
+import { listLocalExternalFindings } from "../src/external-findings-local.js";
+import { prepareNormalizedExternalPublication } from "../src/external-findings-publish.js";
+import { readExternalFindings } from "../src/external-findings-read.js";
+import { validateExternalEvidence } from "../src/external-import-contract.js";
+import type {
+ ExternalFindingEvidence,
+ Provider,
+} from "../src/external-import-models.js";
+import { localFindingsFixture } from "./external-findings-local-helpers.js";
+import { endorFinding, endorSarif } from "./support/endor-import-fixtures.js";
+import {
+ importedAdvisory,
+ importedAlert,
+} from "./support/github-import-fixtures.js";
+import {
+ semgrepJson,
+ semgrepSarif,
+} from "./support/semgrep-import-fixtures.js";
+import {
+ snykJson,
+ snykPluginExport,
+ snykSarif,
+} from "./support/snyk-import-fixtures.js";
+
+const repositoryUrl = "https://github.com/example/project";
+const retainedEvidence = `begin-${"x".repeat(300 * 1024)}-end`;
+
+function jsonWithEvidence(input: unknown, record: object): string {
+ Object.assign(record, { retainedEvidence });
+ return JSON.stringify(input);
+}
+
+function normalized() {
+ return {
+ source_finding_id: "synthetic-finding",
+ evidence: { title: "Synthetic finding", severity: "high" as const },
+ };
+}
+
+const formats: [string, Provider, () => string][] = [
+ [
+ "Semgrep JSON",
+ "semgrep",
+ () => {
+ const input = semgrepJson();
+ return jsonWithEvidence(input, input.results[0]!.extra.metadata);
+ },
+ ],
+ [
+ "Semgrep SARIF",
+ "semgrep",
+ () => {
+ const input = semgrepSarif();
+ return jsonWithEvidence(input, input.runs[0]!.results[0]!);
+ },
+ ],
+ [
+ "Snyk JSON",
+ "snyk",
+ () => {
+ const input = snykJson();
+ return jsonWithEvidence(input, input.vulnerabilities[0]!);
+ },
+ ],
+ [
+ "Snyk SARIF",
+ "snyk",
+ () => {
+ const input = snykSarif();
+ return jsonWithEvidence(input, input.runs[0]!.results[0]!);
+ },
+ ],
+ [
+ "Snyk plugin export",
+ "snyk",
+ () => {
+ const input = snykPluginExport();
+ return jsonWithEvidence(input, input.findings[0]!);
+ },
+ ],
+ [
+ "Endor JSON",
+ "endor",
+ () => {
+ const input = endorFinding();
+ return jsonWithEvidence(input, input);
+ },
+ ],
+ [
+ "Endor SARIF",
+ "endor",
+ () => {
+ const input = endorSarif();
+ return jsonWithEvidence(input, input.runs[0]!.results[0]!);
+ },
+ ],
+ [
+ "GitHub code scanning",
+ "github",
+ () => {
+ const input = importedAlert();
+ return jsonWithEvidence(input, input.alert);
+ },
+ ],
+ ...(["repository", "global"] as const).map(
+ (selection): [string, Provider, () => string] => [
+ `GitHub ${selection} advisory`,
+ "github",
+ () => {
+ const input = importedAdvisory(selection);
+ return jsonWithEvidence(input, input.advisory);
+ },
+ ],
+ ),
+ [
+ "Wiz package JSON",
+ "wiz",
+ () => {
+ const input = {
+ id: "synthetic-finding",
+ name: "CVE-2099-0001",
+ detailedName: "example-package",
+ severity: "HIGH",
+ vulnerableAsset: { id: "synthetic-asset" },
+ };
+ return jsonWithEvidence(input, input);
+ },
+ ],
+ [
+ "Wiz SAST JSON",
+ "wiz",
+ () => {
+ const finding = {
+ id: "synthetic-finding",
+ name: "Synthetic finding",
+ severity: "HIGH",
+ repository: {
+ id: "synthetic-repository",
+ name: "example/project",
+ url: repositoryUrl,
+ },
+ };
+ return jsonWithEvidence({ sastFindings: { nodes: [finding] } }, finding);
+ },
+ ],
+ [
+ "Wiz CSV",
+ "wiz",
+ () => {
+ const row = {
+ ID: "synthetic-finding",
+ Name: "CVE-2099-0001",
+ DetailedName: "example-package",
+ AssetID: "synthetic-asset",
+ WizURL: "https://vendor.example.test/findings/synthetic-finding",
+ CloudPlatform: "GitHub",
+ CloudProviderURL: `${repositoryUrl}/tree/main`,
+ Severity: "HIGH",
+ retainedEvidence,
+ };
+ return [Object.keys(row), Object.values(row)]
+ .map((cells) =>
+ cells.map((value) => `"${value.replaceAll('"', '""')}"`).join(","),
+ )
+ .join("\r\n");
+ },
+ ],
+ [
+ "normalized JSONL",
+ "wiz",
+ () =>
+ JSON.stringify({
+ ...normalized(),
+ evidence: {
+ ...normalized().evidence,
+ source_data: { retainedEvidence },
+ },
+ }),
+ ],
+];
+
+test.each(formats)(
+ "%s persists large local evidence while Cloud retains its size limit",
+ async (_name, provider, contents) => {
+ const fixture = await localFindingsFixture({ remote: repositoryUrl });
+ try {
+ const file = join(fixture.root, "scanner-report");
+ await writeFile(file, contents());
+ const options = {
+ provider,
+ repository: fixture.repository,
+ sourceKey: "synthetic-project",
+ sourceRepositoryUrl: repositoryUrl,
+ };
+ const dependencies = { environment: fixture.environment };
+ const cloud = await readExternalFindings(file, options);
+ expect(cloud.findings.findings).toEqual([]);
+ expect(cloud.findings.excluded).toHaveLength(1);
+ expect(cloud.findings.excluded[0]!.reason).toContain("256 KiB");
+
+ const prepared = await prepareLocalExternalImport(
+ file,
+ options,
+ dependencies,
+ );
+ expect(prepared.preview.excluded).toEqual([]);
+ expect(prepared.preview.findings).toHaveLength(1);
+ expect(
+ JSON.stringify(prepared.preview.findings[0]!.evidence.source_data),
+ ).toContain(retainedEvidence);
+ expect((await prepared.import()).counts).toEqual({
+ created: 1,
+ updated: 0,
+ unchanged: 0,
+ });
+ const stored = await listLocalExternalFindings(options, dependencies);
+ expect(stored).toHaveLength(1);
+ expect(stored[0]!.evidence).toEqual(
+ prepared.preview.findings[0]!.evidence,
+ );
+ } finally {
+ await fixture.dispose();
+ }
+ },
+);
+
+let nested: Record<string, unknown> = { leaf: "retained" };
+for (let index = 0; index < 24; index++) nested = { child: nested };
+
+const evidenceLimits: [string, Partial<ExternalFindingEvidence>][] = [
+ ["UTF-8 field bytes", { title: "é".repeat(257) }],
+ ["description length", { description: "x".repeat(65537) }],
+ [
+ "nested detail length",
+ {
+ details: {
+ kind: "sast",
+ repository: { url: repositoryUrl },
+ code: { snippet: "x".repeat(65537) },
+ },
+ },
+ ],
+ [
+ "location count",
+ {
+ locations: Array.from({ length: 101 }, (_, index) => ({
+ path: `src/file-${index}.ts`,
+ })),
+ },
+ ],
+ ["JSON depth", { source_data: nested }],
+];
+
+test.each(evidenceLimits)(
+ "local imports retain %s above Cloud's contract",
+ async (_name, fields) => {
+ const fixture = await localFindingsFixture({ remote: repositoryUrl });
+ try {
+ const input = {
+ ...normalized(),
+ evidence: { ...normalized().evidence, ...fields },
+ };
+ const file = join(fixture.root, "normalized.jsonl");
+ await writeFile(file, JSON.stringify(input));
+ const options = {
+ provider: "wiz" as const,
+ repository: fixture.repository,
+ sourceKey: "synthetic-project",
+ };
+ const dependencies = { environment: fixture.environment };
+ const prepared = await prepareLocalExternalImport(
+ file,
+ options,
+ dependencies,
+ );
+ expect(prepared.preview.excluded).toEqual([]);
+ const imported = await prepared.import();
+ expect(imported.counts.created).toBe(1);
+ const stored = await listLocalExternalFindings(options, dependencies);
+ expect(stored[0]!.evidence).toEqual(
+ prepared.preview.findings[0]!.evidence,
+ );
+ expect(stored[0]!.evidence).toMatchObject(fields);
+ expect(() =>
+ validateExternalEvidence(structuredClone(input.evidence)),
+ ).toThrow();
+ const cloud = await readExternalFindings(file, options);
+ expect(cloud.findings.findings).toEqual([]);
+ expect(cloud.findings.excluded).toHaveLength(1);
+ const credentials = mock(async () => {
+ throw new Error("Unexpected credential access");
+ });
+ await expect(
+ prepareNormalizedExternalPublication(
+ { read: 1, findings: [input], excluded: [] },
+ options,
+ { credentials },
+ ),
+ ).rejects.toThrow();
+ expect(credentials).not.toHaveBeenCalled();
+ } finally {
+ await fixture.dispose();
+ }
+ },
+);
+
+test.each(["wiz", "endor"] as const)(
+ "%s local imports preserve source identities longer than Cloud accepts",
+ async (provider) => {
+ const fixture = await localFindingsFixture();
+ try {
+ const identity = "x".repeat(513);
+ const input =
+ provider === "wiz"
+ ? { ...normalized(), source_finding_id: identity }
+ : { ...endorFinding(), uuid: identity };
+ const file = join(fixture.root, "normalized.jsonl");
+ await writeFile(file, JSON.stringify(input));
+ const options = {
+ provider,
+ repository: fixture.repository,
+ sourceKey: "synthetic-project",
+ };
+ const dependencies = { environment: fixture.environment };
+ const prepared = await prepareLocalExternalImport(
+ file,
+ options,
+ dependencies,
+ );
+ expect(prepared.preview.excluded).toEqual([]);
+ expect((await prepared.import()).counts.created).toBe(1);
+ const stored = await listLocalExternalFindings(options, dependencies);
+ expect(stored[0]!.sourceFindingId).toBe(identity);
+ const cloud = await readExternalFindings(file, options);
+ expect(cloud.findings.excluded[0]!.reason).toContain("512");
+ const credentials = mock(async () => {
+ throw new Error("Unexpected credential access");
+ });
+ await expect(
+ prepareNormalizedExternalPublication(
+ { read: 1, findings: prepared.preview.findings, excluded: [] },
+ options,
+ { credentials },
+ ),
+ ).rejects.toThrow("512");
+ expect(credentials).not.toHaveBeenCalled();
+ } finally {
+ await fixture.dispose();
+ }
+ },
+);
+
+test("local evidence validation keeps structure, paths, links and numeric integrity", () => {
+ const circular: Record<string, unknown> = {};
+ circular["self"] = circular;
+ expect(() =>
+ validateExternalEvidence(
+ { ...normalized().evidence, source_data: circular },
+ "local",
+ ),
+ ).toThrow();
+ const invalid: [unknown, string][] = [
+ [{ ...normalized().evidence, severity: "not-a-severity" }, "severity"],
+ [
+ { ...normalized().evidence, locations: [{ path: "../outside.ts" }] },
+ "repository-relative",
+ ],
+ [
+ { ...normalized().evidence, url: "https://[email protected]/finding" },
+ "without credentials",
+ ],
+ [{ ...normalized().evidence, source_data: { value: Infinity } }, "finite"],
+ [
+ {
+ ...normalized().evidence,
+ source_data: { value: Number.MAX_SAFE_INTEGER + 1 },
+ },
+ "safe integer",
+ ],
+ ];
+ for (const [evidence, message] of invalid)
+ expect(() => validateExternalEvidence(evidence, "local")).toThrow(message);
+});
+
+test("large local records still require distinct identities and matching repository provenance", async () => {
+ const fixture = await localFindingsFixture({ remote: repositoryUrl });
+ try {
+ const input = {
+ ...normalized(),
+ evidence: { ...normalized().evidence, source_data: { retainedEvidence } },
+ };
+ const file = join(fixture.root, "normalized.jsonl");
+ const options = {
+ provider: "wiz" as const,
+ repository: fixture.repository,
+ sourceKey: "synthetic-project",
+ };
+ const dependencies = { environment: fixture.environment };
+ await writeFile(
+ file,
+ [input, input].map((finding) => JSON.stringify(finding)).join("\n"),
+ );
+ await expect(
+ prepareLocalExternalImport(file, options, dependencies),
+ ).rejects.toThrow("Duplicate source");
+ await writeFile(
+ file,
+ JSON.stringify({
+ ...input,
+ evidence: {
+ ...input.evidence,
+ details: {
+ kind: "sast",
+ repository: { url: "https://github.com/example/other" },
+ },
+ },
+ }),
+ );
+ await expect(
+ prepareLocalExternalImport(file, options, dependencies),
+ ).rejects.toThrow("does not match");
+ expect(await listLocalExternalFindings(options, dependencies)).toEqual([]);
+ } finally {
+ await fixture.dispose();
+ }
+});