Справочник по Codex Security CLI

Используйте этот справочник, чтобы проверить поддерживаемые команды codex-security, флаги, форматы вывода и поведение при завершении. Для пошагового выполнения первого сканирования начните с краткого руководства по CLI.

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

npm install @openai/codex-security

Вызывайте установленный пакет как npx @openai/codex-security. Если исполняемый файл доступен в PATH, можно использовать codex-security напрямую.

Обзор команд

usage: codex-security [--version] <command> [options]

CLI предоставляет следующие команды:

CLI также предоставляет следующие команды интеграции:

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

npx @openai/codex-security --help

Добавьте --help к команде, чтобы изучить её аргументы и параметры:

npx @openai/codex-security scan --help

codex-security --version выводит установленную версию и завершает работу. codex-security info --json сообщает версии SDK и встроенного плагина. Ни одна из этих команд не требует Python.

Найдите команды и подключите агентов

Выведите машиночитаемый агентами манифест команд:

npx @openai/codex-security --llms

Просмотрите схему аргументов сканирования в формате JSON:

npx @openai/codex-security scan --schema --format json

Создайте автодополнения Bash:

npx @openai/codex-security completions bash

Для соответствующих оболочек замените bash на zsh или fish.

Результаты сканирования поддерживают --format toon|json|yaml|jsonl и --full-output. Этот --format уровня фреймворка отличается от --export-format, который выбирает формат артефакта, экспортируемого из завершённого сканирования. В общей справке по командам также указан md, однако результаты сканирования не поддерживают вывод Markdown.

Зарегистрируйте CLI как сервер MCP:

npx @openai/codex-security mcp add

Синхронизируйте навыки Codex Security со своими агентами:

npx @openai/codex-security skills add

Через MCP доступна только команда метаданных info, предназначенная для чтения. Сканирование, экспорт, аутентификация, проверка и исправление доступны только через CLI.

codex-security scan

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

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

По умолчанию repository указывает на текущий каталог.

Выберите аутентификацию сканирования

Используйте --auth auto, значение по умолчанию, чтобы выбирать учётные данные автоматически. Когда доступны и вход через ChatGPT, и OPENAI_API_KEY или CODEX_API_KEY, при интерактивном сканировании с текстовым выводом предлагается выбрать учётные данные. В CI, при сканировании с JSON и JSONL, а также при другом сканировании без интерактивного терминала используется API key из окружения. Пробные запуски не запрашивают и не загружают учётные данные.

Чтобы использовать сохранённые учётные данные, передайте --auth chatgpt:

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

Чтобы использовать API key из окружения, передайте --auth api-key:

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

Чтобы сохранённые учётные данные автоматически использовались по умолчанию, выполните unset OPENAI_API_KEY CODEX_API_KEY.

Используйте Amazon Bedrock

Выберите Amazon Bedrock с помощью --provider amazon-bedrock и явно укажите модель Bedrock с помощью --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Задайте AWS_REGION и выполните аутентификацию с помощью AWS_BEARER_TOKEN_BEDROCK, стандартных ключей доступа AWS, профиля AWS, веб-удостоверения, учётных данных контейнера или стандартной цепочки учётных данных AWS. При сканировании Bedrock используются учётные данные AWS вместо --auth, входа через ChatGPT или OpenAI API key. И scan, и bulk-scan поддерживают --provider.

Выберите цель сканирования

Для каждого сканирования выберите один тип цели.

--path, --diff и --working-tree являются взаимоисключающими. Для --head требуется --diff, а для --base — --working-tree. Углублённый режим поддерживает цели в виде репозитория и пути.

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

Просканируйте весь репозиторий:

npx @openai/codex-security scan .

Просканируйте выбранные пути:

npx @openai/codex-security scan . --path src --path tests

Просканируйте зафиксированные изменения:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Просканируйте индексированные и неиндексированные изменения:

npx @openai/codex-security scan . --working-tree --base HEAD

Выполните углублённую проверку репозитория:

npx @openai/codex-security scan . --mode deep

Добавьте контекст безопасности

Используйте --knowledge-base PATH, чтобы предоставить документы по архитектуре, модели угроз или политики безопасности. Повторите параметр для дополнительных файлов или каталогов:

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

