Codex Security'yi GitLab CI/CD'de çalıştırma

Kaydedilmiş değişiklikleri ve korunan dalları taramak, bulguları GitLab Security'de yayımlamak ve isteğe bağlı olarak doğrulanmış düzeltmeleri taslak birleştirme isteklerinde önermek için Codex Security'yi GitLab CI/CD'de çalıştırın.

İş akışı, tarama kimlik bilgilerini depoya yazma erişiminden ayrı tutar. Oluşturulan değişiklikler birleştirilmeden önce her zaman insan incelemesi gerektirir.

Yalnızca taramaya dayalı raporlamayla başlayın. Düzeltmeyi ancak projenizin çalıştırıcısını, bulgularını ve kimlik bilgisi sınırlarını denetledikten sonra etkinleştirin.

Başlamadan önce

Şunlara ihtiyacınız vardır:

• Codex korumalı alanının kullanıcı ad alanını destekleyen, güvenilir bir çalıştırıcıya sahip GitLab projesi.
• Proje CI/CD değişkenlerini ve korunan kaynakları yapılandırabilmeniz için GitLab projesinde Maintainer veya Owner rolü.
• Codex Security erişimine sahip bir OpenAI API key. Platform API key kullanan kuruluşlar Cyber için Trusted Access talep edebilir. ChatGPT kimlik doğrulaması kullanan kişiler kişisel Trusted Access akışını kullanabilir. Bazı hesaplar veya depolar, deponun tamamının taranması için bu erişimi gerektirir.
• SARIF 2.1.0 veri alımı için GitLab Ultimate 19.2 veya sonraki bir sürüm.
• Birleştirme isteği işlerinin birleştirme tabanını hesaplayabilmesi için eksiksiz Git geçmişi.

İşlem hattı görüntüsü Node.js 26, Python 3, Git, rg ve sabitlenmiş Codex Security CLI'yi yükler. Otomatik düzeltme ayrıca mevcut bir regresyon testi ve korunan kimlik bilgileri olmadan depo tarafından denetlenen komutları çalıştırabilen bir çalıştırıcı gerektirir.

Yalnızca tarama yapan bir işlem hattıyla başlayın

CODEX_SECURITY_API_KEY adlı maskelenmiş, gizli ve korunan bir GitLab CI/CD değişkeni oluşturun. Codex Security erişimine sahip bir OpenAI Platform API key kullanın ve ortam kapsamını codex-security/openai olarak ayarlayın. Ortam kapsamlı CI/CD değişkenleri bölümüne bakın.

Bu asgari işlem hattını önce bir test projesine ekleyin. Uygun korunan birleştirme isteklerindeki kaydedilmiş değişiklikleri tarar, başarılı bir rapor işinden SARIF yayımlar ve tarayıcı sonucunu ayrı bir eşikte geri yükler:

stages:
  - security_scan
  - security_gate

.codex-security-merge-request:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID && $CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED == "true" && $CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED == "true"'

codex-security:
  extends: .codex-security-merge-request
  stage: security_scan
  image: node:26-bookworm-slim
  environment:
    name: codex-security/openai
    action: access
  variables:
    GIT_DEPTH: "0"
  before_script:
    - npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.1.20
  script:
    - |
      set -eu
      test -n "${CODEX_SECURITY_API_KEY:-}"

      CODEX_SECURITY_BIN="/tmp/codex-security-cli/node_modules/.bin/codex-security"
      RESULTS_DIR="/tmp/codex-security-results-$CI_JOB_ID"
      ARTIFACT_DIR="codex-security-artifacts"
      BASE_REVISION="$(git merge-base \
        "$CI_MERGE_REQUEST_DIFF_BASE_SHA" "$CI_COMMIT_SHA")"
      install -d -m 700 "$RESULTS_DIR" "$ARTIFACT_DIR/results"

      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY
      set +e
      OPENAI_API_KEY="$codex_security_api_key" \
        "$CODEX_SECURITY_BIN" scan . \
          --diff "$BASE_REVISION" \
          --head "$CI_COMMIT_SHA" \
          --auth api-key \
          --output-dir "$RESULTS_DIR" \
          --json
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      case "$scan_exit" in
        0|1|2) ;;
        *) exit "$scan_exit" ;;
      esac

      "$CODEX_SECURITY_BIN" export "$RESULTS_DIR" \
        --export-format sarif \
        --source-root "$CI_PROJECT_DIR" \
        --output "$ARTIFACT_DIR/results.sarif"
      test -s "$ARTIFACT_DIR/results.sarif"
      cp -R "$RESULTS_DIR"/. "$ARTIFACT_DIR/results/"
      printf '%s\n' "$scan_exit" > "$ARTIFACT_DIR/scan-exit-code.txt"
      exit 0
  artifacts:
    when: always
    access: maintainer
    expire_in: 7 days
    paths:
      - codex-security-artifacts/
    reports:
      sarif: codex-security-artifacts/results.sarif

