Installation Guide

Prerequisites

  • Installations of wget or curl and bash must be available on PATH.

    • Macaron has been tested with bash 5.1.16(1)-release.

  • Docker (or docker equivalent for your host OS) must be installed, with a docker command line equivalent to Docker 17.06 (Oracle Container Runtime 19.03) and the user should be a member of the operating system group docker (to run Docker in rootless mode).

  • We only support amd64 / x86_64 platforms at the moment. As for aarch64 we suggest using UTM in emulator mode coupled with a x86_64 VM.

Download

Macaron is currently distributed as a Docker image and Python package. Note that the Python package is only published as a GitHub release asset. We provide bash scripts to easily download and run Macaron.

Install Macaron as a Docker image

Download the run_macaron.sh script and make it executable by running the commands (replace tag with the version you want or release for the latest version):

curl -O https://raw.githubusercontent.com/oracle/macaron/refs/tags/<tag>/scripts/release_scripts/run_macaron.sh
chmod +x run_macaron.sh

Note

When run, Macaron will create output files inside the current directory where run_macaron.sh is run. If you run Docker Desktop, please make sure that the current directory is bind mountable for Docker (see the File Sharing settings).

Check the Docker Image

To verify your setup, go to the directory containing the downloaded run_macaron.sh script and run this command in order to print out the help message for Macaron:

./run_macaron.sh --help

Note

In the first execution, this script will download the Macaron Docker image from ghcr.io/oracle/macaron which can take some time. However, the next time you run it, the docker image available on your local host will be used.

Note

By default, latest is used as the tag for the downloaded image. You can choose a specific tag by assigning the environment variable MACARON_IMAGE_TAG. For example to run Macaron v0.1.0 run: MACARON_IMAGE_TAG=v0.1.0 ./run_macaron.sh --help

Note

By default, the script will always check the docker registry to ensure the docker image is up-to-date. This can be overridden if necessary (e.g. if running offline with a pre-installed image) by assigning the environment variable DOCKER_PULL. For example: DOCKER_PULL=never ./run_macaron.sh --help

Install Macaron as a Python package

Download the install_macaron_python.sh script and make it executable by running the commands (replace tag with the version you want or release for the latest version):

curl -O https://raw.githubusercontent.com/oracle/macaron/refs/tags/<tag>/scripts/release_scripts/install_macaron_python.sh
chmod +x install_macaron_python.sh

Install the package by providing a version. The installation will automatically create a virtual environment at ./.venv if one does not already exist. The script uses your system’s python3 interpreter, and requires Python 3.11.14 or later to be available:

./install_macaron_python.sh 0.20.0

Macaron might call slsa-verifier for the mcn_provenance_verified_1 check if it is already installed on your machine. You can also pass the --install-slsa-verifier option to the script to install it for you. Note that if slsa-verifier is not installed, we only log an error but proceed with the rest of the analysis. For further information run:

./install_macaron_python.sh --help

If you run Macaron as a Python package and would like to run the verify-policy or gen-build-spec commands, you need to install the Datalog engine souffle separately.

Check the Python package

To verify your setup, activate the virtual environment and run this command in order to print out the help message for Macaron:

source .venv/bin/activate
macaron --help

Prepare GitHub access token

A GitHub access token is always required when using the analyze command (see example below) of Macaron as it may query information from GitHub API about public repositories. More information on this analyze command is can be found in Using Macaron.

./run_macaron.sh analyze <rest_of_arguments>

To obtain a GitHub access token, please see the official instructions here.

Ideally, the GitHub token must have read permissions for the repositories that you want to analyze:

  • Every fine-grained personal-access token should have read permission to public GitHub repositories. However, if you are analyzing a private repository, please select it in the Repository Access section.

  • For classic personal-access token, the repo.public_repo scope must be selected. Please select the whole repo scope if you are running the analysis against private repositories.

After generating a GitHub personal-access token, please store its value in an environment variable called GITHUB_TOKEN. This environment variable will be read by Macaron for its analyze command.

Now that you have successfully downloaded and installed Macaron, please refer to Using Macaron for the instructions on how to use Macaron.

Proxy Configuration

Make sure your system proxy is correctly set. These environment variables are read from the host machine and set in the Macaron container automatically.

$ export {http,https,ftp}_proxy=http://www-example-proxy:80
$ export no_proxy=localhost,127.0.0.1

In order to connect to the registry on behalf of the Docker client, the Docker daemon service needs the proxies in order to download images:

/etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://wwww-example-proxy:80/"
Environment="http_proxy=http://www-example-proxy:80/"
Environment="HTTPS_PROXY=http://www-example-proxy:80/"
Environment="https_proxy=http://www-example-proxy:80/"

The line below shows an example to exclude the proxy intercept:

/etc/systemd/system/docker.service.d/http-proxy.conf
Environment="NO_PROXY=localhost,127.0.0.1"

Note

If you update /etc/systemd/system/docker.service.d/http-proxy.conf, you need to reload the daemon and restart the docker service to apply changes.

sudo systemctl daemon-reload
sudo systemctl restart docker.service

You can run the following command to make sure the proxy settings are updated:

sudo systemctl show --property=Environment docker