pkgxray — الأمان قبل التثبيت لحزم npm وخوادم MCP ووكلاء الذكاء الاصطناعي

افحص حزمة npm أو خادم MCP قبل تثبيته أو الاتصال به، واحصل على قرار حتمي مدعوم بالأدلة: SAFE أو REVIEW أو BLOCK. تحليل ثابت محلي بلا أي تبعيات — الفحوصات العادية لا تنفّذ كود الحزمة أبدًا.

الموقع · التوثيق · المعايرة · الإبلاغ عن خطأ

_{تشغيلات حقيقية: guard يمرر [email protected]، ثم يحظر عينة مبنية على نموذج اختراق @solana/web3.js لعام 2024.}

أبرز المزايا

• صفر تبعيات وقت التشغيل — Node خالص، يعمل بالكامل على جهازك (مرور ثابت ~25 مللي ثانية).
• الفحوصات العادية لا تنفّذ كود الحزمة أبدًا — يُقرأ ملف tarball كبايتات داخل منطقة العزل.
• قرارات حتمية مُسنَدة — كل اكتشاف يسمّي الملف والدليل؛ لا يوجد LLM في مسار القرار، لذا لا يمكن للنص المحقون توجيهه.
• مصمم لعصر الوكلاء — افحص خوادم MCP قبل الاتصال، وتحكّم في عمليات التثبيت التي ينفذها الوكيل، وأعد تدقيق حركة MCP الحية.
• مُعايَر ومحروس ضد الانحدار — صفر حظر خاطئ قائم على الاستدلال على أكثر 1000 حزمة تنزيلًا، مع فرض ذلك في CI.

1. البدء السريع · 2. ماذا يفحص ويكتشف · 3. القرارات · 4. الاستخدام · 5. التكاملات · 6. كيف يقارن · 7. التوثيق

لماذا

مساعدو البرمجة بالذكاء الاصطناعي يثبّتون الحزم ويتصلون بخوادم MCP بسرعة الآلة، وغالبًا دون أن يقرأ إنسان الكود. حددت Sonatype أكثر من 454,600 حزمة مفتوحة المصدر خبيثة جديدة عبر الأنظمة البيئية المراقبة في 2025، أكثر من 99% منها على npm (Sonatype). npm audit يسأل هل توجد ثغرة CVE معروفة؟؛ بينما يسأل pkgxray أيضًا ماذا يفعل الكود فعليًا — قبل تثبيت أي شيء.

البدء السريع

1. افحص حزمة معروفة بأنها غير ضارة (لا حاجة لتثبيت pkgxray):

npx --yes [email protected] guard npm:[email protected]

يضع ملف tarball في منطقة العزل ويشغّل الفحوصات الثابتة وفحوصات سلسلة التوريد — لا npm install، ولا سكربتات دورة حياة، ولا تنفيذ لأي كود من الحزمة.

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. اقرأ القرار:

SAFE ليس إثباتًا على أن الحزمة غير ضارة؛ فالتحليل الثابت لا يمكنه رؤية حمولة تُنزَّل فقط وقت التشغيل. راجع نموذج التهديدات.

3. شاهد حظر BLOCK على العينة الخاملة المرفقة:

npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown

العينة نص مصدري خامل يحاكي قراءة مفتاح SSH مجزّأ عبر سلاسل نصية وتسريبًا له — لا يُنفَّذ أبدًا. تُرجع BLOCK (رمز الخروج 2) مع الملف والأدلة المُسنَدة.

4. أضِفه إلى سير عملك — إعادة الفحص وCI، وMCP، وبوابة تثبيت Hookshot.

نموذجا تنفيذ. فحوصات guard وaudit الافتراضية ثابتة — لا يُنفَّذ كود الحزمة أبدًا. قد يؤدي تعداد خادم MCP إلى تشغيله، وmcp-proxy يشغّله خلف بوابة؛ وcanary الاختياري هو الاستثناء المتعمد الوحيد الذي ينفّذ الحزمة داخل صندوق رمل لتأكيد السلوك — يمكنه تأكيد الخبث لكنه لا يثبت أبدًا أن الحزمة آمنة. الحدود الكاملة: SECURITY.md.

ماذا يفحص ويكتشف

يفحص — pkgxray guard npm:name@version، وgithub:owner/repo، ودليلًا محليًا، وملفات lock كاملة (npm وyarn وpnpm)، وخوادم MCP، وإضافات وكلاء الذكاء الاصطناعي.

يكتشف — سرقة بيانات الاعتماد (بما في ذلك مسارات التجزئة إلى شظايا)، وحصاد بيانات تعريف المثيلات السحابية ومخازن الأسرار، وحقن المطالبات، وتهريب Unicode، وحمولات base64 ومحمّلات المرحلة الثانية، وتسريب البيانات، والاستمرارية (ملف تعريف الصدفة، ومجدول نظام التشغيل، وسير عمل CI/CD المحقونة)، وبرامج الإسقاط ذاتية الحذف، وتكاثر دودة سجل الحزم (npm publish وقت التثبيت)، وتنفيذ وسيطات محسوبة مبهمة، وثغرات CVE المعروفة (عبر OSV، قبل التنزيل)، وتباين القطع بين npm وGitHub، والتحديثات المسمومة (recheck)، وإساءة استخدام سطح قدرات MCP.

مصفوفة التغطية الكاملة — ونقطة العمى المعروفة للتنزيل اللاحق — موجودة في نموذج التهديدات، ويوجد جدول مقارنة جنبًا إلى جنب على الموقع.

القرارات

رموز الخروج ثابتة ومناسبة لـ CI: 0 آمن/مسموح · 2 حظر · 3 مراجعة.

الاستخدام

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

ملف .pkgxray.json اختياري واحد (تقرؤه جميع الواجهات) يضبط السياسة؛ وغياب الإعدادات يعني أقصى تشدد. لا يمكن أبدًا السماح بتجاوز CVEs، وتُطبع كل عملية تخفيف، والفحص الذي يحدث به خطأ يفشل مغلقًا على review. المخطط والثوابت: configuration.md · .pkgxray.example.json.

التكاملات

محرك واحد خلف كل نقطة دخول. «يعمل مع» تعني دليل إعداد موثّق، وليس تكاملًا معتمدًا من بائع.

كيف يقارن

شغّل pkgxray بجانب npm audit / OSV-Scanner وليس بدلًا منهما — فهما يجيبان عن سؤال "هل توجد ثغرة CVE معروفة؟". وبالمقارنة مع الأدوات في المسار نفسه (الفحص السلوكي لسلسلة التوريد — Socket.dev وOpenSSF Package Analysis وCisco MCP Scanner)، المقارنة الكاملة للقدرات موجودة في docs/comparison.md وعلى الموقع.

الأدلة

معايرة صفر حظر خاطئ قائم على الاستدلال على أكثر 1000 حزمة تنزيلًا محروسة ضد الانحدار في CI (النطاق والمنهجية)، والتشغيلات المنشورة متاحة على pkgxray.ca/stats. هذا الادعاء مقصور على المجموعة الأكثر تثبيتًا — وليس ادعاءً بعدم وجود حظر خاطئ على كل حزمة.

التوثيق

ابدأ من فهرس التوثيق.

المساهمة

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

طلبات السحب مرحّب بها — اقرأ CONTRIBUTING.md وقواعد السلوك. أبلغ عن الثغرات بشكل خاص وفق SECURITY.md. تُنشر الإصدارات على npm مع إثبات المصدر (شهادة SLSA)، مشروطة باجتياز الاختبارات ومعيار المعايرة وحارس سلسلة التوريد الخاص بـ pkgxray.