macaron.slsa_analyzer.build_tool package

The build_tool package contains the supported build tools for Macaron.

Submodules

macaron.slsa_analyzer.build_tool.base_build_tool module

This module contains the BaseBuildTool class to be inherited by other specific Build Tools.

class macaron.slsa_analyzer.build_tool.base_build_tool.BuildToolCommand

Bases: TypedDict

This class is an abstraction for build tool commands storing useful contextual data for analysis.

command: list[str]: The parsed build tool command. This command can be any bash command whose program name is the build tool.

language: str: The name of the language to build the artifact.

language_versions: list[str] | None: The list of possible language version numbers.

language_distributions: list[str] | None: The list of possible language distributions.

language_url: str | None: The URL providing information about the language distributions and versions.

ci_path: str: The relative path to the root CI file that ultimately triggers the command.

step_node: BaseNode: The CI step object that calls the command.

reachable_secrets: list[str]: The list of name of reachable variables that contain secrets.”””

events: list[str] | None: The name of CI events that trigger the workflow running the build command.

macaron.slsa_analyzer.build_tool.base_build_tool.file_exists(path, file_name)

Return True if a file exists in a directory.

This method searches in the directory recursively.

Parameters:

path (str) – The path to search for the file.
file_name (str) – The name of the file to search.

Returns:

True if file_name exists else False.

Return type:

bool

class macaron.slsa_analyzer.build_tool.base_build_tool.RuntimeOptions(build_timeout=600)

Bases: object

The class for build tool runtime configurations read from defaults.ini.

Note that Macaron uses the options in this class to “run” a build tool.

build_timeout: float = 600: The timeout used for running the build tool commands.

__init__(build_timeout=600)

class macaron.slsa_analyzer.build_tool.base_build_tool.BaseBuildTool(name, language, purl_type)

Bases: ABC

This abstract class is used to implement Build Tools.

__init__(name, language, purl_type)

Initialize instance.

Parameters:

name (str) – The name of this build tool.
language (BuildLanguage) – The name of the language used by the programs built by the build tool.
purl_type (str) – The type field of a PackageURL.

abstract is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

abstract prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

This method will return False if there is any errors happened during operation.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

abstract load_defaults()

Load the default values from defaults.ini.

Return type:: None

abstract get_dep_analyzer()

Create a DependencyAnalyzer for the build tool.

Returns:: The DependencyAnalyzer object.
Return type:: DependencyAnalyzer

get_build_dirs(repo_path)

Find directories in the repository that have their own build scripts.

This is especially important for applications that consist of multiple services.

Parameters:: repo_path (str) – The path to the target repo.
Yields:: Path – The relative paths from the repo path that contain build scripts.
Return type:: Iterable[Path]

serialize_to_json(cmd)

Convert a list of values to a json-encoded string so that it is easily parsable by later consumers.

Parameters:: cmd (list[str]) – List of command-line arguments.
Returns:: The list of command-line arguments as a json-encoded string.
Return type:: str

is_build_command(cmd)

Determine if the command is a build tool command.

Parameters:: cmd (list[str]) – List of command-line arguments.
Returns:: True if the command is a build tool command.
Return type:: bool

match_cmd_args(cmd, tools, args)

Check if the build command matches any of the tools and the command-line arguments.

If build command’s first element, which is the program name matches any of the tools names and any of its arguments match any of the arguments in args, this function returns True.

Parameters:

cmd (list[str]) – The command-line arguments.
tools (list[str]) – The name of tools that will be matched with the program name in the bash command.
args (list[str]) – The lit of arguments that should match with the bash command.

Returns:

True if the provided command matches the tool and arguments.

Return type:

bool

infer_confidence_deploy_command(cmd)

Infer the confidence level for the deploy command.

Parameters:: cmd (BuildToolCommand) – The build tool command object.
Returns:: The confidence level for the deploy command.
Return type:: Confidence

is_deploy_command(cmd, excluded_configs=None)

Determine if the command is a deploy command.

A deploy command usually performs multiple tasks, such as compilation, packaging, and publishing the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a deploy tool command.

Return type:

tuple[bool, Confidence]

is_package_command(cmd, excluded_configs=None)

Determine if the command is a packaging command.

A packaging command usually performs multiple tasks, such as compilation and creating the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a build tool command.

Return type:

tuple[bool, Confidence]

macaron.slsa_analyzer.build_tool.docker module

