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

6.2 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { rename, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import {
  classifySeverityInternal,
  validateSeverityClassification,
  type ClassifySeverityOptions,
  type SeverityClassification,
} from "./classify-severity.js";
import { loadContractWithScanDirectory } from "./contract.js";
import { CodexSecurityError } from "./errors.js";
import type { Finding } from "./models.js";
import type { DocumentRoots } from "./prompt-files.js";
import { bundledPluginRoot } from "./runtime.js";
import { savedScanWorkbench } from "./saved-scan-bootstrap.js";
import {
  resolveCompletedScan,
  type SavedScanDependencies,
} from "./saved-scan.js";
import { SeverityStore } from "./severity-store.js";
import { documentSourceRoot, nullIfMissingPath } from "./targets.js";

const CLASSIFICATION_FILE = "severity-classification.json";
export interface ScanSeverityClassification extends SeverityClassification {
  scanId: string;
}

export interface ClassifyScanSeverityOptions extends ClassifySeverityOptions {
  /** Exact selection, such as dedupe's scanRepresentativeFindingIds. Omit to classify all findings. */
  findingIds?: readonly string[];
  /** Reclassify selected findings even when their saved assessment matches the inputs. */
  reprocess?: boolean;
  expectedScanId?: string;
}

/** Resolve a saved scan ID, unique prefix, or latest and save its classification. */
export async function classifyScanSeverity(
  scanId: string,
  options: ClassifyScanSeverityOptions = {},
): Promise<ScanSeverityClassification> {
  return classifyScanSeverityInternal(scanId, options);
}

/** @internal */
export async function classifyScanSeverityInternal(
  scanId: string,
  options: ClassifyScanSeverityOptions = {},
  dependencies: Partial<SavedScanDependencies> = {},
  surface: "sdk" | "cli" = "sdk",
): Promise<ScanSeverityClassification> {
  options.signal?.throwIfAborted();
  const environment = options.environment ?? process.env;
  const pluginRoot = await bundledPluginRoot();
  const currentDirectory = dependencies.currentDirectory?.() ?? process.cwd();
  const bootstrap = dependencies.runWorkbench
    ? undefined
    : await savedScanWorkbench(scanId, {
        environment,
        pluginRoot,
        currentDirectory,
        signal: options.signal,
      });
  const scan = await resolveCompletedScan(scanId, {
    currentDirectory: () => currentDirectory,
    runWorkbench: (args, input) =>
      (dependencies.runWorkbench ?? bootstrap!)(args, input, options.signal),
  });
  if (
    options.expectedScanId !== undefined &&
    options.expectedScanId !== scan.scanId
  ) {
    throw new CodexSecurityError("Saved scan does not match expectedScanId.");
  }
  const target = scan["targetPath"];
  // The workbench enables remediation only for the recorded checkout and revision.
  const sourceRoot =
    scan["remediationAvailable"] === true &&
    typeof target === "string" &&
    (options.rubricPath !== undefined || options.knowledgeBasePaths?.length)
      ? await documentSourceRoot(target, options.signal).catch(
          nullIfMissingPath,
        )
      : null;
  return classifyScanDirectorySeverityInternal(
    scan.scanDir,
    { ...options, expectedScanId: scan.scanId },
    surface,
    bootstrap?.protectedRoots,
    sourceRoot === null ? null : [sourceRoot],
  );
}

/** Classify a sealed scan directory and save a separate assessment without changing its artifacts. */
export async function classifyScanDirectorySeverity(
  scanDirectory: string,
  options: ClassifyScanSeverityOptions = {},
): Promise<ScanSeverityClassification> {
  return classifyScanDirectorySeverityInternal(scanDirectory, options);
}

/** @internal */
export async function classifyScanDirectorySeverityInternal(
  requestedDirectory: string,
  options: ClassifyScanSeverityOptions = {},
  surface: "sdk" | "cli" = "sdk",
  protectedRoots: readonly string[] = [],
  sourceRoots: DocumentRoots = [],
): Promise<ScanSeverityClassification> {
  const { contract, scanDirectory } = await loadContractWithScanDirectory(
    requestedDirectory,
    {
      pluginRoot: await bundledPluginRoot(),
      expectedScanId: options.expectedScanId,
      signal: options.signal,
    },
  );
  const findings = selectClassificationFindings(
    contract.findings.findings,
    options.findingIds,
  );
  const store = new SeverityStore(
    options.environment ?? process.env,
    scanDirectory,
    options.signal,
    protectedRoots,
  );
  const result: ScanSeverityClassification = {
    ...(await classifySeverityInternal(
      findings,
      options,
      surface,
      store.checkpoint(
        contract.manifest.scan.id,
        findings.map(({ findingId }) => findingId),
        options.reprocess ?? false,
      ),
      sourceRoots && [scanDirectory, ...sourceRoots],
    )),
    scanId: contract.manifest.scan.id,
  };
  options.signal?.throwIfAborted();
  const temporary = join(
    scanDirectory,
    `.severity-classification-${randomUUID()}.json`,
  );
  try {
    await writeFile(temporary, `${JSON.stringify(result, null, 2)}\n`, {
      flag: "wx",
      mode: 0o600,
      signal: options.signal,
    });
    options.signal?.throwIfAborted();
    await rename(temporary, join(scanDirectory, CLASSIFICATION_FILE));
  } finally {
    await rm(temporary, { force: true });
  }
  return result;
}

/** @internal */
export function selectClassificationFindings(
  findings: readonly Finding[],
  findingIds?: readonly string[],
): readonly Finding[] {
  if (findingIds === undefined) return findings;
  const selected = new Set(findingIds);
  const result = findings.filter((finding) => selected.has(finding.findingId));
  if (result.length !== selected.size) {
    throw new CodexSecurityError(
      "Selected finding IDs must belong to the supplied scan.",
    );
  }
  return result;
}

/** @internal */
export async function readScanSeverityClassification(
  scanDirectory: string,
  scanId: string,
  findings: readonly Finding[],
  signal?: AbortSignal,
  environment: NodeJS.ProcessEnv = process.env,
): Promise<SeverityClassification | undefined> {
  const classification = await new SeverityStore(
    environment,
    scanDirectory,
    signal,
  ).read(scanId);
  return classification === undefined
    ? undefined
    : validateSeverityClassification(classification, findings);
}