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

12.6 KB
Raw Blame
import { hash } from "node:crypto";
import { isDeepStrictEqual } from "node:util";
import {
  readScanFile,
  safeScopePath,
  validatedFileDigests,
} from "./contract.js";
import { isRecord } from "./record.js";
import { VERSION } from "./version.js";
import {
  hostedScanFailureStatus,
  ScanExecutionError,
  type ScanExecutor,
  type ScanExecutionResult,
  type ScanExecutionEvent,
  type ScanExecutionRequest,
} from "./scan-executor.js";
export type { ScanExecutor, ScanExecutionRequest } from "./scan-executor.js";
import { realpath } from "node:fs/promises";
import { isAbsolute, relative, resolve, sep } from "node:path";
import { z } from "zod";
import { CodexSecurity, type CodexSecuritySurface } from "./api.js";
import { severityRubricSnapshotSchema } from "./classify-severity-records.js";
import { errorMessage } from "./errors.js";
import {
  abortable,
  normalizeRepository,
  repositoryRevision,
} from "./targets.js";
import { isWithin } from "./trusted-executable.js";

/** Hosted v2 mirrors repository/paths targets; only Standard scans are supported. */
export const HostedScanInputSchema = z.strictObject({
  version: z.literal(2),
  repository: z.string().min(1),
  revision: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/),
  scope: z
    .strictObject({ paths: z.array(z.string().min(1)).min(1) })
    .optional(),
  outputDirectory: z.string().min(1),
  stateDirectory: z.string().min(1),
  model: z.string().min(1),
  reasoningEffort: z.string(),
  severityRubric: severityRubricSnapshotSchema
    .refine(
      ({ markdown, sha256 }) => hash("sha256", markdown) === sha256,
      "Rubric SHA-256 does not match its exact UTF-8 Markdown.",
    )
    .optional(),
  ownerSuggestions: z.boolean().optional(),
  identity: z.strictObject({
    runId: z.string().min(1),
    attemptId: z.string().min(1),
    buildId: z.string().min(1),
  }),
});

export type HostedScanInput = z.infer<typeof HostedScanInputSchema>;
export class HostedScanPreparationError extends Error {
  constructor(
    readonly reason:
      | "scope_syntax"
      | "scope_missing"
      | "scope_outside_repository"
      | "scope_alias"
      | "revision_mismatch",
    message: string,
  ) {
    super(message);
    this.name = "HostedScanPreparationError";
  }
}

export function normalizeHostedScope(path: string): string {
  const parts = path.split(process.platform === "win32" ? /[/\\]/ : "/");
  if (
    path.length === 0 ||
    path.includes("\0") ||
    isAbsolute(path) ||
    (process.platform === "win32" && /^[a-z]:/i.test(path)) ||
    parts.includes("..")
  ) {
    throw new HostedScanPreparationError(
      "scope_syntax",
      "Use non-empty repository-relative folders or files without parent traversal or NUL characters.",
    );
  }
  const normalized = parts
    .filter((part) => part !== "" && part !== ".")
    .join("/");
  try {
    return safeScopePath(normalized || ".");
  } catch {
    throw new HostedScanPreparationError(
      "scope_syntax",
      `${JSON.stringify(path)} cannot be used as scan scope: the output contract requires UTF-8 repository-relative paths without drive prefixes, backslashes, or control characters.`,
    );
  }
}

function comparePaths(left: string, right: string): number {
  return Buffer.compare(Buffer.from(left), Buffer.from(right));
}

export function normalizeHostedPaths(
  paths: readonly string[] = ["."],
): string[] {
  if (paths.length === 0)
    throw new HostedScanPreparationError(
      "scope_syntax",
      "An explicit path scope must not be empty. Omit scope to scan the repository.",
    );
  const normalized = [...new Set(paths.map(normalizeHostedScope))].sort(
    comparePaths,
  );
  if (normalized.length > 1 && normalized.includes("."))
    throw new HostedScanPreparationError(
      "scope_syntax",
      "Repository scope cannot be mixed with narrower paths.",
    );
  return normalized;
}

