SARIF dışa aktarımı ve GitHub code scanning entegrasyonu

Tamamlanmış bir vetkit denetimini rapor endpoint’i üzerinden format=sarif ile dışa aktarın, ardından SARIF 2.1.0 dosyasını GitHub Actions iş akışınızdan yükleyin. Yüklemeden önce denetimi analiz edilen depo ve commit’le eşleştirin. Raporu indirmek tek başına GitHub’da uyarı yayımlamaz; yükleme, sizin yapılandırdığınız ayrı bir adımdır.

1. Ön koşulları kontrol edin

• Kuruluş kimliğini, denetim kimliğini ve reports:read kapsamına sahip bir vetkit API anahtarını hazır bulundurun. Denetimleri başlatan ve durumlarını sorgulayan otomatik bir iş akışı ayrıca audits:write ve audits:read kapsamlarına ihtiyaç duyar.
• Denetimin deposunu ve commit SHA’sını doğrulayın. CI için iş akışının tam olarak aynı commit’i için bir denetim isteyin ya da mevcut olanı yeniden kullanın ve dışa aktarmadan önce tamamlanmasını bekleyin.
• JSON raporunda kısmi sonuçları ve gerçek tarama kapsamını inceleyin. Geçerli bir SARIF belgesi yine de eksik bir analizi temsil ediyor olabilir.

GitHub, code scanning’i herkese açık depolar ve GitHub Code Security etkinleştirilmiş uygun kuruluş depoları için destekler. Deponuzun uygunluğunu ve yazma erişimini GitHub’ın SARIF yükleme dokümantasyonunda kontrol edin.

2. Denetimi dışa aktarın

Aşağıdaki değişkenleri yerel shell’inizde ya da CI ortamınızda tanımlayın. VETKIT_API_URL, /v1 olmadan vetkit API origin’inizdir. Anahtarı iş akışı dosyasında, depoda ya da bir shell script’inde değil, bir secret manager’da veya CI secret’ında saklayın. Bu komut curl ve jq gerektirir:

$ set -euo pipefail$ : "${VETKIT_API_URL:?Set the API origin}"$ : "${VETKIT_ORG_ID:?Set the organization ID}"$ : "${VETKIT_AUDIT_ID:?Set the completed audit ID}"$ : "${VETKIT_API_KEY:?Set a reports:read key}" $ curl --fail-with-body --silent --show-error --max-time 30 \  "$VETKIT_API_URL/v1/orgs/$VETKIT_ORG_ID/audits/$VETKIT_AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif$ jq -e '.version == "2.1.0" and (.runs | type == "array")' vetkit.sarif >/dev/null

Endpoint application/sarif+json ve denetlenen commit’e dayalı bir ek dosya adı döndürür. Komut, yükleme adımı için dosyayı bilinçli olarak vetkit.sarif adıyla kaydeder. jq kontrolü temel bir biçim kontrolüdür; tam bir şema doğrulaması ya da taramanın eksiksiz olduğunun teyidi değildir. İndirilen raporu depo bilgisi olarak ele alın ve ona erişimi kontrol altında tutun.

3. İş akışınızdan yükleyin

Taranan deponun bir iş akışında, eşleşen kaynağı checkout edin, tamamlanmış denetimi alın ve yukarıdaki indirme komutunu çalıştırın. VETKIT_API_KEY değerini bir Actions secret’ında tutun. Aşağıdaki parça izinleri ve son yükleme adımını gösterir; tek başına bir tarama iş akışı değildir. İndirme adımını checkout ile yükleme arasına ekleyin:

permissions:  contents: read  actions: read  security-events: write # Inside the job's steps, after choosing the matching audit:steps:  - uses: actions/checkout@v6    with:      persist-credentials: false  # Insert the authenticated download step here.  - name: Upload vetkit results    uses: github/codeql-action/upload-sarif@v4    with:      sarif_file: vetkit.sarif      category: vetkit

GitHub’ın yükleme action’ı rapor yolu için sarif_file, analizleri birbirinden ayırmak için category kullanır. Aynı commit için bir araç/kategori çiftini yeniden kullanmak önceki sonuçların yerine geçebilir; ayrı analizler için farklı kategoriler kullanın. Yukarıdaki izinler ve action sürümleri GitHub’ın örneğini izler.

vetkit’in depo entegrasyonu örneği, SARIF yüklemesini VETKIT_UPLOAD_SARIF=true ayarının arkasında isteğe bağlı tutar. Tam tarama iş akışı tam olarak aynı commit için bir denetim ister ve isteğe bağlı yüklemeden önce başarısız, kısmi ya da puanlanmamış sonuçları reddeder. Bu tamamlanma kontrolü bir bulgu önem derecesi ya da puan eşiği uygulamaz: yayın politikanızı ayrıca tanımlayın. GitHub App kontrolleri ve SARIF yüklemesi ayrı entegrasyon yollarıdır.

4. İçe aktarılan sonuçları yorumlayın

vetkit, sürücüsü vetkit olan tek bir SARIF run’ı dışa aktarır. Sonuçlar kural kimliklerini, mevcut olduğunda dosya konumlarını, düzeltme metnini ve vetkit parmak izlerini içerir. Analizör sürümleri extension olarak kaydedilir ve depo/commit kökeni de dahil edilir. Önem derecesi eşlemesi, vetkit’in önem derecesi özelliklerinin yanında SARIF düzeylerini kullanır; bu sayısal eşlemeler bağımsız olarak hesaplanmış CVSS puanları değildir.

Depo düzeyindeki bulgular yapay bir (repository) konumu kullanır; bu yüzden gerçek bir kaynak satırına işaret etmeyebilirler. Bastırılmış bulgular, SARIF suppression meta verileriyle birlikte dışa aktarımda kalır. Dışa aktarılan sonuç sayısının GitHub’ın gösterdiği aktif uyarı sayısına eşit olduğunu varsaymayın. Kapsam, puanlama bağlamı ve inceleme ayrıntıları için orijinal vetkit raporunu saklayın.

Sorun giderme

• İndirme başarısız oluyor: API origin’ini, kuruluş ve denetim kimliklerini, anahtarın geçerliliğini ve reports:read kapsamını kontrol edin. Hata ayıklarken anahtarı ekrana yazdırmayın.
• Kaynak konumları yanlış: denetimin commit’ini iş akışının commit’i ve checkout’uyla karşılaştırın. Daha eski bir raporu daha yeni bir revizyon için kanıt olarak yüklemeyin.
• Yükleme reddediliyor: GitHub uygunluğunu, iş akışı izinlerini ve yükleme action’ının hata çıktısını kontrol edin. GitHub, desteklediği SARIF özelliklerini ve boyut sınırlarını kendisi uygular.
• Görünür uyarı yok: dosyadaki sonuçları, suppression meta verilerini, seçilen analizi ve orijinal denetim kapsamını inceleyin. Aktarımın başarılı olması temiz bir taramanın kanıtı değildir.

Kaynaklar ve sınırlar

1 Kasım 2026’da vetkit’in rapor controller/service katmanına, SARIF serializer’ına ve depo GitHub Actions entegrasyonu örneğine karşı kontrol edilmiştir. Entegrasyonun iki tarafı için API referansına ve GitHub’ın yükleme gereksinimlerine bakın. GitHub uygunluk koşulları ve action davranışı değişebilir. SARIF dışa aktarımı mevcut bulguları aktarır; CodeQL çalıştırmaz, orijinal denetime kontrol eklemez ya da her vetkit rapor ayrıntısının GitHub arayüzünde görüneceğini garanti etmez.