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

22.9 KB
Raw Blame
import { CodexSecurityError } from "./errors.js";
import {
  repositoryUrlKey,
  validateExternalEvidence,
  type ExternalImportTarget,
} from "./external-import-contract.js";
import { asRecord, canonicalJson } from "./record.js";
import { parseJsonOrJsonl, readScannerText, text } from "./scanner-import.js";
import { isGitHubCloudHost } from "./git-remote.js";
import { readWizCsv, wizCsvFinding, wizCsvRepositoryUrl } from "./wiz-csv.js";
import type {
  ExternalFinding as VendorFinding,
  ExternalFindings as VendorFindings,
  ExternalSourceRepository,
} from "./external-findings.js";

function sourceFindingId(value: unknown, target: ExternalImportTarget): string {
  const id = text(value);
  if (
    !id ||
    id.includes("\0") ||
    (target === "cloud" && Buffer.byteLength(id) > 512)
  )
    throw new Error(
      target === "cloud"
        ? "Source finding id must contain 1–512 UTF-8 bytes and no NUL characters."
        : "Source finding id must be nonempty and contain no NUL characters.",
    );
  return id;
}

/** Distinguish original Wiz package records from opaque SDK asset metadata. */
export function isWizPackageFinding(
  data: VendorFinding["evidence"]["source_data"],
): boolean {
  return Boolean(
    data &&
    data["detectionMethod"] !== "EXTERNAL_NETWORK_SCAN" &&
    text(data["id"]) &&
    text(data["name"]) &&
    text(data["detailedName"]) &&
    text(asRecord(data["vulnerableAsset"])?.["id"]),
  );
}

/** Keep a Wiz vulnerability occurrence intact; advisory names are not identities. */
function wizFinding(
  record: Record<string, unknown>,
  target: ExternalImportTarget,
): VendorFinding {
  if (record["detectionMethod"] === "EXTERNAL_NETWORK_SCAN")
    throw new Error(
      "Wiz external network findings are not supported by the package vulnerability mapping.",
    );
  const id = sourceFindingId(record["id"], target);
  const name = text(record["name"]);
  const packageName = text(record["detailedName"]);
  const version = text(record["version"]);
  const severity = (
    text(record["vendorSeverity"]) ?? text(record["severity"])
  )?.toLowerCase();
  const asset = asRecord(record["vulnerableAsset"]);
  const artifact = asRecord(record["artifactType"]);
  if (!name || !packageName || !text(asset?.["id"])) {
    throw new Error(
      "Expected a Wiz package vulnerability finding with name, detailedName, and vulnerableAsset.id. Other finding classes need a separate mapping.",
    );
  }
  const assetType = text(asset?.["type"]);
  const repositoryAsset =
    assetType === "REPOSITORY_BRANCH" ||
    asset?.["nativeType"] === "github#repositoryBranch";
  // Wiz repository reports prefix root-relative paths with '/'. Workload paths
  // are not source locations and must remain only in the original evidence.
  const locationPath = text(record["locationPath"]);
  const repositoryPath =
    repositoryAsset && locationPath ? locationPath.replace(/^\/+/, "") : null;
  const digest =
    text(asset?.["imageDigest"]) ??
    text(record["imageDigest"]) ??
    (assetType === null ||
    assetType === "CONTAINER_IMAGE" ||
    assetType === "CONTAINER"
      ? (text(asset?.["imageId"]) ??
        text(asset?.["containerImageId"]) ??
        text(asset?.["ImageExternalId"]))
      : null);
  // lastDetectedAt is not proof that the entire vendor record was updated.
  const evidence = {
    title:
      text(record["title"]) ??
      [packageName, version, name].filter(Boolean).join(" "),
    description: text(record["description"]),
    severity: severity === "none" ? "unknown" : severity,
    url: text(record["portalUrl"]),
    advisory_ids: [text(record["vulnerabilityExternalId"]) ?? name],
    packages: [
      {
        name: packageName,
        ecosystem:
          text(record["packageManager"]) ??
          text(artifact?.["osPackageManager"]) ??
          text(artifact?.["codeLibraryLanguage"]) ??
          text(record["codeLibraryLanguage"]),
        installed_version: version,
        manifest_path: repositoryPath,
        fixed_versions: text(record["fixedVersion"])
          ? [record["fixedVersion"]]
          : [],
      },
    ],
    locations: repositoryPath ? [{ path: repositoryPath }] : [],
    branch: null,
    code_revision: null,
    source_scan_id: null,
    image_digests: digest ? [digest] : [],
    source_updated_at: updatedAt(record["updatedAt"], "updatedAt"),
    source_data: record,
  };
  return {
    source_finding_id: id,
    evidence: validateExternalEvidence(evidence, target),
  };
}

type RepositoryFindingKind = "sast" | "secret" | "iac";

type InputRecord = {
  value: unknown;
  kind?: "sca" | "sca_csv" | RepositoryFindingKind | "cloud_configuration";
};

type RepositoryMetadata = {
  id: string | null;
  name: string | null;
  url: string;
};

type FindingInput = {
  records: InputRecord[];
  repositories: Map<string, RepositoryMetadata & { platform: string | null }>;
};

// Wiz's documented inventory platform establishes custom GitHub host semantics.
// Keep this context separate from the repository metadata published as evidence.
function inventoryRepositoryUrlKey(
  value: string,
  platform: string | null | undefined,
): string {
  const key = repositoryUrlKey(value);
  return platform === "GITHUB" ? key.toLowerCase() : key;
}

function sourceRepository(
  repository: Record<string, unknown> | undefined,
  repositories: FindingInput["repositories"],
): RepositoryMetadata {
  const id = text(repository?.["id"]);
  const inventory = id ? repositories.get(id) : undefined;
  const suppliedUrl = text(repository?.["url"]);
  if (
    suppliedUrl &&
    inventory &&
    inventoryRepositoryUrlKey(suppliedUrl, inventory.platform) !==
      inventoryRepositoryUrlKey(inventory.url, inventory.platform)
  )
    throw new Error(
      "The finding and repository inventory have conflicting repository URLs.",
    );
  const url = suppliedUrl ?? inventory?.url;
  if (!url)
    throw new Error(
      "A verified source repository URL is required. Include repository.url or the matching repository.id and repository.url from data.versionControlResources.nodes; names and Wiz IDs are not Cloud repository IDs.",
    );
  return {
    id,
    name: text(repository?.["name"]) ?? inventory?.name ?? null,
    url,
  };
}

function updatedAt(value: unknown, field: string): number | null {
  const timestamp = text(value);
  if (!timestamp) return null;
  const seconds = Date.parse(timestamp) / 1000;
  if (!Number.isFinite(seconds) || seconds < 0)
    throw new Error(`Wiz ${field} is not a valid timestamp.`);
  return Math.floor(seconds);
}

// Empty code and configuration strings are meaningful vendor evidence.
function content(value: unknown): string | null {
  return typeof value === "string" ? value : null;
}

/** Map only explicitly identified repository finding collections. */
function repositoryFinding(
  kind: RepositoryFindingKind,
  record: Record<string, unknown>,
  repositories: FindingInput["repositories"],
  target: ExternalImportTarget = "cloud",
): VendorFinding {
  const id = sourceFindingId(record["id"], target);
  const resource = asRecord(record["resource"]);
  if (kind === "secret" && resource?.["type"] !== "REPOSITORY_BRANCH")
    throw new Error(
      "Only repository-branch secret findings can be published to a repository. Workload secrets require a resource-scoped import and are not supported.",
    );
  const suppliedRepository =
    kind === "secret"
      ? asRecord(asRecord(resource?.["typedProperties"])?.["repository"])
      : asRecord(record["repository"]);
  const repository = sourceRepository(suppliedRepository, repositories);
  const branch =
    kind === "secret"
      ? resource
      : asRecord(record[kind === "sast" ? "repositoryBranch" : "branch"]);
  const rule = asRecord(record["rule"]);
  const path = text(record[kind === "secret" ? "path" : "filePath"]);
  const line = record[kind === "secret" ? "lineNumber" : "startLine"];
  const details = {
    kind,
    repository,
    source_status: text(record["status"]),
    scanner_origin: kind === "sast" ? text(record["origin"]) : null,
    scanner_verdict:
      kind === "sast"
        ? text(asRecord(record["aiAnalysis"])?.["verdict"])
        : null,
    rule: rule
      ? {
          id: text(rule["id"]),
          short_id: text(rule["shortId"]),
          name: text(rule["name"]),
        }
      : null,
    weakness_ids:
      kind === "sast" && Array.isArray(record["weaknesses"])
        ? record["weaknesses"].map((weakness) => asRecord(weakness)?.["id"])
        : [],
    remediation_instructions:
      text(record["remediationInstructions"]) ??
      text(rule?.["remediationInstructions"]),
    code:
      path && kind !== "secret"
        ? {
            end_line: record["endLine"] ?? null,
            snippet: content(
              record[kind === "sast" ? "snippet" : "matchContent"],
            ),
          }
        : null,
    secret:
      kind === "secret"
        ? {
            type: text(record["type"]),
            confidence: text(record["confidence"]),
            validation_status: text(record["validationStatus"]),
            is_encrypted: record["isEncrypted"] ?? null,
            is_managed: record["isManaged"] ?? null,
            introduced_commit: text(
              asRecord(record["vcsDetails"])?.["initialCommitHash"],
            ),
          }
        : null,
    configuration:
      kind === "iac"
        ? {
            platform: text(record["platform"]),
            cloud_platform: text(record["cloudPlatform"]),
            expected: content(record["expectedContent"]),
            actual: content(record["foundContent"]),
          }
        : null,
    file_url: text(record["fileURL"]),
  };
  return {
    // Existing package occurrence IDs remain unchanged. New families cannot
    // collide with one another when the same tenant source key is used.
    source_finding_id: sourceFindingId(`${kind}:${id}`, target),
    evidence: validateExternalEvidence(
      {
        title: text(record["name"]) ?? text(rule?.["name"]),
        severity: text(record["severity"])?.toLowerCase(),
        description: text(record["description"]) ?? text(rule?.["description"]),
        url: text(record["wizUrl"]) ?? text(record["portalUrl"]),
        locations: path ? [{ path, line: line ?? null }] : [],
        branch: text(branch?.["name"]),
        code_revision: null,
        source_scan_id: null,
        source_updated_at:
          kind === "secret"
            ? updatedAt(record["lastUpdatedAt"], "lastUpdatedAt")
            : kind === "iac"
              ? updatedAt(record["updatedAt"], "updatedAt")
              : null,
        source_data: record,
        details,
      },
      target,
    ),
  };
}

