امنیت ربات تلگرام؛ حفاظت از Bot Token و Webhook در عمل

ربات پشتیبانی شرکت ناگهان از طرف شما پیام تبلیغاتی می‌فرستد؛ در همان ساعت، یک Webhook ناشناس در لاگ دیده می‌شود. ممکن است Bot Token در خروجی Debug، اسکرین‌شات تنظیمات یا فایل پشتیبان افشا شده باشد. امنیت ربات تلگرام فقط انتخاب یک آدرس مخفی برای Webhook نیست. کنترل Token، تأیید منشأ درخواست، محدودکردن دسترسی اپراتورها و داشتن برنامه پاسخ به حادثه تعیین می‌کند یک اشتباه کوچک به کنترل کامل ربات تبدیل شود یا نه.

این راهنما با مدل تهدید واقعی پیش می‌رود: چه اطلاعاتی محرمانه‌اند، چه چیزی از سمت Telegram قابل تأیید است، چه خطرهایی از داخل خود ربات می‌آیند و در صورت لو رفتن کلید چگونه سرویس را با کمترین آسیب بازیابی کنیم. اگر به پیاده‌سازی Route و Queue در Laravel نیاز دارید، آموزش Webhook تا اجرای ربات را بخوانید؛ این صفحه به‌طور مستقل روی حفاظت، مجوز و واکنش به نفوذ تمرکز دارد.

مدل تهدید: مهاجم از چه مسیرهایی می‌تواند به ربات برسد؟

مهاجم ممکن است به Bot Token دسترسی پیدا کند، یک درخواست ساختگی به Endpoint عمومی بفرستد، با دسترسی مدیریتی بیش از حد تنظیمات را تغییر دهد یا از یک دستور ربات که مجوز را بررسی نمی‌کند سوءاستفاده کند. حتی بدون Token، یک Endpoint بدون احراز اصالت می‌تواند در معرض سیل درخواست، پیام جعلی یا آلودگی صف قرار بگیرد. در مقابل، فاش‌شدن Bot Token به معنای دسترسی خودکار به تمامی حساب‌های تلگرام کاربران نیست؛ دامنه خطر همان اختیارات Bot API و منطق سرور شماست.

دارایی	ریسک اصلی	کنترل پیشگیرانه	نشانه برای تشخیص
Bot Token	فراخوانی Bot API و تغییر برخی تنظیمات توسط فرد غیرمجاز	Secret Manager، حداقل دسترسی، چرخش کلید	تغییر Webhook یا پیام‌های غیرمنتظره
Webhook ورودی	ارسال رویداد جعلی یا Flood	TLS، Secret Header، کنترل نرخ و اندازه	افزایش 403، Payload نامعتبر و 429
داده Chat	افشای متن پیام یا شناسه کاربر	نگهداری حداقلی، حذف دوره‌ای و کنترل مشاهده	خواندن یا خروجی‌گرفتن غیرعادی
پنل ادمین	تغییر مقصد تحویل یا مجوز ربات	RBAC، MFA، ثبت رویداد حسابرسی	تغییر تنظیمات بدون تیکت یا تأیید
Callback مشتری	SSRF یا تحویل به مقصد ناخواسته	مقصد تأییدشده، کنترل Redirect و IP	درخواست به نشانی داخلی یا غیرمجاز

Bot Token را در کجا و چگونه نگه داریم؟

توکنِ صادرشده از @BotFather یک Secret عملیاتی است. نباید در Git، JavaScript، HTML، Screenshot، Ticket عمومی یا تاریخچه Shell قرار بگیرد. در برنامه Laravel آن را در محیط امن سرور نگه دارید و از طریق config() بخوانید؛ روی سرورهای بزرگ‌تر، Secret Manager و دسترسی سرویس‌به‌سرویس مدیریت را ساده‌تر می‌کنند.

# Secret value is intentionally NOT shown.
TELEGRAM_BOT_TOKEN=replace-with-private-value
TELEGRAM_WEBHOOK_SECRET=replace-with-independent-secret

برای ابزارهای مانیتورینگ و گزارش خطا، الگوی Redaction تعریف کنید تا بخش Bot Token که در URL متدهای Bot API قرار می‌گیرد ذخیره نشود. برای مثال درخواست به https://api.telegram.org/bot[TOKEN]/sendMessage حاوی Token در مسیر است؛ ثبت URL کامل بدون پاک‌سازی می‌تواند آن را افشا کند.

آیا .env به‌تنهایی کافی است؟

