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

13.2 KB
Raw Blame
import {
  normalizeSemgrepPlatformFindings,
  isSemgrepPlatformFormat,
  semgrepPlatformFormat,
} from "./semgrep-platform-findings.js";
import { isRecord } from "./record.js";
import {
  guardianSelectionFormat,
  normalizeGuardianSelection,
} from "./semgrep-guardian-findings.js";
import { parseHostedScannerJson } from "./hosted-scanner-http.js";
import type { ExternalImportTarget } from "./external-import-contract.js";
import {
  cloudRepositoryUrlKey,
  validateExternalEvidence,
} from "./external-import-contract.js";
import type {
  ExternalFindings,
  ExternalSourceRepository,
} from "./external-findings.js";
import {
  messageText,
  nativeResultPath,
  parseNativeJsonResult,
  position,
  projectNativeJsonResult,
  sourceRepositoryUrl,
  ungatedText,
  weaknessIds,
} from "./native-json-findings.js";
import {
  array,
  normalizeRecords,
  optionalArray,
  readScannerJson,
  record,
  requiredText,
  sarifRunRepositories,
  sarifRunResults,
  stableId,
  readSarifRuns,
  text,
  validateSarifRuleReference,
} from "./scanner-import.js";

export interface SemgrepImportOptions {
  /** Independent source references from the SDK reader. */
  sourceRepositories?: readonly ExternalSourceRepository[];
  /** Source repository declared by the caller; never inferred from the destination. */
  sourceRepositoryUrl: string;
}

function sourceRepository(options: Partial<SemgrepImportOptions>): string {
  return sourceRepositoryUrl(options?.sourceRepositoryUrl, "Semgrep");
}

const severityLevels = new Map([
  ["CRITICAL", "critical"],
  ["HIGH", "high"],
  ["MEDIUM", "medium"],
  ["LOW", "low"],
  ["ERROR", "high"],
  ["WARNING", "medium"],
  ["INFO", "low"],
]);

function severity(value: unknown): string {
  return typeof value === "string"
    ? (severityLevels.get(value) ?? "unknown")
    : "unknown";
}

function identity(
  rule: string,
  path: string,
  line: number,
  column: number,
  endLine: number,
  endColumn: number,
): string {
  // CE omits fingerprints and source snippets. Its fallback is stable only while the range is stable.
  return stableId("semgrep-location", [
    rule,
    path,
    line,
    column,
    endLine,
    endColumn,
  ]);
}

function jsonIdentity(value: unknown): string {
  const result = record(value, "Semgrep result");
  const extra = record(result["extra"], "Semgrep extra");
  const supplied = ungatedText(extra["fingerprint"]);
  if (supplied) return stableId("semgrep", [supplied]);
  const start = record(result["start"], "Semgrep start");
  const end = record(result["end"], "Semgrep end");
  return identity(
    requiredText(result["check_id"], "Semgrep check_id"),
    requiredText(result["path"], "Semgrep path"),
    position(start["line"], "Start line"),
    position(start["col"], "Start column"),
    position(end["line"], "End line"),
    position(end["col"], "End column"),
  );
}

function sarifArtifactUri(
  artifact: Record<string, unknown>,
  runContext: Record<string, unknown>,
): string | null {
  const base = artifact["uriBaseId"];
  // Native Semgrep uses %SRCROOT% without defining a base. Keep other references raw.
  if (
    artifact["index"] !== undefined ||
    (base !== undefined &&
      (base !== "%SRCROOT%" ||
        record(runContext["originalUriBaseIds"] ?? {}, "SARIF URI bases")[
          base
        ] !== undefined))
  )
    return null;
  const uri = requiredText(artifact["uri"], "Semgrep artifact URI");
  // Semgrep's native formatter copies filesystem paths without URI encoding.
  return base === "%SRCROOT%" ? uri : decodeURIComponent(uri);
}

function primarySarifLocation(result: Record<string, unknown>) {
  const locations = array(result["locations"] ?? [], "Semgrep locations");
  if (locations.length !== 1)
    throw new Error("Expected Semgrep's single primary result location.");
  const location = record(locations[0], "Location");
  const physical = record(location["physicalLocation"], "Physical location");
  const artifact = record(physical["artifactLocation"], "Artifact location");
  return { physical, artifact };
}

