GitHub PR incelemeleri için Gemini CLI Security Extension'ı kullanma

1. Giriş

Gemini CLI Security Extension, Google tarafından geliştirilen ve kodu güvenlik riskleri ve güvenlik açıkları açısından analiz eden bir açık kaynaklı Gemini CLI uzantısıdır. Güvenlik sorunlarını yerel olarak belirlemek için diğer Gemini CLI uzantılarında olduğu gibi Gemini CLI ile Güvenlik uzantısını kullanabilirsiniz. GitHub'daki çekme isteklerini incelemek için de kullanabilirsiniz. Bu codelab'de, GitHub deponuzda güvenlik uzantısını nasıl kullanacağınızı ele alacağız.

Yapacaklarınız

• GitHub'dan Google Cloud'a güvenli kimlik doğrulamayı yapılandırma
• Gemini CLI Security Extension'ı çağıran bir GitHub Actions iş akışı oluşturun.
• GitHub Actions'ı kullanarak yeni veya mevcut bir çekme isteğinde güvenlik incelemesi çalıştırma

Neler öğreneceksiniz?

• GitHub Actions'tan Google Cloud'a güvenli kimlik doğrulama için Workload Identity federasyonunu kullanma
• Kimlik doğrulama için Gemini API anahtarı yerine Workload Identity Pool ve Workload Identity Provider kullanmanın avantajları hakkında bilgi edinin.
• PR'lerle güvenlik incelemesi yapma
• Güvenlik uzantısı tarafından döndürülen güvenlik incelemelerini yorumlama

Gerekenler

• Web tarayıcısı
• GitHub hesabı ve deposu
• Google Cloud projesi

Bu codelab, GitHub'daki CI/CD iş akışına aşina olan geliştiriciler için tasarlanmıştır. Gemini CLI veya Gemini CLI uzantıları hakkında bilgi sahibi olmanız beklenmez. Uzantıların nasıl çalıştığını öğrenmek istiyorsanız Getting Started with Gemini CLI Extensions (Gemini CLI Uzantılarına Giriş) adlı codelab'e göz atın.

Bu codelab'de, GitHub deponuzda Gemini CLI Security Extension'ı nasıl ayarlayacağınızı öğreneceksiniz. Güvenlik açığı bulgusunu tetiklemek için deponuzda PR açmanızı önermeyiz.

2. Başlamadan önce

Google Cloud kredileri için: Başlamanıza yardımcı olmak için ücretsiz Google Cloud kredilerinizi kullanın. Krediyi etkinleştirmek ve yeni bir proje oluşturmak için talimatları uygulayın.

Proje oluşturun veya seçin

1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmayı nasıl doğrulayacağınızı öğrenin.
3. Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i açın. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.

4. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:

gcloud auth list

5. gcloud komutunun projenizi kullanacak şekilde yapılandırıldığını doğrulamak için aşağıdaki komutu çalıştırın.

gcloud config list project

6. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

3. GitHub'dan Google Cloud'a kimlik doğrulama ayarlama

İşleyiş şekli

GitHub Actions'tan Google Cloud'da kimlik doğrulaması yapmak için Workload Identity Federation kullanılması önerilir.

1. Harici bir kimlik sağlayıcı olarak GitHub, her GitHub Actions iş akışı çalıştırma işi için imzalı bir JWT (JSON Web Jetonu) yayınlar. Bu jeton, söz konusu koşucu için dijital kimlik kartı görevi gören repository, workflow ve job_workflow_ref gibi "talepler" içerir. Bu laboratuvarda, GitHub'dan JWT isteğinde bulunan ve bu jetonu Google Cloud'daki Security Token Service (STS)'ye gönderen google-github-actions/run-gemini-cli işlemini kullanan bir iş içeren GitHub Actions iş akışı oluşturacaksınız.
2. Google Cloud'da bir Workload Identity Pool ve bir Sağlayıcı yapılandıracaksınız. Bunu yapmak için veren URL'sini resmi GitHub jetonu hizmeti URL'si https://token.actions.githubusercontent.com olarak ayarlayın ve genellikle depo ve dal adlarını içeren "Özellik Eşlemelerinizi" tanımlayın. Google Cloud STS, JWT'yi Workload Identity Pool kurallarına göre doğrular. Özellik eşlemeleri de dahil olmak üzere her şey doğruysa STS, GitHub jetonunu kısa ömürlü bir Google Cloud Federated Access Token ile değiştirir.
3. Artık GitHub Actions iş akışınızdaki google-github-actions/run-gemini-cli işlemi, Workload Identity havuzuna bağlı bir hizmet hesabının kimliğine bürünmek için kısa ömürlü Google Cloud Federated Access Token'ı kullanabilir. Bağlı hizmet hesabının, Google Cloud kaynaklarına ve hizmetlerine erişmek için gerekli IAM rollerine ve izinlerine sahip olması gerekir.

   GitHub, hizmet hesabı kimliğine bürünme olmadan doğrudan kimlik federasyonu kullanır. Ancak Gemini CLI, yalnızca hizmet hesabı kimliğine bürünme yoluyla desteklenen bir hizmet hesabı jetonu oluşturulmasını gerektirir.

