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

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

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

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

Проверьте предварительные требования

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

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

Установите опубликованный пакет:

npm install @openai/codex-security

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

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.

Чтобы использовать вход через 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

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

Выполните первое сканирование

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

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

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

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: 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.

Изучите результаты

Откройте 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.

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

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

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

Углублённый режим поддерживает цели в виде репозитория и пути, но не сканирование различий или рабочего дерева.

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

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

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

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

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

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

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

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

Установите для репозитория проверку безопасности 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

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

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

Запускайте массовое сканирование в Docker

Если ваш уровень доступа включает образ Docker для Codex Security, используйте предоставленную защищённую конфигурацию 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"

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

npx @openai/codex-security scans show SCAN_ID

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

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 match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

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