Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

9.2 KB
Raw Blame
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;
}