Краткое руководство по Codex Security CLI

Запустите стандартное сканирование локального репозитория с помощью автономного Codex Security CLI. В результате этого краткого руководства вы получите сохранённый отчёт для изучения и повторного просмотра. Для сканирования в беседе с Codex используйте плагин Codex Security .

Проверка предварительных требований

Используйте Node.js 24 или 26 либо Node.js 22 начиная с версии 22.13.0. Также требуется Python 3.10 или более поздней версии. Для Python 3.10 дополнительно требуется tomli. Для сканирования с использованием инференса OpenAI необходим доступ к Codex Security. В зависимости от вашей учётной записи и репозитория для сканирования всего репозитория также может потребоваться Trusted Access for Cyber.

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

Настройка и проверка CLI

Запустите общедоступный пакет с помощью npx:

npx @openai/codex-security --version

Команда выводит версию установленного пакета. Используйте info --json, чтобы проверить версию встроенного плагина, или --help, чтобы вывести список команд. Изменения пакета перечислены в разделе Выпуски CLI и SDK.

Вход

Войдите с помощью учётной записи ChatGPT:

npx @openai/codex-security login

На компьютере без браузера добавьте --device-auth и следуйте отображаемым инструкциям по входу. Используйте --auth chatgpt в приведённых ниже командах сканирования, чтобы выбрать этот способ входа, даже если в вашем окружении также присутствует API key.

Сведения об API key и других поставщиках см. в разделе Выбор способа аутентификации для сканирования. Для Amazon Bedrock используйте учётные данные AWS и доступ к моделям вместо входа через ChatGPT или OpenAI API key.

Подготовка сканирования

Замените эти пути на путь к вашему репозиторию и путь к новому каталогу результатов вне его рабочего дерева Git:

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Результаты могут содержать фрагменты исходного кода и сведения об уязвимостях. Выберите место с ограниченным доступом. Если не указать --output-dir, CLI использует свой каталог постоянного состояния.

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

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR" --dry-run

Успешный пробный запуск подтверждает корректность локальных входных данных. Он не запускает сканирование, не загружает учётные данные и не проверяет интерпретатор Python плагина, поэтому не подтверждает, что аутентификация и настройка среды выполнения сработают.

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

Удалите --dry-run, чтобы запустить сканирование:

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR"

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

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

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

По умолчанию уровень серьёзности обнаруженной проблемы не приводит к завершению сканирования с ошибкой. Для машиночитаемого вывода в stdout добавьте --json. Чтобы обнаруженные проблемы приводили к сбою проверки CI, задайте политику уровней серьёзности.

Проверка результатов

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

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

Завершённое сканирование возвращает код 0, если обнаруженные проблемы не достигают заданного порога серьёзности; в противном случае возвращается 1. Пробелы в охвате не меняют код выхода, поэтому код 0 не означает, что проверен каждый файл. Ошибки входных данных, выполнения, целостности результатов или формирования обязательных выходных данных возвращают 2. В справочнике CLI описаны коды выхода.

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

При передаче или архивировании сохраняйте каталог сканирования целиком. Он содержит scan-manifest.json, findings.json и coverage.json вместе с отчётом и вспомогательными артефактами. Полная структура приведена в разделе Артефакты сканирования.

Возврат к сохранённому сканированию

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

npx @openai/codex-security scans list "$REPOSITORY"

Скопируйте идентификатор сканирования из результатов:

npx @openai/codex-security scans show SCAN_ID

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

Выберите следующее сканирование

По вопросам аутентификации, различий между повторными сканированиями и отзывов о ложных срабатываниях см. часто задаваемые вопросы о CLI.