codex-security-gate:
  extends: .codex-security-merge-request
  stage: security_gate
  image: alpine:3.20
  needs:
    - job: codex-security
      artifacts: true
  script:
    - exit "$(cat codex-security-artifacts/scan-exit-code.txt)"

Gizli bilgi içeren bir işi çalıştırmadan önce .gitlab-ci.yml dosyasındaki her değişikliği inceleyin. Asgari örnek, tam taramaları ve düzeltmeyi kasıtlı olarak içermez.

Üretim işlem hattını benimseyin

1. Eksiksiz GitLab işlem hattını indirin ve depo köküne .gitlab-ci.yml adıyla kaydedin. Deponuzda zaten bir işlem hattı varsa örnekteki aşamaları, gizli şablonları ve işleri mevcut dosyayla birleştirin.
2. Mevcut derleme, test ve dağıtım aşamalarını koruyun. Proje workflow: rules kullanıyorsa taramak istediğiniz işlem hattı olaylarına izin verdiğini doğrulayın.

Örnek; security_scan, security_remediation, security_publish ve security_gate aşamalarını ekler. Yalnızca taramaya dayalı raporlama için sadece CODEX_SECURITY_API_KEY gerekir.

Tarama işi varsayılan olarak yalnızca aynı projedeki korunan dallar arasında açılan birleştirme istekleri için çalışır. Korunan varsayılan dal gönderimlerini ve manuel işlem hatlarını taramak için CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true değerini ayarlayın. Korunan varsayılan dalda zamanlanmış derin taramaları etkinleştirmek için CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true değerini ayarlayın ve açık zaman ve maliyet bütçeleri yapılandırın.

Bir birleştirme isteği işlem hattı, korunan değişkenlere ve çalıştırıcılara yalnızca şu durumlarda erişebilir:

• Kaynak ve hedef dalları aynı projede korumaya alırsınız.
• Proje, birleştirme isteği işlem hatlarının korunan değişkenlere ve çalıştırıcılara erişmesine izin verir.
• İşlem hattını başlatan kullanıcı hedef dala gönderim yapabilir veya birleştirebilir.

Çatallanmış depo işlem hatları ve korumasız birleştirme istekleri tarama kimlik bilgisini almaz. Gizli bilgi içeren bir işi çalıştırmadan önce .gitlab-ci.yml dosyasındaki her değişikliği inceleyin. Bir değişkeni maskelemek ve gizlemek, güvenilmeyen CI kodunu güvenli hâle getirmez.

Tarama çalıştırın ve bulguları inceleyin

Uygun bir korunan birleştirme isteği oluşturun veya işlem hattını korunan varsayılan dalda çalıştırın. Ücretli bir tam depo taraması çalıştırmadan önce küçük bir farkla başlayın.

codex-security işini açın ve yapıtlarının şunları içerdiğini doğrulayın:

• scan-manifest.json
• findings.json
• coverage.json
• results.sarif
• scan-exit-code.txt

Ardından işlem hattındaki Security sekmesini açın, veri alımı uyarılarını inceleyin ve bulgu tanımlayıcılarını, önem derecelerini ve kaynak konumlarını doğrulayın. Varsayılan dal taramaları ayrıca proje güvenlik açığı kayıtları oluşturur. Birleştirme isteği bulguları işlem hattındaki Security sekmesinde veya birleştirme isteği güvenlik aracında görünür ancak proje genelinde güvenlik açığı kayıtları oluşturmaz.

Tarama sonuçları güvenlik açığı bulunan kaynak parçacıkları, kanıtlar ve düzeltme ayrıntıları içerebileceğinden yapıt erişimini kısıtlayın.

Tarama profili seçin

İşlem hattı, tetikleyiciye göre bir profil seçer:

Birleştirme isteği taramaları, geri bildirimi kaydedilmiş değişikliğe odaklar. Varsayılan dal taramaları tümleşik depoyu inceler. Zamanlanmış derin taramalar daha geniş ve dönemsel kapsam sağlar. Tamamlanan bir fark taraması yalnızca o değişiklik için geçerlidir ve deponun tamamının temiz olduğunu göstermez.

