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

11.8 KB
Raw Blame
import { execFile as execFileCallback } from "node:child_process";
import { lstat, readdir, realpath } from "node:fs/promises";
import { join, relative } from "node:path";
import { promisify } from "node:util";
import { CodexSecurityError, InvalidTargetError } from "./errors.js";
import type { OwnerFinding } from "./suggest-owners.js";
import {
  nullIfMissingFile,
  enclosingGitWorktreeRoot,
  gitMetadataDirectories,
  normalizeRepository,
  relativePathIsOutside,
  validatedGitEnvironment,
} from "./targets.js";
import { resolveTrustedExecutable } from "./trusted-executable.js";
import {
  codeownersForPath,
  parseCodeowners,
  type CodeownerIdentity,
} from "./codeowners.js";

const execFile = promisify(execFileCallback);

export interface OwnerIdentity {
  name: string;
  email: string;
}

export interface OwnerEvidence {
  id: string;
  kind: "source" | "blame" | "history" | "codeowners";
  path: string;
  commit: string;
  /** Original blamed commit; blame citations keep commit at the checkout revision. */
  blameCommit?: string;
  startLine?: number;
  endLine?: number;
  rule?: string;
  matchedPath?: string;
  content: string;
  identityIndex: number | null;
}

export interface OwnerContext {
  identities: OwnerIdentity[];
  evidence: OwnerEvidence[];
  limitations: string[];
  codeowner: CodeownerIdentity | null;
}

/** Read committed objects, so dirty files and source symlinks are never followed. */
export async function ownerRepository(
  repository: string,
  environment: NodeJS.ProcessEnv,
  signal?: AbortSignal,
) {
  repository = await normalizeRepository(repository, signal);
  validatedGitEnvironment(environment);
  repository =
    (await enclosingGitWorktreeRoot(repository, signal, {
      requireIfPresent: true,
    })) ?? repository;
  const executable = await resolveTrustedExecutable(
    "git",
    environment,
    repository,
  );
  if (executable === null)
    throw new CodexSecurityError("Git is required to suggest owners.");
  const run = async (cwd: string, args: string[], encoding: BufferEncoding) => {
    signal?.throwIfAborted();
    const { stdout } = await execFile(executable.executable, args, {
      cwd,
      env: { ...executable.environment, GIT_NO_LAZY_FETCH: "1" },
      signal,
      maxBuffer: Infinity,
      encoding: "buffer",
    });
    return stdout.toString(encoding);
  };
  const [gitDirectory, commonDirectory, ...objectDirectories] =
    await gitMetadataDirectories(repository, signal, {
      includeLocalObjects: true,
    });
  const metadataDirectories = [...new Set([gitDirectory, commonDirectory])];
  if (
    objectDirectories.some((path) =>
      metadataDirectories.every((root) =>
        relativePathIsOutside(relative(root, path)),
      ),
    )
  ) {
    throw new InvalidTargetError(
      "Git objects are not bound to the selected checkout. Use a checkout that does not borrow external object stores.",
    );
  }
  await requireBoundMetadata(metadataDirectories, objectDirectories, signal);
  // Blame otherwise reads an uncommitted .mailmap from the working directory.
  const gitOutput = (encoding: BufferEncoding, ...args: string[]) =>
    run(
      gitDirectory,
      [
        `--git-dir=${gitDirectory}`,
        "--literal-pathspecs",
        "-c",
        "core.bare=true",
        "-c",
        "i18n.logOutputEncoding=UTF-8",
        ...args,
      ],
      encoding,
    );
  const git = (...args: string[]) => gitOutput("utf8", ...args);
  const revision = (await git("rev-parse", "--verify", "HEAD^{commit}")).trim();
  const files = new Set(
    (await gitOutput("latin1", "ls-tree", "-r", "-z", "--full-tree", revision))
      .split("\0")
      .filter((record) => /^100(?:644|755) blob /u.test(record))
      .map((record) => record.slice(record.indexOf("\t") + 1)),
  );
  const shallow =
    (await git("rev-parse", "--is-shallow-repository")).trim() === "true";
  // Latin-1 keys preserve Git's filename bytes, including unrelated non-UTF-8 names.
  const hasFile = (path: string) =>
    path.isWellFormed() && files.has(Buffer.from(path).toString("latin1"));
  const loadCodeowners = async () => {
    const path = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"].find(
      hasFile,
    );
    if (path === undefined) return null;
    const source = await git("cat-file", "blob", `${revision}:${path}`);
    // GitHub requires CODEOWNERS to be under 3 MB.
    return {
      path,
      rules:
        Buffer.byteLength(source) >= 3_000_000 ? null : parseCodeowners(source),
    };
  };
  let codeowners: ReturnType<typeof loadCodeowners> | undefined;
  return {
    git,
    revision,
    hasFile,
    shallow,
    // Keep the load lazy so failures remain inside per-finding error handling.
    codeowners: () => (codeowners ??= loadCodeowners()),
  };
}

