TypeScript SDK для Codex Security

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

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

Настройка SDK

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

npm install @openai/codex-security

Перед запуском сканирования задайте OPENAI_API_KEY или CODEX_API_KEY, используйте существующий файловый вход в Codex либо настройте другого поставщика. Amazon Bedrock использует учетные данные AWS; OpenRouter и Fireworks используют API key и конфигурацию соответствующего поставщика.

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

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

Сканируйте только те репозитории, которым доверяете и которые имеете право проверять. SDK работает с вашими локальными разрешениями операционной системы и никогда не запрашивает подтверждение. Процессы сканирования могут наследовать ваше окружение, поэтому перед запуском удалите посторонние учетные данные. См. раздел Локальные разрешения сканирования.

Создайте один клиент 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"],
  knowledgeBasePaths: ["/path/to/architecture.md"],
  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",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

Углубленный режим поддерживает цели в виде репозитория и пути. Для сканирования различий и рабочего дерева используйте стандартный режим. Необязательные параметры управляют количеством параллельных независимых исполнителей стандартного сканирования, количеством субагентов на исполнителя, количеством последовательных завершенных сканирований исполнителя без новых обнаруженных проблем, а также общим количеством и продолжительностью запусков исполнителей. Для них требуется mode: "deep".

По умолчанию maxTimeHours имеет значение 96 и принимает положительное число до 96, включая дробное количество часов. По достижении срока Codex Security останавливает незавершенных исполнителей, сохраняет результаты завершенных сканирований и объединяет их в итоговый отчет. Проверьте result.coverage.completeness, прежде чем считать ограниченное по времени сканирование доказательством полного покрытия.

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

Передайте архитектурные документы, модели угроз или политики безопасности через 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 отклоняет входные пути, являющиеся ссылками, пропускает ссылки в каталогах и хранит извлеченное содержимое документов вне сохраненных результатов сканирования.

Добавление инструкций для сканирования и последующих действий

Используйте scanPrompt, чтобы направить сканирование на нужную область, и postScanPrompt, чтобы запросить последующее действие:

const result = await security.run("/path/to/repository", {
  scanPrompt: "Focus on tenant isolation and authorization checks.",
  postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
});

Если последующее действие завершается с ошибкой, SDK сохраняет завершенное сканирование и сообщает об ошибке через onWarning. Он восстанавливает все артефакты завершенного сканирования, которые были изменены последующим действием.

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

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

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

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

Лимит оценивает расходы, но не является жестким ограничением, поэтому уже выполняющиеся запросы могут завершиться с небольшим превышением. Если углубленное сканирование достигает лимита после того, как Codex Security объединяет результаты завершенных исполнителей, run возвращает результат, в котором для coverage.completeness задано значение "partial", и сообщает предупреждение о бюджете через onWarning.

Если сканирование не может создать завершенный частичный результат, run создает исключение ScanCostLimitExceededError и сохраняет весь доступный вывод.

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

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

Чтобы потребовать использования того же плагина при последующем сканировании, передайте expectedPluginVersion: result.pluginVersion. SDK отклонит сканирование, если версия установленного плагина отличается.

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

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);
}

Обнаруженные проблемы могут включать необязательные поля codeEvidence, rootCause, validation, attackPath, remediationTests и preventiveControls.

Для проблем в масштабе репозитория confirmedInLatestScan отличает проблемы, обнаруженные при последнем сканировании, от ранее обнаруженных проблем, которые остаются открытыми:

for (const finding of result.repositoryFindings ?? []) {
  console.log(finding.title, finding.confirmedInLatestScan);
}

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

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

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

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

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  onScanStarted() {
    console.log("Scan started");
  },
  onProgress(progress) {
    console.log(progress.phase, progress.filesCompleted, progress.filesTotal);
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  onSessionEvent(session) {
    console.log(session.threadId, session.worker, session.event["type"]);
  },
  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:

Состояние Trusted Access имеет значение granted, not_granted или unknown. Отсутствующий или неизвестный доступ также вызывает onWarning.

onSessionEvent получает события без редактирования, которые могут содержать исходный код или учетные данные. Фильтруйте их перед отправкой в общие журналы или другие службы.

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

Передавайте конфигурацию среды выполнения, когда требуется определенный плагин, интерпретатор или параметр 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.

codexOverrides не может ограничить доступ сканирования к файловой системе или изменить его политику подтверждений. См. раздел Локальные разрешения сканирования.

Для OpenRouter или Fireworks также предоставьте соответствующий API key и полную конфигурацию поставщика в codexOverrides. Например, задайте OPENROUTER_API_KEY и настройте OpenRouter:

const security = new CodexSecurity({
  codexOverrides: {
    model: "anthropic/claude-sonnet-4.5",
    model_provider: "openrouter",
    model_providers: {
      openrouter: {
        name: "OpenRouter",
        base_url: "https://openrouter.ai/api/v1",
        env_key: "OPENROUTER_API_KEY",
        wire_api: "responses",
      },
    },
  },
});

Для Fireworks замените оба ключа openrouter на fireworks, задайте для name значение Fireworks AI, для env_key — значение FIREWORKS_API_KEY, используйте https://api.fireworks.ai/inference/v1 как base_url и выберите модель Fireworks.

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

Дескриптор входа предоставляет waitForInstructions, authUrl, verificationUrl, userCode, wait и cancel, чтобы приложение могло представить и завершить выбранный процесс входа. SDK может повторно использовать файловый вход в Codex. API key хорошо подходят для 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.