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.8 KB
Raw Blame
import { existsSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { z } from "zod";
import { parse as parseToml } from "smol-toml";
import { loadContract, sha256Text as sha256 } from "./contract.js";
import {
  AuthenticationRequiredError,
  CodexSecurityError,
  errorMessage,
} from "./errors.js";
import type { Finding, ScanManifest } from "./models.js";
import {
  CSV_TARGET_ID,
  bindImportedFindings,
  csvRowFinding,
  parseFindingsCsv,
} from "./findings-import.js";
import {
  bundledPluginRoot,
  codexSecurityCredentialAllowsAmbientImport,
  codexSecurityCredentialHome,
  codexSecurityHasStoredFileCredentials,
  credentialHomeUsesFileStorage,
  withCredentialHomeLock,
  expandHome,
} from "./runtime.js";
import { VERSION } from "./version.js";
import { cloudBaseUrl } from "./cloud-endpoint.js";
const CHATGPT_LOGIN_REQUIRED =
  "Cloud publication requires a ChatGPT login already available to Codex Security and saved to a file. Set cli_auth_credentials_store = \"file\" in ~/.codex/config.toml (or $CODEX_HOME/config.toml), run 'codex-security login', then retry.";

const credentialsSchema = z.object({
  auth_mode: z.literal("chatgpt").optional(),
  OPENAI_API_KEY: z.null().optional(),
  tokens: z.object({
    access_token: z.string().trim().min(1),
    account_id: z.string().trim().min(1),
  }),
});

const receiptSchema = z.object({
  status: z.literal("accepted"),
  finding_ids: z.array(z.string().min(1)),
  finding_count: z.number().int().positive(),
});

export interface CloudPublicationResult {
  scanId: string;
  findingIds: string[];
  findingCount: number;
  dryRun?: true;
  findings?: Finding[];
}

interface CloudPublicationDependencies {
  environment?: NodeJS.ProcessEnv;
  fetch?: (url: string, options: RequestInit) => Promise<Response>;
  signal?: AbortSignal;
  dryRun?: boolean;
}

export async function publishScanToCloud(
  scanDirectory: string,
  dependencies: CloudPublicationDependencies & {
    expectedScanId?: string;
  } = {},
): Promise<CloudPublicationResult> {
  const { manifest, findings } = await loadContract(scanDirectory, {
    pluginRoot: await bundledPluginRoot(),
    signal: dependencies.signal,
    expectedScanId: dependencies.expectedScanId,
  });
  if (findings.findings.length === 0) {
    throw new CodexSecurityError(
      "The completed scan has no findings to publish.",
    );
  }
  return publishCloudPayload(manifest.scan, findings.findings, dependencies);
}

export async function publishFindingsCsvToCloud(
  csvPath: string,
  dependencies: CloudPublicationDependencies = {},
): Promise<CloudPublicationResult> {
  dependencies.signal?.throwIfAborted();
  let source: string;
  try {
    source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
      await readFile(csvPath),
    );
  } catch (error) {
    throw new CodexSecurityError(
      `Could not read findings CSV. ${errorMessage(error)}`,
      { cause: error },
    );
  }
  dependencies.signal?.throwIfAborted();
  const rows = parseFindingsCsv(source);
  if (rows.length === 0) {
    throw new CodexSecurityError(
      "Findings CSV must contain at least one finding.",
    );
  }
  const digest = sha256(source);
  const scanId = `scan_csv_${sha256(
    ["codex-security-csv-import/v1", VERSION, source].join("\0"),
  ).slice(0, 24)}`;
  const findings = bindImportedFindings(
    rows.map(csvRowFinding),
    "csv",
    scanId,
    CSV_TARGET_ID,
  );
  const timestamp = "1970-01-01T00:00:00.000Z";
  const findingsDocument = JSON.stringify({
    documentType: "codex-security.findings",
    schemaVersion: "1.0",
    scanId,
    findings,
  });
  const scan: ScanManifest["scan"] = {
    id: scanId,
    producer: { name: "codex-security-cli", version: VERSION },
    status: "completed",
    startedAt: timestamp,
    completedAt: timestamp,
    sealedAt: timestamp,
    target: {
      kind: "directory_snapshot",
      targetId: CSV_TARGET_ID,
      displayName: "findings.csv",
      snapshotDigest: `codex-security-snapshot/v1:sha256:${digest}`,
    },
    scope: {
      includePaths: ["."],
      excludePaths: [],
      summary: "Findings imported from a Codex Security CSV export.",
    },
    mode: "repository",
    review: { excludedPaths: [] },
    findingsRef: "findings.json",
    artifacts: [
      {
        path: "findings.json",
        sha256: sha256(findingsDocument),
        mediaType: "application/json",
      },
      {
        path: "findings.csv",
        sha256: digest,
        mediaType: "text/csv",
      },
    ],
  };
  return publishCloudPayload(scan, findings, dependencies);
}

