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 { randomUUID } from "node:crypto";
import { rename, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import {
classifySeverityInternal,
validateSeverityClassification,
type ClassifySeverityOptions,
type SeverityClassification,
} from "./classify-severity.js";
import { loadContractWithScanDirectory } from "./contract.js";
import { CodexSecurityError } from "./errors.js";
import type { Finding } from "./models.js";
import type { DocumentRoots } from "./prompt-files.js";
import { bundledPluginRoot } from "./runtime.js";
import { savedScanWorkbench } from "./saved-scan-bootstrap.js";
import {
resolveCompletedScan,
type SavedScanDependencies,
} from "./saved-scan.js";
import { SeverityStore } from "./severity-store.js";
import { documentSourceRoot, nullIfMissingPath } from "./targets.js";
const CLASSIFICATION_FILE = "severity-classification.json";
export interface ScanSeverityClassification extends SeverityClassification {
scanId: string;
}
export interface ClassifyScanSeverityOptions extends ClassifySeverityOptions {
/** Exact selection, such as dedupe's scanRepresentativeFindingIds. Omit to classify all findings. */
findingIds?: readonly string[];
/** Reclassify selected findings even when their saved assessment matches the inputs. */
reprocess?: boolean;
expectedScanId?: string;
}
/** Resolve a saved scan ID, unique prefix, or latest and save its classification. */
export async function classifyScanSeverity(
scanId: string,
options: ClassifyScanSeverityOptions = {},
): Promise<ScanSeverityClassification> {
return classifyScanSeverityInternal(scanId, options);
}
/** @internal */
export async function classifyScanSeverityInternal(
scanId: string,
options: ClassifyScanSeverityOptions = {},
dependencies: Partial<SavedScanDependencies> = {},
surface: "sdk" | "cli" = "sdk",
): Promise<ScanSeverityClassification> {
options.signal?.throwIfAborted();
const environment = options.environment ?? process.env;
const pluginRoot = await bundledPluginRoot();
const currentDirectory = dependencies.currentDirectory?.() ?? process.cwd();
const bootstrap = dependencies.runWorkbench
? undefined
: await savedScanWorkbench(scanId, {
environment,
pluginRoot,
currentDirectory,
signal: options.signal,
});
const scan = await resolveCompletedScan(scanId, {
currentDirectory: () => currentDirectory,
runWorkbench: (args, input) =>
(dependencies.runWorkbench ?? bootstrap!)(args, input, options.signal),
});
if (
options.expectedScanId !== undefined &&
options.expectedScanId !== scan.scanId
) {
throw new CodexSecurityError("Saved scan does not match expectedScanId.");
}
const target = scan["targetPath"];
// The workbench enables remediation only for the recorded checkout and revision.
const sourceRoot =
scan["remediationAvailable"] === true &&
typeof target === "string" &&
(options.rubricPath !== undefined || options.knowledgeBasePaths?.length)
? await documentSourceRoot(target, options.signal).catch(
nullIfMissingPath,
)
: null;
return classifyScanDirectorySeverityInternal(
scan.scanDir,
{ ...options, expectedScanId: scan.scanId },
surface,
bootstrap?.protectedRoots,
sourceRoot === null ? null : [sourceRoot],
);
}
/** Classify a sealed scan directory and save a separate assessment without changing its artifacts. */
export async function classifyScanDirectorySeverity(
scanDirectory: string,
options: ClassifyScanSeverityOptions = {},
): Promise<ScanSeverityClassification> {
return classifyScanDirectorySeverityInternal(scanDirectory, options);
}
/** @internal */
export async function classifyScanDirectorySeverityInternal(
requestedDirectory: string,
options: ClassifyScanSeverityOptions = {},
surface: "sdk" | "cli" = "sdk",
protectedRoots: readonly string[] = [],
sourceRoots: DocumentRoots = [],
): Promise<ScanSeverityClassification> {
const { contract, scanDirectory } = await loadContractWithScanDirectory(
requestedDirectory,
{
pluginRoot: await bundledPluginRoot(),
expectedScanId: options.expectedScanId,
signal: options.signal,
},
);
const findings = selectClassificationFindings(
contract.findings.findings,
options.findingIds,
);
const store = new SeverityStore(
options.environment ?? process.env,
scanDirectory,
options.signal,
protectedRoots,
);
const result: ScanSeverityClassification = {
...(await classifySeverityInternal(
findings,
options,
surface,
store.checkpoint(
contract.manifest.scan.id,
findings.map(({ findingId }) => findingId),
options.reprocess ?? false,
),
sourceRoots && [scanDirectory, ...sourceRoots],
)),
scanId: contract.manifest.scan.id,
};
options.signal?.throwIfAborted();
const temporary = join(
scanDirectory,
`.severity-classification-${randomUUID()}.json`,
);
try {
await writeFile(temporary, `${JSON.stringify(result, null, 2)}\n`, {
flag: "wx",
mode: 0o600,
signal: options.signal,
});
options.signal?.throwIfAborted();
await rename(temporary, join(scanDirectory, CLASSIFICATION_FILE));
} finally {
await rm(temporary, { force: true });
}
return result;
}
/** @internal */
export function selectClassificationFindings(
findings: readonly Finding[],
findingIds?: readonly string[],
): readonly Finding[] {
if (findingIds === undefined) return findings;
const selected = new Set(findingIds);
const result = findings.filter((finding) => selected.has(finding.findingId));
if (result.length !== selected.size) {
throw new CodexSecurityError(
"Selected finding IDs must belong to the supplied scan.",
);
}
return result;
}
/** @internal */
export async function readScanSeverityClassification(
scanDirectory: string,
scanId: string,
findings: readonly Finding[],
signal?: AbortSignal,
environment: NodeJS.ProcessEnv = process.env,
): Promise<SeverityClassification | undefined> {
const classification = await new SeverityStore(
environment,
scanDirectory,
signal,
).read(scanId);
return classification === undefined
? undefined
: validateSeverityClassification(classification, findings);
}