adamsjack711-ux/pkgxrayأمان ما قبل التثبيت لوكلاء الذكاء الاصطناعي وحزم npm وخوادم MCP. تحليل ساكن محلي بدون تبعيات (Zero-dep)؛ عمليات الفحص العادية لا تنفّذ كود الحزم أبدًا.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — حلّل الحزم قبل تثبيتها" width="820"> # pkgxray — الأمان قبل التثبيت لحزم npm وخوادم MCP ووكلاء الذكاء الاصطناعي افحص حزمة npm أو خادم MCP **قبل** تثبيته أو الاتصال به، واحصل على قرار حتمي مدعوم بالأدلة: `SAFE` أو `REVIEW` أو `BLOCK`. تحليل ثابت محلي بلا أي تبعيات — الفحوصات العادية لا تنفّذ كود الحزمة أبدًا. [](https://www.npmjs.com/package/pkgxray) [](https://www.npmjs.com/package/pkgxray) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml) [](LICENSE) [**الموقع**](https://pkgxray.ca) · [**التوثيق**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**المعايرة**](https://pkgxray.ca/stats) · [**الإبلاغ عن خطأ**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard يمرر [email protected] بقرار SAFE بدرجة A+، ثم يحظر عينة مسمومة بقرار BLOCK بدرجة F مع اكتشاف وصول إلى بيانات الاعتماد بخطورة HIGH" width="820"> <sub>تشغيلات حقيقية: <code>guard</code> يمرر <code>[email protected]</code>، ثم يحظر عينة مبنية على نموذج اختراق <code>@solana/web3.js</code> لعام 2024.</sub> </div> ## أبرز المزايا - **صفر تبعيات وقت التشغيل** — Node خالص، يعمل بالكامل على جهازك (مرور ثابت ~25 مللي ثانية). - **الفحوصات العادية لا تنفّذ كود الحزمة أبدًا** — يُقرأ ملف tarball كبايتات داخل منطقة العزل. - **قرارات حتمية مُسنَدة** — كل اكتشاف يسمّي الملف والدليل؛ لا يوجد LLM في مسار القرار، لذا لا يمكن للنص المحقون توجيهه. - **مصمم لعصر الوكلاء** — افحص خوادم MCP قبل الاتصال، وتحكّم في عمليات التثبيت التي ينفذها الوكيل، وأعد تدقيق حركة MCP الحية. - **مُعايَر ومحروس ضد الانحدار** — صفر حظر خاطئ قائم على الاستدلال على أكثر 1000 حزمة تنزيلًا، مع فرض ذلك في CI. > **[1. البدء السريع](#quick-start)** · [2. ماذا يفحص ويكتشف](#what-it-scans--detects) · [3. القرارات](#verdicts) · [4. الاستخدام](#usage) · [5. التكاملات](#integrations) · [6. كيف يقارن](#how-it-compares) · [7. التوثيق](#documentation) ## لماذا مساعدو البرمجة بالذكاء الاصطناعي يثبّتون الحزم ويتصلون بخوادم MCP بسرعة الآلة، وغالبًا دون أن يقرأ إنسان الكود. حددت Sonatype **أكثر من 454,600 حزمة مفتوحة المصدر خبيثة جديدة عبر الأنظمة البيئية المراقبة في 2025**، أكثر من 99% منها على npm ([Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `npm audit` يسأل *هل توجد ثغرة CVE معروفة؟*؛ بينما يسأل pkgxray أيضًا *ماذا يفعل الكود فعليًا* — قبل تثبيت أي شيء. ## البدء السريع **1. افحص حزمة معروفة بأنها غير ضارة** (لا حاجة لتثبيت pkgxray): ```bash npx --yes [email protected] guard npm:[email protected] ``` يضع ملف tarball في منطقة العزل ويشغّل الفحوصات الثابتة وفحوصات سلسلة التوريد — لا `npm install`، ولا سكربتات دورة حياة، ولا تنفيذ لأي كود من الحزمة. <details> <summary>مخرجات نموذجية</summary> ```text 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) ``` </details> **2. اقرأ القرار:** | القرار | رمز الخروج | المعنى | |---|---:|---| | `SAFE` | `0` | لا توجد مؤشرات عالية أو متوسطة الخطورة؛ السياسة الافتراضية تسمح بالترقية. | | `REVIEW` | `3` | الأدلة غير مكتملة أو قدرة مميزة تتطلب مراجعة بشرية. | | `BLOCK` | `2` | أدلة مُسنَدة عالية الخطورة — ارفض أو حقّق. | `SAFE` ليس إثباتًا على أن الحزمة غير ضارة؛ فالتحليل الثابت لا يمكنه رؤية حمولة تُنزَّل فقط وقت التشغيل. راجع [نموذج التهديدات](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. شاهد حظر BLOCK على العينة الخاملة المرفقة:** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` العينة نص مصدري خامل يحاكي قراءة مفتاح SSH مجزّأ عبر سلاسل نصية وتسريبًا له — **لا يُنفَّذ أبدًا**. تُرجع `BLOCK` (رمز الخروج `2`) مع الملف والأدلة المُسنَدة. **4. أضِفه إلى سير عملك** — [إعادة الفحص وCI](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck)، و[MCP](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#the-pkgxray-mcp-server)، و[بوابة تثبيت Hookshot](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot). > **نموذجا تنفيذ.** فحوصات `guard` و`audit` الافتراضية **ثابتة** — لا يُنفَّذ > كود الحزمة أبدًا. قد يؤدي تعداد خادم MCP إلى تشغيله، و`mcp-proxy` يشغّله خلف > بوابة؛ و[`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) الاختياري هو الاستثناء المتعمد > الوحيد الذي *ينفّذ* الحزمة داخل صندوق رمل لتأكيد السلوك — يمكنه تأكيد الخبث > لكنه لا يثبت أبدًا أن الحزمة آمنة. الحدود الكاملة: > [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## ماذا يفحص ويكتشف **يفحص** — `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. مصفوفة التغطية الكاملة — ونقطة العمى المعروفة للتنزيل اللاحق — موجودة في [نموذج التهديدات](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)، ويوجد جدول مقارنة جنبًا إلى جنب على [الموقع](https://pkgxray.ca/#catches). ## القرارات | القرار | ما يجب عليك فعله | |---|---| | `SAFE` | ثبّت. فقط `safe` يُرفَّع من العزل افتراضيًا. | | `REVIEW` | افحص النسخة المعزولة قبل الترقية. | | `BLOCK` | لا تثبّت. كل اكتشاف يسمّي الملف والدليل. | رموز الخروج ثابتة ومناسبة لـ CI: **`0`** آمن/مسموح · **`2`** حظر · **`3`** مراجعة. ## الاستخدام ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [`.pkgxray.example.json`](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json). ## التكاملات محرك واحد خلف كل نقطة دخول. «يعمل مع» تعني دليل إعداد موثّق، وليس تكاملًا معتمدًا من بائع. | المكان | ماذا يفعل | الدليل | |---|---|---| | وكلاء البرمجة — Codex وClaude Code وCursor وWindsurf | يتحكم في عمليات التثبيت ويعرض أدوات التدقيق على الوكيل | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | عملاء MCP | يفحص الخادم قبل الاتصال؛ ويشغّل pkgxray نفسه كخادم MCP | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | يفشل البناء عندما تتجاوز تبعية ما السياسة | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | بوابة التثبيت — Hookshot | يشغّل `guard` على كل حزمة يحاول وكيل تثبيتها | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | بوابة MCP وقت التشغيل | يمرر خادم MCP حيًا عبر وكيل ويتحكم في كل استدعاء أداة | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | مراقبة التبعيات | يعيد فحص التبعيات المثبتة ويفحص الترقيات مسبقًا وفق جدول | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## كيف يقارن شغّل pkgxray *بجانب* `npm audit` / OSV-Scanner وليس بدلًا منهما — فهما يجيبان عن سؤال *"هل توجد ثغرة CVE معروفة؟"*. وبالمقارنة مع الأدوات في المسار نفسه (الفحص السلوكي لسلسلة التوريد — Socket.dev وOpenSSF Package Analysis وCisco MCP Scanner)، المقارنة الكاملة للقدرات موجودة في [docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) وعلى [الموقع](https://pkgxray.ca/#comparison). ## الأدلة **معايرة صفر حظر خاطئ قائم على الاستدلال على أكثر 1000 حزمة تنزيلًا** محروسة ضد الانحدار في CI ([النطاق والمنهجية](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md))، والتشغيلات المنشورة متاحة على [pkgxray.ca/stats](https://pkgxray.ca/stats). هذا الادعاء مقصور على المجموعة الأكثر تثبيتًا — وليس ادعاءً بعدم وجود حظر خاطئ على كل حزمة. ## التوثيق | المستند | ما يغطيه | |---|---| | [architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md) · [design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md) | خط الأنابيب والواجهات والمبادئ | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | النطاق ونقاط العمى والموقف من حقن المطالبات | | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) · [mcp-registry.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp-registry.md) | فحص MCP والوكيل وقت التشغيل وإدخال السجل | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | أداة الكناري السلوكية الاختيارية | | [configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [reference.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md) | `.pkgxray.json` وسياسة الخطورة و`recheck` وخادم التخزين المؤقت | | [benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md) · [comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) | المعايرة وكيفية المقارنة | | [compatibility.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/compatibility.md) · [json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md) | عقد الإصدار 1.0 ومخطط `--format json` | ابدأ من [فهرس التوثيق](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## المساهمة ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) و[قواعد السلوك](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). أبلغ عن الثغرات بشكل خاص وفق [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md). تُنشر الإصدارات على npm مع إثبات المصدر (شهادة SLSA)، مشروطة باجتياز الاختبارات ومعيار المعايرة وحارس سلسلة التوريد الخاص بـ pkgxray. <div align="center"> <sub>بُني بواسطة <a href="https://github.com/adamsjack711-ux">Jack Adams-Lovell</a> · <a href="https://github.com/adamsjack711-ux/pkgxray/blob/main/LICENSE">MIT</a> · <a href="https://pkgxray.ca">pkgxray.ca</a></sub> </div>
