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

12.7 KB
Raw Blame
import { DEEP_SCAN_SETTINGS, DeepScanSettingsSchema } from "./scan-settings.js";

type Row = { label: string; description: string };
type Group = readonly [title: string, names: readonly string[]];

const COMMAND_GROUPS: readonly Group[] = [
  ["Scan and remediate", ["scan", "policy", "validate", "patch", "verify-fix"]],
  [
    "Review results",
    ["scans", "findings", "classify-severity", "dedupe", "suggest-owners"],
  ],
  ["Import and share", ["import", "publish", "export"]],
  ["Automate", ["bulk-scan", "scan-components", "install-hook"]],
  [
    "Configure and troubleshoot",
    ["login", "logout", "init", "info", "feedback", "update"],
  ],
];

const SCAN_GROUPS: readonly Group[] = [
  ["Scope", ["path", "diff", "head", "working-tree", "base"]],
  ["Configuration", ["config", "mode", "knowledge-base", "dry-run"]],
  ["Model and authentication", ["auth", "model", "effort", "provider"]],
  [
    "Deep Scan",
    DEEP_SCAN_SETTINGS.flatMap(([, , , flag]) =>
      flag === null ? [] : [flag.slice(2)],
    ),
  ],
  [
    "Results, progress, and limits",
    [
      "output-dir",
      "archive-existing",
      "owner-suggestions",
      "max-cost",
      "max-time",
      "show-cost",
      "fail-on-severity",
      "headless",
      "verbose",
    ],
  ],
  ["Patch after scanning", ["patch", "patch-severity", "create-pr"]],
];

const PUBLISH_GROUPS: readonly Group[] = [
  ["Input", ["scan", "scan-dir", "finding-id", "workflow-id"]],
  ["Destination", ["to", "findings-url"]],
  [
    "Linear",
    [
      "linear-team",
      "linear-project",
      "linear-assignee",
      "linear-api-key",
      "project",
    ],
  ],
  ["Publishing", ["dry-run", "skip-existing"]],
];

const VALUE_LABELS: Record<string, string> = {
  context: "text",
  "context-file": "file",
  "output-schema": "file",
  config: "file",
  path: "path",
  "knowledge-base": "path",
  "scan-prompt-file": "file",
  "validation-prompt-file": "file",
  "post-scan-prompt-file": "file",
  diff: "ref",
  head: "ref",
  base: "ref",
  model: "model",
  "output-dir": "path",
  "scan-dir": "path",
  "plugin-path": "path",
  "source-root": "path",
  "avit-template": "file",
  python: "path",
  codex: "key=value",
  "max-cost": "usd",
  "max-total-cost": "usd",
  "max-time": "minutes",
  "max-time-hours": "hours",
  "fail-on-severity": "level",
  "patch-severity": "level",
  severity: "level",
  scan: "scan-id",
  "finding-id": "id",
  "findings-url": "url",
  output: "file",
  csv: "file",
  json: "file",
  rubric: "file",
  "export-format": "format",
  "filter-output": "keys",
  "token-limit": "count",
  "token-offset": "count",
  to: "destination",
};

const OUTPUT_FLAGS = ["format", "json", "filter-output", "full-output"];

const OUTPUT_GROUPS: readonly Group[] = [
  ["Help and version", ["help", "version"]],
  ["Output", OUTPUT_FLAGS],
];

function rowName(row: Row): string {
  return row.label.match(/--([\w-]+)/u)?.[1] ?? row.label;
}

function parseRows(lines: string[]): Row[] {
  return lines.map((line) => {
    const match = line.trim().match(/^(.*?)\s{2,}(.*)$/u);
    return { label: match?.[1] ?? line.trim(), description: match?.[2] ?? "" };
  });
}

function wrap(text: string, width: number, prefix = "", next = prefix): string {
  const lines: string[] = [];
  let line = prefix;
  let indent = prefix.length;
  for (const word of text.split(/\s+/u)) {
    if (line.length > indent && line.length + 1 + word.length > width) {
      lines.push(line);
      line = next;
      indent = next.length;
    }
    line += `${line.length > indent ? " " : ""}${word}`;
  }
  lines.push(line);
  return lines.join("\n");
}

