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.5 KB
Raw Blame
import { isRecord } from "./record.js";
import { parseJson } from "./value.js";

const MAX_ACTIVITY_PATHS = 8;
const MAX_PROSE_CHARACTERS = 1_000;
const SHELL_TOKEN = /"(?:\\.|[^"\\])*"|'[^']*'|[^\s|;&<>]+/gu;
const POSIX_TOKEN =
  /(?:"(?:\\[\s\S]|[^"\\])*"|'[^']*'|\\[\s\S]|[^\s|;&<>'"\\])+/gu;
const POSIX_SHELL = /(?:^|\/)(?:sh|bash|zsh)$/u;

export type ScanActivityStatus = "running" | "completed" | "failed";

export interface ScanActivity {
  id: string;
  kind: "command" | "tool" | "reasoning" | "message";
  status: ScanActivityStatus;
  description: string;
  paths: string[];
  worker?: number;
}

export function scanActivitiesFromEvent(
  event: Readonly<Record<string, unknown>>,
  repository: string,
): ScanActivity[] {
  const activity = scanActivityFromEvent(event, repository);
  if (activity === null) return [];

  const item = event["item"];
  if (
    activity.kind !== "reasoning" ||
    !isRecord(item) ||
    typeof item["text"] !== "string"
  ) {
    return [activity];
  }

  const summaries = Array.from(item["text"].matchAll(/\*\*([^*\r\n]+)\*\*/gu));
  if (
    summaries.length < 2 ||
    item["text"].replaceAll(/\*\*[^*\r\n]+\*\*/gu, "").trim() !== ""
  ) {
    return [activity];
  }

  return summaries.map((summary, index) => ({
    ...activity,
    id: index === 0 ? activity.id : `${activity.id}:${index}`,
    description: summary[1]!.trim(),
  }));
}

export function scanActivityFromEvent(
  event: Readonly<Record<string, unknown>>,
  repository: string,
): ScanActivity | null {
  if (
    (event["type"] !== "item.started" &&
      event["type"] !== "item.updated" &&
      event["type"] !== "item.completed") ||
    !isRecord(event["item"])
  ) {
    return null;
  }

  const item = event["item"];
  if (typeof item["id"] !== "string") return null;

  const status: ScanActivityStatus =
    item["status"] === "failed"
      ? "failed"
      : event["type"] === "item.completed"
        ? "completed"
        : "running";

  const command = item["command"];
  if (item["type"] === "command_execution" && isCommand(command)) {
    return {
      id: item["id"],
      kind: "command",
      status,
      ...commandDetails(command, repository, item["shell"]),
    };
  }

  if (item["type"] === "mcp_tool_call" && typeof item["tool"] === "string") {
    const arguments_ = isRecord(item["arguments"]) ? item["arguments"] : {};
    const value = arguments_["cmd"] ?? arguments_["command"];
    const details =
      item["tool"] === "exec" && isCommand(value)
        ? commandDetails(
            value,
            repository,
            arguments_["shell"] ?? item["shell"],
          )
        : {
            description: toolDescription(
              item["tool"],
              arguments_,
              item["arguments"],
            ),
            paths: argumentRepositoryPaths(arguments_, repository),
          };
    return { id: item["id"], kind: "tool", status, ...details };
  }

  if (
    (item["type"] === "reasoning" || item["type"] === "agent_message") &&
    typeof item["text"] === "string"
  ) {
    return proseActivity(
      item["id"],
      item["type"] === "reasoning" ? "reasoning" : "message",
      status,
      item["text"],
    );
  }

  return null;
}

function isCommand(value: unknown): value is string | string[] {
  return (
    typeof value === "string" ||
    (Array.isArray(value) && value.every((part) => typeof part === "string"))
  );
}

