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

17.3 KB
Raw Blame
import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
import { realpathSync } from "node:fs";
import { join, resolve } from "node:path";
import { pathToFileURL } from "node:url";
import type { CodexOptions } from "@openai/codex-sdk";
import { parse } from "smol-toml";
import {
  nativeCodexLaunch,
  resolveBundledCodexExecutable,
} from "./codex-sdk-environment.js";
import { CodexSecurityError } from "./errors.js";
import {
  deepMerge,
  inlineToml,
  type JsonObject,
  type JsonValue,
} from "./config.js";
import { isRecord } from "./record.js";
import {
  executablePathForSpawn,
  isDisconnectedChildStdin,
  PLUGIN_NAME,
  runCodexCommand,
  type CodexCommand,
} from "./runtime.js";
import { resolveTrustedExecutable } from "./trusted-executable.js";
import {
  nativePermissionPreflight,
  nativeProfileClient,
  withCodexPreflightLock,
} from "./provider-profile.js";

export type DeepScanDiagnostic = Readonly<Record<string, string | number>>;

export interface DirectDeepScanOptions {
  onDiagnostic?: (event: DeepScanDiagnostic) => void;
  codexOptions: CodexOptions & { nativeProfile?: string };
  preflightCommand: CodexCommand;
  pluginRoot: string;
  repository: string;
  scanDir: string;
  scanId: string;
  prompt: string;
  signal: AbortSignal;
}

// The stock SDK emits one flag per leaf, including literal dotted keys in order.
function sdkConfigFlags(config: JsonObject, prefix = ""): string[] {
  return Object.entries(config).flatMap(([key, value]) => {
    const path = prefix ? `${prefix}.${key}` : key;
    return isRecord(value) && Object.keys(value).length
      ? sdkConfigFlags(value, path)
      : [`${path}=${inlineToml(value)}`];
  });
}

// An older custom launcher must start in the caller's directory. Only use
// supplied routing when its app-server cannot read the scan at startup.
function suppliedParentRouting(
  overrides: readonly string[],
): JsonObject | undefined {
  try {
    const config: JsonObject = Object.create(null);
    for (const override of overrides) {
      const equals = override.indexOf("=");
      const key = override.slice(0, equals).trim();
      if (!/^(?:features|mcp_servers)(?:\.|$)/u.test(key)) continue;
      const path = key.split(".");
      const leaf = path.pop()!;
      let table = config;
      for (const part of path) {
        const next = Object.hasOwn(table, part) ? table[part] : undefined;
        const child =
          table === config["features"] && part === "code_mode"
            ? codeModeTable(next)
            : next;
        table = table[part] = Object.assign(
          Object.create(null),
          isRecord(child) ? child : {},
        );
      }
      const value = parse(`value=${override.slice(equals + 1)}`)[
        "value"
      ] as JsonValue;
      const priorMode =
        key === "features.code_mode" ? codeModeTable(table[leaf]) : undefined;
      const newMode = priorMode && codeModeTable(value);
      table[leaf] =
        priorMode && newMode ? deepMerge({ ...priorMode }, newMode) : value;
    }
    const servers = config["mcp_servers"];
    const owner = isRecord(servers) ? servers[PLUGIN_NAME] : undefined;
    // Even a supplied transport can inherit a machine-level direct opt-out.
    if (isRecord(owner) && !Array.isArray(owner["omit_tools_from"])) return;
    return config;
  } catch {
    // Leave malformed settings for exec's own parser.
    return undefined;
  }
}

// Codex merges a structured Code Mode setting with its boolean shorthand.
function codeModeTable(value: JsonValue | undefined): JsonObject | undefined {
  if (typeof value === "boolean") return { enabled: value };
  return isRecord(value) ? value : undefined;
}

async function deepScanLaunch({
  codexOptions,
  preflightCommand: command,
}: Pick<DirectDeepScanOptions, "codexOptions" | "preflightCommand">) {
  const launch = await nativeCodexLaunch(command.command, {
    ...codexOptions.env,
    ...(codexOptions.apiKey === undefined
      ? {}
      : { CODEX_API_KEY: codexOptions.apiKey }),
  });
  return {
    command: { ...command, command: launch.command },
    environment: launch.environment!,
  };
}

