Документация ChatGPT
Русский
Связаться goolvyouyou@gmail.com

Часто задаваемые вопросы о Codex Security CLI

Ответы на вопросы о сканированиях Codex Security, обнаруженных проблемах, ложных срабатываниях, покрытии, стоимости и CI.

Здесь собраны ответы на распространённые вопросы о сканировании репозиториев и управлении обнаруженными проблемами безопасности из терминала. Чтобы установить инструмент и выполнить первое сканирование, начните с краткого руководства по CLI.

Сканирование репозиториев

Кто может использовать CLI

Пакет @openai/codex-security общедоступен.

Для запуска сканирований требуется доступ к Codex Security. Для получения наилучших результатов используйте учётную запись, проверенную в рамках программы Trusted Access for Cyber.

Почему после входа для сканирования используется API key

Если в вашей среде заданы OPENAI_API_KEY или CODEX_API_KEY, при сканированиях без интерактивного терминала, а также при сканированиях с выводом в JSON и JSONL по умолчанию используется API key из среды, даже после успешного входа через ChatGPT или токен доступа. При интерактивном сканировании с текстовым выводом вам будет предложено выбрать способ, если также доступен вход через ChatGPT. При пробном запуске учётные данные не запрашиваются и не загружаются.

Чтобы использовать сохранённые учётные данные для сканирования, выберите их явно:

npx @openai/codex-security scan . --auth chatgpt

Чтобы обязательно использовать API key из OPENAI_API_KEY или CODEX_API_KEY:

npx @openai/codex-security scan . --auth api-key

Чтобы сохранённые учётные данные автоматически использовались по умолчанию, выполните unset OPENAI_API_KEY CODEX_API_KEY. Все поддерживаемые способы аутентификации описаны в справочнике по CLI.

Как работает массовое сканирование репозиториев

Войдите с помощью GitHub CLI:

gh auth login

Найдите и выберите репозитории учётной записи или организации GitHub:

npx @openai/codex-security bulk-scan

Если у вас уже есть подготовленный список, укажите CSV с репозиториями и каталог для результатов:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

Подробнее об обнаружении репозиториев GitHub, формате CSV, результатах кампании и доступных параметрах см. в разделе Запуск массового сканирования безопасности.

Можно ли возобновить прерванное массовое сканирование

Да. Выполните ту же команду bulk-scan с исходным CSV и каталогом вывода. Codex Security пропустит уже обработанные репозитории.

Добавьте --max-attempts 3, чтобы повторить попытку после временных ошибок репозитория или сканирования:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

Завершённое сканирование с покрытием partial или unknown сохраняет свои результаты и приводит к завершению кампании с кодом 2. Оно не запускается повторно даже при использовании --max-attempts.

Как использовать при сканировании архитектурную документацию и политики безопасности

Передайте архитектурные документы, модели угроз или политики безопасности с помощью --knowledge-base:

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

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

Обнаруженные проблемы и покрытие

Где команды могут найти результаты предыдущих сканирований

Выведите список сохранённых сканирований репозитория:

npx @openai/codex-security scans list /path/to/repository

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

npx @openai/codex-security scans show SCAN_ID

Для каждого завершённого сканирования отчёт, обнаруженные проблемы, данные о покрытии и вспомогательные артефакты хранятся вместе. Полная структура описана в разделе Артефакты сканирования.

Чтобы просмотреть сохранённые события сканирования и рабочих процессов, выполните scans logs SCAN_ID. Эти журналы не подвергаются редактированию и могут содержать исходный код или учётные данные.

Что делать, если CLI не может сохранить историю сканирований

Codex Security хранит историю сканирований в базе данных workbench. Если каталог состояния по умолчанию недоступен для записи, выберите закрытый каталог за пределами репозитория:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Как при сканировании различаются новые и уже известные проблемы

Выведите список открытых проблем из всех сканирований репозитория:

