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

Используйте npx @openai/codex-security bulk-scan, чтобы проверить репозитории в рамках одной кампании. Находите репозитории в личной учетной записи GitHub или организации либо предоставьте CSV, в котором для каждого репозитория указана точная ревизия Git.

Выбор источника репозиториев

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

Поиск репозиториев GitHub

Войдите в систему с помощью GitHub CLI:

gh auth login

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

npx @openai/codex-security bulk-scan

CLI проведет вас через следующие этапы:

1. Выберите личную учетную запись GitHub или организацию.
2. Просмотрите репозитории, активные в течение последних 90 дней.
3. Выполните поиск в списке репозиториев и выберите репозитории для сканирования.
4. Выберите каталог для результатов сканирования.
5. Проверьте выбранные репозитории и подтвердите кампанию.

При поиске исключаются архивные репозитории и форки. CLI записывает точный коммит ветки по умолчанию для каждого выбранного репозитория в <output-directory>/repositories.csv. Сканирование не начнется, пока вы не подтвердите выбор.

Чтобы использовать GitHub Enterprise Server, сначала войдите на свой хост GitHub:

gh auth login --hostname github.example.com

Задайте GH_HOST при запуске поиска репозиториев:

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

Для интерактивного поиска необходим терминал. В CI, контейнерах или при наличии подготовленного списка репозиториев используйте реестр CSV.

Создание CSV с репозиториями

Создайте CSV, содержащий по одной строке для каждого репозитория с закрепленной ревизией:

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

CSV поддерживает следующие столбцы:

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

git -C /path/to/repository rev-parse HEAD

Запуск кампании из CSV

Передайте CSV и закрытый выходной каталог, расположенный вне репозиториев:

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

--workers управляет параллельным сканированием репозиториев; значение по умолчанию — 4. Этот параметр не задает количество независимых исполнителей стандартного сканирования внутри каждого глубокого сканирования; настройте эти ограничения с помощью [deep_scan]. Используйте --mode deep, чтобы выбрать глубокое сканирование для строк, в которых не задан собственный mode. Каждая строка CSV по-прежнему может задавать собственный режим сканирования и область репозитория.

Задайте [deep_scan].max_time_hours, чтобы ограничить выполнение исполнителей для каждого глубокого сканирования в кампании. Флаг --max-time-hours работает с scan, но не с bulk-scan.

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

Передача контекста и инструкций по безопасности

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

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

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

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

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

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

По умолчанию массовые сканирования используют gpt-5.6-sol с уровнем рассуждений xhigh. Чтобы выбрать другую модель и уровень для кампании по CSV, используйте модель, доступную с вашими учётными данными. Если вы входите через ChatGPT, проверьте доступность GPT-6.1 Sol при таком входе, прежде чем использовать этот пример:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-6.1-sol \
  --effort medium

Те же параметры работают при интерактивном поиске репозиториев:

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

Доступные уровни рассуждений зависят от выбранной модели. Массовые сканирования поддерживают minimal, low, medium, high, xhigh и max; для GPT-6.1 Sol требуется как минимум low.

Чтобы использовать OpenRouter или Fireworks, задайте соответственно OPENROUTER_API_KEY или FIREWORKS_API_KEY и укажите --provider и --model. Сведения об учетных данных и примеры см. в разделе Настройка OpenRouter или Fireworks или Настройка Amazon Bedrock.

Проверка результатов кампании

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

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

• manifest.json содержит сведения о репозиториях, закрепленных ревизиях, областях, режимах сканирования и общих либо относящихся к репозиторию инструкциях кампании.
• results.jsonl содержит сведения о каждой попытке обработки репозитория, ее статусе, каталоге артефактов и доступных данных о стоимости или ошибках.
• report.md содержит удобочитаемый отчет об одной попытке обработки репозитория.
• findings.json и coverage.json содержат обнаруженные в рамках этой попытки проблемы и проверенную область.

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

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Результаты могут содержать фрагменты исходного кода и сведения об уязвимостях. Ограничьте доступ к выходному каталогу и храните его вне сканируемых репозиториев. Определите срок хранения результатов.

Возобновление кампании

Выполните исходную команду с теми же CSV и выходным каталогом:

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

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

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

Повторные попытки при ошибках репозитория

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

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

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

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

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

Репозиторий Codex Security содержит защищённую конфигурацию Compose для автоматизированных кампаний на основе CSV на хосте Docker под Linux. Хост должен поддерживать непривилегированное создание пользовательских пространств имён.

Подключайте CSV с репозиториями, результаты сканирования и данные сеанса входа из постоянных каталогов. Передавайте учетные данные OpenAI через переменные окружения или диспетчер секретов. Для закрытых репозиториев GitHub таким же способом предоставьте GH_TOKEN или GITHUB_TOKEN.

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

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

Чтобы возобновить кампанию, используйте те же подключенные CSV и выходной каталог. Для GitHub Enterprise Server задайте в CODEX_SECURITY_GIT_HOST свой хост GitHub.

Все доступные флаги см. в справочнике по команде bulk-scan . Ответы на распространенные вопросы о покрытии сканирования и обнаруженных проблемах см. в часто задаваемых вопросах о CLI .