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

9.5 KB
Raw Blame
import { isNativeError, isNumberObject } from "node:util/types";
import { CodexSecurityError } from "./errors.js";
import type { LocalExternalImportOptions } from "./external-findings-import.js";
import {
  checkEmittedJsonNumber,
  checkReportNumber,
  requireCloudEvidenceDepth,
  requireJsonNumber,
  type ExternalImportTarget,
} from "./external-import-contract.js";
import type { ExternalFindingEvidence } from "./external-import-models.js";

/** A provider occurrence and its evidence, independent of a Codex assessment. */
export interface ExternalFinding {
  source_finding_id: string;
  evidence: ExternalFindingEvidence;
}

/** Repository provenance retained by a reader outside the published evidence. */
export interface ExternalSourceRepository {
  url: string;
  platform?: "github" | "gitlab";
}

export function snapshotSourceRepositories(
  references: readonly ExternalSourceRepository[] = [],
): ExternalSourceRepository[] {
  return references.map(({ url, platform }) => ({ url, platform }));
}

export interface ExternalFindings {
  read: number;
  /** Reader-retained run metadata, including diagnostics for empty reports. */
  report?: Record<string, unknown>;
  findings: ExternalFinding[];
  excluded: {
    position: number;
    source_finding_id: string | null;
    reason: string;
  }[];
}

export function hasNoExternalRecords(input: ExternalFindings): boolean {
  return input.read === 0 && !input.findings.length && !input.excluded.length;
}

/** Classify a reader selection before deciding whether to store, publish, or report it. */
export function externalImportDisposition(
  input: ExternalFindings,
): "ready" | "empty" | "excluded" | "failed" {
  if (input.findings.length) return "ready";
  const errors = input.report?.["errors"];
  if (Array.isArray(errors) && errors.length) return "failed";
  if (hasNoExternalRecords(input)) return "empty";
  return input.read === input.excluded.length ? "excluded" : "failed";
}

/** No findings can be imported. The selection retains every reader exclusion and diagnostic. */
export class NoPublishableFindingsError extends CodexSecurityError {
  readonly summary: string;

  constructor(public readonly selection: ExternalFindings) {
    const diagnostics = reportForJson(selection.report)?.["errors"];
    const summary =
      externalImportDisposition(selection) === "empty"
        ? "No supported findings are ready to publish: the report is empty."
        : `No supported findings are ready to publish (${selection.read} read, ${selection.excluded.length} excluded).${Array.isArray(diagnostics) && diagnostics.length ? ` Scanner diagnostics: ${JSON.stringify(diagnostics)}` : ""}`;
    const reasons = selection.excluded.map(
      (item) => `Item ${item.position}: ${item.reason}`,
    );
    super([summary, ...reasons].join(" "));
    this.summary = summary;
  }
}

export function reportForJson(report: ExternalFindings["report"]) {
  const errors = report?.["errors"];
  if (!Array.isArray(errors)) return report;
  const json = JSON.stringify(errors, (_key, entry: unknown) =>
    entry instanceof Error ? { ...entry, message: entry.message } : entry,
  );
  return { ...report, errors: JSON.parse(json) as unknown[] };
}

const isScannerError = Error.isError ?? isNativeError;
export const nativeErrorStackGetter = Object.getOwnPropertyDescriptor(
  new Error(),
  "stack",
)?.get;

function cloneScannerDiagnostic(source: Error): Error {
  const message = Object.getOwnPropertyDescriptor(source, "message");
  const stack = Object.getOwnPropertyDescriptor(source, "stack");
  try {
    if (
      (!message || Object.hasOwn(message, "value")) &&
      (!stack?.get || stack.get === nativeErrorStackGetter)
    )
      return structuredClone(source);
    // Keep the native error type and data-valued cause without running a
    // caller-supplied message or stack getter while restoring diagnostics.
    const cause = Object.getOwnPropertyDescriptor(source, "cause");
    const clean = new Error(message?.value, { cause: cause?.value });
    const name = Object.getOwnPropertyDescriptor(
      Object.getPrototypeOf(source),
      "name",
    )?.value;
    if (typeof name === "string") clean.name = name;
    if (!message?.get && nativeErrorStackGetter) {
      const nativeStack: unknown = nativeErrorStackGetter.call(source);
      if (typeof nativeStack === "string") clean.stack = nativeStack;
    }
    return structuredClone(clean);
  } catch {
    // A noncloneable cause does not prevent JSON export.
    return new Error(message?.value);
  }
}