npx @openai/codex-security findings list /path/to/repository

В списке отмечаются проблемы, подтверждённые последним сканированием, а также ранее обнаруженные открытые проблемы, которые это сканирование не подтвердило.

Сравните обнаруженные проблемы в двух сканированиях:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

Как работает обратная связь о ложных срабатываниях

Изучите сохранённое сканирование, чтобы найти ID случая:

npx @openai/codex-security scans show SCAN_ID

Укажите, почему эта проблема неприменима:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

При последующих сканированиях того же репозитория это объяснение используется как контекст. При этом текущий исходный код, средства контроля и достижимость по-прежнему проверяются независимо. Отклонение не отключает правило, путь или класс уязвимостей.

Подробное описание команды см. в справочнике по обнаруженным проблемам.

Почему повторные сканирования могут обнаруживать разные проблемы

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

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

При повторном запуске сохраняется исходная конфигурация сканирования и требуется та же версия плагина. Если версия установленного плагина изменилась, команда завершит работу.

Сравните базовое сканирование с новым:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

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

Как команде убедиться, что исправление сработало

После внесения исправления повторно выполните исходное сканирование:

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

Сравните исходные обнаруженные проблемы с новым сканированием:

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Убедитесь, что новое сканирование охватывает исходную цель и затронутый путь без пробелов в покрытии. Затем напрямую повторно проверьте исходную проблему в текущей рабочей копии:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

Само по себе отсутствие проблемы или сравнение сканирований не доказывает, что исправление сработало.

Что означает неполное покрытие

Покрытие может быть complete, partial или unknown. Прежде чем считать сканирование подтверждением проведённой проверки, изучите coverage.json, где указаны исключённые пути, отложенные для проверки поверхности и открытые вопросы.

Сканирования с частичным или неопределённым покрытием возвращают код выхода 2 даже без политики серьёзности. При этом все доступные обнаруженные проблемы и данные о покрытии сохраняются. Последующее сканирование не может подтвердить, что ранее обнаруженной проблемы больше нет, если оно не охватывает исходный путь этой проблемы.

Автоматизация и стоимость

Как работают ограничения времени для глубокого сканирования

При запуске глубокого сканирования задайте предельное время работы исполнителя:

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

По умолчанию задано 96 часов. Можно указать любое положительное значение до 96 включительно, в том числе дробное. По истечении заданного времени Codex Security останавливает незавершивших работу исполнителей, сохраняет результаты завершённых стандартных сканирований и объединяет их в итоговый отчёт. Если ни один исполнитель не завершил проверку исходного кода, в отчёте фиксируется частичное покрытие, а CLI возвращает код выхода 2.

Для постоянных настроек или кампаний массового сканирования задайте max_time_hours в разделе [deep_scan] конфигурации глубокого сканирования.

Как работают ограничения стоимости сканирования

Перед запуском сканирования задайте ограничение предполагаемой стоимости в USD:

npx @openai/codex-security scan . --max-cost 5

Ограничение является оценочным, а не жёстким пределом расходов. Уже выполняющиеся запросы могут завершиться после его превышения. Если глубокое сканирование достигает ограничения после того, как Codex Security объединит результаты завершивших работу исполнителей, CLI сохраняет завершённый отчёт с частичным покрытием и завершает работу с кодом 2. В противном случае он сохраняет все доступные частичные результаты.

Можно ли проверять коммиты и запросы на включение изменений

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

npx @openai/codex-security install-hook

Для проверки запросов на включение изменений просканируйте зафиксированные в коммитах изменения и задайте порог серьёзности:

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

При полном сканировании возвращается код выхода 1, если обнаружена проблема с выбранным или более высоким уровнем серьёзности. Полный рабочий процесс GitHub Actions, обработка артефактов и экспорт SARIF описаны в разделе Запуск сканирований в CI.

Может ли другое приложение запускать сканирования напрямую

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