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.5 KB
Raw Blame
import { realpath } from "node:fs/promises";
import type { main } from "../src/cli.js";
import type {
  CodexSecurity,
  CodexSecurityConfig,
  CoverageDocument,
  FindingsDocument,
  JsonObject,
  ScanActivity,
  ScanCost,
  ScanManifest,
  ScanOptions,
  ScanPreflight,
  ScanProgress,
  ScanWorkerStatus,
  SeverityLevel,
  ValidationOptions,
  ValidationResult,
} from "../src/index.js";
import { CodexSecurityError, ScanResult } from "../src/index.js";
import type { UpdateNotice } from "../src/version.js";
import { throwing } from "./support/errors.js";

type MainDependencies = NonNullable<Parameters<typeof main>[3]>;

export type OnCodex = (
  ...arguments_: Parameters<MainDependencies["runCodex"]>
) => number | Promise<number>;

export const SYNTHETIC_CREDENTIALS = [
  "sk-proj-SYNTHETIC_KEY_123",
  "Bearer SYNTHETIC_TOKEN_123",
  "Authorization: Basic SYNTHETIC_BASIC_123",
  "Authorization: Token SYNTHETIC_HEADER_TOKEN_123",
  "Authorization: Bearer%20SYNTHETIC%2FENCODED%2BTOKEN_123",
  "Authorization%3A%20Bearer%20SYNTHETIC_FULLY_ENCODED_TOKEN_123",
  "https://SYNTHETIC_USER:[email protected]/private",
  "ssh://SYNTHETIC_USER:[email protected]/private",
  "git+ssh://SYNTHETIC_USER:[email protected]/private",
  "github_pat_SYNTHETIC_GITHUB_PAT_123",
  "ghs_SYNTHETIC_GITHUB_TOKEN_123",
  "OPENAI_API_KEY=SYNTHETIC_OPENAI_VALUE_123",
  "CODEX_API_KEY=SYNTHETIC_CODEX_VALUE_123",
  "CODEX_ACCESS_TOKEN=SYNTHETIC_CODEX_ACCESS_TOKEN_123",
  "GITHUB_TOKEN=SYNTHETIC_GITHUB_VALUE_123",
  "GH_TOKEN=SYNTHETIC_GH_VALUE_123",
  '{"OPENAI_API_KEY":"SYNTHETIC_JSON_OPENAI_123","CODEX_API_KEY":"SYNTHETIC_JSON_CODEX_123"}',
  '{\\"OPENAI_API_KEY\\":\\"SYNTHETIC_ESCAPED_OPENAI_123\\",\\"CODEX_API_KEY\\":\\"SYNTHETIC_ESCAPED_CODEX_123\\"}',
  '{"refresh_token":"SYNTHETIC_REFRESH_TOKEN_123","id_token":"SYNTHETIC_ID_TOKEN_123","clientSecret":"SYNTHETIC_CLIENT_SECRET_123","dbPassword":"SYNTHETIC_PASSWORD_123","passwd":"SYNTHETIC_PASSWD_123"}',
  '{\\"refreshToken\\":\\"SYNTHETIC_ESCAPED_REFRESH_123\\",\\"idToken\\":\\"SYNTHETIC_ESCAPED_ID_123\\",\\"clientSecret\\":\\"SYNTHETIC_ESCAPED_SECRET_123\\",\\"password\\":\\"SYNTHETIC_ESCAPED_PASSWORD_123\\"}',
  "AWS_SECRET_ACCESS_KEY=SYNTHETIC_AWS_SECRET_123",
  "AWS_ACCESS_KEY_ID=SYNTHETIC_AWS_ID_123",
  "AWS_SESSION_TOKEN=SYNTHETIC_AWS_SESSION_123",
  "NODE_AUTH_TOKEN=SYNTHETIC_NODE_AUTH_123",
  "NPM_TOKEN=SYNTHETIC_NPM_TOKEN_123",
  "OPENAI_API_KEY=sk-proj-SYNTHETIC_NAMED_OPENAI_123",
  "GITHUB_TOKEN=ghs_SYNTHETIC_NAMED_GITHUB_123",
  "NPM_TOKEN=npm_SYNTHETIC_NAMED_NPM_123",
  "ACTIONS_ID_TOKEN_REQUEST_TOKEN=SYNTHETIC_ACTIONS_TOKEN_123",
  "ACTIONS_RUNTIME_TOKEN=SYNTHETIC_ACTIONS_RUNTIME_123",
  "GITLAB_TOKEN=SYNTHETIC_GITLAB_TOKEN_123",
  "HF_TOKEN=SYNTHETIC_HF_TOKEN_123",
  "SLACK_BOT_TOKEN=SYNTHETIC_SLACK_TOKEN_123",
  "//registry.npmjs.org/:_authToken=SYNTHETIC_NPMRC_TOKEN_123",
  "x-api-key: SYNTHETIC_HEADER_KEY_123",
  "access_token=SYNTHETIC_ACCESS_TOKEN_123",
  "npm_SYNTHETIC_BARE_TOKEN_123",
  "https://example.test/?token=SYNTHETIC_QUERY_123&safe=1",
  "https://example.test/?credential=SYNTHETIC_CREDENTIAL_123&safe=1",
  "https://example.test/?AWS_ACCESS_KEY_ID=SYNTHETIC_QUERY_AWS_ID_123&safe=1",
  "https://example.test/?AWS%5FACCESS%5FKEY%5FID=SYNTHETIC_ENCODED_AWS_ID_123&AWS%2DACCESS%2DKEY%2DID=SYNTHETIC_ENCODED_AWS_DASH_ID_123&safe=1",
  "https://example.test/?service-api-key=SYNTHETIC_QUERY_API_KEY_123&service-access-token=SYNTHETIC_QUERY_ACCESS_TOKEN_123&service-token=SYNTHETIC_QUERY_TOKEN_123&service-secret=SYNTHETIC_QUERY_SECRET_123&signature=SYNTHETIC_SIGNATURE_123&safe=1",
  "https://example.test/?X-Amz-Signature=SYNTHETIC_AMZ_SIGNATURE_123&X-Amz-Credential=SYNTHETIC_AMZ_CREDENTIAL_123&X-Amz-Security-Token=SYNTHETIC_AMZ_TOKEN_123&safe=1",
  "https://example.test/?X-Goog-Signature=SYNTHETIC_GOOG_SIGNATURE_123&X-Goog-Credential=SYNTHETIC_GOOG_CREDENTIAL_123&safe=1",
  "https://example.test/?sv=2026-01-01&sig=SYNTHETIC_AZURE_SIG_123&safe=1",
  "https://example.test/?password=SYNTHETIC_QUERY_PASSWORD_123&passwd=SYNTHETIC_QUERY_PASSWD_123&safe=1",
  "https://example.test/?oauth.refreshToken=SYNTHETIC_DOTTED_TOKEN_123&auth[token]=SYNTHETIC_BRACKET_TOKEN_123&auth%5BclientSecret%5D=SYNTHETIC_ENCODED_SECRET_123&safe=1",
  "https://example.test/?access_token%3DSYNTHETIC_ENCODED_ACCESS_123&client_secret%3DSYNTHETIC_ENCODED_CLIENT_123&safe=1",
  "https://example.test/?redirect_uri=https%3A%2F%2Finner.test%2Fcb%3Frefresh_token%3DSYNTHETIC_NESTED_REFRESH_123%26password%3DSYNTHETIC_NESTED_PASSWORD_123%26safe%3D1",
].join(" ");