Поддерживаются документы в файлах .md, .markdown, .txt, .pdf и .docx. CLI выполняет рекурсивный поиск по каталогам, отклоняет входные пути-ссылки, пропускает ссылки внутри каталогов и хранит извлечённое содержимое документов вне сохранённых результатов сканирования.

Задайте параметры вывода и политики

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

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

Если параметр --output-dir не указан, результаты сохраняются в $CODEX_HOME/state/plugins/codex-security/scans/<repository>. По умолчанию CODEX_HOME имеет значение ~/.codex. Задайте CODEX_SECURITY_STATE_DIR, чтобы вместо этого сохранять результаты в $CODEX_SECURITY_STATE_DIR/scans/<repository>. Эти каталоги могут содержать фрагменты исходного кода и сведения об уязвимостях, поэтому настройте для них подходящие разрешения и сроки хранения.

Workbench хранит историю сканирований в $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. При задании CODEX_SECURITY_STATE_DIR база данных Workbench также перемещается.

Выходной каталог должен находиться за пределами сканируемого каталога и любого охватывающего его рабочего дерева Git. Сканирование может заменить существующий каталог результатов с помощью --archive-existing.

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

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

По умолчанию сканирование только создаёт отчёт. Добавьте --fail-on-severity, чтобы применить политику серьёзности в CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

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

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Настройте среду выполнения

Используйте параметры среды выполнения, когда нужно явно указать модель, интерпретатор, плагин или значение конфигурации Codex.

Чтобы выбрать другую модель и уровень глубины рассуждений без записи TOML:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

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

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

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

npx @openai/codex-security install-hook

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

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

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

Полное руководство по поиску в GitHub, инвентарным спискам CSV, результатам кампаний и сканированию в контейнерах см. в разделе Массовое сканирование безопасности.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Запустите npx @openai/codex-security bulk-scan без аргументов, чтобы выбрать репозитории интерактивно. Для этого процесса требуется вход через GitHub CLI.

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

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

Для подготовленного списка репозиториев укажите CSV и --output-dir:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

CSV должен содержать столбцы id, repository и revision. Ревизии должны быть полными хешами коммитов. Необязательные столбцы scope и mode настраивают отдельные репозитории:

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers ограничивает число одновременных сканирований и по умолчанию имеет значение 4. По умолчанию --mode имеет значение standard, а --max-attempts — 1. Задайте --max-attempts, если требуется повторить попытку для репозитория после ошибки. Запустите ту же команду ещё раз, чтобы возобновить массовое сканирование из существующего выходного каталога. CLI пропускает завершённые репозитории, только если зарегистрированные для них артефакты результатов всё ещё присутствуют.

Сведения о кампаниях в контейнерах см. в разделе Массовое сканирование в Docker.

codex-security scans

Найдите сохранённые сканирования

Выведите сохранённые сканирования текущего каталога:

npx @openai/codex-security scans

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

npx @openai/codex-security scans list /path/to/repository

Найдите сканирования, хранящиеся в указанном выходном каталоге:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Изучите или повторите сканирование

Покажите результаты и конфигурацию сохранённого сканирования:

npx @openai/codex-security scans show SCAN_ID

Повторите сканирование для текущего состояния репозитория, используя исходную конфигурацию:

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

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

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

npx @openai/codex-security scans match --all

Результаты могут различаться даже при повторном запуске с той же конфигурацией. Сопоставление и сравнение отслеживают изменения; они не делают результаты детерминированными и не доказывают, что уязвимость больше не существует. Используйте validate, чтобы повторно проверить критически важную проблему безопасности в текущем коде.

codex-security findings

Зарегистрируйте проверенную проблему как ложное срабатывание:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Изучите сохранённое сканирование, чтобы определить экземпляр проблемы:

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"

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

codex-security export

Экспортируйте CSV, JSON или SARIF из завершённого запечатанного сканирования. При экспорте артефакты сканирования проверяются перед записью вывода, а среда выполнения Codex и учётные данные остаются без изменений.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir — каталог завершённого сканирования.

--source-root работает только с --export-format sarif. JSON сохраняет запечатанный документ с обнаруженными проблемами. CSV содержит переносимые столбцы с проблемами и не включает локальное состояние сортировки Workbench.