function commandDetails(
  value: string | string[],
  repository: string,
  shell: unknown,
) {
  let text: string;
  let paths: string[];
  if (typeof value === "string") {
    const command = unwrapCommand(value);
    text = command.text;
    paths = commandRepositoryPaths(
      command.script ?? text,
      repository,
      shell ?? command.recordedShell,
    );
  } else {
    text = value.join(" ");
    paths = literalRepositoryPaths(value, repository);
  }
  return { description: text.replaceAll(/\s+/gu, " "), paths };
}

/** Decode one literal POSIX word without expanding variables or running a shell. */
function literalPosixWord(argument: string) {
  // A sticky match stops at the first unsupported fragment instead of skipping it.
  const fragment =
    /'([^']*)'|"((?:\\.|[^"\\$\x60])*)"|\\(.)|[^\s'"\\$\x60|;&<>()*?\[\]{}~]+/suy;
  let word = "";
  do {
    const match = fragment.exec(argument);
    if (!match) return undefined;
    const [raw, single, double, escaped] = match;
    if (double !== undefined)
      word += double.replace(/\\\n|\\([$\x60"\\])/gu, "$1");
    else if (escaped !== "\n") word += single ?? escaped ?? raw;
  } while (fragment.lastIndex < argument.length);
  return word;
}

function unwrapCommand(command: string) {
  const normalized = command.trim();
  const powershell =
    process.platform === "win32"
      ? /^(?:"([^"]+)"|([^\s"'|;&<>]+))\s+(?:-NoProfile\s+)?-Command\s+(['"])(.*)\3$/isu.exec(
          normalized,
        )
      : null;
  if (
    powershell !== null &&
    /(?:^|[\\/])(?:powershell|pwsh)(?:\.exe)?$/iu.test(
      powershell[1] ?? powershell[2]!,
    )
  ) {
    return { text: powershell[4]! };
  }
  const match =
    /^((?:\/(?:usr\/)?bin\/)?(?:zsh|bash|sh))\s+-[a-z]*c[a-z]*\s+(["'].*)$/su.exec(
      normalized,
    );
  if (match === null) return { text: normalized, script: command };
  const argument = match[2]!;
  const decoded = literalPosixWord(argument);
  return {
    text: argument.slice(1, argument.endsWith(argument[0]!) ? -1 : undefined),
    script: decoded,
    recordedShell: decoded === undefined ? undefined : match[1],
  };
}

export function scanActivityFromSessionEvent(
  event: Readonly<Record<string, unknown>>,
  repository: string,
): ScanActivity | null {
  if (!isRecord(event["payload"])) {
    return null;
  }
  const payload = event["payload"];
  if (event["type"] === "event_msg") {
    const type = payload["type"];
    const kind =
      type === "agent_reasoning" ||
      type === "agent_reasoning_delta" ||
      type === "agent_reasoning_raw_content" ||
      type === "agent_reasoning_raw_content_delta"
        ? "reasoning"
        : type === "agent_message"
          ? "message"
          : null;
    const delta =
      type === "agent_reasoning_delta" ||
      type === "agent_reasoning_raw_content_delta";
    const text = delta
      ? payload["delta"]
      : kind === "reasoning"
        ? payload["text"]
        : payload["message"];
    if (kind === null || typeof text !== "string") return null;
    return proseActivity(
      `${type}:${typeof event["timestamp"] === "string" ? event["timestamp"] : ""}:${text}`,
      kind,
      delta ? "running" : "completed",
      text,
    );
  }
  if (event["type"] !== "response_item") return null;
  const id = payload["call_id"] ?? payload["id"];
  if (typeof id !== "string") return null;

  if (payload["type"] === "reasoning") {
    return sessionProse(id, "reasoning", payload["summary"]);
  }
  if (payload["type"] === "message" && payload["role"] === "assistant") {
    return sessionProse(id, "message", payload["content"]);
  }
  if (
    payload["type"] !== "function_call" &&
    payload["type"] !== "custom_tool_call" &&
    payload["type"] !== "local_shell_call"
  ) {
    return null;
  }
  const arguments_ = sessionCallArguments(payload);
  const name =
    typeof payload["name"] === "string"
      ? payload["name"]
      : payload["type"] === "local_shell_call"
        ? "shell"
        : null;
  if (name === null) return null;

  const value =
    arguments_["cmd"] ??
    arguments_["command"] ??
    customShellCommand(name, payload["input"]);
  if (
    isCommand(value) &&
    /^(?:exec|exec_command|shell_command|shell)$/u.test(name)
  ) {
    return {
      id,
      kind: "command",
      status: "running",
      ...commandDetails(value, repository, arguments_["shell"]),
    };
  }

  return {
    id,
    kind: "tool",
    status: "running",
    description: toolDescription(name, arguments_, payload["input"]),
    paths: argumentRepositoryPaths(arguments_, repository),
  };
}

function sessionProse(
  id: string,
  kind: "reasoning" | "message",
  value: unknown,
): ScanActivity | null {
  return proseActivity(
    id,
    kind,
    "completed",
    sessionContentText(value, ["summary_text", "output_text"], " "),
  );
}

/** @internal */
export function sessionContentText(
  content: unknown,
  types: readonly string[] = ["output_text"],
  separator = "\n",
): string {
  if (!Array.isArray(content)) return "";
  return content
    .filter(
      (item): item is Record<string, unknown> & { text: string } =>
        isRecord(item) &&
        types.some((type) => item["type"] === type) &&
        typeof item["text"] === "string",
    )
    .map((item) => item.text)
    .join(separator);
}

function proseActivity(
  id: string,
  kind: "reasoning" | "message",
  status: ScanActivityStatus,
  text: string,
): ScanActivity | null {
  const description = prose(
    text
      .split(/\r?\n/u)
      .filter(
        (line) =>
          !/^CODEX_SECURITY_(?:WORKER_STATUS|SCAN_PROGRESS)\s/u.test(line),
      )
      .join("\n"),
  );
  if (description === "") {
    return null;
  }
  return { id, kind, status, description, paths: [] };
}

function prose(text: string, limit?: number): string {
  const normalized = text
    .split(
      /((?<!`)`{3,}[^`\r\n]*(?:\r?\n[\s\S]*?(?:\r?\n[ \t]*`{3,}[ \t]*(?=\r?\n|$)|$)|$)|`[^`\r\n]+`)/gu,
    )
    .reduce((result, part, index) => {
      if (index % 2 === 1) {
        if (!part.startsWith("```")) return `${result}${part}`;
        const previous = result.trimEnd();
        return `${previous}${previous === "" ? "" : "\n"}${part}\n`;
      }
      const plain = part
        .replaceAll(/\*\*([\s\S]+?)\*\*/gu, "$1")
        .replaceAll(/\s+/gu, " ");
      return `${result}${result.endsWith("\n") ? plain.trimStart() : plain}`;
    }, "")
    .trim();
  if (limit === undefined) return normalized;
  const characters = Array.from(normalized);
  return characters.length <= limit
    ? normalized
    : `${characters.slice(0, limit - 1).join("")}…`;
}

