مراقب سلسلة التوريد

مراقبة آلية لأفضل حزم PyPI و npm للكشف عن اختراقات سلسلة التوريد. يقوم باستقصاء كلا السجلين للإصدارات الجديدة، ويقارن كل إصدار بسابقه، ويستخدم نموذج لغة كبير (عبر Cursor Agent CLI) لتصنيف الفروقات على أنها حميدة أو ضارة. تؤدي النتائج الضارة إلى إطلاق تنبيه عبر Slack.

يتم مراقبة كلا النظامين البيئيين افتراضيًا. استخدم --no-pypi أو --no-npm لتعطيل أحدهما.

كيف يعمل

كل نظام بيئي يشغل خيط استقصاء خاص به، لكنه يشارك في خط التحليل والتنبيه.

         ┌─── PyPI ──────────────────────┐   ┌─── npm ───────────────────────┐
         │                               │   │                               │
         │ changelog_since_serial()      │   │ CouchDB _changes feed         │
         │       │                       │   │       │                       │
         │       ▼                       │   │       ▼                       │
         │  ┌────────────┐               │   │  ┌────────────┐               │
         │  │ All PyPI   │─┐             │   │  │ All npm    │─┐             │
         │  │ events     │ │             │   │  │ changes    │ │             │
         │  └────────────┘ ▼             │   │  └────────────┘ ▼             │
         │ hugovk ──► Watchlist          │   │ download-counts ─► Watchlist  │
         │       │                       │   │       │                       │
         │ "new release" events only     │   │ new versions since last epoch │
         └───────────────┬───────────────┘   └───────────────┬───────────────┘
                         │                                   │
                         ▼                                   ▼
               ┌───────────────────┐               ┌───────────────────┐
               │ Download old + new│               │ Download old + new│
               │ (sdist + wheel)   │               │ (tarball)         │
               └───────────────────┘               └───────────────────┘
                         │                                   │
                         └─────────────────┬─────────────────┘
                                           ▼
                                   ┌───────────────┐
                                   │ Unified diff  │
                                   │ report (.md)  │
                                   └───────┬───────┘
                                           ▼
                                   ┌───────────────┐  ◄── LLM analysis
                                   │ Cursor Agent  │      (read-only)
                                   │ CLI (ask mode)│
                                   └───────┬───────┘
                                           │
                                       verdict?
                                           │
                                 malicious │
                                           ▼
                                   ┌───────────────┐
                                   │ Slack alert   │
                                   └───────────────┘

أهداف الكشف

يتم توجيه تحليل LLM للبحث عن:

• كود مبهم (base64، exec، eval، XOR، سلاسل مشفرة)
• استدعاءات شبكة لمضيفين غير متوقعين
• كتابات في نظام الملفات إلى مواقع بدء التشغيل/الاستمرار
• إنشاء عمليات وأوامر شل
• إخفاء المعلومات أو إخفاء البيانات في ملفات الوسائط
• سرقة بيانات الاعتماد والرموز المميزة
• مؤشرات انتحال اسم الحزمة

المتطلبات الأساسية

• Python 3.9+ — قم بتثبيت تبعيات التشغيل باستخدام pip install -r requirements.txt (تغطي المكتبة القياسية معظم الأداة؛ requests تُستخدم لرفع الملفات إلى Slack)
• Cursor Agent CLI — الملف الثنائي المستقل agent، وليس IDE

تثبيت Cursor Agent CLI

ويندوز (PowerShell):

irm 'https://cursor.com/install?win32=true' | iex

macOS / Linux:

curl https://cursor.com/install -fsS | bash

تحقق من التثبيت باستخدام:

agent --version

يجب أن تكون مصادقًا لدى Cursor (agent login أو قم بتعيين CURSOR_API_KEY).

تكوين Slack

ضع رمز bot الخاص بـ Slack في etc/slack.json:

{
    "url": "https://hooks.slack.com/services/...",
    "bot_token": "xoxb-...",
    "channel": "C01XXXXXXXX"
}

يحتاج bot إلى نطاق chat:write على القناة المستهدفة. حقل channel هو معرف قناة Slack حيث تُنشر التنبيهات.

بداية سريعة

# تشغيل لمرة واحدة: تحليل الإصدارات من آخر 10 دقائق تقريبًا
python monitor.py --once

# تشغيل مستمر: مراقبة أفضل 1000 حزمة (كلا النظامين البيئيين)، استقصاء كل 5 دقائق
python monitor.py --top 1000 --interval 300

# إنتاجي: مراقبة أفضل 15000، تنبيه إلى Slack
python monitor.py --top 15000 --interval 300 --slack

