You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Macaron is a supply chain security analysis tool from [Oracle Labs](https://labs.oracle.com/pls/apex/r/labs/labs/intro), 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)](https://slsa.dev/) 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.
8
8
9
-
Macaron uses [SLSA requirements specifications](https://slsa.dev/spec/v1.0/levels) 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:
9
+
**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.
10
10
11
-
* Maven and Gradle Java build systems
12
-
* Pip or Poetry package managers for Python
13
-
* npm and Yarn for JavaScript
14
-
* Go
15
-
* Docker
11
+
## Key Capabilities
16
12
17
-
For the full list of supported technologies, such as CI services, registries, and provenance types see [this page](https://oracle.github.io/macaron/pages/supported_technologies/index.html). Macaron is a work-in-progress project. We plan to support more build systems and technologies in the future.
13
+
Macaron supports:
14
+
-**Attestation verification** for third-party and internal artifacts across major ecosystems like PyPI, npm, and Go, enabling automated provenance validation ([tutorial](https://oracle.github.io/macaron/pages/tutorials/npm_provenance.html)).
15
+
-**Detection of malicious or suspicious packages** in popular ecosystems using customizable heuristics ([tutorial](https://oracle.github.io/macaron/pages/tutorials/detect_malicious_package.html), [blog post](https://blogs.oracle.com/developers/post/detecting-malicious-behavior-in-software-supply-chain-part-1)).
16
+
-**Detection of vulnerable GitHub Actions**, which is increasingly important due to recent real-world incidents like [tj-actions/changed-files](https://www.cve.org/CVERecord?id=CVE-2025-30066) ([tutorial](file:///home/behnaz/research/github/macaron/docs/_build/html/pages/tutorials/detect_vulnerable_github_actions.html)).
17
+
-**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](https://arxiv.org/pdf/2410.08427)).
18
+
-**Accurate repository and commit detection** for released artifacts, improving traceability and trust ([tutorial](https://oracle.github.io/macaron/pages/tutorials/source_finder.html)).
19
+
20
+
## Based on SLSA
21
+
22
+
Macaron follows the recommendations of the [SLSA (Supply chain Levels for Software Artifacts)](https://slsa.dev) 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.
23
+
24
+
## Supported Build Tools
25
+
26
+
Macaron currently supports the following build tools:
27
+
-**Java**: Maven, Gradle
28
+
-**Python**: pip, Poetry
29
+
-**JavaScript**: npm, Yarn
30
+
-**Go**
31
+
-**Docker**
32
+
33
+
## Adoption
34
+
35
+
Macaron is integrated into the [Graal Development Kit (GDK)](https://graal.cloud/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](https://oracle.github.io/macaron/pages/tutorials/use_verification_summary_attestation.html), [blog post](https://blogs.oracle.com/java/post/announcing-graal-development-kit-for-micronaut-460)).
36
+
37
+
## Learn More
38
+
39
+
For a complete list of supported technologies, CI providers, and provenance formats, see the [documentation](https://oracle.github.io/macaron/pages/supported_technologies/index.html).
40
+
41
+
Macaron is actively evolving, with ongoing work to support more ecosystems and enhance supply chain security capabilities.
18
42
19
43
## Table of Contents
20
44
@@ -41,28 +65,24 @@ After cloning a repository, Macaron parses the CI configuration files and bash s
41
65
42
66
To learn how to define your own checks, see the steps in the [checks documentation](/src/macaron/slsa_analyzer/checks/README.md).
43
67
68
+
## Presentations
69
+
70
+
*[Securing the Software Supply Chain with Macaron: A Comprehensive Tool for Analysis and Protection](https://labs.oracle.com/pls/apex/f?p=94065:10:15059068980668:11351), Supply Chain Security Summit 2025.
* 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](https://dl.acm.org/doi/abs/10.1145/3605770.3625213). SCORED 2023. Best paper award :trophy:
47
-
```tex
48
-
@inproceedings{10.1145/3605770.3625213,
49
-
author = {Hassanshahi, Behnaz and Mai, Trong Nhan and Michael, Alistair and Selwyn-Smith, Benjamin and Bates, Sophie and Krishnan, Padmanabhan},
50
-
title = {Macaron: A Logic-Based Framework for Software Supply Chain Security Assurance},
51
-
year = {2023},
52
-
isbn = {9798400702631},
53
-
publisher = {Association for Computing Machinery},
54
-
url = {https://doi.org/10.1145/3605770.3625213},
55
-
doi = {10.1145/3605770.3625213},
56
-
booktitle = {Proceedings of the 2023 Workshop on Software Supply Chain Offensive Research and Ecosystem Defenses},
57
-
pages = {29–37},
58
-
series = {SCORED'23}
59
-
}
60
-
```
61
-
62
-
63
-
## Generating SLSA provenances for Macaron itself
64
-
65
-
We have integrated [SLSA provenance generation](https://github.com/slsa-framework/slsa-github-generator) 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](https://github.com/slsa-framework/slsa-github-generator/issues/2204) is resolved.
76
+
* 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](https://dl.acm.org/doi/abs/10.1145/3605770.3625213), SCORED 2023. Best paper award :trophy:
77
+
78
+
* Ridwan Shariffdeen, Behnaz Hassanshahi, Martin Mirchev, Ali El Husseini, Abhik Roychoudhury [Detecting Python Malware in the Software Supply Chain with Program Analysis](https://labs.oracle.com/pls/apex/f?p=94065:10:11591088449483:11569), ICSE-SEIP 2025.
79
+
80
+
* Jens Dietrich, Tim White, Behnaz Hassanshahi, Paddy Krishnan [Levels of Binary Equivalence for the Comparison of Binaries
81
+
from Alternative Builds](https://arxiv.org/pdf/2410.08427), pre-print on arXiv.
* Jens Dietrich, Tim White, Mohammad Mahdi Abdollahpour, Elliott Wen, Behnaz Hassanshahi [BinEq-A Benchmark of Compiled Java Programs to Assess Alternative Builds](https://dl.acm.org/doi/10.1145/3689944.3696162), SCORED 2024.
Copy file name to clipboardExpand all lines: docs/source/index.rst
+5-9Lines changed: 5 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -11,15 +11,11 @@
11
11
Macaron documentation
12
12
=====================
13
13
14
-
Software supply-chain attacks are becoming more prevalent as the systems get more complex, particularly with respect to the use of open-source
15
-
third-party code. Attacks include stealing credentials, tampering with the
16
-
code, tampering with the code repository, and tampering with the build system.
17
-
It is crucial to have guarantees that the third-party code we rely on is the
18
-
code we expect.
19
-
20
-
To tackle these problems, `Supply-chain Levels for Software Artifacts (SLSA or "salsa") <https://slsa.dev>`_ is created to improve the integrity and
21
-
protection of the software supply-chain. Macaron can analyze a software
22
-
repository to determine its SLSA level and provide supply-chain transparency of the build process.
14
+
Macaron is an open-source software supply chain security tool from Oracle Labs to detect and prevent supply chain attacks across ecosystems like Python and Java. It automatically analyzes software packages (e.g., from PyPI or Maven Central) to detect malicious behavior and insecure DevOps practices. Macaron has reported over **225 malicious PyPI packages**, all confirmed and removed by the PyPI security team.
15
+
16
+
Macaron follows the recommendations of the `SLSA (Supply chain Levels for Software Artifacts) <https://slsa.dev>`_ framework. It features a **flexible and extensible policy engine** that allows users to define and compose custom rules tailored to their CI/CD environments and security goals.
17
+
18
+
It also supports **attestation verification**, **reproducible builds**, and **malicious artifact detection**, making it a valuable tool for securing the modern software supply chain.
0 commit comments