function sarifIdentity(
  value: unknown,
  runContext: Record<string, unknown>,
): string {
  const result = record(value, "Semgrep result");
  const supplied = ungatedText(
    record(result["fingerprints"] ?? {}, "Semgrep fingerprints")[
      "matchBasedId/v1"
    ],
  );
  if (supplied) return stableId("semgrep", [supplied]);
  const { physical, artifact } = primarySarifLocation(result);
  const uri = sarifArtifactUri(artifact, runContext);
  if (uri === null)
    throw new Error(
      "Cannot derive a Semgrep CE identity from an indexed or unresolved base-relative artifact URI.",
    );
  const region = record(physical["region"], "Semgrep region");
  const line = position(region["startLine"], "Start line");
  const column = position(region["startColumn"] ?? 1, "Start column");
  return identity(
    requiredText(result["ruleId"], "Semgrep ruleId"),
    uri,
    line,
    column,
    position(region["endLine"] ?? line, "End line"),
    position(region["endColumn"] ?? column, "End column"),
  );
}

export function normalizeSemgrepFindings(
  input: unknown,
  options: Partial<SemgrepImportOptions> = {},
  target: ExternalImportTarget = "cloud",
): ExternalFindings {
  const document = record(input, "Semgrep report");
  if (document["format"] === guardianSelectionFormat) {
    return normalizeGuardianSelection(
      document,
      target,
      options.sourceRepositoryUrl,
      options.sourceRepositories,
    );
  }
  if (document["format"] === "semgrep-platform-findings/v1")
    throw new Error(
      "This Semgrep Platform export uses the retired v1 format. Recollect the findings with cs import semgrep.",
    );
  if (isSemgrepPlatformFormat(document["format"])) {
    return normalizeSemgrepPlatformFindings(
      document,
      options?.sourceRepositoryUrl,
      target,
      options?.sourceRepositories,
    );
  }
  if (document["version"] === "2.1.0" && document["runs"] !== undefined)
    return normalizeSemgrepSarif(
      document,
      { ...options, sourceRepositoryUrl: options?.sourceRepositoryUrl ?? "" },
      target,
    );
  return normalizeSemgrepJson(document, options, target);
}

function semgrepLocation(raw: string) {
  // Semgrep retains the scanner's path spelling after validation.
  return nativeResultPath(raw) === null ? null : raw;
}

function normalizeSemgrepJson(
  document: Record<string, unknown>,
  options: Partial<SemgrepImportOptions>,
  target: ExternalImportTarget,
): ExternalFindings {
  const repositoryUrl = sourceRepository(options);
  requiredText(document["version"], "Semgrep version");
  const {
    results,
    paths: _paths,
    time: _time,
    explanations: _explanations,
    ...context
  } = document;
  const rows = array(results, "Semgrep results");
  if (!rows.length && document["errors"] === undefined)
    throw new Error("An empty Semgrep report must include its errors array.");
  if (optionalArray(document["errors"], "Semgrep errors").length)
    throw new Error(
      "The Semgrep report contains scan errors; supply a successful report before importing findings.",
    );
  return normalizeRecords(
    rows,
    (value) =>
      projectNativeJsonResult(
        parseNativeJsonResult(value, "Semgrep", semgrepLocation),
        {
          origin: "Semgrep",
          repositoryUrl,
          severity,
          reportContext: context,
          target,
        },
      ),
    jsonIdentity,
    target,
  );
}

export function isSemgrepSarifDriver(name: string): boolean {
  return ["semgrep", "semgrep oss", "semgrep pro"].includes(name.toLowerCase());
}

