TypeScript SDK для Codex Security

Используйте TypeScript SDK для Codex Security, чтобы запускать сканирования безопасности репозиториев и изменений кода из своего приложения или инструмента разработчика. SDK возвращает типизированные данные об обнаруженных проблемах, сведения о покрытии и пути к артефактам сканирования. Для длительных сканирований он поддерживает предварительные проверки, ограничения стоимости, обратные вызовы для отслеживания хода выполнения и отмену.

SDK использует модули ECMAScript (ESM) и работает на стороне сервера с Node.js 22 или более поздней версии. Для сканирования также требуется Python 3.10 или более поздней версии.

Настройка SDK

Установите SDK:

npm install @openai/codex-security

Перед началом сканирования задайте OPENAI_API_KEY или CODEX_API_KEY, используйте существующий вход в Codex с хранением данных в файле либо настройте Amazon Bedrock с учётными данными AWS и явными переопределениями model_provider и model.

Для наилучших результатов используйте учётную запись, проверенную для Trusted Access for Cyber. Вход или предоставление API key не даёт Trusted Access.

Запуск сканирования

Создайте один клиент CodexSecurity, запустите стандартное сканирование репозитория и закройте клиент по завершении работы. Передайте outputDir, чтобы выбрать частный каталог результатов за пределами охватывающего рабочего дерева Git.

Если опустить outputDir, Codex Security сохранит результаты в собственном постоянном каталоге состояния. Результаты могут содержать фрагменты исходного кода и сведения об уязвимостях, поэтому выберите подходящие разрешения и правила хранения.

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log(result.reportPath);
  console.log(result.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

run запускает сканирование, ожидает его завершения, проверяет запечатанные артефакты и возвращает ScanResult. close освобождает изолированную среду выполнения и поддерживает повторные вызовы.

Проверка входных данных с помощью предварительной проверки

Используйте preflight, чтобы проверить репозиторий, цель, режим, расположение вывода и конфигурацию Codex перед началом сканирования:

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  outputDir: "/path/outside/repository/results",
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

Предварительная проверка не изменяет среду выполнения Codex и учётные данные. Она также оставляет обнаружение плагина и Python самому сканированию. Благодаря этому предварительная проверка удобна для проверки пользовательского ввода перед длительной операцией или операцией с учётными данными.

Чтобы предварительно просмотреть архивирование существующего каталога результатов, задайте archiveExisting: true:

const plan = await security.preflight("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
});

console.log(plan.archiveDir);

Возвращаемый archiveDir показывает предполагаемое имя архива. Итоговый путь может отличаться, поскольку run создаёт собственное уникальное место назначения. Получите фактический путь к архиву с помощью onOutputArchived:

await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
  onOutputArchived(archiveDir) {
    console.log("Archived results:", archiveDir);
  },
});

Сканирование архивирует предыдущие результаты и начинает работу с пустым каталогом вывода.

Выбор цели сканирования

SDK поддерживает в качестве целей репозиторий, путь, различия между коммитами и рабочее дерево. По умолчанию целью является весь репозиторий.

Сканирование выбранных путей

Передайте массив путей внутри репозитория:

const result = await security.run("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
});

Пути могут указывать на файлы или каталоги. SDK разрешает каждый путь внутри репозитория и удаляет дубликаты.

Сканирование зафиксированных изменений

Используйте DiffTarget.refs, чтобы сканировать зафиксированные изменения между двумя локально доступными ревизиями Git:

const target = DiffTarget.refs({
  base: "origin/main",
  head: "HEAD",
});

const result = await security.run("/path/to/repository", { target });

По умолчанию главной ревизией является HEAD. Для целей на основе различий аргумент репозитория должен указывать на корень рабочего дерева Git.

Сканирование рабочего дерева

Используйте DiffTarget.workingTree, чтобы сканировать проиндексированные и неиндексированные изменения относительно базовой ревизии:

const target = DiffTarget.workingTree({ base: "HEAD" });
const result = await security.run("/path/to/repository", { target });

По умолчанию базовой ревизией является HEAD. Получите выбранные ревизии перед началом сканирования различий или рабочего дерева.

Выбор углублённого режима

Задайте mode: "deep" для сканирования репозитория или пути, требующего более широкой проверки:

const result = await security.run("/path/to/repository", {
  target: ["services/billing"],
  mode: "deep",
});

Углублённый режим поддерживает цели в виде репозитория и пути. Для сканирования различий и рабочего дерева используйте стандартный режим.

Добавление базы знаний по безопасности

Передайте архитектурные документы, модели угроз или политики безопасности через knowledgeBasePaths:

