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 type { ExternalImportTarget } from "./external-import-contract.js";
import { hash } from "node:crypto";
import { isProxy } from "node:util/types";
import { GHSA_ID, githubRepositoryParts } from "./github-identifiers.js";
import { CodexSecurityError, errorMessage } from "./errors.js";
import {
cloudRepositoryUrlKey,
exportedGitHubRecord,
validateExternalEvidence,
} from "./external-import-contract.js";
import type { ExternalFinding, ExternalFindings } from "./external-findings.js";
import type { ImportedGitHubCodeScanningAlert } from "./github.js";
import type { ImportedGitHubAdvisory } from "./github-advisories.js";
import {
isGitHubDependabotAlert,
normalizeGitHubDependabotAlerts,
} from "./github-dependabot-findings.js";
import { asRecord } from "./record.js";
import {
parseJsonOrJsonl,
readScannerText,
scannerSeverity,
text,
} from "./scanner-import.js";
function repositoryName(value: unknown): string {
const repository = text(value);
if (!repository || !githubRepositoryParts(repository))
throw new Error("GitHub repository must be OWNER/REPO.");
return repository;
}
function sourceUrl(value: string): {
parsed: URL;
host: string;
origin: string;
} {
const parsed = new URL(value);
const origin = /^(https?:\/\/([^/?#]+))/iu.exec(value);
if (!origin) throw new Error("GitHub evidence URL must be an HTTP(S) link.");
// URL.origin/host remove explicit default ports; Cloud keeps those distinct.
return { parsed, host: origin[2]!.toLowerCase(), origin: origin[1]! };
}
function sourceTimestamp(value: unknown): number | null {
if (value === undefined || value === null) return null;
const seconds = typeof value === "string" ? Date.parse(value) / 1000 : NaN;
if (!Number.isFinite(seconds) || seconds < 0)
throw new Error("GitHub updated_at is not a valid timestamp.");
return Math.floor(seconds);
}
function codeScanningPrefix(
{ parsed, host }: ReturnType<typeof sourceUrl>,
repository: string,
number: number,
): string | undefined {
const name = repository.toLowerCase();
const path = parsed.pathname.toLowerCase();
const alert = `code-scanning/${number}`;
if (path === `/${name}/${alert}` || path === `/${name}/security/${alert}`)
return `${host}/${name}/${alert}/`;
}
function codeScanningSource(record: Record<string, unknown>) {
const name = repositoryName(record["repository"]);
const alert = asRecord(record["alert"]);
const number = record["number"];
if (
!alert ||
typeof number !== "number" ||
!Number.isSafeInteger(number) ||
number < 1 ||
alert["number"] !== number
)
throw new Error(
"Expected a GitHub code-scanning import with matching alert numbers.",
);
const url = text(record["url"]);
if (!url || url !== alert["html_url"])
throw new Error("GitHub alert URL must match the original alert.");
const link = sourceUrl(url);
const prefix = codeScanningPrefix(link, name, number);
if (!prefix)
throw new Error(
"GitHub alert URL does not match the selected repository and alert.",
);
const repository = { url: `${link.origin}/${name}`, name };
return { alert, number, prefix, url, repository };
}
function codeScanningFinding(record: Record<string, unknown>): {
source_finding_id: string;
evidence: unknown;
} {
const { alert, number, prefix, url, repository } = codeScanningSource(record);
const rule = asRecord(alert["rule"]);
const instance = asRecord(alert["most_recent_instance"]);
const ref = text(instance?.["ref"]);
if (!ref)
throw new Error(
"GitHub code-scanning evidence requires the selected instance ref.",
);
const location = asRecord(instance?.["location"]);
const tool = asRecord(alert["tool"]);
const message = text(asRecord(instance?.["message"])?.["text"]);
const description =
text(rule?.["full_description"]) ?? text(rule?.["description"]);
const tags = Array.isArray(rule?.["tags"]) ? rule["tags"] : [];
const weaknessIds = [
...new Set(
tags.flatMap((tag: unknown) => {
const match =
typeof tag === "string"
? /^external\/cwe\/cwe-(\d+)$/iu.exec(tag)
: null;
return match ? [`CWE-${Number(match[1])}`] : [];
}),
),
];
const path = text(location?.["path"]);
return {
source_finding_id: prefix + hash("sha256", ref),
evidence: {
title:
text(rule?.["name"]) ??
text(rule?.["description"]) ??
`GitHub code-scanning alert #${number}`,
// SARIF error, warning and note describe diagnostics. Use the security rating.
severity: scannerSeverity(text(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,
// 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,
},
},
};
}
function advisorySourceId(
host: string,
selection: "global" | "repository",
repository: string,
id: string,
): string {
return `${host}/${selection === "repository" ? repository.toLowerCase() : "global"}/security-advisory/${id.toUpperCase()}`;
}
function advisorySource(record: Record<string, unknown>) {
const name = repositoryName(record["repository"]);
const advisory = asRecord(record["advisory"]);
const id = text(record["ghsaId"]);
const selection = record["selection"];
if (
!advisory ||
!id ||
!GHSA_ID.test(id) ||
text(advisory["ghsa_id"])?.toUpperCase() !== id.toUpperCase()
)
throw new Error(
"Expected a GitHub advisory import with matching GHSA IDs.",
);
if (selection !== "repository" && selection !== "global")
throw new Error("GitHub advisory selection must be repository or global.");
const url = text(record["url"]);
if (!url || url !== advisory["html_url"])
throw new Error("GitHub advisory URL must match the original advisory.");
const { parsed: parsedUrl, host: linkHost, origin } = sourceUrl(url);
const host = text(record["githubHost"])?.toLowerCase();
// Enterprise APIs may return the public advisory database's canonical link.
const canonicalGlobalLink =
selection === "global" && parsedUrl.host === "github.com";
const expectedPath =
selection === "repository"
? `/${name}/security/advisories/${id}`
: `/advisories/${id}`;
if (
!host ||
(linkHost !== host && !canonicalGlobalLink) ||
parsedUrl.pathname.toLowerCase() !== expectedPath.toLowerCase()
)
throw new Error(
"GitHub advisory URL does not match the selected source and GHSA ID.",
);
const repository = { url: `${origin}/${name}`, name };
return { advisory, id, selection, url, host, repository } as const;
}
function advisoryFinding(record: Record<string, unknown>): {
source_finding_id: string;
evidence: unknown;
} {
const { advisory, id, selection, url, host, repository } =
advisorySource(record);
const vulnerabilities =
advisory["vulnerabilities"] === null ? [] : advisory["vulnerabilities"];
if (!Array.isArray(vulnerabilities))
throw new Error("GitHub advisory vulnerabilities must be an array.");
const identifiers = Array.isArray(advisory["identifiers"])
? advisory["identifiers"]
: [];
const advisoryIds = [
id,
text(advisory["cve_id"]),
...identifiers.map((identifier) => text(asRecord(identifier)?.["value"])),
].filter((value): value is string => value !== null);
const packages = vulnerabilities.flatMap((value) => {
const vulnerability = asRecord(value);
const pkg = asRecord(vulnerability?.["package"]);
const name = text(pkg?.["name"]);
// GitHub permits incomplete package metadata in advisory disclosures.
// Preserve it in source_data without inventing a typed package identity.
if (!name) return [];
const fixedVersion =
text(vulnerability?.["first_patched_version"]) ??
text(vulnerability?.["patched_versions"]);
return [
{
name,
ecosystem: text(pkg?.["ecosystem"]),
vulnerable_version_range: text(
vulnerability?.["vulnerable_version_range"],
),
fixed_versions: fixedVersion ? [fixedVersion] : [],
},
];
});
const cwes = Array.isArray(advisory["cwes"]) ? advisory["cwes"] : [];
return {
source_finding_id: advisorySourceId(host, selection, repository.name, id),
evidence: {
title: text(advisory["summary"]) ?? id,
severity: scannerSeverity(text(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 } : {}),
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(asRecord(value)?.["cwe_id"]))
.filter((value): value is string => value !== null),
},
},
};
}
/** Keep the repository from a retained collector export when SDK callers supply their own projection. */
export function retainedGitHubRepository(
{ evidence }: ExternalFinding,
repositoryKey = cloudRepositoryUrlKey,
): string | undefined {
const data = evidence.source_data;
if (!data?.["url"] || !data["repository"]) return;
let source;
if (
data["source"] === "github-code-scanning" &&
data["number"] !== undefined &&
asRecord(data["alert"])?.["html_url"]
) {
source = codeScanningSource(data);
} else if (
data["source"] === "github-security-advisory" &&
data["ghsaId"] &&
data["githubHost"] &&
data["selection"] &&
asRecord(data["advisory"])?.["html_url"]
) {
source = advisorySource(data);
if (source.selection === "global") {
if (evidence.details?.repository)
throw new CodexSecurityError(
"Global advisory evidence cannot claim a source repository.",
);
return;
}
} else return;
const native = source.repository.url;
const projected = evidence.details?.repository?.url;
if (projected && repositoryKey(projected) !== repositoryKey(native))
throw new CodexSecurityError(
"The normalized repository does not match the original GitHub finding.",
);
return native;
}
function mapRecord(input: unknown) {
const record = asRecord(input);
if (!record) throw new Error("GitHub finding must be an object.");
if (record["source"] === "github-code-scanning")
return codeScanningFinding(record);
if (record["source"] === "github-security-advisory")
return advisoryFinding(record);
throw new Error(
"Expected saved output from import github or import github-advisories; raw or incomplete API responses need an explicit mapping.",
);
}
function ownData(value: unknown, key: string): unknown {
if (value && typeof value === "object" && !isProxy(value))
return Object.getOwnPropertyDescriptor(value, key)?.value;
}
function normalizeRecords(
records: readonly unknown[],
target: ExternalImportTarget,
snapshot = false,
): ExternalFindings {
const result: ExternalFindings = {
read: records.length,
findings: [],
excluded: [],
};
const identities = new Set<string>();
for (const [index, input] of records.entries()) {
let exported = input;
try {
if (snapshot) {
const capture = exportedGitHubRecord(input, index, target);
exported = capture.record;
if (capture.invalid) throw capture.invalid;
}
const { source_finding_id: id, evidence: mapped } = mapRecord(exported);
const evidence = validateExternalEvidence(mapped, target);
if (identities.has(id))
throw new CodexSecurityError(
`Duplicate source finding id ${JSON.stringify(id)}. Select each GitHub occurrence once.`,
);
identities.add(id);
result.findings.push({ source_finding_id: id, evidence });
} catch (error) {
if (error instanceof CodexSecurityError) throw error;
const url =
snapshot && exported === input
? ownData(input, "url")
: asRecord(exported)?.["url"];
result.excluded.push({
position: index + 1,
source_finding_id: text(url),
reason: errorMessage(error),
});
}
}
return result;
}
/** Map selected code-scanning instances while retaining complete upstream evidence. */
export function normalizeGitHubCodeScanningAlerts(
alerts: readonly ImportedGitHubCodeScanningAlert[],
target: ExternalImportTarget = "cloud",
): ExternalFindings {
return normalizeRecords(alerts, target, true);
}
/** Map advisory disclosures without asserting an installed vulnerable dependency. */
export function normalizeGitHubAdvisories(
advisories: readonly ImportedGitHubAdvisory[],
target: ExternalImportTarget = "cloud",
): ExternalFindings {
return normalizeRecords(advisories, target, true);
}
/** 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));
const rows = Array.isArray(payload) ? payload : [payload];
if (
(rows.length > 0 && rows.every(Array.isArray)) ||
rows.some((row) =>
Array.isArray(row)
? row.some(isGitHubDependabotAlert)
: isGitHubDependabotAlert(row),
)
)
return normalizeGitHubDependabotAlerts(payload, target);
return normalizeRecords(rows, target);
} catch (cause) {
throw new CodexSecurityError(
`Could not read GitHub findings as UTF-8 JSON or JSONL: ${errorMessage(cause)}`,
{ cause },
);
}
}