۱. 📖 مقدمه
در این آزمایشگاه کد، اصول اولیه Gemini CLI را یاد خواهید گرفت و از افزونه بررسی کد و تحلیل امنیتی آن در گردش کار توسعه نرم‌افزار خود استفاده خواهید کرد.
آنچه یاد خواهید گرفت
- نحوه راه‌اندازی رابط خط فرمان Gemini
- نحوه پیکربندی رابط خط فرمان Gemini
- نحوه نصب افزونه Gemini CLI
- نحوه استفاده از افزونه Gemini CLI برای بررسی کد و تحلیل امنیتی
- نحوه پیکربندی MCP برای رابط خط فرمان Gemini
- نحوه بررسی رابط خط فرمان Gemini در CI/CD
آنچه نیاز دارید
- مرورگر وب کروم
- یک حساب جیمیل
- یک پروژه ابری با حساب صورتحساب فعال
۲. 🚀 آماده‌سازی مقدمات توسعه کارگاه
مرحله ۱: انتخاب پروژه فعال در کنسول ابری
در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید (به بخش بالا سمت چپ کنسول خود مراجعه کنید)
روی آن کلیک کنید، و لیستی از تمام پروژه‌های خود را مانند این مثال مشاهده خواهید کرد،
مقداری که با کادر قرمز مشخص شده است، شناسه پروژه (PROJECT ID) است و این مقدار در طول آموزش استفاده خواهد شد.
مطمئن شوید که پرداخت صورتحساب برای پروژه ابری شما فعال است. برای بررسی این موضوع، روی نماد همبرگر ☰ در نوار بالا سمت چپ که منوی پیمایش را نشان می‌دهد کلیک کنید و منوی پرداخت صورتحساب را پیدا کنید.
اگر عبارت «حساب پرداخت آزمایشی پلتفرم ابری گوگل» را زیر عنوان «پرداخت / بررسی اجمالی» ( قسمت بالا سمت چپ کنسول ابری خود ) مشاهده کردید، پروژه شما آماده استفاده برای این آموزش است. در غیر این صورت، به ابتدای این آموزش برگردید و حساب پرداخت آزمایشی را فعال کنید.
مرحله ۲: آشنایی با Cloud Shell
شما در بیشتر بخش‌های آموزش از Cloud Shell استفاده خواهید کرد، روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید. اگر از شما درخواست تأیید کرد، روی Authorize کلیک کنید.
پس از اتصال به Cloud Shell، باید بررسی کنیم که آیا shell (یا ترمینال) از قبل با حساب ما احراز هویت شده است یا خیر.
gcloud auth list
اگر خروجی جیمیل شخصی خود را مانند نمونه زیر مشاهده کردید، همه چیز درست است.
Credentialed Accounts
ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
اگر اینطور نیست، مرورگر خود را رفرش کنید و مطمئن شوید که در صورت درخواست، روی «مجوز» کلیک می‌کنید (ممکن است به دلیل مشکل اتصال، قطع شود).
در مرحله بعد، باید بررسی کنیم که آیا پوسته از قبل با شناسه پروژه صحیحی که دارید پیکربندی شده است یا خیر، اگر مقداری را داخل () قبل از نماد $ در ترمینال مشاهده کردید (در تصویر زیر، مقدار "your-workshop-project" است)، این مقدار پروژه پیکربندی شده برای جلسه پوسته فعال شما را نشان می‌دهد.
اگر مقدار نمایش داده شده از قبل صحیح است، می‌توانید از دستور بعدی صرف نظر کنید . اما اگر صحیح نیست یا وجود ندارد، دستور زیر را اجرا کنید
gcloud config set project <YOUR_PROJECT_ID>
مرحله 3: آشنایی با ویرایشگر Cloud Shell و دایرکتوری کاری برنامه نصب
حالا می‌توانیم ویرایشگر کد خود را برای انجام برخی کارهای کدنویسی تنظیم کنیم. برای این کار از ویرایشگر Cloud Shell استفاده خواهیم کرد.
روی دکمه‌ی «باز کردن ویرایشگر» کلیک کنید، این کار یک ویرایشگر Cloud Shell را باز می‌کند. 
اکنون رابط کاربری Cloud Shell Editor را مانند شکل زیر مشاهده خواهید کرد.
حالا، مخزن نسخه آزمایشی که با آن تعامل خواهیم داشت را کلون کنید. ابتدا، باید ترمینال را برای ویرایشگر باز کنیم. می‌توانید این کار را با کلیک روی ترمینال -> ترمینال جدید در نوار منو انجام دهید، یا از Ctrl + Shift + C استفاده کنید، این کار یک پنجره ترمینال در قسمت پایین مرورگر باز می‌کند.
سپس این دستور را در ترمینال اجرا کنید
git clone https://github.com/alphinside/gemini-cli-code-analysis-demo.git code-analysis-demo
پس از آن، به بخش بالای ویرایشگر Cloud Shell بروید و روی File->Open Folder کلیک کنید، پوشه نام کاربری خود را پیدا کنید و پوشه مخزن شبیه‌سازی شده code-analysis-demo پیدا کنید و سپس روی دکمه OK کلیک کنید. این کار پوشه انتخاب شده را به عنوان پوشه اصلی کار تبدیل می‌کند. در این مثال، نام کاربری alvinprayuda است، از این رو مسیر پوشه در زیر نشان داده شده است.
حالا، دایرکتوری کاری ویرایشگر Cloud Shell شما باید به این شکل باشد
حالا می‌توانیم به مرحله بعدی برویم
۳. 🚀 راه‌اندازی و پیکربندی
اگر می‌خواهید Gemini CLI را در سیستم محلی خود نصب کنید، می‌توانید این مراحل را دنبال کنید:
- مطمئن شوید که سیستم شما نسخه Node 20+ را دارد.
- فعال کردن رابط خط فرمان Gemini از طریق یکی از روش‌های زیر:
- نصب آن به عنوان یک بسته سراسری
# Install as an executor
npm install -g @google/gemini-cli
# then run it from terminal
gemini
- یا آن را مستقیماً از منبع اجرا کنید تا همیشه آخرین نسخه را دریافت کنید
npx https://github.com/google-gemini/gemini-cli
وقتی برای اولین بار آن را اجرا می‌کنید، چندین سوال از شما می‌پرسد. اگر آن را از یک IDE (مثلاً VSCode) اجرا کنید، سوال زیر را از شما می‌پرسد.
سپس، از شما چندین گزینه برای تأیید اعتبار می‌پرسد.
چندین گزینه وجود دارد:
- اگر گزینه ورود با گوگل را انتخاب کنید، صفحه احراز هویت گوگل در مرورگر باز می‌شود و شما فقط باید آن را بپذیرید.
- اگر ترجیح می‌دهید از کلید API Gemini استفاده کنید، باید یکی را در صفحه AI Studio ایجاد کنید و سپس فایل .env را در دایرکتوری کاری خود با متغیر GEMINI_API_KEY ایجاد کنید (یا دستور
export GEMINI_API_KEY="your-api-key"در خط فرمان اجرا کنید). - اگر تصمیم به استفاده از Vertex AI دارید، به پروژه‌ای مانند آنچه قبلاً راه‌اندازی کردید نیاز خواهید داشت و فایل .env را ایجاد کرده و GOOGLE_CLOUD_PROJECT و GOOGLE_CLOUD_LOCATION را تنظیم کنید.
اگر می‌خواهید این روش‌های احراز هویت را تغییر دهید، می‌توانید دستور /auth را از رابط خط فرمان Gemini اجرا کنید یا فایل پیکربندی را ویرایش کنید. اگر می‌خواهید فایل پیکربندی را مستقیماً ویرایش کنید، در لینوکس باید در $HOME/.gemini/settings.json باشد. نوع security و auth را مشاهده کرده و آن را ویرایش کنید.
{
"security": {
"auth": {
"selectedType": "vertex-ai" # or "gemini-api-key" or "oauth-personal"
}
}
}
۴. 🚀 دستورات پایه و ابزارهای داخلی
حالا، بیایید با رابط خط فرمان Gemini کمی کار کنیم تا بیشتر در مورد آن بدانیم، اگر به دنبال دستورهای پایه‌ای هستید که بتوانید از آنها استفاده کنید، می‌توانید برای نمایش تمام دستورات موجود، /help را تایپ کنید.
/help
خروجی مانند این را خواهید دید 
رابط خط فرمان Gemini یک عامل هوش مصنوعی است، از این رو ابزارهایی برای حل وظیفه‌ای که کاربر به آن می‌دهد، خواهد داشت. برای مشاهده ابزارهای داخلی آن، دستور /tools را اجرا کنید.
/tools
خروجی به این شکل به شما نشان داده خواهد شد
می‌توانید ببینید که Gemini CLI قابلیت‌های مختلفی مانند خواندن و نوشتن در فایل، جستجوی وب و چندین مورد دیگر دارد. چندین مورد از این ابزارها به دلیل خطر بالقوه، به طور پیش‌فرض نیاز به تأیید کاربر داشتند.
حالا بیایید آن را در عمل ببینیم، سعی کنید این اعلان‌ها را در Gemini CLI اجرا کنید.
Find top 10 OWASP security issue and write it down to owasp.md
خواهید دید که ابزار GoogleSearch فراخوانی می‌کند و بعداً نتیجه را با استفاده از WriteFile می‌نویسد. و اگر از IDE استفاده کنید، خواهید دید که به عنوان یک گزینه diff و نمایش اینکه آیا می‌خواهید پیشنهادات را بپذیرید یا رد کنید، ارائه می‌شود. در اینجا، می‌توانید ببینید که Gemini CLI از شما اجازه نوشتن فایل را می‌خواهد.
۵. 🚀 اکستنشن‌ها
برای بهبود خروجی یک کار خاص با یک عامل هوش مصنوعی، چالش‌های پیش رو این است که چگونه می‌توانیم یک اعلان مناسب ایجاد کنیم، یک مهندسی زمینه مناسب را با ادغام ابزارهای مناسب مدیریت کنیم و غیره.
افزونه‌های Gemini CLI یک بسته‌ی آماده و به راحتی قابل نصب هستند که می‌توانند به ابزارهای خارجی متصل شوند. هر افزونه شامل یک «کتابچه‌ی راهنما»ی داخلی در مورد نحوه‌ی استفاده‌ی مؤثر از ابزارها است و می‌تواند از اجزای زیر تشکیل شود:
- دستورات اسلش سفارشی
- پیکربندی‌های MCP
- فایل‌های زمینه
نصب افزونه‌های امنیتی
برای مثال، در این آموزش، نحوه نصب افزونه‌های code-review و security را بررسی خواهیم کرد.
دستور زیر را برای نصب افزونه‌های security از ترمینال اجرا کنید.
gemini extensions install https://github.com/gemini-cli-extensions/security
سوالات زیر نمایش داده می‌شود، برای پذیرش، فقط Enter را فشار دهید.
Installing extension "gemini-cli-security". **Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.** This extension will run the following MCP servers: * securityServer (local): node /home/alvinprayuda/.gemini/extensions/gemini-cli-security/mcp-server/dist/security.js This extension will append info to your gemini.md context using GEMINI.md Do you want to continue? [Y/n]: Extension "gemini-cli-security" installed successfully and enabled.
نصب افزونه‌های بررسی کد
و در مرحله بعد، افزونه code-review را نصب می‌کنیم، دستور زیر را اجرا کنید
gemini extensions install https://github.com/gemini-cli-extensions/code-review
پس از اتمام، دوباره Gemini CLI را اجرا کنید
gemini
و دستور /extensions را اجرا کنید، خواهید دید که این دو افزونه از قبل نصب شده‌اند.
/extensions
بسیار خوب، حالا بیایید یک اجرای عملی روی مخزن نمونه‌ای که قبلاً کلون کرده‌اید انجام دهیم.
۶. 🚀 حالت تعاملی - برنامه افزونه تحلیل امنیت کد
افزونه‌ی امنیتی (Security) یک افزونه‌ی متن‌باز رابط خط فرمان (CLI) برای Gemini است که برای افزایش امنیت مخزن ساخته شده است. این افزونه یک دستور جدید به رابط خط فرمان Gemini اضافه می‌کند که تغییرات کد را تجزیه و تحلیل می‌کند تا انواع خطرات و آسیب‌پذیری‌های امنیتی را شناسایی کند.
حالا بیایید ابتدا مخزن آزمایشی خود را آماده کنیم، دستور زیر را اجرا کنید تا به شاخه‌ای بروید که تغییرات با ریسک امنیتی از قبل در آن اعمال شده‌اند.
git checkout refactor/analysis-demo
پس از آن، Gemini CLI را در ترمینال اجرا کنید.
gemini
سپس افزونه‌ها را اجرا می‌کنیم
/security:analyze
این یک فرآیند طولانی مدت را آغاز می‌کند و در طول فرآیند، چندین وقفه دریافت خواهید کرد که از شما اجازه اجرای عملیات خاصی مانند mkdir را درخواست می‌کند، همانطور که در زیر نشان داده شده است.
این یک مکانیسم حفاظتی است تا اطمینان حاصل شود که کاربران از آنچه توسط Gemini CLI اجرا خواهد شد، آگاه هستند. در ادامه آموزش، همیشه می‌توانید آن را مجاز کنید (گزینه ۲).
این افزونه یک فرآیند طولانی مدت را فراخوانی می‌کند، می‌توانید ببینید که یک فایل برنامه‌ریزی در داخل دایرکتوری .gemini_security ایجاد می‌کند و می‌توانید چک لیستی را ببینید که نشان می‌دهد کدام فرآیند انجام شده است یا خیر. همانطور که در مثال زیر نشان داده شده است:
مدتی طول می‌کشد تا وظایفش تمام شود، در این مدت می‌توانیم منبع این افزونه‌ها را در مخزن گیت‌هاب بررسی کنیم. این URL نشان‌دهنده‌ی اعلانی است که برای اجرای تمام این فرآیندهای اسکن امنیتی استفاده می‌شود.
همانطور که در آنجا می‌بینید، برای انجام این اسکن، باید از طریق رابط خط فرمان Gemini، بررسی دو مرحله‌ای، مرحله شناسایی و مرحله تحقیقات دقیق‌تر را انجام دهید.
اگر در رابط خط فرمان Gemini با پیام زیر مواجه شدید، می‌توانید گزینه ۲ را برای غیرفعال کردن تشخیص حلقه انتخاب کنید.
سپس از رابط خط فرمان Gemini بخواهید ادامه دهد
continue
این مکانیزمی برای جلوگیری از حلقه‌های فراخوانی ابزار بی‌نهایت و غیرمولد است و به مرور زمان بهبود خواهد یافت.
پس از اتمام، گزارش در ترمینال تعاملی نمایش داده می‌شود، برای آسان‌تر کردن این کار، بیایید به Gemini CLI دستور دهیم که آن را در security-analysis.md بنویسد.
write the result to security-analysis.md file
حالا می‌توانید نتیجه‌ی نوشته شده روی فایل را بررسی کنید.
۷. 🚀 حالت غیرتعاملی - برنامه افزونه بررسی کد
افزونه‌ی code-review دستور جدیدی را به رابط خط فرمان Gemini اضافه می‌کند که تغییرات کد را برای شناسایی انواع مشکلات کیفیت کد، تجزیه و تحلیل می‌کند.
این افزونه می‌تواند در حالت غیر تعاملی Gemini CLI اجرا شود، به این معنی که تمام فرآیند می‌تواند بدون نیاز به ورود به پوسته Gemini CLI اجرا شود. برای اجرای Gemini CLI در حالت غیر تعاملی، می‌توانید این کار را با الگوی دستور زیر انجام دهید:
gemini "put your command here"
با این حال، لازم به ذکر است که اجرا در حالت غیر تعاملی، هرگونه عملیاتی از ابزارها را که به اجازه کاربر نیاز دارد، غیرفعال می‌کند، از این رو باید پرچم --yolo را برای تأیید خودکار همه اقدامات اضافه کنیم، به این معنی که همه ابزارها در حالت غیر تعاملی فعال می‌شوند.
بیایید افزونه‌ی code-review را با دستور زیر اجرا کنیم.
gemini "/code-review" --yolo -e code-review > code-review.md
این دستور نتیجه خروجی Gemini CLI را در فایل code-review.md می‌نویسد. به فلگ -e در اینجا توجه کنید، این فلگ کنترل می‌کند که کدام افزونه در طول جلسه فعال شود. در اینجا ما فقط افزونه code-review را فعال می‌کنیم و بقیه را غیرفعال می‌کنیم.
مدتی طول خواهد کشید، اما پس از اتمام، می‌توانید نتیجه‌ای مشابه آنچه در زیر نشان داده شده است را که در فایل markdown نوشته شده است، مشاهده کنید.
Here are the results of the code review.
While the recent changes to rename `get_products` and `get_product` to `GetProducts` and `GetProduct` are minor, the codebase has some inconsistencies in its naming conventions. For instance, other functions like `create_product` use `snake_case`, while the newly renamed functions use `PascalCase`. For better code quality and readability, I recommend using a consistent naming convention throughout the project.
More importantly, I have identified several security vulnerabilities in the `main.py` file. Here is a summary of the findings:
### 1. SQL Injection
* **Severity**: High
* **Location**:
* `main.py:99` in `get_products_by_category`
* `main.py:146` in `search_products`
* `main.py:372` in `get_user_transactions`
* `main.py:438` in `adjust_inventory_by_query`
* **Description**: The endpoints directly use f-strings to construct SQL queries, making them vulnerable to SQL injection attacks. An attacker could manipulate the input to execute arbitrary SQL commands, potentially leading to data breaches or unauthorized modifications.
* **Recommendation**: Use parameterized queries or an ORM to handle database interactions. This will ensure that user input is properly sanitized and prevent SQL injection attacks.
### 2. Server-Side Request Forgery (SSRF)
* **Severity**: High
* **Location**: `main.py:265` in `fetch_url`
* **Description**: The `fetch_url` endpoint allows users to specify an arbitrary URL, which the server then requests. This can be exploited to make requests to internal services or local files, leading to information disclosure or other security breaches.
* **Recommendation**: Implement a whitelist of allowed domains or protocols to restrict the URLs that can be requested. Additionally, you can disable redirects and use a timeout to limit the impact of an attack.
### 3. Information Exposure
* **Severity**: Medium
* **Location**: `main.py:423` in `get_environment_variables`
* **Description**: The `get_environment_variables` endpoint exposes all environment variables to the user. This can include sensitive information such as API keys, database credentials, and other secrets.
* **Recommendation**: Remove this endpoint or restrict access to it to authorized users. If you need to expose some environment variables, do so selectively and avoid exposing sensitive information.
۸. 🚀 پشتیبانی از پروتکل زمینه مدل
حال، همانطور که قبلاً در توضیحات افزونه بررسی کردیم، رابط خط فرمان Gemini می‌تواند به سرورهای MCP متصل شود - برنامه‌هایی که ابزارها و منابع را از طریق پروتکل Model Context ارائه می‌دهند. این اتصال به Gemini CLI اجازه می‌دهد تا با استفاده از سرورهای MCP به عنوان پل‌هایی به محیط محلی شما و سرویس‌های خارجی مانند APIها، با سیستم‌ها و منابع داده خارجی تعامل داشته باشد.
اگر می‌خواهید سرور MCP خودتان را راه‌اندازی کنید، باید فایل .gemini/settings.json خود را تغییر داده و پیکربندی‌های زیر را به آن اضافه کنید:
{
...
# Previous settings above if any
"mcpServers": {
"server_name": {
# MCP server configurations here
}
}
}
برای این آموزش، بیایید اتصال با حساب گیت‌هاب خود را پیکربندی کنیم تا داده‌های گزارش قبلی را به گیت‌هاب ارسال کنیم.
پیکربندی سرور Github MCP
ابتدا، فایل پیکربندی پروژه Gemini CLI خود را ایجاد می‌کنیم. دستور زیر را اجرا کنید
mkdir -p .gemini && touch .gemini/settings.json
سپس فایل .gemini/settings.json را باز کنید و آن را با پیکربندی زیر پر کنید.
{
"mcpServers": {
"github": {
"httpUrl": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "your-personal-access-token"
},
"timeout": 5000
}
}
}
حالا، ما به توکن دسترسی شخصی Github شما نیاز داریم، بنابراین مطمئن شوید که از قبل حساب Github خود را دارید.
به گیت‌هاب خود وارد شوید و به تنظیمات بروید
پس از آن، به پایین اسکرول کنید تا تنظیمات توسعه‌دهنده (Developer settings) را پیدا کنید و روی آن کلیک کنید.
سپس روی نشانه‌های دسترسی شخصی کلیک کنید و توکن‌ها (کلاسیک) را انتخاب کنید.
نام توکن دسترسی شخصی خود را اینجا وارد کنید و محدوده‌های مخزن را بررسی کنید
سپس به پایین اسکرول کنید و روی دکمه‌ی Generate Token کلیک کنید، مطمئن شوید که
روی دکمه‌ی «ایجاد توکن جدید» کلیک کنید و گزینه‌ی « ایجاد توکن جدید (کلاسیک)» را انتخاب کنید. پس از آن، توکن تولید شده را کپی کرده و در فایل .gemini/settings.json بنویسید.
بنابراین، فایل .gemini/settings.json شما باید مانند مثال زیر باشد.
{
"mcpServers": {
"github": {
"httpUrl": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "ghp-xxxx"
},
"timeout": 5000
}
}
}
حالا، بیایید اتصال را تأیید کنیم. با اجرای این دستور، وارد Gemini CLI شوید.
gemini
سپس، دستور /mcp را اجرا کنید، باید ببینید که Github MCP از قبل به درستی پیکربندی شده است.
/mcp
سپس برای آزمایش این اتصال MCP، این دستور را ارسال می‌کنیم.
Aggregate the findings from @code-review.md and @security-analysis.md into a single report and ensure no duplicates issues reported. Post this report as a comment on the relevant pull request for the current git branch on GitHub and display the pull request URL for manual review
به نمادهای @code-review.md و @security-analysis.md در اینجا توجه کنید، اینگونه است که ما به فایل‌هایی که باید به Gemini CLI ارسال شوند، ارجاع می‌دهیم. این دستور محتوای هر دو فایل را می‌خواند و با استفاده از اتصال Github MCP، یک نظر را به درخواست Pull مربوط به این شاخه ارسال می‌کند. پس از آن می‌توانید URL درخواست pull را بررسی کنید تا آن را تأیید کنید.
۹. 💡Gemini CLI در گردش کار CI/CD
اگر شما یک کاربر گیت‌هاب هستید، می‌توانید به راحتی Gemini CLI را با استفاده از run-gemini-cli Github Action در خط لوله CI/CD خود جاسازی کنید. این ابزار هم به عنوان یک عامل مستقل برای وظایف کدنویسی روتین و هم به عنوان یک همکار بر اساس تقاضا عمل می‌کند که می‌توانید به سرعت کار را به او واگذار کنید.
شما می‌توانید از آن برای انجام بررسی درخواست‌های pull، بررسی مشکلات، انجام تجزیه و تحلیل و اصلاح کد و موارد دیگر با استفاده از Gemini به صورت مکالمه‌ای مستقیماً در مخازن Github استفاده کنید.
نمونه‌ای از این ادغام را می‌توان در این درخواست pull بررسی کرد، که در آن از افزونه Gemini CLI Security درون runner استفاده می‌کنیم و هنگام ایجاد درخواست pull، بررسی‌ها را ارائه می‌دهیم.
۱۰. 💡سایر افزونه‌های خط فرمان Gemini را بررسی کنید
همچنین می‌توانید افزونه‌های بیشتری را در https://geminicli.com/extensions بررسی کنید. برای ابزارهای جالب‌تر، آن را بررسی کنید!
۱۱. 🧹 تمیز کردن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این codelab، این مراحل را دنبال کنید:
- در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
- در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
- در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.