macaron.provenance package

This package contains the provenance tools for software components.

Submodules

macaron.provenance.provenance_extractor module

This module contains methods for extracting repository and commit metadata from provenance files.

macaron.provenance.provenance_extractor.extract_repo_and_commit_from_provenance(payload)

Extract the repository and commit metadata from the passed provenance payload.

Parameters:: payload (InTotoPayload) – The payload to extract from.
Returns:: The repository URL and commit hash if found, a pair of empty strings otherwise.
Return type:: tuple[str, str]
Raises:: ProvenanceError – If the extraction process fails for any reason.

macaron.provenance.provenance_extractor.extract_predicate_version(payload)

Extract and return the SLSA version from the passed payload.

Parameters:: payload (InTotoPayload) – The payload to extract from.
Returns:: The SLSA version, or None if the payload does contain a supported version number.
Return type:: str | None

macaron.provenance.provenance_extractor.check_if_input_repo_provenance_conflict(repo_path_input, provenance_repo_url)

Test if the input repo and commit match the contents of the provenance.

Parameters:

repo_path_input (str | None) – The repo URL from input.
provenance_repo_url (str | None) – The repo URL from provenance.

Returns:

True if there is a conflict between the inputs, False otherwise, or if the comparison cannot be performed.

Return type:

bool

macaron.provenance.provenance_extractor.check_if_input_purl_provenance_conflict(repo_path_input, provenance_repo_url, purl)

Test if the input repository type PURL’s repo and commit match the contents of the provenance.

Parameters:

repo_path_input (bool) – True if there is a repo as input.
provenance_repo_url (str | None) – The repo url from provenance.
purl (PackageURL) – The input repository PURL.

Returns:

True if there is a conflict between the inputs, False otherwise, or if the comparison cannot be performed.

Return type:

bool

macaron.provenance.provenance_extractor.check_if_repository_purl_and_url_match(url, repo_purl)

Compare a repository PURL and URL for equality.

Parameters:

url (str) – The URL.
repo_purl (PackageURL) – A PURL that is of the repository abstract type. E.g. GitHub.

Returns:

True if the two inputs match in terms of URL netloc/domain and path.

Return type:

bool

class macaron.provenance.provenance_extractor.ProvenanceBuildDefinition

Bases: ABC

Abstract base class for representing provenance build definitions.

This class serves as a blueprint for various types of build definitions in provenance data. It outlines the methods and properties that derived classes must implement to handle specific build definition types.

expected_build_type: str: Determines the expected buildType field in the provenance predicate.

abstractmethod get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

This method is intended to be implemented by subclasses to extract specific invocation details from a provenance statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]
Raises:: NotImplementedError – If the method is called directly without being overridden in a subclass.

class macaron.provenance.provenance_extractor.SLSAGithubGenericBuildDefinitionV01

Bases: ProvenanceBuildDefinition

Class representing the SLSA GitHub Generic Build Definition (v0.1).

This class implements the abstract methods defined in ProvenanceBuildDefinition to extract build invocation details specific to the GitHub provenance generator’s generic build type.

expected_build_type: str = 'https://github.com/slsa-framework/slsa-github-generator/generic@v1': Determines the expected buildType field in the provenance predicate.

get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]

class macaron.provenance.provenance_extractor.SLSAGithubActionsBuildDefinitionV1

Bases: ProvenanceBuildDefinition

Class representing the SLSA GitHub Actions Build Definition (v1).

This class implements the abstract methods from the ProvenanceBuildDefinition to extract build invocation details specific to the GitHub Actions build type.

expected_build_type: str = 'https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1': Determines the expected buildType field in the provenance predicate.

get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]

class macaron.provenance.provenance_extractor.SLSANPMCLIBuildDefinitionV2

Bases: ProvenanceBuildDefinition

Class representing the SLSA NPM CLI Build Definition (v12).

This class implements the abstract methods from the ProvenanceBuildDefinition to extract build invocation details specific to the GitHub Actions build type.

expected_build_type: str = 'https://github.com/npm/cli/gha/v2': Determines the expected buildType field in the provenance predicate.

get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]

class macaron.provenance.provenance_extractor.SLSAGCBBuildDefinitionV1

Bases: ProvenanceBuildDefinition

Class representing the SLSA Google Cloud Build (GCB) Build Definition (v1).

This class implements the abstract methods from ProvenanceBuildDefinition to extract build invocation details specific to the Google Cloud Build (GCB).

expected_build_type: str = 'https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1': Determines the expected buildType field in the provenance predicate.

get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]

class macaron.provenance.provenance_extractor.SLSAOCIBuildDefinitionV1

Bases: ProvenanceBuildDefinition

Class representing the SLSA Oracle Cloud Infrastructure (OCI) Build Definition (v1).

This class implements the abstract methods from ProvenanceBuildDefinition to extract build invocation details specific to OCI builds.

expected_build_type: str = 'https://github.com/oracle/macaron/tree/main/src/macaron/resources/provenance-buildtypes/oci/v1': Determines the expected buildType field in the provenance predicate.

get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]

class macaron.provenance.provenance_extractor.WitnessGitLabBuildDefinitionV01

Bases: ProvenanceBuildDefinition

Class representing the Witness GitLab Build Definition (v0.1).

This class implements the abstract methods from ProvenanceBuildDefinition to extract build invocation details specific to GitLab.

expected_build_type: str = 'https://witness.testifysec.com/attestation-collection/v0.1': Determines the expected buildType field in the provenance predicate.

expected_attestation_type = 'https://witness.dev/attestations/gitlab/v0.1': Determines the expected attestations.type field in the Witness provenance predicate.

get_build_invocation(statement)