# npm فقط، أفضل 5000
python monitor.py --no-pypi --npm-top 5000

# PyPI فقط
python monitor.py --no-npm

نظرة عامة على الملفات

الملف	الغرض
monitor.py	المنسق الرئيسي — استقصاء PyPI + npm، مقارنة، تحليل، تنبيه (خيوط متوازية)
pypi_monitor.py	مستقصي سجل تغييرات PyPI المستقل (يُستخدم للاستكشاف)
package_diff.py	تنزيل ومقارنة نسختين من أي حزمة PyPI أو npm
analyze_diff.py	إرسال الفرق إلى Cursor Agent CLI، تحليل الحكم
top_pypi_packages.py	جلب وعرض أفضل N من حزم PyPI حسب عدد التحميلات
slack.py	عميل API Slack (إرسال رسالة، رفع ملف)
etc/slack.json	بيانات اعتماد Bot Slack
last_serial.yaml	حالة الاستقصاء المحفوظة (تسلسل PyPI + تسلسل/عصر npm)
logs/	ملفات سجل يومية (monitor_YYYYMMDD.log)

تفاصيل الاستخدام

monitor.py — المنسق الرئيسي

python monitor.py [OPTIONS]

الخيارات:
  --top N          عدد أفضل الحزم المراقبة لكل نظام بيئي (الافتراضي: 15000)
  --interval SECS  فترة الاستقصاء بالثواني (الافتراضي: 300)
  --once           تشغيل لمرة واحدة على الأحداث الأخيرة، ثم الخروج
  --slack          تفعيل تنبيهات Slack للنتائج الضارة
  --model MODEL    تجاوز نموذج LLM (الافتراضي: composer-2-fast)
  --debug          تفعيل تسجيل DEBUG (يشمل المخرجات الأولية للوكيل)

خيارات PyPI:
  --no-pypi        تعطيل مراقبة PyPI
  --serial N       تسلسل سجل PyPI للبدء منه

خيارات npm:
  --no-npm         تعطيل مراقبة npm
  --npm-top N      أفضل N من حزم npm للمراقبة (الافتراضي: نفس --top)
  --npm-seq N      تسلسل تكرار npm للبدء منه

يعمل كل من PyPI و npm في خيط استقصاء خاص به. يتم حفظ حالة الاستقصاء (تسلسل PyPI، تسلسل + عصر npm) في last_serial.yaml حتى يستأنف المراقب من حيث توقف بعد إعادة التشغيل.

خط أنابيب PyPI:

1. يقوم بتحميل أفضل N من الحزم من مجموعة بيانات hugovk/top-pypi-packages كقائمة مراقبة
2. يتصل بواجهة XML-RPC الخاصة بـ PyPI ويحصل على الرقم التسلسلي الحالي
3. كل --interval ثانية، يستدعي changelog_since_serial() — استدعاء API واحد يعيد جميع الأحداث منذ آخر فحص
4. يقوم بالتصفية لأحداث "new release" المطابقة لقائمة المراقبة
5. لكل إصدار جديد: يقوم بتنزيل النسخ القديمة والجديدة (sdist و wheel عندما يكونان موجودين)، يقارن، يحلل عبر LLM، وينبه Slack إذا كان ضارًا

خط أنابيب npm:

1. يقوم بتحميل أفضل N من الحزم من مجموعة بيانات download-counts (يتراجع إلى واجهة بحث npm)
2. يقرأ تسلسل تكرار CouchDB الحالي من replicate.npmjs.com
3. كل --interval ثانية، يجلب خلاصة _changes لجميع تغييرات السجل منذ آخر تسلسل
4. يقوم بتصفية الحزم المتغيرة مقابل قائمة المراقبة ويتحقق من الإصدارات المنشورة بعد آخر عصر استقصاء
5. لكل إصدار جديد: يقوم بتنزيل التاربول القديم والجديد من سجل npm، يقارن، يحلل عبر LLM، وينبه Slack إذا كان ضارًا

يتم تسجيل جميع المخرجات في كل من وحدة التحكم و logs/monitor_YYYYMMDD.log.

package_diff.py — مقارن الحزم

# مقارنة نسختين من PyPI
python package_diff.py requests 2.31.0 2.32.0

# مقارنة نسختين من npm
python package_diff.py --npm express 4.18.2 4.19.0

# حفظ في ملف
python package_diff.py telnyx 2.0.0 2.1.0 -o telnyx_diff.md

# مقارنة أرشيفات محلية
python package_diff.py --local old.tar.gz new.tar.gz -n mypackage