۱. 📖 مقدمه
در این آزمایشگاه کد، اصول اولیه Gemini CLI را یاد خواهید گرفت و از افزونه بررسی کد و تحلیل امنیتی آن در گردش کار توسعه نرمافزار خود استفاده خواهید کرد.
آنچه یاد خواهید گرفت
- How to setup Gemini CLI
- نحوه پیکربندی رابط خط فرمان 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`
اگر اینطور نیست، مرورگر خود را رفرش کنید و مطمئن شوید که در صورت درخواست، روی «مجوز» کلیک میکنید (ممکن است به دلیل مشکل اتصال، قطع شود).
مرحله 3: آشنایی با ویرایشگر Cloud Shell و دایرکتوری کاری برنامه نصب
حالا میتوانیم ویرایشگر کد خود را برای انجام برخی کارهای کدنویسی تنظیم کنیم. برای این کار از ویرایشگر Cloud Shell استفاده خواهیم کرد.
ما باید مخزن نسخه آزمایشی را که با آن تعامل خواهیم داشت، کلون کنیم. این دستور را در ترمینال اجرا کنید تا مخزن کلون شود و ویرایشگر Cloud Shell باز شود.
git clone https://github.com/alphinside/gemini-cli-code-analysis-demo.git code-analysis-demo && cloudshell ws code-analysis-demo
حالا، دایرکتوری کاری ویرایشگر Cloud Shell شما باید به این شکل باشد
در مرحله بعد، باید مطمئن شویم که آیا پوسته از قبل با شناسه پروژه صحیحی که دارید پیکربندی شده است یا خیر، اگر مقداری را داخل () قبل از نماد $ در ترمینال مشاهده کردید (در تصویر زیر، مقدار "your-workshop-project" است)، این مقدار پروژه پیکربندی شده برای جلسه پوسته فعال شما را نشان میدهد.
اگر مقدار نمایش داده شده از قبل صحیح است، میتوانید از دستور بعدی صرف نظر کنید . اما اگر صحیح نیست یا وجود ندارد، دستور زیر را اجرا کنید
gcloud config set project <YOUR_PROJECT_ID>
Now we can go to the next phase
۳. 🚀 راهاندازی و پیکربندی
اگر میخواهید 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) اجرا کنید، سوال زیر را از شما میپرسد.
سپس، از شما چندین گزینه برای تأیید اعتبار میپرسد.
There are several options:
- اگر گزینه ورود با گوگل را انتخاب کنید، صفحه احراز هویت گوگل در مرورگر باز میشود و شما فقط باید آن را بپذیرید.
- اگر ترجیح میدهید از کلید API Gemini استفاده کنید، باید یکی را در صفحه AI Studio ایجاد کنید و سپس فایل .env را در دایرکتوری کاری خود با متغیر GEMINI_API_KEY ایجاد کنید (یا دستور
export GEMINI_API_KEY="your-api-key"را در خط فرمان اجرا کنید). - If you choose to use Vertex AI, you will need a project like you setup previously and create .env file and set the GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION
اگر میخواهید این روشهای احراز هویت را تغییر دهید، میتوانید دستور /auth را از رابط خط فرمان Gemini اجرا کنید یا فایل پیکربندی را ویرایش کنید. اگر میخواهید فایل پیکربندی را مستقیماً ویرایش کنید، در لینوکس باید در $HOME/.gemini/settings.json باشد. نوع security و auth را مشاهده کرده و آن را ویرایش کنید.
{
"security": {
"auth": {
"selectedType": "vertex-ai" # or "gemini-api-key" or "oauth-personal"
}
}
}
۴. 🚀 دستورات پایه و ابزارهای داخلی
حالا، بیایید کمی با رابط خط فرمان Gemini کار کنیم تا بیشتر در مورد آن بدانیم. دستور زیر را در ترمینال اجرا کنید تا وارد رابط خط فرمان Gemini شوید.
gemini
اگر به دنبال دستورهای پایهای هستید که بتوانید از آنها استفاده کنید، میتوانید برای نمایش تمام دستورات موجود، دستور /help را تایپ کنید.
/help
You will see output like this 
رابط خط فرمان Gemini یک عامل هوش مصنوعی است، از این رو ابزارهایی برای حل وظیفهای که کاربر به آن میدهد، خواهد داشت. برای مشاهده ابزارهای داخلی آن، دستور /tools را اجرا کنید.
/tools
خروجی به این شکل به شما نشان داده خواهد شد
You can see that Gemini CLI has several capabilities like read and write to file, web search and several more. Several of these tools required user acknowledgement by default due to the potential risk
حالا بیایید آن را در عمل ببینیم، سعی کنید این اعلانها را در Gemini CLI اجرا کنید.
Find top 10 OWASP security issue and write it down to owasp.md
You will see it will invoke GoogleSearch tool and later on it will write the result using WriteFile one. And if you utilize IDE, you will see that it will be presented as a diff and display option whether you want to accept or reject the suggestions. Here, you can see that Gemini CLI ask you permission to write the file
۵. 🚀 اکستنشنها
In order to improve output of a specific task with an AI Agent, the challenging things are how we can craft a proper prompt, manage a proper context engineering with proper tools integration and so on.
افزونههای Gemini CLI یک بستهی آماده و به راحتی قابل نصب هستند که میتوانند به ابزارهای خارجی متصل شوند. هر افزونه شامل یک «کتابچهی راهنما»ی داخلی در مورد نحوهی استفادهی مؤثر از ابزارها است و میتواند از اجزای زیر تشکیل شود:
- Custom slash commands
- پیکربندیهای MCP
- Context files
Installing Security Extensions
برای مثال، در این آموزش، نحوه نصب افزونههای 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
بسیار خوب، حالا بیایید یک اجرای عملی روی مخزن نمونهای که قبلاً کلون کردهاید انجام دهیم.
۶. 🚀 حالت تعاملی - برنامه افزونه تحلیل امنیت کد
The Security extension is an open-source Gemini CLI extension, built to enhance the repository's security. The extension adds a new command to Gemini CLI that analyzes code changes to identify a variety of security risks and vulnerabilities.
حالا بیایید ابتدا مخزن آزمایشی خود را آماده کنیم، دستور زیر را اجرا کنید تا به شاخهای بروید که تغییرات با ریسک امنیتی از قبل در آن اعمال شدهاند.
git checkout refactor/analysis-demo
پس از آن، Gemini CLI را در ترمینال اجرا کنید.
gemini
سپس افزونهها را اجرا میکنیم
/security:analyze
این یک فرآیند طولانی مدت را آغاز میکند و در طول فرآیند، چندین وقفه دریافت خواهید کرد که از شما اجازه اجرای عملیات خاصی مانند mkdir را درخواست میکند، همانطور که در زیر نشان داده شده است.
این یک مکانیسم حفاظتی است تا اطمینان حاصل شود که کاربران از آنچه توسط Gemini CLI اجرا خواهد شد، آگاه هستند. در ادامه آموزش، همیشه میتوانید آن را مجاز کنید (گزینه ۲).
این افزونه یک فرآیند طولانی مدت را فراخوانی میکند، میتوانید ببینید که یک فایل برنامهریزی در داخل دایرکتوری .gemini_security ایجاد میکند و میتوانید چک لیستی را ببینید که نشان میدهد کدام فرآیند انجام شده است یا خیر. همانطور که در مثال زیر نشان داده شده است:
مدتی طول میکشد تا وظایفش تمام شود، در این مدت میتوانیم منبع این افزونهها را در مخزن گیتهاب بررسی کنیم. این URL نشاندهندهی اعلانی است که برای اجرای تمام این فرآیندهای اسکن امنیتی استفاده میشود.
همانطور که در آنجا میبینید، برای انجام این اسکن، باید از طریق رابط خط فرمان Gemini، بررسی دو مرحلهای، مرحله شناسایی و مرحله تحقیقات دقیقتر را انجام دهید.
اگر در رابط خط فرمان Gemini با پیام زیر مواجه شدید، میتوانید گزینه ۲ را برای غیرفعال کردن تشخیص حلقه انتخاب کنید.
Then prompt the Gemini CLI to continue
continue
این مکانیزمی برای جلوگیری از حلقههای فراخوانی ابزار بینهایت و غیرمولد است و به مرور زمان بهبود خواهد یافت.
پس از اتمام، گزارش در ترمینال تعاملی نمایش داده میشود، برای آسانتر کردن این کار، بیایید به Gemini CLI دستور دهیم که آن را در security-analysis.md بنویسد.
write the result to security-analysis.md file
حالا میتوانید نتیجهی نوشته شده روی فایل را بررسی کنید.
۷. 🚀 حالت غیرتعاملی - برنامه افزونه بررسی کد
افزونهی code-review دستور جدیدی را به رابط خط فرمان Gemini اضافه میکند که تغییرات کد را برای شناسایی انواع مشکلات کیفیت کد، تجزیه و تحلیل میکند.
This extension can be executed in Gemini CLI non-interactive mode, meaning that all of the process can be executed without the need to enter Gemini CLI shell. To run Gemini CLI in non-interactive mode you can do it with the following command pattern
gemini -p "put your command here"
However, it's important to be noted that, running in non-interactive mode will disable any tools operation which will require user permission, hence we need to add the --yolo flag to auto approve all actions which means enabling all tools during the non-interactive mode
اگر این پرچم yolo را در cloudshell اجرا کنید، پیکربندی پیشفرض سیستم شما را از اجرای آن منع کرده و این پیام خطا را نشان میدهد.
Cannot start in YOLO mode when it is disabled by settings
دستور زیر را برای تنظیم فایل پیکربندی سطح فضای کاری اجرا کنید
mkdir .gemini && cloudshell edit .gemini/settings.json
اکنون، فایل settings.json در ویرایشگر باز میشود، پیکربندی زیر را برای فعال کردن حالت yolo کپی کنید.
{
"security": {
"disableYoloMode": false
}
}
حالا، بیایید افزونهی code-review را با دستور زیر اجرا کنیم
gemini -p "activate the code review skill and review code changes in current branch, then write the result to code-review.md" --yolo -e code-review
This command will activate the skill included in code-review extension and write the result of the Gemini CLI output into the code-review.md file. Note the -e flag here, this flag controls which extension to activate during the session. Here we only activate the code-review extension and disable the others.
مدتی طول خواهد کشید، اما پس از اتمام، میتوانید نتیجهای مشابه آنچه در زیر نشان داده شده است را که در فایل 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.
۸. 🚀 پشتیبانی از پروتکل زمینه مدل
Now, as we inspected before in the extension explanations, the Gemini CLI can connect to MCP servers—applications that provide tools and resources through the Model Context Protocol. This connection allows the Gemini CLI to interact with external systems and data sources by using MCP servers as bridges to your local environment and external services like APIs.
اگر میخواهید سرور 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 خود را دارید.
Login to your Github and go to Settings
پس از آن، به پایین اسکرول کنید تا تنظیمات توسعهدهنده (Developer settings) را پیدا کنید و روی آن کلیک کنید.
سپس روی نشانههای دسترسی شخصی کلیک کنید و توکنها (کلاسیک) را انتخاب کنید.
نام توکن دسترسی شخصی خود را اینجا وارد کنید و محدودههای مخزن را بررسی کنید
سپس به پایین اسکرول کنید و روی دکمهی Generate Token کلیک کنید، مطمئن شوید که
روی دکمهی «ایجاد توکن جدید» کلیک کنید و گزینهی «ایجاد توکن جدید (کلاسیک) » را انتخاب کنید. پس از آن، توکن تولید شده را کپی کرده و در فایل .gemini/settings.json بنویسید.
بنابراین، فایل .gemini/settings.json شما باید مانند مثال زیر باشد.
{
"mcpServers": {
"github": {
"httpUrl": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "ghp-xxxx"
},
"timeout": 5000
}
}
}
Now, let's verify the connection. Enter the Gemini CLI by running this command
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
Note the @code-review.md and @security-analysis.md notation here, this is how we reference files to be passed to Gemini CLI. This command will read content of both files and push a comment to the Pull Request related to this branch using the Github MCP connection. After that you can check in the pull request URL to verify it.
9. 💡Gemini CLI in CI/CD Workflow
If you are a Github user, you can easily embed Gemini CLI in your CI/CD pipeline by utilizing run-gemini-cli Github Action. It acts both as an autonomous agent for critical routine coding tasks, and an on-demand collaborator you can quickly delegate work to
شما میتوانید از آن برای انجام بررسی درخواستهای pull، بررسی مشکلات، انجام تجزیه و تحلیل و اصلاح کد و موارد دیگر با استفاده از Gemini به صورت مکالمهای مستقیماً در مخازن Github استفاده کنید.
The example of this integration can be inspected in this pull request , where we utilize the Gemini CLI Security extension inside the runner and give the reviews when the Pull Request is created
۱۰. 💡سایر افزونههای خط فرمان Gemini را بررسی کنید
همچنین میتوانید افزونههای بیشتری را در https://geminicli.com/extensions بررسی کنید. برای ابزارهای جالبتر، آن را بررسی کنید!
۱۱. 🧹 تمیز کردن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این codelab، این مراحل را دنبال کنید:
- در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
- در لیست پروژهها، پروژهای را که میخواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
- در کادر محاورهای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.