function customShellCommand(name: string, value: unknown): string | null {
  if (name !== "exec" || typeof value !== "string") return null;
  const quoted =
    /\b(?:exec_command|shell_command)\s*\(\s*\{[\s\S]{0,1024}?\b(?:cmd|command)["']?\s*:\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`[^`]*`)/u.exec(
      value,
    )?.[1];
  if (quoted === undefined) return null;
  if (quoted.startsWith('"')) {
    return parseJson(() => quoted) as string | null;
  }
  return quoted.slice(1, -1).replaceAll(/\\(['`\\])/gu, "$1");
}

function toolDescription(
  name: string,
  arguments_: Readonly<Record<string, unknown>>,
  input: unknown,
): string {
  if (name === "send_message" || name === "followup_task") {
    const target = arguments_["target"] ?? arguments_["recipient"];
    const message = arguments_["message"] ?? arguments_["text"];
    return `${name}${typeof target === "string" ? ` → ${target}` : ""}${typeof message === "string" ? `: ${prose(message, MAX_PROSE_CHARACTERS)}` : ""}`;
  }
  if (name === "spawn_agent") {
    const task = arguments_["message"] ?? arguments_["task"];
    return typeof task === "string"
      ? `spawn_agent · ${prose(task, MAX_PROSE_CHARACTERS)}`
      : name;
  }
  if (name === "exec" && typeof input === "string") {
    if (/\b(?:exec_command|shell_command)\s*\(/u.test(input)) {
      return "exec · run shell command";
    }
    if (/\bapply_patch\s*\(/u.test(input)) return "exec · apply patch";
    const tool = /\btools\.(?:\w+__)?(\w+)\s*\(/u.exec(input)?.[1];
    if (tool !== undefined) return tool;
    const search =
      /\bALL_TOOLS\.(?:filter|find)\s*\([\s\S]{0,512}?\/([^/\r\n]+)\/[a-z]*/u.exec(
        input,
      )?.[1];
    if (search !== undefined) {
      return `find tools · ${search.replaceAll("|", ", ").replaceAll(/(?:\.\*|\.\?|_)/gu, "-")}`;
    }
  }
  return name;
}

function sessionCallArguments(
  payload: Readonly<Record<string, unknown>>,
): Record<string, unknown> {
  if (isRecord(payload["action"])) return payload["action"];
  const value = payload["arguments"] ?? payload["input"];
  if (isRecord(value)) return value;
  if (typeof value !== "string") return {};
  const parsed = parseJson(() => value);
  return isRecord(parsed) ? parsed : {};
}

const WINDOWS_DRIVE = /^(?:(?:\\\\|\/\/)[?.][\\/])?[a-z]:(?=[\\/])/i;
const UNC_SERVER = /^(?:\\\\|\/\/)(?:[?.][\\/]UNC[\\/])?[^\\/]+/i;

function windowsActivityRoot(path: string): string {
  // Inspect the original separators: a POSIX directory name can begin with a backslash.
  const root =
    WINDOWS_DRIVE.exec(path)?.[0] ?? UNC_SERVER.exec(path)?.[0] ?? "";
  return root
    .replaceAll("\\", "/")
    .replace(/[A-Z]/gu, (letter) => letter.toLowerCase());
}

function repositoryPathMatcher(repository: string, literal: boolean) {
  const root = windowsActivityRoot(repository);
  const normalize = (path: string) =>
    literal && !root ? path : path.replaceAll("\\", "/");
  const prefix = `${normalize(repository).replace(/\/$/u, "")}/`;
  const directory = prefix.slice(root.length);

  // A recorded UNC path can refer to either an SMB share or a case-sensitive
  // WebDAV collection. Keep every component after the server exact.
  return (raw: string, value = normalize(raw)): string | null => {
    if (
      value.startsWith(prefix) ||
      (root !== "" &&
        value.startsWith(directory, root.length) &&
        windowsActivityRoot(raw) === root)
    ) {
      return value.slice(prefix.length);
    }
    return null;
  };
}

function literalRepositoryPaths(argv: string[], repository: string): string[] {
  // The shell's -c argument is source text. Its positional arguments are literal.
  const executable = argv[0] ?? "";
  const posix = POSIX_SHELL.test(executable);
  const powershell = /(?:^|[\\/])(?:pwsh|powershell)(?:\.exe)?$/iu.test(
    executable,
  );
  let operands = argv;
  if (posix || powershell) {
    for (let i = 1; i < argv.length; i++) {
      const part = argv[i]!;
      if (
        !part.startsWith("-") ||
        part === "--" ||
        (powershell && /^-file$/iu.test(part))
      )
        break;
      if (posix && /^-[a-z]*c[a-z]*$/u.test(part)) {
        const script = argv[i + 1] === "--" ? i + 2 : i + 1;
        operands = argv.filter((_, index) => index !== script);
        break;
      }
      if (powershell && /^-command$/iu.test(part)) {
        operands = argv.slice(0, i);
        break;
      }
    }
  }
  return operandRepositoryPaths(operands, repository, true);
}

function commandRepositoryPaths(
  command: string,
  repository: string,
  shell: unknown,
): string[] {
  const posixShell = typeof shell === "string" && POSIX_SHELL.test(shell);
  const posixPaths = posixShell && windowsActivityRoot(repository) === "";
  const paths = new Set<string>();
  const roots = [
    "$CODEX_SECURITY_REPOSITORY",
    "${CODEX_SECURITY_REPOSITORY}",
    repository,
  ].map((root) => repositoryPathMatcher(root, posixPaths));
  for (const token of command.match(posixShell ? POSIX_TOKEN : SHELL_TOKEN) ??
    []) {
    let value = token;
    const first = token[0]!;
    const quote =
      (first === "'" || first === '"') && token.endsWith(first)
        ? first
        : undefined;
    const hasQuote = /['"]/u.test(token);
    const hasEscape = posixPaths
      ? token.includes("\\")
      : /\\[ \t]/u.test(token);
    const posixLiteral = posixShell && (hasQuote || hasEscape);
    if (posixLiteral) {
      if (!posixPaths && !hasQuote && /\\(?![ \t])/u.test(token)) continue;
      // A single-quoted or backslash-escaped dollar sign is literal.
      const variable =
        /^"?(\$(?:CODEX_SECURITY_REPOSITORY|\{CODEX_SECURITY_REPOSITORY\}))/u.exec(
          token,
        )?.[1];
      const literal = literalPosixWord(
        variable ? token.replace(variable, "") : token,
      );
      if (literal === undefined || literal.startsWith("$")) continue;
      value = (variable ?? "") + literal;
    } else if (quote) value = value.slice(1, -1);
    const raw = posixLiteral ? value : value.replaceAll('\\"', '"');
    value = posixPaths ? raw : raw.replaceAll("\\", "/");
    if (process.platform === "win32" && quote !== "'") {
      value = value.replace(
        /^\$(?:env:CODEX_SECURITY_REPOSITORY|\{env:CODEX_SECURITY_REPOSITORY\})\//iu,
        "$CODEX_SECURITY_REPOSITORY/",
      );
    }
    for (const relativeTo of roots) {
      const relative = relativeTo(raw, value);
      if (relative === null) continue;
      // Quotes, edge whitespace and colon-number suffixes can be filename data.
      let path = relative;
      if (!posixLiteral) {
        // An opposite quote inside a quoted filename is literal data.
        const boundary =
          quote && !path.includes(quote) ? /[\r\n].*$/u : /["'\r\n].*$/u;
        path = path.replace(boundary, "").trim();
      }
      path = path.replace(/\/+$/u, "");
      if (!posixLiteral) path = path.replace(/:\d+(?::\d+)?$/u, "");
      if (path !== "" && !path.split("/").includes("..")) paths.add(path);
    }
    if (paths.size >= MAX_ACTIVITY_PATHS) break;
  }
  return [...paths];
}

function argumentRepositoryPaths(value: unknown, repository: string): string[] {
  if (!isRecord(value)) return [];
  const candidates = [value["path"], value["file_path"], value["paths"]].flat();
  return operandRepositoryPaths(candidates, repository);
}

function operandRepositoryPaths(
  candidates: unknown[],
  repository: string,
  skipRoot = false,
): string[] {
  const paths = new Set<string>();
  const relativeTo = repositoryPathMatcher(repository, true);
  for (const candidate of candidates) {
    if (typeof candidate !== "string") continue;
    const path = relativeTo(candidate);
    if (
      path !== null &&
      (!skipRoot || path !== "") &&
      !path.split("/").includes("..")
    )
      paths.add(path);
    if (paths.size >= MAX_ACTIVITY_PATHS) break;
  }
  return [...paths];
}