export function capture(isTTY: boolean | null = false): {
  stream: Pick<NodeJS.WriteStream, "write"> &
    Partial<Pick<NodeJS.WriteStream, "isTTY">>;
  text(): string;
} {
  let value = "";
  return {
    stream: {
      ...(isTTY === null ? {} : { isTTY }),
      write(chunk: string | Uint8Array): boolean {
        value += chunk.toString();
        return true;
      },
    },
    text: () => value,
  };
}

export function fakePreflight(
  repository = "/current/repository",
): ScanPreflight {
  return {
    repository,
    target: { kind: "repository", paths: [] },
    mode: "standard",
    outputDir: null,
    authentication: { method: "stored_credentials", verified: false },
    model: "gpt-5.6-sol",
    reasoningEffort: "xhigh",
  };
}

export const savedRecipe = (
  config: JsonObject = {},
  target: JsonObject = { kind: "repository", paths: [] },
) => ({
  scanId: "scan-original",
  recipe: {
    repository: "/original/repository",
    target,
    mode: "standard",
    config,
  },
});

export function fakeResult(
  severityLevels: readonly SeverityLevel[] = [],
  completeness?: "complete" | "partial" | "unknown",
  usage: unknown = null,
): ScanResult {
  const manifest = {
    documentType: "codex-security.scan-manifest",
    schemaVersion: "1.0",
    scan: {
      id: "scan",
      producer: { name: "codex-security-plugin", version: "1.2.3" },
      status: "completed",
      startedAt: "2026-01-01T00:00:00Z",
      completedAt: "2026-01-01T00:00:01Z",
      sealedAt: "2026-01-01T00:00:01Z",
      target: {
        kind: "directory_snapshot",
        targetId: "id",
        displayName: "repo",
      },
      scope: { includePaths: ["."], excludePaths: [] },
      coverageRef: "coverage.json",
      findingsRef: "findings.json",
      artifacts: [],
    },
  } satisfies ScanManifest;
  const findings = {
    documentType: "codex-security.findings",
    schemaVersion: "1.0",
    scanId: "scan",
    findings: severityLevels.map((level) => ({
      severity: { level },
    })) as FindingsDocument["findings"],
  } satisfies FindingsDocument;
  const coverage = {
    documentType: "codex-security.coverage",
    schemaVersion: "1.0",
    scanId: "scan",
    mode: "repository",
    ...(completeness === undefined ? {} : { completeness }),
    inventoryStrategy: "repository",
    includePaths: ["."],
    excludePaths: [],
    surfaces: [],
    explicitExclusions: [],
    deferred: [],
  } satisfies CoverageDocument;
  return new ScanResult({
    manifest,
    findings,
    coverage,
    scanDir: "/tmp/scan",
    threadId: "thread-1",
    turnResult: {
      status: "completed",
      model: "gpt-5.6-sol",
      finalResponse: "done",
      usage,
    },
  });
}

