macaron.dependency_analyzer package

This package contains the dependency resolvers.

Submodules

macaron.dependency_analyzer.cyclonedx module

This module contains helper functions to process CycloneDX SBOM.

macaron.dependency_analyzer.cyclonedx.deserialize_bom_json(file_path)

Deserialize the bom.json file.

Parameters:: file_path (str) – Path to the bom.json file.
Returns:: The CycloneDX Bom object.
Return type:: Bom
Raises:: CycloneDXParserError – If the bom.json file cannot be located or deserialized.

class macaron.dependency_analyzer.cyclonedx.DependencyTools(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Dependency resolvers supported by Macaron.

CYCLONEDX_MAVEN = 'cyclonedx-maven'

CYCLONEDX_GRADLE = 'cyclonedx-gradle'

CYCLONEDX_PYTHON = 'cyclonedx_py'

class macaron.dependency_analyzer.cyclonedx.DependencyInfo

Bases: TypedDict

The information of a resolved dependency.

purl: PackageURL

url: str

note: str

available: SCMStatus

class macaron.dependency_analyzer.cyclonedx.DependencyAnalyzer(resources_path, file_name, tool_name, tool_version)

Bases: ABC

This abstract class is used to implement dependency analyzers.

__init__(resources_path, file_name, tool_name, tool_version)

Initialize the dependency analyzer instance.

Parameters:

resources_path (str) – The path to the resources directory.
file_name (str) – The name of dependency output file.
tool_name (str) – The name of the dependency analyzer.
tool_version (str) – The version of the dependency analyzer.

abstract collect_dependencies(dir_path, target_component)

Process the dependency JSON files and collect direct dependencies.

Parameters:

dir_path (str) – Local path to the target repo.
target_component (Component) – The analyzed target software component.

Returns:

A dictionary where artifacts are grouped based on “artifactId:groupId”.

Return type:

dict

abstract remove_sboms(dir_path)

Remove all the SBOM files in the provided directory recursively.

Parameters:: dir_path (str) – Path to the repo.
Returns:: Returns True if all the files are removed successfully.
Return type:: bool

abstract get_cmd()

Return the CLI command to run the dependency analyzer.

Returns:: The command line arguments.
Return type:: list

abstract get_purl_from_cdx_component(component)

Construct and return a PackageURL from a CycloneDX component.

Parameters:: component (CDXComponent)
Returns:: The PackageURL object constructed from the CycloneDX component.
Return type:: PackageURL

static add_latest_version(item, key, all_versions, latest_deps, url_to_artifact)

Find and add the unique URL for the latest version of the artifact.

Parameters:

item (DependencyInfo) – The dictionary containing info about the dependency to be added.
key (str) – The ID of the artifact.
all_versions (dict[str, str]) – Stores all the versions of dependencies for debugging.
latest_deps (dict[str, DependencyInfo]) – Stores the latest version of dependencies.
url_to_artifact (dict[str, set]) – Used to detect artifacts that have similar repos.

Return type:

None

static merge_configs(config_deps, resolved_deps)

Merge the resolved dependencies into the manual config dependencies.

Manual configuration entries are prioritized over the automatically resolved dependencies.

Parameters:

config_deps (list[Configuration]) – Dependencies defined in the configuration file.
resolved_deps (dict[str, DependencyInfo]) – The automatically resolved dependencies.

Returns:

The result list contains the merged dependencies.

Return type:

list[Configuration]

static tool_valid(tool)

Validate the dependency analyzer name.

Parameters:: tool (str) – The full name of the dependency analyzer, i.e., <name>:<version>.
Returns:: Return True if the tool name is valid.
Return type:: bool

static resolve_dependencies(main_ctx, sbom_path)

Resolve the dependencies of the main target repo.

Parameters:

main_ctx (Any (AnalyzeContext)) – The context of object of the target repository.
sbom_path (str) – The path to the SBOM.

Returns:

A dictionary where artifacts are grouped based on artifactId:groupId.

Return type:

dict[str, DependencyInfo]

get_root_component(root_bom_path)

Get the root dependency component.

Parameters:: root_bom_path (str) – Path to the root bom.json file.
Returns:: The root CycloneDX component.
Return type:: CDXComponent | None

get_target_cdx_component(root_bom, target_component)

Get the CycloneDX component that matches the analyzed target software component.

Parameters:

root_bom (Bom) – The top-level BOM file.
target_component (Component) – The analyzed target software component.

Returns:

The CycloneDX component or None if it cannot be found.

Return type:

CDXComponent | None

get_dep_components(target_component, root_bom_path, child_bom_paths=None, recursive=False)

Get CycloneDX components that are dependencies of the analyzed target software component.

Parameters:

target_component (Component) – The analyzed target software component.
root_bom_path (str) – Path to the root bom.json file.
child_bom_paths (list[Path] | None) – The list of paths to sub-project bom.json files.
recursive (bool) – Set to False to get the direct dependencies only (default).

Yields:

CDXComponent – The dependencies as CycloneDX components.

Return type:

Iterable[Component]

convert_components_to_artifacts(components, root_component=None)

Convert CycloneDX components using internal artifact representation.

Parameters:

components (Iterable[CDXComponent]) – The dependency components.
root_component (CDXComponent | None) – The root CycloneDX component.

Returns:

A dictionary where dependency artifacts are grouped based on “groupId:artifactId”.

Return type:

dict

get_deps_from_sbom(sbom_path, target_component)

Get the dependencies from a provided SBOM.

Parameters:

sbom_path (str | Path) – The path to the SBOM file.
target_component (Component) – The analyzed target software component.

Return type:

dict[str, DependencyInfo]

Returns:

A dictionary where dependency artifacts are grouped based on “groupId:artifactId”.

class macaron.dependency_analyzer.cyclonedx.NoneDependencyAnalyzer

Bases: DependencyAnalyzer

This class is used to implement an empty dependency analyzers.

__init__(): Initialize the dependency analyzer instance.

collect_dependencies(dir_path, target_component)

Process the dependency JSON files and collect direct dependencies.

Parameters:

dir_path (str) – Local path to the target repo.
target_component (Component) – The analyzed target software component.

Returns:

A dictionary where artifacts are grouped based on “artifactId:groupId”.

Return type:

dict

remove_sboms(dir_path)

Remove all the SBOM files in the provided directory recursively.

Parameters:: dir_path (str) – Path to the repo.
Returns:: Returns True if all the files are removed successfully.
Return type:: bool

get_cmd()

Return the CLI command to run the dependency analyzer.

Returns:: The command line arguments.
Return type:: list

get_purl_from_cdx_component(component)

Construct and return a PackageURL from a CycloneDX component.

Parameters:: component (CDXComponent)
Returns:: The PackageURL object constructed from the CycloneDX component.
Return type:: PackageURL

macaron.dependency_analyzer.cyclonedx_gradle module

This module processes the JSON dependency output files generated by CycloneDX Gradle plugin.

It also collects the direct dependencies that should be processed by Macaron. See https://github.com/CycloneDX/cyclonedx-gradle-plugin.

class macaron.dependency_analyzer.cyclonedx_gradle.CycloneDxGradle(resources_path, file_name, tool_name, tool_version)

Bases: DependencyAnalyzer

This class implements the CycloneDX Gradle plugin analyzer.

get_cmd()

Return the CLI command to run the CycloneDX Gradle plugin.

Returns:: The command line arguments.
Return type:: list

collect_dependencies(dir_path, target_component)

Process the dependency JSON files and collect direct dependencies.

Parameters:

dir_path (str) – Local path to the target repo.
target_component (Component) – The analyzed target software component.

Returns:

A dictionary where artifacts are grouped based on “artifactId:groupId”.

Return type:

dict

remove_sboms(dir_path)

Remove all the SBOM files in the provided directory recursively.

Parameters:: dir_path (str) – Path to the repo.
Returns:: Returns True if all the files are removed successfully.
Return type:: bool

get_purl_from_cdx_component(component)

Construct and return a PackageURL from a CycloneDX component.

Parameters:: component (CDXComponent)
Returns:: The PackageURL object constructed from the CycloneDX component.
Return type:: PackageURL

macaron.dependency_analyzer.cyclonedx_mvn module

This module processes the JSON dependency output files generated by CycloneDX Maven plugin.

It also collects the direct dependencies that should be processed by Macaron. See https://github.com/CycloneDX/cyclonedx-maven-plugin.

class macaron.dependency_analyzer.cyclonedx_mvn.CycloneDxMaven(resources_path, file_name, tool_name, tool_version)

Bases: DependencyAnalyzer

This class implements the CycloneDX Maven plugin analyzer.

get_cmd()

Return the CLI command to run the CycloneDX Maven plugin.

Returns:: The command line arguments.
Return type:: list

collect_dependencies(dir_path, target_component)

Process the dependency JSON files and collect direct dependencies.

We allow the dependency JSON files to be accepted as long as there is only one JSON file in the target directory. If a file with the expected name is found, it is accepted, otherwise any lone file is accepted instead. This is because projects can be configured to produce a custom named SBOM, which cannot be overridden if included at the parent POM level. The presence of multiple JSON files within a target directory differs too greatly from the expectations of the plugin’s output. It is for this reason that an error is thrown in such cases.

Parameters:

dir_path (str) – Local path to the target repo.
target_component (Component) – The analyzed target software component.

Returns:

A dictionary where artifacts are grouped based on “artifactId:groupId”.

Return type:

dict

remove_sboms(dir_path)

Remove all the SBOM files in the provided directory recursively.

Parameters:: dir_path (str) – Path to the repo.
Returns:: Returns True if all the files are removed successfully.
Return type:: bool

get_purl_from_cdx_component(component)

Construct and return a PackageURL from a CycloneDX component.

Parameters:: component (CDXComponent)
Returns:: The PackageURL object constructed from the CycloneDX component.
Return type:: PackageURL

macaron.dependency_analyzer.cyclonedx_python module

This module processes the JSON dependency output files generated by CycloneDX Maven plugin.

It also collects the direct dependencies that should be processed by Macaron. See https://github.com/CycloneDX/cyclonedx-maven-plugin.

class macaron.dependency_analyzer.cyclonedx_python.CycloneDxPython(resources_path, file_name, tool_name, tool_version)

Bases: DependencyAnalyzer

This class implements the CycloneDX Maven plugin analyzer.

get_cmd()

Return the CLI command to run the CycloneDX Maven plugin.

Returns:: The command line arguments.
Return type:: list

collect_dependencies(dir_path, target_component)

Process the dependency JSON files and collect dependencies.

Parameters:

dir_path (str) – Local path to the target repo.
target_component (Component) – The analyzed target software component.

Returns:

A dictionary where artifacts are grouped based on “artifactId:groupId”.

Return type:

dict

remove_sboms(dir_path)

Remove all the SBOM files in the provided directory recursively.

Parameters:: dir_path (str) – Path to the repo.
Returns:: Returns True if all the files are removed successfully.
Return type:: bool

get_purl_from_cdx_component(component)

Construct and return a PackageURL from a CycloneDX component.

Parameters:: component (CDXComponent)
Returns:: The PackageURL object constructed from the CycloneDX component.
Return type:: PackageURL