function records(payload: unknown): FindingInput {
  const repositories: FindingInput["repositories"] = new Map();
  if (Array.isArray(payload))
    return { records: payload.map((value) => ({ value })), repositories };
  const envelope = asRecord(payload);
  if (!envelope)
    throw new Error(
      "Expected finding objects or a named Wiz finding collection.",
    );
  if (
    asRecord(envelope["scannersRunStatuses"]) &&
    asRecord(envelope["codeAnalyzerDetails"])
  )
    throw new Error(
      "This is a Wiz Code & Build Scan event, which contains scan metadata rather than vulnerability records. In Vulnerability Findings, filter the repository and selection, then choose Save as → Report with JSON format and Detailed columns. Download that report instead of Raw Event.",
    );
  if (Array.isArray(envelope["errors"]) && envelope["errors"].length > 0)
    throw new Error(
      "Wiz returned GraphQL errors. Resolve them before publishing this response.",
    );
  if (
    envelope["source_finding_id"] !== undefined ||
    envelope["id"] !== undefined
  )
    return { records: [{ value: envelope }], repositories };
  const data = asRecord(envelope["data"]) ?? envelope;
  const inventory = asRecord(data["versionControlResources"]);
  if (asRecord(inventory?.["pageInfo"])?.["hasNextPage"] === true)
    throw new Error(
      "Wiz repository inventory has another page. Finish the selected inventory before publishing.",
    );
  if (Array.isArray(inventory?.["nodes"])) {
    const entries = inventory["nodes"].flatMap((entry) => {
      const node = asRecord(entry);
      const repository = asRecord(node?.["repository"]);
      const id = text(repository?.["id"]);
      const url = text(repository?.["url"]);
      return id && url
        ? [
            {
              id,
              name: text(repository?.["name"]),
              url,
              platform: text(node?.["platform"]),
            },
          ]
        : [];
    });
    // Resolve provider hints before comparing URLs, so duplicate row order cannot
    // discard a known platform or reject a case variant before its GITHUB hint.
    for (const entry of entries) {
      const previous = repositories.get(entry.id);
      if (
        previous?.platform &&
        entry.platform &&
        previous.platform !== entry.platform
      )
        throw new Error(
          `Repository inventory contains conflicting platforms for ${JSON.stringify(entry.id)}.`,
        );
      repositories.set(entry.id, {
        ...entry,
        // Equivalent inventory aliases must produce the same evidence when the
        // export reorders its rows. Keep a stable supplied URL and nonempty name.
        url: previous && previous.url < entry.url ? previous.url : entry.url,
        name:
          previous?.name && (!entry.name || previous.name < entry.name)
            ? previous.name
            : entry.name,
        platform: entry.platform ?? previous?.platform ?? null,
      });
    }
    for (const entry of entries) {
      const resolved = repositories.get(entry.id)!;
      if (
        inventoryRepositoryUrlKey(entry.url, resolved.platform) !==
        inventoryRepositoryUrlKey(resolved.url, resolved.platform)
      )
        throw new Error(
          `Repository inventory contains conflicting URLs for ${JSON.stringify(entry.id)}.`,
        );
    }
  }
  const collections = {
    vulnerabilityFindings: "sca",
    sastFindings: "sast",
    secretInstances: "secret",
    iacFindings: "iac",
    configurationFindings: "cloud_configuration",
  } as const;
  const selected: InputRecord[] = [];
  let found = false;
  let countedCollection: string | undefined;
  for (const [root, kind] of Object.entries(collections)) {
    if (!(root in data)) continue;
    const collection = asRecord(data[root]);
    if (!collection)
      throw new Error(`Wiz ${root} must be an object with a nodes array.`);
    found = true;
    if (!Array.isArray(collection["nodes"]))
      throw new Error(`Wiz ${root}.nodes must be an array.`);
    if (asRecord(collection["pageInfo"])?.["hasNextPage"] === true)
      throw new Error(
        "Wiz response has another page. Complete the requested pages or save the explicitly selected records in their named collection before publishing.",
      );
    const total = collection["totalCount"];
    if (typeof total === "number" && total > 0) countedCollection = root;
    for (const value of collection["nodes"]) selected.push({ value, kind });
  }
  if (!selected.length && countedCollection)
    throw new Error(
      `Wiz ${countedCollection}.totalCount reports findings, but the export contains no finding nodes.`,
    );
  if (found)
    return {
      records: selected,
      repositories,
    };
  throw new Error(
    "Unsupported Wiz export. Supply repository vulnerability CSV, vulnerability finding objects, named sastFindings/secretInstances/iacFindings collections, or normalized JSONL. Other CSV reports need an explicit normalized JSONL mapping.",
  );
}