export function normalizeSemgrepSarif(
  input: unknown,
  options: SemgrepImportOptions,
  target: ExternalImportTarget = "cloud",
): ExternalFindings {
  const repositoryUrl = sourceRepository(options);
  const repositoryKey = cloudRepositoryUrlKey(repositoryUrl);
  const verifiedUrls = new Set([repositoryUrl]);
  const entries = readSarifRuns(input, "Semgrep", (context) => {
    for (const { url: declared } of sarifRunRepositories(
      context.run,
      "Semgrep",
    )) {
      if (verifiedUrls.has(declared)) continue;
      if (cloudRepositoryUrlKey(declared) !== repositoryKey)
        throw new Error(
          "SARIF source repository does not match the declared source repository URL.",
        );
      verifiedUrls.add(declared);
    }
    if (
      !isSemgrepSarifDriver(
        requiredText(context.driver["name"], "SARIF producer"),
      )
    )
      throw new Error("Expected a Semgrep SARIF producer.");
    return sarifRunResults(context, "Semgrep");
  });
  return normalizeRecords(
    entries,
    ({ result: value, context }) => {
      const result = record(value, "Semgrep result");
      const properties = record(
        result["properties"] ?? {},
        "Semgrep result properties",
      );
      if (
        properties["exposure"] != null ||
        properties["dependencyPaths"] != null
      )
        throw new Error(
          "This adapter supports Semgrep SAST; Supply Chain reports need separate qualification.",
        );
      const ruleId = requiredText(result["ruleId"], "Semgrep ruleId");
      const selectedRule = context.rulesById.get(ruleId) ?? undefined;
      if (context.rulesById.size > 0 && !selectedRule)
        throw new Error(
          "Semgrep result must reference exactly one rule in its run.",
        );
      const rule = selectedRule?.rule;
      validateSarifRuleReference(result, ruleId, selectedRule, "Semgrep");
      const { physical, artifact } = primarySarifLocation(result);
      const rawPath = sarifArtifactUri(artifact, context.runContext);
      const region = record(physical["region"], "Semgrep region");
      const line = position(region["startLine"], "Start line");
      const column = position(region["startColumn"] ?? 1, "Start column");
      const endLine = position(region["endLine"] ?? line, "End line");
      const endColumn = position(region["endColumn"] ?? column, "End column");
      if (endLine < line || (endLine === line && endColumn < column))
        throw new Error("Semgrep source range ends before it starts.");
      const message = record(result["message"], "Semgrep message");
      const configuration = record(
        rule?.["defaultConfiguration"] ?? {},
        "Rule configuration",
      );
      const level = text(result["level"]) ?? text(configuration["level"]);
      // SARIF collapses severity categories; retain its diagnostic level and all original metadata.
      const mappedSeverity =
        level === "error"
          ? "high"
          : level === "warning"
            ? "medium"
            : level === "note"
              ? "low"
              : "unknown";
      // Native %SRCROOT% values are filesystem paths; direct URIs can name other targets.
      const absoluteUri =
        artifact["uriBaseId"] !== "%SRCROOT%" &&
        typeof artifact["uri"] === "string" &&
        /^[a-z][a-z\d+.-]*:/iu.test(artifact["uri"]);
      const path =
        rawPath === null || absoluteUri ? null : semgrepLocation(rawPath);
      return validateExternalEvidence(
        {
          title: ruleId,
          description:
            text(message["markdown"]) ??
            messageText(message["text"], "Semgrep"),
          severity: mappedSeverity,
          locations: path ? [{ path, line }] : [],
          details: {
            kind: "sast",
            repository: { url: repositoryUrl },
            scanner_origin: "Semgrep",
            rule: { id: ruleId },
            weakness_ids: weaknessIds(
              record(rule?.["properties"] ?? {}, "Rule properties")["tags"],
            ),
            code: {
              end_line: path ? endLine : null,
              snippet: ungatedText(
                record(region["snippet"] ?? {}, "Snippet")["text"],
              ),
            },
            source_status:
              Array.isArray(result["suppressions"]) &&
              result["suppressions"].some((value) => {
                const status = record(value, "Suppression")["status"];
                return status === undefined || status === "accepted";
              })
                ? "suppressed"
                : null,
          },
          source_data: context.sourceData(result, rule),
        },
        target,
      );
    },
    ({ result, context }) => sarifIdentity(result, context.runContext),
    target,
  );
}

/** @internal Read the original file before resolving repository provenance. */
export async function readSemgrepReport(path: string): Promise<unknown> {
  return readScannerJson(path, (json) => {
    // Pick a parser before allocating the findings array. Verify the root:
    // the member can be nested in a native report or escaped in a Platform one.
    const parser = /"format"\s*:\s*"semgrep-platform-findings\/v2"/u.test(json)
      ? parseHostedScannerJson
      : JSON.parse;
    const parsed: unknown = parser(json);
    const requiredParser =
      isRecord(parsed) && parsed["format"] === semgrepPlatformFormat
        ? parseHostedScannerJson
        : JSON.parse;
    return parser === requiredParser ? parsed : requiredParser(json);
  });
}

export async function readSemgrepFindings(
  path: string,
  options: Partial<SemgrepImportOptions> = {},
  target: ExternalImportTarget = "cloud",
): Promise<ExternalFindings> {
  return normalizeSemgrepFindings(
    await readSemgrepReport(path),
    options,
    target,
  );
}