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 { findingEntry } from "./value.js";
import { isGitHubCloudHost } from "./git-remote.js";
import { isRecord } from "./record.js";
import {
loadContractWithScanDirectory,
type LoadedContract,
} from "./contract.js";
import type {
Finding,
FindingCodeEvidence,
FindingLocation,
ScanTargetRecord,
SeverityLevel,
} from "./models.js";
import { bundledPluginRoot } from "./runtime.js";
import { CodexSecurityError } from "./errors.js";
import {
severityClassificationSchema,
validateSeverityClassification,
type SeverityClassification,
type SeverityAssessment,
} from "./classify-severity.js";
import {
readScanSeverityClassification,
selectClassificationFindings,
type ScanSeverityClassification,
} from "./classify-scan-severity.js";
export interface LinearPublicationDestination {
type: "linear";
teamId: string;
projectId?: string;
}
export interface PrepareScanPublicationOptions {
destination: "linear";
teamId: string;
projectId?: string;
uploadedAt?: string;
environment?: NodeJS.ProcessEnv;
signal?: AbortSignal;
expectedScanId?: string;
/** Publish only these finding IDs from the supplied scan. Use scanRepresentativeFindingIds from saved-scan dedupe. */
findingIds?: readonly string[];
/** Use this assessment; otherwise use the scan's saved classification when present. */
classification?: SeverityClassification | ScanSeverityClassification;
}
export interface PreparedPublicationIssue {
findingId: string;
occurrenceId: string;
title: string;
description: string;
priority?: 1 | 2 | 3 | 4;
}
export interface PreparedScanPublication {
scanId: string;
scanDirectory: string;
destination: LinearPublicationDestination;
issues: PreparedPublicationIssue[];
}
export function linearPublicationArguments(
destination: LinearPublicationDestination,
issue: PreparedPublicationIssue,
): Pick<PreparedPublicationIssue, "title" | "description" | "priority"> & {
team: string;
project?: string;
} {
return {
team: destination.teamId,
...(destination.projectId === undefined
? {}
: { project: destination.projectId }),
title: issue.title,
description: issue.description,
...(issue.priority === undefined ? {} : { priority: issue.priority }),
};
}
const LINEAR_PRIORITIES = {
critical: 1,
high: 2,
medium: 3,
low: 4,
informational: undefined,
} as const satisfies Record<SeverityLevel, 1 | 2 | 3 | 4 | undefined>;
export async function prepareScanPublication(
scanDirectory: string,
options: PrepareScanPublicationOptions,
): Promise<PreparedScanPublication> {
const { contract, scanDirectory: canonicalScanDirectory } =
await loadContractWithScanDirectory(scanDirectory, {
pluginRoot: await bundledPluginRoot(),
...(options.signal === undefined ? {} : { signal: options.signal }),
expectedScanId: options.expectedScanId,
});
const uploadedAt = options.uploadedAt ?? new Date().toISOString();
const scanId = contract.manifest.scan.id;
let classification: SeverityClassification | undefined;
if (options.classification !== undefined) {
const { scanId: assessedScanId, ...assessment } =
options.classification as ScanSeverityClassification;
if (assessedScanId !== undefined && assessedScanId !== scanId) {
throw new CodexSecurityError(
"Severity classification belongs to a different scan.",
);
}
classification = validateSeverityClassification(
severityClassificationSchema.parse(assessment),
contract.findings.findings,
);
} else {
classification = await readScanSeverityClassification(
canonicalScanDirectory,
scanId,
contract.findings.findings,
options.signal,
options.environment,
);
}
const assessments = new Map(classification?.assessments.map(findingEntry));
const selected = selectClassificationFindings(
contract.findings.findings,
options.findingIds ??
classification?.assessments.map(({ findingId }) => findingId),
);
if (
classification &&
selected.some(({ findingId }) => !assessments.has(findingId))
) {
throw new CodexSecurityError(
"Selected findings are missing from the severity classification. Classify the selection before publishing.",
);
}
return {
scanId,
scanDirectory: canonicalScanDirectory,
destination: {
type: options.destination,
teamId: options.teamId,
...(options.projectId === undefined
? {}
: { projectId: options.projectId }),
},
issues: selected.flatMap((finding) => {
const assessment = assessments.get(finding.findingId);
if (assessment?.decision === "excluded") return [];
const level = assessment?.level ?? finding.severity.level;
const priority = LINEAR_PRIORITIES[level];
return {
findingId: finding.findingId,
occurrenceId: finding.occurrenceId,
title: `[Codex Security][${level.toUpperCase()}] ${finding.title}`,
description: renderFindingDescription(
contract,
finding,
uploadedAt,
assessment,
),
...(priority === undefined ? {} : { priority }),
};
}),
};
}
function renderFindingDescription(
contract: LoadedContract,
finding: Finding,
uploadedAt: string,
assessment?: SeverityAssessment,
): string {
const { scan } = contract.manifest;
const lines = ["## Summary", "", finding.summary];
if (assessment?.source === "rubric") {
lines.push(
"",
"",
"## Severity classification",
"",
`**Assessed severity:** ${assessment.level}`,
`**Rubric label:** ${assessment.rubricLabel}`,
"",
assessment.rationale,
);
if (assessment.confidence !== null)
lines.push("", `**Classification confidence:** ${assessment.confidence}`);
if (assessment.reviewTrigger !== null)
lines.push("", `**Review trigger:** ${assessment.reviewTrigger}`);
}
if (finding.attackPath?.summary !== undefined) {
lines.push("", "## Reproduction summary", "", finding.attackPath.summary);
}
const rootCause = publicationRootCause(finding);
if (typeof rootCause === "string") {
lines.push("", "## Root cause", "", rootCause);
} else if (
rootCause !== undefined &&
(rootCause.summary !== undefined || rootCause.code !== undefined)
) {
lines.push("", "## Root cause");
if (rootCause.summary !== undefined) lines.push("", rootCause.summary);
if (rootCause.code !== undefined) {
lines.push("", fencedCode(rootCause.code, rootCause.language));
}
}
lines.push("", "## Remediation", "", finding.remediation);
const validation = finding.validation;
const limits = [
...new Set([
...(validation?.limitations ?? []),
...(validation?.counterEvidence ?? []),
...(finding.attackPath?.limitations ?? []),
]),
];
if (validation?.summary || validation?.method || limits.length > 0) {
lines.push("", "## Validation", "");
if (validation?.summary) lines.push(validation.summary, "");
if (validation?.method) lines.push(`**Method:** ${validation.method}`, "");
lines.push(...limits.map((limit) => `- ${limit}`));
}
const codeEvidence = publicationCodeEvidence(finding);
if (codeEvidence.length > 0) {
lines.push("", "## Source-code evidence");
for (const [index, evidence] of codeEvidence.entries()) {
lines.push("", ...renderCodeEvidence(scan.target, evidence, index));
}
}
lines.push(
"",
"---",
"",
"## Codex Security finding",
"",
`**Scan ID:** ${scan.id}`,
`**Finding ID:** ${finding.findingId}`,
`**Occurrence ID:** ${finding.occurrenceId}`,
`**Fingerprint:** ${finding.fingerprints.primary}`,
`**Severity:** ${finding.severity.level.toUpperCase()}`,
`**Confidence:** ${finding.confidence.level.toUpperCase()}`,
...(finding.taxonomy.cwe.length === 0
? []
: [`**CWE:** ${finding.taxonomy.cwe.join(", ")}`]),
"",
"## Scanned code",
"",
`**Repository:** ${scan.target.displayName}`,
...(scan.target.remote === undefined
? []
: [`**Remote:** ${scan.target.remote}`]),
...renderTargetIdentity(scan.target),
`**Scanned scope:** ${scan.scope.includePaths.join(", ") || "entire repository"}`,
...(scan.scope.excludePaths.length === 0
? []
: [`**Excluded scope:** ${scan.scope.excludePaths.join(", ")}`]),
`**Scan mode:** ${scanMode(contract.mode)}`,
`**Started:** ${scan.startedAt}`,
`**Completed:** ${scan.completedAt}`,
`**Uploaded:** ${uploadedAt}`,
"",
"### Affected locations",
"",
...finding.locations.map((location) =>
renderLocation(scan.target, location),
),
);
return `${lines.join("\n")}\n`;
}
function renderTargetIdentity(target: ScanTargetRecord): string[] {
const lines: string[] = [];
if (target.revision !== undefined) {
const label = target.kind === "git_revision" ? "Revision" : "Base revision";
lines.push(`**${label}:** ${target.revision}`);
}
if (target.baseRevision !== undefined) {
lines.push(`**Diff base revision:** ${target.baseRevision}`);
}
if (target.headRevision !== undefined) {
lines.push(`**Diff head revision:** ${target.headRevision}`);
}
if (target.snapshotDigest !== undefined) {
lines.push(`**Snapshot digest:** ${target.snapshotDigest}`);
}
return lines;
}
function scanMode(mode: LoadedContract["mode"]): string {
if (mode === "deep_repository") return "deep";
if (mode === "repository") return "standard";
return mode;
}
function renderLocation(
target: ScanTargetRecord,
location: FindingLocation,
): string {
const role =
location.role === undefined ? "Location" : humanizeRole(location.role);
const label = `${location.path}:${location.startLine}${
location.endLine === undefined || location.endLine === location.startLine
? ""
: `-${location.endLine}`
}`;
const sourceUrl = immutableSourceUrl(target, location);
const formattedLabel = inlineCode(label);
return `- **${role}:** ${sourceUrl === undefined ? formattedLabel : `[${formattedLabel}](${sourceUrl})`}`;
}
function renderCodeEvidence(
target: ScanTargetRecord,
evidence: PublicationCodeEvidence,
index: number,
): string[] {
const lines = [`### ${evidence.label ?? `Code evidence ${index + 1}`}`, ""];
if (typeof evidence["location"] === "string") {
lines.push(
`- **${evidence.role === undefined ? "Location" : humanizeRole(evidence.role)}:** ${inlineCode(evidence["location"])}`,
"",
);
} else if (evidence.path !== undefined) {
lines.push(
evidence.startLine === undefined
? `- **${evidence.role === undefined ? "Location" : humanizeRole(evidence.role)}:** ${inlineCode(evidence.path)}`
: renderLocation(target, {
...evidence,
path: evidence.path,
startLine: evidence.startLine,
}),
"",
);
}
lines.push(fencedCode(evidence.code, evidence.language));
if (evidence.explanation !== undefined) lines.push("", evidence.explanation);
return lines;
}
function publicationRootCause(finding: Finding) {
const canonical = finding.rootCause;
const legacy = finding.root_cause;
if (canonical === undefined) return legacy ?? undefined;
if (legacy === undefined || legacy === null) return canonical;
const details: Array<{ summary?: string; code?: string; language?: string }> =
[canonical, legacy].map((detail) =>
typeof detail === "string" ? { summary: detail } : detail,
);
const summary = details.find((detail) => detail.summary?.trim())?.summary;
const code = details.find((detail) => detail.code?.trim())?.code;
const language = details.find(
(detail) => detail.code === code && detail.language?.trim(),
)?.language;
return summary === undefined && code === undefined
? undefined
: { summary, code, language };
}
type PublicationCodeEvidence = Partial<FindingCodeEvidence> &
Pick<FindingCodeEvidence, "code">;
function publicationCodeEvidence(finding: Finding): PublicationCodeEvidence[] {
const evidence: PublicationCodeEvidence[] = (finding.codeEvidence ?? []).map(
(item) =>
typeof item["location"] === "string" || isRecord(item["location"])
? publicationEvidenceEntry(item, item.code)
: item,
);
const ids = new Set(
evidence.filter((item) => item.code.trim()).map((item) => item.id),
);
for (const item of finding.code_evidence ?? []) {
if (ids.has(item.id)) continue;
if (item.code.trim()) ids.add(item.id);
evidence.push(publicationEvidenceEntry(item, item.code));
}
const snippets = new Set(
evidence.map((item) => JSON.stringify([item.id ?? "", item.code])),
);
const attackPath = finding.attackPath;
for (const section of [
finding.rootCause,
finding.root_cause,
finding.validation,
attackPath,
attackPath?.dataFlow,
attackPath?.["dataflow"],
attackPath?.data_flow,
attackPath?.reachability,
]) {
if (!isRecord(section)) continue;
for (const key of ["codeEvidence", "code_evidence"]) {
const embedded = section[key];
if (!Array.isArray(embedded)) continue;
for (const item of embedded) {
if (!isRecord(item)) continue;
const code = item["code"];
if (typeof code !== "string" || !code.trim()) continue;
const identity = JSON.stringify([item["id"] ?? "", code]);
if (snippets.has(identity)) continue;
snippets.add(identity);
evidence.push(publicationEvidenceEntry(item, code));
}
}
}
return evidence;
}
function publicationEvidenceEntry(
item: Record<string, unknown>,
code: string,
): PublicationCodeEvidence {
const entry: PublicationCodeEvidence = { code };
for (const key of [
"id",
"label",
"language",
"role",
"explanation",
] as const) {
const value = item[key];
if (typeof value === "string" && value.length > 0) entry[key] = value;
}
if (typeof item["location"] === "string") {
const label = item["location"].trim().replace(/\s+/g, " ");
if (label) entry["location"] = label;
return entry;
}
const location = isRecord(item["location"]) ? item["location"] : item;
const path = location["path"];
if (typeof path === "string" && path.length > 0) entry.path = path;
const start = location["startLine"];
if (typeof start === "number" && Number.isInteger(start) && start > 0) {
entry.startLine = start;
const end = location["endLine"];
if (typeof end === "number" && Number.isInteger(end) && end >= start)
entry.endLine = end;
}
return entry;
}
function humanizeRole(role: string): string {
const words = role.replaceAll("_", " ");
return `${words.slice(0, 1).toUpperCase()}${words.slice(1)}`;
}
function inlineCode(label: string): string {
let fenceLength = 1;
for (const match of label.matchAll(/`+/g)) {
fenceLength = Math.max(fenceLength, match[0].length + 1);
}
const fence = "`".repeat(fenceLength);
const padding = label.startsWith("`") || label.endsWith("`") ? " " : "";
return `${fence}${padding}${label}${padding}${fence}`;
}
function fencedCode(code: string, language?: string): string {
let fenceLength = 3;
for (const match of code.matchAll(/`+/g)) {
fenceLength = Math.max(fenceLength, match[0].length + 1);
}
const fence = "`".repeat(fenceLength);
const tag =
language !== undefined && /^[A-Za-z0-9_+.-]+$/.test(language)
? language
: "";
return `${fence}${tag}\n${code}\n${fence}`;
}
function immutableSourceUrl(
target: ScanTargetRecord,
location: FindingLocation,
): string | undefined {
if (
target.kind !== "git_revision" ||
target.remote === undefined ||
target.revision === undefined ||
!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(target.revision) ||
!isSafeRepositoryPath(location.path)
) {
return undefined;
}
let remote: URL;
try {
remote = new URL(target.remote);
} catch {
return undefined;
}
if (remote.protocol !== "https:" || !isGitHubCloudHost(remote.hostname)) {
return undefined;
}
const repository = remote.pathname
.replace(/\.git\/?$/, "")
.replace(/\/$/, "");
const segments = location.path.split("/");
const path = segments.map(encodeURIComponent).join("/");
remote.pathname = `${repository}/blob/${target.revision}/${path}`;
// GitHub renders Markdown previews without source line anchors.
const markdownPath =
/\.(?:md|markdown|mdown|mdwn|mkd|mkdn|mkdown|mdx|litcoffee|livemd|ronn|scd|workbook)$/i;
if (markdownPath.test(location.path) || segments.at(-1) === "contents.lr") {
remote.search = "plain=1";
}
remote.hash = `L${location.startLine}${
location.endLine === undefined || location.endLine === location.startLine
? ""
: `-L${location.endLine}`
}`;
return remote.toString();
}
function isSafeRepositoryPath(path: string): boolean {
if (
path.includes("\\") ||
/^[A-Za-z]:/.test(path) ||
/[\u0000-\u001f\u007f]/.test(path)
) {
return false;
}
return path
.split("/")
.every(
(segment) =>
segment.length > 0 &&
segment !== "." &&
segment !== ".." &&
!/%(?:2e|2f|5c)/i.test(segment),
);
}