Macaron documentation

Software supply-chain attacks are becoming more prevalent as the systems get more complex, particularly with respect to the use of open-source third-party code. Attacks include stealing credentials, tampering with the code, tampering with the code repository, and tampering with the build system. It is crucial to have guarantees that the third-party code we rely on is the code we expect.

To tackle these problems, Supply-chain Levels for Software Artifacts (SLSA or “salsa”) is created to improve the integrity and protection of the software supply-chain. Macaron can analyze a software repository to determine its SLSA level and provide supply-chain transparency of the build process.

Overview

Macaron is an analysis tool which focuses on the build process for an artifact and its dependencies. As the SLSA requirements are at a high-level, Macaron first defines these requirements as specific concrete rules that can be checked automatically. Macaron has a customizable checker platform that makes it easy to define checks that depend on each other.

Getting started

To start with Macaron, see the Installation and Using pages.

For all services and technologies that Macaron supports, see the Supported Technologies page.

Current checks in Macaron

The table below shows the current set of actionable checks derived from the requirements that are currently supported by Macaron.

Mapping SLSA requirements to Macaron checks
Check ID	SLSA requirement	Concrete check
`mcn_build_script_1`	Scripted build - All build steps were fully defined in a “build script”.	Identify and validate build script(s).
`mcn_provenance_available_1`	Provenance available - Provenances are available.	Check for existence of provenances, which can be SLSA or Witness provenances. If there is no provenance, the repo can still be compliant to level 1 given the build script is available.
`mcn_provenance_witness_level_one_1`	Witness provenance - One or more Witness provenances are discovered.	Check for existence of Witness provenances, and whether artifact digests match those in the provenances.
`mcn_build_service_1`	Build service - All build steps are run using some build service (e.g. GitHub Actions)	Identify and validate the CI service(s) used for the build process.
`mcn_provenance_verified_1`	Provenance verified - Provenance is available and verified.	See SLSA Build Levels
`mcn_trusted_builder_level_three_1`	Trusted builders - Guarantees the identification of the top-level build configuration used to initiate the build. The build is verified to be hermetic, isolated, parameterless, and executed in an ephemeral environment.	Identify and validate that the builder used in the CI pipeline is a trusted one.
`mcn_build_as_code_1`	Build as code - If a trusted builder is not present, this requirement determines that the build definition and configuration executed by the build service is verifiably derived from text file definitions stored in a version control system.	Identify and validate the CI service(s) used to build and deploy/publish an artifact.
`mcn_infer_artifact_pipeline_1`	Infer artifact publish pipeline - When a provenance is not available, checks whether a CI workflow run has automatically published the artifact.	Identify a workflow run that has triggered the deploy step determined by the `Build as code` check.
`mcn_provenance_level_three_1`	Provenance Level three - Check whether the target has SLSA provenance level 3.	Use the slsa-verifier to attest to the subjects in the SLSA provenance that accompanies an artifact.
`mcn_provenance_expectation_1`	Provenance expectation - Check if the provenance meets an expectation.	The user can provide an expectation for the provenance as a CUE expectation file, which will be compared against the provenance.
`mcn_provenance_derived_repo_1`	Provenance derived repo - Check if the analysis target’s repository matches the repository in the provenance.	If there is no provenance, this check will fail.
`mcn_provenance_derived_commit_1`	Provenance derived commit - Check if the analysis target’s commit matches the commit in the provenance.	If there is no commit, this check will fail.

Macaron checks that report integrity issues but do not map to SLSA requirements directly

Check ID	Description
`mcn_detect_malicious_metadata_1`	This check analyzes the metadata of a package and reports malicious behavior. This check currently supports PyPI packages.

How does Macaron work?

Macaron infrastructure — Macaron’s infrastructure

Macaron is designed based on a Zero Trust model. It analyzes a target repository as an external tool and requires minimal configurations. After cloning a repository, Macaron parses the CI configuration files and bash scripts that are triggered by the CI, creates call graphs and other intermediate representations as abstractions. Using such abstractions, Macaron implements concrete checks based on a security specification and verifies the desired properties.