vexhub

VEX Hub هو مستودع مركزي يجمع ويدير مستندات Vulnerability Exploitability eXchange (VEX) من مختلف مشاريع البرمجيات مفتوحة المصدر. يعمل كمورد شامل لمعلومات الثغرات، مما يساعد المستخدمين وأدوات الأمان على الوصول إلى بيانات VEX واستخدامها بكفاءة عبر مشاريع وأنظمة بيئية متعددة.

يقوم VEX Hub تلقائيًا باسترداد مستندات VEX من مستودعات المصدر للمشاريع المسجلة. من خلال تحديد مستودع المصدر من رابط الحزمة (PURL) المسجل، يقوم VEX Hub بنسخ مستندات VEX وتنظيمها، مما يجعلها متاحة بسهولة للمجتمع الأوسع.

البدء السريع: إضافة مستندات VEX إلى VEX Hub

1. أنشئ ملف VEX الخاص بك
   1. يدعم VEX Hub تنسيق OpenVEX أو CSAF.
   2. خزّن ملفات VEX الخاصة بك في مستودع الكود المصدري داخل دليل .vex/ في جذر المستودع. مزيد من المعلومات هنا.
   3. للحصول على إرشادات إضافية حول إنشاء مستندات VEX لـ VEX Hub، انظر هنا.
2. سجّل حزمتك لدى VEX Hub
   1. أنشئ طلب سحب (Pull Request) يضيف PURL الخاص بحزمتك إلى ملف الحزم المُزحفة.

هذا كل شيء! سيقوم VEX Hub تلقائيًا باسترداد مستندات VEX الخاصة بك ومعالجتها.

الزحف في VEX

يقوم VEX Hub Crawler بشكل دوري بالزحف على مستندات VEX للحزم المسجلة ويحافظ عليها في VEX Hub. تُعرَّف الحزم المسجلة على أنها قائمة من PURLs في ملف يمكن لأي شخص تحديثه عبر طلبات السحب (Pull Requests).

للحصول على معلومات تفصيلية حول تسجيل PURL والأنظمة البيئية المدعومة والمتطلبات المحددة، يرجى الرجوع إلى VEX Hub Crawler.

تحديد مستودعات المصدر

يحدد ملف الحزم PURL الخاص بالحزمة المراد الزحف إليها فقط، ويقوم VEX Hub Crawler تلقائيًا بتحديد مستودع الكود المصدري الذي يوجد فيه ملف VEX. تختلف طريقة تحديد مستودعات المصدر حسب النظام البيئي. للحصول على معلومات تفصيلية حول كيفية تحديد مستودعات المصدر والزحف إليها لأنواع الحزم المختلفة، يرجى الرجوع إلى توثيق vex-crawler.

اكتشاف مستندات VEX

بعد تحديد مستودع الكود المصدري، يكتشف VEX Hub تلقائيًا مستندات VEX الموجودة فيه. تشمل عملية الاكتشاف النقاط الرئيسية التالية:

• يتم البحث عن مستندات VEX في دليل .vex/ في جذر المستودع.
• تنسيقات VEX المدعومة هي OpenVEX وCSAF.
• تُؤخذ في الاعتبار أسماء الملفات المطابقة لأنماط محددة (مثل *.vex.json، *.csaf.json).
• يجب استخدام PURLs للمنتجات والمكونات الفرعية في مستندات VEX.
• يتم تجاهل مستندات VEX غير المطابقة لـ PURL المسجل.

للحصول على معلومات تفصيلية حول عملية الاكتشاف والأنظمة البيئية المدعومة والمتطلبات المحددة، يرجى الرجوع إلى توثيق vex-crawler.

بنية الدليل

يتم تنظيم VEX Hub استنادًا إلى رابط الحزمة (PURL)، مع استبعاد version وqualifiers وsubpath. تلتزم البنية بالقواعد التالية:

1. يُشتق التسلسل الهرمي للدليل من مكونات PURL: المخطط، والنوع، والنطاق (إن وُجد)، والاسم. في حالة oci، يُستخدم مُعدِّل repository_url بدلاً من ذلك.
2. يُستبعد الإصدار (version) والمُعدِّلات (qualifiers) من بنية الدليل. يجب تحديد هذه العناصر داخل حقل products في مستندات VEX.
3. يتم تطبيق ترميز URL على الأحرف الخاصة في مكونات PURL.

أمثلة على تكوين بنية الدليل:

• pkg:npm/express → /npm/express/
• pkg:golang/github.com/gorilla/mux → /golang/github.com/gorilla/mux/
• pkg:maven/org.apache.xmlgraphics/batik-anim → /maven/org.apache.xmlgraphics/batik-anim/
• pkg:oci/trivy?repository_url=ghcr.io/aquasecurity/trivy → /oci/ghcr.io/aquasecurity/trivy/

مثال مع ترميز الأحرف الخاصة:

• pkg:npm/@angular/core → /npm/%40angular/core/

التوزيع

يتوافق VEX Hub مع مواصفة مستودع VEX. يمكن استخدام ملفي vex_repository.json وindex.json للوصول برمجيًا إلى مستندات VEX في VEX Hub.

مستندات VEX متعددة لكل PURL

يمتلك VEX Hub القدرة على تخزين مستندات VEX متعددة لـ PURL واحد، حيث يقوم بنسخ جميع مستندات VEX المطابقة من مستودع المصدر. ومع ذلك، تسمح مواصفة مستودع VEX بمستند VEX واحد فقط لكل PURL. للامتثال لهذه المواصفة، ينفذ VEX Hub استراتيجية التوزيع التالية:

