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 { notify } from "./value.js";
import { writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { basename, join, relative, resolve, sep } from "node:path";
import {
CodexSecurity,
DEFAULT_DEPENDENCIES,
scanAuthentication,
scanCodexHome,
selectedScanEnvironment,
type CodexSecuritySurface,
type ScanAuthentication,
type ScanLifecycle,
type ScanOptions,
} from "./api.js";
import {
normalizeComponentPlan,
planComponents,
type ComponentPlan,
type ComponentPlanningOptions,
} from "./component-plan.js";
import {
hasCommandAuth,
mergedCodexConfig,
scanModelProvider,
scanProviderEnvKey,
type CodexSecurityConfig,
} from "./config.js";
import type {
ScanCost,
ScanSessionEvent,
ScanUsageMeasurement,
ScanUsageObservation,
} from "./cost.js";
import type { ScanTokenUsage } from "./cost-model.js";
import { readThreatModelPath } from "./artifact-export.js";
import {
errorMessage,
OutputDirectoryNotEmptyError,
ScanCostLimitExceededError,
} from "./errors.js";
import type { Finding } from "./models.js";
import type { ScanResult } from "./result.js";
import type { ScanActivity } from "./scan-activity.js";
import type { DeepScanProgress } from "./scan-progress.js";
import type { ScanSettings } from "./scan-settings.js";
import { BatchCostPool, batchScanBudget } from "./batch-cost.js";
import type { ScanProgress, ScanWorkerStatus } from "./worker-progress.js";
import {
matchScanFindingsInternal,
type ScanComparisonResult,
} from "./scan-comparison.js";
import { prepareOutputDir, requireOutputOutsideRepository } from "./runtime.js";
import { enclosingGitWorktreeRoot, normalizeRepository } from "./targets.js";
export interface ComponentScanOptions {
/** @internal Calling surface, inherited by planning, scans, and matching. */
surface?: CodexSecuritySurface;
repository: string;
outputDir: string;
components?: ComponentPlan["components"];
auto?: boolean;
planOnly?: boolean;
workers?: number;
maxTotalCostUsd?: number;
config?: CodexSecurityConfig;
scanOptions?: Omit<ScanSettings, "target" | "outputDir"> &
Pick<ScanOptions, "onMeasurement">;
signal?: AbortSignal;
createSecurity?: (
config: CodexSecurityConfig,
) => Pick<CodexSecurity, "run" | "close">;
planComponents?: (
repository: string,
options: ComponentPlanningOptions,
) => Promise<ComponentPlan>;
environment?: NodeJS.ProcessEnv;
/** @internal */
matchFindings?: typeof matchScanFindingsInternal;
onPlan?: (components: ComponentReceipt[]) => void;
onScanEvent?: (event: ComponentScanEvent) => void;
onComplete?: (result: ComponentScanResult) => void;
onDeduplicationStarted?: () => void;
onProgress?: (component: ComponentReceipt) => void;
}
export interface ComponentReceipt {
id: string;
name: string;
paths: string[];
maxCostUsd?: number;
status: "pending" | "started" | "completed" | "failed";
outputDir: string;
scanId?: string;
operationId?: string;
threatModelPath?: string;
findingCount?: number;
cost?: Readonly<ScanCost>;
measurement?: Readonly<ScanUsageMeasurement>;
outcome?: "completed" | "failed" | "canceled";
error?: string;
}
type ComponentScanUpdate =
| { type: "authentication"; value: ScanAuthentication }
| { type: "lifecycle"; value: ScanLifecycle }
| { type: "progress"; value: ScanProgress }
| { type: "deep-progress"; value: DeepScanProgress }
| { type: "activity"; value: ScanActivity }
| { type: "session"; value: ScanSessionEvent }
| { type: "cost"; value: Readonly<ScanCost> }
| { type: "usage"; value: Readonly<ScanTokenUsage> }
| { type: "measurement"; value: Readonly<ScanUsageMeasurement> }
| { type: "usage-observation"; value: Readonly<ScanUsageObservation> }
| { type: "workers"; value: ScanWorkerStatus }
| { type: "warning"; value: string };
export type ComponentScanEvent = ComponentScanUpdate & { componentId: string };
interface FindingSource {
componentId: string;
scanId: string;
occurrenceId: string;
scanDir: string;
}
interface CombinedFinding {
finding: Finding;
sources: FindingSource[];
}
export interface ComponentDeduplicationSummary {
status: "completed" | "failed" | "skipped";
confirmedGroups: number;
uncertainPairs: number;
error?: string;
}
export interface ComponentScanResult {
total: number;
completed: number;
failed: number;
planPath: string;
summaryPath?: string;
findingsPath?: string;
reportPath?: string;
retryPlanPath?: string;
findingCount?: number;
sourceFindingCount?: number;
deduplication?: ComponentDeduplicationSummary;
policyFailed?: boolean;
}
export async function runComponentScans(
options: ComponentScanOptions,
): Promise<ComponentScanResult> {
const workers = options.workers ?? 4;
if (!Number.isSafeInteger(workers) || workers < 1)
throw new Error("Component workers must be a positive integer.");
if (Boolean(options.auto) === (options.components !== undefined))
throw new Error("Choose exactly one of components or automatic planning.");
if (options.auto && options.maxTotalCostUsd !== undefined)
throw new Error(
"--max-total-cost requires --component or --components-file because automatic planning calls an unmetered model.",
);
const pool =
options.planOnly || options.maxTotalCostUsd === undefined
? undefined
: new BatchCostPool(
options.maxTotalCostUsd,
options.components?.length ?? 1,
);
const budget = batchScanBudget(pool?.share, options.scanOptions ?? {});
const auth = options.scanOptions?.auth;
let environment = options.environment;
if (
(!options.planOnly || options.auto) &&
auth !== undefined &&
auth !== "auto"
) {
const source = environment ?? process.env;
const configuration = await mergedCodexConfig(
options.config ?? {},
scanCodexHome(source),
);
const provider = scanModelProvider(configuration);
const providerEnvKey = scanProviderEnvKey(configuration);
scanAuthentication(
source,
auth,
provider,
hasCommandAuth(configuration),
false,
providerEnvKey,
);
environment = selectedScanEnvironment(
source,
auth,
provider,
providerEnvKey,
configuration,
);
}
const repository = await normalizeRepository(
options.repository,
options.signal,
);
const protectedRoot =
(await enclosingGitWorktreeRoot(repository, options.signal)) ?? repository;
const output = await prepareOutputDir(
options.outputDir,
basename(repository),
undefined,
(path) => requireOutputOutsideRepository(protectedRoot, path),
).catch((error: unknown) => {
if (error instanceof OutputDirectoryNotEmptyError)
throw new OutputDirectoryNotEmptyError(error.directory, "component");
throw error;
});
const plan = await normalizeComponentPlan(
repository,
options.auto
? await (options.planComponents ?? planComponents)(repository, {
auth,
surface: options.surface ?? "sdk",
cyberAccessProgram: options.scanOptions?.cyberAccessProgram,
config: options.config,
environment,
signal: options.signal,
})
: { components: options.components },
options.signal,
);
const planPath = join(output, "components.json");
await writeJson(planPath, plan);
const base = {
total: plan.components.length,
completed: 0,
failed: 0,
planPath,
};
if (options.planOnly) return base;
const { maxCostUsd } = budget;
const receipts: ComponentReceipt[] = plan.components.map(
(component, index) => ({
...component,
id: `component-${index + 1}`,
operationId: randomUUID(),
...(maxCostUsd === undefined ? {} : { maxCostUsd }),
status: "pending",
outputDir: join(output, `component-${index + 1}`),
}),
);
notify(() => options.onPlan?.(receipts.map(copyReceipt)));
const results = new Map<string, ScanResult>();
const parentAttemptId = randomUUID();
let next = 0;
const settled = await Promise.allSettled(
Array.from({ length: Math.min(workers, receipts.length) }, async () => {
const security = (
options.createSecurity ??
((config) =>
new CodexSecurity(
config,
{
...DEFAULT_DEPENDENCIES,
environment: options.environment ?? process.env,
},
{ surface: options.surface ?? "sdk" },
))
)(options.config ?? {});
try {
while (!options.signal?.aborted) {
const receipt = receipts[next++];
if (receipt === undefined) return;
const emit = (event: ComponentScanUpdate): void =>
notify(() =>
options.onScanEvent?.({ ...event, componentId: receipt.id }),
);
const observers: ScanOptions =
options.onScanEvent === undefined
? {}
: {
onAuthentication: (value) =>
emit({ type: "authentication", value }),
onLifecycle: (value) => emit({ type: "lifecycle", value }),
onProgress: (value) => emit({ type: "progress", value }),
onDeepProgress: (value) =>
emit({ type: "deep-progress", value }),
onActivity: (value) => emit({ type: "activity", value }),
onSessionEvent: (value) => emit({ type: "session", value }),
onCost: (value) => emit({ type: "cost", value }),
onUsage: (value) => emit({ type: "usage", value }),
onUsageObservation: (value) =>
emit({ type: "usage-observation", value }),
onWorkerStatus: (value) => emit({ type: "workers", value }),
onWarning: (value) => emit({ type: "warning", value }),
};
let reservation: ReturnType<BatchCostPool["reserve"]> | undefined;
try {
reservation = pool?.reserve(maxCostUsd);
if (reservation !== undefined)
receipt.maxCostUsd = reservation.maxCostUsd;
receipt.status = "started";
notify(() => options.onProgress?.(copyReceipt(receipt)));
const result = await security.run(repository, {
...options.scanOptions,
...budget,
maxCostUsd: receipt.maxCostUsd,
...observers,
onScanRegistered: ({ scanId }) => {
receipt.scanId = scanId;
},
mode: options.scanOptions?.mode ?? "standard",
target: receipt.paths.map((path) => resolve(repository, path)),
outputDir: receipt.outputDir,
signal: options.signal,
telemetryContext: {
operationId: receipt.operationId!,
parentAttemptId,
},
onMeasurement: (measurement) => {
reservation?.record(measurement.cost);
receipt.measurement = measurement;
if (measurement.cost !== null) receipt.cost = measurement.cost;
else delete receipt.cost;
notify(() => options.scanOptions?.onMeasurement?.(measurement));
emit({ type: "measurement", value: measurement });
},
});
reservation?.record(result.cost);
if (result.manifest.scan.status !== "completed")
throw new Error(`Component scan ${result.manifest.scan.status}.`);
results.set(receipt.id, result);
receipt.scanId = result.manifest.scan.id;
receipt.findingCount = result.findings.findings.length;
if (result.cost !== null) receipt.cost = result.cost;
receipt.status = "completed";
receipt.outcome = "completed";
if (result.threatModelPath !== null)
receipt.threatModelPath = result.threatModelPath;
} catch (error) {
if (error instanceof ScanCostLimitExceededError)
reservation?.record(error.cost);
receipt.status = "failed";
receipt.outcome = options.signal?.aborted ? "canceled" : "failed";
receipt.error = errorMessage(error);
if (!options.signal?.aborted) {
const path = await readThreatModelPath(receipt.outputDir, {
pythonPath: options.config?.pythonPath,
protectedRoot,
signal: options.signal,
});
if (path !== null) receipt.threatModelPath = path;
}
}
notify(() => options.onProgress?.(copyReceipt(receipt)));
}
} finally {
await security.close();
}
}),
);
const failed = settled.find((result) => result.status === "rejected");
for (const receipt of receipts) {
if (receipt.status === "pending" || receipt.status === "started") {
receipt.status = "failed";
receipt.outcome = options.signal?.aborted ? "canceled" : "failed";
receipt.error = options.signal?.aborted
? "Scan canceled."
: "Component scan did not finish.";
notify(() => options.onProgress?.(copyReceipt(receipt)));
}
}
const { findings, matches, uncertain, related, error, skipped } =
await deduplicateFindings(receipts, results, { ...options, environment });
const deduplication: ComponentDeduplicationSummary = {
status: skipped ? "skipped" : error === undefined ? "completed" : "failed",
confirmedGroups: matches.length,
uncertainPairs: uncertain.length,
...(error === undefined ? {} : { error }),
};
const retryComponents = receipts
.filter(({ status }) => status === "failed")
.map(({ name, paths }) => ({ name, paths }));
const retryPlanPath =
retryComponents.length === 0
? undefined
: join(output, "retry-components.json");
if (retryPlanPath !== undefined)
await writeJson(retryPlanPath, { components: retryComponents });
const failureSeverity = options.scanOptions?.failureSeverity;
const summary = {
...base,
completed: receipts.filter(({ status }) => status === "completed").length,
failed: receipts.filter(({ status }) => status === "failed").length,
summaryPath: join(output, "summary.json"),
findingsPath: join(output, "findings.json"),
reportPath: join(output, "report.md"),
...(retryPlanPath === undefined ? {} : { retryPlanPath }),
findingCount: findings.length,
sourceFindingCount: findings.reduce(
(total, finding) => total + finding.sources.length,
0,
),
deduplication,
...(failureSeverity === undefined
? {}
: {
policyFailed: [...results.values()].some((result) =>
result.hasFindingsAtOrAbove(failureSeverity),
),
}),
};
await writeJson(summary.findingsPath, {
documentType: "codex-security.component-findings",
schemaVersion: "1.0",
findings,
deduplication: { ...deduplication, matches, uncertain, related },
});
await writeJson(summary.summaryPath, {
...summary,
repository,
attemptId: parentAttemptId,
components: receipts,
});
await writeFile(
summary.reportPath,
renderReport(summary, receipts, findings),
{ flag: "wx", mode: 0o600 },
);
notify(() => options.onComplete?.(summary));
options.signal?.throwIfAborted();
if (failed?.status === "rejected") throw failed.reason;
return summary;
}
async function deduplicateFindings(
receipts: ComponentReceipt[],
results: Map<string, ScanResult>,
options: ComponentScanOptions,
): Promise<
ScanComparisonResult & {
findings: CombinedFinding[];
error?: string;
skipped?: boolean;
}
> {
const scans = receipts.flatMap((receipt) => {
const findings = results.get(receipt.id)?.findings.findings ?? [];
return findings.length ? [{ receipt, findings }] : [];
});
let findings: CombinedFinding[] = scans.flatMap(({ receipt, findings }) =>
findings.map((finding) => ({
finding,
sources: [
{
componentId: receipt.id,
scanId: receipt.scanId!,
occurrenceId: finding.occurrenceId,
scanDir: receipt.outputDir,
},
],
})),
);
const matching: ScanComparisonResult = { matches: [], uncertain: [] };
const [first, ...remaining] = scans;
if (remaining.length && options.maxTotalCostUsd !== undefined)
return { ...matching, findings, skipped: true };
const componentFindings = ({
receipt,
findings,
}: (typeof scans)[number]): Finding[] =>
findings.map((finding) => ({
...finding,
findingId: `${receipt.id}:${finding.findingId}`,
}));
const previous = first === undefined ? [] : componentFindings(first);
let error: string | undefined;
try {
options.signal?.throwIfAborted();
if (remaining.length) notify(() => options.onDeduplicationStarted?.());
for (const component of remaining) {
const current = componentFindings(component);
const comparison = await (
options.matchFindings ?? matchScanFindingsInternal
)(
{ before: [...previous], after: current },
{
allowHistoricalUncertainty: true,
auth: options.scanOptions?.auth,
cyberAccessProgram: options.scanOptions?.cyberAccessProgram,
config: options.config ?? {},
environment: options.environment,
signal: options.signal,
workingDirectory: tmpdir(),
},
{ surface: options.surface ?? "sdk" },
);
matching.matches.push(...comparison.matches);
matching.uncertain.push(...comparison.uncertain);
if (comparison.related !== undefined) {
matching.related ??= [];
matching.related.push(...comparison.related);
}
for (const match of comparison.matches) {
findings = mergeFindingGroups(
findings,
new Set([...match.beforeOccurrenceIds, ...match.afterOccurrenceIds]),
);
}
previous.push(...current);
}
} catch (failure) {
error = options.signal?.aborted
? "Cross-component matching was canceled."
: errorMessage(failure);
}
const remainSeparate = ({
beforeOccurrenceId,
afterOccurrenceId,
}: ScanComparisonResult["uncertain"][number]): boolean =>
!findings.some(
({ sources }) =>
sources.some(
({ occurrenceId }) => occurrenceId === beforeOccurrenceId,
) &&
sources.some(({ occurrenceId }) => occurrenceId === afterOccurrenceId),
);
matching.uncertain = matching.uncertain.filter(remainSeparate);
if (matching.related !== undefined) {
matching.related = matching.related.filter(remainSeparate);
}
return { findings, ...matching, ...(error === undefined ? {} : { error }) };
}
function mergeFindingGroups(
findings: CombinedFinding[],
occurrenceIds: Set<string>,
): CombinedFinding[] {
const selected = findings.filter(({ sources }) =>
sources.some(({ occurrenceId }) => occurrenceIds.has(occurrenceId)),
);
if (selected.length < 2) return findings;
const merged = {
finding: selected.map(({ finding }) => finding).reduce(strongerFinding),
sources: selected.flatMap(({ sources }) => sources),
};
return findings.flatMap((group) =>
group === selected[0] ? [merged] : selected.includes(group) ? [] : [group],
);
}
function strongerFinding(first: Finding, second: Finding): Finding {
const levels = ["critical", "high", "medium", "low", "informational"];
return levels.indexOf(second.severity.level) <
levels.indexOf(first.severity.level)
? second
: first;
}
function renderReport(
summary: ComponentScanResult,
receipts: ComponentReceipt[],
findings: CombinedFinding[],
): string {
return [
"# Component scan report",
"",
`${summary.completed} complete, ${summary.failed} failed. ${findings.length} finding groups.`,
...(summary.deduplication?.status === "skipped"
? [
"",
"Cross-component matching skipped under the total cost limit. Findings are listed separately.",
]
: []),
...(summary.deduplication?.status === "failed"
? ["", `Cross-component matching failed: ${summary.deduplication.error}`]
: []),
...(summary.deduplication?.uncertainPairs
? [
"",
`${summary.deduplication.uncertainPairs} possible duplicate pairs remain separate. See findings.json.`,
]
: []),
"",
"Coverage applies only to the selected components. See each scan for exclusions and deferred work.",
...(summary.retryPlanPath === undefined
? []
: ["", "[Retry plan for failed components](./retry-components.json)"]),
"",
"## Components",
"",
...receipts.map((receipt) => {
const modelLink = receipt.threatModelPath
? ` · [Threat model](./${receipt.id}/${relative(receipt.outputDir, receipt.threatModelPath).split(sep).join("/")})`
: "";
return `- ${JSON.stringify(receipt.name)}: ${receipt.status}. [Scan files](./${receipt.id}/)${modelLink}${receipt.error ? ` — ${receipt.error}` : ""}`;
}),
"",
"## Findings",
"",
...findings.map(
({ finding, sources }) =>
`- ${finding.severity.level}: ${finding.title} (${sources.map(({ componentId }) => `[${componentId}](./${componentId}/report.md)`).join(", ")})`,
),
"",
].join("\n");
}
async function writeJson(path: string, value: unknown): Promise<void> {
await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
flag: "wx",
mode: 0o600,
});
}
function copyReceipt(receipt: ComponentReceipt): ComponentReceipt {
return { ...receipt, paths: [...receipt.paths] };
}