macaron package

This module initializes the necessary components for the macaron package.

Subpackages

• macaron.code_analyzer package
• macaron.config package
• macaron.database package
• macaron.dependency_analyzer package
• macaron.malware_analyzer package
• macaron.output_reporter package
• macaron.parsers package
• macaron.policy_engine package
• macaron.repo_finder package
• macaron.slsa_analyzer package
• macaron.vsa package

Submodules

macaron.environment_variables module

Helper functions related to environment variables.

macaron.environment_variables.get_patched_env(patch, _env=None)

Return a dictionary whose elements copied from os.environ and are updated according to patch.

This function does not modify os.environ.

Parameters:

• patch (Mapping[str, str | None]) – A mapping (immutable) in which: - each key is an environment variable. - each value is the value to set to the corresponding environment variable. If value is None, the environment variable is “unset”.

• _env (dict[str, str] | None) – The environment being updated. This is None by default, in which case os.environ is being updated.

Returns:

The the dictionary contains the patched env variables.

Return type:

dict[str, str]

macaron.errors module

This module contains error classes for Macaron.

exception macaron.errors.MacaronError

Bases: Exception

The base class for Macaron errors.

exception macaron.errors.InvalidExpectationError

Bases: MacaronError

Happens when the provenance expectation is invalid.

exception macaron.errors.ExpectationRuntimeError

Bases: MacaronError

Happens if there are errors while validating the expectation against a target.

exception macaron.errors.CUEExpectationError

Bases: MacaronError

Happens when the CUE expectation is invalid.

exception macaron.errors.CUERuntimeError

Bases: MacaronError

Happens when there are errors in CUE expectation validation.

exception macaron.errors.ConfigurationError

Bases: MacaronError

Happens when there is an error in the configuration (.ini) file.

exception macaron.errors.CloneError

Bases: MacaronError

Happens when cannot clone a git repository.

exception macaron.errors.RepoCheckOutError

Bases: MacaronError

Happens when there is an error when checking out the correct revision of a git repository.

exception macaron.errors.RepoNotFoundError

Bases: MacaronError

Happens if a repository is not found.

exception macaron.errors.PURLNotFoundError

Bases: MacaronError

Happens if the PURL identifier for a software component is not found.

exception macaron.errors.InvalidPURLError

Bases: MacaronError

Happens when the input PURL string is invalid.

exception macaron.errors.DuplicateError

Bases: MacaronError

The class for errors for duplicated data.

exception macaron.errors.InvalidHTTPResponseError

Bases: MacaronError

Happens when the HTTP response is invalid or unexpected.

exception macaron.errors.CheckRegistryError

Bases: MacaronError

The Check Registry Error class.

exception macaron.errors.ProvenanceError

Bases: MacaronError

When there is an error while extracting from provenance.

exception macaron.errors.InvalidAnalysisTargetError

Bases: MacaronError

When a valid Analysis Target cannot be constructed.

exception macaron.errors.ParseError

Bases: MacaronError

The errors related to parsers.

exception macaron.errors.CallGraphError

Bases: MacaronError

The errors related to callgraphs.

exception macaron.errors.GitHubActionsValueError

Bases: MacaronError

The errors related to GitHub Actions value errors.

exception macaron.errors.CycloneDXParserError

Bases: MacaronError

The CycloneDX error class.

exception macaron.errors.DependencyAnalyzerError

Bases: MacaronError

The DependencyAnalyzer error class.

macaron.json_tools module

This module provides utility functions for JSON data.

macaron.json_tools.json_extract(entry, keys, type_)

Return the value found by following the list of depth-sequential keys inside the passed JSON dictionary.

The value must be of the passed type.

Parameters:

• entry (dict | list) – An entry point into a JSON structure.

• keys (Sequence[str | int]) – The sequence of depth-sequential keys within the JSON. Can be dict keys or list indices.

• type (type[T]) – The type to check the value against and return it as.

Returns:

The found value as the type of the type parameter.

Return type:

T | None

macaron.util module

This module includes utilities functions for Macaron.

macaron.util.send_get_http(url, headers)

Send the GET HTTP request with the given url and headers.

This method also handle logging when the server return error status code.

Parameters:

• url (str) – The url of the request.

• headers (dict) – The dictionary to be included as the header of the request.

Returns:

The response’s json data or an empty dict if there is an error.

Return type:

dict

macaron.util.send_get_http_raw(url, headers=None, timeout=None, allow_redirects=True)

Send the GET HTTP request with the given url and headers.

This method also handle logging when the API server return error status code.

Parameters:

• url (str) – The url of the request.

• headers (dict | None) – The dict that describes the headers of the request.

• timeout (int | None) – The request timeout (optional).

• allow_redirects (bool) – Whether to allow redirects. Default: True.

Returns:

If a Response object is returned and allow_redirects is True (the default) it will have a status code of 200 (OK). If allow_redirects is False the response can instead have a status code of 302. Otherwise, the request has failed and None will be returned.

Return type:

Response | None

macaron.util.check_rate_limit(response)

Check the remaining calls limit to GitHub API and wait accordingly.

Parameters:

response (Response) – The latest response from GitHub API.

Return type:

None

macaron.util.construct_query(params)

Construct a URL query from the provided keywords params.

Parameters:

params (dict) – The dictionary of parameters for the search.

Returns:

The constructed query as string.

Return type:

str

Examples

>>> construct_query({"bar":1,"foo":2})
'bar=1&foo=2'

macaron.util.download_github_build_log(url, headers)

Download and return the build log from a GitHub API build log url.

Parameters:

• url (str) – The url of the request.

• headers (dict) – The dict that describes the headers of the request.

Returns:

The content of the downloaded build log or empty if error.

Return type:

str

macaron.util.copy_file(src, dest_dir)

Copy a file using shutil.copy2.

This copy operation will preserve the permission of the src file.

Parameters:

• src (str) – The path of the source file.

• dest_dir (str) – The destination path to copy to.

Returns:

True if succeed else False.

Return type:

bool

macaron.util.copy_file_bulk(file_list, src_path, target_path)

Copy multiple files using the copy_file method.

Files in file_list will be copied from src_path to target_path.

If a file in file_list exists in target_path, it will be ignored. This method will handle creating intermediate dirs to store files accordingly.

Parameters:

• file_list (list) – The list of file path need to be copied. These are relative path from src_path.

• src_path (str) – The absolute path of the source dir.

• target_path (str) – The absolute path to the target dir where all files will be copied.

Returns:

True if succeed else False.

Return type:

bool

See also

copy_file

Copy a single file.

Examples

file.txt will be copied from src/foo/bar/file.txt to target/foo/bar/file.txt

copy_file_bulk(["foo/bar/file.txt"], "src", "target")