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

Bir pull request veya merge request'teki değişiklikleri tam olarak incelemek, bulguları ve kapsamı saklamak 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 örneklerini 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şkeniyle 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.

İş akışını yalnızca güvendiğiniz depolar ve pull request'ler için çalıştırın. Taramalar, çalıştırıcının yerel izinlerini kullanır ve onay için duraklamaz. Tarama işlemleri iş ortamını devralabilir; bu nedenle ilgisiz belirteçleri ve bulut kimlik bilgilerini bu ortamın dışında tutun.

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

Node.js 22 (22.13.0 veya sonrası), 24 ya da 26.
Python 3.10 veya sonrası.
Depo çalışma kopyasının dışına 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 kullanıma almadan önce güvenilir yürütülebilir dosyanın $RUNNER_TEMP/codex-security/node_modules/.bin/codex-security konumunda bulunabilmesi 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 sürümünü kullanıma alır, merge base'ini hesaplar ve bu revizyonlar arasındaki kaydedilmiş değişiklikleri tarar. Tam geçmiş, hedefin kesin kalmasını sağlar. persist-credentials: false, depo belirtecini kullanıma alınmış Git yapılandırmasının dışında tutar. CLI'ı kullanıma alma işleminden önce yüklemek ve mutlak yoluyla çalıştırmak, depo denetimindeki 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 bir eksiksiz JSON belgesi yazar; böylece iş akışı bunu doğrudan kaydedebilir. İlerleme, tamamlanma özetleri ve hatalar stderr'de kalır. Bu davranış, bir JSON Lines olay akışı yayan codex exec --json komutundan 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çığı bulunan kaynak parçacıkları, kanıtlar ve düzeltme ayrıntıları içerebilir. Deponuza uygun erişim denetimlerini ve kısa bir saklama süresini tercih edin.

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

Korunan varsayılan dal taramalarını, isteğe bağlı zamanlanmış derin taramaları, ayrı SARIF politikası eşik denetimini ve isteğe bağlı doğrulanmış taslak birleştirme isteklerini içeren bir üretim iş akışı için Codex Security'yi GitLab CI/CD'de çalıştırma kılavuzunu kullanın.

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

Aşağıdaki asgari örnek, kök dizindeki .gitlab-ci.yml dosyasına yalnızca tarama yapan bir security işi ekler. Dosyadaki mevcut aşamaları ve işleri koruyun. Varsayılan olarak birleştirme isteği 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@0.1.20
      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 merge base'i CI_MERGE_REQUEST_DIFF_BASE_SHA ve CI_COMMIT_SHA üzerinden 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 üzerinde yapılan değişiklikler 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 bu değeri yalnızca korumalı dallar arasındaki aynı proje merge request'leri için ve yalnızca kullanıcı hedef dala erişebiliyorsa kullanılabilir kılar.

Özel GitLab kılavuzu, bu asgari işi bölümün başında bağlantısı verilen üretim iş akışına genişletir.

Önem derecesi politikası seçme

Her iki örnek de --fail-on-severity içermediği için 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. Bir eşik, mevcut taramadaki o önem derecesinde ve üzerindeki bulguları kapsar. Depo özetinde gösterilen daha eski açık bulgular politikayı etkilemez.

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

Çıkış	Anlamı
`0`	Tarama eksiksiz kapsamla tamamlandı ve yapılandırılmış tüm politikalar başarılı oldu.
`1`	Tamamlanan tarama, eşik düzeyinde veya üzerinde bir bulgu içeriyor.
`2`	CLI bir giriş ya da çalışma zamanı hatası buldu veya tamamlanan taramanın kapsamı eksik.
`130`	Ctrl-C taramayı kesintiye uğrattı.
`143`	SIGTERM taramayı sonlandırdı.

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

Mevcut bir 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 --archive-existing ile koruyun:

"$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 getirin, merge base'i hesaplayın ve iki revizyonu da açıkça iletin.
Korumalı veya boş olmayan çıktı dizini: Kapsayıcı Git çalışma ağacının 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şkeniyle 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 sonraki bir sürümü kullandığını doğrulayın.
Eksik kapsam: Ertelenmiş yüzeyler ve açık sorular dâhil olmak üzere 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 sonraki bir sürümü 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ı bir CI incelemesi için Kod değişikliklerini güvenlik açısından inceleme bölümüne 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 bir sonuç diziniyle yeniden deneme

CI taramasında sorun giderme