تحليل الثغرات الأمنية DevSecOps استخبارات التهديدات أمن سلسلة التوريد

aquasecurity/vex-repo-spec

vex-repo-spec

مواصفات مستودع VEX

عرض المستودع

72منذ 2 سنوات

الأكثر شعبية

عرض الكل →

اكتشف الأدوات الأكثر استخدامًا من قبل مجتمعنا.

استكشف جميع الأدوات

تصفح مجموعتنا من الأدوات

عرض جميع الأدوات →

يجب تفسير الكلمات المفتاحية "MUST" و"MUST NOT" و"REQUIRED" و"SHALL" و"SHALL NOT" و"SHOULD" و"SHOULD NOT" و"RECOMMENDED" و"MAY" و"OPTIONAL" الواردة في هذا المستند كما هو موصوف في RFC 2119.

1. ترقيم الإصدارات

يجب أن تستخدم مواصفات مستودع VEX (تبادل قابلية استغلال الثغرات) ترقيم إصدارات بصيغة vX.Y.
بالنسبة للإصدار v1.0 والإصدارات الأحدث:
- يجب تحديث X (الإصدار الرئيسي) عند حدوث تغييرات جذرية (breaking changes).
- يجب تحديث Y (الإصدار الثانوي) عند حدوث تغييرات متوافقة مع الإصدارات السابقة.
بالنسبة لإصدارات v0.Y، قد تحدث تغييرات جذرية مع تحديثات الإصدار الثانوي.

عند مقارنة الإصدارات:

يجب مقارنة الإصدارات عدديًا، وليس معجميًا.
يجب مقارنة الإصدارات الرئيسية أولاً:
- إذا اختلفت الإصدارات الرئيسية، يُعتبر الإصدار ذو الإصدار الرئيسي الأعلى أحدث.
- إذا تساوت الإصدارات الرئيسية، تابع بمقارنة الإصدارات الثانوية.
يجب مقارنة الإصدارات الثانوية فقط عندما تتساوى الإصدارات الرئيسية:
- يُعتبر الإصدار ذو الإصدار الثانوي الأعلى أحدث.

أمثلة على المقارنات:

1.0 < 2.0
1.1 < 1.2
1.10 > 1.2

2. بيان المستودع

2.1 نظرة عامة

يوفر ملف البيان (manifest) بيانات وصفية حول مستودع بيانات VEX. يجب أن يحتوي هذا الملف على المعلومات اللازمة لاسترجاع بيانات VEX وتحديثها.

2.2 موقع الملف

لبروتوكول HTTPS: يجب أن يكون ملف البيان موجودًا على https://<domain>/.well-known/vex-repository.json
لمستودعات GitHub: يجب وضع vex-repository.json في الدليل الجذر للفرع الرئيسي.

2.3 المخطط

يتم تعريف مخطط JSON لملف البيان هنا.

2.4 مثال

{
  "name": "Example Org VEX Repository",
  "description": "VEX repository for Example Organization",
  "versions": [
    {
      "spec_version": "0.1",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v0/vex-data-v0.tar.gz"
        }
      ],
      "update_interval": "24h",
      "repository_specific": {
        "location": {
          "repository_type": "db",
          "db_type": "bbolt",
          "url": "oci://ghcr.io/example.com/vex-db:0"
        }
      }
    },
    {
      "spec_version": "1.0",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v1/vex-data-v1.tar.gz//subdirectory"
        },
        {
          "url": "https://example.com/vex-api/v1"
        }
      ],
      "update_interval": "1h"
    }
  ]
}

2.5 أوصاف الحقول وملاحظات الاستخدام

الحقول الرئيسية

Field	Required	Description and Usage Notes
name	✓	اسم المستودع.
description	✓	وصف موجز للمستودع.
versions	✓	مصفوفة تحتوي على تفاصيل الإصدارات المتاحة. يمثل كل كائن في المصفوفة إصدارًا ينفذ نسخة من مواصفات مستودع VEX. يجب ترتيب الإصدارات تصاعديًا، من الأقدم إلى الأحدث. راجع الجدول المنفصل للحقول الفرعية.

