Macaron GitHub Action

Overview

This document describes the composite GitHub Action defined in action.yaml at the repository root. The action uses the Macaron CLI to run supply-chain security analysis and policy verification from a GitHub Actions workflow.

Quick usage

When using this action you can reference the action in your workflow. Example:

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
      - name: Run Macaron Security Analysis Action
        uses: oracle/macaron@v0.22.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

Example: policy verification only

To run only the policy verification step (when you already have an output database), call the action with policy_file and set output_dir to the directory containing macaron.db:

- name: Verify policy
  uses: oracle/macaron@v0.22.0
  with:
    policy_file: policy.dl
    output_dir: macaron-output
    upload_attestation: true

Inputs

The action exposes a number of inputs which map directly to Macaron CLI options. Key inputs are listed below (see action.yaml for the full list):

Input	Description	Default
`repo_path`	The path or URL of the repository to analyze.
`package_url`	A PURL identifying a package to analyze instead of a repository.
`sbom_path`	Path to an SBOM file to analyze.
`python_venv`	Path to an existing Python virtualenv (used when analyzing Python packages).
`defaults_path`	Path to a Macaron defaults configuration file.
`policy_file`	Path to a Datalog policy file for policy verification.
`policy_purl`	PURL for a pre-defined policy to use with verification.
`branch` / `digest`	Checkout options when analyzing a repository (branch name or commit digest).
`provenance_expectation`	The path to provenance expectation file or directory.
`provenance_file`	The path to the provenance file in in-toto format.
`deps_depth`	Dependency resolution depth (how many levels of transitive dependencies to resolve).	`0`
`show_prelude`	Shows the Datalog prelude for the database.
`github_token`	Token used by Macaron to access GitHub (for cloning, API access, etc.).	`${{ github.token }}`
`output_dir`	Directory where Macaron writes results (database, reports, artifacts).	`output`
`upload_attestation`	When `true`, the action will attempt to upload a generated verification attestation (VSA) after policy verification.	`false`
`subject_path`	Path to the artifact serving as the subject of the attestation.	`${{ github.workspace }}`

Outputs

The composite action exposes the following outputs (set by the run_macaron_policy_verification.sh script when applicable):

Output	Description
`policy_report`	Path to the generated policy report JSON file produced by `macaron verify-policy`. This file contains the policy evaluation results.
`vsa_report`	Path to the generated VSA (Verification Summary Attestation) in in-toto JSONL format. If no VSA was produced during verification, the action emits the string `"VSA Not Generated."` instead of a path.

Default Policies

Macaron provides policy templates to run pre-defined policies:

Policy name	Description	Template
`check-github-actions`	Detects whether a component was built using GitHub Actions that are known to be vulnerable or otherwise unsafe. The policy evaluates a check named mcn_githubactions_vulnerabilities_1 and reports a passed/failed result for the component when applied.	check-github-actions template
`malware-detection`	Checks a component for indicators of malicious or suspicious content. The policy evaluates a check named mcn_detect_malicious_metadata_1 and reports a passed/failed result for the component when applied.	malware-detection template
`malware-detection-dependencies`	Checks the component and its transitive dependencies for indicators of malicious or suspicious content. The policy ensures the component and each dependency pass the mcn_detect_malicious_metadata_1 check.	malware-detection-dependencies template

How the action works

Setup Macaron: downloads run_macaron.sh script to install and run macaron in the action.
Run Macaron Analysis: calls scripts/actions/run_macaron_analysis.sh which assembles the macaron analyze command from the inputs and runs it. Results are written into output_dir.
Run Macaron Policy Verification: if a policy file or PURL is supplied, the corresponding script runs macaron verify-policy against the analysis database and writes policy_report and vsa_report to $GITHUB_OUTPUT when produced.