async function publishCloudPayload(
  scan: ScanManifest["scan"],
  findings: Finding[],
  dependencies: CloudPublicationDependencies,
): Promise<CloudPublicationResult> {
  dependencies.signal?.throwIfAborted();
  if (dependencies.dryRun) {
    return {
      scanId: scan.id,
      findingIds: [],
      findingCount: findings.length,
      dryRun: true,
      findings,
    };
  }
  const environment = dependencies.environment ?? process.env;
  const publishUrl =
    environment["CODEX_SECURITY_CLOUD_PUBLISH_URL"]?.trim() ||
    `${cloudBaseUrl(environment)}/cli/findings`;
  const credentials = await readCloudCredentials(
    environment,
    dependencies.signal,
  );
  const timeout = AbortSignal.timeout(30_000);
  const signal = dependencies.signal
    ? AbortSignal.any([dependencies.signal, timeout])
    : timeout;
  let response: Response;
  try {
    response = await (dependencies.fetch ?? globalThis.fetch)(publishUrl, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${credentials.access_token}`,
        "ChatGPT-Account-ID": credentials.account_id,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        schemaVersion: "1.0",
        scan,
        findings,
      }),
      redirect: "error",
      signal,
    });
  } catch (error) {
    dependencies.signal?.throwIfAborted();
    // A lost response does not establish whether the server accepted the POST.
    throw new CodexSecurityError(
      `Cloud publication was not confirmed: ${errorMessage(error)}. The request was not retried; check whether it was accepted before submitting again.`,
      { cause: error },
    );
  }
  if (!response.ok) {
    await response.body?.cancel().catch(() => undefined);
    const detail =
      response.status === 401
        ? "Sign in with ChatGPT again before retrying."
        : response.status === 403
          ? "The signed-in account is not authorized to publish to Cloud."
          : response.status === 404
            ? "Cloud publication is not available for this account or deployment."
            : "The request was not retried.";
    throw new CodexSecurityError(
      `Cloud publication failed (HTTP ${response.status}). ${detail}`,
    );
  }
  const receipt = receiptSchema.safeParse(
    await response.json().catch(() => {
      dependencies.signal?.throwIfAborted();
      return undefined;
    }),
  );
  // Cloud assigns opaque IDs in request order, so they cannot be compared to
  // local finding IDs. The authenticated response must still preserve the
  // submitted count and return one distinct observation for each finding.
  if (
    (response.status !== 200 && response.status !== 201) ||
    !receipt.success ||
    receipt.data.finding_count !== findings.length ||
    receipt.data.finding_ids.length !== findings.length ||
    new Set(receipt.data.finding_ids).size !== receipt.data.finding_ids.length
  ) {
    throw new CodexSecurityError(
      "Cloud publication returned an invalid acceptance receipt. Check whether the request was accepted before submitting again.",
    );
  }
  return {
    scanId: scan.id,
    findingIds: receipt.data.finding_ids,
    findingCount: receipt.data.finding_count,
  };
}

/** @internal Shared sign-in for local Cloud publishers. */
export async function readCloudCredentials(
  environment: NodeJS.ProcessEnv,
  signal?: AbortSignal,
) {
  const dedicatedHome = codexSecurityCredentialHome(environment);
  if (existsSync(dedicatedHome)) {
    const dedicated = await withCredentialHomeLock(
      dedicatedHome,
      async () => {
        if (
          !(await codexSecurityCredentialAllowsAmbientImport(dedicatedHome))
        ) {
          throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
        }
        if (await codexSecurityHasStoredFileCredentials(dedicatedHome)) {
          if (await credentialHomeUsesFileStorage(dedicatedHome))
            return readCloudLoginFile(dedicatedHome);
          throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
        }
        // A dedicated configuration may point to a different account in the keyring.
        if (existsSync(join(dedicatedHome, "config.toml")))
          throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
      },
      signal,
    );
    if (dedicated) return dedicated;
  }
  const configuredHome = environment["CODEX_HOME"];
  const home = expandHome(
    configuredHome?.trim() ? configuredHome : "~/.codex",
    environment,
  );
  let credentialStorage: unknown;
  try {
    credentialStorage = parseToml(
      await readFile(join(home, "config.toml"), "utf8"),
      { integersAsBigInt: "asNeeded" },
    )["cli_auth_credentials_store"];
  } catch {
    throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
  }
  // Ambient auto storage can leave a file for another account.
  if (credentialStorage !== "file")
    throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
  return readCloudLoginFile(home);
}

async function readCloudLoginFile(home: string) {
  try {
    const credentials = credentialsSchema.safeParse(
      JSON.parse(await readFile(join(home, "auth.json"), "utf8")),
    );
    if (credentials.success) return credentials.data.tokens;
  } catch {
    // Parsing and filesystem diagnostics must not reflect credential contents.
  }
  throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
}