chore: create a new release

.github/workflows/test_macaron_action.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2025 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 name: Test Macaron Action (tutorials)
@@ -111,7 +111,7 @@ jobs:
     - name: Run Macaron (analyze purl - log4j-core example)
       uses: ./
       with:
-        package_url: pkg:maven/org.apache.logging.log4j/log4j-core@3.0.0-beta3
+        package_url: pkg:maven/org.apache.logging.log4j/log4j-core@2.25.3
         output_dir: macaron_output/detect_vulnerable_github_actions
 
     - name: Run Macaron (verify policy - github_actions_vulns for purl)
@@ -184,7 +184,7 @@ jobs:
         package_url: pkg:maven/io.github.behnazh-w.demo/example-maven-app@2.0?type=jar
         repo_path: https://github.com/behnazh-w/example-maven-app
         output_dir: macaron_output/detect_malicious_java_dep
-        sbom_path: ./resources/detect_malicious_java_dep/example-sbom.json
+        sbom_path: ./tests/tutorial_resources/detect_malicious_java_dep/example-sbom.json
         deps_depth: '1'
 
     - name: Run Macaron (verify policy - detect-malicious-upload)

.gitignore

@@ -167,6 +167,7 @@ gradlew.bat
 .macaron
 reports
 output
+output_dir
 cdx_debug.json
 sbom_debug.json
 golang/internal/filewriter/mock_dir/result.json

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # See https://pre-commit.com for more information
@@ -224,7 +224,7 @@ repos:
 
 # A linter for Golang
 - repo: https://github.com/golangci/golangci-lint
-  rev: v2.3.0
+  rev: v2.8.0
   hooks:
   - id: golangci-lint
 
@@ -236,7 +236,7 @@ repos:
 # Other staged files shouldn't trigger these hooks.
 # Documentation: https://github.com/TekWizely/pre-commit-golang/blob/v1.0.0-rc.1/README.md.
 - repo: https://github.com/tekwizely/pre-commit-golang
-  rev: v1.0.0-rc.1
+  rev: v1.0.0-rc.4
   hooks:
   - id: go-build-mod
   - id: go-build-repo-mod

CONTRIBUTING.md