/** Read the same native layers and CLI overrides as the parent before adding its tool. */
export async function readDeepScanParentConfig(
  options: Pick<
    DirectDeepScanOptions,
    "codexOptions" | "preflightCommand" | "scanDir" | "signal"
  > & {
    plugin?: { marketplacePath: string; pluginName: string };
    pluginServers?: Record<string, unknown>;
  },
): Promise<JsonObject | undefined> {
  const { codexOptions } = options;
  const config = codexOptions.config ?? {};
  // The provider-profile launcher emits whole top-level tables instead.
  const overrides =
    codexOptions.nativeProfile === undefined
      ? sdkConfigFlags(config)
      : (await nativeProfileClient()).profileConfigOverrides(config);
  const { command, environment } = await deepScanLaunch(options);
  const configOverrides = [
    ...overrides,
    ...(codexOptions.configOverrides ?? []),
  ];
  // Subcommand help does not load a project. A global --cd is ignored by
  // older app-servers, so require support on the subcommand itself.
  const help = await runCodexCommand(
    command,
    ["app-server", "--cd", options.scanDir, "--help"],
    environment,
    undefined,
    options.signal,
  );
  const supportsCd =
    help.success && /^\s*(?:-C,\s*)?--cd\s+<[^>\n]+>/mu.test(help.stdout);
  if (!supportsCd) {
    // The bundled command is the native executable itself. A custom launcher
    // can use its own working directory to resolve scripts and other inputs.
    if (
      resolve(options.scanDir) !== process.cwd() &&
      !isBundledExecutable(command.command)
    )
      return options.plugin
        ? undefined
        : suppliedParentRouting(configOverrides);
    if (environment["CODEX_HOME"])
      environment["CODEX_HOME"] = resolve(environment["CODEX_HOME"]);
  }

  const native = await nativePermissionPreflight();
  return withCodexPreflightLock(environment, options.signal, () =>
    native.readDeepScanRuntimeConfig(
      {
        codexPath: command.command,
        commandArgs: command.args,
        cwd: supportsCd ? process.cwd() : options.scanDir,
        ...(supportsCd && { configCwd: options.scanDir }),
        configOverrides,
        env: environment,
        signal: options.signal,
        context: "parent-config",
        plugin: options.plugin,
      },
      (
        config: JsonObject,
        hasEmptyCatalog: (server: string) => Promise<boolean>,
      ) => inspectFilteredPeers(config, options.pluginServers, hasEmptyCatalog),
    ),
  );
}

function isBundledExecutable(command: string): boolean {
  try {
    return (
      realpathSync.native(command) ===
      realpathSync.native(resolveBundledCodexExecutable())
    );
  } catch {
    return false; // An installation may supply only an external launcher.
  }
}

async function inspectFilteredPeers(
  config: JsonObject,
  pluginServers: Record<string, unknown> | undefined,
  hasEmptyCatalog: (server: string) => Promise<boolean>,
): Promise<JsonObject> {
  const configured = isRecord(config["mcp_servers"])
    ? config["mcp_servers"]
    : {};
  const owner = configured[PLUGIN_NAME];
  if (
    isRecord(owner) &&
    (owner["command"] ||
      owner["url"] ||
      Array.isArray(owner["omit_tools_from"]))
  )
    return config;
  const servers = { ...pluginServers, ...configured };
  const registration = servers[PLUGIN_NAME];
  if (!isRecord(registration) || registration["enabled"] === false)
    return config;
  const routing = { ...configured };
  for (const [name, settings] of Object.entries(servers)) {
    if (
      name === PLUGIN_NAME ||
      !isRecord(settings) ||
      settings["enabled"] === false ||
      !["codex_security", "mcp__codex_security"].includes(
        normalizedServerName(name),
      )
    )
      continue;
    if (
      ![settings["enabled_tools"], settings["disabled_tools"]].some(
        (tools) => Array.isArray(tools) && tools.length > 0,
      )
    )
      continue;
    if (await hasEmptyCatalog(name)) {
      // This view is used only to select a namespace. Never change the peer's config.
      routing[name] = { enabled_tools: [] };
    }
  }
  return { ...config, mcp_servers: routing };
}

function normalizedServerName(server: string): string {
  return server.replace(/[-.:@/]/gu, "_");
}