• عند وجود ملفات VEX متعددة لـ PURL واحد، يختار VEX Hub أول ملف بالترتيب المعجمي.
• اكتب الملف المحدد إلى index.json للتوزيع.

إنشاء مستندات VEX لـ VEX Hub

لمنع الالتباس وضمان الاتساق، لا يُنصح بتقسيم تصريحات VEX الخاصة بنفس PURL إلى ملفات متعددة، لأن VEX Hub يوزع ملف VEX واحدًا فقط لكل PURL.

الطرق الموصى بها هي:

1. دمج تصريحات VEX لجميع المنتجات التي يديرها مستودع المصدر في ملف واحد.
2. تقسيم مستندات VEX حسب PURL.

سيناريو مثال: لنفترض مستودع مصدر https://github.com/org/repo يدير منتجين: وحدة Go وصورة OCi.

الطريقة الأولى هي إنشاء ملف VEX واحد، vex.json، يحتوي على تصريحات VEX للمنتجين معًا.

• openvex.json: للمنتجين معًا، مع PURLs التالية pkg:golang/github.com/org/repo وpkg:oci/repo?repository_url=docker.io/org/repo وpkg:oci/repo?repository_url=ghcr.io/org/repo

الطريقة الثانية هي إنشاء ملفات VEX منفصلة لكل منتج.

• golang.vex: لوحدة Go، مع PURL pkg:golang/github.com/org/repo
• oci.vex: لصورة OCI، مع PURLs التالية pkg:oci/repo?repository_url=docker.io/org/repo وpkg:oci/repo?repository_url=ghcr.io/org/repo

البنية التالية غير موصى بها:

• v1.vex: لوحدة Go، مع PURL pkg:golang/github.com/org/[email protected]
• v2.vex: لوحدة Go، مع PURL pkg:golang/github.com/org/[email protected]

في هذا المثال، يتم اختيار v1.vex للتوزيع، ويتم تجاهل v2.vex. يجب دمجهما في ملف VEX واحد، golang.vex، مع إصدارات ومُعدِّلات متعددة.

نموذج الثقة في VEX Hub

نظرًا لأن VEX Hub (وVEX بشكل عام) قد يعزز نتائج فحص الأمان، فمن حقك أن تدقق في صحة مستندات VEX التي تستهلكها. على عكس خلاصات تبادل الثغرات الأخرى، أو خلاصات النشرات الأمنية الجاهزة لـ VEX، فإن VEX Hub ليس مصدر البيانات لتصريحات VEX. يقوم VEX Hub فقط بتجميع مستندات VEX الموجودة وتنظيمها في مستودع مركزي ملائم.

لكي تظهر مستندات VEX في VEX Hub، يجب أولاً إيداعها (commit) في مستودع الكود المصدري للحزمة الرئيسية. تعتمد هذه الطريقة على حقيقة أنه بوصفك مستخدمًا، يجب أن تثق بالفعل في الحزم التي تستخدمها، وبالتالي في القائمين على صيانتها، ونظم الحوكمة، والعمليات التي يستخدمونها. لكل مشروع نظام الحوكمة الخاص به وعملياته الخاصة للإيداع في مستودع الكود المصدري. تلك الأنظمة والعمليات التي تجعل كود الحزمة جديرًا بالثقة في نظرك، هي نفسها الأنظمة والعمليات التي تجعل مستندات VEX جديرة بالثقة بالنسبة لك. يجب ألا تثق في VEX Hub أكثر مما تثق في الحزم التي تختار استخدامها.

ليس لـ VEX Hub أي مسؤولية أو معرفة بمحتوى مستندات VEX التي يحتفظ بها أو بالحزم التي تصفها. لا يقوم القائمون على صيانة VEX Hub بمراجعة محتوى مستندات VEX أو تدقيقه، وتقع مسؤولية دقة المعلومات وصحتها على عاتق القائمين على صيانة الحزم المصدر. نوصي المستخدمين بفرز الثغرات المُخفاة يدويًا بنفس الطريقة التي يفرزون بها أي ثغرة أخرى.

استكشاف الأخطاء وإصلاحها

إذا لم يتم تحديث مستندات VEX الموجودة في مستودع المصدر لـ PURL مسجل بشكل صحيح في VEX Hub، فيرجى التحقق مما يلي:

1. تأكد من وضع مستندات VEX في الموقع الصحيح (دليل .vex/ في جذر المستودع).
2. تحقق من أن مستندات VEX تستخدم أحد اصطلاحات تسمية الملفات المدعومة.
3. تأكد من أن PURL في مستند VEX يطابق PURL المسجل في VEX Hub.
4. راجع توثيق vexhub-crawler للتأكد من استيفاء جميع مواصفات الزحف.

إذا استمرت المشكلات بعد التحقق من هذه النقاط، فيرجى فتح issue في مستودع VEX Hub للحصول على مساعدة إضافية.

المساهمة

نرحب بالمساهمات لتحسين VEX Hub! يرجى ملاحظة أن قائمة الحزم والكود المرتبط بها تتم صيانتهما في مستودع VEX Hub Crawler. لا يُشجَّع على طلبات السحب التي تضيف مستندات VEX مباشرة إلى هذا المستودع. يخضع هذا المشروع وجميع المشاركين فيه لـمدونة قواعد السلوك الخاصة بـ Aqua Security.