Codex Security'yi GitHub Actions'ta çalıştırın

Çekme isteği değişikliklerini incelemek veya deponuzu belirli bir zamanlamayla taramak için Codex Security'yi GitHub Actions'ta çalıştırın. Action, CLI aracını yükler, yapılandırılmış raporları kaydeder ve bir iş özeti ile kaynak kodu açıklamaları ekler. Bilgilendirme amaçlı sonuçlarla başlayın, ardından kapsamı ve tarama kalitesini inceleyerek kuralların uygulanmasını yapılandırın.

İş akışını hazırlayın

Tarama çalıştırmak için Codex Security erişimi gerekir. OpenAI API key değerinizi eklemek için:

GitHub deponuzda Settings → Secrets and variables → Actions bölümünü açın.
New repository secret seçeneğini seçin.
Ad olarak CODEX_SECURITY_API_KEY girin ve değer olarak OpenAI API key değerinizi yapıştırın. Gizli bilgiyi kaydedin.

Aşağıdaki iş akışı örnekleri bu gizli bilgiyi Codex Security Action'a otomatik olarak iletir. API key değerinizi iş akışı dosyasına koymanız gerekmez.

İş akışını yalnızca güvendiğiniz depolar ve çekme istekleri için çalıştırın. Taramalar, çalıştırıcının yerel izinlerini kullanır ve onay için duraklamaz. İlgisiz kimlik bilgilerini ve dağıtım adımlarını ayrı işlerde tutun.

GitHub Actions iş akışını ekleyin

Depoyu belirli bir zamanlamayla tarayın

Aşağıdaki iş akışı, varsayılan dalınızı her pazartesi 07:23 UTC'de tarar. İş akışını GitHub'ın Actions sekmesinden elle de çalıştırabilirsiniz. GitHub tarafından barındırılan bir x64 Ubuntu 24.04 çalıştırıcısı kullanır ve gerekli korumalı alanı otomatik olarak kurar.

Deponuzda Add file → Create new file seçeneğini seçin.
Dosyayı .github/workflows/codex-security-repository.yml olarak adlandırın.
Aşağıdaki iş akışını yapıştırın ve varsayılan dalınıza commit edin.

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 }}

Çalıştırıcıyı uyarlama: Action, bu çalıştırıcının sağladığı Node.js 24 ve Python 3.11 veya üzerini gerektirir. Korumalı alan kurulumu, bubblewrap paketini yükler ve taramadan önce sağlanan AppArmor profilini etkinleştirir. Bu çalıştırıcıda yalnızca paketi yüklemek yeterli değildir.

İş akışını elle çalıştırmak için Actions → Codex Security repository → Run workflow yolunu açın. Özeti, açıklamaları ve indirilebilir raporları incelemek için tamamlanmış bir çalıştırmayı açın.

fail-on-severity değeri none olduğundan bulgular yalnızca raporlanır. Tarama aracı ve zorunlu raporlama hataları yine de işi başarısız kılar.

Seçili klasörleri taramak için tarama adımının with bloğuna her satırda bir sabit yol ekleyin:

paths: |
  src/api
  src/auth

Yollar scope: repository gerektirir ve glob kalıplarını genişletmez. Fark taramaları için paths girdisini belirtmeyin. persist-credentials: false ayarını koruyun ve taramayı checkout işleminden hemen sonra çalıştırın.

Çekme isteği değişikliklerini tarayın

Aynı gizli bilgiyi kullanarak .github/workflows/codex-security-pr.yml dosyasını oluşturun:

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 }}

Aynı depodaki bir daldan PR açın veya mevcut bir PR'ı güncelleyin. Action, kesin ortak birleştirme atasını bulmak için tüm geçmişi kullanır ve checkout yapılan PR uç commit'ine kadar olan değişiklikleri tarar. PR'daki Checks altında Codex Security denetimini görüntüleyin. Bilgilendirme amaçlı bulgularla başlayın, ardından değişiklikleri koşullara bağlamaya hazır olduğunuzda bir önem derecesi politikası seçin.

Bu örnek, çatallardan gelen PR'ları ve dependabot[bot] tarafından açılan PR'ları atlar. Atlanan bir iş, güvenlik incelemesi yapıldığının kanıtı değildir. Bu bot PR'larını dahil etmek için aktör dışlama koşulunu kaldırın ve ayrıca CODEX_SECURITY_API_KEY değerini dependabot[bot] için gizli bilgi olarak yapılandırın. Action, pull_request_target veya workflow_run desteği sunmaz.

