BotDetect v2 — مكتبة كشف البوتات للبيئات الإنتاجية

مكتبة كشف البوتات والأتمتة من جانب العميل مع نظام تسجيل مرجح، وتحليل سلوكي، وبصمة متصفح، وعتبات قابلة للتكوين. تكتشف المتصفحات عديمة الرأس، وسيلينيوم، وبابيتير، وبلاي رايت، والأدوات القائمة على بروتوكول CDP، وأطر الأتمتة الخفية.

الإصدار v2.1.0 — مصائد مضادة للاكتشاف، بصمة كانفاس مستقرة لبطاقة الرسوميات GPU، تحليل سلوكي محسّن، تهيئة كسولة، كشف التلاعب من جانب الخادم، ربط بصمة الطلب، وتحديد معدل الطلبات.

---

جدول المحتويات

• الميزات
• الهندسة المعمارية
• البدء السريع
• واجهة برمجة التطبيقات من جانب العميل
• التكامل من جانب الخادم
• وحدات الكشف
• التكوين
• قائمة التحقق للإنتاج
• الاختبار

---

الميزات

• 28 وحدة كشف تغطي أطر الأتمتة، والمتصفحات عديمة الرأس، والبصمة، والتحليل السلوكي، والمصائد، ومصائد تتبع مكدس الاستدعاءات
• نظام تسجيل مرجح — لكل إشارة وزن قابل للتكوين؛ النتيجة النهائية تُحسب من جانب الخادم
• ثلاثة مستويات حكم: human (بشري)، suspicious (مريب)، bot (بوت) مع إجراءات احتكاك مقابلة (monitor مراقبة، challenge تحدٍ، block حظر)
• التحقق من جانب الخادم — مقيد بـ nonce، محمي من إعادة التشغيل، موقع بإثبات العمل
• مصائد تتبع مكدس الاستدعاءات — تزييد واجهات برمجة تطبيقات DOM لالتقاط مكدسات استدعاء أدوات الأتمتة
• التحليل السلوكي — انحناء الماوس، تباين توقيت ضغطات المفاتيح، تسارع التمرير، ديناميكيات اللمس
• مصائد مضادة للاكتشاف — إخفاء عشوائي عبر CSS، حقول خادعة، أسماء حقول واقعية
• كشف التلاعب من جانب الخادم — يتحقق من سلامة الإشارة، ويكشف محاولات التلاعب
• ربط بصمة الطلب — ربط رموز إثبات العمل بخصائص طلب HTTP
• تحديد معدل الطلبات — تحديد المعدل لكل جلسة على جميع نقاط التحقق
• كشف عدم وجود سكريبت — يحدد العملاء الذين لا يرسلون حمولات الكشف مطلقًا
• قائمة مسموح بها للزواحف المعروفة — أكثر من 20 بوتًا شرعيًا مستبعدًا من التسجيل

---

الهندسة المعمارية

Browser                                  Your Server
┌──────────────────────────┐            ┌──────────────────────┐
│ Collector (singleton)    │  POST      │ Express Middleware    │
│  ├─ 28 detection modules│  signals   │  ├─ NonceManager      │
│  ├─ BehaviorTracker     │  + nonce   │  ├─ RateLimiter       │
│  ├─ HoneypotTraps       │───────────▶│  ├─ TamperDetector    │
│  ├─ Stack trace traps   │            │  ├─ computeVerdict()  │
│  └─ IframeContext       │            │  └─ Proof-of-Work     │
│                         │  verdict   │                        │
│  ↓ collect() →          │  + proof   │  Returns:             │
│  DetectionResult[]      │◀───────────│  { verdict, score,    │
└──────────────────────────┘            │    confidence, proof, │
                                        │    tamperScore }      │
                                        └──────────────────────┘
                                              │
                                              ▼
                                        Session-gated endpoint
                                        (login, checkout, etc.)
                                        validates proof before
                                        granting access

المبدأ الأساسي: يقوم المتصفح فقط بجمع إشارات DetectionResult[] الأولية. الخادم يحسب الحكم النهائي باستخدام جدول أوزان سري. لا يتم الوثوق أبدًا بالنتائج المحسوبة من جانب العميل.