/** The source repository retained by a Wiz package finding or CSV row. */
export function wizFindingRepository(
  evidence: VendorFinding["evidence"],
  target: ExternalImportTarget = "local",
): ExternalSourceRepository | undefined {
  const csvUrl = wizCsvRepositoryUrl(evidence);
  if (csvUrl) return { url: csvUrl, platform: "github" };
  const asset = asRecord(evidence.source_data?.["vulnerableAsset"]);
  if (!asset || typeof asset["cloudProviderURL"] !== "string") return;
  const url = URL.parse(asset["cloudProviderURL"]);
  if (!url) return;
  const github =
    asset["nativeType"] === "github#repositoryBranch" ||
    (asset["type"] === "REPOSITORY_BRANCH" &&
      (text(asset["cloudPlatform"])?.toLowerCase() === "github" ||
        isGitHubCloudHost(url.hostname)));
  if (!github)
    return asset["type"] === "REPOSITORY_BRANCH"
      ? { url: asset["cloudProviderURL"] }
      : undefined;
  const [, owner, repository] = url.pathname.split("/");
  if (!owner || !repository) return;
  // URL.origin drops explicit default ports, which the Cloud catalog retains.
  const port =
    target === "cloud"
      ? /^https?:\/\/[^/?#\\]*:(\d+)(?:[/?#]|$)/iu.exec(
          asset["cloudProviderURL"],
        )?.[1]
      : undefined;
  const origin = port ? `${url.protocol}//${url.hostname}:${port}` : url.origin;
  return { url: `${origin}/${owner}/${repository}`, platform: "github" };
}

export async function readVendorFindings(
  path: string,
  target: ExternalImportTarget = "cloud",
): Promise<VendorFindings> {
  return normalizeFindings(await readFindingInput(path), target);
}

/** @internal Reopen a native JSON selection with the same rules as a Wiz file. */
export function normalizeWizJson(
  payload: unknown,
  target: ExternalImportTarget,
) {
  return normalizeFindings(records(payload), target);
}

function inventorySources(input: FindingInput, current: VendorFindings) {
  return current.findings.flatMap(({ evidence }) => {
    const repository = evidence.details?.repository;
    const inventory = input.repositories.get(repository?.id ?? "");
    // Forward provenance only for selected findings that match the inventory.
    // Use the emitted spelling so typed evidence and reader hints share it.
    return repository &&
      inventory?.platform === "GITHUB" &&
      inventoryRepositoryUrlKey(repository.url, inventory.platform) ===
        inventoryRepositoryUrlKey(inventory.url, inventory.platform)
      ? [{ url: repository.url, platform: "github" as const }]
      : [];
  });
}

export async function readWizSelection(
  path: string,
  target: ExternalImportTarget,
) {
  const input = await readFindingInput(path);
  const findings = normalizeFindings(input, target);
  return { findings, sourceRepositories: inventorySources(input, findings) };
}

