github.com/google/go-github/v74@v74.0.0/github/dependency_graph.go (about)

     1  // Copyright 2023 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"context"
    10  	"fmt"
    11  )
    12  
    13  type DependencyGraphService service
    14  
    15  // SBOM represents a software bill of materials, which describes the
    16  // packages/libraries that a repository depends on.
    17  type SBOM struct {
    18  	SBOM *SBOMInfo `json:"sbom,omitempty"`
    19  }
    20  
    21  // CreationInfo represents when the SBOM was created and who created it.
    22  type CreationInfo struct {
    23  	Created  *Timestamp `json:"created,omitempty"`
    24  	Creators []string   `json:"creators,omitempty"`
    25  }
    26  
    27  // RepoDependencies represents the dependencies of a repo.
    28  type RepoDependencies struct {
    29  	SPDXID *string `json:"SPDXID,omitempty"`
    30  	// Package name
    31  	Name             *string               `json:"name,omitempty"`
    32  	VersionInfo      *string               `json:"versionInfo,omitempty"`
    33  	DownloadLocation *string               `json:"downloadLocation,omitempty"`
    34  	FilesAnalyzed    *bool                 `json:"filesAnalyzed,omitempty"`
    35  	LicenseConcluded *string               `json:"licenseConcluded,omitempty"`
    36  	LicenseDeclared  *string               `json:"licenseDeclared,omitempty"`
    37  	ExternalRefs     []*PackageExternalRef `json:"externalRefs,omitempty"`
    38  }
    39  
    40  // PackageExternalRef allows an Package to reference an external sources of additional information,
    41  // like asset identifiers, or downloadable content that are relevant to the package,
    42  // Example for identifiers (e.g., PURL/SWID/CPE) for a package in the SBOM.
    43  // https://spdx.github.io/spdx-spec/v2.3/package-information/#721-external-reference-field
    44  type PackageExternalRef struct {
    45  	// ReferenceCategory specifies the external reference categories such
    46  	// SECURITY", "PACKAGE-MANAGER", "PERSISTENT-ID", or "OTHER"
    47  	// Example: "PACKAGE-MANAGER"
    48  	ReferenceCategory string `json:"referenceCategory"`
    49  
    50  	// ReferenceType specifies the type of external reference.
    51  	// For PACKAGE-MANAGER, it could be "purl"; other types include "cpe22Type", "swid", etc.
    52  	ReferenceType string `json:"referenceType"`
    53  
    54  	// ReferenceLocator is the actual unique identifier or URI for the external reference.
    55  	// Example: "pkg:golang/github.com/spf13/cobra@1.8.1"
    56  	ReferenceLocator string `json:"referenceLocator"`
    57  }
    58  
    59  // SBOMRelationship provides information about the relationship between two SPDX elements.
    60  // Element could be packages or files in the SBOM.
    61  // For example, to represent a relationship between two different Files, between a Package and a File,
    62  // between two Packages, or between one SPDXDocument and another SPDXDocument.
    63  // https://spdx.github.io/spdx-spec/v2.3/relationships-between-SPDX-elements/
    64  type SBOMRelationship struct {
    65  	// SPDXElementID is the identifier of the SPDX element that has a relationship.
    66  	// Example: "SPDXRef-github-interlynk-io-sbomqs-main-f43c98"
    67  	SPDXElementID string `json:"spdxElementId"`
    68  
    69  	// RelatedSPDXElement is the identifier of the related SPDX element.
    70  	// Example: "SPDXRef-golang-github.comspf13-cobra-1.8.1-75c946"
    71  	RelatedSPDXElement string `json:"relatedSpdxElement"`
    72  
    73  	// RelationshipType describes the type of relationship between the two elements.
    74  	// Such as "DEPENDS_ON", "DESCRIBES", "CONTAINS", etc., as defined by SPDX 2.3.
    75  	// Example: "DEPENDS_ON", "CONTAINS", "DESCRIBES", etc.
    76  	RelationshipType string `json:"relationshipType"`
    77  }
    78  
    79  // SBOMInfo represents a software bill of materials (SBOM) using SPDX.
    80  // SPDX is an open standard for SBOMs that
    81  // identifies and catalogs components, licenses, copyrights, security
    82  // references, and other metadata relating to software.
    83  type SBOMInfo struct {
    84  	SPDXID       *string       `json:"SPDXID,omitempty"`
    85  	SPDXVersion  *string       `json:"spdxVersion,omitempty"`
    86  	CreationInfo *CreationInfo `json:"creationInfo,omitempty"`
    87  
    88  	// Repo name
    89  	Name              *string  `json:"name,omitempty"`
    90  	DataLicense       *string  `json:"dataLicense,omitempty"`
    91  	DocumentDescribes []string `json:"documentDescribes,omitempty"`
    92  	DocumentNamespace *string  `json:"documentNamespace,omitempty"`
    93  
    94  	// List of packages dependencies
    95  	Packages []*RepoDependencies `json:"packages,omitempty"`
    96  
    97  	// List of relationships between packages
    98  	Relationships []*SBOMRelationship `json:"relationships,omitempty"`
    99  }
   100  
   101  func (s SBOM) String() string {
   102  	return Stringify(s)
   103  }
   104  
   105  // GetSBOM fetches the software bill of materials for a repository.
   106  //
   107  // GitHub API docs: https://docs.github.com/rest/dependency-graph/sboms#export-a-software-bill-of-materials-sbom-for-a-repository
   108  //
   109  //meta:operation GET /repos/{owner}/{repo}/dependency-graph/sbom
   110  func (s *DependencyGraphService) GetSBOM(ctx context.Context, owner, repo string) (*SBOM, *Response, error) {
   111  	u := fmt.Sprintf("repos/%v/%v/dependency-graph/sbom", owner, repo)
   112  
   113  	req, err := s.client.NewRequest("GET", u, nil)
   114  	if err != nil {
   115  		return nil, nil, err
   116  	}
   117  
   118  	var sbom *SBOM
   119  	resp, err := s.client.Do(ctx, req, &sbom)
   120  	if err != nil {
   121  		return nil, resp, err
   122  	}
   123  
   124  	return sbom, resp, nil
   125  }