macaron.slsa_analyzer.checks package

Import Checks for running and importing from other packages.

Submodules

macaron.slsa_analyzer.checks.base_check module

This module contains the BaseCheck class to be inherited by other concrete Checks.

class macaron.slsa_analyzer.checks.base_check.BaseCheck(check_id='', description='', depends_on=None, eval_reqs=None, result_on_skip=CheckResultType.SKIPPED)

Bases: object

This abstract class is used to implement Checks in Macaron.

__init__(check_id='', description='', depends_on=None, eval_reqs=None, result_on_skip=CheckResultType.SKIPPED)

Initialize instance.

Parameters:

  • check_id (str) – The id of the check.

  • description (str) – The description of the check.

  • depends_on (list[tuple[str, CheckResultType]] | None) – The list of parent checks that this check depends on. Each member of the list is a tuple of the parent’s id and the status of that parent check.

  • eval_reqs (list[ReqName] | None) – The list of SLSA requirements that this check addresses.

  • result_on_skip (CheckResultType) – The status for this check when it’s skipped based on another check’s result.

property check_info: CheckInfo

Get the information identifying/describing this check.

property depends_on: list[tuple[str, CheckResultType]]

Get the list of parent checks that this check depends on.

Each member of the list is a tuple of the parent’s id and the status of that parent check.

property result_on_skip: CheckResultType

Get the status for this check when it’s skipped based on another check’s result.

run(target, skipped_info=None)

Run the check and return the results.

Parameters:

  • target (AnalyzeContext) – The object containing processed data for the target repo.

  • skipped_info (SkippedInfo | None) – Determine whether the check is skipped.

Returns:

The result of the check.

Return type:

CheckResult

abstract run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.build_as_code_check module

This module contains the BuildAsCodeCheck class.

class macaron.slsa_analyzer.checks.build_as_code_check.BuildAsCodeFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in build_as_code check.

id: Mapped[int]

The primary key.

build_tool_name: Mapped[str]

The name of the tool used to build.

ci_service_name: Mapped[str]

The CI service name used to build and deploy.

build_trigger: Mapped[str]

The entrypoint script that triggers the build and deploy.

language: Mapped[str]

The language of the artifact built by build tool command.

language_distributions: Mapped[str | None]

The possible language distributions.

language_versions: Mapped[str | None]

The possible language versions.

language_url: Mapped[str | None]

The URL that provides information about the language distributions and versions.

deploy_command: Mapped[str]

The command used to deploy.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.build_as_code_check.BuildAsCodeCheck

Bases: BaseCheck

This class checks the build as code requirement.

See https://slsa.dev/spec/v0.1/requirements#build-as-code.

__init__()

Initiate the BuildAsCodeCheck instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.build_script_check module

This module contains the BuildScriptCheck class.

class macaron.slsa_analyzer.checks.build_script_check.BuildScriptFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in build_script check.

id: Mapped[int]

The primary key.

build_tool_name: Mapped[str]

The name of the tool used to build.

ci_service_name: Mapped[str]

The CI service name used to build and deploy.

build_trigger: Mapped[str]

The entrypoint script that triggers the build and deploy.

language: Mapped[str]

The language of the artifact built by build tool command.

language_distributions: Mapped[str | None]

The possible language distributions.

language_versions: Mapped[str | None]

The possible language versions.

language_url: Mapped[str | None]

The URL that provides information about the language distribution and version.

build_tool_command: Mapped[str]

The build tool command.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.build_script_check.BuildScriptCheck

Bases: BaseCheck

This Check checks whether the target repo has a valid build script.

__init__()

Initiate the BuildScriptCheck instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.build_service_check module

This module contains the BuildServiceCheck class.

class macaron.slsa_analyzer.checks.build_service_check.BuildServiceFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in build_service check.

id: Mapped[int]

The primary key.

build_tool_name: Mapped[str]

The name of the tool used to build.

ci_service_name: Mapped[str]

The CI service name used to build.

build_trigger: Mapped[str]

The entrypoint script that triggers the build.

build_command: Mapped[str]

The command used to build.

language: Mapped[str]

The language of the artifact built by build tool command.

language_distributions: Mapped[str | None]

The possible language distributions.

language_versions: Mapped[str | None]