الحقول الفرعية للإصدارات

Field	Required	Description and Usage Notes
spec_version	✓	إصدار مواصفات مستودع VEX المنفذ (مثل "0.1"). يجب أن يكون التنسيق "X.Y" كما هو معرّف في القسم 1.
locations	✓	مصفوفة من الكائنات تصف مواقع بيانات VEX. يجب أن تحتوي على كائن موقع واحد على الأقل. راجع الجدول المنفصل للحقول الفرعية.
update_interval	✓	الفاصل الزمني الموصى به للتحقق من التحديثات لبيانات VEX الخاصة بهذا الإصدار. يستخدم تنسيق مدة Go (مثل "1h" أو "30m" أو "24h").
repository_specific	-	معلومات إضافية خاصة بالمستودع.

الحقول الفرعية للمواقع

Field	Required	Description and Usage Notes
url	✓	عنوان URL لموقع بيانات VEX، يبدأ بـ "https://". يلتزم المحتوى بمواصفات بنية المستودع في القسم 3 والقسم 4. قد يتضمن عنوان URL تحديد دليل فرعي بإلحاق '//' يتبعه مسار الدليل الفرعي.

3. بنية المستودع

3.1 بنية الملفات

يجب أن يكون للمستودع البنية التالية:

vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
    ├── <type>/
    │   ├── <namespace>/
    │   │   ├── <name>/
    │   │   │   └── vex.json
    │   │   └── ...
    │   └── ...
    └── ...

حيث <archive_extension> هي إحدى صيغ الأرشيف المدعومة.

يتم تضمين [optional_subdirectory/] عندما ينتهي عنوان URL في حقل locations بـ // يتبعه مسار دليل فرعي. يسمح هذا بمرونة في بنية المستودع، خاصة عند استخدام تخطيطات مستودعات قائمة مثل تلك الموجودة في مستودعات GitHub.

على سبيل المثال، إذا كان عنوان URL هو https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main، فستكون بنية الملفات:

main.tar.gz
└──repo-main/
   ├── index.json
   └── pkg/
       └── ...

في هذه الحالة، repo-main/ هو الدليل الجذر لمستودع VEX داخل ملف tar.gz.

3.2 index.json

يعمل ملف index.json كبيان (manifest) لمحتويات ملف الأرشيف. يجب وضعه في الدليل الجذر للأرشيف أو في الدليل الفرعي المحدد إذا تم تعريف واحد في عنوان URL. يجب أن يكون للملف البنية التالية:

{
  "updated_at": "2023-07-04T12:00:00Z",
  "packages": [
    {
      "id": "pkg:deb/debian/curl",
      "location": "pkg/deb/debian/curl/vex.json"
    },
    {
      "id": "pkg:npm/lodash",
      "location": "pkg/npm/lodash/vex.json",
      "format": "csaf"
    }
  ]
}

أوصاف الحقول:

Field	Required	Description
updated_at	✓	طابع زمني يشير إلى آخر مرة تم فيها تحديث ملف index.json هذا.
packages	✓	مصفوفة من الكائنات، يمثل كل منها حزمة في المستودع.
packages[].id	✓	معرّف الحزمة. حاليًا، يتم قبول Package URL (PURL) فقط. يجب حذف الإصدار والمؤهلات (qualifiers) والمسار الفرعي لأنها مضمنة في مستند VEX. بالنسبة للحزم من نوع OCI، يجب تضمين مؤهل `repository_url` في المعرّف (id).
packages[].location	✓	مسار نسبي لملف VEX الخاص بهذه الحزمة داخل الأرشيف. يجب على العملاء استخدام هذا الحقل لتحديد موقع ملفات VEX الخاصة بحزمة معينة.
packages[].format	-	تنسيق بيانات VEX. إما "openvex" أو "csaf". إذا تم حذفه، يُفترض أن التنسيق "openvex".

