OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
import { CodexSecurityError } from "./errors.js";
import type { Provider } from "./external-import-models.js";
import {
type ExternalImportTarget,
validateEnrichedExternalEvidence,
} from "./external-import-contract.js";
import type { ExternalFinding, ExternalFindings } from "./external-findings.js";
import { canonicalJson, isRecord } from "./record.js";
import {
array,
normalizeRecords,
scannerJsonReader,
record,
reportableScannerSeverity,
requiredText,
stableId,
text,
} from "./scanner-import.js";
import {
declaredScannerRepositoryUrl,
repositoryScopeValidator,
} 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; scope?: 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, scope: projectVersion };
}
export const blackDuckReportRepositories = repositoryScopeValidator(
{ provider: "blackduck", label: "Black Duck", scope: "project version" },
retainedRepository,
);
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],
};
}
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 vulnerability = row["vulnerabilityWithRemediation"];
return {
row,
matched,
scope,
// Shape errors are row exclusions; project-scope errors abort the report.
get vulnerability() {
record(value, "Black Duck BOM component");
return record(vulnerability, "Black Duck 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 === "github" && parts.length === 2)
return parts.join("/").toLowerCase();
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 fallback = origin ? [origin] : [];
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 { packages: fallback };
const pkg = {
name,
ecosystem,
installed_version: purl[3]
? decodeURIComponent(purl[3])
: text(row["componentVersionName"]),
};
// Retain the origin coordinate if the qualified owner/repository PURL exceeds a Cloud limit.
return ecosystem === "github" && name.includes("/")
? { packages: fallback, enrichment: { packages: [pkg] } }
: { packages: [pkg] };
}
} catch {
// A malformed escape does not invalidate the native origin coordinate.
}
}
return { packages: fallback };
}
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 related = text(vulnerability["relatedVulnerability"]);
const { packages, enrichment } = blackDuckPackages(row);
return validateEnrichedExternalEvidence(
{
title: `${advisory} in ${name}`,
description: text(vulnerability["description"]),
severity: reportableScannerSeverity(vulnerability["severity"]),
advisory_ids:
related && related !== advisory ? [advisory, related] : [advisory],
packages,
source_data: {
format,
sourceRepositoryUrl: repository,
projectVersionUrl: projectVersion,
row: structuredClone(row),
},
},
target,
enrichment,
);
},
(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 const readBlackDuckFindings = scannerJsonReader(
normalizeBlackDuckFindings,
);