This module contains the Docker class which inherits BaseBuildTool.

This module is used to work with repositories that use Docker as a build tool.

class macaron.slsa_analyzer.build_tool.docker.Docker

Bases: BaseBuildTool

This class contains the information of Docker when used as a build tool.

__init__(): Initialize instance.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Make necessary preparations for using this build tool.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the Docker build tool. Currently unimplemented.

Returns:: The NoneDependencyAnalyser object.
Return type:: NoneDependencyAnalyser
Raises:: DependencyAnalyzerError –

macaron.slsa_analyzer.build_tool.go module

This module contains the Go class which inherits BaseBuildTool.

This module is used to work with repositories that have Go.

class macaron.slsa_analyzer.build_tool.go.Go

Bases: BaseBuildTool

This class contains the information of the Go build tool.

__init__()

Initialize instance.

Parameters:

name (str) – The name of this build tool.
language (BuildLanguage) – The name of the language used by the programs built by the build tool.
purl_type (str) – The type field of a PackageURL.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

Go doesn’t require preparation, so return true.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the build tool.

Returns:: The DependencyAnalyzer object.
Return type:: DependencyAnalyzer

macaron.slsa_analyzer.build_tool.gradle module

This module contains the Gradle class which inherits BaseBuildTool.

This module is used to work with repositories that use Gradle build tool.

class macaron.slsa_analyzer.build_tool.gradle.Gradle

Bases: BaseBuildTool

This class contains the information of the Gradle build tool.

__init__(): Initialize instance.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

This method will return False if there is any errors happened during operation.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the Gradle build tool.

Returns:: The CycloneDxGradle object.
Return type:: CycloneDxGradle
Raises:: DependencyAnalyzerError –

get_gradle_exec(repo_path)

Get the Gradle executable for the repo.

Parameters:: repo_path (str) – The absolute path to a repository containing Gradle projects.
Returns:: The absolute path to the Gradle executable.
Return type:: str

get_group_id(gradle_exec, project_path)

Get the group id of a Gradle project.

A Gradle project is a directory containing a build.gradle file. According to the Gradle’s documentation, there is a one-to-one mapping between a “project” and a build.gradle file. See: https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html.

Parameters:

gradle_exec (str) – The absolute path to the Gradle executable.
project_path (str) – The absolute path to the Gradle project.

Returns:

The group id of the project, if exists.

Return type:

str | None

macaron.slsa_analyzer.build_tool.language module

This module contains abstractions for build languages.