@@ -85,7 +85,7 @@ Please see the [README for the malware analyzer](./src/macaron/malware_analyzer/
 ### Prerequisites
 
 - Python 3.11.14
-- Go 1.23
+- Go 1.24
 - JDK 17
 
 ### Prepare the environment
@@ -116,6 +116,12 @@ make setup
 
 **Note**: Running the above command will prompt you for sudo access to install [Soufflé Datalog engine](https://github.com/souffle-lang/souffle). You can install Soufflé on your system before running `make setup` to avoid getting prompted.
 
+**Note**: The [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) dependency needs to be installed separately using the following command. This dependency is only used to verify some provenances, so you might not always need it for development.
+
+```bash
+make install-slsa-verifier
+```
+
 With that in place, you’re ready to build and contribute to Macaron!
 
 ### Updating dependent packages

Makefile

@@ -1,16 +1,39 @@
-# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # Use bash as the shell when executing a rule's recipe. For more details:
 # https://www.gnu.org/software/make/manual/html_node/Choosing-the-Shell.html
 SHELL := bash
 
-# Set the package's name, version, and path for use throughout the Makefile.
+# Set the package's name and version for use throughout the Makefile.
 PACKAGE_NAME := macaron
 PACKAGE_VERSION := $(shell python -c $$'try: import $(PACKAGE_NAME); print($(PACKAGE_NAME).__version__);\nexcept: print("unknown");')
+
+# Determine the OS,architecture, and number of cores.
+OS := $(shell uname -s)
+ifeq ($(OS),Darwin)
+  PLATFORM_NAME := macosx
+  OS_DISTRO := "Darwin"
+else
+  ifeq ($(OS),Linux)
+	PLATFORM_NAME := linux
+    OS_DISTRO := "$(shell grep '^NAME=' /etc/os-release | sed 's/^NAME=//' | sed 's/"//g')"
+    OS_MAJOR_VERSION := "$(shell grep '^VERSION=' /etc/os-release | sed -r 's/^[^0-9]+([0-9]+)\..*/\1/')"
+  endif
+endif
+ARCH := $(shell uname -m)
+NPROC := $(shell nproc)
+
+# Construct short package identifier.
+PACKAGE_SDIST_NAME := $(PACKAGE_NAME)-$(PACKAGE_VERSION)
+
+# Construct full package identifier.
+PACKAGE_WHEEL_DIST_NAME := $(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-$(PLATFORM_NAME)_$(ARCH)
+
+# Set the Python version, package, and repo paths.
+PYTHON ?= python3.11
 PACKAGE_PATH := $(shell pwd)/src/$(PACKAGE_NAME)
 REPO_PATH := $(shell pwd)
-PYTHON ?= python3.11
 
 # This variable contains the first goal that matches any of the listed goals
 # here, else it contains an empty string. The net effect is to filter out
@@ -93,26 +116,28 @@ setup: force-upgrade setup-go setup-binaries setup-schemastore
 	go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.3.0
 setup-go:
 	go build -o $(PACKAGE_PATH)/bin/ $(REPO_PATH)/golang/cmd/...
-setup-binaries: $(PACKAGE_PATH)/bin/slsa-verifier souffle gnu-sed
+setup-binaries: souffle gnu-sed
 
-# Install SLSA Verifier.
+# Install SLSA Verifier if not already installed.
+# Get the checksum from https://github.com/slsa-framework/slsa-verifier/blob/main/SHA256SUM.md.
 SLSA_VERIFIER_TAG := v2.7.1
 SLSA_VERIFIER_BIN := slsa-verifier-linux-amd64
-SLSA_VERIFIER_BIN_PATH := $(PACKAGE_PATH)/bin/$(SLSA_VERIFIER_BIN)
-SLSA_VERIFIER_PROVENANCE := $(SLSA_VERIFIER_BIN).intoto.jsonl
-SLSA_VERIFIER_PROVENANCE_PATH := $(PACKAGE_PATH)/bin/$(SLSA_VERIFIER_PROVENANCE)
-
-$(PACKAGE_PATH)/bin/slsa-verifier:
-	mkdir -p $(PACKAGE_PATH)/bin \
-    	&& wget -O $(PACKAGE_PATH)/bin/slsa-verifier https://github.com/slsa-framework/slsa-verifier/releases/download/$(SLSA_VERIFIER_TAG)/$(SLSA_VERIFIER_BIN) \
-    	&& wget -O $(SLSA_VERIFIER_PROVENANCE_PATH) https://github.com/slsa-framework/slsa-verifier/releases/download/$(SLSA_VERIFIER_TAG)/$(SLSA_VERIFIER_PROVENANCE) \
-    	&& chmod +x $(PACKAGE_PATH)/bin/slsa-verifier \
-		&& EXPECTED_HASH=$$(jq -r '.payload' $(SLSA_VERIFIER_PROVENANCE_PATH) | base64 -d | jq -r '.subject[] | select(.name == "$(SLSA_VERIFIER_BIN)") | .digest.sha256') \
-		&& ACTUAL_HASH=$$(sha256sum $(PACKAGE_PATH)/bin/slsa-verifier | awk '{print $$1}'); \
-		if [ "$$EXPECTED_HASH" != "$$ACTUAL_HASH" ]; then \
-			echo "Hash mismatch: expected $$EXPECTED_HASH, got $$ACTUAL_HASH"; \
-			exit 1; \
-		fi
+SLSA_VERIFIER_BIN_PATH := $(HOME)/.local/bin
+SLSA_VERIFIER_CHECKSUM := 946dbec729094195e88ef78e1734324a27869f03e2c6bd2f61cbc06bd5350339
+.PHONY: install-slsa-verifier
+install-slsa-verifier:
+	if ! command -v slsa-verifier >/dev/null 2>&1; then \
+	  mkdir -p $(SLSA_VERIFIER_BIN_PATH) \
+	    && curl --fail -L -o $(SLSA_VERIFIER_BIN_PATH)/slsa-verifier https://github.com/slsa-framework/slsa-verifier/releases/download/$(SLSA_VERIFIER_TAG)/$(SLSA_VERIFIER_BIN) \
+	    && SLSA_VERIFIER_COMPUTED_HASH=$$(sha256sum $(SLSA_VERIFIER_BIN_PATH)/slsa-verifier | cut -d' ' -f1) \
+	    && if [ $$SLSA_VERIFIER_COMPUTED_HASH != $(SLSA_VERIFIER_CHECKSUM) ]; then \
+	      echo "slsa-verifier checksum could not be verified. Removing slsa-verifier binary and exiting." >&2 \
+	      && rm -f ${SLSA_VERIFIER_BIN_PATH}/slsa-verifier \
+	      && exit 1; \
+	    fi; \
+	    chmod +x $(SLSA_VERIFIER_BIN_PATH)/slsa-verifier \
+	    && command -v $(SLSA_VERIFIER_BIN_PATH)/slsa-verifier; \
+	fi;
 
 # Set up schemastore for GitHub Actions specs.
 setup-schemastore: $(PACKAGE_PATH)/resources/schemastore/github-workflow.json $(PACKAGE_PATH)/resources/schemastore/LICENSE $(PACKAGE_PATH)/resources/schemastore/NOTICE
@@ -238,8 +263,8 @@ setup-integration-test-utility-for-docker:
 # Generate a Software Bill of Materials (SBOM).
 .PHONY: sbom
 sbom: requirements
-	cyclonedx-py requirements --output-format json --output-file dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-sbom.json
-	$$HOME/go/bin/cyclonedx-gomod mod -json -output dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-sbom-go.json $(REPO_PATH)
+	cyclonedx-py requirements --output-format json --output-file dist/$(PACKAGE_WHEEL_DIST_NAME)-sbom.json
+	$$HOME/go/bin/cyclonedx-gomod mod -json -output dist/$(PACKAGE_WHEEL_DIST_NAME)-sbom-go.json $(REPO_PATH)
 
 # Generate a requirements.txt file containing version and integrity hashes for all
 # packages currently installed in the virtual environment. There's no easy way to
@@ -261,14 +286,14 @@ requirements.txt: pyproject.toml
 	  [[ $$pkg =~ (.*)==(.*) ]] && curl -s https://pypi.org/pypi/$${BASH_REMATCH[1]}/$${BASH_REMATCH[2]}/json | python -c "import json, sys; print(''.join(f''' \\\\\n    --hash=sha256:{pkg['digests']['sha256']}''' for pkg in json.load(sys.stdin)['urls']));" >> requirements.txt; \
 	done
 	echo -e -n "$(PACKAGE_NAME)==$(PACKAGE_VERSION)" >> requirements.txt
-	if [ -f dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz ]; then \
-	  echo -e -n " \\\\\n    $$(python -m pip hash --algorithm sha256 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz | grep '^\-\-hash')" >> requirements.txt; \
+	if [ -f dist/$(PACKAGE_SDIST_NAME).tar.gz ]; then \
+	  echo -e -n " \\\\\n    $$(python -m pip hash --algorithm sha256 dist/$(PACKAGE_SDIST_NAME).tar.gz | grep '^\-\-hash')" >> requirements.txt; \
 	fi
-	if [ -f dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl ]; then \
-	  echo -e -n " \\\\\n    $$(python -m pip hash --algorithm sha256 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl | grep '^\-\-hash')" >> requirements.txt; \
+	if [ -f dist/$(PACKAGE_WHEEL_DIST_NAME).whl ]; then \
+	  echo -e -n " \\\\\n    $$(python -m pip hash --algorithm sha256 dist/$(PACKAGE_WHEEL_DIST_NAME).whl | grep '^\-\-hash')" >> requirements.txt; \
 	fi
 	echo "" >> requirements.txt
-	cp requirements.txt dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-requirements.txt
+	cp requirements.txt dist/$(PACKAGE_WHEEL_DIST_NAME)-requirements.txt
 
 # Audit the currently installed packages. Skip packages that are installed in
 # editable mode (like the one in development here) because they may not have
@@ -359,15 +384,16 @@ integration-test-update:
 # When building these artifacts, we need the environment variable SOURCE_DATE_EPOCH
 # set to the build date/epoch. For more details, see: https://flit.pypa.io/en/latest/reproducible.html
 .PHONY: dist
-dist: dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
-dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl: check test integration-test
-	flit build --setup-py --format wheel
-dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz: check test integration-test
-	flit build --setup-py --format sdist
+dist: dist/$(PACKAGE_WHEEL_DIST_NAME).whl dist/$(PACKAGE_SDIST_NAME).tar.gz dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip dist/$(PACKAGE_WHEEL_DIST_NAME)-build-epoch.txt
+dist/$(PACKAGE_WHEEL_DIST_NAME).whl: check test integration-test
+	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) flit build --setup-py --format wheel
+	mv dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_WHEEL_DIST_NAME).whl
+dist/$(PACKAGE_SDIST_NAME).tar.gz: check test integration-test
+	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) flit build --setup-py --format sdist
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip: docs
 	python -m zipfile -c dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip docs/_build/html
-dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt:
-	echo $(SOURCE_DATE_EPOCH) > dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
+dist/$(PACKAGE_WHEEL_DIST_NAME)-build-epoch.txt:
+	echo $(SOURCE_DATE_EPOCH) > dist/$(PACKAGE_WHEEL_DIST_NAME)-build-epoch.txt
 
 # Build the HTML documentation from the package's source.
 .PHONY: docs

README.md

@@ -4,11 +4,27 @@
 
 ![Macaron](./docs/source/assets/macaron.svg)
 
-[Full Documentation](https://oracle.github.io/macaron/index.html) | [Tutorials](https://oracle.github.io/macaron/pages/tutorials/index.html) | [Videos](https://www.youtube.com/watch?v=ebo0kGKP6bw) | [Papers](#publications) | [Presentations](#presentations)
+[Full Documentation](https://oracle.github.io/macaron/index.html) | [Tutorials](https://oracle.github.io/macaron/pages/tutorials/index.html) | [Videos](https://www.youtube.com/watch?v=ebo0kGKP6bw) | [Papers](#publications) | [Presentations](#presentations) | [Macaron GitHub Action](https://oracle.github.io/macaron/pages/macaron_action.html)
 
 
 **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.
 
+Use Macaron as a GitHub Action
+
+To use the Macaron GitHub Action, add the following step to your workflow (adjust the version as needed). In this example, we use an example policy. For detailed instructions and a comprehensive list of available options, please refer to the [Macaron GitHub Action documentation](https://oracle.github.io/macaron/pages/macaron_action.html).
+
+```yaml
+- uses: oracle/macaron@v0.21.0
+  with:
+    repo_path: 'https://github.com/example/project'
+    policy_file: check-github-actions
+    policy_purl: 'pkg:github.com/example/project'
+    output_dir: 'macaron-output'
+    upload_attestation: true
+```
+
+For detailed instructions and a comprehensive list of available options, please refer to the [Macaron GitHub Action documentation](https://oracle.github.io/macaron/pages/macaron_action.html).
+
 ## Key Capabilities
 
 Macaron supports:

action.yaml

@@ -58,28 +58,13 @@ outputs:
 runs:
   using: composite
   steps:
-  - name: Setup Python
-    uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
-    with:
-      python-version: 3.11.14
-
-  - name: Setup Go
-    uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
-    with:
-      go-version: '1.23'
-      cache: false
-
-  - name: Setup JDK
-    uses: actions/setup-java@b36c23c0d998641eff861008f374ee103c25ac73 # v4.4.0
-    with:
-      java-version: '17'
-      distribution: oracle
-
   - name: Setup Macaron
-    # Create or reuse a Python virtualenv with the macaron CLI and export the `MACARON` binary path via `$GITHUB_ENV` so later steps can use it.
+    # Create or reuse run_macaron.sh script
     run: |
       bash "$GITHUB_ACTION_PATH/scripts/actions/setup_macaron.sh"
     shell: bash
+    env:
+      ACTION_REF: ${{ github.action_ref }}
 
   - name: Run Macaron Analysis
     id: run-macaron-analysis

docker/Dockerfile.final

@@ -43,6 +43,15 @@ RUN : \
     && rm -rf $HOME/dist \
     && deactivate
 
+# Install slsa-verifier.
+# Copy only the Makefile from the build context
+COPY Makefile .
+RUN : \
+    && make install-slsa-verifier \
+    # Test that slsa-verifier exists and is executable.
+    && ls -l $HOME/.local/bin/slsa-verifier \
+    && test -x $HOME/.local/bin/slsa-verifier
+
 COPY --chown=macaron:macaron docker/user.sh $HOME/user.sh
 
 # We enable the root user here so that the user.sh script can modify the

docs/source/conf.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2024, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # Configuration file for the Sphinx documentation builder.
@@ -76,6 +76,10 @@
     "<class 'macaron.parsers.github_workflow_model.Workflow'>",
 ]
 
+suppress_warnings = [
+    "sphinx_autodoc_typehints.forward_reference",  # Sphinx has issues with resolving forward references.
+]
+
 
 # We add the docstrings for class constructors in the `__init__` methods.
 def skip(app, what, name, obj, would_skip, options):

docs/source/index.rst

@@ -121,6 +121,7 @@ intermediate representations as abstractions. Using such abstractions, Macaron i
    pages/installation
    pages/using
    pages/cli_usage/index
+   pages/macaron_action
    pages/tutorials/index
    pages/output_files
    pages/checks/slsa_builds

docs/source/pages/cli_usage/index.rst

@@ -42,7 +42,7 @@ Common Options
 
     Disable Rich UI output. This will turn off any rich formatting (e.g., colored output, tables, etc.) used in the terminal UI.
 
-.. option:: -o OUTPUT_DIR, --output-dir OUTPUT_DIR
+.. option:: -o OUTPUT, --output OUTPUT_DIR
 
     The output destination path for Macaron. This is where Macaron will store the results of the analysis.
 

docs/source/pages/developers_guide/apidoc/macaron.build_spec_generator.dockerfile.rst

@@ -0,0 +1,26 @@
+macaron.build\_spec\_generator.dockerfile package
+=================================================
+
+.. automodule:: macaron.build_spec_generator.dockerfile
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Submodules
+----------
+
+macaron.build\_spec\_generator.dockerfile.dockerfile\_output module
+-------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.dockerfile.dockerfile_output
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.dockerfile.pypi\_dockerfile\_output module
+-------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.dockerfile.pypi_dockerfile_output
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/source/pages/developers_guide/apidoc/macaron.build_spec_generator.rst

@@ -14,6 +14,7 @@ Subpackages
 
    macaron.build_spec_generator.cli_command_parser
    macaron.build_spec_generator.common_spec
+   macaron.build_spec_generator.dockerfile
    macaron.build_spec_generator.reproducible_central
 
 Submodules