از افزونه امنیتی Gemini CLI برای بررسی‌های روابط عمومی GitHub استفاده کنید

۱. مقدمه

افزونه امنیتی Gemini CLI یک افزونه متن‌باز Gemini CLI ساخته گوگل است که کد را برای خطرات و آسیب‌پذیری‌های امنیتی تجزیه و تحلیل می‌کند. شما می‌توانید از افزونه امنیتی به همراه Gemini CLI برای شناسایی مشکلات امنیتی به صورت محلی استفاده کنید، همانطور که با هر افزونه Gemini CLI دیگر این کار را انجام می‌دهید. همچنین می‌توانید آن را برای بررسی درخواست‌های Pull در GitHub فراخوانی کنید. در این آزمایشگاه کد، نحوه استفاده از افزونه امنیتی در مخزن GitHub شما را بررسی خواهیم کرد.

کاری که انجام خواهید داد

• پیکربندی احراز هویت امن از گیت‌هاب به گوگل کلود
• یک گردش کار GitHub Actions ایجاد کنید که افزونه امنیتی Gemini CLI را فراخوانی کند.
• با استفاده از GitHub Actions، یک بررسی امنیتی روی یک PR جدید یا موجود اجرا کنید.

آنچه یاد خواهید گرفت

• نحوه استفاده از Workload Identity Federation برای احراز هویت امن از GitHub Actions به Google Cloud
• مزایای استفاده از Workload Identity Pool و Workload Identity Provider را نسبت به کلید API Gemini برای احراز هویت بیاموزید.
• نحوه اجرای بررسی امنیتی با PRها
• نحوه تفسیر بررسی‌های امنیتی برگردانده شده توسط افزونه امنیتی

آنچه نیاز دارید

• یک مرورگر وب
• یک حساب کاربری و مخزن گیت‌هاب
• یک پروژه ابری گوگل

این آزمایشگاه کد برای توسعه‌دهندگانی طراحی شده است که با گردش کار CI/CD در GitHub آشنا هستند. انتظار نمی‌رود که با Gemini CLI یا افزونه‌های Gemini CLI آشنایی داشته باشید. اگر می‌خواهید نحوه کار افزونه‌ها را بیاموزید، آزمایشگاه کد را بررسی کنید: شروع کار با افزونه‌های Gemini CLI .

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه افزونه امنیتی Gemini CLI را در مخزن گیت‌هاب خود راه‌اندازی کنید. ما کدی را برای باز کردن یک PR در مخزن خود برای فعال کردن یافتن آسیب‌پذیری امنیتی پیشنهاد نمی‌کنیم.

۲. قبل از شروع

برای اعتبارهای Google Cloud: برای کمک به شروع کار، اعتبارهای رایگان Google Cloud خود را فعال کنید . دستورالعمل‌ها را برای فعال کردن اعتبار و ایجاد یک پروژه جدید دنبال کنید.

ایجاد یا انتخاب پروژه

1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. نحوه تأیید صورتحساب را بیاموزید.
3. Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می‌شود را باز کنید. در بالای کنسول Google Cloud روی Activate Cloud Shell کلیک کنید.

4. پس از اتصال به Cloud Shell، با استفاده از دستور زیر، بررسی کنید که احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است:

gcloud auth list

5. برای تأیید اینکه دستور gcloud برای استفاده از پروژه شما پیکربندی شده است، دستور زیر را اجرا کنید.

gcloud config list project

6. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

۳. تنظیم احراز هویت از گیت‌هاب به گوگل کلود

چگونه کار می‌کند؟

فدراسیون هویت بار کاری (Workload Identity Federation ) روش پیشنهادی برای احراز هویت از GitHub Actions به Google Cloud است.

1. برای هر کار (job) که توسط GitHub Actions workflow اجرا می‌شود ، GitHub به عنوان یک ارائه دهنده هویت خارجی، یک JWT (توکن وب JSON) امضا شده صادر می‌کند. این توکن شامل "claims" هایی مانند repository ، workflow و job_workflow_ref است که به عنوان یک کارت شناسایی دیجیتال برای آن اجرا کننده خاص عمل می‌کنند. در این آزمایش، شما یک گردش کار GitHub Actions با یک job ایجاد خواهید کرد که از اکشن google-github-actions/run-gemini-cli استفاده می‌کند، که یک JWT را از GitHub درخواست کرده و این توکن را به سرویس توکن امنیتی (STS) در Google Cloud ارسال می‌کند.
2. شما با تنظیم URL صادرکننده به آدرس رسمی سرویس توکن GitHub به آدرس https://token.actions.githubusercontent.com و تعریف "نگاشت‌های ویژگی" خود، که معمولاً شامل نام مخزن و شاخه‌ها می‌شود، یک Workload Identity Pool و یک Provider را در Google Cloud پیکربندی خواهید کرد. Google Cloud STS، JWT را بر اساس قوانین Workload Identity Pool اعتبارسنجی می‌کند. اگر همه چیز، از جمله نگاشت‌های ویژگی، بررسی شود، STS توکن GitHub را با یک Google Cloud Federated Access Token کوتاه مدت مبادله می‌کند.
3. اکنون اکشن google-github-actions/run-gemini-cli در گردش کار GitHub Actions شما می‌تواند از توکن دسترسی فدرال گوگل کلود (Google Cloud Federated Access Token) که مدت کوتاهی فعال است، برای "جعل هویت" یک حساب سرویس متصل به Workload Identity Pool استفاده کند. حساب سرویس متصل باید نقش‌ها و مجوزهای IAM لازم را برای دسترسی به هرگونه منابع و سرویس‌های گوگل کلود داشته باشد.

   گیت‌هاب از فدراسیون هویت مستقیم بدون جعل هویت حساب کاربری سرویس استفاده می‌کند. با این حال، رابط خط فرمان Gemini نیاز به ایجاد توکن حساب کاربری سرویس دارد که فقط از طریق جعل هویت حساب کاربری سرویس پشتیبانی می‌شود.