يتم تعريف مخطط ملف الفهرس هنا.

3.3 مستندات VEX

يجب تخزين معلومات VEX الخاصة بكل حزمة في ملف JSON منفصل، باتباع بنية المسار المعرفة في ملف index.json. يجب أن يلتزم محتوى هذه الملفات بمواصفات تنسيق VEX (OpenVEX أو CSAF VEX) كما هو محدد في حقل format. قد يتضمن مستند VEX واحد معلومات لإصدارات ومؤهلات ومسارات فرعية مختلفة لنفس الحزمة.

لأمثلة مستندات OpenVEX، يُرجى الرجوع إلى مواصفات OpenVEX.

3.4 ملاحظات الاستخدام

بنية الدليل

يُوصى بإنشاء بنيات أدلة للحزم استنادًا إلى PURL الخاص بها، مع استبعاد الإصدار والمؤهلات والمسار الفرعي. على سبيل المثال، يمكن تخزين حزمة يكون PURL الخاص بها "pkg:deb/debian/curl" في المسار "pkg/deb/debian/curl/vex.json".
بالنسبة لحزم OCI، يمكن استخدام مؤهل repository_url الخاص بـ PURL لإنشاء بنية الدليل. على سبيل المثال، يمكن تخزين حزمة يكون PURL الخاص بها "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian" في المسار "pkg/oci/docker.io/library/debian/vex.json".
يمكن تحديد الموقع الفعلي لملفات VEX بحرية في حقل location بملف index.json، بغض النظر عن البنية الموصى بها.
يجب أن تستخدم جميع مسارات الملفات داخل الأرشيف الشرطة المائلة للأمام (/) كفواصل، بغض النظر عن نظام التشغيل.
يجب ترميز أسماء الحزم في بنية الدليل بترميز URL إذا كانت تحتوي على أحرف خاصة.

محتوى مستند VEX

قد يتضمن مستند VEX واحد معلومات لإصدارات ومؤهلات ومسارات فرعية مختلفة لنفس الحزمة.
عند الاستعلام عن إصدار أو مؤهل أو مسار فرعي محدد، يجب على العملاء تحليل مستند VEX بالكامل للعثور على المعلومات ذات الصلة.

3.5 تحديث المستودع

عند تحديث مستودع VEX:

أنشئ ملفات vex.json جديدة أو محدثة للحزم المتأثرة.
حدّث ملف index.json ليعكس أي تغييرات، بما في ذلك تحديث الطابع الزمني updated_at.
أنشئ أرشيفًا جديدًا بالمحتويات المحدثة.
ارفع الأرشيف الجديد إلى الموقع المحدد في ملف البيان (vex-repository.json).
حدّث عنوان URL الخاص بـ locations ذي الصلة في ملف البيان (vex-repository.json) إذا لزم الأمر.

4. توزيع المستودع

4.1 نظرة عامة

يجب توزيع مستودع VEX كملف أرشيف يحتوي على بيانات VEX والبيانات الوصفية المرتبطة بها. يجب أن تتم الإشارة إلى هذا الأرشيف بواسطة حقل locations في ملف vex-repository.json، وهو الوسيلة الأساسية لتوزيع معلومات VEX.

4.2 صيغة الأرشيف

يجب أن يكون ملف الأرشيف بأحد الصيغ التالية:

tar.gz وtgz
tar.bz2 وtbz2
tar.xz وtxz
zip
gz
bz2
xz

5. إرشادات تنفيذ العميل

5.1 اختيار الإصدار

عند اختيار إصدار من مصفوفة versions:

