Skip to content

Security: parkerhell008-bit/TelegramBotManager

Security

SECURITY.md

🔐 SECURITY — سیاست امنیتی و گزارش حادثه

آخرین به‌روزرسانی: ۳۰ اکتبر ۲۰۲۶ (۸ آبان ۱۴۰۵) — همگام با نسخه ۲.۴.۱

این سند هم سیاست امنیتی پروژه Bot Pilot (TelegramBotManager) است و هم گزارش رسمی حادثه افشای کلید امضا و اقدامات اصلاحی انجام‌شده.


۱) نحوه گزارش مشکل امنیتی

  • اگر آسیب‌پذیری‌ای در برنامه، Backend یا workflowها پیدا کردید، آن را در Issue عمومی منتشر نکنید.
  • از طریق Issue با برچسب security و توضیح حداقلی (بدون درج توکن/نمونه حساب واقعی) گزارش دهید تا در اسرع وقت پیگیری شود.
  • توکن ربات یا رمز عبوری را در گزارش‌ها، اسکرین‌شات‌ها یا لاگ‌ها قرار ندهید.

۲) حادثه ۲۰۲۶-۱۰-۳۰: افشای کلید امضای Release در مخزن عمومی

شرح حادثه

  • فایل‌های keystore/release.keystore و keystore/keystore.properties (شامل رمزهای متن ساده کلید) از نسخه v1.2.0 تا v2.4.0 به‌صورت عمومی در مخزن قرار داشتند.
  • این کار برای «ثبات امضای آپدیت‌ها» انجام شده بود، اما به این معنا بود که هر بازدیدکننده‌ای می‌توانست کلید و رمز آن را دانلود کند و APK جعلی با همان امضا بسازد.
  • بر اساس اصول مدیریت حادثه، کلید قدیمی لو رفته تلقی و کاملاً بازنشسته (چرخش) شد.

ارزیابی اثر

مورد وضعیت
توکن ربات‌های کاربران لو نرفته — هرگز در مخزن نبود (فقط داخل اپ و رمزنگاری‌شده با Android Keystore)
توکن GitHub کاربران (قابلیت ابری) لو نرفته — فقط داخل اپ رمزنگاری می‌شود
کلید امضای APK لو رفته → باطل و با کلید جدید جایگزین شد
داده‌های کاربران در مخزن وجود نداشت

اقدامات انجام‌شده (فاز ۱ و ۲ بازطراحی)

  1. پاک‌سازی کامل تاریخچه Git — با git filter-repo مسیر keystore/ از همه ۲۷ کامیت و هر ۱۳ تگ (v1.0.0 … v2.4.0) حذف شد. هیچ نسخه‌ای از کلید در تاریخچه مخزن باقی نمانده است. تغییرات با --force به main و همه تگ‌ها push می‌شود.
    • پیش از بازنویسی، بکاپ کامل تاریخچه (mirror) روی دستگاه توسعه نگهداری می‌شود.
    • مخزن تک‌شاخه و تک‌توسعه‌دهنده است؛ بازنویسی تاریخچه برای شاخه‌ها/همکاران اثر جانبی ندارد.
  2. کلید امضای جدید — PKCS12، RSA-4096، اعتبار ۳۰ سال، alias: botpilot. اثر انگشت گواهی (SHA-256) در DEPLOYMENT.md ثبت شده است. کلید فقط در GitHub Secrets و نسخه محلی git-ignored نگهداری می‌شود.
  3. بازنویسی GitHub Secrets — چهار secret امضا (KEYSTORE_BASE64، KEYSTORE_PASSWORD، KEYSTORE_ALIAS، KEY_PASSWORD) با مقدار کلید جدید به‌روزرسانی شدند.
  4. حذف fallback کلید Debug برای Release — پیش‌تر در نبود کلید، نسخه Release با کلید debug امضا می‌شد. اکنون ساخت Release بدون تنظیمات امضای امن با خطای شفاف شکست می‌خورد (نگهبان taskGraph در app/build.gradle.kts).
  5. اصلاح .gitignore — پوشه keystore/، *.keystore، *.jks، *.p12، *.pem، keystore.properties، .env و مشابه آن‌ها برای همیشه از ثبت جلوگیری می‌کنند.
  6. تست‌ها به‌عنوان دروازه انتشار — Unit Testهای واقعی (تقویم جلالی + هسته رمزنگاری بکاپ) به CI اضافه شد؛ workflow انتشار در صورت شکست تست‌ها اصلاً APK نمی‌سازد.
  7. workflow انتشار فقط با Secrets معتبر — پیش از build، وجود هر چهار secret بررسی می‌شود؛ در نبود آن‌ها انتشار متوقف می‌شود.
  8. مستندسازی — DEPLOYMENT.md (فرایند امضا/انتشار/بازیابی) و همین سند.