فایل محیطی یک محل متعارف پیکربندی است، اما تضمین امنیت نیست. مجوز فایل، سطح دسترسی Worker، نبودن در پوشه Public، نسخه پشتیبان، خروجی phpinfo() و نحوه ثبت Crash هم اهمیت دارند. اگر چند تیم به یک سرور مشترک SSH دارند، مدیریت جداگانه Secret و کاهش دسترسی سیستم‌عامل لازم است.

Webhook تلگرام را واقعاً چگونه اعتبارسنجی کنیم؟

طبق مستندات رسمی Telegram Bot API، هنگام ثبت Webhook می‌توان secret_token مستقل تعیین کرد. تلگرام این مقدار را در Header با نام X-Telegram-Bot-Api-Secret-Token به مقصد می‌فرستد. گیرنده باید وجود و مقدار آن را با مقایسه زمان‌ثابت بررسی کند. این Header امضای رمزنگاری‌شده محتوای درخواست نیست؛ TLS و حفاظت Secret ضروری‌اند.

$expected = (string) config('services.telegram.webhook_secret');
$received = (string) $request->header('X-Telegram-Bot-Api-Secret-Token', '');
if ($expected === '' || ! hash_equals($expected, $received)) {
    return response()->json(['ok' => false], 403);
}
// Validate payload shape and persist unique (bot_id, update_id) next.

این قطعه فقط بخش اعتبارسنجی است؛ تعریف Route و مدل پایگاه‌داده را باید جدا پیاده کرد. برای جلوگیری از ورود دوباره، شناسه update_id را با شناسه همان Bot ذخیره کنید. دریافت تکراری Update همیشه حمله نیست: در قطع اتصال، تلاش دوباره تحویل ممکن است رفتار طبیعی باشد.

آیا IP Allowlist جایگزین Secret می‌شود؟

خیر. محدودکردن شبکه می‌تواند لایه مکمل باشد، اما فهرست IPها و مسیرهای Proxy ممکن است تغییر کنند. وقتی پشت CDN یا Reverse Proxy هستید، نباید بدون پیکربندی Trusted Proxy به سربرگ‌هایی مثل X-Forwarded-For که از اینترنت می‌آیند اعتماد کنید. Secret، محدودیت اندازه درخواست و Logging امن را مستقل نگه دارید.

Webhook جعلی، Replay و Flood را چگونه مهار کنیم؟

قبل از قرار دادن رویداد در Queue، نوع داده، اندازه Payload و وجود شناسه معتبر را بررسی کنید. از محدودسازی تعداد درخواست در Edge یا Route استفاده کنید، اما آستانه را چنان تنظیم نکنید که هنگام دریافت قانونی انبوه Updateها از تلگرام، پیام‌های معتبر نیز بدون برنامه از بین بروند. درخواست تکراری را با کلید یکتای (bot_id, update_id) شناسایی کنید و برای پردازش‌های پرهزینه سهمیه مستقلی داشته باشید.

اگر سرویس مرکزی رویداد را دوباره به پروژه مصرف‌کننده تحویل می‌دهد، سازوکار تحویل آن ممکن است از HMAC روی بدنه و Timestamp استفاده کند؛ این قرارداد با Secret Header اصلی Telegram متفاوت است. بررسی HMAC فقط زمانی درست است که نحوه ساخت رشته امضا، نام Header و پنجره زمانی دقیقاً با مستندات فرستنده یکسان باشد.

محدودکردن دستورهای مدیریتی؛ Chat ID مجوز نیست

اگر ربات فرمان‌هایی مثل مشاهده سفارش، تغییر وضعیت پشتیبانی یا اجرای Job دارد، فقط با دیدن chat_id نباید اجازه بدهید. هویت و نقش باید به داده قابل اعتماد برنامه متصل شود؛ شناسه تلگرام به‌تنهایی سیاست مجوز را تعریف نمی‌کند. برای عملیات حساس، تأیید اضافی در پنل سازمان، ثبت لاگ حسابرسی و جداسازی محیط آزمایشی از Production مناسب است.

فرمان	حداقل نقش	کنترل تکمیلی
مشاهده وضعیت سرویس	مشاهده‌گر همان پروژه	حذف داده حساس از پاسخ
مشاهده اطلاعات سفارش	اپراتور مجاز همان شرکت	بررسی Tenant و مالکیت سفارش
تغییر تنظیم Webhook	مدیر فنی تأییدشده	MFA و ثبت تغییرات
چرخش Token	مالک یا مسئول امنیت	دو مرحله تأیید و برنامه بازگشت

