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

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

Настройте Codex Security, запустите локальное сканирование и изучите отчёт, обнаруженные проблемы и покрытие.

Codex Security помогает командам безопасности и разработки находить, подтверждать и устранять уязвимости. Используйте его интерфейс командной строки (CLI), чтобы сканировать собственные репозитории или репозитории, на оценку которых у вас есть разрешение, отслеживать обнаруженные проблемы, а также проверять изменения до их включения.

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

Для CLI требуется Node.js 22 (22.13.0 или более поздней версии), 24 либо 26. Для сканирований, массовых сканирований, экспорта, истории сканирований и сохранённых результатов также требуется Python 3.10 или более поздней версии. Дополнительные сведения см. в разделе Аутентификация и предварительные требования.

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

Запустите CLI с помощью npx и проверьте его версию:

npx @openai/codex-security --version

Чтобы увидеть версию пакета и версию входящего в него плагина, выполните:

npx @openai/codex-security info --json

Сведения об изменениях пакета см. в разделе Выпуски CLI и SDK.

Выведите список доступных команд:

npx @openai/codex-security --help

См. также Справочник по CLI.

Вход

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

npx @openai/codex-security login

На удалённом компьютере или компьютере без графического интерфейса используйте аутентификацию устройства:

npx @openai/codex-security login --device-auth

Для CI и других автоматизированных рабочих процессов задайте OpenAI API key:

export OPENAI_API_KEY="<your-api-key>"

Сведения об учётных данных AWS см. в разделе Настройка Amazon Bedrock. Для OpenRouter или Fireworks задайте API key поставщика и выберите модель с помощью --provider и --model.

Чтобы использовать вход через ChatGPT, когда также задан API key, выберите его явно:

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

Чтобы требовать API key из окружения, выберите аутентификацию с помощью API key:

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

В зависимости от вашей учётной записи и репозитория для сканирования всего репозитория также может потребоваться Trusted Access for Cyber.

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

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

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

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

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

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

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

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

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

Пробный запуск проверяет локальные входные данные, включая все пути --knowledge-base, не запуская Codex, не загружая учётные данные и не проверяя интерпретатор Python плагина.

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

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

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

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

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

По умолчанию CLI записывает ход сканирования и итоговую сводку в stderr. Полный результат сканирования не выводится в stdout. После завершения сканирования выводится примерно такая сводка:

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

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

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

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

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

Выбор модели и уровня рассуждения

По умолчанию сканирования используют gpt-5.6-sol с уровнем рассуждения xhigh. Если задача того требует, выберите другую модель и уровень:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Поддерживаются уровни minimal, low, medium, high, xhigh и max.

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

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

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json содержит сведения о цели, области проверки, источнике и запечатанных артефактах.
  • findings.json содержит сведения о серьёзности, достоверности, расположении, доказательствах и способе устранения каждой обнаруженной проблемы.
  • coverage.json содержит сведения о проверенных поверхностях, исключениях, отложенной работе, открытых вопросах и полноте покрытия.

Покрытие может иметь значение complete, partial или unknown. Ознакомьтесь со всеми отложенными областями и открытыми вопросами, прежде чем считать сканирование доказательством проведённой проверки. Полный контракт артефактов и выходных данных описан в Справочнике по CLI.

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

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

Чтобы исправить проблемы высокой и критической серьёзности без обозревателя:

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

Добавьте --create-pr, чтобы зафиксировать проверенные исправления и открыть запрос на включение изменений в GitHub.

Также можно исправлять сохранённые проблемы или импортировать задачи Linear. См. справочник по validate и patch.

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

Используйте сканирование пути, если репозиторий содержит отдельные сервисы или пакеты:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Проверьте зафиксированные изменения между базовой ревизией и HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Проверьте индексированные и неиндексированные изменения относительно HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

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

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

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Чтобы управлять исполнителями, субагентами и моментом остановки сканирования:

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

Для этих параметров требуется углублённый режим, который поддерживает цели в виде репозитория и пути, но не сканирование различий или рабочего дерева. Здесь --workers управляет независимыми исполнителями стандартного сканирования в рамках одного сканирования, а bulk-scan --workers — параллельными сканированиями репозиториев. --max-time-hours принимает положительное число не более 96, в том числе дробное количество часов. При достижении ограничения сканирование останавливает незавершённых исполнителей, сохраняет результаты завершённых сканирований и объединяет их в итоговый отчёт.

Добавление контекста архитектуры и безопасности

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

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

Добавление пользовательских инструкций по сканированию

Добавьте инструкции, направляющие сканирование на ваши приоритеты безопасности. Для последующих инструкций используйте второй файл:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

Последующий этап выполняется в том же аутентифицированном сеансе после успешных сканирований, а также сканирований с неполным покрытием или ошибками. Если последующий этап завершается с ошибкой, CLI выводит предупреждение и сохраняет завершённое сканирование. Он не выполняется после отмены или сканирования, достигшего ограничения стоимости. Оба параметра также работают с bulk-scan; столбец CSV prompt добавляет инструкции для конкретного репозитория.

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

Используйте --max-cost, чтобы остановить сканирование, когда расчётная стоимость использования модели превысит заданный предел в USD:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

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

Сканирование изменений перед каждым коммитом

Установите в репозитории проверку безопасности Git перед коммитом:

npx @openai/codex-security install-hook

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

Массовое сканирование репозиториев

Войдите в GitHub перед поиском репозиториев:

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

Повторно выполните ту же команду, чтобы продолжить существующее массовое сканирование. Codex Security пропустит завершённые репозитории. Добавьте --max-attempts 3, если нужно повторить попытку после временных ошибок репозитория или сканирования.

Сведения о поиске репозиториев GitHub, подготовке CSV, результатах кампании и настройке Docker см. в разделе Массовое сканирование безопасности.

Массовое сканирование в Docker

Если ваш доступ включает образ Codex Security для Docker, используйте предоставленную усиленную конфигурацию Compose и профиль безопасности на хосте Linux Docker. Хост должен поддерживать создание пространства имён непривилегированного пользователя. Предоставьте CSV репозиториев, храните результаты и данные состояния входа в постоянных подключённых каталогах и передавайте учётные данные через окружение или диспетчер секретов:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Контейнер выполняет массовые сканирования без интерактивных запросов. Используйте CLI вне Docker, если хотите искать репозитории интерактивно. Для закрытых репозиториев передайте GH_TOKEN или GITHUB_TOKEN через окружение или диспетчер секретов. Требования к входу, включая доступ к учётной записи и репозиториям, также применяются к сканированиям в контейнерах.

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

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

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

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

npx @openai/codex-security scans show SCAN_ID

Чтобы просмотреть сохранённые события сканирования и его исполнителей:

npx @openai/codex-security scans logs SCAN_ID

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

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

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

Обнаруженная ранее проблема остаётся открытой, если последнее сканирование её не подтверждает.

Чтобы пометить проверенную проблему как ложноположительное срабатывание, объясните, почему она неприменима:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Последующие сканирования учтут это объяснение, но всё равно повторно проверят текущий код.

Запустите то же сканирование для текущей рабочей копии с исходной конфигурацией:

npx @openai/codex-security scans rerun SCAN_ID

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

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

Формат CSV для массового сканирования, фильтры истории сканирований и параметры команд описаны в Справочнике по CLI.

Продолжите работу по сценарию, соответствующему вашей цели: