VEX Hub Crawler

vexhub-crawler هو مكوّن من VEX Hub يقوم تلقائيًا باسترجاع مستندات VEX من المستودعات المصدرية.

نظرة عامة

يحدد الزاحف المستودعات المصدرية من PURLs (Package URLs) المسجلة وينسخ مستندات VEX إلى VEX Hub. تضمن هذه العملية أن يحتفظ VEX Hub بمجموعة محدّثة من مستندات VEX لمختلف حزم البرمجيات.

يوضح المخطط التالي سير العملية عالي المستوى لزاحف VEX Hub، باستخدام npm كمثال:

flowchart TD
    Dev[Developer] -->|Register package| PL[Package List]
    PL -->|Provide packages for crawling| Crawler
    Crawler -->|Identify repository URL| Registry[Package Registry]
    Crawler -->|Retrieve VEX documents| Src
    Crawler -->|Validate and update VEX documents| Hub

    subgraph crawler [VEX Hub Crawler]
        Crawler
        PL
    end

    subgraph bottom [  ]
        direction LR
        Registry
        Src
        Hub[VEX Hub]
        
        subgraph Src[Source Repository]
            direction TB
            VEX[VEX documents<br>under .vex/ directory]
        end
    end

    
    classDef dev fill:#b3d9ff,stroke:#2a4d69,stroke-width:1px,color:#2a4d69;
    classDef vexHub fill:#ffd9e6,stroke:#4b3832,stroke-width:1px,color:#4b3832;
    classDef crawler fill:#c2f0c2,stroke:#1e4d2b,stroke-width:1px,color:#1e4d2b;
    classDef npmReg fill:#ffe6cc,stroke:#5e3023,stroke-width:1px,color:#5e3023;
    classDef sourceRepo fill:#e6ccff,stroke:#3b2e58,stroke-width:1px,color:#3b2e58;
    classDef pkgList fill:#ccf2ff,stroke:#1c4e5a,stroke-width:1px,color:#1c4e5a;
    classDef invisible fill:none,stroke:none;

    class Dev dev;
    class Hub vexHub;
    class crawler crawler;
    class Registry npmReg;
    class Src,VEX sourceRepo;
    class PL pkgList;
    class bottom invisible;

تسجيل PURLs

يحتفظ VEX Hub Crawler بقائمة PURLs لاكتشاف مستندات VEX. يكون تنسيق ملف تعريف PURL كما يلي:

pkg:
  npm:
    - namespace: "@angular"
      name: animations
  golang:
    - name: github.com/aquasecurity/trivy
  pypi:
    - name: django
  maven:
    - namespace: org.junit.jupiter
      name: junit-jupiter-api
  oci:
    - name: trivy
      qualifiers:
         - key: repository_url
           value: index.docker.io/aquasec/trivy
    - name: trivy
      qualifiers:
        - key: repository_url
          value: ghcr.io/aquasecurity/trivy

عند تحديد PURLs، تكون المكونات التالية مطلوبة:

type
name

يجب حذف version. قد تكون namespace وqualifiers وsubpath ضرورية لأنظمة بيئية معينة، مثل oci. للحصول على معلومات تفصيلية حول تكوين PURL، يرجى الرجوع إلى مواصفات PURL.

يمكن لأي شخص تحديث قائمة PURLs عبر Pull Requests. إذا كانت مستندات VEX مخزّنة بالفعل في المستودع المصدر لمشروع مفتوح المصدر، فمرحبًا بالأفراد غير القائمين على صيانة المشروع لتسجيل الـ PURL في VEX Hub.

حاليًا، يدعم الزاحف الأنظمة البيئية التالية:

npm
Go
PyPI
Maven
Cargo
OCI

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

تختلف طريقة تحديد المستودعات المصدرية حسب النظام البيئي:

npm

سيتم استخدام واجهة برمجة تطبيقات سجل npm لحل المستودع المصدر. لكل حزمة قسم لتحديد المستودع.

على سبيل المثال مع React، سيكون الأمر كما يلي:

$ curl -s https://registry.npmjs.org/react | jq .repository.url
"git+https://github.com/facebook/react.git"

سيقوم vexhub-crawler تلقائيًا باسترجاع ملفات VEX المخزنة في https://github.com/facebook/react.

Go

سيتم إجراء وصول HTTP لتحديد المستودع من go-import.

curl -s "https://k8s.io/client-go?go-get=1"

            <html><head>
                  <meta name="go-import"
                        content="k8s.io/client-go
                                 git https://github.com/kubernetes/client-go">
                  <meta name="go-source"
                        content="k8s.io/client-go
                                 https://github.com/kubernetes/client-go
                                 https://github.com/kubernetes/client-go/tree/master{/dir}
                                 https://github.com/kubernetes/client-go/blob/master{/dir}/{file}#L{line}">
            </head></html>

PyPI

سيتم استخدام واجهة برمجة تطبيقات PyPI لحل المستودع.

curl -s https://pypi.org/pypi/<package-name>/json | jq .info.project_urls.Source

Cargo

سيتم استخدام واجهة برمجة تطبيقات crates.io لحل المستودع.