export class FakeSignals {
  readonly listeners = new Map<string, Set<() => void>>();

  public add(signal: string, listener: () => void): void {
    const listeners = this.listeners.get(signal) ?? new Set();
    listeners.add(listener);
    this.listeners.set(signal, listeners);
  }

  public remove(signal: string, listener: () => void): void {
    this.listeners.get(signal)?.delete(listener);
  }

  public emit(signal: string): void {
    for (const listener of this.listeners.get(signal) ?? []) listener();
  }
}

export function dependencies(
  options: {
    onConfig?: (config: CodexSecurityConfig) => void;
    onTurn?: (repository: string, options: ScanOptions) => void;
    onRun?: () => void;
    onInterrupt?: () => void;
    onClose?: () => void | Promise<void>;
    onValidate?: (options: ValidationOptions) => Promise<ValidationResult>;
    onCodex?: OnCodex;
    linearClient?: MainDependencies["linearClient"];
    importGitHubAlerts?: MainDependencies["importGitHubAlerts"];
    importGitHubAdvisories?: MainDependencies["importGitHubAdvisories"];
    onRepositoryCommand?: (
      ...arguments_: Parameters<MainDependencies["runRepositoryCommand"]>
    ) => string | Promise<string>;
    onWorkbench?: (
      args: readonly string[],
      input?: string,
      signal?: AbortSignal,
    ) => JsonObject | Promise<JsonObject>;
    readSavedFindings?: MainDependencies["readSavedFindings"];
    onMatch?: MainDependencies["matchFindings"];
    onUpdateCheck?: (signal: AbortSignal) => Promise<UpdateNotice | undefined>;
    currentDirectory?: string;
    preflight?: ScanPreflight;
    environment?: NodeJS.ProcessEnv;
    signals?: FakeSignals;
    result?: ScanResult;
    activities?: ScanActivity[];
    costUpdates?: ScanCost[];
    scanProgress?: ScanProgress[];
    workerStatuses?: ScanWorkerStatus[];
  } = {},
): MainDependencies {
  const signals = options.signals ?? new FakeSignals();
  const result = options.result ?? fakeResult();
  let scannedRepository: string | undefined;
  const security = {
    run: async (repository: string, runOptions: ScanOptions) => {
      scannedRepository = repository;
      options.onTurn?.(repository, runOptions);
      const signal = runOptions.signal;
      signal?.addEventListener("abort", () => options.onInterrupt?.(), {
        once: true,
      });
      options.onRun?.();
      if (!signal?.aborted) {
        runOptions.onScanStarted?.();
        for (const activity of options.activities ?? []) {
          runOptions.onActivity?.(activity);
        }
        for (const cost of options.costUpdates ?? []) {
          runOptions.onCost?.(cost);
        }
        for (const progress of options.scanProgress ?? []) {
          runOptions.onProgress?.(progress);
        }
        for (const status of options.workerStatuses ?? []) {
          runOptions.onWorkerStatus?.(status);
        }
      }
      return result;
    },
    preflight: async (repository: string, { maxCostUsd }: ScanOptions = {}) =>
      options.preflight ?? {
        ...fakePreflight(repository),
        ...(maxCostUsd === undefined ? {} : { maxCostUsd }),
      },
    validate: async (validationOptions: ValidationOptions) =>
      options.onValidate?.(validationOptions) ?? {
        disposition: "deferred",
        report: "Additional evidence is needed.",
        outputDir: "/tmp/validation",
        threadId: "validation-thread",
      },
    close: async () => await options.onClose?.(),
  } as Pick<CodexSecurity, "run" | "preflight" | "validate" | "close">;
  return {
    createSecurity: (config) => {
      options.onConfig?.(config);
      return security;
    },
    environment: options.environment ?? {},
    checkForUpdate: async (signal) => await options.onUpdateCheck?.(signal),
    currentDirectory: () => options.currentDirectory ?? "/current/repository",
    now: () => 0,
    setInterval: fakeInterval,
    clearInterval: () => {},
    addSignalListener: (signal, listener) => signals.add(signal, listener),
    removeSignalListener: (signal, listener) =>
      signals.remove(signal, listener),
    writeSynchronously: (stream, value) => stream.write(value),
    forceExit: () => {},
    runCodex: async (...args) => (await options.onCodex?.(...args)) ?? 0,
    runRepositoryCommand: async (command, args, repository, commandOptions) =>
      (await options.onRepositoryCommand?.(
        command,
        args,
        repository,
        commandOptions,
      )) ?? (args.includes("--name-only") ? "src/finding-1.ts\0" : ""),
    ...(options.linearClient === undefined
      ? {}
      : { linearClient: options.linearClient }),
    ...(options.importGitHubAdvisories === undefined
      ? {}
      : { importGitHubAdvisories: options.importGitHubAdvisories }),
    ...(options.importGitHubAlerts === undefined
      ? {}
      : { importGitHubAlerts: options.importGitHubAlerts }),
    runWorkbench: async (args, input, signal) =>
      (await options.onWorkbench?.(args, input, signal)) ??
      (args[0] === "get-scan" &&
      args.includes("--check-target") &&
      scannedRepository !== undefined
        ? { scan: { targetPath: await realpath(scannedRepository) } }
        : { scans: [] }),
    readSavedFindings:
      options.readSavedFindings ?? (async () => result.findings.findings),
    matchFindings: async (input, comparisonOptions) =>
      (await options.onMatch?.(input, comparisonOptions)) ?? {
        matches: [],
        uncertain: [],
      },
    exportFindings: async (arguments_) =>
      new TextEncoder().encode(
        arguments_.format === "csv"
          ? "occurrence_id,finding_id\n"
          : arguments_.format === "json"
            ? '{"documentType":"codex-security.findings"}\n'
            : '{"version":"2.1.0"}\n',
      ),
  };
}

export const mustNotInitializeCodex = throwing("must not initialize Codex");

export function fakeSecurity(run: CodexSecurity["run"]) {
  return {
    ...dependencies().createSecurity({}),
    run,
    preflight: async () => fakePreflight(),
  };
}

export function failingSecurity(message: string) {
  return fakeSecurity(async () => {
    throw new CodexSecurityError(message);
  });
}

export function fakeInterval(_callback: () => void): NodeJS.Timeout {
  return {} as NodeJS.Timeout;
}

export const warningResult =
  (message: string, targetChanged = false) =>
  async (_repository: string, options?: ScanOptions) => {
    if (targetChanged)
      options?.onWarning?.(message, { kind: "target_changed" });
    else options?.onWarning?.(message);
    return fakeResult();
  };