The possible language versions.

language_url: Mapped[str | None]

The URL that provides information about the language distribution and version.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.build_service_check.BuildServiceCheck

Bases: BaseCheck

This Check checks whether the target repo has a valid build service.

__init__()

Initiate the BuildServiceCheck instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.check_result module

This module contains the CheckResult class for storing the result of a check.

class macaron.slsa_analyzer.checks.check_result.CheckResultType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

This class contains the types of a check result.

PASSED = 'PASSED'
FAILED = 'FAILED'
SKIPPED = 'SKIPPED'
DISABLED = 'DISABLED'
UNKNOWN = 'UNKNOWN'
class macaron.slsa_analyzer.checks.check_result.Evidence(name, found, weight)

Bases: object

The class representing an evidence generated by a check.

name: str

The name of the evidence.

found: bool

Determines whether the was evidence is found.

weight: float

The weight of the evidence.

__init__(name, found, weight)
class macaron.slsa_analyzer.checks.check_result.EvidenceWeightMap(evidence_list)

Bases: object

This class creates a map object for collected evidence.

__init__(evidence_list)

Initialize the class.

Parameters:

evidence_list (list[Evidence]) – The list of evidences.

add(evidence)

Add an evidence to the map.

Parameters:

evidence (Evidence) – The evidence object.

Return type:

None

update_result(name, found)

Update the result if an evidence is found.

Parameters:

found (bool) – True if evidence was found.

Return type:

None

get_max_score()

Get the maximum possible score in this map.

Returns:

The maximum possible score or zero if the map is empty.

Return type:

float

get_score()

Compute the score using the evidence result and weights.

Returns:

The aggregate score or zero if the map is empty.

Return type:

float