class macaron.slsa_analyzer.build_tool.language.BuildLanguage(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The supported build languages.

JAVA = 'java'

PYTHON = 'python'

GO = 'go'

JAVASCRIPT = 'javascript'

DOCKER = 'docker'

class macaron.slsa_analyzer.build_tool.language.Language(*args, **kwargs)

Bases: Protocol

Interface of a language.

property lang_name: str: Get the name of the language.

property lang_versions: list[str] | None: Get the possible versions of the language.

property lang_distributions: list[str] | None: Get the possible distributions of the language.

property lang_url: str | None: Get the URL that provides information about the language distributions and versions.

__init__(*args, **kwargs)

macaron.slsa_analyzer.build_tool.maven module

This module contains the Maven class which inherits BaseBuildTool.

This module is used to work with repositories that use Maven build tool.

class macaron.slsa_analyzer.build_tool.maven.Maven

Bases: BaseBuildTool

This class contains the information of the Maven build tool.

__init__(): Initialize instance.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

This method will return False if there is any errors happened during operation.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the Maven build tool.

Returns:: The CycloneDxMaven object.
Return type:: CycloneDxMaven
Raises:: DependencyAnalyzerError –

macaron.slsa_analyzer.build_tool.npm module

This module contains the NPM class which inherits BaseBuildTool.

This module is used to work with repositories that use npm/pnpm as its build tool.

class macaron.slsa_analyzer.build_tool.npm.NPM

Bases: BaseBuildTool

This class contains the information of the npm/pnpm build tool.

__init__()

Initialize instance.

Parameters:

name (str) – The name of this build tool.
language (BuildLanguage) – The name of the language used by the programs built by the build tool.
purl_type (str) – The type field of a PackageURL.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

npm/pnpm doesn’t require preparation, so return true.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the build tool.

Returns:: The DependencyAnalyzer object.
Return type:: DependencyAnalyzer

is_deploy_command(cmd, excluded_configs=None)

Determine if the command is a deploy command.

A deploy command usually performs multiple tasks, such as compilation, packaging, and publishing the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a deploy tool command.

Return type:

tuple[bool, Confidence]

is_package_command(cmd, excluded_configs=None)

Determine if the command is a packaging command.

A packaging command usually performs multiple tasks, such as compilation and creating the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a build tool command.

Return type:

tuple[bool, Confidence]

macaron.slsa_analyzer.build_tool.pip module

This module contains the Pip class which inherits BaseBuildTool.

This module is used to work with repositories that use pip for dependency management.

class macaron.slsa_analyzer.build_tool.pip.Pip

Bases: BaseBuildTool

This class contains the information of the pip build tool.

__init__(): Initialize instance.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

This method returns False on errors. Pip doesn’t require any preparation, therefore this method always returns True.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the build tool.

Returns:: The DependencyAnalyzer object.
Return type:: DependencyAnalyzer

is_deploy_command(cmd, excluded_configs=None)

Determine if the command is a deploy command.

A deploy command usually performs multiple tasks, such as compilation, packaging, and publishing the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a deploy tool command.

Return type:

tuple[bool, Confidence]

is_package_command(cmd, excluded_configs=None)

Determine if the command is a packaging command.

A packaging command usually performs multiple tasks, such as compilation and creating the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a build tool command.

Return type:

tuple[bool, Confidence]

macaron.slsa_analyzer.build_tool.poetry module

This module contains the Poetry class which inherits BaseBuildTool.

This module is used to work with repositories that use Poetry for dependency management.

class macaron.slsa_analyzer.build_tool.poetry.Poetry

Bases: BaseBuildTool

This class contains the information of the poetry build tool.

__init__(): Initialize instance.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

This method returns False on errors. Poetry doesn’t require any preparation, therefore this method always returns True.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeeds else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the build tool.

Returns:: The DependencyAnalyzer object.
Return type:: DependencyAnalyzer

is_deploy_command(cmd, excluded_configs=None)

Determine if the command is a deploy command.

A deploy command usually performs multiple tasks, such as compilation, packaging, and publishing the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a deploy tool command.

Return type:

tuple[bool, Confidence]

is_package_command(cmd, excluded_configs=None)

Determine if the command is a packaging command.

A packaging command usually performs multiple tasks, such as compilation and creating the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a build tool command.

Return type:

tuple[bool, Confidence]

macaron.slsa_analyzer.build_tool.yarn module

This module contains the Yarn class which inherits BaseBuildTool.

This module is used to work with repositories that use Yarn as its build tool.

class macaron.slsa_analyzer.build_tool.yarn.Yarn

Bases: BaseBuildTool

This class contains the information of the yarn build tool.

__init__()

Initialize instance.

Parameters:

name (str) – The name of this build tool.
language (BuildLanguage) – The name of the language used by the programs built by the build tool.
purl_type (str) – The type field of a PackageURL.

load_defaults()

Load the default values from defaults.ini.

Return type:: None

is_detected(repo_path)

Return True if this build tool is used in the target repo.

Parameters:: repo_path (str) – The path to the target repo.
Returns:: True if this build tool is detected, else False.
Return type:: bool

prepare_config_files(wrapper_path, build_dir)

Prepare the necessary wrapper files for running the build.

yarn doesn’t require preparation, so return true.

Parameters:

wrapper_path (str) – The path where all necessary wrapper files are located.
build_dir (str) – The path of the build dir. This is where all files are copied to.

Returns:

True if succeed else False.

Return type:

bool

get_dep_analyzer()

Create a DependencyAnalyzer for the build tool.

Returns:: The DependencyAnalyzer object.
Return type:: DependencyAnalyzer

is_deploy_command(cmd, excluded_configs=None)

Determine if the command is a deploy command.

A deploy command usually performs multiple tasks, such as compilation, packaging, and publishing the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a deploy tool command.

Return type:

tuple[bool, Confidence]

is_package_command(cmd, excluded_configs=None)

Determine if the command is a packaging command.

A packaging command usually performs multiple tasks, such as compilation and creating the artifact. This function filters the build tool commands that are called from the configuration files provided as input.

Parameters:

cmd (BuildToolCommand) – The build tool command object.
excluded_configs (list[str] | None) – Build tool commands that are called from these configuration files are excluded.

Returns:

Return True along with the inferred confidence level if the command is a build tool command.

Return type:

tuple[bool, Confidence]