Tarama aracı, PR'daki politika değişiklikleri dahil olmak üzere checkout yapılan kopyadaki geçerli SECURITY.md yönergelerini okur. Bu değişiklikleri kodla birlikte inceleyin.

İsteğe bağlı Daybreak erişimini yapılandırın

Daybreak isteğe bağlıdır. Her iki iş akışı örneği de gpt-6-sol kullanır. Kuruluşunuz Siber Güvenlik için Güvenilir Erişim için onay aldıysa tarama adımının with bloğunda cyber-access-program öncesindeki # işaretini kaldırın:

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

Daybreak Blue'nun etkin olduğu ve gpt-6-sol erişimi bulunan bir projeden API key kullanın.

Program girdisi standard değerini de kabul eder. Daybreak erişiminiz yoksa API key değerinizin standart güvenlik önlemleri kapsamında erişebildiği bir model kullanın ve cyber-access-program girdisini belirtmeyin veya standard olarak ayarlayın. Model veya program seçmek erişim sağlamaz. Action'ın Daybreak erişim yönergelerine bakın.

Taramayı sonlandıran bir ret veya güvenlik engeli, fail-on-severity değeri none olduğunda da Action'ı başarısız kılar. Bu girdi, tarama aracı hatalarını değil, bulgu politikasını kontrol eder.

İsteğe bağlı tarama bütçesi belirleyin

Her iki iş akışı örneğinde de max-cost belirtilmediğinden tahmini maliyete göre durdurma eşiği yoktur. Eşik belirlemek için max-cost girdisiyle pozitif bir ABD doları tutarı ekleyin. Doğrudan CLI taramaları için --max-cost kullanın.

Maliyet sınırı, seçilen model için CLI fiyatlandırma desteği gerektirir. Tahmini eşik, kesin bir harcama sınırı değildir: hâlihazırda devam eden isteklerin maliyeti bu tutarı aşabilir. Tarama eşikte durursa bulguları ve coverage.json dosyasını inceleyin. Maliyet sınırının davranışı için çıktı ve politika seçenekleri bölümüne bakın.

Raporları kaydedin ve SARIF yükleyin

Örnekler, indirilebilir raporları yedi günlük saklama süresiyle kaydetmek için upload-artifacts: "true" ayarını kullanır. Raporlar kaynak kodu parçacıkları, güvenlik açığı kanıtları ve düzeltme ayrıntıları içerebilir. Kodunuza uygun bir saklama süresi ve depo erişimi seçin. Action yalnızca izin listesindeki doğrulanmış raporları yükler; results-directory çıktısını alt dizinleriyle birlikte yüklemeyin.

SARIF yüklemek isteğe bağlıdır. Özel veya kurum içi depolarda yüklemeden önce GitHub Code Security özelliğini etkinleştirin. İş akışının permissions bloğunu şununla değiştirin:

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

Ardından her iki iş akışından birinde taramadan sonra şu adımı ekleyin:

- 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 iş akışında, her kapsamın ayrı bir kategorisi olması için category: codex-security-pr kullanın. Tarama adımında id: security ayarını koruyun. Bulgular nedeniyle önem derecesi politikası başarısız olduğunda bile eksiksiz ve doğrulanmış raporlar yüklenebilir durumda kalır. Başarısız veya kesintiye uğramış taramalar, boş farklar ya da deneme çalıştırmaları için SARIF yüklenmez.

Tüm ayarlar, durum alanları ve rapor yolları için Action'ın girdi ve çıktı başvuru kılavuzuna bakın.

Bir önem derecesi politikası seçin

GitHub iş akışları fail-on-severity: none ile başlar. Tamamlanmış bir taramadaki yüksek veya kritik önem dereceli bulgularda başarısız olmak için tarama adımının girdisini değiştirin:

fail-on-severity: high

PR işi başarısız olduğunda birleştirmeleri engellemek için depo kurallarınızda Codex Security denetimini zorunlu durum denetimi yapın. GitHub, zorunlu denetimlerde bile koşullu olarak atlanan bir işi başarılı sayar. Çatallardan ve dependabot[bot] tarafından gelen PR'lar bu denetimi tarama yapılmadan geçer. Bu atlamaları engellemek için başarıyla tamamlanmış bir taramayı zorunlu kılın.