class macaron.slsa_analyzer.checks.check_result.Confidence(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: float, Enum

This class contains confidence score for a check result.

The scores must be in the range [0.0, 1.0].

HIGH = 1.0

A high confidence score.

MEDIUM = 0.7

A medium confidence score.

LOW = 0.4

A low confidence score.

classmethod normalize(evidence_weight_map)

Normalize the score based on the provided evidence weight map.

The values in the evidence weight map are expected to be positive. Expect invalid results if negative weights are passed to this function.

Parameters:

evidence_weight_map (EvidenceWeightMap) – The map that contains the detected evidence and their corresponding weight.

Return type:

Confidence

class macaron.slsa_analyzer.checks.check_result.JustificationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

This class contains the type of a justification that will be used in creating the HTML report.

TEXT = 'text'

If a justification has a text type, it will be added as a plain text.

HREF = 'href'

If a justification has a href type, it will be added as a hyperlink.

class macaron.slsa_analyzer.checks.check_result.CheckInfo(check_id, check_description, eval_reqs)

Bases: object

This class identifies and describes a check.

check_id: str

The id of the check.

check_description: str

The description of the check.

eval_reqs: list[ReqName]

The list of SLSA requirements that this check addresses.

__init__(check_id, check_description, eval_reqs)
class macaron.slsa_analyzer.checks.check_result.CheckResultData(result_tables, result_type)

Bases: object

This class stores the result of a check.

result_tables: list[CheckFacts]

List of result tables produced by the check.

result_type: CheckResultType

Result type of the check (e.g. PASSED).

property justification_report: list[tuple[Confidence, list]]

Return a sorted list of justifications based on confidence scores in descending order.

These justifications are generated from the tables in the database. Note that the elements in the justification will be rendered differently based on their types:

Return type:

list[tuple[Confidence, list]]

__init__(result_tables, result_type)
class macaron.slsa_analyzer.checks.check_result.CheckResult(check, result)

Bases: object

This class stores the result of a check, including the description of the check that produced it.

check: CheckInfo

Info about the check that produced these results.

result: CheckResultData

The results produced by the check.

get_summary()

Get a flattened dictionary representation for this CheckResult, in a format suitable for the output report.

The SLSA requirements, in particular, are translated into a list of their textual descriptions, to be suitable for display to users in the output report (as opposed to the internal representation as a list of enum identifiers).

Return type:

dict

__init__(check, result)
class macaron.slsa_analyzer.checks.check_result.SkippedInfo

Bases: TypedDict

This class stores the information about a skipped check.

check_id: str
suppress_comment: str
macaron.slsa_analyzer.checks.check_result.get_result_as_bool(check_result_type)

Return the CheckResultType as bool.

This method returns True only if the result type is PASSED else it returns False.

Parameters:

check_result_type (CheckResultType) – The check result type to return the bool value.

Return type:

bool

macaron.slsa_analyzer.checks.detect_malicious_metadata_check module

This check examines the metadata of pypi packages with seven heuristics.

class macaron.slsa_analyzer.checks.detect_malicious_metadata_check.MaliciousMetadataFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in pypi heuristic check.

id: Mapped[int]

The primary key.

detail_information: Mapped[dict[str, int | float | str | None | bool | list[JsonType] | dict[str, JsonType]]]

Detailed information about the analysis.

result: Mapped[dict[Heuristics, HeuristicResult]]

The result of analysis, which is of dict[Heuristics, HeuristicResult] type.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.detect_malicious_metadata_check.DetectMaliciousMetadataCheck

Bases: BaseCheck

This check analyzes the metadata of a package for malicious behavior.

__init__()

Initialize a check instance.

run_heuristics(pypi_package_json)

Run the analysis heuristics.

Parameters:

pypi_package_json (PyPIPackageJsonAsset) – The PyPI package JSON asset object.

Returns:

Containing the analysis results and relevant metadata.

Return type:

tuple[dict[Heuristics, HeuristicResult], dict[str, JsonType]]

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.infer_artifact_pipeline_check module

This module contains the InferArtifactPipelineCheck class to check if an artifact is published from a pipeline automatically.

class macaron.slsa_analyzer.checks.infer_artifact_pipeline_check.InferArtifactPipelineFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications of the infer_artifact_pipeline check.

id: Mapped[int]

The primary key.

deploy_job: Mapped[str]

The workflow job that triggered deploy.

deploy_step: Mapped[str]

The workflow step that triggered deploy.

run_url: Mapped[str]

The workflow run URL.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.infer_artifact_pipeline_check.InferArtifactPipelineCheck

Bases: BaseCheck

This check detects a potential pipeline from which an artifact is published.

When a verifiable provenance is found for an artifact, the result of this check can be discarded. Otherwise, we check whether a CI workflow run has automatically published the artifact.

We use several heuristics in this check:

  • The workflow run should have started before the artifact is published.

  • The workflow step that calls a deploy command should have run successfully.

  • The workflow step that calls a deploy command should have started before the artifact is published.

Note: due to a limitation, we cannot specify the provenance checks as parents of this check because a check cannot have more than one parent in the current design. It would be good to skip this with a success result if the relevant provenance checks pass in the future.

__init__()

Initialize the InferArtifactPipeline instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result type of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_available_check module

This module contains the implementation of the Provenance Available check.

exception macaron.slsa_analyzer.checks.provenance_available_check.ProvenanceAvailableException

Bases: MacaronError

When there is an error while checking if a provenance is available.

class macaron.slsa_analyzer.checks.provenance_available_check.ProvenanceAvailableFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in provenance_available check.

id: Mapped[int]

The primary key.

asset_name: Mapped[str]

The provenance asset name.

asset_url: Mapped[str]

The URL for the provenance asset.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.provenance_available_check.ProvenanceAvailableCheck

Bases: BaseCheck

This Check checks whether the target repo has in-toto provenance.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_commit_check module

This module adds a check that determines whether the repository URL came from provenance.

class macaron.slsa_analyzer.checks.provenance_commit_check.ProvenanceDerivedCommitFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in the commit from provenance check.

id: Mapped[int]

The primary key.

commit_info: Mapped[str]

The state of the commit.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.provenance_commit_check.ProvenanceDerivedCommitCheck

Bases: BaseCheck

This check tries to extract the repo from the provenance and compare it to what is in the context.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_l3_check module

This module implements a check to verify a target repo has intoto provenance level 3.

class macaron.slsa_analyzer.checks.provenance_l3_check.ProvenanceL3VerifiedFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in provenance_l3 check.

id: Mapped[int]

The primary key.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.provenance_l3_check.ProvenanceL3Check

Bases: BaseCheck

This Check checks whether the target repo has SLSA provenance level 3.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_l3_content_check module

This module checks if a SLSA provenance conforms to a given expectation.

class macaron.slsa_analyzer.checks.provenance_l3_content_check.ProvenanceL3ContentCheck

Bases: BaseCheck

This check compares a SLSA provenance with a given expectation and checks whether they match.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_repo_check module

This module adds a check that determines whether the repository URL came from provenance.

class macaron.slsa_analyzer.checks.provenance_repo_check.ProvenanceDerivedRepoFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in the repository from provenance check.

id: Mapped[int]

The primary key.

repository_info: Mapped[str]

The state of the repository.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.provenance_repo_check.ProvenanceDerivedRepoCheck

Bases: BaseCheck

This check tries to extract the repo from the provenance and compare it to what is in the context.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_verified_check module

This module adds a Check that checks whether the provenance is verified.

class macaron.slsa_analyzer.checks.provenance_verified_check.ProvenanceVerifiedFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in the provenance verified check.

id: Mapped[int]

The primary key.

build_level: Mapped[int]
build_type: Mapped[str]
__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.provenance_verified_check.ProvenanceVerifiedCheck

Bases: BaseCheck

This Check checks whether the provenance is flagged as verified in the context.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.provenance_witness_l1_check module

This check examines a witness provenance (https://github.com/testifysec/witness).

exception macaron.slsa_analyzer.checks.provenance_witness_l1_check.WitnessProvenanceException

Bases: MacaronError

When there is an error while processing a Witness provenance.

class macaron.slsa_analyzer.checks.provenance_witness_l1_check.WitnessProvenanceAvailableFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in provenance l3 check.

id: Mapped[int]

The primary key.

provenance_name: Mapped[str]

The provenance asset name.

provenance_url: Mapped[str]

The URL for the provenance asset.

artifact_url: Mapped[str]

The URL for the artifact asset.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

macaron.slsa_analyzer.checks.provenance_witness_l1_check.verify_artifact_assets(artifact_assets, subjects)

Verify artifact assets against subjects in the witness provenance payload.

Parameters:
Returns:

True if verification succeeds and False otherwise.

Return type:

bool

Raises:

WitnessProvenanceException – If a subject is not a file attested by the Witness product attestor.

class macaron.slsa_analyzer.checks.provenance_witness_l1_check.ProvenanceWitnessL1Check

Bases: BaseCheck

This check examines a Witness provenance (https://github.com/testifysec/witness).

At the moment, we are only checking the actual digests of the artifacts against the digests in the provenance.

__init__()

Initialize a check instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.trusted_builder_l3_check module

This module contains the TrustedBuilderL3Check class.

class macaron.slsa_analyzer.checks.trusted_builder_l3_check.TrustedBuilderFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in trusted_builder.

id: Mapped[int]

The primary key.

build_tool_name: Mapped[str]

The name of the tool used to build.

ci_service_name: Mapped[str]

The CI service name used to build.

build_trigger: Mapped[str]

The entrypoint script that triggers the build.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.trusted_builder_l3_check.TrustedBuilderL3Check

Bases: BaseCheck

This Check checks whether the target repo uses level 3 builders.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData

macaron.slsa_analyzer.checks.vcs_check module

This module contains the implementation of the VCS check.

class macaron.slsa_analyzer.checks.vcs_check.VCSFacts(**kwargs)

Bases: CheckFacts

The ORM mapping for justifications in the vcs check.

id: Mapped[int]

The primary key.

git_repo: Mapped[str]

The Git repository path.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

check_result_id: Mapped[int]

The foreign key to the check result.

check_type: Mapped[str]

The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped['MappedCheckResult']

A many-to-one relationship with check results.

component: Mapped['Component']

A many-to-one relationship with software components.

component_id: Mapped[int]

The foreign key to the software component.

confidence: Mapped[float]

The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

class macaron.slsa_analyzer.checks.vcs_check.VCSCheck

Bases: BaseCheck

This Check checks whether the target repo uses a version control system.

__init__()

Initialize instance.

run_check(ctx)

Implement the check in this method.

Parameters:

ctx (AnalyzeContext) – The object containing processed data for the target repo.

Returns:

The result of the check.

Return type:

CheckResultData