curl -s https://crates.io/api/v1/crates/<crate-name> | jq .crate.repository

Maven

بالنسبة لحزم Maven، يتبع الخطوات التالية لتحديد المستودع المصدر:

أولًا، احصل على repository_url بناءً على مواصفات PURL. عنوان URL الافتراضي هو https://repo.maven.apache.org/maven2.
ثم أنشئ عنوان URL لملف maven-metadata.xml باستخدام namespace والاسم من PURL. على سبيل المثال، بالنسبة إلى com.fasterxml.jackson.core:jackson-databind، سيكون عنوان URL هو: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/maven-metadata.xml.
استخرج أحدث إصدار من maven-metadata.xml،
باستخدام هذا الإصدار، قم بتنزيل ملف POM المقابل. على سبيل المثال، إذا كان أحدث إصدار من jackson-databind هو 2.17.1، فسيكون عنوان URL لـ POM هو: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/2.17.1/jackson-core-2.17.1.pom
أخيرًا، حدد المستودع المصدر من خلال فحص حقل scm.url أو url داخل ملف POM.

صور OCI

بالنسبة لصور OCI، يتم تحديد المستودع المصدر من خلال فحص التسمية org.opencontainers.image.source أو التعليق التوضيحي لوسم latest. عادةً ما يتم تعيين البيانات الوصفية أثناء عملية بناء الصورة وتوفر طريقة موحدة للإشارة إلى مستودع الكود المصدري.

تكون العملية كما يلي:

بالنسبة إلى PURL المعطى، أنشئ مرجع الصورة الكامل بإلحاق repository_url ووسم :latest.
استرجع manifest الصورة والإعدادات لوسم latest.
ابحث عن المفتاح org.opencontainers.image.source في المواقع التالية:
- حقل Labels في إعدادات الصورة
- حقل annotations في manifest الصورة

مثال على استرجاع عنوان URL المصدر باستخدام crane:

$ crane config ghcr.io/aquasecurity/trivy:latest | jq -r '.config.Labels["org.opencontainers.image.source"]'
https://github.com/aquasecurity/trivy

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

بمجرد تحديد المستودع المصدر (يتم دعم مستودعات git فقط حاليًا)، يبحث vexhub-crawler عن مستندات VEX في دليل .vex/ في جذر المستودع.

يعتبر الزاحف الملفات المطابقة للأنماط التالية مستندات VEX:

*.csaf.json
*.openvex.json
*.vex.json
.openvex.json
vex.json

التحقق

يقوم الزاحف بعمليات التحقق التالية:

يتحقق من أن PURL المكتوب في VEX المسترجع يطابق الـ PURL المسجل في VEX Hub.
إذا لم يتطابق، تُعتبر المستند غير ذي صلة ويتم تجاهله.

هيكل دليل VEX Hub

ينسخ الزاحف الملفات المكتشفة إلى VEX Hub بأسمائها الأصلية. يتم إنشاء هيكل الدليل في VEX Hub استنادًا إلى Package URL (PURL)، باستثناء الإصدار (version) وqualifiers وsubpath.

الأساس المنطقي

الموثوقية

يعتمد الزاحف نموذج ثقة قائمًا على مستندات VEX المخزنة في المستودعات المصدرية. كما ذُكر في قسم التحقق، يقوم بتصفية مستندات VEX التي تعلن عن منتجات مختلفة عن PURL الأصلي.

على سبيل المثال، إذا تم تسجيل PURL pkg:npm/malicious في VEX Hub وتم حله إلى المستودع المصدر github.com/org/malicious، فيجب أن يكون لأي مستندات VEX مخزنة هناك معرف منتج pkg:npm/malicious. سيتم تجاهل مستندات VEX ذات معرفات المنتجات المختلفة، مثل pkg:npm/[email protected].

يضمن هذا النهج تضمين مستندات VEX ذات الصلة والموثوقة فقط في VEX Hub.

العمل المستقبلي

حل أكثر موثوقية للمستودع المصدر

حاليًا، يستخدم VEX Hub Crawler واجهات برمجة تطبيقات السجلات (registry APIs) لتحديد المستودعات المصدرية للحزم. ومع ذلك، ينطوي هذا النهج على مخاطر أمنية محتملة حيث يمكن لمُطوّري الحزم تعيين معلومات المستودع بحرية، مما يجعله عرضة للعبث.

لمعالجة هذا التحدي، ندرس استخدام إثبات المنشأ (provenance attestation) لحل أكثر موثوقية للمستودع المصدر في المستقبل. يسمح إثبات المنشأ بالحصول على عنوان URL الفعلي للمستودع الذي بُنيت فيه الحزمة بطريقة موثوقة، مما يتيح التحقق التشفيري من العلاقة بين الكود المصدري للحزمة ومخرجاتها المنشورة.

من الجدير بالذكر أن npm قد طبّقت بالفعل إثبات المنشأ في سجلها. يتيح هذا التنفيذ استرجاع معلومات المستودع المصدر مباشرة من PURL باستخدام بيانات المنشأ. نعتقد أن هذا النهج يمكن أن يعزز موثوقية عملية حل المستودع المصدر للحزم.

vexhub-crawler

الأكثر شعبية