Supply Chain

This part of the documentation covers all the supplychain APIs.

Dependency Graph API

class ghastoolkit.DependencyGraph(repository: Repository | None = None, enable_graphql: bool = True, enable_clearlydefined: bool = False, cache: bool = False)

Dependency Graph API.

This class is used to interact with the Dependency Graph API in GitHub.

__init__(repository: Repository | None = None, enable_graphql: bool = True, enable_clearlydefined: bool = False, cache: bool = False) → None

Initialise Dependency Graph.

Parameters:

  • repository – The repository to use. If not provided, it will use the current repository in GitHub.

  • enable_graphql – Enable GraphQL API. Defaults to True.

  • enable_clearlydefined – Enable ClearlyDefined API. Defaults to False.

  • cache – Enable caching. Defaults to False.

exportBOM() → Dict

Download / Export DependencyGraph SBOM.

https://docs.github.com/en/rest/dependency-graph/sboms#export-a-software-bill-of-materials-sbom-for-a-repository

getDependencies() → Dependencies

Get Dependencies.

getDependenciesGraphQL(dependencies_count: int = 100) → Dependencies

Get Dependencies from GraphQL.

This functions requests each manifest file in the repository and the dependencies associated with it. It then paginates through both the manifests and dependencies.

This is done to avoid the timeout errors in the GraphQL API when requesting large projects with many manifests and dependencies.

getDependenciesInPR(base: str, head: str) → Dependencies

Get all the dependencies from a Pull Request.

Parameters:

  • base – The base branch of the Pull Request.

  • head – The head branch of the Pull Request.

Returns:

A list of dependencies.

Return type:

Dependencies

getDependenciesSbom() → Dependencies

Get Dependencies from SBOM.

If cache is enabled, it will use the cached dependencies if they exist. If not, it will download the SBOM and cache it.

getOrganizationDependencies(owner: str | None = None) → Dict[Repository, Dependencies]

Get Organization Dependencies for all repositories.

This is done by iterating through all the repositories in the organization and getting the dependencies for each repository. This is done as there is no way to get all the dependencies for an organization in a single request.

Parameters:

owner – The owner of the organization. If not provided, it will use the current owner of the repository.

Returns:

A dictionary of repositories and their dependencies.

Return type:

Dict[Repository, Dependencies]

getUniqueOrgDependencies(version: bool = False) → Dependencies

Create a unique list of dependencies, this is useful for merging multiple lists for example from an organization.

Parameters:

version – If True, include the version in the unique list. Defaults to False.

submitDependencies(dependencies: Dependencies, tool: str, path: str, sha: str = '', ref: str = '', version: str = '0.0.0', url: str = '')

Submit dependencies to GitHub Dependency Graph snapshots API.

Parameters:

  • dependencies – The dependencies to submit.

  • tool – The tool used to generate the dependencies.

  • path – The path to the dependencies file.

  • sha – The SHA of the commit.

  • ref – The reference of the commit.

  • version – The version of the dependencies.

  • url – The URL of the dependencies file.

https://docs.github.com/en/rest/dependency-graph/dependency-submission?apiVersion=2022-11-28#create-a-snapshot-of-dependencies-for-a-repository

submitSbom(sbom: dict[Any, Any])

Submit SBOM.

Dependabot API

class ghastoolkit.Dependabot(repository: Repository | None = None)

Dependabot API instance.

__init__(repository: Repository | None = None) → None

Initialise Dependabot API class.

getAlerts(state: str = 'open', severity: str | None = None, ecosystem: str | None = None, package: str | None = None, manifest: str | None = None, scope: str | None = None) → list[DependencyAlert]

Get All Dependabot alerts from REST API.

Parameters:

  • state (str) – State of the alert. Defaults to “open”. Options: auto_dismissed, dismissed, fixed, open

  • severity (str) – Severity of the alert. Options: low, moderate, high, critical

  • ecosystem (str) – Ecosystem of the alert. Options: npm, rubygems, maven, pip, etc.

  • package (str) – Package name of the alert.

  • manifest (str) – Manifest path of the alert.

  • scope (str) – Scope of the alert.

Returns:

List of Dependabot alerts.

Return type:

list[DependencyAlert]

Raises:

  • GHASToolkitTypeError – If the state is not valid.

  • GHASToolkitError – If the request fails.

https://docs.github.com/en/rest/dependabot/alerts

getAlertsGraphQL() → list[DependencyAlert]

Get All Dependabot alerts from GraphQL API using the GetDependencyAlerts query.

getAlertsInPR() → list[DependencyAlert]

Get All Dependabot alerts from REST API in Pull Request.

getEnterpriseAlerts(state: str = 'open', severity: str | None = None, ecosystem: str | None = None, package: str | None = None, manifest: str | None = None, scope: str | None = None) → list[DependencyAlert]

Get all Dependabot alerts from Enterprise.

Parameters:

  • severity (str) – Severity of the alert. Options: low, moderate, high, critical

  • ecosystem (str) – Ecosystem of the alert. Options: npm, rubygems, maven, pip, etc.

  • package (str) – Package name of the alert.

  • manifest (str) – Manifest path of the alert.

  • scope (str) – Scope of the alert.

Returns:

List of Dependabot alerts.

Return type:

list[DependencyAlert]

Raises:

  • GHASToolkitAuthenticationError – If the request fails due to authentication.

  • GHASToolkitTypeError – If the state is not valid.

  • GHASToolkitError – If the request fails.

getOrganizationAlerts(state: str = 'open', severity: str | None = None, ecosystem: str | None = None, package: str | None = None, manifest: str | None = None, scope: str | None = None) → list[DependencyAlert]

Get all Dependabot alerts from organization.

Parameters:

  • state (str) – State of the alert. Defaults to “open”. Options: auto_dismissed, dismissed, fixed, open

  • severity (str) – Severity of the alert. Options: low, moderate, high, critical

  • ecosystem (str) – Ecosystem of the alert. Options: npm, rubygems, maven, pip, etc.

  • package (str) – Package name of the alert.

  • manifest (str) – Manifest path of the alert.

  • scope (str) – Scope of the alert.

Returns:

List of Dependabot alerts.

Return type:

list[DependencyAlert]

Raises:

  • GHASToolkitAuthenticationError – If the request fails due to authentication.

  • GHASToolkitTypeError – If the state is not valid.

  • GHASToolkitError – If the request fails.

isEnabled() → bool

Is Dependabot enabled.

isSecurityUpdatesEnabled() → bool

Is Security Updates for Dependabot enabled.

https://docs.github.com/en/rest/reference/repos#get-a-repository