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

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