İş akışı, CLI'yi deponun dışına yükler ve mutlak yoluyla çalıştırır. Kuru çalıştırma ön kontrolü, işlem kapsamlı API key'i kullanır ancak ücretli bir tarama başlatmaz; API kimlik doğrulamasını, Codex Security erişimini, kotayı veya model kullanılabilirliğini doğrulamaz.

İş akışı, tarama durumunu ve sonuçlarını çalışma ağacının dışına yazar ve OPENAI_API_KEY kapsamını tarama işlemiyle sınırlar. CLI, tüm GitLab değişkenlerini devralmak yerine küçük ve açıkça tanımlanmış bir ortam alır. İş akışı, fark taramalarında birleştirme tabanını hesaplar ve taramayı incelenen taban ve baş revizyonlarına bağlar.

Örnek, @openai/codex-security öğesini 0.1.20 değerine sabitler. Sabitlemeyi değiştirmeden önce kimlik doğrulamayı, yapıtları, SARIF veri alımını ve politika eşik denetimini yeniden test edin.

Raporlamayı politika uygulamasından ayırın

GitLab, SARIF'i başarılı bir rapor işinden alır. İşlem hattı önce raporu yayımlar, ardından tarayıcının çıkış durumunu ayrı bir codex-security-gate işinde geri yükler.

Rapor işi 0 ve 1 çıkış kodlarından gelen bulguları kabul eder. 2 çıkış kodunu yalnızca tarama bildirimi taramanın tamamlandığını kanıtlarsa, kapsam açıkça partial ise ve boş olmayan bir SARIF raporu mevcutsa kabul eder. Diğer çalışma zamanı, yapılandırma veya dışa aktarma hataları engelleyici olmaya devam eder.

Son eşik şu tarayıcı çıkış kodlarını korur:

Örnek, kısmi kapsamı ayarlarken 2 çıkışına geçici olarak izin verir. Eksik kapsamın işlem hattını engellemesi gerektiğinde bu izni kaldırın.

Düzeltme ve yayımlama, son politika eşiğinden önce çalışır. Uygun bir bulgu, eşik daha sonra işlem hattını başarısız kılsa bile doğrulanmış bir taslak birleştirme isteği oluşturabilir.

Doğrulanmış düzeltmeyi etkinleştirin

Otomatik düzeltme isteğe bağlıdır ve yalnızca korunan varsayılan dal işlem hatlarında çalışır. Codex düzeltme işlemi ve depo tarafından denetlenen doğrulama komutları, GitLab proje erişim belirtecini veya çalıştırıcı tarafından eklenen kimlik bilgilerini almaz.

Güvenlik sözleşmesinin üç bölümü vardır: depo tarafından denetlenen komutlar OpenAI veya GitLab kimlik bilgilerini hiçbir zaman almaz, yalnızca yayımlama işi depoya yazma erişimi alır ve oluşturulan her değişiklik bir insan tarafından incelenip birleştirilene kadar taslak olarak kalır.

İş akışı:

1. Eksiksiz tarama kapsamı ve high ya da critical önem derecesinde bir bulgu gerektirir.
2. Yapılandırılan regresyon testinin yama uygulanmadan önce başarısız olduğunu doğrular.
3. Odaklı bir yama oluşturur ve CI, kimlik bilgisi, ikili dosya veya diğer korunan dosyalardaki değişiklikleri reddeder.
4. Regresyon testini OpenAI, GitLab, kayıt defteri, dağıtım veya iş belirteci kimlik bilgileri olmadan çalıştırır.
5. fixed, still_vulnerable veya inconclusive döndürmek için verify-fix kullanır. İş yalnızca verify-fix, fixed döndürdüğünde ve doğrulama işlemi yamayı değiştirmeden bıraktığında yamayı yayımlar.

Düzeltmeyi etkinleştirmek için şu korunan değişkenleri ayarlayın:

• CODEX_SECURITY_ENABLE_REMEDIATION değerini true olarak ayarlayın.
• CODEX_SECURITY_VERIFICATION_COMMAND değerini, düzeltmeden önce 1 ve sonrasında 0 ile çıkan mevcut bir regresyon testine ayarlayın.
• İsteğe bağlı olarak CODEX_SECURITY_SETUP_COMMAND değerini etkileşimsiz bir bağımlılık kurulum komutuna ayarlayın.

