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

14.4 KB
Raw Blame
import type { ExternalImportTarget } from "./external-import-contract.js";
import { hash } from "node:crypto";
import { isProxy } from "node:util/types";
import { GHSA_ID, githubRepositoryParts } from "./github-identifiers.js";
import { CodexSecurityError, errorMessage } from "./errors.js";
import {
  cloudRepositoryUrlKey,
  exportedGitHubRecord,
  validateExternalEvidence,
} from "./external-import-contract.js";
import type { ExternalFinding, ExternalFindings } from "./external-findings.js";
import type { ImportedGitHubCodeScanningAlert } from "./github.js";
import type { ImportedGitHubAdvisory } from "./github-advisories.js";
import {
  isGitHubDependabotAlert,
  normalizeGitHubDependabotAlerts,
} from "./github-dependabot-findings.js";
import { asRecord } from "./record.js";
import {
  parseJsonOrJsonl,
  readScannerText,
  scannerSeverity,
  text,
} from "./scanner-import.js";

function repositoryName(value: unknown): string {
  const repository = text(value);
  if (!repository || !githubRepositoryParts(repository))
    throw new Error("GitHub repository must be OWNER/REPO.");
  return repository;
}

function sourceUrl(value: string): {
  parsed: URL;
  host: string;
  origin: string;
} {
  const parsed = new URL(value);
  const origin = /^(https?:\/\/([^/?#]+))/iu.exec(value);
  if (!origin) throw new Error("GitHub evidence URL must be an HTTP(S) link.");
  // URL.origin/host remove explicit default ports; Cloud keeps those distinct.
  return { parsed, host: origin[2]!.toLowerCase(), origin: origin[1]! };
}

function sourceTimestamp(value: unknown): number | null {
  if (value === undefined || value === null) return null;
  const seconds = typeof value === "string" ? Date.parse(value) / 1000 : NaN;
  if (!Number.isFinite(seconds) || seconds < 0)
    throw new Error("GitHub updated_at is not a valid timestamp.");
  return Math.floor(seconds);
}

function codeScanningPrefix(
  { parsed, host }: ReturnType<typeof sourceUrl>,
  repository: string,
  number: number,
): string | undefined {
  const name = repository.toLowerCase();
  const path = parsed.pathname.toLowerCase();
  const alert = `code-scanning/${number}`;
  if (path === `/${name}/${alert}` || path === `/${name}/security/${alert}`)
    return `${host}/${name}/${alert}/`;
}

function codeScanningSource(record: Record<string, unknown>) {
  const name = repositoryName(record["repository"]);
  const alert = asRecord(record["alert"]);
  const number = record["number"];
  if (
    !alert ||
    typeof number !== "number" ||
    !Number.isSafeInteger(number) ||
    number < 1 ||
    alert["number"] !== number
  )
    throw new Error(
      "Expected a GitHub code-scanning import with matching alert numbers.",
    );
  const url = text(record["url"]);
  if (!url || url !== alert["html_url"])
    throw new Error("GitHub alert URL must match the original alert.");
  const link = sourceUrl(url);
  const prefix = codeScanningPrefix(link, name, number);
  if (!prefix)
    throw new Error(
      "GitHub alert URL does not match the selected repository and alert.",
    );
  const repository = { url: `${link.origin}/${name}`, name };
  return { alert, number, prefix, url, repository };
}

function codeScanningFinding(record: Record<string, unknown>): {
  source_finding_id: string;
  evidence: unknown;
} {
  const { alert, number, prefix, url, repository } = codeScanningSource(record);
  const rule = asRecord(alert["rule"]);
  const instance = asRecord(alert["most_recent_instance"]);
  const ref = text(instance?.["ref"]);
  if (!ref)
    throw new Error(
      "GitHub code-scanning evidence requires the selected instance ref.",
    );
  const location = asRecord(instance?.["location"]);
  const tool = asRecord(alert["tool"]);
  const message = text(asRecord(instance?.["message"])?.["text"]);
  const description =
    text(rule?.["full_description"]) ?? text(rule?.["description"]);
  const tags = Array.isArray(rule?.["tags"]) ? rule["tags"] : [];
  const weaknessIds = [
    ...new Set(
      tags.flatMap((tag: unknown) => {
        const match =
          typeof tag === "string"
            ? /^external\/cwe\/cwe-(\d+)$/iu.exec(tag)
            : null;
        return match ? [`CWE-${Number(match[1])}`] : [];
      }),
    ),
  ];
  const path = text(location?.["path"]);
  return {
    source_finding_id: prefix + hash("sha256", ref),
    evidence: {
      title:
        text(rule?.["name"]) ??
        text(rule?.["description"]) ??
        `GitHub code-scanning alert #${number}`,
      // SARIF error, warning and note describe diagnostics. Use the security rating.
      severity: scannerSeverity(text(rule?.["security_severity_level"])),
      description:
        [...new Set([message, description].filter(Boolean))].join("\n\n") ||
        null,
      url,
      locations: path ? [{ path, line: location?.["start_line"] ?? null }] : [],
      branch: ref,
      code_revision: text(instance?.["commit_sha"]),
      source_updated_at: sourceTimestamp(alert["updated_at"]),
      source_data: record,
      details: {
        kind: "sast",
        repository,
        // Dismissal covers every branch; detection state belongs to the selected ref.
        source_status:
          alert["state"] === "dismissed"
            ? "dismissed"
            : (text(instance?.["state"]) ?? text(alert["state"])),
        scanner_origin: text(tool?.["name"]),
        rule: { id: text(rule?.["id"]), name: text(rule?.["name"]) },
        weakness_ids: weaknessIds,
        remediation_instructions: text(rule?.["help"]),
        code: path ? { end_line: location?.["end_line"] ?? null } : null,
      },
    },
  };
}

function advisorySourceId(
  host: string,
  selection: "global" | "repository",
  repository: string,
  id: string,
): string {
  return `${host}/${selection === "repository" ? repository.toLowerCase() : "global"}/security-advisory/${id.toUpperCase()}`;
}

function advisorySource(record: Record<string, unknown>) {
  const name = repositoryName(record["repository"]);
  const advisory = asRecord(record["advisory"]);
  const id = text(record["ghsaId"]);
  const selection = record["selection"];
  if (
    !advisory ||
    !id ||
    !GHSA_ID.test(id) ||
    text(advisory["ghsa_id"])?.toUpperCase() !== id.toUpperCase()
  )
    throw new Error(
      "Expected a GitHub advisory import with matching GHSA IDs.",
    );
  if (selection !== "repository" && selection !== "global")
    throw new Error("GitHub advisory selection must be repository or global.");
  const url = text(record["url"]);
  if (!url || url !== advisory["html_url"])
    throw new Error("GitHub advisory URL must match the original advisory.");
  const { parsed: parsedUrl, host: linkHost, origin } = sourceUrl(url);
  const host = text(record["githubHost"])?.toLowerCase();
  // Enterprise APIs may return the public advisory database's canonical link.
  const canonicalGlobalLink =
    selection === "global" && parsedUrl.host === "github.com";
  const expectedPath =
    selection === "repository"
      ? `/${name}/security/advisories/${id}`
      : `/advisories/${id}`;
  if (
    !host ||
    (linkHost !== host && !canonicalGlobalLink) ||
    parsedUrl.pathname.toLowerCase() !== expectedPath.toLowerCase()
  )
    throw new Error(
      "GitHub advisory URL does not match the selected source and GHSA ID.",
    );
  const repository = { url: `${origin}/${name}`, name };
  return { advisory, id, selection, url, host, repository } as const;
}

function advisoryFinding(record: Record<string, unknown>): {
  source_finding_id: string;
  evidence: unknown;
} {
  const { advisory, id, selection, url, host, repository } =
    advisorySource(record);
  const vulnerabilities =
    advisory["vulnerabilities"] === null ? [] : advisory["vulnerabilities"];
  if (!Array.isArray(vulnerabilities))
    throw new Error("GitHub advisory vulnerabilities must be an array.");
  const identifiers = Array.isArray(advisory["identifiers"])
    ? advisory["identifiers"]
    : [];
  const advisoryIds = [
    id,
    text(advisory["cve_id"]),
    ...identifiers.map((identifier) => text(asRecord(identifier)?.["value"])),
  ].filter((value): value is string => value !== null);
  const packages = vulnerabilities.flatMap((value) => {
    const vulnerability = asRecord(value);
    const pkg = asRecord(vulnerability?.["package"]);
    const name = text(pkg?.["name"]);
    // GitHub permits incomplete package metadata in advisory disclosures.
    // Preserve it in source_data without inventing a typed package identity.
    if (!name) return [];
    const fixedVersion =
      text(vulnerability?.["first_patched_version"]) ??
      text(vulnerability?.["patched_versions"]);
    return [
      {
        name,
        ecosystem: text(pkg?.["ecosystem"]),
        vulnerable_version_range: text(
          vulnerability?.["vulnerable_version_range"],
        ),
        fixed_versions: fixedVersion ? [fixedVersion] : [],
      },
    ];
  });
  const cwes = Array.isArray(advisory["cwes"]) ? advisory["cwes"] : [];
  return {
    source_finding_id: advisorySourceId(host, selection, repository.name, id),
    evidence: {
      title: text(advisory["summary"]) ?? id,
      severity: scannerSeverity(text(advisory["severity"])),
      description: text(advisory["description"]),
      url,
      advisory_ids: [...new Set(advisoryIds)],
      packages,
      source_updated_at: sourceTimestamp(advisory["updated_at"]),
      source_data: record,
      details: {
        kind: "advisory",
        advisory: { source: selection },
        ...(selection === "repository" ? { repository } : {}),
        source_status: text(advisory["withdrawn_at"])
          ? "withdrawn"
          : (text(advisory["state"]) ??
            (selection === "global" ? "published" : null)),
        scanner_origin: "GitHub Security Advisories",
        weakness_ids: cwes
          .map((value) => text(asRecord(value)?.["cwe_id"]))
          .filter((value): value is string => value !== null),
      },
    },
  };
}

/** Keep the repository from a retained collector export when SDK callers supply their own projection. */
export function retainedGitHubRepository(
  { evidence }: ExternalFinding,
  repositoryKey = cloudRepositoryUrlKey,
): string | undefined {
  const data = evidence.source_data;
  if (!data?.["url"] || !data["repository"]) return;
  let source;
  if (
    data["source"] === "github-code-scanning" &&
    data["number"] !== undefined &&
    asRecord(data["alert"])?.["html_url"]
  ) {
    source = codeScanningSource(data);
  } else if (
    data["source"] === "github-security-advisory" &&
    data["ghsaId"] &&
    data["githubHost"] &&
    data["selection"] &&
    asRecord(data["advisory"])?.["html_url"]
  ) {
    source = advisorySource(data);
    if (source.selection === "global") {
      if (evidence.details?.repository)
        throw new CodexSecurityError(
          "Global advisory evidence cannot claim a source repository.",
        );
      return;
    }
  } else return;
  const native = source.repository.url;
  const projected = evidence.details?.repository?.url;
  if (projected && repositoryKey(projected) !== repositoryKey(native))
    throw new CodexSecurityError(
      "The normalized repository does not match the original GitHub finding.",
    );
  return native;
}

function mapRecord(input: unknown) {
  const record = asRecord(input);
  if (!record) throw new Error("GitHub finding must be an object.");
  if (record["source"] === "github-code-scanning")
    return codeScanningFinding(record);
  if (record["source"] === "github-security-advisory")
    return advisoryFinding(record);
  throw new Error(
    "Expected saved output from import github or import github-advisories; raw or incomplete API responses need an explicit mapping.",
  );
}

function ownData(value: unknown, key: string): unknown {
  if (value && typeof value === "object" && !isProxy(value))
    return Object.getOwnPropertyDescriptor(value, key)?.value;
}

function normalizeRecords(
  records: readonly unknown[],
  target: ExternalImportTarget,
  snapshot = false,
): ExternalFindings {
  const result: ExternalFindings = {
    read: records.length,
    findings: [],
    excluded: [],
  };
  const identities = new Set<string>();
  for (const [index, input] of records.entries()) {
    let exported = input;
    try {
      if (snapshot) {
        const capture = exportedGitHubRecord(input, index, target);
        exported = capture.record;
        if (capture.invalid) throw capture.invalid;
      }
      const { source_finding_id: id, evidence: mapped } = mapRecord(exported);
      const evidence = validateExternalEvidence(mapped, target);
      if (identities.has(id))
        throw new CodexSecurityError(
          `Duplicate source finding id ${JSON.stringify(id)}. Select each GitHub occurrence once.`,
        );
      identities.add(id);
      result.findings.push({ source_finding_id: id, evidence });
    } catch (error) {
      if (error instanceof CodexSecurityError) throw error;
      const url =
        snapshot && exported === input
          ? ownData(input, "url")
          : asRecord(exported)?.["url"];
      result.excluded.push({
        position: index + 1,
        source_finding_id: text(url),
        reason: errorMessage(error),
      });
    }
  }
  return result;
}

/** Map selected code-scanning instances while retaining complete upstream evidence. */
export function normalizeGitHubCodeScanningAlerts(
  alerts: readonly ImportedGitHubCodeScanningAlert[],
  target: ExternalImportTarget = "cloud",
): ExternalFindings {
  return normalizeRecords(alerts, target, true);
}

/** Map advisory disclosures without asserting an installed vulnerable dependency. */
export function normalizeGitHubAdvisories(
  advisories: readonly ImportedGitHubAdvisory[],
  target: ExternalImportTarget = "cloud",
): ExternalFindings {
  return normalizeRecords(advisories, target, true);
}

/** Read unfiltered JSON/JSONL output saved by the read-only GitHub import commands. */
export async function readGitHubFindings(
  path: string,
  target: ExternalImportTarget = "cloud",
): Promise<ExternalFindings> {
  try {
    const payload = parseJsonOrJsonl(await readScannerText(path));
    const rows = Array.isArray(payload) ? payload : [payload];
    if (
      (rows.length > 0 && rows.every(Array.isArray)) ||
      rows.some((row) =>
        Array.isArray(row)
          ? row.some(isGitHubDependabotAlert)
          : isGitHubDependabotAlert(row),
      )
    )
      return normalizeGitHubDependabotAlerts(payload, target);
    return normalizeRecords(rows, target);
  } catch (cause) {
    throw new CodexSecurityError(
      `Could not read GitHub findings as UTF-8 JSON or JSONL: ${errorMessage(cause)}`,
      { cause },
    );
  }
}