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 { z } from "zod";
import { GHSA_ID, githubRepositoryParts } from "./github-identifiers.js";
import { CodexSecurityError } from "./errors.js";
import {
type ExternalImportTarget,
validateExternalEvidence,
} from "./external-import-contract.js";
import type { ExternalFinding, ExternalFindings } from "./external-findings.js";
import { isGitHubCloudHost } from "./git-remote.js";
import { isRecord } from "./record.js";
import { REPORTABLE_SEVERITIES } from "./scan-settings.js";
import {
appendFinding,
record,
relativePath,
requiredText,
text,
} from "./scanner-import.js";
export function isGitHubDependabotAlert(
value: unknown,
): value is Record<string, unknown> {
return (
isRecord(value) &&
("security_vulnerability" in value ||
("dependency" in value && "security_advisory" in value) ||
[value["url"], value["html_url"]].some(
(url) =>
typeof url === "string" &&
/^\/(?:[^/]+\/[^/]+\/security\/dependabot|(?:api\/v3\/)?repos\/[^/]+\/[^/]+\/dependabot\/alerts)\/\d+$/iu.test(
URL.parse(url)?.pathname ?? "",
),
))
);
}
function webIdentity(url: string) {
const match =
/^(https?):\/\/([^/?#@\\\s]+)\/([^/?#]+\/[^/?#]+)\/security\/dependabot\/([1-9]\d*)$/iu.exec(
url,
);
if (!match || !githubRepositoryParts(match[3]!)) return null;
const parsed = URL.parse(url);
if (
!parsed ||
(parsed.protocol === "http:" && isGitHubCloudHost(parsed.hostname))
)
return null;
const host = match[2]!.toLowerCase();
const repository = match[3]!.toLowerCase();
const origin = `${parsed.protocol}//${host}`;
const number = match[4]!;
const apiBase = isGitHubCloudHost(parsed.hostname)
? `https://api.${host}`
: `${origin}/api/v3`;
const repositoryUrl = `${origin}/${repository}`;
const apiRepo = `${apiBase}/repos/${repository}`;
return {
repository,
repositoryUrl,
apiRepo,
number,
sourceId: `${host}/${repository}/dependabot/${number}`,
htmlUrl: `${repositoryUrl}/security/dependabot/${number}`,
apiUrl: `${apiRepo}/dependabot/alerts/${number}`,
};
}
// Normalized SDK evidence may link to either REST or the web UI.
function alertUrlIdentity(url: unknown) {
if (typeof url !== "string") return null;
const web = webIdentity(url);
if (web) return web;
const api =
/^(https?:\/\/)([^/?#@\\\s]+)\/(api\/v3\/)?repos\/([^/]+\/[^/]+)\/dependabot\/alerts\/([1-9]\d*)$/iu.exec(
url,
);
if (!api) return null;
const host = api[3] ? api[2] : api[2]!.replace(/^api\./iu, "");
const parsed = webIdentity(
`${api[1]}${host}/${api[4]}/security/dependabot/${api[5]}`,
);
return parsed?.apiUrl === url.toLowerCase() ? parsed : null;
}
function checkSourceFamily(alert: Record<string, unknown>) {
if (
alert["source"] === "github-code-scanning" ||
alert["source"] === "github-security-advisory"
)
throw new Error(
"Dependabot alert conflicts with its GitHub source family.",
);
}
function checkNativeClaims(
alert: Record<string, unknown>,
occurrence: NonNullable<ReturnType<typeof webIdentity>>,
) {
if ("number" in alert && alert["number"] !== Number(occurrence.number))
throw new Error(
"Dependabot alert number must match the repository alert URL.",
);
if (
("url" in alert &&
text(alert["url"])?.toLowerCase() !== occurrence.apiUrl) ||
("html_url" in alert &&
text(alert["html_url"])?.toLowerCase() !== occurrence.htmlUrl)
)
throw new Error(
"Dependabot API url and html_url must identify the same host, repository and alert number.",
);
if ("repository" in alert) {
const declared = record(alert["repository"], "Dependabot repository");
if (
text(declared["full_name"])?.toLowerCase() !== occurrence.repository ||
("html_url" in declared &&
text(declared["html_url"])?.toLowerCase() !==
occurrence.repositoryUrl) ||
("url" in declared &&
text(declared["url"])?.toLowerCase() !== occurrence.apiRepo)
)
throw new Error(
"Dependabot repository metadata conflicts with its alert URLs.",
);
}
}
function identity(alert: Record<string, unknown>) {
checkSourceFamily(alert);
const number = alert["number"];
if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 1)
throw new Error("Dependabot alert number must be a positive safe integer.");
const url = requiredText(alert["html_url"], "Dependabot html_url");
const parsed = webIdentity(url);
if (!parsed || parsed.number !== String(number))
throw new Error(
"Dependabot html_url must identify the repository and alert number.",
);
requiredText(alert["url"], "Dependabot API url");
checkNativeClaims(alert, parsed);
return {
repositoryUrl: parsed.repositoryUrl,
sourceId: parsed.sourceId,
url,
};
}
export function dependabotRepository({
source_finding_id: id,
evidence: { source_data: sourceData, url },
}: ExternalFinding): string | undefined {
const native = isGitHubDependabotAlert(sourceData) ? sourceData : null;
const raw =
native &&
(alertUrlIdentity(native["html_url"]) ?? alertUrlIdentity(native["url"]));
const projected = alertUrlIdentity(url);
const occurrence = raw ?? projected;
const structuredId =
/^[^/]+\/[^/]+\/[^/]+\/(?:dependabot|code-scanning|security-advisory)\//u.test(
id,
);
if (!occurrence) {
if (/^[^/]+\/[^/]+\/[^/]+\/dependabot\/[1-9]\d*$/u.test(id))
throw new CodexSecurityError(
"The normalized Dependabot occurrence needs the original alert or its repository alert URL.",
);
return;
}
if (isRecord(sourceData)) checkSourceFamily(sourceData);
if (native) checkNativeClaims(native, occurrence);
// A caller may have stored this occurrence under an opaque ID before native imports existed.
if ((structuredId || id === "") && id !== occurrence.sourceId)
throw new CodexSecurityError(
"The normalized source finding ID does not match the original Dependabot alert.",
);
if (raw && projected && raw.htmlUrl !== projected.htmlUrl)
throw new CodexSecurityError(
"The normalized alert URL does not match the original Dependabot alert.",
);
return occurrence.repositoryUrl;
}
function selectedAlerts(input: unknown) {
const selection = Array.isArray(input) ? input : [input];
const hasPages = selection.some(Array.isArray);
if (hasPages && !selection.every(Array.isArray))
throw new Error(
"Dependabot input must not mix alert records and page arrays.",
);
const rows: unknown[] = hasPages ? selection.flat() : selection;
if (!rows.every(isGitHubDependabotAlert))
throw new Error(
"Expected complete native Dependabot repository alerts, not mixed families, page shapes or API envelopes.",
);
return rows;
}
// Parse only the matched vulnerability projection. Keep the complete upstream alert as evidence.
const nonblank = z.string().regex(/\S/u);
const matchedVulnerability = z.object({
package: z.object({ name: nonblank, ecosystem: nonblank }),
vulnerable_version_range: nonblank,
first_patched_version: z.object({ identifier: nonblank }).nullable(),
severity: z.enum(REPORTABLE_SEVERITIES),
});
// Python distribution identity ignores case and treats runs of -, _ and . alike.
function packageNameKey(ecosystem: string, name: unknown): unknown {
if (
ecosystem === "pip" &&
typeof name === "string" &&
/^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u.test(name)
)
return name.toLowerCase().replace(/[-_.]+/gu, "-");
return name;
}
function evidence(alert: Record<string, unknown>, url: string) {
const dependency = record(alert["dependency"], "Dependabot dependency");
const advisory = record(
alert["security_advisory"],
"Dependabot security_advisory",
);
const {
package: { name, ecosystem },
vulnerable_version_range: range,
first_patched_version: patch,
severity,
} = matchedVulnerability.parse(alert["security_vulnerability"]);
const nameKey = packageNameKey(ecosystem, name);
const matchesPackage = (pkg: Record<string, unknown>) =>
pkg["ecosystem"] === ecosystem &&
packageNameKey(ecosystem, pkg["name"]) === nameKey;
if ("package" in dependency) {
const observed = record(
dependency["package"],
"Dependabot dependency package",
);
if (!matchesPackage(observed))
throw new Error(
"Dependabot dependency and matched vulnerability packages disagree.",
);
}
const path = dependency["manifest_path"] ?? null;
if (path !== null) {
const filename = relativePath(path)?.split("/").at(-1);
if (
typeof path !== "string" ||
/^[a-z][a-z\d+.-]*:/iu.test(path) ||
!filename ||
filename === "."
)
throw new Error(
"Dependabot manifest_path must identify a repository-relative file.",
);
}
const ghsa = requiredText(advisory["ghsa_id"], "Dependabot GHSA ID");
if (!GHSA_ID.test(ghsa))
throw new Error("Dependabot security_advisory must identify a GHSA.");
const affected = advisory["vulnerabilities"];
if (
!Array.isArray(affected) ||
!affected.some(
(entry) =>
isRecord(entry) &&
isRecord(entry["package"]) &&
matchesPackage(entry["package"]) &&
entry["vulnerable_version_range"] === range,
)
)
throw new Error(
"Dependabot advisory does not cover the matched package and vulnerable range.",
);
const state = alert["state"];
if (
typeof state !== "string" ||
!["open", "dismissed", "auto_dismissed", "fixed"].includes(state)
)
throw new Error(
"Dependabot alert state must be open, dismissed, auto_dismissed or fixed.",
);
const updated =
Date.parse(requiredText(alert["updated_at"], "Dependabot updated_at")) /
1000;
if (!Number.isFinite(updated) || updated < 0)
throw new Error("Dependabot updated_at must be a valid timestamp.");
const advisoryIds = new Set([ghsa]);
const cve = text(advisory["cve_id"]);
if (cve) advisoryIds.add(cve);
const identifiers = advisory["identifiers"];
if (Array.isArray(identifiers)) {
for (const item of identifiers) {
const value = isRecord(item) && text(item["value"]);
if (!value) continue;
if (
(item["type"] === "GHSA" || /^GHSA-/iu.test(value)) &&
value.toUpperCase() !== ghsa.toUpperCase()
)
throw new Error(
"Dependabot advisory identifiers disagree on the GHSA.",
);
advisoryIds.add(value);
}
}
return {
title: requiredText(advisory["summary"], "Dependabot advisory summary"),
description: text(advisory["description"]),
severity,
url,
advisory_ids: [...advisoryIds],
packages: [
{
name,
ecosystem,
manifest_path: path,
vulnerable_version_range: range,
fixed_versions: patch ? [patch.identifier] : [],
},
],
locations: path ? [{ path }] : [],
source_updated_at: Math.floor(updated),
source_data: structuredClone(alert),
};
}
export function normalizeGitHubDependabotAlerts(
input: unknown,
target: ExternalImportTarget = "cloud",
): ExternalFindings {
const alerts = selectedAlerts(input);
const result: ExternalFindings = {
read: alerts.length,
findings: [],
excluded: [],
};
const ids = new Set<string>();
let sourceRepository: string | undefined;
for (const [index, alert] of alerts.entries()) {
const { repositoryUrl, sourceId, url } = identity(alert);
if (sourceRepository !== undefined && sourceRepository !== repositoryUrl)
throw new CodexSecurityError(
"Select Dependabot alerts from only one GitHub host and repository.",
);
sourceRepository = repositoryUrl;
if (ids.has(sourceId))
throw new CodexSecurityError(
`Duplicate source finding id ${JSON.stringify(sourceId)}. Select each Dependabot alert once.`,
);
ids.add(sourceId);
const inputEvidence = evidence(alert, url);
appendFinding(result, index + 1, sourceId, () => {
if (target === "cloud" && Buffer.byteLength(sourceId) > 512)
throw new Error(
"Source finding ID exceeds the Cloud limit of 512 UTF-8 bytes.",
);
return validateExternalEvidence(inputEvidence, target);
});
}
return result;
}