Belirli bir uygulamayı değil, temel güvenlik değişmezini sınayan bir regresyon testi seçin. Oluşturulan test ve kaynak değişikliklerini de aynı titizlikle inceleyin.

Taslak birleştirme isteği yayımlayın

Developer rolü ve api ile write_repository kapsamlarına sahip bir GitLab proje erişim belirteci oluşturun. Bunu yalnızca codex-security/publish ortamıyla kapsamlandırılmış, korunan, maskelenmiş ve gizli bir GITLAB_REMEDIATION_TOKEN olarak saklayın.

Yayımlamayı etkinleştirmek için CODEX_SECURITY_CREATE_MR=true değerini ayarlayın. Ayrıca gizli olmayan CODEX_SECURITY_MR_TEST_COMMAND değerini, oluşturulan her düzeltme dalının geçmesi gereken projeye özgü güvenlik regresyon testine ayarlayın. Oluşturulan korumasız birleştirme isteğinin komutu okuyabilmesi için bu değişkeni korumasız tutun. Yayımlama iş akışı:

• Depoya yazma belirtecini alır ancak OpenAI kimlik bilgisi almaz.
• Bir codex-security/fix-<finding-hash> dalı oluşturur.
• Bir taslak birleştirme isteği açar ve yinelenen bir istek oluşturmak yerine mevcut açık taslağı yeniden kullanır.
• Korumasız düzeltme dalının regresyon testini, korunan kimlik bilgileri olmadan yalnızca izlenen dosyaları içeren bir kopyada ayrıcalıksız kullanıcı olarak çalıştırır.
• Oluşturulan değişikliği hiçbir zaman otomatik olarak birleştirmez.

Proje erişim belirteci yerine CI_JOB_TOKEN kullanmayın. Gerekli birleştirme isteği oluşturma işlemini gerçekleştiremez. Birleştirmeden önce önerilen yamayı, doğrulama kanıtını ve bulguyu inceleyin.

İsteğe bağlı değişkenleri yapılandırın

Yalnızca etkinleştirdiğiniz özellikler için gereken değişkenleri yapılandırın:

GitLab, CI_* değişkenlerini sağlar. İşlem hattı CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR ve CODEX_SECURITY_TARGET öğelerini yönetir; bunları proje değişkenleri olarak yapılandırmayın. Fark taramalarında CLI, kurallı hedef kimliğini normalleştirilmiş taban ve baş revizyonlarından türetir.

Uygulamayı ve maliyeti ayarlayın

Birleştirme isteği geri bildirimi için odaklı fark taramaları, varsayılan dal için standart depo taramaları ve daha geniş kapsam için zamanlanmış derin taramalar kullanın. Her iki tam depo profili de varsayılan olarak kapalıdır. Zamanlanmış bir derin tarama ayrıca CODEX_SECURITY_DEEP_MAX_TIME_HOURS ve CODEX_SECURITY_DEEP_MAX_COST gerektirir; CLI zaman bütçesini işin sekiz saatlik zaman aşımı süresinin altında tutun. Bütçe belirlemeden önce temsili çalıştırmaları ölçün. --max-cost değerini kesin bir faturalandırma üst sınırı değil, tahmini bir maliyet sınırı olarak değerlendirin.

Yalnızca rapor üreten taramalarla başlayın. Ekibiniz temsili bulguları, kapsamı, maliyeti ve çalışma süresini inceledikten sonra --fail-on-severity ekleyin. Önem derecesi politikaları ve çıkış kodu ayrıntıları için Codex Security'yi CI'da çalıştırma bölümüne bakın.

Bir iş başarısız olduğunda:

• Eksik tarama yapıtları bir yapılandırma veya çalıştırıcı sorununa işaret eder.
• Kısmi kapsamlı mevcut yapıtlar, coverage.json öğesinin incelenmesini gerektirir.
• Eksik GitLab bulguları, SARIF raporu işinin başarılı olup olmadığının ve GitLab'ın raporu kabul edip etmediğinin denetlenmesini gerektirir.
• Atlanan düzeltme için korunan dalı, eksiksiz kapsamı, bulgu önem derecesini, doğrulama komutunu ve etkinleştirme değişkenlerini denetlemek gerekir.
• Yayımlama hataları için proje belirtecinin rolünü, kapsamlarını ve ortam kısıtlamasını denetlemek gerekir.

Her komut, bayrak ve yapıt için Codex Security CLI referansına bakın.