Macaron

Macaron is a supply chain security analysis tool from Oracle Labs, which focuses on the build integrity of an artifact and the artifact dependencies. It is based on the Supply chain Levels for Software Artifacts (SLSA) specification, which aims at preventing some of the software supply chain attacks as the systems get more complex, especially with respect to the use of open-source third-party code in applications. Attacks include stealing credentials, injecting malicious code etc., and it is critical to have security assurance on the third-party code to guarantee that the integrity of the code has not been compromised.

Macaron uses SLSA requirements specifications to define concrete rules for protecting software integrity that can be checked for compliance requirements automatically. Macaron provides a customizable checker platform that makes it easy to define checks that depend on each other. This is particularly useful for implementing checks for SLSA levels. In addition, Macaron also checks a user-specified policy for a software component to detect unexpected behavior in the build process. We currently support the following build tools:

• Maven and Gradle Java build systems
• Pip or Poetry package managers for Python
• npm and Yarn for JavaScript
• Go
• Docker

For the full list of supported technologies, such as CI services, registries, and provenance types see this page. Macaron is a work-in-progress project. We plan to support more build systems and technologies in the future.

Table of Contents

• Getting started
• Contributing
• Defining new checks
• Publications
• Security
• License

Getting started

• To learn how to download and run Macaron, see our documentation here.
• Check out our tutorials to see how Macaron can detect software supply chain issues.
• You can also watch this demo to learn more about Macaron.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.

Defining new checks

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 to gather facts and metadata based on a security specification.

To learn how to define your own checks, see the steps in the checks documentation.

Publications

• Behnaz Hassanshahi, Trong Nhan Mai, Alistair Michael, Benjamin Selwyn-Smith, Sophie Bates, and Padmanabhan Krishnan: Macaron: A Logic-based Framework for Software Supply Chain Security Assurance. SCORED 2023. Best paper award 🏆

  @inproceedings{10.1145/3605770.3625213,
    author = {Hassanshahi, Behnaz and Mai, Trong Nhan and Michael, Alistair and Selwyn-Smith, Benjamin and Bates, Sophie and Krishnan, Padmanabhan},
    title = {Macaron: A Logic-Based Framework for Software Supply Chain Security Assurance},
    year = {2023},
    isbn = {9798400702631},
    publisher = {Association for Computing Machinery},
    url = {https://doi.org/10.1145/3605770.3625213},
    doi = {10.1145/3605770.3625213},
    booktitle = {Proceedings of the 2023 Workshop on Software Supply Chain Offensive Research and Ecosystem Defenses},
    pages = {29–37},
    series = {SCORED'23}
  }

Generating SLSA provenances for Macaron itself

We have integrated SLSA provenance generation for our Docker image and release artifacts. However, due to a strict policy regarding the use of third-party GitHub Actions, we cannot generate the provenances in this repository yet until this issue is resolved.

Security

Please consult the security guide for our responsible security vulnerability disclosure process.

License

Copyright (c) 2022, 2024 Oracle and/or its affiliates. Macaron is licensed under the Universal Permissive License (UPL), Version 1.0.