Skip to content

Latest commit

 

History

History
105 lines (77 loc) · 6.9 KB

using-the-dependency-submission-api.md

File metadata and controls

105 lines (77 loc) · 6.9 KB
Raw
title intro shortTitle topics versions
Using the dependency submission API
You can use the {% data variables.dependency-submission-api.name %} to submit dependencies for projects, such as the dependencies resolved when a project is built or compiled.
Dependency submission API
API
Dependency graph
Dependencies
REST
fpt ghes ghec
*
*
*

About the {% data variables.dependency-submission-api.name %}

{% data reusables.dependency-submission.about-dependency-submission %}

Dependencies are submitted to the {% data variables.dependency-submission-api.name %} in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from your dependencies detected at build time or from a software bill of materials (SBOM). There are {% data variables.product.prodname_actions %} that support either of these use cases. For more information about the {% data variables.dependency-submission-api.name %}, see "AUTOTITLE."

Submitting dependencies at build-time

You can use the {% data variables.dependency-submission-api.name %} in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built.

Using pre-made actions

{% data reusables.dependency-submission.api-premade-actions %}

For more information about these actions, see "AUTOTITLE."

Creating your own action

Alternatively, you can write your own action to submit dependencies for your project at build-time. Your workflow should:

  1. Generate a list of dependencies for your project.
  2. Translate the list of dependencies into the snapshot format accepted by the {% data variables.dependency-submission-api.name %}. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in "AUTOTITLE."
  3. Submit the formatted list of dependencies to the {% data variables.dependency-submission-api.name %}.

{% data variables.product.product_name %} maintains the Dependency Submission Toolkit, a TypeScript library to help you build your own GitHub Action for submitting dependencies to the {% data variables.dependency-submission-api.name %}. For more information about writing an action, see "AUTOTITLE".

Generating and submitting a software bill of materials (SBOM)

{% data reusables.dependency-graph.sbom-intro %}

Generating a software bill of materials (SBOM)

To generate an SBOM, you can use:

  • The {% data variables.product.prodname_dotcom %} UI. For more information about how to export an SBOM for a repository using information from the dependency graph, see "AUTOTITLE."
  • The REST API. For more information, see "AUTOTITLE."
  • {% data variables.product.prodname_actions %}. The following actions will generate an SBOM for your repository and attach it as a workflow artifact which you can download and use in other applications. For more information about downloading workflow artifacts, see "AUTOTITLE."
Action Details
Anchore SBOM Action Uses Syft to create SPDX 2.2 compatible SBOMs with the supported ecosystems
sbom-tool by Microsoft Scans your dependencies and creates an SPDX compatible SBOM

Submitting a software bill of materials (SBOM) to the {% data variables.dependency-submission-api.name %}

To receive {% data variables.product.prodname_dependabot_alerts %} for dependencies that have known vulnerabilities, you can upload and submit the SBOM to the {% data variables.dependency-submission-api.name %}. To submit an SBOM to the {% data variables.dependency-submission-api.name %}, you can use one of the actions in the following table.

[!TIP] The SPDX Dependency Submission Action and the Anchore SBOM Action can be used to both generate the SBOM and submit it to the {% data variables.dependency-submission-api.name %}.

Action Details
SPDX Dependency Submission Action Uses Microsoft's SBOM Tool to create SPDX 2.2 compatible SBOMs with the supported ecosystems
Anchore SBOM Action Uses Syft to create SPDX 2.2 compatible SBOMs with the supported ecosystems
SBOM Dependency Submission Action Uploads a CycloneDX SBOM to the {% data variables.dependency-submission-api.name %}

For example, the following SPDX Dependency Submission Action workflow calculates the dependencies for a repository, generates an exportable SBOM in SPDX 2.2 format, and submits it to the {% data variables.dependency-submission-api.name %}.

name: SBOM upload

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

jobs:
  SBOM-upload:

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

    steps:
    - uses: {% data reusables.actions.action-checkout %}
    - 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 ${{ github.repository }} -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
    - uses: {% data reusables.actions.action-upload-artifact %}
      with:
        name: sbom
        path: _manifest/spdx_2.2
    - name: SBOM upload
      uses: advanced-security/spdx-dependency-submission-action@5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e
      with:
        filePath: "_manifest/spdx_2.2/"