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

5.0 KB
Raw Blame
import { loadContractWithScanDirectory } from "./contract.js";
import { CodexSecurityError } from "./errors.js";
import { FindingsClient, type FindingsRequest } from "./findings-client.js";
import type { Finding } from "./models.js";
import { bundledPluginRoot, type runWorkbench } from "./runtime.js";
import {
  FindingWorkflow,
  scanArtifactDigest,
  workflowDestination,
} from "./finding-workflow.js";
import {
  PublicationTelemetryRecorder,
  type PublicationTelemetry,
  type PublicationTelemetryObserver,
} from "./publication-telemetry.js";

export interface PublishScanToCustomOptions {
  /** Resume publication within the named local findings workflow. */
  workflowId?: string;
  /** Findings API base URL, such as http://localhost:3000. */
  findingsUrl: string;
  /** Validate and preview the upload without making an HTTP request. */
  dryRun?: boolean;
  expectedScanId?: string;
  signal?: AbortSignal;
  /** Best-effort content-free outcome accounting, including preparation failures. */
  onTelemetry?: PublicationTelemetryObserver;
}

export interface CustomPublicationResult {
  scanId: string;
  repositoryId: string;
  findingIds: string[];
  findingCount: number;
  dryRun?: true;
  findings?: Finding[];
  telemetry?: PublicationTelemetry;
}

interface CustomPublicationDependencies {
  fetch?: FindingsRequest;
  environment?: NodeJS.ProcessEnv;
  runWorkbench?: typeof runWorkbench;
}

/** Publish complete, sealed findings to a findings API without changing scan artifacts. */
export async function publishScanToCustom(
  scanDirectory: string,
  options: PublishScanToCustomOptions,
): Promise<CustomPublicationResult> {
  return await publishScanToCustomInternal(scanDirectory, options);
}

/** @internal */
export async function publishScanToCustomInternal(
  scanDirectory: string,
  options: PublishScanToCustomOptions,
  dependencies: CustomPublicationDependencies = {},
): Promise<CustomPublicationResult> {
  const telemetry = new PublicationTelemetryRecorder(
    "custom",
    options.onTelemetry,
  );
  try {
    const result = await publishScanToCustomAttempt(
      scanDirectory,
      options,
      dependencies,
      telemetry,
    );
    telemetry.notify(result.telemetry!);
    return result;
  } catch (error) {
    telemetry.notifyFailure(options);
    throw error;
  }
}

async function publishScanToCustomAttempt(
  scanDirectory: string,
  options: PublishScanToCustomOptions,
  dependencies: CustomPublicationDependencies,
  telemetry: PublicationTelemetryRecorder,
): Promise<CustomPublicationResult> {
  const { contract, scanDirectory: canonicalDirectory } =
    await loadContractWithScanDirectory(scanDirectory, {
      pluginRoot: await bundledPluginRoot(),
      signal: options.signal,
      expectedScanId: options.expectedScanId,
    });
  const { manifest, findings } = contract;
  telemetry.counts.selected = findings.findings.length;
  if (findings.findings.length === 0 && options.workflowId === undefined) {
    throw new CodexSecurityError(
      "The completed scan has no findings to publish.",
    );
  }
  const repositoryId = manifest.scan.target.targetId;
  let invoked = false;
  const publish = async (): Promise<CustomPublicationResult> => {
    invoked = true;
    const client = options.dryRun
      ? null
      : new FindingsClient(
          options.findingsUrl,
          options.signal,
          dependencies.fetch,
        );
    if (client !== null) {
      telemetry.attempted = true;
      telemetry.counts.submitted = findings.findings.length;
      // The bulk API acknowledges IDs; it does not distinguish inserts from upserts.
      telemetry.counts.created = null;
      telemetry.counts.reused = null;
      telemetry.counts.acknowledged = null;
      telemetry.counts.failed = null;
      telemetry.outcome = "indeterminate";
    }
    const findingIds =
      client === null
        ? findings.findings.map((finding) => finding.findingId)
        : await client.publish(findings.findings, repositoryId);
    telemetry.outcome = options.dryRun ? "preview" : "completed";
    telemetry.counts.acknowledged = options.dryRun ? 0 : findingIds.length;
    telemetry.counts.failed = 0;
    return {
      scanId: manifest.scan.id,
      repositoryId,
      findingIds,
      findingCount: findingIds.length,
      ...(options.dryRun ? { dryRun: true, findings: findings.findings } : {}),
      telemetry: telemetry.snapshot(),
    };
  };
  if (options.workflowId === undefined || options.dryRun)
    return await publish();
  const workflow = new FindingWorkflow(
    options.workflowId,
    dependencies.environment,
    dependencies.runWorkbench,
  );
  await workflow.protectArtifacts(canonicalDirectory);
  await workflow.bind({
    scanId: manifest.scan.id,
    scanDir: canonicalDirectory,
    artifactDigest: scanArtifactDigest(contract),
    destination: workflowDestination(options.findingsUrl),
  });
  await workflow.complete("scan", null);
  const result = await workflow.run("publish", publish);
  if (invoked) return result;
  telemetry.counts.reused = result.findingCount;
  return { ...result, telemetry: telemetry.snapshot("completed") };
}