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

7.9 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { z } from "zod";
import { errorMessage } from "./errors.js";
import { bundledPluginRoot, pluginMetadata } from "./runtime.js";
import { normalizeRepository, repositoryRevision } from "./targets.js";
import {
  parseFindingPatch,
  parseFindingVerifications,
  remediationPrompt,
  VerificationModeSchema,
  type FindingPatch,
  type FindingVerification,
} from "./remediation.js";
import {
  ScanExecutionResultSchema,
  type ScanExecutionResult,
} from "./scan-executor.js";
import { VERSION } from "./version.js";

export const HostedRemediationInputSchema = z.strictObject({
  version: z.literal(1),
  operation: z.enum(["patch", "verify"]),
  repository: z.string().min(1),
  revision: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/),
  finding: z.strictObject({
    id: z.string().min(1),
    context: z.string().trim().min(1),
  }),
  instructions: z.string().optional(),
  validationInstructions: z.string().optional(),
  verificationMode: VerificationModeSchema.optional(),
  model: z.string().min(1),
  reasoningEffort: z.string(),
  identity: z.strictObject({
    runId: z.string().min(1),
    attemptId: z.string().min(1),
    buildId: z.string().min(1),
  }),
});

export type HostedRemediationInput = z.infer<
  typeof HostedRemediationInputSchema
>;

export interface RemediationExecutionRequest {
  version: 1;
  requestId: string;
  operation: HostedRemediationInput["operation"];
  repository: string;
  revision: string;
  identity: HostedRemediationInput["identity"];
  findingId: string;
  prompt: string;
  model: string;
  reasoningEffort: HostedRemediationInput["reasoningEffort"];
  sandbox: "workspace-write" | "read-only";
  runtime: { pluginRoot: string; pluginVersion: string };
}

export type RemediationExecutionResult = ScanExecutionResult;
export type RemediationExecutionEvent = Readonly<Record<string, unknown>>;

export interface RemediationExecutor {
  /** Submit once and settle cancellation with the host's recorded receipt. */
  run(
    request: RemediationExecutionRequest,
    options: {
      signal: AbortSignal;
      onEvent?: (event: RemediationExecutionEvent) => void;
    },
  ): Promise<RemediationExecutionResult>;
}

export interface HostedRemediationOptions {
  executor: RemediationExecutor;
  signal?: AbortSignal;
  onEvent?: (event: RemediationExecutionEvent) => void;
}

export interface HostedRemediationResult {
  version: 1;
  operation: HostedRemediationInput["operation"];
  repository: string;
  revision: string;
  identity: HostedRemediationInput["identity"];
  findingId: string;
  status: RemediationExecutionResult["status"];
  provenance: { cliVersion: string; pluginVersion: string; buildId: string };
  execution?: RemediationExecutionResult;
  patch?: FindingPatch;
  verification?: FindingVerification;
  error?: { code: string; message: string; reason?: "revision_changed" };
}

export class HostedRemediationPreparationError extends Error {
  readonly reason = "revision_mismatch";
  constructor() {
    super("Checkout does not match the frozen revision.");
    this.name = "HostedRemediationPreparationError";
  }
}

/**
 * Run one patch or verification through the supplied host executor.
 * The host prepares the candidate checkout, enforces the requested sandbox,
 * and owns patch artifacts, durable attempts, usage, and reconciliation.
 */
export async function runHostedRemediation(
  value: HostedRemediationInput,
  options: HostedRemediationOptions,
): Promise<HostedRemediationResult> {
  const input = HostedRemediationInputSchema.parse(value);
  const signal = options.signal ?? new AbortController().signal;
  signal.throwIfAborted();
  const repository = await normalizeRepository(input.repository, signal);
  if ((await repositoryRevision(repository, signal)) !== input.revision)
    throw new HostedRemediationPreparationError();
  const pluginRoot = await bundledPluginRoot();
  const { version: pluginVersion } = await pluginMetadata(pluginRoot);
  let prompt = await remediationPrompt({
    operation: input.operation,
    pluginRoot,
    contents: [
      { occurrenceId: input.finding.id, context: input.finding.context },
    ],
    structuredPatch: true,
    verificationIds: [input.finding.id],
    instructions: input.instructions,
    validationInstructions: input.validationInstructions,
    verificationMode: input.verificationMode,
  });
  if (input.operation === "patch") {
    prompt = [
      "Work in the supplied checkout and leave all patch edits uncommitted for the host to capture, even if repository or validation instructions ask you to commit or use a separate worktree.",
      `Keep HEAD at the pinned revision ${input.revision}. Before returning, check git rev-parse HEAD and git status --short to confirm the revision and the files you report.`,
      prompt,
    ].join("\n");
  }
  const target = {
    version: 1 as const,
    operation: input.operation,
    repository,
    revision: input.revision,
    identity: input.identity,
    findingId: input.finding.id,
  };
  const request: RemediationExecutionRequest = {
    ...target,
    requestId: randomUUID(),
    prompt,
    model: input.model,
    reasoningEffort: input.reasoningEffort,
    sandbox: input.operation === "verify" ? "read-only" : "workspace-write",
    runtime: { pluginRoot, pluginVersion },
  };
  const base = {
    ...target,
    provenance: {
      cliVersion: VERSION,
      pluginVersion,
      buildId: input.identity.buildId,
    },
  };
  let execution: RemediationExecutionResult | undefined;
  const onEvent = (event: RemediationExecutionEvent) => {
    void Promise.resolve()
      .then(() => options.onEvent?.(event))
      .catch(() => {});
  };
  try {
    signal.throwIfAborted();
    execution = await options.executor.run(request, { signal, onEvent });
    ScanExecutionResultSchema.parse(execution);
    if (execution.requestId !== request.requestId)
      throw new Error(
        "Execution receipt does not match the remediation request.",
      );
    if (execution.status !== "completed")
      return { ...base, status: execution.status, execution };
    const revision = await repositoryRevision(repository);
    if (revision === null)
      throw new Error("Could not resolve HEAD after remediation execution.");
    if (revision !== input.revision) {
      return {
        ...base,
        status: "failed",
        execution,
        error: {
          code: "INVALID_RESULT",
          reason: "revision_changed",
          message:
            "Checkout changed from the frozen revision during execution.",
        },
      };
    }
    const response = execution.finalResponse ?? "";
    const outcome =
      input.operation === "patch"
        ? { patch: parseFindingPatch(response, input.finding.id) }
        : {
            verification: parseHostedVerification(response, input.finding.id),
          };
    return { ...base, status: "completed", execution, ...outcome };
  } catch (error) {
    return {
      ...base,
      status: signal.aborted && execution === undefined ? "canceled" : "failed",
      ...(execution === undefined ? {} : { execution }),
      error: {
        code: execution === undefined ? "EXECUTION_FAILED" : "INVALID_RESULT",
        message: errorMessage(error),
      },
    };
  }
}

function parseHostedVerification(response: string, findingId: string) {
  const verification = parseFindingVerifications(response, [findingId])[0]!;
  if (verification.status !== "fixed") return verification;
  // Recognize SDK 0.6.0 checks in the original report without requiring them.
  const checks = z
    .array(
      z.object({
        name: z.string().trim().min(1),
        status: z.enum(["passed", "failed", "not_run"]),
        evidence: z.string().trim().min(1),
        command: z.string().trim().min(1).optional(),
      }),
    )
    .safeParse(JSON.parse(response).results[0].checks);
  if (checks.success && checks.data.some(({ status }) => status !== "passed")) {
    throw new Error(
      "A fixed verification result contradicts a failed or unrun required check.",
    );
  }
  return verification;
}