macaron package

This module initializes the necessary components for the macaron package.

Subpackages

Submodules

macaron.console module

This module implements a rich console handler for logging.

class macaron.console.RichConsoleHandler(*args, verbose=False, **kwargs)

Bases: RichHandler

A rich console handler for logging with rich formatting and live updates.

__init__(*args, verbose=False, **kwargs)

Initialize the RichConsoleHandler.

Parameters:

verbose (bool, optional) – if True, enables verbose logging, by default False
args (Any) – Variable length argument list.
kwargs (Any) – Arbitrary keyword arguments.

emit(record)

Emit a log record with rich formatting.

Parameters:: record (logging.LogRecord) – The log record to be emitted.
Return type:: None

add_description_table_content(key, value)

Add or update a key-value pair in the description table.

Parameters:

key (str) – The key to be added or updated.
value (str or Status) – The value associated with the key.

Return type:

None

no_of_checks(value)

Initialize the progress bar with the total number of checks.

Parameters:: value (int) – The total number of checks to be performed.
Return type:: None

update_checks(check_id, status='RUNNING')

Update the status of a specific check and refresh the progress table.

Parameters:

check_id (str) – The identifier of the check to be updated.
status (str, optional) – The new status of the check, by default “RUNNING”

Return type:

None

update_checks_summary(checks_summary, total_checks)

Update the summary tables with the results of the checks.

Parameters:

checks_summary (dict) – Dictionary containing lists of checks categorized by their results.
total_checks (int) – The total number of checks.

Return type:

None

update_report_table(report_type, report_path)

Update the report table with the path of a generated report.

Parameters:

report_type (str) – The type of the report (e.g., “HTML Report”, “JSON Report”).
report_path (str) – The relative path to the generated report.

Return type:

None

generate_policy_summary_table()

Generate the policy summary table based on the current policy summary data.

Return type:: None

update_policy_report(report_path)

Update the policy report path in the policy summary.

Parameters:: report_path (str) – The relative path to the policy report.
Return type:: None

update_vsa(vsa_path)

Update the verification summary attestation path.

Parameters:: vsa_path (str) – The relative path to the verification summary attestation.
Return type:: None

update_policy_engine(results)

Update the policy engine results including components that violate or satisfy policies.

Parameters:: results (dict) – Dictionary containing policy engine results including components that violate or satisfy policies, and lists of passed and failed policies.
Return type:: None

update_find_source_table(key, value)

Add or update a key-value pair in the find source table.

Parameters:

key (str) – The key to be added or updated.
value (str or Status) – The value associated with the key.

Return type:

None

update_dump_defaults(value)

Update the dump defaults value.

Parameters:: value (str or Status) – The value to be set for dump defaults.
Return type:: None

update_gen_build_spec(key, value)

Add or update a key-value pair in the generate build spec table.

Parameters:

key (str) – The key to be added or updated.
value (str or Status) – The value associated with the key.

Return type:

None

make_layout()

Create the layout for the live console display.

Returns:: A rich Group object containing the layout for the live console display.
Return type:: Group

error(message)

Handle error logging.

Parameters:: message (str) – The error message to be logged.
Return type:: None

start(command)

Start the live console display.

Parameters:: command (str) – The command being executed (e.g., “analyze”, “verify-policy”).
Return type:: None

close()

Stop the live console display.

Return type:: None

class macaron.console.AccessHandler

Bases: object

A class to manage access to the RichConsoleHandler instance.

__init__(): Initialize the AccessHandler with a default RichConsoleHandler instance.

set_handler(verbose)

Set a new RichConsoleHandler instance with the specified verbosity.

Parameters:: verbose (bool) – if True, enables verbose logging
Returns:: The new RichConsoleHandler instance.
Return type:: RichConsoleHandler

get_handler()

Get the current RichConsoleHandler instance.

Returns:: The current RichConsoleHandler instance.
Return type:: RichConsoleHandler

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.GitTagError

Bases: MacaronError

Happens when there is a Git tag related error.

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.APIAccessError

Bases: MacaronError

Happens when a service API cannot be accessed.

Reasons can include:

misconfiguration issues
invalid API request
network errors
unexpected response returned by the API

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.

exception macaron.errors.HeuristicAnalyzerValueError

Bases: MacaronError

Error class for BaseHeuristicAnalyzer errors when parsing data.

exception macaron.errors.LocalArtifactFinderError

Bases: MacaronError

Happens when there is an error looking for local artifacts.

exception macaron.errors.SourceCodeError

Bases: MacaronError

Error for operations on package source code.

exception macaron.errors.CommandLineParseError

Bases: Exception

Raised if an error is encountered while parsing a CLI Command.

exception macaron.errors.PatchBuildCommandError

Bases: Exception

Raised if an error is encountered while patching a Maven CLI Command.

exception macaron.errors.QueryMacaronDatabaseError

Bases: Exception

Happens when there is an unexpected error while querying the database using SQLAlchemy.

exception macaron.errors.GenerateBuildSpecError

Bases: Exception

Happens when there is an unexpected error while generating the build spec file.

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_head_http_raw(url, headers=None, timeout=None, allow_redirects=True)

Send the HEAD 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.send_get_http_raw(url, headers=None, timeout=None, allow_redirects=True, check_response_fails=True, stream=False)

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.
check_response_fails (bool) – When True, check if the response fails. Otherwise, return the response.
stream (bool) – Indicates whether the response should be immediately downloaded (False) or streamed (True). Default: False.

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. If check_response_fails is False, the response will be returned regardless of its status code.

Return type:

Response | None

macaron.util.send_post_http_raw(url, json_data=None, headers=None, timeout=None, allow_redirects=True)

Send a POST HTTP request with the given url, data, and headers.

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

Parameters:

url (str) – The url of the request.
json_data (dict | None) – The request payload.
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

class macaron.util.StreamWriteDownloader(file)

Bases: object

A class to handle writing a streamed download to a file.

__init__(file): Initialise the class with the file path.

chunk_function(chunk)

Write the chunk to the file.

Return type:: None

macaron.util.can_download_file(url, size_limit, timeout=None)

Send a head request to check if the file provided at url can be downloaded within the size limit.

It expects a URL to a file, and checks the “Content-Length” field of the response.

Parameters:

url (str) – The target of the request.
size_limit (int) – The size limit in bytes of the file.
timeout (int | None) – The request timeout (optional).

Returns:

True if the file can be downloaded within the size limit, False otherwise.

Return type:

bool

macaron.util.download_file_with_size_limit(url, headers, file_path, timeout=40, size_limit=0)

Download a file with a size limit that will abort the operation if exceeded.

Parameters:

url (str) – The target of the request.
headers (dict) – The headers to use in the request.
file_path (str) – The path to download the file to.
timeout (int) – The timeout in seconds for the request.
size_limit (int) – The size limit in bytes of the downloaded file. A download will terminate if it reaches beyond this amount.

Returns:

True if the operation succeeded, False otherwise.

Return type:

bool

macaron.util.stream_file_with_size_limit(url, headers, chunk_function, timeout=40, size_limit=0)

Stream a file download and perform the passed function on the chunks of its data.

If data in excess of the size limit is received, this operation will be aborted.

Parameters:

url (str) – The target of the request.
headers (dict) – The headers to use in the request.
chunk_function (Callable[[bytes], None]) – The function to use with each downloaded chunk.
timeout (int) – The timeout in seconds for the request.
size_limit (int) – The size limit in bytes of the downloaded file. A download will terminate if it reaches beyond this amount. The default value of zero disables the limit.

Returns:

True if the operation succeeded, False otherwise.

Return type:

bool

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