اگر چند ربات و چند شرکت دارید، دسترسی مدیر یک شرکت نباید با تغییر پارامتر شناسه بتواند تنظیم Bot دیگری را بخواند. این خطر از جنس Broken Object Level Authorization است و باید در Backend با Policy واقعی بررسی شود، نه پنهان‌کردن دکمه‌های UI.

اگر Bot Token افشا شد، چه کار کنیم؟ برنامه ۳۰ دقیقه اول

در حادثه واقعی، سرعت مهم است ولی حذف فوری Logها یا تغییر کورکورانه تنظیمات ممکن است شواهد را نابود کند. مسئول حادثه را مشخص و زمان کشف، مکان احتمالی افشا و نسخه برنامه را ثبت کنید. سپس در BotFather با حساب مالک، توکن را طبق سازوکار رسمی لغو و جایگزین کنید. Token قدیمی نباید بعد از چرخش در Worker، Cron یا فایل پشتیبان قابل استفاده بماند.

1. مهار: مسیر افشا را محدود کنید؛ دسترسی فایل یا Token چاپ‌شده در Log عمومی را ببندید. پیام‌هایی با محتوای مشکوک را مستند کنید.
2. چرخش: از BotFather توکن جدید دریافت و مقدار را فقط در Secret Store مجاز وارد کنید. چرخش باید با برنامه Restart کنترل‌شده Workerها هماهنگ باشد.
3. بررسی Webhook: با Token تازه، getWebhookInfo را از محیط امن بخوانید و آدرس ثبت‌شده و خطاهای تحویل را با انتظار خود مقایسه کنید. اگر مقصد ناشناس ثبت شده، اصلاح آن نیازمند تصمیم حادثه است.
4. پاک‌سازی آثار: اگر Token در مخزن، لاگ، CI یا تیکت کپی شده، دسترسی به نسخه‌های دارای Secret را محدود و آثار را مطابق سیاست امنیتی اصلاح کنید. حذف یک Commit از تاریخچه همه نسخه‌ها را پاک نمی‌کند.
5. بازبینی مجوز: مدیران پنل و دسترسی SSH یا CI را بررسی کنید و مسیر افشا را اصلاح کنید.
6. بازیابی و پایش: دریافت Update، ارسال پیام آزمایشی و وضعیت Queue را جدا تأیید و برای چند ساعت خطاهای غیرعادی را رصد کنید.

اگر آسیب به حساب یا داده مشتری محتمل است، تیم امنیت و مسئول حقوقی سازمان باید درباره اطلاع‌رسانی و نگهداری شواهد تصمیم بگیرند. هدف چرخش صرف، حذف همه پیامدهای سوءاستفاده احتمالی نیست.

Log و مانیتورینگ امنیتی ربات باید چه چیزهایی را نشان دهند؟

به جای ثبت متن کامل همه پیام‌ها، شناسه داخلی رویداد، Bot، پروژه، زمان، نوع خطا، نتیجه اعتبارسنجی و مدت پردازش را نگه دارید. برای هشدار، جهش غیرعادی HTTP 403، تغییر آدرس Callback، نرخ بالا و پیوسته 429 از Bot API، ورود مدیر ناشناس و شکست مداوم ارسال را در نظر بگیرید. خود این رویدادها به‌تنهایی اثبات نفوذ نیستند؛ برای کاهش هشدار کاذب نیاز به هم‌بستگی شواهد دارید.

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

کنترل مقصد Webhook در معماری چندرباتی و خطر SSRF

اگر کاربر پنل مرکزی می‌تواند URL مقصد تحویل رویداد را تغییر دهد، سرور نباید بدون اعتبارسنجی هر نشانی دلخواه را فراخوانی کند. درخواست به نشانی‌های داخلی، دامنه دارای Redirect به شبکه خصوصی یا Metadata Service می‌تواند به SSRF تبدیل شود. بهتر است URL مقصد فقط HTTPS معتبر و دامنه‌های تأییدشده باشد، DNS در زمان اتصال دوباره بررسی شود و Redirect به مقصد نامجاز مسدود گردد. راهنمای OWASP برای پیشگیری از SSRF جزئیات طراحی را پوشش می‌دهد.

برای چند Tenant، هر Bot و هر Endpoint باید مالک مشخص و مجوز مستقل داشته باشند. روش معماری و صف جداگانه را در مقاله مدیریت چند ربات در پنل مرکزی شرح داده‌ایم؛ اینجا اولویت با کنترل حمله و چرخش Secret است.

