macaron.slsa_analyzer.ci_service package

The ci_service package contains the supported CI services for Macaron.

Subpackages

Submodules

macaron.slsa_analyzer.ci_service.base_ci_service module

This module contains the BaseCIService class to be inherited by a CI service.

class macaron.slsa_analyzer.ci_service.base_ci_service.BaseCIService(name)

Bases: object

This abstract class is used to implement CI services.

__init__(name)

Initialize instance.

Parameters:

name (str) – The name of the CI service.

abstract load_defaults()

Load the default values from defaults.ini.

Return type:

None

abstract set_api_client()

Set the API client using the personal access token.

Return type:

None

abstract get_workflows(repo_path)

Get all workflows in a repository.

Parameters:

repo_path (str) – The path to the repository.

Returns:

The list of workflow files in this repository.

Return type:

list

is_detected(repo_path, git_service=None)

Return True if this CI service is used in the target repo.

Parameters:

  • repo_path (str) – The path to the target repo.

  • git_service (BaseGitService) – The Git service that hosts the target repo (currently an unused argument).

Returns:

True if this CI service is detected, else False.

Return type:

bool

abstract build_call_graph(repo_path, macaron_path='')

Build the call Graph for this CI service.

Parameters:

  • repo_path (str) – The path to the repo.

  • macaron_path (str) – Macaron’s root path (optional).

Returns:

CallGraph – The call graph built for the CI.

Return type:

CallGraph

has_kws_in_config(kws, build_tool_name, repo_path)

Check the content of all config files in a repository for any build keywords.

For now, it only checks the file content directly.

Parameters:

  • kws (list) – The list of keywords to check.

  • build_tool_name (str) – The name of the target build tool.

  • repo_path (str) – The path to the target repo.

Returns:

keywordstr

The keyword that was found.

configstr

The config file name that the keyword was found in.

Return type:

tuple[keyword, config]

has_latest_run_passed(repo_full_name, branch_name, commit_sha, commit_date, workflow)

Get the latest run of a workflow in the repository.

This workflow run must be based on the latest commit according to the commit sha in the Analyze context.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • branch_name (str | None) – The target branch.

  • commit_sha (str) – The commit sha of the target repo.

  • commit_date (str) – The commit date of the target repo.

  • workflow (str) – The name of the workflow file (e.g build.yml).

Returns:

The feed back of the check, or empty if no passing workflow is found.

Return type:

str

workflow_run_in_date_time_range(repo_full_name, workflow, date_time, step_name, step_id, time_range=0)

Check if the repository has a workflow run started before the date_time timestamp within the time_range.

  • This method queries the list of workflow runs using the GitHub API for the provided repository full name.

  • It will filter out the runs that are not triggered by the given workflow.

  • It will only accept the runs that from date_time - time_range to date_time.

  • If a step_name is provided, checks that it has started before the date_time and has succeeded.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • workflow (str) – The workflow URL.

  • date_time (datetime) – The datetime object to query.

  • step_name (str) – The step in the GitHub Action workflow that needs to be checked.

  • time_range (int) – The date-time range in seconds. The default value is 0. For example a 30 seconds range for 2022-11-05T20:30 is 2022-11-05T20:15..2022-11-05T20:45.

Returns:

The set of URLs found for the workflow within the time range.

Return type:

set[str]

get_build_tool_commands(callgraph, build_tool)

Traverse the callgraph and find all the reachable build tool commands.

Parameters:

  • callgraph (CallGraph) – The callgraph reachable from the CI workflows.

  • build_tool (BaseBuildTool) – The corresponding build tool for which shell commands need to be detected.

Yields:

BuildToolCommand – The object that contains the build command as well useful contextual information.

Raises:

CallGraphError – Error raised when an error occurs while traversing the callgraph.

Return type:

Iterable[BuildToolCommand]

get_third_party_configurations()

Get the list of third-party CI configuration files.

Returns:

The list of third-party CI configuration files

Return type:

list[str]

class macaron.slsa_analyzer.ci_service.base_ci_service.NoneCIService

Bases: BaseCIService

This class can be used to initialize an empty CI service.

__init__()

Initialize instance.

get_workflows(repo_path)

Get all workflows in a repository.

Parameters:

repo_path (str) – The path to the repository.

Returns:

The list of workflow files in this repository.

Return type:

list

load_defaults()

Load the default values from defaults.ini.

Return type:

None

set_api_client()

Set the API client using the personal access token.

Return type:

None

build_call_graph(repo_path, macaron_path='')

Build the call Graph for this CI service.

Parameters:

  • repo_path (str) – The path to the repo.

  • macaron_path (str) – Macaron’s root path (optional).

Returns:

CallGraph – The call graph built for the CI.

Return type:

CallGraph

get_build_tool_commands(callgraph, build_tool)

Traverse the callgraph and find all the reachable build tool commands.

Parameters:

  • callgraph (CallGraph) – The callgraph reachable from the CI workflows.

  • build_tool (BaseBuildTool) – The corresponding build tool for which shell commands need to be detected.

Yields:

BuildToolCommand – The object that contains the build command as well useful contextual information.

Raises:

CallGraphError – Error raised when an error occurs while traversing the callgraph.

Return type:

Iterable[BuildToolCommand]

has_latest_run_passed(repo_full_name, branch_name, commit_sha, commit_date, workflow)

Get the latest run of a workflow in the repository.

This workflow run must be based on the latest commit according to the commit sha in the Analyze context.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • branch_name (str | None) – The target branch.

  • commit_sha (str) – The commit sha of the target repo.

  • commit_date (str) – The commit date of the target repo.

  • workflow (str) – The name of the workflow file (e.g build.yml).

Returns:

The feed back of the check, or empty if no passing workflow is found.

Return type:

str

get_third_party_configurations()

Get the list of third-party CI configuration files.

Returns:

The list of third-party CI configuration files

Return type:

list[str]

macaron.slsa_analyzer.ci_service.circleci module

This module analyze Circle CI.

class macaron.slsa_analyzer.ci_service.circleci.CircleCI

Bases: BaseCIService

This class implements CircleCI service.

__init__()

Initialize instance.

get_workflows(repo_path)

Get all workflows in a repository.

Parameters:

repo_path (str) – The path to the repository.

Returns:

The list of workflow files in this repository.

Return type:

list

load_defaults()

Load the default values from defaults.ini.

Return type:

None

set_api_client()

Set the API client using the personal access token.

Return type:

None

build_call_graph(repo_path, macaron_path='')

Build the call Graph for this CI service.

Parameters:

  • repo_path (str) – The path to the repo.

  • macaron_path (str) – Macaron’s root path (optional).

Returns:

CallGraph – The call graph built for the CI.

Return type:

CallGraph

has_latest_run_passed(repo_full_name, branch_name, commit_sha, commit_date, workflow)

Get the latest run of a workflow in the repository.

This workflow run must be based on the latest commit according to the commit sha in the Analyze context.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • branch_name (str | None) – The target branch.

  • commit_sha (str) – The commit sha of the target repo.

  • commit_date (str) – The commit date of the target repo.

  • workflow (str) – The name of the workflow file (e.g build.yml).

Returns:

The feed back of the check, or empty if no passing workflow is found.

Return type:

str

macaron.slsa_analyzer.ci_service.gitlab_ci module

This module analyzes GitLab CI.

class macaron.slsa_analyzer.ci_service.gitlab_ci.GitLabCI

Bases: BaseCIService

This class implements GitLab CI service.

__init__()

Initialize instance.

get_workflows(repo_path)

Get all workflows in a repository.

Parameters:

repo_path (str) – The path to the repository.

Returns:

The list of workflow files in this repository.

Return type:

list

load_defaults()

Load the default values from defaults.ini.

Return type:

None

set_api_client()

Set the API client using the personal access token.

Return type:

None

build_call_graph(repo_path, macaron_path='')

Build the call Graph for this CI service.

Parameters:

  • repo_path (str) – The path to the repo.

  • macaron_path (str) – Macaron’s root path (optional).

Returns:

CallGraph – The call graph built for the CI.

Return type:

CallGraph

has_latest_run_passed(repo_full_name, branch_name, commit_sha, commit_date, workflow)

Get the latest run of a workflow in the repository.

This workflow run must be based on the latest commit according to the commit sha in the Analyze context.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • branch_name (str | None) – The target branch.

  • commit_sha (str) – The commit sha of the target repo.

  • commit_date (str) – The commit date of the target repo.

  • workflow (str) – The name of the workflow file (e.g build.yml).

Returns:

The feed back of the check, or empty if no passing workflow is found.

Return type:

str

macaron.slsa_analyzer.ci_service.jenkins module

This module analyzes Jenkins CI.

class macaron.slsa_analyzer.ci_service.jenkins.Jenkins

Bases: BaseCIService

This class implements Jenkins CI service.

__init__()

Initialize instance.

get_workflows(repo_path)

Get all workflows in a repository.

Parameters:

repo_path (str) – The path to the repository.

Returns:

The list of workflow files in this repository.

Return type:

list

load_defaults()

Load the default values from defaults.ini.

Return type:

None

set_api_client()

Set the API client using the personal access token.

Return type:

None

build_call_graph(repo_path, macaron_path='')

Build the call Graph for this CI service.

Parameters:

  • repo_path (str) – The path to the repo.

  • macaron_path (str) – Macaron’s root path (optional).

Returns:

CallGraph – The call graph built for the CI.

Return type:

CallGraph

has_latest_run_passed(repo_full_name, branch_name, commit_sha, commit_date, workflow)

Get the latest run of a workflow in the repository.

This workflow run must be based on the latest commit according to the commit sha in the Analyze context.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • branch_name (str | None) – The target branch.

  • commit_sha (str) – The commit sha of the target repo.

  • commit_date (str) – The commit date of the target repo.

  • workflow (str) – The name of the workflow file (e.g build.yml).

Returns:

The feed back of the check, or empty if no passing workflow is found.

Return type:

str

macaron.slsa_analyzer.ci_service.travis module

This module analyzes Travis CI.

class macaron.slsa_analyzer.ci_service.travis.Travis

Bases: BaseCIService

This class implements Travis CI service.

__init__()

Initialize instance.

get_workflows(repo_path)

Get all workflows in a repository.

Parameters:

repo_path (str) – The path to the repository.

Returns:

The list of workflow files in this repository.

Return type:

list

load_defaults()

Load the default values from defaults.ini.

Return type:

None

set_api_client()

Set the API client using the personal access token.

Return type:

None

build_call_graph(repo_path, macaron_path='')

Build the call Graph for this CI service.

Parameters:

  • repo_path (str) – The path to the repo.

  • macaron_path (str) – Macaron’s root path (optional).

Returns:

CallGraph – The call graph built for the CI.

Return type:

CallGraph

has_latest_run_passed(repo_full_name, branch_name, commit_sha, commit_date, workflow)

Get the latest run of a workflow in the repository.

This workflow run must be based on the latest commit according to the commit sha in the Analyze context.

Parameters:

  • repo_full_name (str) – The target repo’s full name.

  • branch_name (str | None) – The target branch.

  • commit_sha (str) – The commit sha of the target repo.

  • commit_date (str) – The commit date of the target repo.

  • workflow (str) – The name of the workflow file (e.g build.yml).

Returns:

The feed back of the check, or empty if no passing workflow is found.

Return type:

str