Codex Security'yi CI'da çalıştırma

Bir pull request veya merge request'teki değişiklikleri tam olarak incelemek, bulguları ve kapsamı korumak ve isteğe bağlı olarak seçilen bir önem derecesinde denetimi başarısız kılmak için Codex Security CLI'ı CI'da çalıştırın. Önce bilgilendirme amaçlı sonuçlarla başlayın, tarama kalitesini ve çalışma süresini inceleyin, ardından deponuza uygun bir önem derecesi politikası ekleyin.

Bu kılavuz GitHub Actions ve GitLab CI/CD örnekleri içerir. Aynı tarama ve dışa aktarma komutları diğer CI sistemlerinde de çalışır.

İş akışını hazırlama

OpenAI API key'i CI sağlayıcınızın gizli değer deposunda CODEX_SECURITY_API_KEY olarak saklayın.

Bu gizli değeri doğrudan tarama adımının OPENAI_API_KEY ortam değişkenine eşleyin. Kimlik bilgisinin kapsamını tarama işlemiyle sınırlı tutun ve açıkça seçmek için --auth api-key kullanın.

Çalıştırıcı için gerekenler:

Node.js 22 veya üzeri.
Python 3.10 veya üzeri.
Depo checkout'ının dışında yüklenmiş, yayımlanmış @openai/codex-security paketi.
Git'in merge base'i hesaplayabilmesi için pull request veya merge request'in head ve base geçmişi.

GitHub Actions iş akışını ekleme

Özel veya kurum içi depolarda SARIF yüklemeden önce GitHub Code Security'yi etkinleştirin.

.github/workflows/codex-security.yml oluşturun. Pull request'i checkout etmeden önce güvenilir yürütülebilir dosyanın $RUNNER_TEMP/codex-security/node_modules/.bin/codex-security konumunda kullanılabilmesi için @openai/codex-security paketini $RUNNER_TEMP/codex-security altına yükleyin:

name: Codex Security scan

on:
  pull_request:

jobs:
  codex-security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: "26"

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
        with:
          python-version: "3.14"

      - name: Install Codex Security
        run: |
          set -euo pipefail
          npm install \
            --prefix "$RUNNER_TEMP/codex-security" \
            --ignore-scripts \
            --no-audit \
            --no-fund \
            @openai/codex-security

      - name: Verify Codex Security
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
        run: |
          set -euo pipefail
          test -x "$CODEX_SECURITY_BIN"
          "$CODEX_SECURITY_BIN" --version

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

      - name: Scan the pull request
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          CODEX_SECURITY_STATE_DIR: ${{ runner.temp }}/codex-security-state
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
        run: |
          set -euo pipefail
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
          "$CODEX_SECURITY_BIN" scan . \
            --diff "$BASE_REVISION" \
            --head "$HEAD_SHA" \
            --auth api-key \
            --output-dir "$SCAN_DIR" \
            --json > "$RUNNER_TEMP/codex-security.json"

      - name: Export SARIF
        id: export-sarif
        if: always()
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
          SARIF_FILE: ${{ runner.temp }}/codex-security.sarif
        run: |
          set -euo pipefail
          if test -f "$SCAN_DIR/scan-manifest.json"; then
            "$CODEX_SECURITY_BIN" export "$SCAN_DIR" \
              --export-format sarif \
              --source-root "$GITHUB_WORKSPACE" \
              --output "$SARIF_FILE"
            echo "available=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload SARIF
        if: always() && steps.export-sarif.outputs.available == 'true'
        uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
        with:
          sarif_file: ${{ runner.temp }}/codex-security.sarif
          ref: refs/pull/${{ github.event.pull_request.number }}/head
          sha: ${{ github.event.pull_request.head.sha }}
          category: codex-security

      - name: Preserve scan results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: codex-security-results
          path: |
            ${{ runner.temp }}/codex-security-results
            ${{ runner.temp }}/codex-security.json
          if-no-files-found: warn
          retention-days: 7

İş akışı pull request'in head'ini checkout eder, merge base'ini hesaplar ve bu revizyonlar arasındaki commit edilmiş değişiklikleri tarar. Tam geçmiş, hedefin kesin olmasını sağlar. persist-credentials: false, depo token'ını checkout edilmiş Git yapılandırmasının dışında tutar. CLI'ın checkout'tan önce yüklenmesi ve mutlak yoluyla çalıştırılması, depo tarafından denetlenen yürütülebilir dosyaları tarama kimlik bilgisinden uzak tutar. --auth api-key, kapsamı sınırlandırılmış API key'i açıkça seçer. Tarama, geçmişini deponun dışındaki yazılabilir bir durum dizinine kaydeder.

--json stdout'a tek ve eksiksiz bir JSON belgesi yazar; böylece iş akışı bunu doğrudan kaydedebilir. İlerleme, tamamlanma özetleri ve hatalar stderr'de kalır. Bu davranış, JSON Lines olay akışı yayan codex exec --json davranışından farklıdır.

