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 { hash } from "node:crypto";
import {
getDefaultSeverityRubric,
type SeverityRubricSnapshot,
} from "./severity-rubric.js";
import { findingEntry } from "./value.js";
import { z } from "zod";
import { CodexSecurityError } from "./errors.js";
import { workflowDigest } from "./finding-workflow.js";
import { readKnowledgeBaseSnapshot } from "./knowledge-base.js";
import type { DocumentRoots } from "./prompt-files.js";
import type { Finding } from "./models.js";
import {
runReadOnlyCodex,
type ReadOnlyCodexOptions,
} from "./scan-comparison.js";
import {
severityDecisionSchema as decisionSchema,
severityReviewInstructions,
parseSeverityDecision,
reviewSeverity,
classificationRunsSchema,
reviewRunsOption,
} from "./severity-review.js";
import { CODEX_SECURITY_THREAD_SOURCES } from "./thread-source.js";
/** Full reports and explicitly supplied context from any finding source. */
export type SeverityClassificationFinding = Pick<
Finding,
"findingId" | "title" | "summary"
> &
Partial<Pick<Finding, "occurrenceId" | "severity">> &
Record<string, unknown>;
export interface ClassifySeverityOptions extends Pick<
ReadOnlyCodexOptions,
| "config"
| "environment"
| "model"
| "reasoningEffort"
| "signal"
| "workingDirectory"
> {
/** Overrides both the bundled default and the optional remote default. */
rubricPath?: string;
/** Independent reviews per finding: integer 1–10, default 3. */
classificationRuns?: number;
/** Supporting evidence, separate from classification policy. */
knowledgeBasePaths?: readonly string[];
/** @internal Test client for the shared read-only runtime. */
codex?: ReadOnlyCodexOptions["codex"];
}
export interface SeverityAssessment extends z.infer<typeof decisionSchema> {
occurrenceId: string | null;
inputSha256: string;
source: "existing-severity" | "rubric";
}
export interface SeverityClassification {
schemaVersion: 1;
assessedAt: string;
/** Absent on legacy results whose review count was not recorded. */
classificationRuns?: number;
/** SHA-256 of the exact policy text, or the ordered document digest for collections and legacy results. */
rubricSha256: string | null;
/** Revision of the bundled or remote rubric. Unversioned file inputs and legacy results omit it. */
rubricRevision?: number;
knowledgeBaseSha256: string | null;
assessments: SeverityAssessment[];
}
/** @internal Document collections retain their original checkpoint key. */
export type SeverityClassificationBinding = Omit<
SeverityClassification,
"assessments"
> & {
rubricCheckpointSha256: string | null;
};
/** @internal Per-finding persistence used by saved-scan classification. */
export interface SeverityClassificationCheckpoint {
load(binding: SeverityClassificationBinding): Promise<SeverityAssessment[]>;
save(
finding: SeverityClassificationFinding,
assessment: SeverityAssessment,
binding: SeverityClassificationBinding,
): Promise<void>;
}
const textSchema = z
.string()
.min(1)
.refine((value) => value.trim().length > 0);
const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
/** @internal */
export const severityClassificationSchema = z.strictObject({
schemaVersion: z.literal(1),
assessedAt: z.string().datetime(),
classificationRuns: classificationRunsSchema.optional(),
rubricSha256: digestSchema.nullable(),
rubricRevision: z.number().int().positive().optional(),
knowledgeBaseSha256: digestSchema.nullable(),
assessments: z.array(
decisionSchema.extend({
occurrenceId: textSchema.nullable(),
inputSha256: digestSchema,
source: z.enum(["existing-severity", "rubric"]),
}),
),
}) satisfies z.ZodType<SeverityClassification>;
/** Classify each supplied report independently, without scanning or writing findings. */
export async function classifySeverity(
findings: readonly SeverityClassificationFinding[],
options: ClassifySeverityOptions = {},
): Promise<SeverityClassification> {
return classifySeverityInternal(findings, options);
}
/** @internal */
export async function classifySeverityInternal(
findings: readonly SeverityClassificationFinding[],
options: ClassifySeverityOptions = {},
surface: "sdk" | "cli" = "sdk",
checkpoint?: SeverityClassificationCheckpoint,
roots?: DocumentRoots,
): Promise<SeverityClassification> {
options.signal?.throwIfAborted();
const classificationRuns = reviewRunsOption.parse(options.classificationRuns);
const ids = new Set<string>();
for (const finding of findings) {
if (!finding.findingId?.trim() || ids.has(finding.findingId)) {
throw new CodexSecurityError(
"Severity classification requires unique finding IDs.",
);
}
ids.add(finding.findingId);
}
let rubric: string[];
let defaultRubric: SeverityRubricSnapshot | undefined;
if (options.rubricPath === undefined) {
defaultRubric = await getDefaultSeverityRubric(options);
rubric = [defaultRubric.markdown];
} else {
rubric = await readDocuments([options.rubricPath], options.signal, roots);
}
const knowledge = options.knowledgeBasePaths?.length
? await readDocuments(options.knowledgeBasePaths, options.signal, roots)
: null;
const rubricCheckpointSha256 = workflowDigest(rubric);
const metadata = {
schemaVersion: 1 as const,
classificationRuns,
assessedAt: new Date().toISOString(),
...(defaultRubric
? {
rubricSha256: defaultRubric.sha256,
rubricRevision: defaultRubric.revision,
}
: {
rubricSha256:
rubric.length === 1
? hash("sha256", rubric[0]!)
: rubricCheckpointSha256,
}),
knowledgeBaseSha256: knowledge === null ? null : workflowDigest(knowledge),
};
const result: SeverityClassification = { ...metadata, assessments: [] };
const binding = { ...metadata, rubricCheckpointSha256 };
const cached = new Map((await checkpoint?.load(binding))?.map(findingEntry));
for (const finding of findings) {
options.signal?.throwIfAborted();
const inputSha256 = workflowDigest(finding);
const previous = cached.get(finding.findingId);
if (previous?.inputSha256 === inputSha256) {
validateSeverityClassification({ ...result, assessments: [previous] }, [
finding,
]);
result.assessments.push(previous);
continue;
}
const prompt = [
severityReviewInstructions,
JSON.stringify({ rubric, knowledgeBase: knowledge, finding }),
].join("\n\n");
const decision = await reviewSeverity(async () => {
options.signal?.throwIfAborted();
const response = await runReadOnlyCodex(
prompt,
z.toJSONSchema(decisionSchema),
options,
{
surface,
command: "classify-severity",
threadSource: CODEX_SECURITY_THREAD_SOURCES.severityClassification,
},
);
options.signal?.throwIfAborted();
try {
return parseSeverityDecision(JSON.parse(response), finding.findingId);
} catch (error) {
throw new CodexSecurityError(
"Severity classification returned an invalid assessment.",
{ cause: error },
);
}
}, classificationRuns);
options.signal?.throwIfAborted();
const assessment: SeverityAssessment = {
...decision,
occurrenceId: finding.occurrenceId ?? null,
inputSha256,
source: "rubric",
};
await checkpoint?.save(finding, assessment, binding);
result.assessments.push(assessment);
}
options.signal?.throwIfAborted();
return result;
}
async function readDocuments(
paths: readonly string[],
signal?: AbortSignal,
roots?: DocumentRoots,
): Promise<string[]> {
const { documents } = await readKnowledgeBaseSnapshot(paths, signal, roots);
const contents = Object.keys(documents)
.sort()
.map((name) => documents[name]!);
if (contents.every((text) => !text.trim())) {
throw new CodexSecurityError("Classification documents must not be empty.");
}
return contents;
}
/** @internal Check parsed assessments against the actual finding evidence. */
export function validateSeverityClassification(
result: SeverityClassification,
findings: readonly SeverityClassificationFinding[],
): SeverityClassification {
const byId = new Map(findings.map(findingEntry));
for (const assessment of result.assessments) {
const finding = byId.get(assessment.findingId);
if (
!finding ||
assessment.occurrenceId !== (finding.occurrenceId ?? null) ||
assessment.inputSha256 !== workflowDigest(finding) ||
(assessment.source === "rubric") !== (result.rubricSha256 !== null) ||
(assessment.decision === "assessed"
? assessment.level === null
: assessment.level !== null) ||
(assessment.source === "rubric" &&
(assessment.decision === "assessed"
? assessment.rubricLabel === null
: assessment.rubricLabel !== null)) ||
(assessment.source === "existing-severity" &&
(assessment.decision !== "assessed" ||
assessment.level !== finding.severity?.level))
) {
throw new CodexSecurityError(
"Severity assessment does not match the supplied findings. Classify the findings again.",
);
}
byId.delete(assessment.findingId);
}
return result;
}