Retrieve the build invocation information from the given statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build invocation details. This statement contains the metadata about the build process and its associated artifacts.
Returns:: A tuple containing two elements: - The first element is the build invocation entry point (e.g., workflow name), or None if not found. - The second element is the invocation URL or identifier (e.g., job URL), or None if not found.
Return type:: tuple[str | None, str | None]

class macaron.provenance.provenance_extractor.ProvenancePredicate

Bases: object

Class providing utility methods for handling provenance predicates.

This class contains static methods for extracting information from predicates in provenance statements related to various build definitions. It serves as a helper for identifying build types and finding the appropriate build definitions based on the extracted data.

static get_build_type(statement)

Extract the build type from the provided provenance statement.

Parameters:: statement (InTotoV1Statement | InTotoV01Statement) – The provenance statement from which to extract the build type.
Returns:: The build type if found; otherwise, None.
Return type:: str | None

static find_build_def(statement)

Find the appropriate build definition class based on the extracted build type.

This method checks the provided provenance statement for its build type and returns the corresponding ProvenanceBuildDefinition subclass.

Parameters:: statement (InTotoV01Statement | InTotoV1Statement) – The provenance statement containing the build type information.
Returns:: An instance of the appropriate build definition class that matches the extracted build type.
Return type:: ProvenanceBuildDefinition
Raises:: ProvenanceError – Raised when the build definition cannot be found in the provenance statement.

macaron.provenance.provenance_finder module

This module contains methods for finding provenance files.

class macaron.provenance.provenance_finder.ProvenanceFinder

Bases: object

This class is used to find and retrieve provenance files from supported registries.

__init__()

find_provenance(purl)

Find the provenance file(s) of the passed PURL.

Parameters:: purl (PackageURL) – The PURL to find provenance for.
Returns:: The provenance payload, or an empty list if not found.
Return type:: list[InTotoPayload]

macaron.provenance.provenance_finder.find_npm_provenance(purl, registry)

Find and download the NPM based provenance for the passed PURL.

Two kinds of attestation can be retrieved from npm: “Provenance” and “Publish”. The “Provenance” attestation contains the important information Macaron seeks, but is not signed. The “Publish” attestation is signed. Comparison of the signed vs unsigned at the subject level, allows the unsigned to be verified. See: https://docs.npmjs.com/generating-provenance-statements

Parameters:

purl (PackageURL) – The PURL of the analysis target.
registry (NPMRegistry) – The npm registry to use.

Returns:

The provenance payload(s), or an empty list if not found.

Return type:

list[InTotoPayload]

macaron.provenance.provenance_finder.find_gav_provenance(purl, registry)

Find and download the GAV based provenance for the passed PURL.

Parameters:

purl (PackageURL) – The PURL of the analysis target.
registry (JFrogMavenRegistry) – The registry to use for finding.

Returns:

The provenance payload if found, or an empty list otherwise.

Return type:

list[InTotoPayload] | None

Raises:

ProvenanceAvailableException – If the discovered provenance file size exceeds the configured limit.

macaron.provenance.provenance_finder.find_provenance_from_ci(analyze_ctx, git_obj, download_path)

Try to find provenance from CI services of the repository.

Note that we stop going through the CI services once we encounter a CI service that does host provenance assets.

This method also loads the provenance payloads into the CIInfo object where the provenance assets are found.

Parameters:

analyze_ctx (AnalyzeContext) – The context of the ongoing analysis.
git_obj (Git | None) – The Pydriller Git object representing the repository, if any.
download_path (str) – The pre-existing location to download discovered files to.

Returns:

The provenance payload, or None if not found.

Return type:

InTotoPayload | None

macaron.provenance.provenance_finder.download_provenances_from_ci_service(ci_info, download_path)

Download provenances from GitHub Actions.

Parameters:

ci_info (CIInfo,) – A CIInfo instance that holds a GitHub Actions git service object.
download_path (str) – The pre-existing location to download discovered files to.

Return type:

None

macaron.provenance.provenance_verifier module

This module contains methods for verifying provenance files.

macaron.provenance.provenance_verifier.verify_provenance(purl, provenance)

Verify the passed provenance.

Parameters:

purl (PackageURL) – The PURL of the analysis target.
provenance (list[InTotoPayload]) – The list of provenance.

Returns:

True if the provenance could be verified, or False otherwise.

Return type:

bool

macaron.provenance.provenance_verifier.verify_npm_provenance(purl, provenance)

Compare the unsigned payload subject digest with the signed payload digest, if available.

Parameters:

purl (PackageURL) – The PURL of the analysis target.
provenance (list[InTotoPayload]) – The provenances to verify.

Returns:

True if the provenance was verified, or False otherwise.

Return type:

bool

macaron.provenance.provenance_verifier.check_purls_equivalent(original_purl, new_purl)

Check if new_purl is equivalent to original_purl, excluding versions if the original has none.

Return type:: bool

macaron.provenance.provenance_verifier.verify_ci_provenance(analyze_ctx, ci_info, download_path)

Try to verify the CI provenance in terms of SLSA level 3 requirements.

Involves running the SLSA verifier.

Parameters:

analyze_ctx (AnalyzeContext) – The context of the analysis.
ci_info (CIInfo) – A CIInfo instance that holds a GitHub Actions git service object.
download_path (str) – The location to search for downloaded files.

Returns:

True if the provenance could be verified.

Return type:

bool

macaron.provenance.provenance_verifier.determine_provenance_slsa_level(ctx, provenance_payload, verified, verified_l3)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.
provenance_payload (dict | None) – The provenance payload.
verified (bool) – True if the provenance content is verified.
verified_l3 (bool) – True if the provenance content is level 3 verified.

Returns:

The SLSA level.

Return type:

int