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

8.0 KB
Raw Blame
import { listenForAbort } from "./cli-signals.js";
import type { CodexSecurity, ScanAuthMode } from "./api.js";
import type { BulkScanPrompt } from "./bulk-scan-discovery.js";
import type { CodexSecurityConfig } from "./config.js";
import { formatScanCost } from "./cost-model.js";
import { errorMessage } from "./errors.js";
import {
  formatSecurityPolicyText as display,
  type SecurityPolicyOptions,
  type SecurityPolicyStage,
} from "./security-policy.js";

type SignalName = "SIGINT" | "SIGTERM";
type Output = { write(value: string): unknown };
export type PolicyPrompt = Pick<BulkScanPrompt, "isInteractive" | "input">;
export type PolicySecurity = Pick<
  CodexSecurity,
  "generatePolicy" | "preflightPolicy" | "previewPolicy" | "close"
>;

export interface PolicyCommandOptions {
  repository: string;
  config: CodexSecurityConfig;
  generation: SecurityPolicyOptions;
  headless: boolean;
  dryRun: boolean;
  format: string;
  explicitOutput: boolean;
}

export interface PolicyCommandDependencies {
  createSecurity(config: CodexSecurityConfig): PolicySecurity;
  chooseAuthentication(
    config: CodexSecurityConfig,
    auth: ScanAuthMode | undefined,
    signal: AbortSignal,
  ): Promise<ScanAuthMode | undefined>;
  prompt: PolicyPrompt;
  environment: NodeJS.ProcessEnv;
  errorOutput: Output;
  now(): number;
  addSignalListener(signal: SignalName, listener: () => void): void;
  removeSignalListener(signal: SignalName, listener: () => void): void;
  forceExit(signal: SignalName): void;
}

const STAGES: Record<SecurityPolicyStage, string> = {
  architecture: "[1/3] Reading the source",
  threat_model: "[2/3] Writing the threat model",
  policy: "[3/3] Drafting SECURITY.md",
};