Action, CLI sonucunu izler:

0 çıkış kodu, scan-status: completed ve policy-status: passed ayarlarını yapar.
1 çıkış kodu, scan-status: completed ve policy-status: failed ayarlarını yapar; yapılandırılmış önem derecesindeki veya üzerindeki bulgular adımı başarısız kılar.
2 çıkış kodu veya kesintiye uğramış bir süreç, scan-status: failed ve policy-status: not-evaluated ayarlarını yapar; adım başarısız olur.
Geçersiz veya eksik zorunlu raporlar, checkout yapılan kopyanın değişmesi, istenen çıktı dosyalarının yüklenememesi ve çalışma ortamını temizleme hataları da adımı başarısız kılar.

Tamamlanmış bir tarama, yapılandırılan analizin geçerli bir sonuç ürettiği anlamına gelir. coverage.json dosyasındaki kapsam dışı bırakılan alanlar, ertelenmiş incelemeler ve diğer notlar ayrı bir tarama sonucu oluşturmaz veya önem derecesi politikasını devre dışı bırakmaz. Taramanın tamamlanması, her güvenlik açığının bulunduğunu doğrulamaz. Sonucu değerlendirirken coverage.json dosyasını inceleyin.

Başarıyla tamamlanmış bir taramayı zorunlu kılın

Daha katı bir politika için tarama işi başarısız olsa veya GitHub tarafından atlansa bile çalışan ayrı bir geçiş denetimi ekleyin. Tarama işinin içindeki bir adım, atlanan bir işi denetleyemez; çünkü o işin adımlarının hiçbiri çalışmaz.

PR iş akışında, mevcut security işine bu outputs eşlemesini, runs-on ve steps ile aynı girinti düzeyinde ekleyin:

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

Ardından jobs altına, mevcut security işinin yanına bu işi ekleyin:

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

Bu politika için Codex Security gate denetimini zorunlu durum denetimi yapın. Hem başarılı bir tarama işi hem de scan-status: completed gerektirir. Her ikisinin de denetlenmesi, taramanın kendisi tamamlanmış olsa bile önem derecesi politikasından, raporlamadan ve temizlemeden kaynaklanan hataların korunmasını sağlar.

Örnekteki dışlama koşullarıyla bu geçiş denetimi, çatallardan gelen PR'ları ve dependabot[bot] tarafından açılan PR'ları engeller. Action'ın skipped olarak işaretlediği boş farkları ve deneme çalıştırmalarını da engeller. Geçiş denetimi, dışlanan PR'ları taramaz. Bu politikayı yalnızca bu durumların birleştirmeyi engellemesi gerekiyorsa seçin.

Tarama sorunlarını giderin

Bilinmeyen Git referansı veya beklenmeyen fark: PR uç commit'ini fetch-depth: 0 ile checkout yapın.
Korumalı alan başlatma hatası: Ubuntu 24.04'te bubblewrap paketini yükleyin ve Action'dan önce AppArmor profilini etkinleştirin. Yalnızca paketi yüklemek gerekli profili etkinleştirmez.
Eksik kimlik bilgileri: CODEX_SECURITY_API_KEY değerinin güvenilir iş akışının kullanımına sunulduğunu ve tarama adımının OPENAI_API_KEY ortam değişkenine eşlendiğini doğrulayın.
Python kurulum hatası: Action, Python 3.11 veya üzerini gerektirir.
Kapsam notları: coverage.json dosyasında kapsam dışı bırakılan alanları ve ertelenmiş incelemeleri gözden geçirin. Bu notlar yürütme hatalarına neden olmaz veya önem derecesi politikasını devre dışı bırakmaz.
Eksik SARIF: scan-status, report-status ve sarif-upload-ready alanlarını inceleyin. İsteğe bağlı SARIF eksikse Action, tarama sonucunu değiştirmeden uyarı verir; istenen çıktı dosyalarının yüklenememesi yine de işi başarısız kılar.
SARIF yükleme hatası: Kuruluşunuzun depo için GitHub Code Security özelliğini etkinleştirdiğini ve iş akışının actions: read, contents: read ve security-events: write izinlerini verdiğini doğrulayın.

Tüm komutlar, bayraklar, çıktı dosyaları ve çıktı alanları için CLI başvuru kılavuzuna bakın. Diğer sağlayıcılar için CI/CD genel bakışına bakın.

Son aramalar

Önerilen aramalar

Belge gezintisi