اسکن Secret در تاریخچه

کل تاریخچه (هر ۲۷ کامیت) با الگوهای زیر اسکن شد:

  • توکن ربات تلگرام (\d+:[A-Za-z0-9_-]{35})
  • PAT کلاسیک گیت‌هاب (ghp_…) و PAT fine-grained (github_pat_…)
  • کلید AWS (AKIA…)، بلوک PRIVATE KEY، الگوی عمومی password/secret=

نتیجه: به‌جز فایل‌های keystore (که حذف شدند) هیچ Secret دیگری در تاریخچه یافت نشد.


۳) ریسک‌های باقی‌مانده و توصیه‌ها (شفاف)

  • کش گیت‌هاب از کامیت‌های یتیم: گیت‌هاب ممکن است تا مدتی کامیت‌های قدیمی بازنویسی‌شده را با SHA مستقیم نگه دارد. اثر عملی آن نزدیک به صفر است (کلید باطل شده)، اما برای پاک‌سازی کامل می‌توانید از GitHub Support بخواهید کامیت‌های یتیم را از کش خارج کند یا موقتاً مخزن را خصوصی کنید.
  • Releaseهای قدیمی (v1.2.0 تا v2.4.0): APKهای منتشرشده قدیمی با کلید لو رفته امضا شده‌اند. این APKها «امنیت جدید» را نقض نمی‌کنند، اما پیشنهاد می‌شود پس از انتشار نسخه جدید، Assetهای قدیمی حذف یا مخزن Releaseها تمیز شود (تصمیم با مالک مخزن).
  • کاربرانی که نسخه قدیمی دارند: با کلید جدید، آپدیت روی نسخه قبلی نصب نمی‌شود؛ مسیر مهاجرت (بکاپ → حذف نصب → نصب → بازیابی) در DEPLOYMENT.md آمده است.
  • توکن CI مخزن: توکن دسترسی محلی/CI که برای push استفاده می‌شد در طول این مأموریت منقضی تشخیص داده شد و باید تعویض شود؛ توکن تازه را هرگز داخل مخزن قرار ندهید.
  • androidx.security:security-crypto:1.1.0-alpha06: نسخه آلفا است؛ در فاز مهاجرت به Backend ابری، جایگزین پایدار برای ذخیره امن توکن‌ها بررسی می‌شود.
  • محدودیت سرویس‌های ابری برای کاربر ایران: Google Cloud Run/Firestore (معماری هدف) به Billing و حساب GCP نیاز دارد و ثبت‌نام مستقیم از ایران ممکن نیست؛ این محدودیت و گزینه‌های جایگزین در فاز طراحی Backend مستند خواهد شد.

۴) قوانین نگهداری Secret (برای همه مشارکت‌کنندگان)

  1. هرگز هیچ کلید امضا، توکن، رمز عبور یا .env را در کد، مستندات، Issue، لاگ یا Commit قرار ندهید.
  2. کلید امضا فقط در GitHub Secrets و روی دستگاه توسعه (git-ignored) زندگی می‌کند.
  3. اگر Secretای به‌اشتباه کامیت شد: فوراً آن را بچرخانید (کلید جدید بسازید)، سپس تاریخچه را پاک کنید — چرخش اول است، پاک‌سازی دوم؛ پاک‌سازی به‌تنهایی کافی نیست.
  4. پیش از هر push، git status را بررسی کنید و مطمئن شوید فایل حساسی stage نشده است.
  5. رمز کلید امضا را در یک مدیر رمز (password manager) نگه دارید و یک نسخه آفلاین خارج از دستگاه داشته باشید؛ بدون رمز، کلید و در نتیجه آپدیت‌های آینده غیرقابل استفاده می‌شوند.

۵) دامنه داده‌ها در نسخه فعلی

  • توکن‌های ربات: فقط روی گوشی کاربر، در EncryptedSharedPreferences با کلید Android Keystore؛ به هیچ سروری ارسال نمی‌شود.
  • بکاپ: فایل تک‌فایلی AES-256-GCM با کلید مشتق‌شده از رمز عبور کاربر (PBKDF2، ۱۵۰ هزار تکرار) — بدون رمز، بازیابی ناممکن است.
  • انتقال: همه ترافیک فقط HTTPS (usesCleartextTraffic=false + network security config).

There aren't any published security advisories