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

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

Запустите CLI с помощью npx @openai/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] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--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.

Использование OpenRouter или Fireworks

Выберите OpenRouter с его API key и явно указанной моделью:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Выберите Fireworks с его API key и явно указанной моделью:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Оба провайдера также поддерживают bulk-scan.

Использование 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 вместо --auth, входа через ChatGPT или API key OpenAI используются учётные данные AWS. И 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

Настройка глубокого сканирования

Используйте эти параметры с --mode deep для управления параллелизмом обработчиков и временем выполнения:

--subagents принимает ноль или положительное целое число. --max-time-hours принимает положительное число не больше 96. Остальным параметрам требуется положительное целое число. Эти параметры недоступны для стандартного сканирования.

Например, чтобы использовать два обработчика, разрешить до десяти запусков и остановить их работу через 1,5 часа:

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

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

Задайте постоянные значения по умолчанию в ~/.codex/codex-security/config.toml либо в $CODEX_HOME/codex-security/config.toml, если задан CODEX_HOME:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

Параметры командной строки переопределяют эти значения. scan --workers управляет независимыми обработчиками стандартного сканирования внутри одного глубокого сканирования; bulk-scan --workers управляет параллельным сканированием репозиториев. Задавайте stop_after_consecutive_errors только в файле TOML; значение по умолчанию — 3.

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

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

Добавление инструкций для сканирования

Чтобы добавить инструкции для сканирования, укажите текстовый файл или файл Markdown с помощью --scan-prompt-file. Используйте --post-scan-prompt-file для выполнения дополнительных инструкций в том же аутентифицированном сеансе после успешного сканирования, а также сканирования с неполным покрытием или ошибками:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

Например, с помощью запроса сканирования можно сосредоточить проверку на границах авторизации, а в дополнительной инструкции запросить создание нового файла post-scan-summary.md в каталоге сканирования. Если дополнительная инструкция завершится ошибкой, CLI выведет предупреждение и сохранит завершённое сканирование. Дополнительная инструкция не выполняется после отмены или достижения сканированием ограничения стоимости.

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

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

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

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

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

Каталог вывода должен находиться за пределами сканируемого каталога и любого охватывающего его рабочего дерева 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}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--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 и prompt настраивают отдельные репозитории:

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

Используйте --knowledge-base PATH, чтобы предоставить документы по безопасности всем репозиториям. Используйте --scan-prompt-file FILE, чтобы добавить общие инструкции по сканированию; столбец CSV prompt добавляет инструкции для конкретного репозитория после этого общего запроса. --post-scan-prompt-file FILE выполняет дополнительные инструкции после каждого сканирования, включая сканирования с неполным покрытием или ошибками. Они не выполняются после отмены или достижения сканированием ограничения стоимости.

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

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

Добавьте --show-linked-findings, чтобы включить ссылки на находки из предыдущих сканирований.

Повторно просканировать текущую рабочую копию с исходной конфигурацией:

npx @openai/codex-security scans rerun SCAN_ID

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

Просмотр сохранённых журналов сканирования

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

npx @openai/codex-security scans logs SCAN_ID

Добавьте --json, чтобы получить машиночитаемый результат с полной информацией.

Сопоставление и сравнение находок

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

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

При сравнении автоматически сопоставляются находки с одной первопричиной и повторно используются сохранённые сопоставления. Чтобы явно сохранить сопоставления, используйте scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

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

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

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

codex-security findings

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

npx @openai/codex-security findings list

Передайте путь репозитория, чтобы проверить другую рабочую копию:

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

Добавьте --json для структурированного вывода. Список включает находки, обнаруженные при последнем сканировании, и более ранние находки, не подтверждённые при этом сканировании.

Обратите внимание: более ранние находки остаются открытыми, пока их не устранят или не отклонят (отсутствие в последнем сканировании не считается доказательством исправления).

Чтобы отметить проверенную находку как ложноположительную:

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

Без --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 publish scan

Опубликовать все находки из завершённого сканирования в Linear:

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

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

