macaron

Macaron

Macaron is a software supply chain security analysis tool from Oracle Labs focused on verifying the build integrity of artifacts and their dependencies. It helps developers, security teams, and researchers ensure that packages are built as expected and have not been tampered with.

Key Capabilities

Macaron supports:

Attestation verification for third-party and internal artifacts across major ecosystems like PyPI, npm, and Go, enabling automated provenance validation (tutorial).
Detection of malicious or suspicious packages in popular ecosystems using customizable heuristics (tutorial, blog post).
Detection of vulnerable GitHub Actions, which is increasingly important due to recent real-world incidents like tj-actions/changed-files (tutorial).
Reproducible build through static analysis of build scripts. Macaron enables rebuilding packages from source and comparing to released artifacts to detect discrepancies, and therefore compromised workflows or artifacts (paper).
Accurate repository and commit detection for released artifacts, improving traceability and trust (tutorial).

Based on SLSA

Macaron follows the recommendations of the SLSA (Supply chain Levels for Software Artifacts) framework. It offers a flexible, extensible policy engine for checking compliance with SLSA levels. Users can define and compose custom rules tailored to their CI/CD practices and security needs.

Supported Build Tools

Macaron currently supports the following build tools:

Java: Maven, Gradle
Python: pip, Poetry
JavaScript: npm, Yarn
Go
Docker

Adoption

Macaron is integrated into the Graal Development Kit (GDK), where it is used to generate Verification Summary Attestations for each artifact. This helps GDK users validate and trust the integrity of their dependencies (tutorial, blog post).

Learn More

For a complete list of supported technologies, CI providers, and provenance formats, see the documentation.

Macaron is actively evolving, with ongoing work to support more ecosystems and enhance supply chain security capabilities.

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.

Presentations

Securing the Software Supply Chain with Macaron: A Comprehensive Tool for Analysis and Protection, Supply Chain Security Summit 2025.
Towards safeguarding software components from supply chain attacks, Chalmers Security & Privacy Lab Seminars 2024.

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 :trophy:
Behnaz Hassanshahi, Trong Nhan Mai, Benjamin Selwyn-Smith, and Nicholas Allen: Unlocking Reproducibility: Automating re-Build Process for Open-Source Software, ASE Industry Showcase 2025.
Ridwan Shariffdeen, Behnaz Hassanshahi, Martin Mirchev, Ali El Husseini, Abhik Roychoudhury Detecting Python Malware in the Software Supply Chain with Program Analysis, ICSE-SEIP 2025.
Jens Dietrich, Tim White, Behnaz Hassanshahi, Paddy Krishnan Levels of Binary Equivalence for the Comparison of Binaries from Alternative Builds, ICSME Industry Track 2025.
Jens Dietrich, Tim White, Valerio Terragni, Behnaz Hassanshahi Towards Cross-Build Differential Testing, ICST 2025.
Jens Dietrich, Tim White, Mohammad Mahdi Abdollahpour, Elliott Wen, Behnaz Hassanshahi BinEq-A Benchmark of Compiled Java Programs to Assess Alternative Builds, SCORED 2024.
Jens Dietrich and Behnaz Hassanshahi DALEQ–Explainable Equivalence for Java Bytecode, ASE Industry Showcase 2025.

Security

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

License

This site is open source. Improve this page.