/** @internal Capture fresh input once, so preview, limits and storage use the same JSON. */
export function snapshotNormalizedFindings<T extends Partial<ExternalFindings>>(
  input: T,
  checkEvidenceNumber = (value: number) => requireJsonNumber(value, "Evidence"),
  target: ExternalImportTarget = "local",
  provider?: string,
): T {
  const fields = new Map<string, unknown>();
  const errors: { path: string[]; error: Error }[] = [];
  let root: unknown;

  function captureField(field: string, observed: unknown): string | undefined {
    const parents: { key: string; value: object }[] = [];
    // The outer traversal already called this field's toJSON with its real key.
    // Returning that value from the wrapper keeps JSON from calling it twice.
    return JSON.stringify(
      { toJSON: () => observed },
      function (this: object, key, value: unknown) {
        while (parents.length && parents.at(-1)!.value !== this) parents.pop();
        const evidence = field === "findings" && parents[2]?.key === "evidence";
        if (evidence && target === "cloud")
          requireCloudEvidenceDepth(parents.length - 2, this, value);
        if (isNumberObject(value)) value = +value;
        if (field === "report") checkReportNumber(value);
        if (evidence) checkEmittedJsonNumber(value, checkEvidenceNumber);
        if (value !== null && typeof value === "object") {
          if (value === root) {
            const path = [field, ...parents.slice(1).map((p) => p.key)];
            if (parents.length) path.push(key);
            throw new TypeError(
              `Converting circular structure to JSON at ${JSON.stringify(path)}`,
            );
          }
          if (
            field === "report" &&
            parents[1]?.key === "errors" &&
            Array.isArray(parents[1].value) &&
            isScannerError(value)
          ) {
            errors.push({
              path: [field, ...parents.slice(1).map((p) => p.key), key],
              error: value,
            });
          }
          parents.push({ key, value });
        }
        return value;
      },
    );
  }

  // Capture each member in native property order. A report and a findings
  // payload can each fit in a string while their combined JSON does not.
  const envelope = JSON.stringify(
    input,
    function (this: object, field, value: unknown) {
      if (this !== root) {
        root = value;
        return value;
      }
      const json = captureField(field, value);
      if (json === undefined) return undefined;
      fields.set(field, JSON.parse(json));
      return null;
    },
  );
  const result = JSON.parse(envelope);
  for (const [key, value] of fields) result[key] = value;
  for (const { path, error: source } of errors) {
    const key = path.pop()!;
    let parent = result as unknown as Record<string, unknown>;
    for (const field of path) parent = parent[field] as Record<string, unknown>;
    const error = cloneScannerDiagnostic(source);
    Object.defineProperties(
      error,
      Object.getOwnPropertyDescriptors(parent[key] as object),
    );
    parent[key] = error;
  }
  // Reader scope can live on a getter. Do not evaluate enumerable getters twice.
  if (provider !== undefined) {
    const keys = ["sourceFormat", "semgrepPlatformScope", "snykRestContext"];
    if (provider === "semgrep" || provider === "snyk")
      keys.push("sourceRepositoryUrl", "sourceRepositoryPlatform");
    for (const key of keys)
      if (
        !(key in result) &&
        key in input &&
        !Object.prototype.propertyIsEnumerable.call(input, key)
      )
        result[key] = structuredClone(Reflect.get(input, key));
  }
  return result;
}

/** @internal Clone owned values without serializing the evidence again in every preview view. */
export function cloneImportPreview<T extends ExternalFindings>(input: T): T {
  if (input.report === undefined) return structuredClone(input);
  return {
    ...structuredClone({ ...input, report: undefined }),
    ...snapshotNormalizedFindings({ report: input.report }),
  };
}

/** Capture the caller's import settings before reading an export or resolving its destination. */
export function snapshotImportOptions<P extends string>({
  repository,
  provider,
  sourceKey,
  sourceRepositoryUrl,
  trivyScanRoot,
  inspectorProjectMap,
}: Omit<LocalExternalImportOptions, "provider"> & { provider: P }) {
  if (provider === "trivy" && sourceRepositoryUrl !== undefined)
    throw new CodexSecurityError(
      "Trivy reads repository provenance from the report; do not supply --source-repository-url.",
    );
  if (trivyScanRoot !== undefined && provider !== "trivy")
    throw new CodexSecurityError(
      "--trivy-scan-root applies only to --provider trivy.",
    );
  if (inspectorProjectMap !== undefined && provider !== "inspector")
    throw new CodexSecurityError(
      "An Inspector project map requires the inspector provider.",
    );
  return {
    repository,
    provider,
    sourceKey,
    sourceRepositoryUrl,
    trivyScanRoot,
    inspectorProjectMap: inspectorProjectMap && new Map(inspectorProjectMap),
  };
}