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

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

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

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

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

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

Пакет @openai/codex-security общедоступен. Установите CLI и SDK:

npm install @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, результатах кампании и доступных параметрах см. в разделе Запуск массового сканирования безопасности.

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

Да. Повторно выполните ту же команду массового сканирования с исходным 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

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

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

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

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

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

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

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

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

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Сравните сопоставленные проблемы:

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

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

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

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

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

Это приблизительное ограничение, а не жёсткий предел расходов. Уже выполняющиеся запросы могут завершиться с превышением лимита. После остановки сканирования Codex Security сохраняет доступные результаты.

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

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

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