export async function runPolicyCommand(
  options: PolicyCommandOptions,
  dependencies: PolicyCommandDependencies,
): Promise<{
  exitCode: number;
  data?: Record<string, unknown>;
  markdown?: string;
  error?: string;
}> {
  const { errorOutput, prompt } = dependencies;
  const controller = new AbortController();
  const interactive =
    !options.headless &&
    options.format === "toon" &&
    dependencies.environment["CI"] === undefined &&
    prompt.isInteractive();
  const started = dependencies.now();
  let security: PolicySecurity | undefined;
  let outputDir: string | undefined;
  const write = (message: string): void => {
    try {
      errorOutput.write(`${message}\n`);
    } catch {}
  };
  const removeSignalListeners = listenForAbort(
    dependencies,
    controller,
    (signal) => dependencies.forceExit(signal),
  );
  try {
    const auth =
      interactive && !options.dryRun
        ? await dependencies.chooseAuthentication(
            options.config,
            options.generation.auth,
            controller.signal,
          )
        : options.generation.auth;
    controller.signal.throwIfAborted();
    security = dependencies.createSecurity(options.config);
    if (options.dryRun) {
      const preflight = await security.preflightPolicy(options.repository, {
        ...options.generation,
        signal: controller.signal,
      });
      controller.signal.throwIfAborted();
      return {
        exitCode: 0,
        data: {
          ...preflight,
          dryRun: true,
        },
      };
    }
    const draft = await security.generatePolicy(options.repository, {
      ...options.generation,
      auth,
      signal: controller.signal,
      onOutputDirReady: (directory) => {
        outputDir = directory;
        write(`Policy artifacts: ${display(directory)}`);
      },
      onStage: (stage) => write(STAGES[stage]),
      onWarning: (warning) =>
        write(`codex-security: ${display(errorMessage(warning))}`),
      ...(interactive
        ? {
            answerQuestions: async (
              questions: readonly string[],
              signal: AbortSignal,
            ) => {
              write(
                "Answer what you know; leave other answers blank for later review.",
              );
              const answers: string[] = [];
              for (const question of questions) {
                signal.throwIfAborted();
                const answer = await prompt.input(
                  display(question),
                  undefined,
                  signal,
                );
                if (answer.trim()) answers.push(`${question}\n${answer}`);
              }
              return answers.join("\n\n");
            },
          }
        : {}),
    });
    controller.signal.throwIfAborted();
    const cost = draft.cost;
    const changed = draft.previousContent !== draft.content;
    const humanOutput = options.format === "toon" && !options.explicitOutput;
    if (humanOutput) {
      let diff: string;
      try {
        diff = await security.previewPolicy(draft, {
          signal: controller.signal,
        });
      } catch (error) {
        controller.signal.throwIfAborted();
        diff = "Preview unavailable. Review the saved draft.";
        write(
          `codex-security: Could not preview the policy: ${display(errorMessage(error))}`,
        );
      }
      const preview = [
        `\nPolicy target: ${display(draft.targetPath)}`,
        diff.replace(/\n$/u, "") || "SECURITY.md is already up to date.",
        ...(draft.reviewNotes.length === 0
          ? []
          : [
              "\nReview notes:",
              ...draft.reviewNotes.map((note) => `- ${display(note)}`),
            ]),
      ].join("\n");
      write(preview);
    }
    controller.signal.throwIfAborted();
    const status = changed ? "draft" : "unchanged";
    if (humanOutput) {
      write(`\nDraft: ${display(draft.draftPath)}`);
      write(`Architecture: ${display(draft.specificationPath)}`);
      if (draft.threatModelPath !== null)
        write(`Threat model: ${display(draft.threatModelPath)}`);
      if (changed)
        write(
          "No repository files changed. Review the draft, then copy only SECURITY.md to the Policy target shown.",
        );
    }
    const seconds = Math.max(0, (dependencies.now() - started) / 1000);
    write(
      `Policy generation finished in ${seconds.toFixed(1)}s${cost === null ? "" : ` (estimated cost: ${formatScanCost(cost)})`}.`,
    );
    return {
      exitCode: 0,
      markdown: draft.content,
      data: {
        status,
        repository: draft.repository,
        scope: draft.scope,
        targetPath: draft.targetPath,
        outputDir: draft.outputDir,
        draftPath: draft.draftPath,
        specificationPath: draft.specificationPath,
        threatModelPath: draft.threatModelPath,
        threatModel: draft.threatModel,
        customPlugin: draft.customPlugin,
        reviewNotes: draft.reviewNotes,
        cost,
      },
    };
  } catch (error) {
    const signal =
      controller.signal.reason ??
      (error instanceof Error && error.name === "ExitPromptError"
        ? "SIGINT"
        : undefined);
    const exitCode = signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 2;
    const message =
      signal === "SIGINT"
        ? "Policy generation canceled by Ctrl-C."
        : signal === "SIGTERM"
          ? "Policy generation terminated by SIGTERM."
          : display(errorMessage(error));
    write(`codex-security: ${message}`);
    if (outputDir !== undefined)
      write(`Saved artifacts: ${display(outputDir)}`);
    return {
      exitCode,
      error: message,
    };
  } finally {
    removeSignalListeners();
    try {
      await security?.close();
    } catch (error) {
      write(
        `codex-security: Could not clean up the policy runtime: ${display(errorMessage(error))}`,
      );
    }
  }
}

export function policyDisplayData(
  data: Record<string, unknown> | undefined,
): Record<string, unknown> | undefined {
  const displayValue = (value: unknown): unknown => {
    if (typeof value === "string") return display(value);
    if (Array.isArray(value)) return value.map(displayValue);
    if (value !== null && typeof value === "object")
      return Object.fromEntries(
        Object.entries(value).map(([key, item]) => [key, displayValue(item)]),
      );
    return value;
  };
  return data === undefined
    ? undefined
    : (displayValue(data) as Record<string, unknown>);
}