يجب على العملاء اختيار إصدار يدعمونه بناءً على حقل spec_version.
يجب على العملاء مقارنة الإصدارات وفقًا للقواعد المعرفة في القسم 1.
مصفوفة versions مضمونة أن تكون مرتبة من الأقدم إلى الأحدث. يمكن للعملاء استخدام هذا الترتيب لتحديد إصدار مناسب بكفاءة.
بالنسبة للإصدارات v1.0 والإصدارات الأحدث:
- قد يختار العملاء أحدث إصدار يدعمونه ضمن نفس الإصدار الرئيسي، حيث يتم الحفاظ على التوافق مع الإصدارات السابقة ضمن الإصدارات الرئيسية.
بالنسبة للإصدارات v0.Y (حيث Y هو أي إصدار ثانوي):
- يجب على العملاء اختيار تطابق إصدار دقيق.
- وذلك لأن إصدارات v0.Y قد تتضمن تغييرات جذرية بين الإصدارات الثانوية.
إذا لم يتوفر إصدار مدعوم، يجب على العملاء عدم استخدام المستودع ويجب عليهم إشعار المستخدم.

5.2 اختيار الموقع

عند التعامل مع مواقع متعددة في مصفوفة locations:

ترتيب الأولوية: يجب على العملاء تحديد أولوية المواقع بناءً على ترتيبها في المصفوفة. يجب محاولة الوصول إلى الموقع المدرج أولاً قبل الانتقال إلى المواقع اللاحقة.
دعم المخطط (Scheme):
- حاليًا، يُدعم مخطط "https" فقط في المواصفات.
- قد تقدم الإصدارات المستقبلية من هذه المواصفات مخططات إضافية.
- يجب على العملاء التحقق من مخطط URL لكل موقع واستخدام المواقع ذات المخططات المدعومة فقط.
آلية الاحتياط: إذا واجه العميل خطأً مع أحد المواقع، فيجب عليه محاولة استخدام الموقع التالي المتاح في المصفوفة.

5.3 دعم مستودعات متعددة

يجب تصميم العملاء لدعم مستودعات VEX متعددة.

أولوية المستودعات

يجب على العملاء تنفيذ آلية لتحديد أولوية المستودعات.
عندما توفر مستودعات متعددة بيانات VEX لنفس PURL، يجب على العملاء اختيار البيانات بناءً على أولوية المستودع.
يجب أن تكون طريقة تحديد الأولوية قابلة للتكوين للسماح للمستخدمين بالضبط وفقًا لاحتياجاتهم الخاصة ومدى ثقتهم في مصادر البيانات المختلفة.

5.4 التحقق من التحديثات

يجب على العملاء استخدام العملية التالية للتحقق من التحديثات:

قم بتخزين الطابع الزمني لآخر تحديث ناجح أو آخر فحص تحديث محليًا.
عند التفكير في التحديث، استرجع update_interval من ملف vex-repository.json.
احسب وقت التحديث التالي بإضافة update_interval إلى الطابع الزمني المخزن محليًا.
قارن هذا الوقت المحسوب بالوقت الحالي:
- إذا كان الوقت الحالي أحدث من الوقت المحسوب، فتابع التحقق من التحديثات:
  - أرسل طلبًا لتنزيل أحدث محتوى للمستودع.
  - إذا كان المحتوى الجديد متاحًا، فقم بتنزيل المستودع المحدّث ومعالجته.
  - حدّث الطابع الزمني المخزن محليًا بالوقت الحالي.
- إذا كان الوقت الحالي أقدم من الوقت المحسوب، فاستمر في استخدام محتوى المستودع المخزن مؤقتًا.

5.5 استراتيجيات الكفاءة

للتشغيل الفعال، قد ينفذ العملاء الاستراتيجيات التالية:

استخدم رؤوس HTTP ETags أو Last-Modified عند إرسال طلبات التحقق من التحديثات. يمكن أن يساعد ذلك في تقليل التنزيلات غير الضرورية عندما لا يتغير المحتوى.
نفّذ فاصلًا زمنيًا أدنى بين فحوصات التحديث (مثل ساعة واحدة) لتجنب طلبات الشبكة المفرطة، خاصة في الحالات التي يكون فيها update_interval قصيرًا جدًا.
اسمح بتجاوز يدوي لفحوصات التحديث، مما يمكن المستخدمين من فرض فحص فوري بغض النظر عن وقت التحديث التالي المحسوب.

تنزيل الأداة