Gemini API anahtarı yerine Workload Identity federasyonunu kullanmanın avantajları

GitHub Actions'dan kaynaklanan Gemini CLI çağrılarını, uygun anahtar değerine sahip GEMINI_API_KEY adlı yeni bir GitHub Actions sırrı oluşturarak Gemini API anahtarıyla kimlik doğrulamak mümkündür. Ancak bu durum, aşağıdaki güvenlik nedenleriyle önerilmez:

• Gemini API anahtarları, ilgili IAM rol bağlamalarından geniş izinlere sahip olabilir. Bu hesaplar saldırıya uğradığında çok çeşitli Google Cloud kaynaklarına ve hizmetlerine erişim sağlanır. Workload Identity Federation, hizmet hesaplarını ve kısa ömürlü erişim jetonlarını kullanarak kimlik doğrulama sürecini önemli ölçüde sıkılaştırır.
• Gemini API anahtarlarının büyük ölçekte yönetilmesi de zordur. Hangi iş akışlarının açığa çıkarılmış bir anahtar kullandığını belirlemek zaman alır. Anahtarları manuel olarak döndürmek de zaman alır. Diğer yandan, Cloud Console'dan deponuzla ilişkili Workload Identity havuzlarını ve sağlayıcılarını kolayca arayabilir, düzenleyebilir ve silebilirsiniz.
• Gemini API anahtarlarını kullanırken, bunları herhangi bir erişim veya hata ayıklama günlüğünde yanlışlıkla kullanıma sunmadığınızı her zaman iki kez kontrol etmeniz gerekir. Workload Identity Federation ile GitHub Actions iş akışlarının sırlarını değil, değişkenlerini depolarsınız. Değişkenler, doğası gereği daha az hassastır.

GitHub Actions ve Google Cloud'u yapılandırma

1. Cloud Shell'inizde GitHub hesabınıza giriş yapın.

gh auth login

2. Yeni bir dosya oluşturun setup_workload_identity.sh ve google-github-actions/run-gemini-cli deposundaki kurulum komut dosyasını kopyalayıp yapıştırın.
3. Komut dosyasını yürütülebilir hale getirin.

chmod +x setup_workload_identity.sh

4. Komut dosyasını çalıştırın.

./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}

4. GitHub Actions iş akışı oluşturma

1. Sahibi olduğunuz bir GitHub deposunu inceleyin.

git clone {YOUR_REPO}
cd {YOUR REPO}

2. /gemini-cli-extensions/security deposundan bir örnek iş akışı yml komut dosyasını kopyalayarak /security:analyze-github-pr eğik çizgi komutunu çağıran bir GitHub Actions iş akışı oluşturun.

git checkout -b workflow
mkdir .github/ && cd .github/
mkdir workflows/ && cd workflows/
curl -L https://raw.githubusercontent.com/gemini-cli-extensions/security/refs/heads/main/.github/workflows/gemini-review.yml -o gemini-review.yml

3. GitHub Actions iş akışını GitHub'daki uzak kaynağınıza gönderin.

git add .github/workflows/gemini-review.yml
git commit -m "add new gha workflow"
git push --set-upstream origin workflow

5. Yeni ve mevcut çekme isteklerinde güvenlik analizi iş akışını çalıştırma

GitHub deponuzda yeni bir PR başlatın veya depo sahibi ya da katkıda bulunan olarak "@gemini-cli /review" yorumunu gönderin. Bu işlem, çekme isteğiyle ilgili güvenlik incelemesini başlatır. Deponuza işlediğiniz GitHub Actions iş akışındaki Gemini CLI Güvenlik Uzantısı, bulduğu güvenlik sorunlarını "Kritik", "Yüksek", "Orta" ve "Düşük" önem derecesine göre etiketler.

Yeni bir PR'deki güvenlik incelemesi örneği ve mevcut bir PR'deki güvenlik incelemesi örneği aşağıda verilmiştir.

6. Daha fazla keşif

Gemini KSA Güvenlik uzantısındaki yeni güvenlik özelliklerini içeren ve giderek büyüyen özel komut listesini incelemenizi ve iş akışlarınızda kullanmaya başlamanızı öneririz. Örneğin:

• /security:scan-deps projenizin bağımlılıklarını OSV.dev ile çapraz referanslandırır.

En yeni özellikler ve hata düzeltmeleri için sürüm notlarına da göz atın.

7. Tebrikler

Tebrikler. GitHub deponuzu, güvenlik riskleri ve güvenlik açıkları için çekme isteklerini analiz etmek üzere Gemini CLI Security Extension'ı kullanacak şekilde başarıyla yapılandırdınız.