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 { constants } from 'node:fs';
import { lstat, open, realpath } from 'node:fs/promises';
import { join, resolve } from 'node:path';
import { isRecord, safeSourcePath, assertSafeSarif } from './sarif.ts';
export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'informational';
export type ScanStatus = 'completed' | 'failed' | 'skipped';
export type PolicyStatus = 'passed' | 'failed' | 'not-evaluated';
export type ReportStatus = 'ready' | 'partial' | 'failed';
export interface Finding {
severity: Severity;
title: string;
summary: string;
path?: string;
startLine?: number;
endLine?: number;
}
export interface ResultOptions {
stdout: string;
resultsDirectory: string;
scannedSha: string;
exitCode: number | null;
executionFailed?: boolean;
publishable: boolean;
}
export interface ResultPaths {
resultsDirectory: string;
manifestPath: string;
jsonPath: string;
coveragePath: string;
sarifPath: string;
}
export interface ScanResults {
scanStatus: ScanStatus;
policyStatus: PolicyStatus;
reportStatus: ReportStatus;
findings: Finding[];
scopeLimitations?: string[];
counts?: Record<Severity, number>;
usage?: { input_tokens: number; cached_input_tokens: number; output_tokens: number };
estimatedCost?: number;
estimatedCostRange?: { min: number; max: number | null };
paths: ResultPaths;
errors: string[];
sarifUploadReady: boolean;
}
const REPORT_FILES = new Set(['scan-manifest.json', 'findings.json', 'coverage.json', 'exports/results.sarif']);
/** Access only owned report files after the scanner exits; never follow links. */
async function processReportFile(root: string, name: string, adapt?: (bytes: Buffer) => Buffer): Promise<Buffer> {
if (!REPORT_FILES.has(name)) throw new Error('Unsupported report filename.');
const absoluteRoot = resolve(root);
if (await realpath(absoluteRoot) !== absoluteRoot) throw new Error('Report root must be canonical and cannot contain symlinks.');
const rootInfo = await lstat(absoluteRoot);
if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) throw new Error('Report root is not a directory.');
const components = name.split('/');
let directory = absoluteRoot;
for (const part of components.slice(0, -1)) {
directory = join(directory, part);
const info = await lstat(directory);
if (!info.isDirectory() || info.isSymbolicLink() || await realpath(directory) !== directory) throw new Error('Report directory contains a symlink or non-directory.');
}
const path = join(absoluteRoot, name);
const before = await lstat(path);
if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) throw new Error('Report must be a regular file without links.');
const file = await open(path, (adapt ? constants.O_RDWR : constants.O_RDONLY) | constants.O_NOFOLLOW | constants.O_NONBLOCK);
try {
const opened = await file.stat();
if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== before.dev || opened.ino !== before.ino) throw new Error('Report changed while opening.');
const bytes = await file.readFile();
const after = await file.stat();
if (bytes.length !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs ||
await realpath(path) !== path) throw new Error('Report changed while reading.');
const prepared = adapt ? adapt(bytes) : bytes;
if (!prepared.equals(bytes)) {
let offset = 0;
while (offset < prepared.length) {
const { bytesWritten } = await file.write(prepared, offset, prepared.length - offset, offset);
if (!bytesWritten) throw new Error('Report could not be rewritten.');
offset += bytesWritten;
}
await file.truncate(prepared.length);
}
return prepared;
} finally { await file.close(); }
}
export async function readReportFile(root: string, name: string): Promise<Buffer> {
return processReportFile(root, name);
}
async function prepareSarif(root: string): Promise<void> {
await processReportFile(root, 'exports/results.sarif', (bytes) => {
const sarif: unknown = JSON.parse(bytes.toString('utf8'));
assertSafeSarif(sarif);
// upload-sarif applies its category only when automationDetails is absent.
// The CLI's scan UUID must not override the workflow's stable scope category.
if (isRecord(sarif) && Array.isArray(sarif.runs)) {
for (const run of sarif.runs) if (isRecord(run)) delete run.automationDetails;
}
return Buffer.from(JSON.stringify(sarif));
});
}
// Consume only the fields needed for GitHub reporting. The CLI owns the report contract.
export async function analyzeResults(options: ResultOptions): Promise<ScanResults> {
const result: ScanResults = { scanStatus: 'failed', policyStatus: 'not-evaluated', reportStatus: 'failed', findings: [],
paths: { resultsDirectory: '', manifestPath: '', jsonPath: '', coveragePath: '', sarifPath: '' }, errors: [],
sarifUploadReady: false };
let value: any;
try {
value = JSON.parse(options.stdout);
if (isRecord(value) && value.status === 'failed' && typeof value.message === 'string') {
result.errors.push(value.message);
return result;
}
if (!value?.manifest?.scan?.target || !Array.isArray(value?.findings?.findings) || !(value?.review ?? value?.coverage))
throw new Error();
} catch {
result.errors.push('CLI did not return a usable JSON scan result. See the CLI diagnostics.');
return result;
}
if (value.scanDir !== options.resultsDirectory) {
result.errors.push('CLI report directory does not match the private output directory.');
return result;
}
const target = value.manifest.scan.target;
const revision = target.kind === 'git_diff' ? target.headRevision : target.kind === 'git_revision' ? target.revision : undefined;
if (revision !== options.scannedSha) {
result.errors.push('CLI scan revision does not match the requested checkout commit.');
return result;
}
try {
result.findings = value.findings.findings.map((finding: any): Finding => {
const location = finding.locations.find((item: any) => item.role === 'root_control') ?? finding.locations[0];
if (location && (!safeSourcePath(location.path) || !Number.isSafeInteger(location.startLine) || location.startLine < 1 ||
(location.endLine !== undefined && (!Number.isSafeInteger(location.endLine) || location.endLine < location.startLine))))
throw new Error('CLI finding has an unsafe source location for GitHub annotations.');
return {title: finding.title, summary: finding.summary, severity: finding.severity.level as Severity,
path: location?.path, startLine: location?.startLine, endLine: location?.endLine ?? location?.startLine};
});
} catch (error) {
result.errors.push((error as Error).message);
return result;
}
const limitations = value.manifest.scan.scope?.limitations;
if (Array.isArray(limitations)) result.scopeLimitations = limitations.filter((item: unknown) => typeof item === 'string');
result.counts = { critical: 0, high: 0, medium: 0, low: 0, informational: 0 };
for (const finding of result.findings) result.counts[finding.severity] += 1;
const usage = value.turn?.usage;
result.usage = usage == null ? undefined : {...usage, cached_input_tokens: usage.cached_input_tokens ?? 0};
result.estimatedCost = value.cost?.estimatedUsd;
result.estimatedCostRange = value.cost?.estimatedUsdRange;
result.paths = {resultsDirectory: options.resultsDirectory, manifestPath: join(options.resultsDirectory, 'scan-manifest.json'),
jsonPath: join(options.resultsDirectory, 'findings.json'), coveragePath: value.coverage ? join(options.resultsDirectory, 'coverage.json') : '', sarifPath: ''};
const warnings: string[] = value.warnings ?? [];
// Execution and severity-policy outcomes come from the CLI, not coverage notes.
// Target-change warnings still prevent publication of a changed checkout.
if (options.executionFailed || value.manifest.scan.status !== 'completed' || warnings.length > 0 ||
(options.exitCode !== 0 && options.exitCode !== 1)) {
result.errors.push('CLI did not complete successfully. See the CLI diagnostics.');
} else {
result.scanStatus = 'completed';
result.policyStatus = options.exitCode === 1 ? 'failed' : 'passed';
}
result.errors.push(...warnings);
const sarifPath = join(options.resultsDirectory, 'exports/results.sarif');
if (value.sarifPath != null) {
try {
if (value.sarifPath !== sarifPath) throw new Error('SARIF path is outside the expected report location.');
await prepareSarif(options.resultsDirectory);
result.paths.sarifPath = sarifPath;
} catch { result.errors.push('SARIF report is missing, unsafe, or unreadable.'); }
}
result.reportStatus = result.paths.sarifPath ? 'ready' : 'partial';
result.sarifUploadReady = result.scanStatus === 'completed' && result.reportStatus === 'ready' && options.publishable;
return result;
}