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

Запуск Codex Security в GitHub Actions

Сканируйте pull request и репозитории с помощью Codex Security Action, сохраняйте отчёты, загружайте SARIF и настраивайте применение политик.

Запускайте Codex Security в GitHub Actions, чтобы проверять изменения в pull request или сканировать репозиторий по расписанию. Action устанавливает CLI, сохраняет структурированные отчёты и добавляет сводку задания и аннотации к исходному коду. Начните с результатов в рекомендательном режиме, затем настройте применение политик после оценки охвата и качества сканирования.

Подготовьте рабочий процесс

Для запуска сканирования требуется доступ к Codex Security. Чтобы добавить OpenAI API key:

  1. В репозитории GitHub откройте Settings → Secrets and variables → Actions.
  2. Выберите New repository secret.
  3. Введите CODEX_SECURITY_API_KEY в качестве имени и вставьте OpenAI API key в качестве значения. Сохраните секрет.

Приведённые ниже примеры рабочих процессов передают этот секрет в Codex Security Action автоматически. Добавлять API key в файл рабочего процесса не требуется.

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

Добавьте рабочий процесс GitHub Actions

Сканируйте репозиторий по расписанию

Следующий рабочий процесс сканирует ветку по умолчанию каждый понедельник в 07:23 UTC. Его также можно запустить вручную на вкладке Actions в GitHub. Он использует раннер x64 с Ubuntu 24.04, размещённый в GitHub, и автоматически настраивает необходимую песочницу.

  1. В репозитории выберите Add file → Create new file.
  2. Назовите файл .github/workflows/codex-security-repository.yml.
  3. Вставьте приведённый ниже рабочий процесс и сохраните его коммитом в ветке по умолчанию.
name: Codex Security repository

on:
  workflow_dispatch:
  schedule:
    - cron: "23 7 * * 1" # Mondays at 07:23 UTC

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-24.04
    timeout-minutes: 120
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Scan the repository
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: repository
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Адаптация раннера: Action требуются Node.js 24 и Python 3.11 или новее, которые доступны на этом раннере. При настройке песочницы устанавливается пакет bubblewrap и перед сканированием загружается предоставленный профиль AppArmor. Одной установки пакета на этом раннере недостаточно.

Чтобы запустить рабочий процесс вручную, откройте Actions → Codex Security repository → Run workflow. Откройте завершённый запуск, чтобы изучить сводку, аннотации и доступные для скачивания отчёты.

Выявленные проблемы только включаются в отчёты, поскольку fail-on-severity имеет значение none. Ошибки сканера и обязательного формирования отчётов по-прежнему приводят к сбою задания.

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

paths: |
  src/api
  src/auth

Для путей требуется scope: repository; glob-шаблоны не раскрываются. Для сканирования изменений не указывайте paths. Сохраните persist-credentials: false и запускайте сканирование сразу после получения рабочей копии.

Сканируйте изменения в pull request

Используя тот же секрет, создайте .github/workflows/codex-security-pr.yml:

name: Codex Security PR

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read

concurrency:
  group: codex-security-pr-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    name: Codex Security
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Scan PR changes
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: diff
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Откройте или обновите PR из ветки того же репозитория. Action использует полную историю, чтобы найти точную базу слияния, и сканирует изменения вплоть до полученного в рабочую копию головного коммита PR. Просмотрите проверку Codex Security в разделе Checks PR. Начните с выявленных проблем в рекомендательном режиме, затем выберите политику серьёзности, когда будете готовы блокировать изменения по результатам проверки.

Этот пример пропускает PR из форков и PR, открытые dependabot[bot]. Пропущенное задание не подтверждает проведение проверки безопасности. Чтобы включить такие PR от ботов, удалите исключение по автору и также настройте CODEX_SECURITY_API_KEY как секрет для dependabot[bot]. Action не поддерживает pull_request_target и workflow_run.

Сканер читает применимые инструкции SECURITY.md из рабочей копии, включая изменения политик в PR. Проверяйте эти изменения вместе с кодом.

Настройте дополнительный доступ к Daybreak

Daybreak необязателен. Оба примера рабочих процессов используют gpt-6-sol. Если ваша организация получила одобрение на Trusted Access for Cyber, удалите # перед cyber-access-program в блоке with шага сканирования:

model: gpt-6-sol
cyber-access-program: daybreak_blue

Используйте API key проекта, в котором включён Daybreak Blue и есть доступ к gpt-6-sol.

Входной параметр программы также принимает standard. Без доступа к Daybreak используйте модель, доступную вашему API key со стандартными мерами защиты, и не указывайте cyber-access-program либо задайте ему значение standard. Выбор модели или программы не предоставляет доступ. См. рекомендации по доступу к Daybreak для Action.

Отказ или блокировка системой безопасности, прерывающие сканирование, приводят к сбою Action, в том числе когда fail-on-severity имеет значение none. Этот параметр управляет политикой обработки выявленных проблем, а не ошибками сканера.

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

В обоих примерах рабочих процессов не указан max-cost, поэтому порог остановки по оценочной стоимости отсутствует. Чтобы задать его, укажите положительную сумму в долларах США через параметр max-cost. Для сканирования напрямую через CLI используйте --max-cost.

Для ограничения стоимости CLI должен поддерживать расчёт стоимости выбранной модели. Оценочный порог не является жёстким лимитом расходов: стоимость уже выполняющихся запросов может привести к его превышению. Если сканирование остановилось при достижении порога, изучите выявленные проблемы и coverage.json. Поведение при ограничении стоимости см. в разделе Параметры вывода и политик.

Сохраняйте отчёты и загружайте SARIF