/** Validate every path at the frozen commit before registering a scan/executing. */
async function prepareHostedRepository(
  input: Pick<ScanExecutionRequest, "repository" | "revision" | "scope">,
  signal?: AbortSignal,
) {
  const repository = await normalizeRepository(input.repository, signal);
  if ((await repositoryRevision(repository, signal)) !== input.revision)
    throw new HostedScanPreparationError(
      "revision_mismatch",
      "Checkout does not match the frozen revision.",
    );
  for (const path of input.scope.paths) {
    const selected = resolve(repository, path);
    let target: string;
    try {
      target = await abortable(() => realpath(selected), signal);
    } catch (error) {
      if (
        (signal?.aborted && error === signal.reason) ||
        !(error instanceof Error) ||
        !("code" in error) ||
        error.code !== "ENOENT"
      )
        throw error;
      throw new HostedScanPreparationError(
        "scope_missing",
        `${path} does not exist at the selected revision. Update the paths and start a new scan.`,
      );
    }
    if (!isWithin(repository, target))
      throw new HostedScanPreparationError(
        "scope_outside_repository",
        `${path} resolves outside the repository.`,
      );
    if (target !== selected) {
      const canonical =
        relative(repository, target).split(sep).join("/") || ".";
      throw new HostedScanPreparationError(
        "scope_alias",
        `${path} resolves to ${canonical}. Use the canonical repository path and start a new scan.`,
      );
    }
  }
  return repository;
}

function hostedScanEnvironment(stateDirectory: string): Record<string, string> {
  const environment: Record<string, string> = {
    PATH: process.env["PATH"] ?? "",
    CODEX_SECURITY_STATE_DIR: resolve(stateDirectory),
  };
  for (const key of [
    "SYSTEMROOT",
    "WINDIR",
    "PATHEXT",
    "TMPDIR",
    "TEMP",
    "TMP",
  ])
    if (process.env[key] !== undefined) environment[key] = process.env[key]!;
  return environment;
}

export interface HostedScanOptions {
  executor: ScanExecutor;
  /** @deprecated Automatic owner reports validate scan hints without additional inference. */
  ownerCodex?: {
    startThread(options: { model?: string; modelReasoningEffort?: string }): {
      run(
        input: string,
        options: { outputSchema?: unknown; signal?: AbortSignal },
      ): Promise<{ finalResponse: string }>;
    };
  };
  signal?: AbortSignal;
  onEvent?: (event: ScanExecutionEvent) => void;
}

/** One invocation, with only scan-domain state. The host decides retry/reconciliation. */
export function runHostedScan(
  value: HostedScanInput,
  options: HostedScanOptions,
) {
  return runHostedScanInternal("sdk", value, options);
}