При каждом непробном запуске предпринимается попытка создать новую задачу для каждой находки. Повторная публикация того же сканирования не сопоставляет, не обновляет и не использует повторно существующие задачи. Если некоторые находки опубликовать не удалось, команда сохраняет успешно созданные задачи и возвращает код завершения 2. При использовании --json перед повторной попыткой проверьте результаты created и failed, чтобы избежать дубликатов.

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

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

Публикация через подключённое приложение Linear

Если API key Linear отсутствует, команда запускает Codex с вашей существующей конфигурацией и подключённым приложением Linear. Перед публикацией войдите в систему и подключите Linear к своей учётной записи Codex:

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Публикация с API key Linear

Если указан --linear-api-key или CODEX_SECURITY_LINEAR_API_KEY, публикация выполняется непосредственно через API Linear без запуска Codex. При прямой публикации задачи остаются без исполнителя, если вы его не выбрали:

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

Значения командной строки переопределяют соответствующие переменные окружения. Для API key предпочтительнее использовать CODEX_SECURITY_LINEAR_API_KEY, а не --linear-api-key, поскольку аргументы командной строки могут отображаться в истории оболочки и списках процессов.

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

Исправление находок после сканирования

Используйте scan --patch для исправления находок после полного сканирования. Для этого требуется @openai/codex-security версии 0.1.15 или новее. Порог серьёзности по умолчанию — low. Эта команда выбирает находки высокого и критического уровня:

npx @openai/codex-security scan . --patch --patch-severity high --json

Проверенные и уже исправленные находки не запускают --fail-on-severity.

Исправление сохранённых находок

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

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest выбирает последнее завершённое сканирование текущего репозитория. Команды для сохранённых находок поддерживают --json; текстовые значения и входные файлы — нет.

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

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

Если отправка изменений или создание запроса на их включение завершатся ошибкой, выполните выведенную команду patch --resume-pr BRANCH из того же репозитория для повторной попытки.

Исправление задач Linear

Задайте CODEX_SECURITY_LINEAR_API_KEY или LINEAR_API_KEY для персонального API key либо LINEAR_ACCESS_TOKEN для токена OAuth. Используйте переменную окружения вместо --linear-api-key KEY, чтобы ключ не попал в историю оболочки.

Импортируйте задачу по идентификатору или URL. Повторите --linear-issue, чтобы выбрать несколько задач:

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

Используйте --linear-project, чтобы выбрать открытые задачи проекта. Добавьте --linear-filter, чтобы сузить выборку:

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

CLI исключает завершённые и отменённые задачи, если фильтр не задаёт state. Он не изменяет задачи Linear.

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.

В интерактивных терминалах отображается динамическая панель с текущей фазой сканирования, проверенными файлами, активностью, использованием токенов и оценочной стоимостью. В CI и при перенаправленном выводе ход выполнения отображается обычным текстом. Добавьте --headless, чтобы использовать обычный текст в интерактивном терминале:

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

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

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

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

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

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

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

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

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

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

Вывод JSON

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

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

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

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

Разрешения для локального сканирования

Сканирования CLI и SDK выполняются с вашими локальными разрешениями операционной системы. Каждое сканирование использует профиль файловой системы codex_security_scan и задаёт для approvalPolicy значение "never". Этот профиль разрешает чтение локальной файловой системы и запись в корни рабочих пространств и выбранный каталог состояния сканирования. При сканировании интерактивное подтверждение не запрашивается.

Параметры, переданные через --codex CLI или codexOverrides SDK, включая approval_policy, sandbox_mode и разрешения файловой системы, не могут заменить или ограничить эти средства контроля сканирования. Ограничения хоста и сети продолжают действовать.

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

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

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

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

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

Для CLI требуется Node.js 22 (22.13.0 или новее), 24 либо 26. Для сканирования, массового сканирования, экспорта, истории сканирования и сохранённых находок также требуется Python 3.10 или новее. Для Python 3.10 дополнительно требуется tomli. Используйте --python с scan, bulk-scan или export либо задайте PYTHON для любой команды, использующей Python.

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

Текстовые псевдонимы

• --output FILE|-