118 lines
12 KiB
Markdown
118 lines
12 KiB
Markdown
# مشخصات درس‌نامه: مدیریت Secretها، کلیدهای API و واکنش اضطراری به نشت اطلاعات
|
||
- **شناسه در سیلابس:** `L11.3`
|
||
- **فصل:** فصل ۱۱: امنیت و استفاده مسئولانه (Ch 11)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L11.2` (چک‌لیست پیش از انتشار)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** چرا نشت کلیدهای API در گیت‌هاب کابوس شماره یک توسعه‌دهندگان است و چرا ایجنت‌های هوش مصنوعی مستعد هاردکد کردن تصادفی توکن‌ها در کلاینت هستند.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت پاک کردن یک فایل در کامیت جدید را با پاک کردن کامل آن از تاریخچه عمیق گیت (Git History) درک کرده و ضرورت باطل‌سازی فوری کلیدها را ارزیابی نماید.
|
||
- [ ] **به‌کار ببندد (Apply):** پروتکل ۳ مرحله‌ای واکنش به حادثه امنیتی نشت کلید (Incident Response: باطل‌سازی در پنل $\rightarrow$ صدور کلید جدید $\rightarrow$ پاک‌سازی تاریخچه با ابزارهای خودکار) را اجرا کند.
|
||
- [ ] **ایجاد کند (Create):** یک پرامپت بازرسی امنیتی برای اسکن تمام فایل‌های پروژه تنظیم کند تا ایجنت هرگونه کلید مشکوک، توکن هاردکد شده یا متغیر کلاینتی ناامن را کشف و ایزوله کند.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **کابوس نشت کلید: واقعیتی تلخ در دنیای وایب کدینگ:**
|
||
* چرا هوش مصنوعی گاهی برای سریع‌تر کار کردن، مقادیر کلیدها را مستقیماً داخل کدهای React می‌گذارد؟
|
||
* سرعت باورنکردنی ربات‌های اسکنر: رصد مداوم خروجی گیت‌هاب و خالی کردن شارژ در عرض چند ثانیه.
|
||
2. **سپرهای پیشگیرانه پیش از ارسال کد به گیت‌هاب:**
|
||
* فعال‌سازی قابلیت رایگان GitHub Push Protection (مسدودسازی خودکار پوش در صورت شناسایی کلید).
|
||
* چک‌لیست بازرسی نهایی فایل `.gitignore` برای اطمینان از قرار گرفتن `.env*`.
|
||
3. **پروتکل واکنش اضطراری به حادثه امنیتی (Emergency Protocol):**
|
||
* سناریو: «همین الان ناخواسته فایل `.env.local` را روی گیت‌هاب پوش کردم! چه کنم؟»
|
||
* گام اول (بسیار فوری): متوقف کردن وحشت و ورود به پنل ارائه‌دهنده (OpenRouter, Supabase, Kavenegar) و زدن دکمه Revoke / Delete Key (باطل کردن کلید در کمتر از ۱ دقیقه).
|
||
* گام دوم: ساخت کلید جدید و جایگزینی آن در فایل محلی.
|
||
* گام سوم: چرا کامیت کردن حذف فایل کافی نیست؟ آموزش پاک کردن تاریخچه با کامندهای استاندارد.
|
||
4. **چرخش دوره‌ای کلیدها (Secret Rotation):**
|
||
* استراتژی تعویض دوره‌ای کلیدهای حساس برای حفظ حداکثر امنیت در طول زمان.
|
||
5. **دستورات چندسکویی برای بررسی سریع تاریخچه و فایل‌های پیگیری‌شده:**
|
||
* دستورات گیت برای بررسی اینکه آیا فایلی از نوع `.env` ردیابی شده است یا خیر در سه سیستم‌عامل.
|
||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): نحوه کار ربات‌های ماینر و اسکرپرهای اختصاصی که کلیدهای OpenAI و کلاد را هدف می‌گیرند.
|
||
* کال‌اوت سبز (`<details class="green">`): فعال بودن پیش‌فرض GitHub Secret Scanning در مخازن عمومی.
|
||
* کال‌اوت قرمز (`<details class="red">`): اشتباه مرگبار؛ زدن `git rm .env` و پوش کردن مجدد، کلید را از کامیت‌های قبلی پاک نمی‌کند! تاریخچه گیت ابدی است مگر اینکه بازنویسی شود.
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- استفاده از سیستم‌های سازمانی گاوصندوق سخت‌افزاری مانند HashiCorp Vault یا AWS KMS.
|
||
- مباحث کریپتوگرافی و الگوریتم‌های رمزنگاری متقارن/نامتقارن.
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| Secret Leak | نشت اطلاعات محرمانه | حادثه امنیتی فاش شدن کلیدهای دسترسی، رمزها یا توکن‌ها در مخزن کدهای عمومی |
|
||
| Key Revocation | ابطال فوری کلید | غیرفعال‌سازی آنی کلید از پنل شرکت ارائه‌دهنده برای بی‌اثر کردن دسترسی نفوذگران |
|
||
| Push Protection | محافظت در برابر پوش ناامن | قابلیتی در گیت‌هاب که با شناسایی توکن‌ها مانع از ارسال کامیت حاوی رمز می‌شود |
|
||
| Secret Rotation | چرخش دوره‌ای کلیدها | رویه استاندارد تعویض و صدور مجدد کلیدهای دسترسی در بازه‌های زمانی مشخص |
|
||
| Hardcoded Credentials | اطلاعات هویتی هاردکد شده | نوشتن مستقیم رمز یا توکن در میان خطوط کد به جای خواندن امن آن از متغیرهای محیطی |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** زنگ خطر قرمز امنیتی که کلید شکسته شده‌ای را هشدار می‌دهد و یک دست دیجیتال کلید را ابطال و کلید جدید جایگزین می‌کند.
|
||
2. **سرعت ربات‌های شکارچی کلید در گیت‌هاب:** `images/github-bot-scraping-speed.png`
|
||
* **موضوع:** اینفوگرافیک تایم‌لاین: ثانیه ۱: کامیت اشتباه $\rightarrow$ ثانیه ۳: اسکن توسط ربات نفوذگر $\rightarrow$ ثانیه ۱۰: مصرف اعتبار و ساخت ماشین مجازی غیرمجاز.
|
||
3. **پروتکل ۳ مرحله‌ای نجات در زمان نشت اطلاعات:** `images/incident-response-flow.png`
|
||
* **موضوع:** فلوچارت امداد فوری: ۱) باطل‌سازی آنی در پنل ارائه‌دهنده $\rightarrow$ ۲) صدور کلید جدید $\rightarrow$ ۳) بازنویسی تاریخچه گیت.
|
||
4. **پیام هشدار GitHub Push Protection در ترمینال:** `images/github-push-protection-alert.png`
|
||
* **موضوع:** اسکرین‌شات از مسدود شدن `git push` در ترمینال توسط گیت‌هاب به دلیل وجود کلید مشکوک.
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# مدیریت Secretها، کلیدهای API و واکنش اضطراری به نشت اطلاعات`
|
||
2. **مقدمه:** فاجعه‌ای که در ۳ ثانیه رخ می‌دهد: داستان تلخ برنامه‌نویسانی که بخاطر یک پوش اشتباه، چند هزار دلار بدهی بالا آوردند!
|
||
3. **جدول کاور درس**
|
||
4. **چرا ایجنت‌های هوش مصنوعی مستعد لو دادن کلیدها هستند؟**
|
||
* خطای شایع قرار دادن کلیدها داخل فایل‌های کامپوننت یا ساختن فایل‌های کانفیگ بدون `.gitignore`.
|
||
5. **آزمایشگاه بازرسی پروژه پورتفولیو: شکار کلیدهای هاردکد شده:**
|
||
* جستجوی عباراتی نظیر `sk-`, `eyJh`, `api_key` در سرتاسر کدهای پروژه.
|
||
6. **سپر دفاعی اول: فعال‌سازی Push Protection در گیت‌هاب:**
|
||
* تنظیمات رایگان مخزن در گیت‌هاب برای سد کردن راه پوش‌های خطرناک.
|
||
7. **پروتکل اتاق فرمان در زمان بحران (کارهایی که در ۳ دقیقه اول باید انجام دهید):**
|
||
* گام ۱: ابطال فوری در پنل سوپابیس، کاوه‌نگار یا OpenRouter.
|
||
* گام ۲: تولید کلید جایگزین.
|
||
* گام ۳: پاک کردن ردپای فایل از تاریخچه گیت با ابزار `git filter-repo`.
|
||
8. **جعبه پرامپت طلایی: اسکن امنیتی کل کدهای پروژه با ایجنت:**
|
||
* پرامپت دقیق:
|
||
> «تمام فایل‌های پروژه من را اسکن کن. بررسی کن که آیا هیچ کلید API، رمز عبور یا توکن هاردکد شده‌ای داخل کدهای فرانت‌اند یا کامپوننت‌های کلاینت وجود دارد یا خیر. همچنین بررسی کن که متغیرهای حاوی اطلاعات محرمانه تصادفاً پیشوند `NEXT_PUBLIC_` نگرفته باشند و گزارش کاملی از موارد مشکوک به همراه راهکار اصلاح ارائه بده.»
|
||
9. **دستورات چندسکویی بررسی وضعیت فایل‌های ردیابی‌شده در گیت:**
|
||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||
- Windows (PowerShell):
|
||
```powershell
|
||
git ls-files | Select-String "\.env"
|
||
```
|
||
- macOS (Terminal):
|
||
```bash
|
||
git ls-files | grep "\.env"
|
||
```
|
||
- Linux (Bash):
|
||
```bash
|
||
git ls-files | grep "\.env"
|
||
```
|
||
10. **باکس نکته Quera (`<details class="violet">`):** چرا سطل زباله گیت پاک نمی‌شود؟ مفهوم Commit Tree و دلایل باقی ماندن دیتا در تاریخچه حتی پس از حذف فایل.
|
||
11. **باکس هشدار Quera (`<details class="red">`):** هرگز کلید سوپابیس `service_role` را در پروژه‌های فرانت‌اند استفاده نکنید؛ این کلید شاه‌کلید تمام دیتابیس است!
|
||
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** اجرای موفق اسکن امنیتی و اطمینان از اینکه هیچ کلیدی در کدهای گیت جا نمانده است.
|
||
13. **جمع‌بندی درس‌نامه:** ایمن‌سازی کامل کلیدها؛ ورود به لایه بعدی دفاع: احراز هویت و کنترل دسترسی پیشرفته (Auth & RBAC) در درس بعدی.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] خطرات نشت کلید و سرعت ربات‌های اسکنر به زبان شفاف بیان شود.
|
||
- [ ] پروتکل گام‌به‌گام واکنش اضطراری به نشت کلید ارائه گردد.
|
||
- [ ] روش‌های پیشگیری نظیر GitHub Push Protection و بررسی `.gitignore` تشریح شود.
|
||
- [ ] پرامپت ممیزی امنیتی پروژه توسط ایجنت در متن گنجانده شود.
|