/** Keep direct dispatch scoped to the original SDK coordinator turn and MCP server. */
export function deepScanParentToolOverrides(
  config: JsonObject,
  pluginServers: Record<string, unknown>,
): string[] {
  const features = config["features"] ?? {};
  if (!isRecord(features)) return [];
  const mode = features["code_mode"];
  if (mode !== undefined && typeof mode !== "boolean" && !isRecord(mode))
    return [];
  const direct =
    (isRecord(mode) ? mode["direct_only_tool_namespaces"] : undefined) ?? [];
  if (!Array.isArray(direct)) return [];

  const owner = PLUGIN_NAME;
  const bare = "codex_security";
  const prefixed = "mcp__codex_security";
  let required = [prefixed, bare];
  const overrides: string[] = [];
  const configured = config["mcp_servers"];
  // Native registrations take precedence over the selected plugin's entries.
  const servers: Record<string, unknown> = {
    ...pluginServers,
    ...(isRecord(configured) ? configured : {}),
  };
  const ownerConfig = servers[owner];
  if (!isRecord(ownerConfig) || ownerConfig["enabled"] === false) return [];
  const omitted = ownerConfig["omit_tools_from"];
  if (Array.isArray(omitted) && omitted.includes("direct")) return [];
  // A raw transport or an existing omission leaf can be updated in place.
  // Adding a new registration would shadow a plugin's transport and policy.
  if (
    isRecord(configured) &&
    Object.hasOwn(configured, owner) &&
    (Array.isArray(omitted) ||
      typeof ownerConfig["command"] === "string" ||
      typeof ownerConfig["url"] === "string")
  ) {
    if (omitted != null && !Array.isArray(omitted)) return [];
    const surfaces = omitted ?? [];
    if (surfaces.includes("code_mode") && surfaces.includes("deferred"))
      return [];
    return [
      `mcp_servers.${owner}.omit_tools_from=${inlineToml([...new Set([...surfaces, "code_mode", "deferred"])])}`,
    ];
  }
  const option = features["non_prefixed_mcp_tool_names"];
  const enabled =
    option === true || (isRecord(option) && option["enabled"] === true);
  const selected = isRecord(option) ? option["server_names"] : undefined;
  function namespace(server: string): string {
    const name = normalizedServerName(server);
    const omitPrefix =
      enabled && (!Array.isArray(selected) || selected.includes(server));
    return omitPrefix || name.startsWith("mcp__") ? name : `mcp__${name}`;
  }
  const occupied = new Set(
    Object.entries(servers)
      .filter(
        ([server, settings]) =>
          server !== owner &&
          isRecord(settings) &&
          settings["enabled"] !== false &&
          (!Array.isArray(settings["enabled_tools"]) ||
            settings["enabled_tools"].length > 0),
      )
      .map(([server]) => namespace(server)),
  );
  const current = namespace(owner);
  if (occupied.has(current)) {
    const excluded = isRecord(mode) ? mode["excluded_tool_namespaces"] : null;
    const routed = Array.isArray(excluded) ? [...direct, ...excluded] : direct;
    // Moving the owner also renames its peers. Keep names that the caller
    // explicitly routed or excluded from Code Mode.
    if (
      current === bare ||
      occupied.has(bare) ||
      routed.some(
        (name) =>
          name === current ||
          (typeof name === "string" &&
            /^mcp__codex_security_[0-9a-f]{12}$/u.test(name)),
      ) ||
      (option != null && !enabled)
    )
      return [];
    overrides.push(
      `features.non_prefixed_mcp_tool_names=${inlineToml({
        enabled: true,
        server_names: [...(Array.isArray(selected) ? selected : []), owner],
      })}`,
    );
    required = [bare];
  } else if (occupied.has(prefixed) || occupied.has(bare)) {
    required = [current];
  }
  if (!required.every((name) => direct.includes(name))) {
    overrides.push(
      `features.code_mode.direct_only_tool_namespaces=${inlineToml([...new Set([...direct, ...required])])}`,
    );
  }
  return overrides;
}

// The direct coordinator records context but never calls a model itself.
export const DIRECT_DEEP_SCAN_CONTROL_USAGE = {
  input_tokens: 0,
  cached_input_tokens: 0,
  cache_write_input_tokens: 0,
  output_tokens: 0,
} as const;