Dışa aktarma adımı tamamlanmış ve mühürlenmiş bir taramayı okur ve SARIF yazar. Codex çalışma zamanına ve kimlik bilgilerine dokunmaz. Tarama yapıtları güvenlik açığı içeren kaynak parçacıkları, kanıtlar ve düzeltme ayrıntıları içerebilir. Deponuza uygun erişim denetimleri ve kısa bir saklama süresi seçin.

GitLab CI/CD işlem hattını ekleme

GitLab Ultimate 19.2 veya üzeri sürümlerde GitLab, SARIF 2.1.0 raporlarını alabilir. İşlem hattını çalıştırmadan önce maskelenmiş ve gizlenmiş bir CODEX_SECURITY_API_KEY CI/CD değişkeni ekleyin.

Kök .gitlab-ci.yml dosyasına security aşamasını ve Codex Security işini ekleyin. Dosyadaki mevcut aşamaları ve işleri koruyun. Örnek, varsayılan olarak merge request değişikliklerini tarar. Varsayılan dalın tamamını da taramak için CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH değerini "true" olarak ayarlayın:

variables:
  CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH: "false"

stages:
  - test
  - security

codex-security:
  stage: security
  image: node:26-bookworm-slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID'
      variables:
        CODEX_SECURITY_SCAN_SCOPE: "diff"
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH == "true"'
      variables:
        CODEX_SECURITY_SCAN_SCOPE: "full"
  variables:
    GIT_DEPTH: "0"
    CODEX_SECURITY_CLI_DIR: "/tmp/codex-security-cli"
  before_script:
    - |
      set -eu
      apt-get update -qq
      apt-get install -y -qq --no-install-recommends \
        ca-certificates \
        git \
        python3 \
        ripgrep
      npm install \
        --prefix "$CODEX_SECURITY_CLI_DIR" \
        --ignore-scripts \
        --no-audit \
        --no-fund \
        @openai/codex-security
      export CODEX_SECURITY_BIN="$CODEX_SECURITY_CLI_DIR/node_modules/.bin/codex-security"
      test -x "$CODEX_SECURITY_BIN"
      "$CODEX_SECURITY_BIN" --version
  script:
    - |
      set -eu
      if test -z "${CODEX_SECURITY_API_KEY:-}"; then
        echo "Set the CODEX_SECURITY_API_KEY CI/CD variable." >&2
        exit 2
      fi

      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY

      case "${CODEX_SECURITY_SCAN_SCOPE:-}" in
        diff)
          BASE_SHA="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
          HEAD_SHA="$CI_COMMIT_SHA"
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
          set -- --diff "$BASE_REVISION" --head "$HEAD_SHA"
          echo "Scanning committed changes from $BASE_REVISION to $HEAD_SHA."
          ;;
        full)
          set -- --mode standard
          echo "Scanning the complete default branch at $CI_COMMIT_SHA."
          ;;
        *)
          echo "Unsupported Codex Security scan scope: ${CODEX_SECURITY_SCAN_SCOPE:-unset}" >&2
          exit 2
          ;;
      esac

      export CODEX_SECURITY_STATE_DIR="/tmp/codex-security-state-$CI_JOB_ID"
      SCAN_DIR="/tmp/codex-security-results-$CI_JOB_ID"
      JSON_FILE="/tmp/codex-security-$CI_JOB_ID.json"
      SARIF_FILE="/tmp/codex-security-$CI_JOB_ID.sarif"

      install -d -m 700 "$CODEX_SECURITY_STATE_DIR" "$SCAN_DIR"

      set +e
      OPENAI_API_KEY="$codex_security_api_key" \
        "$CODEX_SECURITY_BIN" scan . \
          "$@" \
          --auth api-key \
          --output-dir "$SCAN_DIR" \
          --json > "$JSON_FILE"
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      install -d -m 700 codex-security-artifacts/results
      cp -R "$SCAN_DIR"/. codex-security-artifacts/results/
      if test -s "$JSON_FILE"; then
        cp "$JSON_FILE" codex-security-artifacts/codex-security.json
      fi
      printf '%s\n' "$scan_exit" > codex-security-artifacts/scan-exit-code.txt

      export_exit=0
      if test -f "$SCAN_DIR/scan-manifest.json"; then
        set +e
        "$CODEX_SECURITY_BIN" export "$SCAN_DIR" \
          --export-format sarif \
          --source-root "$CI_PROJECT_DIR" \
          --output "$SARIF_FILE"
        export_exit="$?"
        set -e
        if test -s "$SARIF_FILE"; then
          cp "$SARIF_FILE" codex-security-artifacts/codex-security.sarif
        fi
      fi

      if test "$scan_exit" -ne 0; then
        exit "$scan_exit"
      fi
      exit "$export_exit"
  artifacts:
    when: always
    access: maintainer
    expire_in: 7 days
    paths:
      - codex-security-artifacts/
    reports:
      sarif: codex-security-artifacts/codex-security.sarif

İş varsayılan olarak yalnızca aynı projedeki dallardan gelen merge request'ler için çalışır; böylece fork işlem hatları tarama kimlik bilgisini almaz. Varsayılan dalda standart bir tam tarama da çalıştırmak için grup, proje veya işlem hattı düzeyinde CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH değerini "true" olarak ayarlayın. Tam taramalar, fark taramalarından daha uzun sürer ve daha maliyetlidir.

