VEX Hub Crawler

vexhub-crawler [VEX Hub][vexhub] का एक घटक है जो स्रोत रिपॉज़िटरी से VEX दस्तावेज़ स्वचालित रूप से प्राप्त करता है।

अवलोकन

क्रॉलर पंजीकृत [PURLs (पैकेज URLs)][purl] से स्रोत रिपॉज़िटरी की पहचान करता है और VEX दस्तावेज़ों को VEX Hub में कॉपी करता है। यह प्रक्रिया सुनिश्चित करती है कि VEX Hub विभिन्न सॉफ़्टवेयर पैकेजों के लिए VEX दस्तावेज़ों का अद्यतन संग्रह बनाए रखे।

निम्नलिखित आरेख VEX Hub Crawler की उच्च-स्तरीय प्रक्रिया प्रवाह को दर्शाता है, जिसमें 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 VEX दस्तावेज़ खोजने के लिए PURLs की एक सूची रखता है। 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 दस्तावेज़ पहले से ही किसी ओपन-सोर्स प्रोजेक्ट की स्रोत रिपॉज़िटरी में संग्रहीत हैं, तो प्रोजेक्ट के अनुरक्षकों के अलावा अन्य व्यक्ति VEX Hub में PURL पंजीकृत कर सकते हैं।

वर्तमान में, क्रॉलर निम्नलिखित इकोसिस्टम का समर्थन करता है:

• npm
• Go
• PyPI
• Maven
• Cargo
• OCI

स्रोत रिपॉज़िटरी की पहचान करना

स्रोत रिपॉज़िटरी की पहचान करने की विधि इकोसिस्टम के अनुसार भिन्न होती है:

npm

स्रोत रिपॉज़िटरी का पता लगाने के लिए npm रजिस्ट्री API का उपयोग किया जाएगा। प्रत्येक पैकेज में रिपॉज़िटरी को परिभाषित करने के लिए एक अनुभाग होता है।

React के उदाहरण के लिए, यह इस प्रकार होगा:

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

vexhub-crawler https://github.com/facebook/react में संग्रहीत VEX फ़ाइलों को स्वचालित रूप से प्राप्त करेगा।

Go

go-import से रिपॉज़िटरी की पहचान करने के लिए एक HTTP एक्सेस किया जाएगा।

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 API का उपयोग किया जाएगा।

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

Cargo

रिपॉज़िटरी का पता लगाने के लिए crates.io API का उपयोग किया जाएगा।

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

Maven

Maven पैकेजों के लिए, स्रोत रिपॉज़िटरी की पहचान करने हेतु ये चरण अपनाए जाते हैं:

1. सबसे पहले, PURL विनिर्देश के आधार पर repository_url प्राप्त करें। डिफ़ॉल्ट URL https://repo.maven.apache.org/maven2 है।
2. फिर PURL से namespace और name का उपयोग करके maven-metadata.xml फ़ाइल का URL बनाएं। उदाहरण के लिए, com.fasterxml.jackson.core:jackson-databind के लिए URL होगा: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/maven-metadata.xml।
3. maven-metadata.xml से नवीनतम संस्करण निकालें,
4. इस संस्करण का उपयोग करके, संबंधित POM फ़ाइल डाउनलोड करें। उदाहरण के लिए, यदि jackson-databind का नवीनतम संस्करण 2.17.1 है, तो POM URL होगा: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/2.17.1/jackson-core-2.17.1.pom
5. अंत में, POM फ़ाइल के भीतर scm.url या url फ़ील्ड की जाँच करके स्रोत रिपॉज़िटरी की पहचान करें।

OCI इमेजेस

OCI इमेजेस के लिए, latest टैग के org.opencontainers.image.source लेबल या एनोटेशन की जाँच करके स्रोत रिपॉज़िटरी की पहचान की जाती है। यह मेटाडेटा सामान्यतः इमेज बिल्ड प्रक्रिया के दौरान सेट किया जाता है और स्रोत कोड रिपॉज़िटरी को संदर्भित करने का एक मानकीकृत तरीका प्रदान करता है।

प्रक्रिया इस प्रकार है:

1. दिए गए PURL के लिए, repository_url और :latest टैग जोड़कर पूर्ण इमेज संदर्भ बनाएं।
2. latest टैग के लिए इमेज मैनिफेस्ट और कॉन्फ़िगरेशन प्राप्त करें।
3. निम्नलिखित स्थानों में org.opencontainers.image.source कुंजी देखें:
   • इमेज कॉन्फ़िगरेशन का Labels फ़ील्ड
   • इमेज मैनिफेस्ट का annotations फ़ील्ड

crane का उपयोग करके स्रोत URL प्राप्त करने का उदाहरण:

$ 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

सत्यापन

क्रॉलर निम्नलिखित सत्यापन करता है:

1. सत्यापित करता है कि प्राप्त VEX में लिखा गया PURL, VEX Hub में पंजीकृत PURL से मेल खाता है।
2. यदि नहीं, तो दस्तावेज़ को असंबंधित मानकर अनदेखा कर दिया जाता है।

VEX Hub निर्देशिका संरचना

क्रॉलर खोजी गई फ़ाइलों को उनके मूल फ़ाइल नामों के साथ VEX Hub में कॉपी करता है। VEX Hub में निर्देशिका संरचना पैकेज URL (PURL) के आधार पर बनाई जाती है, संस्करण, qualifiers और subpath को छोड़कर।

तर्क

विश्वसनीयता