async function readFindingInput(path: string): Promise<FindingInput> {
  try {
    const contents = await readScannerText(path);
    let payload: unknown;
    try {
      payload = JSON.parse(contents);
    } catch {
      const csv = readWizCsv(contents);
      if (csv)
        return {
          records: csv.map((value) => ({ value, kind: "sca_csv" })),
          repositories: new Map(),
        };
      payload = parseJsonOrJsonl(contents);
    }
    return records(payload);
  } catch (cause) {
    throw new CodexSecurityError(
      `Could not read vendor findings as UTF-8 JSON, JSONL, or Wiz CSV: ${cause instanceof Error ? cause.message : String(cause)}`,
      { cause },
    );
  }
}

/** Apply Wiz's own reader to an occurrence that also retains another scanner's fields. */
export function isWizOccurrence(
  finding: VendorFinding,
  target: ExternalImportTarget,
): boolean {
  const { source_data: data, details } = finding.evidence;
  if (!data || typeof data["id"] !== "string") return false;
  const kind = details?.kind;
  const scoped = kind === "sast" || kind === "iac" || kind === "secret";
  if (
    finding.source_finding_id !==
    (scoped ? `${kind}:${data["id"]}` : data["id"])
  )
    return false;
  const input: FindingInput = {
    records: [{ value: data, kind: scoped ? kind : "sca" }],
    repositories: new Map(),
  };
  const repository = details?.repository;
  if (scoped && repository?.id)
    input.repositories.set(repository.id, {
      id: repository.id,
      name: repository.name ?? null,
      url: repository.url,
      platform: null,
    });
  // The raw record is the same. Check that Wiz produced the selected evidence,
  // including its own repository binding, before treating upstream fields as opaque.
  const selected = canonicalJson({
    ...validateExternalEvidence(finding.evidence, target),
    source_data: undefined,
  });
  const [row] = normalizeFindings(input, target).findings;
  return (
    row !== undefined &&
    canonicalJson({ ...row.evidence, source_data: undefined }) === selected
  );
}

function normalizeFindings(
  input: FindingInput,
  target: ExternalImportTarget,
): VendorFindings {
  const result: VendorFindings = {
    read: input.records.length,
    findings: [],
    excluded: [],
  };
  const identities = new Set<string>();
  for (const [index, item] of input.records.entries()) {
    const record = asRecord(item.value);
    try {
      if (!record) throw new Error("Finding must be an object.");
      let finding: VendorFinding;
      if (item.kind === "sca_csv") {
        finding = wizCsvFinding(
          record,
          sourceFindingId(record["ID"], target),
          target,
        );
      } else if ("source_finding_id" in record) {
        if (
          Object.keys(record).some(
            (key) => !["source_finding_id", "evidence"].includes(key),
          )
        ) {
          throw new Error(
            "Normalized input permits only source_finding_id and evidence.",
          );
        }
        finding = {
          source_finding_id: sourceFindingId(
            record["source_finding_id"],
            target,
          ),
          evidence: validateExternalEvidence(record["evidence"], target),
        };
      } else if (item.kind === "cloud_configuration") {
        throw new Error(
          "Cloud configuration findings require a resource-scoped import and cannot be published to a repository.",
        );
      } else if (item.kind && item.kind !== "sca") {
        finding = repositoryFinding(
          item.kind,
          record,
          input.repositories,
          target,
        );
      } else {
        if (
          !item.kind &&
          (asRecord(record["repository"]) ||
            asRecord(record["repositoryBranch"]) ||
            asRecord(record["resource"]))
        )
          throw new Error(
            "Raw SAST, secret, and IaC records require their named sastFindings, secretInstances, or iacFindings collection. Bare arrays do not identify the finding family; use normalized JSONL for an explicit mapping.",
          );
        finding = wizFinding(record, target);
      }
      if (identities.has(finding.source_finding_id)) {
        throw new CodexSecurityError(
          `Duplicate source finding id ${JSON.stringify(finding.source_finding_id)}. Select each vendor occurrence once.`,
        );
      }
      identities.add(finding.source_finding_id);
      result.findings.push(finding);
    } catch (error) {
      if (error instanceof CodexSecurityError) throw error;
      result.excluded.push({
        position: index + 1,
        source_finding_id:
          item.kind === "sca_csv"
            ? text(record?.["ID"])
            : (text(record?.["source_finding_id"]) ?? text(record?.["id"])),
        reason: error instanceof Error ? error.message : String(error),
      });
    }
  }
  return result;
}