Macaron

Abstract

1. Introduction

For detailed instructions and a comprehensive list of available options, please refer to the Macaron GitHub Action documentation.

This screencast shows how Macaron analyzes the django@5.0.6 Python package and its dependencies. Macaron runs the same set of checks, including malware detection, on the dependencies as it does on the Django package. You can either generate a Software Bill of Materials (SBOM) manually or point Macaron to a virtual environment where Django is installed to automatically analyze the entire dependency tree. The policy engine ensures that the malware detection check passes for all packages in the dependency tree.

2. Objective

Macaron is an extensible supply-chain security analysis framework from Oracle Labs that supports a wide range of build systems and CI/CD services. It can be used to prevent supply chain attacks, detect malicious Python packages, or check conformance to frameworks, such as SLSA. Documentation:

This project demonstrates how Python, Docker can be applied to a real-world Cybersecurity & Ethical Hacking problem.

3. Key Features / Modules

• 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).
• Accurate repository and commit detection for released artifacts, improving traceability and trust (tutorial).

4. Technology Stack

• Java: Maven, Gradle
• Python: pip, Poetry
• JavaScript: npm, Yarn

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Python 3.8 or later
• pip / virtualenv for dependencies
• VS Code, PyCharm or Jupyter Notebook
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/oracle/macaron.git
cd macaron

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

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add logging and alert notifications (email / Telegram)
• Write a threat model document for the tool
• Package it with Docker for safe lab testing

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which threat or attack does this project defend against?
2. What detection or protection technique is used and what are its limits?
3. How are false positives and false negatives handled?
4. Which cryptographic algorithms or security standards are involved?
5. What legal and ethical rules apply when testing a tool like this?

9. Source Code & License

This project is developed by oracle and published on GitHub under the Universal Permissive License v1.0. Please follow the license terms and credit the original author when you use or modify this code.