/** Run the same coordinator as the plugin, without a parent model turn. */
export async function* runDeepScan(
  options: DirectDeepScanOptions,
): AsyncGenerator<{
  type: string;
  [key: string]: unknown;
}> {
  const native = await import(
    pathToFileURL(
      join(options.pluginRoot, "mcp", "permission-profile-preflight.mjs"),
    ).href
  );
  const profile = await import(
    pathToFileURL(join(options.pluginRoot, "scripts", "codex_profile.mjs")).href
  );
  const configured = options.codexOptions;
  const { command, environment } = await deepScanLaunch(options);
  const session = (await withCodexPreflightLock(
    environment,
    options.signal,
    () =>
      native.prepareCliDeepScanSession({
        codexPath: command.command,
        commandArgs: command.args,
        cwd: options.scanDir,
        env: environment,
        configOverrides: [
          ...profile.profileConfigOverrides(configured.config ?? {}),
          ...(configured.configOverrides ?? []),
          // This session only records native context; workers keep their own snapshot.
          "features.plugins=false",
        ],
        signal: options.signal,
        prompt:
          options.prompt +
          "\n\nThe host runs this Deep Scan coordinator directly and owns finalization. This saved request supplies context for later follow-up; do not start a replacement scan.",
      }),
  )) as {
    threadId: string;
    model: string;
    reasoningEffort?: string;
    permissionProfile: unknown;
  };
  yield { type: "thread.started", thread_id: session.threadId };
  options.signal.throwIfAborted();
  const node = process.versions["bun"]
    ? await resolveTrustedExecutable("node", environment, [options.repository])
    : undefined;
  if (node === null)
    throw new CodexSecurityError("Node.js is not available on PATH.");
  const output = await runEngine(
    node?.executable ?? process.execPath,
    [join(options.pluginRoot, "mcp", "server.mjs"), "--deep-scan-engine"],
    node?.environment ?? environment,
    JSON.stringify({
      scanId: options.scanId,
      ...session,
      ...(options.onDiagnostic && { diagnosticsVersion: 1 }),
    }),
    options.signal,
    options.onDiagnostic,
  );
  const completed = JSON.parse(output);
  if (
    completed.scanId !== options.scanId ||
    completed.manifestPath !== join(options.scanDir, "scan-manifest.json")
  ) {
    throw new CodexSecurityError(
      "Deep Scan engine returned results for a different scan.",
    );
  }
  // The control session makes no model calls. Worker usage is read by the
  // existing scan tracker from the native sessions below this scan directory.
  yield {
    type: "turn.completed",
    usage: { ...DIRECT_DEEP_SCAN_CONTROL_USAGE },
  };
}

function runEngine(
  command: string,
  args: string[],
  env: NodeJS.ProcessEnv,
  request: string,
  signal: AbortSignal,
  onDiagnostic: DirectDeepScanOptions["onDiagnostic"],
): Promise<string> {
  signal.throwIfAborted();
  const child = spawn(executablePathForSpawn(command), args, {
    env,
    windowsHide: true,
    serialization: "json",
    stdio: onDiagnostic ? ["pipe", "pipe", "pipe", "ipc"] : "pipe",
  }) as ChildProcessWithoutNullStreams;
  if (onDiagnostic) {
    child.on("message", (message) => {
      if (!isRecord(message) || typeof message["event"] !== "string") return;
      const fields: Record<string, string | number> = {};
      for (const [name, value] of Object.entries(message)) {
        if (
          /^[a-zA-Z][a-zA-Z0-9]*$/u.test(name) &&
          (typeof value === "number" || typeof value === "string")
        )
          fields[name] = value;
      }
      try {
        void Promise.resolve(onDiagnostic(fields)).catch(() => {});
      } catch {
        // The optional diagnostic sink cannot stop the scan.
      }
    });
  }
  // EOF requests graceful coordinator/worker cleanup on Windows as well as Unix.
  // Keep the control pipe open until completion or explicit cancellation.
  const cancel = () => child.stdin.end();
  let stdout = "";
  let stderr = "";
  let processError: Error | undefined;
  child.stdout.setEncoding("utf8").on("data", (chunk) => {
    stdout += chunk;
  });
  child.stderr.setEncoding("utf8").on("data", (chunk) => {
    stderr += chunk;
  });
  child.once("error", (error) => {
    processError = error;
  });
  child.stdin.on("error", (error: NodeJS.ErrnoException) => {
    if (!isDisconnectedChildStdin(error)) processError = error;
  });
  const result = new Promise<string>((resolve, reject) => {
    child.once("close", (code) => {
      signal.removeEventListener("abort", cancel);
      if (signal.aborted) reject(signal.reason);
      else if (processError) reject(processError);
      else if (code !== 0)
        reject(
          new CodexSecurityError(
            stderr.trim() || `Deep Scan engine exited with code ${code}.`,
          ),
        );
      else resolve(stdout);
    });
  });
  child.stdin.write(request + "\n");
  signal.addEventListener("abort", cancel, { once: true });
  if (signal.aborted) cancel();
  return result;
}