مزایای استفاده از Workload Identity Federation نسبت به Gemini API Key

می‌توان فراخوانی‌های Gemini CLI را که از GitHub Actions سرچشمه گرفته‌اند، با استفاده از کلید API Gemini تأیید اعتبار کرد، که شامل ایجاد یک رمز جدید GitHub Actions با نام GEMINI_API_KEY با مقدار کلید مناسب است. با این حال، این کار به دلایل امنیتی زیر توصیه نمی‌شود:

• کلیدهای API Gemini می‌توانند مجوزهای گسترده‌ای از اتصالات نقش IAM مربوطه خود داشته باشند. در صورت نفوذ، دسترسی به طیف وسیعی از منابع و خدمات Google Cloud را فراهم می‌کنند. فدراسیون هویت بار کاری از حساب‌های سرویس و توکن‌های دسترسی کوتاه‌مدت استفاده می‌کند که به طور قابل توجهی احراز هویت را محدود می‌کند.
• مدیریت کلیدهای API Gemini در مقیاس بزرگ نیز چالش برانگیز است. شناسایی اینکه کدام گردش‌های کاری از یک کلید در معرض خطر استفاده می‌کنند، زمان‌بر است. چرخاندن دستی کلیدها نیز زمان‌بر است. از طرف دیگر، می‌توانید به راحتی استخرها و ارائه دهندگان هویت بار کاری مرتبط با مخزن خود را از کنسول ابری جستجو، ویرایش و حذف کنید.
• با کلیدهای API Gemini، شما همیشه باید دوباره بررسی کنید که آنها را به طور تصادفی در هیچ لاگ دسترسی یا اشکال‌زدایی افشا نکنید. با فدراسیون هویت بار کاری، شما هیچ راز گردش کار GitHub Actions را ذخیره نمی‌کنید، بلکه متغیرهایی را ذخیره می‌کنید که ذاتاً حساسیت کمتری دارند.

پیکربندی GitHub Actions و Google Cloud

1. در Cloud Shell خود، وارد حساب GitHub خود شوید.

gh auth login

2. یک فایل جدید setup_workload_identity.sh ایجاد کنید و اسکریپت راه‌اندازی را از مخزن google-github-actions/run-gemini-cli کپی و جایگذاری کنید.
3. اسکریپت را به یک فایل اجرایی تبدیل کنید.

chmod +x setup_workload_identity.sh

4. اسکریپت را اجرا کنید.

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

۴. یک گردش کار GitHub Actions ایجاد کنید

1. مخزن گیت‌هاب متعلق به خودتان را بررسی کنید.

git clone {YOUR_REPO}
cd {YOUR REPO}

2. با کپی کردن یک اسکریپت yml نمونه از مخزن /gemini-cli-extensions/security ، یک گردش کار GitHub Actions ایجاد کنید که دستور اسلش /security:analyze-github-pr را فراخوانی کند.

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 را به سرور اصلی خود در GitHub منتقل کنید.

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

۵. اجرای گردش کار تحلیل امنیتی روی PR های جدید و موجود

یک PR جدید در مخزن گیت‌هاب خود شروع کنید یا یک نظر جدید با عنوان "@gemini-cli /review" به عنوان مالک یا مشارکت‌کننده مخزن ارسال کنید. این کار یک بررسی امنیتی روی PR آغاز می‌کند. افزونه امنیتی Gemini CLI از گردش کار GitHub Actions که شما به مخزن خود کامیت کرده‌اید، هر مسئله امنیتی را که پیدا کند، بر اساس دسته‌بندی‌های شدت از "بحرانی"، "زیاد"، "متوسط" تا "کم" برچسب‌گذاری می‌کند.

در اینجا مثالی از بررسی امنیتی یک PR جدید و مثالی از بررسی امنیتی یک PR موجود آورده شده است.

۶. کاوش بیشتر

ما شما را تشویق می‌کنیم که فهرست رو به رشدی از دستورات سفارشی با قابلیت‌های امنیتی جدید در افزونه Gemini CLI Security را بررسی کنید و استفاده از آن را در گردش‌های کاری خود شروع کنید. به عنوان مثال:

• /security:scan-deps وابستگی‌های پروژه شما را با OSV.dev ارجاع متقابل می‌دهد.

برای اطلاع از آخرین ویژگی‌ها و رفع اشکالات ، یادداشت‌های انتشار را نیز بررسی کنید.

۷. تبریک

تبریک می‌گوییم، شما با موفقیت مخزن گیت‌هاب خود را پیکربندی کرده‌اید تا از افزونه امنیتی Gemini CLI برای تجزیه و تحلیل PRها جهت شناسایی خطرات و آسیب‌پذیری‌های امنیتی استفاده کند.