function renderRows(title: string, rows: Row[], width: number): string {
  // Keep long option names from moving every description across the terminal.
  const column = Math.min(
    30,
    Math.floor(width / 2),
    Math.max(...rows.map((row) => row.label.length)) + 4,
  );
  return [
    `${title}:`,
    ...rows.map(({ label, description }) => {
      if (!description) return `  ${label}`;
      if (label.length + 4 > column) {
        return `  ${label}\n${wrap(description, width, "    ")}`;
      }
      return wrap(
        description,
        width,
        `  ${label}${" ".repeat(column - label.length - 2)}`,
        " ".repeat(column),
      );
    }),
  ].join("\n");
}

function groupedRows(
  rows: Row[],
  groups: readonly Group[],
  remainingTitle: string,
  width: number,
): string[] {
  const remaining = new Map(rows.map((row) => [rowName(row), row]));
  const sections: string[] = [];
  for (const [title, names] of groups) {
    const selected = names.flatMap((name) => {
      const row = remaining.get(name);
      remaining.delete(name);
      return row === undefined ? [] : [row];
    });
    if (selected.length) sections.push(renderRows(title, selected, width));
  }
  if (remaining.size) {
    sections.push(renderRows(remainingTitle, [...remaining.values()], width));
  }
  return sections;
}

function optionRow(row: Row, command: string): Row {
  const name = rowName(row);
  let { label, description } = row;
  label = label.replace(/<([^>]+)>/u, (_, type: string) => {
    const choices = type.split("|");
    if (choices.length > 1) {
      description += `${description.endsWith(".") ? "" : "."} Choices: ${choices.join(", ")}.`;
    }
    return `<${VALUE_LABELS[name] ?? (type === "number" ? "count" : name)}>`;
  });
  if (name === "token-limit")
    description = "Maximum tokens in the text view (nonnegative integer).";
  if (name === "token-offset")
    description = "Start the text view at this token (nonnegative integer).";
  label = label.replace(/^--([\w-]+), (-\w)/u, "$2, --$1");
  if (command === "scan" && !/default:/iu.test(description)) {
    const setting = DEEP_SCAN_SETTINGS.find(
      ([, , , flag]) => flag === `--${name}`,
    );
    if (setting) {
      const value =
        DeepScanSettingsSchema.shape[setting[0]].meta()?.["default"];
      if (value !== undefined) description += ` (default: ${value})`;
    }
  }
  return { label, description };
}

function globalRows(rows: Row[], command: string): Row[] {
  const scan = command === "scan" || command === "scan import";
  const plainOutput = ["validate", "login", "logout", "export"].includes(
    command,
  );
  const visible = rows.filter(({ label }) => {
    if (label === "--update") return false;
    if (scan && label.startsWith("--filter-output")) return false;
    return !(
      plainOutput &&
      /^(--format |--filter-output |--full-output$|--token-)/u.test(label)
    );
  });
  const formats = visible.find((row) => rowName(row) === "format");
  if (
    formats &&
    (scan || command === "scans rerun" || command === "scans resume")
  ) {
    formats.label = formats.label.replace("|md", "");
  }
  if (formats) {
    visible.push({
      label: "--json",
      description: "Shorthand for --format json.",
    });
  }
  return visible.map((row) =>
    optionRow(
      row.label === "--help" ? { ...row, label: "-h, --help" } : row,
      command,
    ),
  );
}

