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

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

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

Почему после входа для сканирования используется 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.

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

Да. Выполните ту же команду 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

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

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

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

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

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 validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

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

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

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

Изучите coverage.json: в нём указаны исключённые пути, области с отложенной проверкой и открытые вопросы. Новые результаты не содержат поля полноты охвата. Проверьте scan.status в scan-manifest.json, чтобы узнать статус выполнения.

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

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

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

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

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

Значение по умолчанию — 96 ч. Допускается любое положительное значение до 96, включая дробные. По истечении срока Codex Security останавливает незавершённые рабочие процессы, сохраняет результаты завершённых стандартных сканирований и объединяет их в итоговый отчёт. Проверьте в отчёте, какие области были проверены и какая работа отложена. Само по себе истечение срока не определяет код завершения: его определяют статус выполнения и политика уровней серьёзности.

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

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

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

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

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

Для проверок пул-реквестов GitHub и сканирования репозитория по расписанию используйте Codex Security GitHub Action. В версии action-v0.3.0 завершённое сканирование означает, что настроенный анализ дал допустимый результат. Исключения из области сканирования и отложенные исследования не позволяют обойти политику уровней серьёзности. Изучите coverage.json, чтобы оценить охват сканирования и его ограничения. Чтобы также отклонять пустые наборы изменений и пробные запуски, требуйте, чтобы выходное значение scan-status у Action было равно completed; см. Выбор политики уровней серьёзности.

Для других провайдеров см. обзор CI/CD. Для проверки перед каждым коммитом используйте install-hook.