const result = await security.run("/path/to/repository", {
  knowledgeBasePaths: [
    "/path/to/architecture.md",
    "/path/to/security-policies",
  ],
});

SDK принимает файлы или каталоги и выполняет рекурсивный поиск в каталогах. Поддерживаемые форматы документов: .md, .markdown, .txt, .pdf и .docx. SDK отклоняет входные пути, являющиеся ссылками, пропускает ссылки в каталогах и хранит извлечённое содержимое документов вне сохранённых результатов сканирования.

Установка бюджета сканирования

Задайте maxCostUsd, чтобы остановить сканирование, когда предполагаемая стоимость модели превысит лимит. Используйте onCost для отслеживания стоимости во время сканирования:

const result = await security.run("/path/to/repository", {
  maxCostUsd: 5,
  onCost(cost) {
    console.log(cost.estimatedUsd);
  },
});

console.log(result.cost?.estimatedUsd);

Лимит является оценкой, а не жёстким ограничением расходов. Уже выполняющиеся запросы могут завершиться с превышением лимита. Если сканирование превышает лимит, SDK создаёт исключение ScanCostLimitExceededError и сохраняет доступные результаты.

Работа с результатами сканирования

ScanResult предоставляет структурированные документы, метаданные сканирования и пути к артефактам:

Используйте структурированные данные об обнаруженных проблемах и покрытии напрямую:

for (const finding of result.findings.findings) {
  const location = finding.locations[0];
  if (location === undefined) continue;

  console.log(
    finding.severity.level,
    `${location.path}:${location.startLine}`,
    finding.title
  );
}

for (const deferred of result.coverage.deferred) {
  console.log(deferred.id, deferred.reason);
}

Полнота покрытия принимает значение complete, partial или unknown. Проверьте отложенные области, исключения и открытые вопросы, прежде чем использовать сканирование как основание для решения по безопасности.

result.toJSON() возвращает манифест, обнаруженные проблемы, покрытие, идентификаторы сканирования и потока, reportPath, artifactsDir, sarifPath и метаданные хода в одном готовом для JSON объекте.

Отслеживание или отмена сканирования

Передайте обратные вызовы ScanOptions, чтобы сообщать о запуске сканирования, ходе работы исполнителей и повторных попытках подключения:

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  onScanStarted() {
    console.log("Scan started");
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  onReconnect(attempt, maxAttempts) {
    console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
  },
  onObserverError(observer, error) {
    console.error(`${observer} failed`, error);
  },
});

console.log(result.reportPath);

Передайте AbortSignal, когда отмена поступает от запроса, контроллера задания или тайм-аута:

const controller = new AbortController();

try {
  const scan = security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
    signal: controller.signal,
  });

  controller.abort();
  await scan;
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
}

Прерванное сканирование может оставить частичный вывод в scanDir. Сохраните этот каталог, если результат необходимо исследовать.

Приложения, отображающие ход настройки сканирования, также могут использовать обратные вызовы жизненного цикла ScanOptions:

Настройка среды выполнения и учётных данных

Передайте конфигурацию среды выполнения, если требуется определённый плагин, интерпретатор или параметр Codex:

const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "gpt-5.6-terra",
    model_reasoning_effort: "high",
  },
});

pluginPath принимает каталог или ZIP-файл плагина. pythonPath выбирает интерпретатор плагина. codexOverrides объединяет поддерживаемые значения с изолированной конфигурацией Codex. По умолчанию сканирования используют gpt-5.6-sol с особо высоким уровнем рассуждений. Задайте model и model_reasoning_effort в codexOverrides, чтобы использовать другую модель или уровень рассуждений. Чтобы использовать Amazon Bedrock, задайте model_provider и model в codexOverrides.

Клиент также предоставляет поддерживаемые методы аутентификации:

Дескриптор входа предоставляет waitForInstructions, authUrl, verificationUrl, userCode, wait и cancel, чтобы приложение могло представить и завершить выбранный процесс входа. SDK может повторно использовать вход в Codex с хранением данных в файле. API keys удобны для CI и серверной автоматизации.

Когда доступны и API key, и сохранённый вход, SDK по умолчанию использует API key. Чтобы вместо него использовать вход в ChatGPT, выберите его для сканирования:

const result = await security.run("/path/to/repository", {
  auth: "chatgpt",
});

Задайте auth: "api-key", чтобы требовать API key из окружения. preflight принимает тот же параметр auth.

Обработка ошибок сканирования

Перехватывайте экспортированный класс ошибки, соответствующий действию, которое может выполнить ваше приложение:

Продолжите работу с кратким руководством по CLI, руководством по CI или справочником CLI.