macaron.slsa_analyzer.ci_service.github_actions package

Submodules

macaron.slsa_analyzer.ci_service.github_actions.github_actions_ci module

This module analyzes GitHub Actions CI.

class macaron.slsa_analyzer.ci_service.github_actions.github_actions_ci.GitHubActions

Bases: BaseCIService

This class contains the spec of the GitHub Actions.

__init__()

Initialize instance.

set_api_client()

Set the GitHub client using the personal access token.

Return type:

None

load_defaults()

Load the default values from defaults.ini.

Return type:

None

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 hosting the target repo.

Returns:

True if this CI service is detected, else False.

Return type:

bool

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

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

Check if the latest run of workflow on commit commit_sha is passing.

This method queries for the list of workflow runs only from GitHub API using the repository full name. It will first perform a search using branch_name and commit_date as filters. If that failed, it will perform the same search but without any filtering.

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 URL for the passing workflow run, or empty if no passing GitHub Action build workflow is found.

Return type:

str

check_publish_start_commit_timestamps(started_at, publish_date_time, commit_date_time, time_range)

Check if the timestamps of CI run, artifact publishing, and commit date are within the acceptable time range and valid.

This function checks that the CI run has happened before the artifact publishing timestamp.

This function also verifies whether the commit date is within an acceptable time range from the publish start time. The acceptable range is defined as half of the provided time range parameter.

Parameters:

  • started_at (datetime) – The timestamp indicating when the GitHub Actions workflow started.

  • publish_date_time (datetime) – The timestamp indicating when the artifact is published.

  • commit_date_time (datetime) – The timestamp of the source code commit.

  • time_range (int) – The total acceptable time range in seconds.

Returns:

True if the commit date is within the acceptable range from the publish start time,

False otherwise. Returns False in case of any errors during timestamp comparisons.

Return type:

bool

workflow_run_in_date_time_range(repo_full_name, workflow, publish_date_time, commit_date_time, job_id, step_name, step_id, time_range=0, callee_node_type=None)

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 | None) – The name of the step in the GitHub Action workflow that needs to be checked.

  • step_id (str | None) – The ID of 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.

Returns:

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

Return type:

set[str]

Raises:

GitHubActionsValueError – This error is raised when the GitHub Action workflow run misses values.

workflow_run_deleted(timestamp)

Check if the CI run data is deleted based on a retention policy.

Parameters:

timestamp (datetime) – The timestamp of the CI run.

Returns:

True if the CI run data is deleted.

Return type:

bool

search_for_workflow_run(workflow_id, commit_sha, full_name, branch_name=None, created_after=None)

Search for the target workflow run using GitHub API.

This method will perform a query to get workflow runs. It will then look through each run data to determine the target workflow run. It will only stop if:

  • There are no results left

  • It reaches the maximum number of results (1000) allowed by GitHub API

  • It finds the workflow run we are looking for

Parameters:

  • workflow_id (str) – The unique id of the workflow file obtained through GitHub API.

  • commit_sha (str) – The digest of the commit the workflow run on.

  • full_name (str) – The full name of the repository (e.g. owner/repo).

  • branch_name (str | None) – The branch name to filter out workflow runs.

  • created_after (str | None) – Only look for workflow runs after this date (e.g. 2022-03-11T16:44:40Z).

Returns:

The response data of the latest workflow run or an empty dict if error.

Return type:

dict

has_kws_in_log(latest_run, build_log)

Check the build log of this workflow run to see if it has build keywords.

Parameters:

  • latest_run (dict) – The latest run data from GitHub API.

  • build_log (list) – The list of kws used to analyze the build log.

Returns:

Whether the build log has build kw in it.

Return type:

bool

build_call_graph(repo_path, macaron_path='')

Build the call Graph for GitHub Actions workflows.

At the moment it does not analyze third-party workflows to include their callees.

Parameters:

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

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

Returns:

CallGraph – The call graph built for GitHub Actions.

Return type:

CallGraph

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]