/** Neither references nor objects may link into another checkout. */
async function requireBoundMetadata(
  metadataDirectories: string[],
  objectDirectories: string[],
  signal?: AbortSignal,
): Promise<void> {
  const pending = [
    ...objectDirectories,
    ...metadataDirectories.flatMap((directory) =>
      ["HEAD", "refs", "packed-refs", "reftable"].map((name) =>
        join(directory, name),
      ),
    ),
  ];
  const visited = new Set<string>();
  while (pending.length > 0) {
    signal?.throwIfAborted();
    const path = pending.pop()!;
    if (visited.has(path)) continue;
    visited.add(path);
    const entry = await lstat(path).catch(nullIfMissingFile);
    if (entry?.isSymbolicLink()) {
      const destination = await realpath(path);
      if (
        metadataDirectories.every((root) =>
          relativePathIsOutside(relative(root, destination)),
        )
      ) {
        throw new InvalidTargetError(
          "Git metadata is not bound to the selected checkout. Select the intended checkout or repair its Git metadata.",
        );
      }
      pending.push(destination);
    } else if (entry?.isDirectory()) {
      for (const name of await readdir(path)) pending.push(join(path, name));
    }
  }
}

export async function collectOwnerEvidence(
  finding: OwnerFinding,
  repository: Awaited<ReturnType<typeof ownerRepository>>,
): Promise<OwnerContext> {
  const { git, revision, hasFile, shallow } = repository;
  const context: OwnerContext = {
    identities: [],
    evidence: [],
    codeowner: null,
    limitations: [
      "Git authors are not verified tracker accounts or proof of current employment.",
    ],
  };
  if (shallow)
    context.limitations.push(
      "This checkout has shallow history; earlier contributors may be missing.",
    );
  const stale =
    finding.sourceRevision !== undefined && finding.sourceRevision !== revision;
  if (stale)
    context.limitations.push(
      "The finding revision differs from HEAD; its line ranges were not used.",
    );
  if (finding.locations.length === 0)
    context.limitations.push("No source locations were supplied.");
  const identityIndex = (name: string, email: string) => {
    const index = context.identities.findIndex(
      (identity) => identity.email === email,
    );
    if (index !== -1) return index;
    return context.identities.push({ name, email }) - 1;
  };
  const add = (item: Omit<OwnerEvidence, "id">) => {
    context.evidence.push({ id: `e${context.evidence.length + 1}`, ...item });
  };
  const codeowners = await repository.codeowners();
  if (codeowners !== null) {
    if (codeowners.rules === null) {
      context.limitations.push(
        "CODEOWNERS meets or exceeds GitHub's 3 MB file-size limit and was ignored.",
      );
    } else {
      for (const { path } of finding.locations) {
        if (!hasFile(path)) continue;
        const rule = codeownersForPath(codeowners.rules, path);
        if (rule === undefined) continue;
        const owner = rule.owners[0];
        if (owner === undefined) continue;
        context.codeowner = owner;
        context.limitations.push(
          "CODEOWNERS identities are declarations; their existence and repository access are not verified.",
        );
        add({
          kind: "codeowners",
          path: codeowners.path,
          commit: revision,
          startLine: rule.line,
          endLine: rule.line,
          rule: rule.rule,
          matchedPath: path,
          content: rule.rule,
          identityIndex: null,
        });
        return context;
      }
    }
  }
  for (const path of new Set(finding.locations.map(({ path }) => path))) {
    if (!hasFile(path)) {
      context.limitations.push(`Not a regular file at HEAD: ${path}`);
      continue;
    }
    const source = await git("cat-file", "blob", `${revision}:${path}`);
    if (!source || source.includes("\0")) {
      context.limitations.push(`Source is empty or binary: ${path}`);
      continue;
    }
    const lines = source.replace(/\n$/u, "").split("\n");
    const locations = stale
      ? [{ path }]
      : finding.locations.filter((location) => location.path === path);
    for (const location of locations) {
      const start = location.startLine ?? 1;
      if (start > lines.length) {
        context.limitations.push(
          `Finding line is outside the committed file: ${path}:${start}`,
        );
        continue;
      }
      // Include surrounding code for the model, but attribute only the affected lines.
      const end = Math.min(
        location.endLine ?? location.startLine ?? lines.length,
        lines.length,
      );
      const excerptStart = Math.max(1, start - 10);
      const excerptEnd = Math.min(lines.length, end + 10);
      add({
        kind: "source",
        path,
        commit: revision,
        startLine: excerptStart,
        endLine: excerptEnd,
        content: lines
          .slice(excerptStart - 1, excerptEnd)
          .map((line, index) => `${excerptStart + index}: ${line}`)
          .join("\n"),
        identityIndex: null,
      });
      const blame = await git(
        "blame",
        "--line-porcelain",
        "--no-textconv",
        "--ignore-revs-file=",
        "-L",
        `${start},${end}`,
        revision,
        "--",
        path,
      );
      let commit = "",
        name = "",
        email = "",
        line = 0;
      for (const value of blame.split("\n")) {
        const header = /^([a-f0-9]{40,64}) \d+ (\d+)(?: \d+)?$/u.exec(value);
        if (header) {
          commit = header[1]!;
          line = Number(header[2]);
        } else if (value.startsWith("author ")) name = value.slice(7);
        else if (value.startsWith("author-mail <")) email = value.slice(13, -1);
        else if (value.startsWith("\t") && email.trim()) {
          const index = identityIndex(name, email);
          const previous = context.evidence.at(-1);
          if (
            previous?.kind === "blame" &&
            previous.blameCommit === commit &&
            previous.identityIndex === index &&
            previous.endLine === line - 1
          ) {
            previous.endLine = line;
          } else {
            add({
              kind: "blame",
              path,
              commit: revision,
              blameCommit: commit,
              startLine: line,
              endLine: line,
              content: `Authored in ${commit}.`,
              identityIndex: index,
            });
          }
        }
      }
    }
    const history = (
      await git(
        "log",
        "--no-use-mailmap",
        "--no-show-signature",
        "--no-notes",
        "--no-decorate",
        "--format=%H%x00%an%x00%ae%x00%aI%x00%s",
        "-z",
        revision,
        "--",
        path,
      )
    ).split("\0");
    for (let index = 0; index + 4 < history.length; index += 5) {
      const [commit, name, email, date, subject] = history.slice(
        index,
        index + 5,
      ) as [string, string, string, string, string];
      if (email.trim())
        add({
          kind: "history",
          path,
          commit,
          content: `${date}: ${subject}`,
          identityIndex: identityIndex(name, email),
        });
    }
  }
  return context;
}