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 { posix, sep } from "node:path";
import type { ExternalImportTarget } from "./external-import-contract.js";
import { validateExternalEvidence } from "./external-import-contract.js";
import type { ExternalFindings } from "./external-findings.js";
import { isGitHubCloudHost, isGitSsh, parseGitRemote } from "./git-remote.js";
import {
hostedRepositoryUrlKey,
normalizeHostedGitRepositoryUrl,
} from "./hosted-git-repository.js";
import { isRecord } from "./record.js";
import {
array,
normalizeRecords,
readScannerJson,
record,
relativePath,
reportableScannerSeverity,
requiredText,
stableId,
strings,
text,
} from "./scanner-import.js";
type NativeRecord = Record<string, unknown>;
const urlScheme = /^[a-z][a-z\d+.-]*:\/\//iu;
const javaArchiveAncestor = /\.(?:jar|war|ear|par)\//iu;
const cloudLocationLimit = 100;
const curlUrlPrefix = /^(?:(?:https?|ftps?)::)?(?:https?|ftps?):\/{1,3}/iu;
const unsafeRepositoryUrl =
"Use a Trivy repository URL without credentials, a query, or a fragment.";
function hasHttpUserinfo(
value: string | null,
allowImplicitHttps: boolean,
): boolean {
if (!value) return false;
const prefix = curlUrlPrefix.exec(value)?.[0];
if (!prefix && (!allowImplicitHttps || /^[a-z]:[\\/]/iu.test(value)))
return false;
// Git's HTTP transport treats backslashes before @ as part of userinfo.
const authority = value.slice(prefix?.length ?? 0).split(/[/?#]/u, 1)[0]!;
const at = authority.lastIndexOf("@");
const colon = authority.indexOf(":");
const scp = colon > authority.indexOf("@");
// A bare user@host:path is Git's SSH form. Trivy reads user@host/path as HTTPS.
return at > 0 && (!!prefix || (!scp && !authority.includes("\\", at + 1)));
}
function networkRepository(value: unknown): string | null {
const source = text(value);
if (!source || /^(?:[a-z]:|[./\\])/iu.test(source)) return null;
const remote = parseGitRemote(source);
if (!remote) return null;
const { url } = remote;
const ssh = isGitSsh(url.protocol);
if (url.password || (!ssh && url.username) || /[?#\t\r\n]/u.test(source))
throw new Error(unsafeRepositoryUrl);
if (url.protocol === "file:") return null;
if (
!url.hostname ||
!remote.path ||
(!ssh &&
!["http:", "https:", "git:", "ftp:", "ftps:"].includes(url.protocol))
)
throw new Error("Unsupported Trivy repository URL.");
return source;
}
function comparableGitHubRemote(
remote: string,
cloudRepositoryUrl?: string,
): string | undefined {
if (/[?#\t\r\n]/u.test(remote)) return undefined;
let parsed;
try {
parsed = parseGitRemote(remote);
} catch {
// A checkout can have unrelated remotes with no comparable URL.
return undefined;
}
if (!parsed) return undefined;
const prefix = `${parsed.url.protocol}//`;
// Git dispatches mixed-case schemes to distinct remote helpers.
if (!parsed.scpStyle && !remote.startsWith(prefix)) return undefined;
const host = parsed.url.hostname.toLowerCase();
const githubUrl =
cloudRepositoryUrl ??
(isGitHubCloudHost(host) ? `https://${host}` : undefined);
const normalized = normalizeHostedGitRepositoryUrl(
remote,
githubUrl,
githubUrl !== undefined,
);
if (!/^https?:\/\//iu.test(normalized)) return undefined;
if (
!isGitHubCloudHost(new URL(normalized).hostname) &&
(!cloudRepositoryUrl || new URL(cloudRepositoryUrl).hostname !== host)
)
return undefined;
return normalized;
}
export function trivyRemoteKey(
remote: string,
cloudRepositoryUrl?: string,
checkout = false,
): string {
const normalized = comparableGitHubRemote(remote, cloudRepositoryUrl);
if (!normalized) return remote;
// GitHub identifies an HTTPS repository by host and path. Other Git servers
// may use the HTTP username to select the repository.
const url = checkout
? normalized.replace(/^(https?:\/\/)[^/\\?#]*@/iu, "$1")
: normalized;
return hostedRepositoryUrlKey(
url,
true,
false,
cloudRepositoryUrl ? "cloud" : "local",
);
}
const sshScheme = /^(?:ssh|git\+ssh|ssh\+git):\/\//u;
export function trivyRemoteOmitsSshUser(url: string): boolean {
return sshScheme.test(url) && !new URL(url).username;
}
export const trivyHeaderFields = [
"SchemaVersion",
"ArtifactType",
"ArtifactID",
"ReportID",
"CreatedAt",
];
// Go may rewrite escaped separators or unreserved bytes in mixed Unicode paths.
// Only escape spaces and non-ASCII bytes when existing escapes are unambiguous.
function escapedHttpTarget(target: string): string {
return target.replace(
/^(https?:\/\/[^/]+)(\/(?:[^%]|%(?:2[05]|[89A-F][\dA-F]))*)$/u,
(_, authority: string, path: string) =>
authority + path.replace(/[ \P{ASCII}]+/gu, encodeURIComponent),
);
}
export function trivyReportRemotes(report: unknown) {
if (!isRecord(report)) return { urls: [] };
const metadata = report["Metadata"];
const repoUrl = text(isRecord(metadata) && metadata["RepoURL"]);
const name = text(report["ArtifactName"]);
if (
hasHttpUserinfo(repoUrl, true) ||
hasHttpUserinfo(name, report["ArtifactType"] !== "filesystem")
)
throw new Error(unsafeRepositoryUrl);
const repository = networkRepository(repoUrl);
let artifact = name && urlScheme.test(name) ? networkRepository(name) : null;
if (report["SchemaVersion"] !== 2) return { urls: [] };
// A filesystem display label is validated but never identifies the repository.
if (report["ArtifactType"] === "filesystem")
return { urls: repository ? [repository] : [] };
// Trivy accepts scheme-less HTTPS targets and relative checkout paths.
// A scheme-less name identifies a remote only when Git metadata corroborates it.
const target =
artifact ??
(name && /^[^./:\\][^/:\\]*\//u.test(name) ? `https://${name}` : null);
if (
target &&
repository &&
report["ArtifactType"] === "repository" &&
(target === repository || escapedHttpTarget(target) === repository)
)
artifact = repository;
// A checkout-supplied label cannot restore an omitted SSH user. Keep any
// other difference visible when validating the report's repository claims.
if (
repository &&
trivyRemoteOmitsSshUser(repository) &&
artifact?.replace(/^([^:]+:\/\/)[^/@]+@/u, "$1") === repository
)
return { urls: [repository] };
return {
urls: [repository, artifact].filter((url) => url !== null),
uncorroboratedTarget: repository ? null : artifact,
};
}
function matchingTrivyRemotes(
[repository, artifact]: readonly string[],
githubUrl?: string,
): boolean {
return (
!!repository &&
!!artifact &&
trivyRemoteKey(repository, githubUrl) ===
trivyRemoteKey(artifact, githubUrl)
);
}
/** Compare the report's claims using the authenticated host when available. */
export function trivyRepositoryUrl(
report: unknown,
cloudRepositoryUrl?: string,
): string | null {
const { urls } = trivyReportRemotes(report);
if (urls.length > 1 && !matchingTrivyRemotes(urls, cloudRepositoryUrl))
throw new Error("Trivy source URLs identify different repositories.");
const remote = urls[0];
return remote && cloudRepositoryUrl
? (comparableGitHubRemote(remote, cloudRepositoryUrl) ?? remote)
: (remote ?? null);
}
function repositoryPath(value: unknown, directory = false): string | null {
const raw = text(value);
if (!raw || !relativePath(raw)) return null;
// Check the emitted spelling across platforms while retaining literal POSIX backslashes.
const path = posix.normalize(raw);
const portable = posix.normalize(path.replaceAll("\\", "/"));
const firstComponent = portable.split("/", 1)[0]!;
const at = firstComponent.indexOf("@", 1);
const scpStyle = at !== -1 && firstComponent.indexOf(":", at + 2) !== -1;
return relativePath(portable) &&
(directory || (portable !== "." && !portable.endsWith("/"))) &&
!scpStyle &&
!/^[a-z][a-z\d+.-]*:\//iu.test(portable)
? path
: null;
}
const aggregateTargets = new Map([
["python-pkg", "Python"],
["conda-pkg", "Conda"],
["gemspec", "Ruby"],
["node-pkg", "Node.js"],
["jar", "Java"],
["kubernetes", "Kubernetes"],
]);
const nonManifestTypes = new Set([
"gobinary",
"rustbinary",
"jar",
"javascript",
]);
function resolveScanRoot(
scanRoot: string | undefined,
remoteRepository: boolean,
): string {
if (scanRoot === undefined) {
if (remoteRepository) return ".";
throw new Error(
"Specify --trivy-scan-root relative to the repository; use . for a whole-checkout scan.",
);
}
const root = repositoryPath(scanRoot.split(sep).join("/"), true)?.replace(
/\/$/u,
"",
);
if (!root)
throw new Error(
"--trivy-scan-root must be a repository-relative directory without traversal.",
);
if (remoteRepository && root !== ".")
throw new Error(
"A remote Trivy repository scan starts at the checkout root; --trivy-scan-root must be .",
);
return root;
}
function scopedPath(root: string, value: unknown): string | null {
const path = repositoryPath(value);
return path === null ? null : posix.join(root, path);
}
function pick(source: NativeRecord, fields: string[]): NativeRecord {
return Object.fromEntries(
fields
.filter((field) => Object.hasOwn(source, field))
.map((field) => [field, source[field]]),
);
}
function packageKeys(row: NativeRecord, inventory: boolean) {
const path = row[inventory ? "FilePath" : "PkgPath"];
const identifier = row[inventory ? "Identifier" : "PkgIdentifier"];
const name = row[inventory ? "Name" : "PkgName"];
const version = row[inventory ? "Version" : "InstalledVersion"];
const file = repositoryPath(path) ?? text(path);
const key = (kind: string, value: unknown) =>
text(value) && JSON.stringify([kind, value, file]);
const native = isRecord(identifier) ? identifier : {};
return {
id: key("id", row[inventory ? "ID" : "PkgID"]),
uid: key("uid", native["UID"]),
purl: key("purl", native["PURL"]),
bomRef: key("bomRef", native["BOMRef"]),
nameVersion:
text(name) &&
text(version) &&
JSON.stringify(["name-version", name, version, file]),
};
}
type PackageIndex = Map<
string,
{ pkg: NativeRecord; keys: ReturnType<typeof packageKeys> } | null
>;
function indexPackages(packages: unknown): PackageIndex {
const index: PackageIndex = new Map();
for (const value of array(packages ?? [], "Trivy Packages")) {
const pkg = record(value, "Trivy package");
const keys = packageKeys(pkg, true);
const match = { pkg, keys };
for (const key of Object.values(keys))
if (key) index.set(key, index.has(key) ? null : match);
}
return index;
}
function matchingPackage(vulnerability: NativeRecord, index: PackageIndex) {
const keys = packageKeys(vulnerability, false);
const supplied = (["uid", "id", "purl", "bomRef"] as const).filter(
(field) => keys[field],
);
for (const field of supplied.length ? supplied : (["nameVersion"] as const)) {
const key = keys[field];
const match = key && index.get(key);
if (
match &&
agreesWhenPresent(vulnerability["PkgName"], match.pkg["Name"]) &&
agreesWhenPresent(
vulnerability["InstalledVersion"],
match.pkg["Version"],
) &&
supplied.every((id) => !match.keys[id] || keys[id] === match.keys[id])
)
return match.pkg;
}
return null;
}
function agreesWhenPresent(detected: unknown, inventoried: unknown): boolean {
return !text(detected) || !text(inventoried) || detected === inventoried;
}
interface Entry {
result: { Target?: string; Type: string; Class: string };
packages: PackageIndex;
value: unknown;
}
function occurrence(entry: Entry | string, root: string) {
if (typeof entry === "string") throw new Error(entry);
const vulnerability = record(entry.value, "Trivy vulnerability");
const { Target, Type } = entry.result;
return {
...entry,
vulnerability,
advisory: requiredText(
vulnerability["VulnerabilityID"],
"Trivy VulnerabilityID",
),
name: requiredText(vulnerability["PkgName"], "Trivy PkgName"),
pkgPath: text(vulnerability["PkgPath"]),
targetPath:
aggregateTargets.get(Type) === Target ? null : scopedPath(root, Target),
packagePath: scopedPath(root, vulnerability["PkgPath"]),
};
}
/** Import native Trivy dependency occurrences. Local scans require their checkout-relative
* scan root. The package ecosystem is the PURL type when supplied, otherwise the analyzer. */
export function normalizeTrivyFindings(
input: unknown,
target: ExternalImportTarget = "cloud",
scanRoot?: string,
): ExternalFindings {
const locationLimit = target === "cloud" ? cloudLocationLimit : Infinity;
const document = record(input, "Trivy report");
if (document["SchemaVersion"] !== 2)
throw new Error(
"Expected a native Trivy JSON report with SchemaVersion 2.",
);
if (
document["ArtifactType"] !== "repository" &&
document["ArtifactType"] !== "filesystem"
)
throw new Error(
"Only Trivy repository and filesystem reports are supported.",
);
const metadata = record(document["Metadata"] ?? {}, "Trivy Metadata");
const { urls } = trivyReportRemotes(document);
const report = {
...pick(document, trivyHeaderFields),
...(isRecord(document["Trivy"])
? { Trivy: pick(document["Trivy"], ["Version"]) }
: {}),
...(typeof document["ArtifactName"] === "string"
? { ArtifactName: document["ArtifactName"] }
: {}),
Metadata: pick(metadata, ["RepoURL", "Branch", "Commit"]),
};
// A scan root requires corroboration. Explicit-root readers can inspect a report
// whose declarations still have to agree with the destination at import.
const root = resolveScanRoot(scanRoot, matchingTrivyRemotes(urls));
const entries: (Entry | string)[] = [];
for (const group of array(document["Results"] ?? [], "Trivy Results")) {
const result = record(group, "Trivy result");
if (result["Class"] !== "lang-pkgs") {
entries.push(
`Unsupported Trivy result class: ${text(result["Class"]) ?? "(missing)"}. Only lang-pkgs vulnerabilities are imported.`,
);
continue;
}
for (const field of [
"Misconfigurations",
"Secrets",
"Licenses",
"CryptoAssets",
"CustomResources",
"ExperimentalModifiedFindings",
])
if (array(result[field] ?? [], `Trivy ${field}`).length)
entries.push(`Unsupported Trivy ${field} in lang-pkgs result.`);
const vulnerabilities = array(
result["Vulnerabilities"] ?? [],
"Trivy Vulnerabilities",
);
if (!vulnerabilities.length) continue;
const reportedTarget = result["Target"];
if (reportedTarget != null && typeof reportedTarget !== "string")
throw new Error("Trivy result Target must be text.");
const context = {
...(reportedTarget == null ? {} : { Target: reportedTarget }),
Type: requiredText(result["Type"], "Trivy result Type"),
Class: result["Class"],
};
const packages = indexPackages(result["Packages"]);
for (const value of vulnerabilities)
entries.push({ result: context, packages, value });
}
const findings = normalizeRecords(
entries,
(entry) => {
const row = occurrence(entry, root);
const { result, packages, vulnerability, advisory, name, targetPath } =
row;
const identifier = vulnerability["PkgIdentifier"];
const purl = isRecord(identifier) ? text(identifier["PURL"]) : null;
const ecosystem =
purl?.match(/^pkg:([a-z][a-z\d.+-]*)\//iu)?.[1]?.toLowerCase() ??
result.Type;
const pkg = matchingPackage(vulnerability, packages);
const manifest = nonManifestTypes.has(result.Type) ? null : targetPath;
// Trivy uses the same spelling for archive members and files in exploded archives.
let declaration = row.pkgPath ? row.packagePath : manifest;
if (
result.Type === "jar" &&
row.pkgPath !== null &&
javaArchiveAncestor.test(row.pkgPath) &&
/\.(?:jar|ear|war)$/u.test(row.pkgPath)
)
declaration = null;
const locations: { path: string; line: number | null }[] = [];
if (targetPath && targetPath !== declaration)
locations.push({ path: targetPath, line: null });
if (declaration) {
// The scan target already consumes a slot when it differs from this declaration.
const lineLimit = locationLimit - locations.length;
const lines = new Set<number>();
for (const range of array(
pkg?.["Locations"] ?? [],
"Trivy package Locations",
)) {
const start = isRecord(range) && range["StartLine"];
if (
typeof start === "number" &&
Number.isSafeInteger(start) &&
start > 0 &&
lines.size < lineLimit
)
lines.add(start);
}
if (!lines.size) locations.push({ path: declaration, line: null });
for (const line of lines) locations.push({ path: declaration, line });
}
return validateExternalEvidence(
{
title: text(vulnerability["Title"]) ?? `${advisory} in ${name}`,
severity: reportableScannerSeverity(vulnerability["Severity"]),
description: text(vulnerability["Description"]),
url: text(vulnerability["PrimaryURL"]),
advisory_ids: [
...new Set([advisory, ...strings(vulnerability["VendorIDs"])]),
],
packages: [
{
name,
ecosystem,
manifest_path: manifest,
installed_version: text(vulnerability["InstalledVersion"]),
fixed_versions:
text(vulnerability["FixedVersion"])
?.split(",")
.map((version) => version.trim())
.filter(Boolean) ?? [],
},
],
locations,
branch: text(metadata["Branch"]),
source_scan_id: text(document["ReportID"]),
source_data: structuredClone({
scanRoot: root,
report,
result,
vulnerability,
...(pkg
? {
package: pick(pkg, [
"ID",
"Name",
"Version",
"Identifier",
"FilePath",
"Relationship",
"Locations",
]),
}
: {}),
}),
},
target,
);
},
(entry) => {
const { result, advisory, name, pkgPath, targetPath, packagePath } =
occurrence(entry, root);
const manifest = targetPath ?? text(result.Target);
const concretePath = packagePath ?? pkgPath;
return stableId("trivy", [
result.Type,
manifest,
advisory,
name,
concretePath === manifest ? null : concretePath,
...(!targetPath && !packagePath && root !== "." ? [root] : []),
]);
},
target,
);
if (!findings.findings.length) findings.report = report;
return findings;
}
export async function readTrivyFindings(
path: string,
target: ExternalImportTarget = "cloud",
scanRoot?: string,
): Promise<ExternalFindings> {
return normalizeTrivyFindings(await readScannerJson(path), target, scanRoot);
}