/** Present Incur's generated help without changing its routing or command output. */
export function formatCliHelp(text: string, columns = 80): string | undefined {
  const header = text.match(
    /^(codex-security(?:@[^\s]+)?((?: [a-z][a-z-]*)*))(?: — ([^\n]*))?\n\nUsage: /u,
  );
  if (!header) return undefined;
  const command = header[2]!.trim();
  const sections: string[] = [];
  // Presentation width only; long paths and copyable commands remain intact.
  const width = columns > 0 ? columns : 80;
  const blocks = text.trimEnd().split(/\n\n/u);
  const examples = blocks.find((block) => block.startsWith("Examples:\n"));
  for (const [index, block] of blocks.entries()) {
    const [title = "", ...lines] = block.split("\n");
    if (index === 0) {
      sections.push(
        [header[1], header[3] && wrap(header[3], width)]
          .filter(Boolean)
          .join("\n"),
      );
    } else if (title.startsWith("Usage: ")) {
      let usage = block.replace(
        /([a-z])([A-Z])/gu,
        (_, lower: string, upper: string) => `${lower}-${upper.toLowerCase()}`,
      );
      if (command === "scans" || command === "findings") {
        usage = usage.replace("<command>", "[command]");
        usage += "\nDefault command: list";
      }
      sections.push(
        usage
          .split("\n")
          .map((line) =>
            wrap(
              line.trimStart(),
              width,
              line.startsWith("       ") ? "       " : "",
              "       ",
            ),
          )
          .join("\n"),
      );
      if (command === "") {
        sections.push(
          [
            "Get started:",
            "  codex-security scan . --dry-run",
            "  codex-security login",
            "  codex-security scan .",
            "  codex-security scans show",
          ].join("\n"),
        );
      } else if (command === "import") {
        sections.push(
          renderRows(
            "Choose your input",
            [
              {
                label: "Live provider",
                description: "Choose a collector below.",
              },
              {
                label: "CLI, API, or MCP source",
                description:
                  "Ask Codex to import it using the publish-findings skill.",
              },
              {
                label: "Workbench findings",
                description:
                  "Ask Codex to publish a stored import or selected finding versions.",
              },
              {
                label: "Saved vendor report",
                description:
                  "See codex-security publish findings --help for local storage and publication.",
              },
              {
                label: "Codex Security CSV or JSON",
                description:
                  "See codex-security scan import --help to add the export to local scan history.",
              },
            ],
            width,
          ),
        );
      } else if (examples) {
        sections.push(examples);
      }
    } else if (title === "Examples:") {
      continue;
    } else if (title === "Commands:") {
      const rows = parseRows(lines);
      sections.push(
        ...(command === ""
          ? groupedRows(rows, COMMAND_GROUPS, "Other commands", width)
          : [renderRows("Commands", rows, width)]),
      );
    } else if (title === "Options:") {
      const options = parseRows(lines)
        .filter(
          (row) =>
            !(command === "publish scan" && rowName(row) === "csv") &&
            !(command === "publish check" && rowName(row) === "to"),
        )
        .map((row) => optionRow(row, command));
      const rows = options.filter(
        (row) => !row.description.startsWith("[deprecated]"),
      );
      sections.push(
        ...(command === "scan"
          ? groupedRows(rows, SCAN_GROUPS, "Advanced", width)
          : command === "publish scan"
            ? groupedRows(rows, PUBLISH_GROUPS, "Options", width)
            : [renderRows("Options", rows, width)]),
      );
      const deprecated = options.filter((row) =>
        row.description.startsWith("[deprecated]"),
      );
      if (deprecated.length)
        sections.push(renderRows("Deprecated options", deprecated, width));
    } else if (title === "Global Options:") {
      const rows = globalRows(parseRows(lines), command);
      if (command === "") {
        sections.push(
          ...groupedRows(rows, OUTPUT_GROUPS, "Agent options", width),
        );
      } else {
        const outputRows = rows.filter((row) =>
          OUTPUT_FLAGS.includes(rowName(row)),
        );
        if (outputRows.length)
          sections.push(renderRows("Output", outputRows, width));
        sections.push(
          wrap(
            "See codex-security --help for shared help and agent options.",
            width,
          ),
        );
      }
    } else if (
      ["Arguments:", "Integrations:", "Environment Variables:"].includes(title)
    ) {
      const rows = parseRows(lines).map((row) => ({
        ...row,
        label:
          title === "Arguments:"
            ? row.label.replace(/([a-z])([A-Z])/gu, "$1-$2").toLowerCase()
            : row.label,
      }));
      sections.push(renderRows(title.slice(0, -1), rows, width));
    } else {
      sections.push(
        block
          .split("\n")
          .map((line) => (line.startsWith("  ") ? line : wrap(line, width)))
          .join("\n"),
      );
    }
  }
  if (command === "completions") {
    sections.push(
      wrap(
        "Shell setup: https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#shell-completions",
        width,
      ),
    );
  }
  if (command === "") {
    sections.push(
      wrap(
        "Use codex-security <command> --help for options and examples.",
        width,
      ),
    );
    sections.push("Docs: https://learn.chatgpt.com/docs/security/cli");
  }
  return `${sections.join("\n\n")}\n`;
}