VEX Hub Crawler

vexhub-crawler — это компонент [VEX Hub][vexhub], который автоматически получает VEX-документы из исходных репозиториев.

Обзор

Краулер определяет исходные репозитории по зарегистрированным [PURL (Package 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;

Регистрация PURL

VEX Hub Crawler поддерживает список PURL для поиска 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

При указании PURL требуются следующие компоненты:

• type
• name

Поле version должно быть опущено. Параметры namespace, qualifiers и subpath могут потребоваться для некоторых экосистем, например oci. Подробную информацию о составе PURL см. в спецификации PURL.

Список PURL может быть обновлён любым желающим через Pull Requests. Если VEX-документы уже хранятся в исходном репозитории проекта с открытым исходным кодом, сторонние разработчики (не только сопровождающие проекта) могут зарегистрировать PURL в VEX Hub.

В настоящее время краулер поддерживает следующие экосистемы:

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

Определение исходных репозиториев

Метод определения исходных репозиториев зависит от экосистемы:

npm

Для определения исходного репозитория используется API реестра 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

Для определения репозитория по 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

Для определения репозитория используется API PyPI.

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

Cargo

API crates.io будет использоваться для определения репозитория.

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

Maven

Для Maven-пакетов определение исходного репозитория выполняется следующим образом:

1. Сначала получите repository_url в соответствии со спецификацией PURL. URL по умолчанию: https://repo.maven.apache.org/maven2.
2. Затем сформируйте URL для файла maven-metadata.xml, используя namespace и name из PURL. Например, для 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, URL POM будет таким: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-core/2.17.1/jackson-core-2.17.1.pom
5. Наконец, определите исходный репозиторий, проверив поле scm.url или url в POM-файле.

OCI-образы

Для OCI-образов исходный репозиторий определяется путём проверки метки (label) или аннотации (annotation) org.opencontainers.image.source у тега latest. Эти метаданные обычно задаются в процессе сборки образа и предоставляют стандартизированный способ указания репозитория исходного кода.

Процесс выглядит следующим образом:

1. Для указанного PURL сформируйте полную ссылку на образ, добавив repository_url и тег :latest.
2. Получите манифест и конфигурацию образа для тега latest.
3. Найдите ключ org.opencontainers.image.source в следующих местах:
   • в поле Labels конфигурации образа
   • в поле annotations манифеста образа

Пример получения 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

Проверка

Краулер выполняет следующие проверки:

1. Проверяет, что PURL, указанный в полученном VEX-документе, совпадает с PURL, зарегистрированным в VEX Hub.
2. Если нет, документ считается посторонним и игнорируется.

Структура каталога VEX Hub

Краулер копирует обнаруженные файлы в VEX Hub с их исходными именами. Структура каталогов в VEX Hub создаётся на основе Package URL (PURL), без учёта версии, квалификаторов и subpath.

Обоснование

Достоверность