---

البدء السريع

1. البناء

npm install
npm run build

المخرجات إلى dist/:

• botdetect.min.js (مع polyfills، حوالي 151 كيلوبايت)
• botdetect-clean.min.js (للمتصفحات الحديثة فقط، حوالي 74 كيلوبايت)

2. تضمينه في صفحتك

<script src="/path/to/botdetect.min.js"></script>
<script>
  BotDetect.collector.enableTraps();
  BotDetect.collector.enableBehavioralTracking();
  BotDetect.collector.enableHoneypots();
</script>

3. إعداد التحقق من جانب الخادم

cd server
npm install express cors express-session
node example-integration.js

4. إرسال الإشارات عند إجراء حساس

async function onLogin() {
  const { nonce } = await (await fetch('/api/botdetect/nonce')).json();
  BotDetect.collector.setNonce(nonce);

  const signals = await BotDetect.collector.collect();

  const resp = await fetch('/api/botdetect/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ signals, nonce })
  });
  const { verdict, score, proof, friction } = await resp.json();

  document.getElementById('botdetect-proof').value = proof;
  document.getElementById('login-form').submit();
}

5. التحقق على الخادم

app.post('/api/login', (req, res) => {
  const bd = req.session.botdetect;
  if (!bd) return res.status(403).json({ error: 'no_verification' });
  if (bd.verdict === 'bot') return res.status(403).json({ error: 'access_denied' });
  if (bd.verdict === 'suspicious') return challengeCaptcha(req, res);
  res.json({ success: true });
});

---

واجهة برمجة التطبيقات من جانب العميل

Collector (مفرد)

import Collector from './collector/Collector';
// أو عبر الكائن العام: BotDetect.collector

الطريقة	الإرجاع	الوصف
getInstance(config?)	Collector	الوصول إلى المفرد
configure(config)	void	تحديث الإعدادات وقت التشغيل
getConfig()	CollectorConfig	الإعدادات الحالية
init()	void	تهيئة كسولة للمصائد، التتبع، المصائد الخادعة
enableTraps()	void	تثبيت مصائد تتبع المكدس على واجهات DOM
enableBehavioralTracking()	void	بدء مراقبة الماوس/لوحة المفاتيح/التمرير
enableHoneypots(container?)	void	تثبيت حقول المصائد الخادعة
collect()	Promise<DetectionResult[]>	تشغيل جميع عمليات الكشف
setNonce(nonce)	void	تخزين nonce الصادر من الخادم
getSessionId()	string	معرف جلسة فريد
getFingerprint()	string	تجزئة بصمة الجلسة
resetBehavioralData()	void	مسح البيانات السلوكية
destroy()	void	تنظيف جميع المستمعين وعناصر DOM

Detector (للتصحيح فقط)

import Detector from './detector/Detector';

الطريقة	الإرجاع	الوصف
getInstance(config?)	Detector	الوصول إلى المفرد
configure(config)	void	تحديث الإعدادات
analyze(results)	DetectionVerdict	تسجيل + تصنيف (تصحيح محلي فقط)
handleError(error)	DetectionVerdict	حكم احتياطي عند الفشل

تحذير: يتم تشغيل analyze() بالكامل في المتصفح. لا تستخدم مخرجاته أبدًا في قرارات الإنتاج.

الأنواع

interface DetectionResult {
  name: string;      // اسم الوحدة
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (الأهمية)
  detail?: string;   // وصف قابل للقراءة البشرية
}

interface DetectionVerdict {
  verdict: 'bot' | 'suspicious' | 'human';
  score: number;       // 0.0 – 1.0
  confidence: number;  // 0.0 – 1.0
  signals: DetectionResult[];
  threshold: number;
  friction: 'monitor' | 'challenge' | 'block';
}

interface CollectorConfig {
  detectionTimeoutMs: number;   // مهلة لكل وحدة (الافتراضي: 3000)
  enableTraps: boolean;
  enableBehavioralTracking: boolean;
  enableHoneypots: boolean;
  thresholds: { strict: number; balanced: number; relaxed: number };
}

---

التكامل من جانب الخادم

الوسيط Express

const { createBotDetectEndpoint } = require('./server');