В примерах задан upload-artifacts: "true" для сохранения доступных для скачивания отчётов в течение семи дней. Отчёты могут содержать фрагменты исходного кода, доказательства уязвимостей и сведения об их устранении. Выберите срок хранения и доступ к репозиторию, подходящие для вашего кода. Action загружает только проверенные отчёты из своего списка разрешённых файлов; не загружайте рекурсивно его выходные данные results-directory.

Загрузка SARIF необязательна. Для закрытых или внутренних репозиториев включите GitHub Code Security перед загрузкой. Замените блок permissions рабочего процесса следующим:

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories

Затем добавьте этот шаг после сканирования в любом из рабочих процессов:

- name: Upload security findings
  if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }}
  uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
  with:
    sarif_file: ${{ steps.security.outputs.sarif-path }}
    sha: ${{ steps.security.outputs.scanned-sha }}
    ref: ${{ steps.security.outputs.analysis-ref }}
    category: codex-security-repository

Для рабочего процесса PR используйте category: codex-security-pr, чтобы у каждой области проверки была своя категория. Сохраните id: security в шаге сканирования. Полные проверенные отчёты остаются доступными для загрузки, когда выявленные проблемы нарушают политику серьёзности. SARIF не загружается при сбое или прерывании сканирования, пустом наборе изменений и пробных запусках.

Все настройки, поля состояния и пути отчётов см. в справочнике входных и выходных параметров Action.

Выберите политику серьёзности

Изначально рабочие процессы GitHub используют fail-on-severity: none. Чтобы проверка завершалась сбоем при выявлении проблем высокого или критического уровня в завершённом сканировании, измените входной параметр шага сканирования:

fail-on-severity: high

Сделайте Codex Security обязательной проверкой статуса в правилах репозитория, чтобы блокировать слияния при сбое задания PR. GitHub считает задание, пропущенное по условию, успешным, даже для обязательных проверок. PR из форков и PR от dependabot[bot] проходят эту проверку без сканирования. Чтобы блокировать такие пропуски, требуйте успешного завершённого сканирования.

Action следует результату CLI:

  • Код выхода 0 задаёт scan-status: completed и policy-status: passed.
  • Код выхода 1 задаёт scan-status: completed и policy-status: failed; шаг завершается сбоем при выявлении проблем с уровнем серьёзности не ниже заданного.
  • Код выхода 2 или прерванный процесс задаёт scan-status: failed и policy-status: not-evaluated; шаг завершается сбоем.
  • Некорректные или отсутствующие обязательные отчёты, изменение рабочей копии, ошибки загрузки запрошенных артефактов и ошибки очистки среды выполнения также приводят к сбою шага.

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

Требуйте успешного завершённого сканирования

Для более строгой политики добавьте отдельную проверку допуска, которая запускается даже при сбое задания сканирования или его пропуске GitHub. Шаг внутри задания сканирования не может проверить пропущенное задание, поскольку ни один из его шагов не выполняется.

В рабочем процессе PR добавьте это сопоставление outputs в существующее задание security, на том же уровне отступа, что и runs-on и steps:

outputs:
  scan-status: ${{ steps.security.outputs.scan-status }}

Затем добавьте это задание в jobs рядом с существующим заданием security:

security-gate:
  name: Codex Security gate
  needs: security
  if: ${{ always() }}
  runs-on: ubuntu-24.04
  steps:
    - name: Require a successful, completed scan
      env:
        SCAN_RESULT: ${{ needs.security.result }}
        SCAN_STATUS: ${{ needs.security.outputs.scan-status }}
      run: test "$SCAN_RESULT" = success && test "$SCAN_STATUS" = completed

Сделайте Codex Security gate обязательной проверкой статуса для этой политики. Она требует и успешного выполнения задания сканирования, и scan-status: completed. Проверка обоих условий сохраняет сбои, вызванные политикой серьёзности, формированием отчётов и очисткой, даже если само сканирование завершилось.

С исключениями из примера эта проверка допуска блокирует PR из форков и PR от dependabot[bot]. Она также блокирует пустые наборы изменений и пробные запуски, которые Action помечает как skipped. Проверка допуска не сканирует исключённые PR. Выбирайте эту политику, только если такие случаи должны препятствовать слиянию.

Устранение неполадок сканирования

  • Неизвестная ссылка Git или неожиданный набор изменений: Получите головной коммит PR в рабочую копию с помощью fetch-depth: 0.
  • Ошибка запуска песочницы: В Ubuntu 24.04 установите пакет bubblewrap и загрузите профиль AppArmor перед запуском Action. Одна лишь установка пакета не загружает необходимый профиль.
  • Отсутствуют учётные данные: Убедитесь, что CODEX_SECURITY_API_KEY доступен доверенному рабочему процессу и передаётся в переменную окружения OPENAI_API_KEY шага сканирования.
  • Ошибка настройки Python: Action требуется Python 3.11 или новее.
  • Примечания об охвате: Изучите исключения из области проверки и отложенные исследования в coverage.json. Эти примечания не вызывают ошибок выполнения и не позволяют обойти политику серьёзности.
  • Отсутствует SARIF: Проверьте scan-status, report-status и sarif-upload-ready. Если необязательный SARIF отсутствует, Action выдаёт предупреждение, не меняя исход сканирования; ошибки загрузки запрошенных артефактов по-прежнему приводят к сбою задания.
  • Ошибка загрузки SARIF: Убедитесь, что ваша организация включила GitHub Code Security для репозитория и что рабочий процесс предоставляет разрешения actions: read, contents: read и security-events: write.

Описание всех команд, флагов, артефактов и выходных полей см. в справочнике CLI. Для других провайдеров см. обзор CI/CD.