GIT_DEPTH: "0", merge request taramalarında CI_MERGE_REQUEST_DIFF_BASE_SHA ile CI_COMMIT_SHA üzerinden merge base'i hesaplamak için gereken geçmişi sağlar.

İş, CLI'ı /tmp altına yükler, mutlak yoluyla çalıştırır ve API key'i yalnızca tarama işlemine açar. artifacts: when: always tarama başarısız olduğunda SARIF raporunu korurken artifacts:access: maintainer ayrıntılı tarama sonuçlarına erişimi sınırlar.

.gitlab-ci.yml değişiklikleri CI/CD değişkenlerini açığa çıkarabilir; bu nedenle işi çalıştırmadan önce işlem hattı değişikliklerini inceleyin. CODEX_SECURITY_API_KEY değerini korumaya alırsanız, GitLab bunu yalnızca korumalı dallar arasındaki aynı proje merge request'lerinde ve kullanıcı hedef dala erişebildiğinde kullanılabilir kılar.

Önem derecesi politikası seçme

Her iki örnek de --fail-on-severity içermediğinden yalnızca raporlama yapar. Bulguların denetimi etkilemesine hazır olduğunuzda tarama komutuna bir eşik ekleyin:

"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --fail-on-severity high

Desteklenen eşikler critical, high, medium ve low değerleridir. Eşik, o önem derecesindeki ve üzerindeki bulguları kapsar.

Tarama adımı şu çıkış kodlarını kullanır:

Çıkış	Anlamı
`0`	Tarama eksiksiz kapsamla tamamlandı ve yapılandırılmış tüm politikalar geçti.
`1`	Tamamlanan tarama, eşik veya üzeri önem derecesinde bir bulgu içeriyor.
`2`	CLI bir girdi ya da çalışma zamanı hatası buldu veya tamamlanan taramanın kapsamı eksik.
`130`	Ctrl-C taramayı yarıda kesti.
`143`	SIGTERM taramayı sonlandırdı.

partial veya unknown kapsamlı bir tarama, önem derecesi politikası olmasa bile 2 döndürür. CLI yine de mevcut bulgularını ve kapsamı yazar. Denetimi kesin sonuç olarak kabul etmeden önce coverage.json içindeki ertelenmiş alanları inceleyin.

Mevcut sonuç diziniyle yeniden deneme

Her CI işi için yeni bir çalıştırıcı dizini kullanın. Kalıcı veya kendi barındırdığınız bir çalıştırıcıda önceki bir sonucu korumak için --archive-existing kullanın:

"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --archive-existing

Komut önceki sonuçları arşivler ve boş bir tarama diziniyle başlar.

CI taramasında sorun giderme

Bilinmeyen Git ref'i veya beklenmeyen fark: Base ve head geçmişini fetch edin, merge base'i hesaplayın ve iki revizyonu da açıkça iletin.
Korumalı veya boş olmayan çıktı dizini: Kapsayan Git worktree'nin dışında özel bir dizin seçin. Dizin zaten sonuç içeriyorsa --archive-existing kullanın.
Eksik kimlik bilgileri: CODEX_SECURITY_API_KEY değerinin güvenilir iş akışı veya işlem hattı tarafından kullanılabildiğini ve doğrudan tarama işleminin OPENAI_API_KEY ortam değişkenine eşlendiğini doğrulayın.
Tarama geçmişi hatası: CODEX_SECURITY_STATE_DIR değerini deponun dışındaki yazılabilir bir dizine ayarlayın.
Python kurulum hatası: Çalıştırıcının Python 3.10 veya üzerini kullandığını doğrulayın.
Eksik kapsam: Ertelenmiş yüzeyler ve açık sorular dâhil coverage.json değerini inceleyin, ardından uygun bir hedef veya ortamla yeniden çalıştırın.
SARIF dışa aktarma hatası: Taramanın tamamlandığını ve tam tarama dizininin kullanılabilir olduğunu doğrulayın. Dışa aktarma işlemi SARIF yazmadan önce mühürlenmiş yapıtları doğrular.
SARIF yükleme hatası: GitHub Actions için kuruluşunuzun depoda GitHub Code Security'yi etkinleştirdiğini ve iş akışının actions: read, contents: read ve security-events: write izinlerini verdiğini doğrulayın. GitLab CI/CD için projenin GitLab Ultimate 19.2 veya üzerini kullandığını ve işin artifacts:reports:sarif üzerinden bir SARIF 2.1.0 dosyası yüklediğini doğrulayın.

Her komut, bayrak, yapıt ve çıktı alanı için CLI referansına bakın. Etkileşimli, eklenti tabanlı CI incelemesi için Kod değişikliklerini güvenlik açısından inceleme sayfasına bakın.

Son aramalar

Önerilen aramalar

Belge gezintisi

Codex Security'yi CI'da çalıştırma

İş akışını hazırlama

GitHub Actions iş akışını ekleme

GitLab CI/CD işlem hattını ekleme

Önem derecesi politikası seçme

Mevcut sonuç diziniyle yeniden deneme

CI taramasında sorun giderme