Использование API отправки зависимостей

Примечание: Возможность использования REST API для отправки зависимостей в настоящее время находится в общедоступной бета-версии и может быть изменена.

Сведения об API отправки зависимостей

Для отправки зависимостей для проекта можно использовать REST API. Так вы сможете добавлять зависимости, например разрешаемые при компиляции или сборке программного обеспечения, в функцию графа зависимостей GitHub, чтобы создать более полную картину всех зависимостей проекта.

На графе зависимостей отображаются все зависимости, которые вы отправили через этот API, а также те, которые определены в файлах манифеста или блокировки, размещенных в репозитории (например, файл package-lock.json в проекте JavaScript). Дополнительные сведения о просмотре графа зависимостей см. в разделе Изучение зависимостей репозитория.

Отправленные зависимости будут получать Dependabot alerts и Dependabot security updates по всем известным уязвимостям. Вы будете получать Dependabot alerts только для тех зависимостей, которые относятся к одной из поддерживаемых экосистем GitHub Advisory Database. Отправленные зависимости не будут отображаться при проверке зависимостей или в аналитических сведениях о зависимостях в вашей организации.

Зависимости отправляются в API отправки зависимостей в виде моментального снимка. Моментальный снимок — это набор зависимостей, связанных с SHA фиксации и другими метаданными, которые отражают текущее состояние репозитория для фиксации. Моментальные снимки можно создавать из зависимостей, обнаруженных во время сборки, или из программного обеспечения (SBOM). Существуют GitHub Actions, которые поддерживают любой из этих вариантов использования. Дополнительные сведения об API отправки зависимостей см. в документации по REST API отправки зависимостей.

Отправка зависимостей во время сборки

API отправки зависимостей можно использовать в рабочем процессе GitHub Actions для отправки зависимостей для проекта при создании проекта.

Использование готовых действий

Самый простой способ использовать API отправки зависимостей — добавить в репозиторий готовое действие, которое будет собирать и преобразовывать список зависимостей в требуемый формат моментальных снимков и отправлять список в API. Действия, которые выполняют эти действия для различных экосистем, доступны в GitHub Marketplace. Некоторые из этих действий предоставляются третьими лицами. Ссылки на доступные в настоящее время действия можно найти в таблице ниже.

Экосистема	Действие	Поддерживается GitHub
Go	Отправка зависимостей Go
Gradle	Отправка зависимостей Gradle
Maven	Отправка зависимостей дерева зависимостей Maven
Мельница	Отправка зависимостей милли
Scala	Отправка зависимостей Sbt

Например, следующий рабочий процесс отправки зависимостей Go вычисляет зависимости для целевого объекта сборки Go (файл Go с main функцией) и отправляет список в API отправки зависимостей.


name: Go Dependency Submission
on:
  push:
    branches:
      - main

# The API requires write permission on the repository to submit dependencies
permissions:
  contents: write

# Envionment variables to configure Go and Go modules. Customize as necessary
env:
  GOPROXY: '' # A Go Proxy server to be used
  GOPRIVATE: '' # A list of modules are considered private and not requested from GOPROXY
jobs:
  go-action-detection:
    runs-on: ubuntu-latest
    steps:
      - name: 'Checkout Repository'
        uses: actions/checkout@v3

      - uses: actions/setup-go@v3
        with:
          go-version: ">=1.18.0"

      - name: Run snapshot action
        uses: actions/go-dependency-submission@v1
        with:
            # Required: Define the repo path to the go.mod file used by the
            # build target
            go-mod-path: go-example/go.mod
            #
            # Optional. Define the repo path of a build target,
            # a file with a `main()` function.
            # If undefined, this action will collect all dependencies
            # used by all build targets for the module. This may
            # include Go dependencies used by tests and tooling.
            go-build-target: go-example/cmd/octocat.go

Создание собственного действия

Кроме того, можно написать собственное действие для отправки зависимостей для проекта во время сборки. Рабочий процесс должен делать следующее:

Создать список зависимостей для проекта.
Преобразовать список зависимостей в формат моментального снимка, принятый API отправки зависимостей. Дополнительные сведения о формате см. в основных параметрах операции API "Создание моментального снимка репозитория" в документации по REST API отправки зависимостей.
Отправьте форматированный список зависимостей в API отправки зависимостей.

GitHub Enterprise Server поддерживает набор средств отправки зависимостей, библиотеку TypeScript, помогающую создавать собственные действия GitHub Actions для отправки зависимостей в API отправки зависимостей. Дополнительные сведения о написании действия см. в разделе Создание действий.

Создание и отправка счета за программное обеспечение (SBOM)

GitHub Actions можно использовать для создания счета за программное обеспечение (SBOM), формального и машиночитаемого инвентаризации зависимостей и связанных сведений. Следующие действия создадут SBOM для репозитория и прикрепят его в качестве артефакта рабочего процесса, который можно скачать и использовать в других приложениях. Дополнительные сведения о скачивании артефактов рабочего процесса см. в разделе Скачивание артефактов рабочего процесса.

Действие	Сведения	Поддерживается GitHub
SBOM-generator-action	Использует сведения в графе зависимостей для создания SBOM SPDX
Действие Anchore SBOM	Использует Syft для создания SBOM, совместимых с SPDX 2.2, с поддерживаемыми экосистемами
sbom-tool от Майкрософт	Проверяет зависимости и создает SBOM, совместимый с SPDX.

Затем можно отправить SBOM в API отправки зависимостей, выполнив одно из следующих действий, чтобы получить Dependabot alerts для всех зависимостей, имеющих известные уязвимости. Действия, отображаемые в обеих таблицах, можно настроить как для создания, так и для отправки SBOM.

Действие	Сведения	Поддерживается GitHub
Действие отправки зависимостей SPDX	Использование средства SBOM корпорации Майкрософт для создания SBOM,совместимых с SPDX 2.2, с поддерживаемыми экосистемами
Действие Anchore SBOM	Использует Syft для создания SBOM, совместимых с SPDX 2.2, с поддерживаемыми экосистемами
Действие отправки зависимостей SBOM	Отправляет SBOM-файл CycloneDX в API отправки зависимостей.

Например, следующий рабочий процесс действия отправки зависимостей SPDX вычисляет зависимости для репозитория, создает экспортируемую SBOM в формате SPDX 2.2 и отправляет его в API отправки зависимостей.


name: SBOM upload

on:
  workflow_dispatch:
  push:
    branches: ["main"]

jobs:
  SBOM-upload:

    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write

    steps:
    - uses: actions/checkout@v3
    - name: Generate SBOM
      # generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
      run: |
        curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
        chmod +x $RUNNER_TEMP/sbom-tool
        $RUNNER_TEMP/sbom-tool generate -b . -bc . -pn $ -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
    - uses: actions/upload-artifact@v3
      with:
        name: sbom
        path: _manifest/spdx_2.2
    - name: SBOM upload
      uses: advanced-security/spdx-dependency-submission-action@v0.0.1
      with:
        filePath: "_manifest/spdx_2.2/"