Без --output CLI записывает SARIF в results.sarif, JSON в findings.json, а CSV в findings.csv в текущем рабочем каталоге. Экспортированные данные могут содержать фрагменты исходного кода и сведения об уязвимостях. Запустите команду вне репозитория или передайте --output с закрытым путём за пределами сканируемой рабочей копии.

Запишите SARIF в файл:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Запишите SARIF в stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Экспортируйте обнаруженные проблемы в JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Экспортируйте обнаруженные проблемы в CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate и codex-security patch

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

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

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

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

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

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

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login, logout и info

Войдите интерактивно:

npx @openai/codex-security login

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

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

Проверьте текущий вход:

npx @openai/codex-security login status

Удалите сохранённые данные входа:

npx @openai/codex-security logout

Сохраните API key, передав его через stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Сохраните корпоративный токен доступа:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

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

npx @openai/codex-security info --json

Когда CLI предоставляется как сервер MCP, info является единственной доступной командой. Сканирование, экспорт, вход, проверка и исправление доступны только через CLI.

Чтение вывода сканирования

По умолчанию сканирование отправляет ход выполнения, итоговые сводки и ошибки в stderr, не записывая полный результат сканирования в stdout. Запросите --json, --format или --full-output, чтобы отправить структурированные результаты сканирования в stdout.

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

Добавьте --verbose, чтобы вывести в stderr очищенные от конфиденциальных данных сведения о жизненном цикле, аутентификации, ходе выполнения и стоимости:

npx @openai/codex-security scan . --verbose

Задайте CODEX_SECURITY_LOG_LEVEL=debug, чтобы включить ту же диагностику без флага. LOG_LEVEL=debug также включает диагностику, когда CODEX_SECURITY_LOG_LEVEL не задан.

Эти элементы управления журналированием применяются только к CLI. Учётные данные и идентификаторы поставщиков остаются скрытыми, а структурированные результаты сканирования — в stdout.

Итоговая сводка

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

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Информационные проблемы учитываются в общем числе в сводке. Политики серьёзности оценивают только проблемы critical, high, medium и low.

Вывод JSON

scan --json записывает в stdout один полный документ JSON. Его структура верхнего уровня:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

Ход выполнения, итоговые сводки, уведомления об архивации и ошибки остаются в stderr. Завершённое сканирование всё равно выводит полный результат JSON, когда политика серьёзности возвращает код завершения 1 или неполное покрытие — код 2.

Артефакты сканирования

Завершённое сканирование хранит удобочитаемый отчёт и структурированные артефакты вместе:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Структурированные файлы выполняют разные задачи:

Полнота покрытия имеет три значения:

• complete: сканирование фиксирует полное покрытие выбранной области.
• partial: сканирование фиксирует отложенную работу или другие ограничения покрытия.
• unknown: полнота покрытия сканирования указана как неизвестная.

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

Коды завершения и сигналы

CLI использует следующие коды завершения:

Любое сканирование с покрытием partial или unknown возвращает 2 даже без политики серьёзности. Когда запрошен структурированный вывод, завершённые сканирования всё равно записывают доступные результаты в stdout. После прерывания или ошибки среды выполнения CLI выводит расположение всех частичных результатов.

Аутентификация и предварительные требования

Задайте OPENAI_API_KEY или CODEX_API_KEY, войдите с помощью npx @openai/codex-security login или используйте существующий файловый вход Codex. Для Amazon Bedrock используйте API key Bedrock или стандартную цепочку учётных данных AWS.

Сведения о выборе учётных данных см. в разделе Выбор аутентификации сканирования.

Для CI ограничьте область действия API key шагом сканирования и используйте доверенный рабочий процесс.

Для CLI требуется Node.js 22 или более поздней версии. Для запуска сканирования или экспорта обнаруженных проблем также требуется Python 3.10 или более поздней версии. Для Python 3.10 также требуется tomli. Используйте --python или PYTHON, чтобы выбрать интерпретатор, когда автоматическое обнаружение не подходит.

Продолжите с кратким руководством по CLI, руководством по массовому сканированию, ответами на часто задаваемые вопросы о CLI, руководством по CI или руководством по TypeScript SDK.

Псевдонимы в виде обычного текста

• --output FILE|-