Full Documentation | Tutorials | Videos | Papers | Presentations
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.
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).
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.
Macaron currently supports the following build tools:
- Java: Maven, Gradle
- Python: pip, Poetry
- JavaScript: npm, Yarn
- Go
- Docker
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).
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.
- 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.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.
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.
-
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.
-
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 🏆
-
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, pre-print on arXiv.
-
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.
Please consult the security guide for our responsible security vulnerability disclosure process.
Copyright (c) 2022, 2024 Oracle and/or its affiliates. Macaron is licensed under the Universal Permissive License (UPL), Version 1.0.