/** @internal */
export async function runHostedScanInternal(
  surface: CodexSecuritySurface,
  value: HostedScanInput,
  options: HostedScanOptions,
) {
  const input = HostedScanInputSchema.parse(value);
  const context = {
    repository: input.repository,
    revision: input.revision,
    scope: { paths: normalizeHostedPaths(input.scope?.paths) },
    identity: input.identity,
    ...(input.severityRubric === undefined
      ? {}
      : { severityRubric: input.severityRubric }),
  };
  let execution: ScanExecutionResult | undefined;
  let request: ScanExecutionRequest | undefined;
  let scanId: string | undefined;
  let stoppedStatus: "canceled" | "failed" | undefined;
  let outputDirectory = resolve(input.outputDirectory);
  const base = () => ({
    version: 2 as const,
    ...context,
    outputDirectory,
    ...(scanId === undefined ? {} : { scanId }),
    ...(request === undefined
      ? {}
      : {
          pluginVersion: request.runtime.pluginVersion,
        }),
    provenance: {
      cliVersion: VERSION,
      buildId: input.identity.buildId,
      ...(request === undefined
        ? {}
        : { pluginVersion: request.runtime.pluginVersion }),
    },
    ...(execution === undefined ? {} : { execution }),
  });
  try {
    context.repository = await prepareHostedRepository(context, options.signal);
  } catch (error) {
    if (
      options.signal?.aborted &&
      (Object.is(error, options.signal.reason) ||
        (error instanceof DOMException && error.name === "AbortError"))
    )
      return {
        ...base(),
        status: "canceled" as const,
        error: `Canceled before checkout verification finished: ${errorMessage(error)}`,
        artifacts: [],
      };
    throw error;
  }
  const onEvent = (event: ScanExecutionEvent): void => {
    void Promise.resolve()
      .then(() => options.onEvent?.(event))
      .catch(() => {});
  };
  const client = new CodexSecurity(
    {
      codexOverrides: {
        model: input.model,
        model_reasoning_effort: input.reasoningEffort,
      },
    },
    {
      environment: hostedScanEnvironment(input.stateDirectory),
      hostedScan: {
        context,
        executor: {
          async run(value, runOptions) {
            request = value;
            execution = await options.executor.run(value, runOptions);
            return execution;
          },
        },
        onEvent,
      },
      createCodex() {
        throw new Error("Local inference is unavailable in hosted mode.");
      },
    },
    { surface },
  );
  try {
    const result = await client.run(context.repository, {
      target:
        context.scope.paths[0] === "."
          ? "repository"
          : context.scope.paths.map((path) => `./${path}`),
      mode: "standard",
      outputDir: outputDirectory,
      signal: options.signal,
      ownerSuggestions: input.ownerSuggestions,
      onOutputDirReady(path) {
        outputDirectory = path;
      },
      onScanRegistered(scan) {
        scanId = scan.scanId;
        outputDirectory = scan.scanDir;
      },
      onLifecycle(scan) {
        if (scan.status === "canceled" || scan.status === "failed")
          stoppedStatus = scan.status;
      },
      onProgress(progress) {
        onEvent({ type: "progress", progress });
      },
      onActivity(activity) {
        onEvent({ type: "activity", activity });
      },
    });
    if (
      result.manifest.scan.target.revision !== context.revision ||
      // Owner cancellation cannot invalidate an already sealed base scan.
      (await repositoryRevision(context.repository)) !== context.revision
    )
      throw new Error(
        "Checkout changed from the frozen revision during execution.",
      );
    if (
      !isDeepStrictEqual(
        [...result.manifest.scan.scope.includePaths].sort(comparePaths),
        context.scope.paths,
      ) ||
      result.manifest.scan.scope.excludePaths.length !== 0
    )
      throw new Error("Completed artifacts do not match the requested scope.");
    const sources = result.manifest.scan["preservedSources"];
    const sealedDigests = validatedFileDigests.get(result.manifest)!;
    const names = new Set([
      "scan-manifest.json",
      "findings.json",
      "report.md",
      ...result.manifest.scan.artifacts.map(({ path }) => path),
      ...(isRecord(sources) ? Object.keys(sources) : []),
    ]);
    if (result.ownerSuggestionsPath !== undefined)
      names.add("owner-suggestions.json");
    const artifacts = await Promise.all(
      [...names].sort().map(async (path) => {
        const contents = await readScanFile(outputDirectory, path, path);
        return {
          path,
          sha256: hash("sha256", contents),
          bytes: contents.byteLength,
        };
      }),
    );
    // Report a seal mismatch after the concurrent reads have closed their files.
    for (const { path, sha256 } of artifacts) {
      const expected = sealedDigests.get(path);
      if (expected !== undefined && expected !== sha256) {
        throw new Error(
          `The sealed file ${path} changed before the hosted receipt was created.`,
        );
      }
    }
    return {
      ...base(),
      status: "completed" as const,
      ...(result.ownerSuggestionsError === undefined
        ? {}
        : { ownerSuggestionsError: result.ownerSuggestionsError }),
      artifacts,
    };
  } catch (error) {
    if (error instanceof ScanExecutionError) execution = error.result;
    const status = hostedScanFailureStatus(error, options.signal, execution);
    return {
      ...base(),
      // A late abort during cleanup cannot change an already committed failure.
      status:
        status === "acceptance_unknown" ? status : (stoppedStatus ?? status),
      error: errorMessage(error),
      artifacts: [],
    };
  } finally {
    try {
      await client.close();
    } catch (error) {
      onEvent({
        type: "activity",
        activity: {
          id: "runtime.cleanup",
          kind: "message",
          status: "failed",
          description: `Hosted scan cleanup failed: ${errorMessage(error)}`,
          paths: [],
        },
      });
    }
  }
}

export type HostedScanResult = Awaited<ReturnType<typeof runHostedScan>>;