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 { listenForAbort } from "./cli-signals.js";
import type { CodexSecurity, ScanAuthMode } from "./api.js";
import type { BulkScanPrompt } from "./bulk-scan-discovery.js";
import type { CodexSecurityConfig } from "./config.js";
import { formatScanCost } from "./cost-model.js";
import { errorMessage } from "./errors.js";
import {
formatSecurityPolicyText as display,
type SecurityPolicyOptions,
type SecurityPolicyStage,
} from "./security-policy.js";
type SignalName = "SIGINT" | "SIGTERM";
type Output = { write(value: string): unknown };
export type PolicyPrompt = Pick<BulkScanPrompt, "isInteractive" | "input">;
export type PolicySecurity = Pick<
CodexSecurity,
"generatePolicy" | "preflightPolicy" | "previewPolicy" | "close"
>;
export interface PolicyCommandOptions {
repository: string;
config: CodexSecurityConfig;
generation: SecurityPolicyOptions;
headless: boolean;
dryRun: boolean;
format: string;
explicitOutput: boolean;
}
export interface PolicyCommandDependencies {
createSecurity(config: CodexSecurityConfig): PolicySecurity;
chooseAuthentication(
config: CodexSecurityConfig,
auth: ScanAuthMode | undefined,
signal: AbortSignal,
): Promise<ScanAuthMode | undefined>;
prompt: PolicyPrompt;
environment: NodeJS.ProcessEnv;
errorOutput: Output;
now(): number;
addSignalListener(signal: SignalName, listener: () => void): void;
removeSignalListener(signal: SignalName, listener: () => void): void;
forceExit(signal: SignalName): void;
}
const STAGES: Record<SecurityPolicyStage, string> = {
architecture: "[1/3] Reading the source",
threat_model: "[2/3] Writing the threat model",
policy: "[3/3] Drafting SECURITY.md",
};
export async function runPolicyCommand(
options: PolicyCommandOptions,
dependencies: PolicyCommandDependencies,
): Promise<{
exitCode: number;
data?: Record<string, unknown>;
markdown?: string;
error?: string;
}> {
const { errorOutput, prompt } = dependencies;
const controller = new AbortController();
const interactive =
!options.headless &&
options.format === "toon" &&
dependencies.environment["CI"] === undefined &&
prompt.isInteractive();
const started = dependencies.now();
let security: PolicySecurity | undefined;
let outputDir: string | undefined;
const write = (message: string): void => {
try {
errorOutput.write(`${message}\n`);
} catch {}
};
const removeSignalListeners = listenForAbort(
dependencies,
controller,
(signal) => dependencies.forceExit(signal),
);
try {
const auth =
interactive && !options.dryRun
? await dependencies.chooseAuthentication(
options.config,
options.generation.auth,
controller.signal,
)
: options.generation.auth;
controller.signal.throwIfAborted();
security = dependencies.createSecurity(options.config);
if (options.dryRun) {
const preflight = await security.preflightPolicy(options.repository, {
...options.generation,
signal: controller.signal,
});
controller.signal.throwIfAborted();
return {
exitCode: 0,
data: {
...preflight,
dryRun: true,
},
};
}
const draft = await security.generatePolicy(options.repository, {
...options.generation,
auth,
signal: controller.signal,
onOutputDirReady: (directory) => {
outputDir = directory;
write(`Policy artifacts: ${display(directory)}`);
},
onStage: (stage) => write(STAGES[stage]),
onWarning: (warning) =>
write(`codex-security: ${display(errorMessage(warning))}`),
...(interactive
? {
answerQuestions: async (
questions: readonly string[],
signal: AbortSignal,
) => {
write(
"Answer what you know; leave other answers blank for later review.",
);
const answers: string[] = [];
for (const question of questions) {
signal.throwIfAborted();
const answer = await prompt.input(
display(question),
undefined,
signal,
);
if (answer.trim()) answers.push(`${question}\n${answer}`);
}
return answers.join("\n\n");
},
}
: {}),
});
controller.signal.throwIfAborted();
const cost = draft.cost;
const changed = draft.previousContent !== draft.content;
const humanOutput = options.format === "toon" && !options.explicitOutput;
if (humanOutput) {
let diff: string;
try {
diff = await security.previewPolicy(draft, {
signal: controller.signal,
});
} catch (error) {
controller.signal.throwIfAborted();
diff = "Preview unavailable. Review the saved draft.";
write(
`codex-security: Could not preview the policy: ${display(errorMessage(error))}`,
);
}
const preview = [
`\nPolicy target: ${display(draft.targetPath)}`,
diff.replace(/\n$/u, "") || "SECURITY.md is already up to date.",
...(draft.reviewNotes.length === 0
? []
: [
"\nReview notes:",
...draft.reviewNotes.map((note) => `- ${display(note)}`),
]),
].join("\n");
write(preview);
}
controller.signal.throwIfAborted();
const status = changed ? "draft" : "unchanged";
if (humanOutput) {
write(`\nDraft: ${display(draft.draftPath)}`);
write(`Architecture: ${display(draft.specificationPath)}`);
if (draft.threatModelPath !== null)
write(`Threat model: ${display(draft.threatModelPath)}`);
if (changed)
write(
"No repository files changed. Review the draft, then copy only SECURITY.md to the Policy target shown.",
);
}
const seconds = Math.max(0, (dependencies.now() - started) / 1000);
write(
`Policy generation finished in ${seconds.toFixed(1)}s${cost === null ? "" : ` (estimated cost: ${formatScanCost(cost)})`}.`,
);
return {
exitCode: 0,
markdown: draft.content,
data: {
status,
repository: draft.repository,
scope: draft.scope,
targetPath: draft.targetPath,
outputDir: draft.outputDir,
draftPath: draft.draftPath,
specificationPath: draft.specificationPath,
threatModelPath: draft.threatModelPath,
threatModel: draft.threatModel,
customPlugin: draft.customPlugin,
reviewNotes: draft.reviewNotes,
cost,
},
};
} catch (error) {
const signal =
controller.signal.reason ??
(error instanceof Error && error.name === "ExitPromptError"
? "SIGINT"
: undefined);
const exitCode = signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 2;
const message =
signal === "SIGINT"
? "Policy generation canceled by Ctrl-C."
: signal === "SIGTERM"
? "Policy generation terminated by SIGTERM."
: display(errorMessage(error));
write(`codex-security: ${message}`);
if (outputDir !== undefined)
write(`Saved artifacts: ${display(outputDir)}`);
return {
exitCode,
error: message,
};
} finally {
removeSignalListeners();
try {
await security?.close();
} catch (error) {
write(
`codex-security: Could not clean up the policy runtime: ${display(errorMessage(error))}`,
);
}
}
}
export function policyDisplayData(
data: Record<string, unknown> | undefined,
): Record<string, unknown> | undefined {
const displayValue = (value: unknown): unknown => {
if (typeof value === "string") return display(value);
if (Array.isArray(value)) return value.map(displayValue);
if (value !== null && typeof value === "object")
return Object.fromEntries(
Object.entries(value).map(([key, item]) => [key, displayValue(item)]),
);
return value;
};
return data === undefined
? undefined
: (displayValue(data) as Record<string, unknown>);
}