نقش Avaztek Telegram در طراحی امن مسیر تحویل

Avaztek Telegram طبق معرفی محصول، هسته‌ای برای دریافت Webhook، تفکیک Bot و شرکت، ثبت رویداد، صف و Retry و تحویل امضاشده به سرویس مصرف‌کننده است. این جداسازی می‌تواند مدیریت مسیرهای مشترک را منظم‌تر کند، ولی به‌طور خودکار تمام خطرهای Token، مجوز ادمین یا ضعف منطق ربات را رفع نمی‌کند.

اگر پروژه Laravel دارید، قرارداد دقیق امضا و اعتبارسنجی را از مستندات SDK بخوانید. برای بررسی نیاز امنیتی و اتصال چند ربات، از فرم درخواست فنی سامانه تلگرام استفاده کنید؛ Token واقعی را در فرم تماس وارد نکنید.

چک‌لیست امنیت ربات پیش از انتشار Production

• Bot Token و Webhook Secret دو مقدار مستقل‌اند و فقط Backend به آن‌ها دسترسی دارد.
• Webhook از HTTPS معتبر، Secret Header و محدودسازی درخواست استفاده می‌کند.
• بدنه Update از نظر حجم و شکل داده بررسی و با کلید یکتا ثبت می‌شود.
• نقش‌ها و مالکیت Tenant در خود Backend اعتبارسنجی می‌شوند.
• URL Callback قابل تبدیل به نشانی شبکه داخلی یا مقصد دلخواه نیست.
• Log و Error Tracking اطلاعات محرمانه را حذف یا پوشانده‌اند.
• روش چرخش Token، توقف Worker و آزمون بازیابی مستند شده است.
• مدیران پنل با احراز هویت قوی و تاریخچه تغییر تنظیمات کار می‌کنند.

پرسش‌های متداول امنیت Bot Token و Webhook

اگر Bot Token تلگرام لو برود، آیا باید ربات را حذف کنیم؟

معمولاً ابتدا باید توکن را از BotFather لغو و جایگزین کرد، مسیر افشا را بست و وضعیت Webhook و رخدادهای مشکوک را بررسی کرد. حذف ربات بدون ارزیابی حادثه راهکار پیش‌فرض نیست.

آیا آدرس طولانی و ناشناخته Webhook برای امنیت کافی است؟

خیر. URL مخفی ممکن است در Log و تنظیمات افشا شود. HTTPS، Secret Header، محدودیت درخواست و مجوز Backend لازم‌اند.

تفاوت secret_token و HMAC در Telegram چیست؟

secret_token تلگرام مقدار ثابتی است که در Header به مقصد می‌رسد. HMAC بدنه معمولاً سازوکار جداگانه بین دو سامانه است. این دو نباید به جای یکدیگر به کار روند.

آیا می‌توان Bot Token را به ادمین پشتیبانی نشان داد؟

در حالت معمول نیازی نیست. اپراتور می‌تواند وضعیت رویداد و خطای پاک‌سازی‌شده را ببیند؛ مشاهده یا چرخش Secret باید به نقش محدود و ثبت‌شده سپرده شود.

چرا با وجود بررسی Secret هنوز Update تکراری دریافت می‌کنیم؟

ممکن است Telegram در قطع ارتباط درخواست را دوباره تحویل دهد یا فرایند داخلی Retry کرده باشد. با کلید یکتا و پردازش Idempotent این وضعیت را مهار کنید؛ تکرار لزوماً حمله نیست.

آیا Avaztek Telegram جای بررسی امنیت ربات را می‌گیرد؟

خیر. هسته تحویل مرکزی بخشی از مسئولیت اتصال را پوشش می‌دهد، اما نگهداری امن توکن، مجوز دستورات و حفاظت داده داخل پروژه نیز ضروری است.

جمع‌بندی: از Token تا نقش اپراتور، امنیت زنجیره‌ای است

امنیت ربات تلگرام با نگهداری Secret شروع می‌شود و تا اعتبارسنجی Webhook، تفکیک Tenant، ثبت رویداد و بازیابی پس از حادثه ادامه دارد. برای تیم‌هایی با چند ربات و چند مقصد، Avaztek Telegram یکی از گزینه‌های مدیریت مرکزی مسیر رویداد است؛ وضعیت امنیتی هر پروژه باید با آزمون و قرارداد واقعی سنجیده شود.