From db7ac942f9b85297c11c21bef0c9a1133624ea41 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Sun, 28 Sep 2025 19:28:52 +0530 Subject: [PATCH 01/15] feat: add --policy flag in verify-policy command for example policies Signed-off-by: Demolus13 --- src/macaron/__main__.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index d972e9261..406a8b1dd 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -204,6 +204,7 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: show_prelude(verify_policy_args.database) return os.EX_OK + policy_content = None if verify_policy_args.file: if not os.path.isfile(verify_policy_args.file): logger.critical('The policy file "%s" does not exist.', verify_policy_args.file) @@ -211,7 +212,21 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: with open(verify_policy_args.file, encoding="utf-8") as file: policy_content = file.read() + elif verify_policy_args.policy: + policy_dir = os.path.join(macaron.MACARON_PATH, "resources/policies/datalog") + available_policies = [policy[:-3] for policy in os.listdir(policy_dir) if policy.endswith(".dl")] + if verify_policy_args.policy not in available_policies: + logger.error( + "The policy %s is not available. Available policies are: %s", + verify_policy_args.policy, + available_policies, + ) + return os.EX_USAGE + policy_path = os.path.join(policy_dir, f"{verify_policy_args.policy}.dl") + with open(policy_path, encoding="utf-8") as file: + policy_content = file.read() + if policy_content: result = run_policy_engine(verify_policy_args.database, policy_content) vsa = generate_vsa(policy_content=policy_content, policy_result=result) # Retrieve the console handler previously configured via the access_handler. @@ -574,6 +589,7 @@ def main(argv: list[str] | None = None) -> None: vp_parser.add_argument("-d", "--database", required=True, type=str, help="Path to the database.") vp_group.add_argument("-f", "--file", type=str, help="Path to the Datalog policy.") + vp_group.add_argument("-p", "--policy", help="Example policy to run.") vp_group.add_argument("-s", "--show-prelude", action="store_true", help="Show policy prelude.") # Find the repo and commit of a passed PURL, or the commit of a passed PURL and repo. From 3126b92fe7e4821335707d5ffe2e842952f53cfa Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Mon, 29 Sep 2025 21:26:08 +0530 Subject: [PATCH 02/15] feat: add policy template modification for standardization Signed-off-by: Demolus13 --- src/macaron/__main__.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index 406a8b1dd..7695c4726 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -214,7 +214,7 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: policy_content = file.read() elif verify_policy_args.policy: policy_dir = os.path.join(macaron.MACARON_PATH, "resources/policies/datalog") - available_policies = [policy[:-3] for policy in os.listdir(policy_dir) if policy.endswith(".dl")] + available_policies = [policy[:-12] for policy in os.listdir(policy_dir) if policy.endswith(".dl.template")] if verify_policy_args.policy not in available_policies: logger.error( "The policy %s is not available. Available policies are: %s", @@ -222,9 +222,11 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: available_policies, ) return os.EX_USAGE - policy_path = os.path.join(policy_dir, f"{verify_policy_args.policy}.dl") + policy_path = os.path.join(policy_dir, f"{verify_policy_args.policy}.dl.template") with open(policy_path, encoding="utf-8") as file: policy_content = file.read() + if verify_policy_args.package_url: + policy_content = policy_content.replace("", verify_policy_args.package_url) if policy_content: result = run_policy_engine(verify_policy_args.database, policy_content) @@ -588,6 +590,7 @@ def main(argv: list[str] | None = None) -> None: vp_group = vp_parser.add_mutually_exclusive_group(required=True) vp_parser.add_argument("-d", "--database", required=True, type=str, help="Path to the database.") + vp_parser.add_argument("-purl", "--package-url", help="PackageURL for policy template.") vp_group.add_argument("-f", "--file", type=str, help="Path to the Datalog policy.") vp_group.add_argument("-p", "--policy", help="Example policy to run.") vp_group.add_argument("-s", "--show-prelude", action="store_true", help="Show policy prelude.") From ed9478430f73837f1ea1025c122339dc6a107f57 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Tue, 7 Oct 2025 11:49:08 +0530 Subject: [PATCH 03/15] feat: add sample policies Signed-off-by: Demolus13 --- .../policies/datalog/check-github-actions.dl.template | 8 ++++++++ .../datalog/malware-detection-dependencies.dl.template | 10 ++++++++++ .../policies/datalog/malware-detection.dl.template | 9 +++++++++ 3 files changed, 27 insertions(+) create mode 100644 src/macaron/resources/policies/datalog/check-github-actions.dl.template create mode 100644 src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template create mode 100644 src/macaron/resources/policies/datalog/malware-detection.dl.template diff --git a/src/macaron/resources/policies/datalog/check-github-actions.dl.template b/src/macaron/resources/policies/datalog/check-github-actions.dl.template new file mode 100644 index 000000000..bfd0b04d3 --- /dev/null +++ b/src/macaron/resources/policies/datalog/check-github-actions.dl.template @@ -0,0 +1,8 @@ +#include "prelude.dl" + +Policy("github_actions_vulns", component_id, "GitHub Actions Vulnerability Detection") :- + check_passed(component_id, "mcn_githubactions_vulnerabilities_1"). + +apply_policy_to("github_actions_vulns", component_id) :- + is_component(component_id, purl), + match("@.*", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template new file mode 100644 index 000000000..55c2adca1 --- /dev/null +++ b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template @@ -0,0 +1,10 @@ +#include "prelude.dl" + +Policy("check-dependencies", component_id, "Check the dependencies of component.") :- + transitive_dependency(component_id, dependency), + check_passed(component_id, "mcn_detect_malicious_metadata_1"), + check_passed(dependency, "mcn_detect_malicious_metadata_1"). + +apply_policy_to("check-dependencies", component_id) :- + is_component(component_id, purl), + match("@.*", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection.dl.template b/src/macaron/resources/policies/datalog/malware-detection.dl.template new file mode 100644 index 000000000..38bff2c4b --- /dev/null +++ b/src/macaron/resources/policies/datalog/malware-detection.dl.template @@ -0,0 +1,9 @@ +#include "prelude.dl" + +Policy("check-component", component_id, "Check component artifacts.") :- + check_passed(component_id, "mcn_detect_malicious_metadata_1"). + + +apply_policy_to("check-component", component_id) :- + is_component(component_id, purl), + match("@.*", purl). From c604c61f43c86bc25b449eceebd9824c5d9d22c0 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Fri, 31 Oct 2025 12:19:31 +0530 Subject: [PATCH 04/15] chore: improve handling of policy templates and verify packageurl Signed-off-by: Demolus13 --- src/macaron/__main__.py | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index 7695c4726..dce3ac200 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -213,8 +213,14 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: with open(verify_policy_args.file, encoding="utf-8") as file: policy_content = file.read() elif verify_policy_args.policy: - policy_dir = os.path.join(macaron.MACARON_PATH, "resources/policies/datalog") - available_policies = [policy[:-12] for policy in os.listdir(policy_dir) if policy.endswith(".dl.template")] + policy_dir = os.path.join(macaron.MACARON_PATH, "resources", "policies", "datalog") + policy_suffix = ".dl" + template_suffix = f"{policy_suffix}.template" + available_policies = [ + os.path.splitext(policy)[0].replace(policy_suffix, "") + for policy in os.listdir(policy_dir) + if policy.endswith(template_suffix) + ] if verify_policy_args.policy not in available_policies: logger.error( "The policy %s is not available. Available policies are: %s", @@ -222,11 +228,15 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: available_policies, ) return os.EX_USAGE - policy_path = os.path.join(policy_dir, f"{verify_policy_args.policy}.dl.template") + policy_path = os.path.join(policy_dir, f"{verify_policy_args.policy}{template_suffix}") with open(policy_path, encoding="utf-8") as file: policy_content = file.read() - if verify_policy_args.package_url: + try: + PackageURL.from_string(verify_policy_args.package_url) policy_content = policy_content.replace("", verify_policy_args.package_url) + except ValueError as err: + logger.error("The package url %s is not valid. Error: %s", verify_policy_args.package_url, err) + return os.EX_USAGE if policy_content: result = run_policy_engine(verify_policy_args.database, policy_content) From ec0956462f8e5ec9f32928579803c4a53488b3b9 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Sat, 1 Nov 2025 09:54:49 +0530 Subject: [PATCH 05/15] refactor: change -p (--policy) to -e (--existing-policy) for verify-policy command Signed-off-by: Demolus13 --- src/macaron/__main__.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index dce3ac200..63d062a23 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -212,7 +212,7 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: with open(verify_policy_args.file, encoding="utf-8") as file: policy_content = file.read() - elif verify_policy_args.policy: + elif verify_policy_args.existing_policy: policy_dir = os.path.join(macaron.MACARON_PATH, "resources", "policies", "datalog") policy_suffix = ".dl" template_suffix = f"{policy_suffix}.template" @@ -221,14 +221,14 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: for policy in os.listdir(policy_dir) if policy.endswith(template_suffix) ] - if verify_policy_args.policy not in available_policies: + if verify_policy_args.existing_policy not in available_policies: logger.error( "The policy %s is not available. Available policies are: %s", - verify_policy_args.policy, + verify_policy_args.existing_policy, available_policies, ) return os.EX_USAGE - policy_path = os.path.join(policy_dir, f"{verify_policy_args.policy}{template_suffix}") + policy_path = os.path.join(policy_dir, f"{verify_policy_args.existing_policy}{template_suffix}") with open(policy_path, encoding="utf-8") as file: policy_content = file.read() try: @@ -602,7 +602,7 @@ def main(argv: list[str] | None = None) -> None: vp_parser.add_argument("-d", "--database", required=True, type=str, help="Path to the database.") vp_parser.add_argument("-purl", "--package-url", help="PackageURL for policy template.") vp_group.add_argument("-f", "--file", type=str, help="Path to the Datalog policy.") - vp_group.add_argument("-p", "--policy", help="Example policy to run.") + vp_group.add_argument("-e", "--existing-policy", help="Name of the existing policy to run.") vp_group.add_argument("-s", "--show-prelude", action="store_true", help="Show policy prelude.") # Find the repo and commit of a passed PURL, or the commit of a passed PURL and repo. From a017638ea4b6c87a1ceacf96ce86878dea7f2d1e Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Sun, 2 Nov 2025 22:39:05 +0530 Subject: [PATCH 06/15] chore: add simple tests for existing-policy flag Signed-off-by: Demolus13 --- tests/policy_engine/test_existing_policy.py | 61 +++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 tests/policy_engine/test_existing_policy.py diff --git a/tests/policy_engine/test_existing_policy.py b/tests/policy_engine/test_existing_policy.py new file mode 100644 index 000000000..359c07f1d --- /dev/null +++ b/tests/policy_engine/test_existing_policy.py @@ -0,0 +1,61 @@ +# Copyright (c) 2025 - 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/. + +"""This module tests the existing-policy flag supported by the policy engine.""" + +import argparse +import os +from pathlib import Path +from unittest.mock import MagicMock, patch + +from macaron.__main__ import verify_policy + + +def test_verify_existing_policy_success(tmp_path: Path) -> None: + """When an existing policy is provided and package-url is valid, verify_policy returns EX_OK.""" + db_file = tmp_path / "macaron.db" + db_file.write_text("") + + # Use a MagicMock for the handler. + mock_handler = MagicMock() + + # Fake run_policy_engine and generate_vsa that returns a fixed result. + fake_run = MagicMock(return_value={"passed_policies": [["check-component"]], "failed_policies": []}) + fake_generate_vsa = MagicMock(return_value=None) + + # Fake PolicyReporter class: when called, returns an instance with generate method. + fake_policy_reporter_cls = MagicMock() + fake_policy_reporter_inst = MagicMock() + fake_policy_reporter_inst.generate.return_value = None + fake_policy_reporter_cls.return_value = fake_policy_reporter_inst + + with ( + patch("macaron.__main__.run_policy_engine", fake_run), + patch("macaron.__main__.generate_vsa", fake_generate_vsa), + patch("macaron.__main__.access_handler.get_handler", return_value=mock_handler), + patch("macaron.__main__.PolicyReporter", fake_policy_reporter_cls), + ): + policy_args = argparse.Namespace( + database=str(db_file), + show_prelude=False, + file=None, + existing_policy="malware-detection", + package_url="pkg:pypi/django", + ) + result = verify_policy(policy_args) + assert result == os.EX_OK + + +def test_verify_existing_policy_not_found(tmp_path: Path) -> None: + """Requesting a non-existent policy returns usage error.""" + db_file = tmp_path / "macaron.db" + db_file.write_text("") + policy_args = argparse.Namespace( + database=str(db_file), + show_prelude=False, + file=None, + existing_policy="no-such-policy", + package_url="pkg:pypi/django", + ) + result = verify_policy(policy_args) + assert result == os.EX_USAGE From 4b9f002cdd0118bf9b1dd3cb605a66dd88df2679 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Mon, 10 Nov 2025 09:32:37 +0530 Subject: [PATCH 07/15] refactor: add new tutorial for existing-policy flag Signed-off-by: Demolus13 --- docs/source/pages/tutorials/index.rst | 1 + .../tutorials/verify_with_existing_policy.rst | 53 +++++++++++++++++++ .../datalog/check-github-actions.dl.template | 2 +- ...malware-detection-dependencies.dl.template | 2 +- .../datalog/malware-detection.dl.template | 2 +- 5 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 docs/source/pages/tutorials/verify_with_existing_policy.rst diff --git a/docs/source/pages/tutorials/index.rst b/docs/source/pages/tutorials/index.rst index 6f6b3bf00..5fa5e899a 100644 --- a/docs/source/pages/tutorials/index.rst +++ b/docs/source/pages/tutorials/index.rst @@ -23,6 +23,7 @@ For the full list of supported technologies, such as CI services, registries, an detect_vulnerable_github_actions provenance detect_malicious_java_dep + verify_with_existing_policy generate_verification_summary_attestation use_verification_summary_attestation exclude_include_checks diff --git a/docs/source/pages/tutorials/verify_with_existing_policy.rst b/docs/source/pages/tutorials/verify_with_existing_policy.rst new file mode 100644 index 000000000..df97cd627 --- /dev/null +++ b/docs/source/pages/tutorials/verify_with_existing_policy.rst @@ -0,0 +1,53 @@ +============================================================== +Verify with an existing example policy using --existing-policy +============================================================== + +This short tutorial shows how to use the ``--existing-policy`` flag with the ``verify-policy`` subcommand to run one of the example (predefined) policies that ship with Macaron. + +-------- +Use case +-------- + +Use ``--existing-policy`` when you want to run one of the built-in example policies by name instead of providing a local policy file with ``--file``. Example policies are useful for quick checks or automated examples/tests. + +------- +Example +------- + +Run the ``malware-detection`` example policy against a package URL: + +.. code-block:: shell + + ./run_macaron.sh analyze -purl pkg:pypi/django@5.0.6 + +.. note:: By default, Macaron clones the repositories and creates output files under the ``output`` directory. To understand the structure of this directory please see :ref:`Output Files Guide `. + +.. code-block:: shell + + ./run_macaron.sh verify-policy \ + --database output/macaron.db \ + --existing-policy malware-detection \ + --package-url "pkg:pypi/django" + +The result of this command should show that the policy succeeds with a zero exit code (if a policy fails to pass, Macaron returns a none-zero error code): + +.. code-block:: shell + + Components Satisfy Policy + 1 pkg:pypi/django@5.0.6 check-component + + Components Violate Policy None + + Passed Policies check-component + Failed Policies None + Policy Report output/policy_report.json + Verification Summary Attestation output/vsa.intoto.jsonl + Decode and Inspect the Content cat output/vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq + +----------------- +Related tutorials +----------------- + +- :doc:`detect_malicious_package` — shows what the malware-detection policy does in this tutorial. +- :doc:`use_verification_summary_attestation` — how to consume an attestation + produced by Macaron. diff --git a/src/macaron/resources/policies/datalog/check-github-actions.dl.template b/src/macaron/resources/policies/datalog/check-github-actions.dl.template index bfd0b04d3..35ec0b65d 100644 --- a/src/macaron/resources/policies/datalog/check-github-actions.dl.template +++ b/src/macaron/resources/policies/datalog/check-github-actions.dl.template @@ -5,4 +5,4 @@ Policy("github_actions_vulns", component_id, "GitHub Actions Vulnerability Detec apply_policy_to("github_actions_vulns", component_id) :- is_component(component_id, purl), - match("@.*", purl). + match("*", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template index 55c2adca1..1d93c56d5 100644 --- a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template +++ b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template @@ -7,4 +7,4 @@ Policy("check-dependencies", component_id, "Check the dependencies of component. apply_policy_to("check-dependencies", component_id) :- is_component(component_id, purl), - match("@.*", purl). + match("*", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection.dl.template b/src/macaron/resources/policies/datalog/malware-detection.dl.template index 38bff2c4b..8b2969aaf 100644 --- a/src/macaron/resources/policies/datalog/malware-detection.dl.template +++ b/src/macaron/resources/policies/datalog/malware-detection.dl.template @@ -6,4 +6,4 @@ Policy("check-component", component_id, "Check component artifacts.") :- apply_policy_to("check-component", component_id) :- is_component(component_id, purl), - match("@.*", purl). + match("*", purl). From 1118df87c5fed3b2a9ab485ddec2b7873ab4e4b5 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Tue, 11 Nov 2025 11:21:50 +0530 Subject: [PATCH 08/15] refactor: add --list-policies flag to check for available policies. Signed-off-by: Demolus13 --- .../tutorials/verify_with_existing_policy.rst | 12 ++++++------ src/macaron/__main__.py | 16 +++++++++++++++- .../datalog/check-github-actions.dl.template | 2 +- .../malware-detection-dependencies.dl.template | 2 +- .../datalog/malware-detection.dl.template | 2 +- tests/policy_engine/test_existing_policy.py | 10 ++++++---- 6 files changed, 30 insertions(+), 14 deletions(-) diff --git a/docs/source/pages/tutorials/verify_with_existing_policy.rst b/docs/source/pages/tutorials/verify_with_existing_policy.rst index df97cd627..bd799ecda 100644 --- a/docs/source/pages/tutorials/verify_with_existing_policy.rst +++ b/docs/source/pages/tutorials/verify_with_existing_policy.rst @@ -1,20 +1,20 @@ -============================================================== -Verify with an existing example policy using --existing-policy -============================================================== +=================================================================== +How to use the policy engine to verify with our predefined policies +=================================================================== -This short tutorial shows how to use the ``--existing-policy`` flag with the ``verify-policy`` subcommand to run one of the example (predefined) policies that ship with Macaron. +This tutorial shows how to use the ``--existing-policy`` flag with the ``verify-policy`` subcommand to run one of the predefined policies that ship with Macaron. -------- Use case -------- -Use ``--existing-policy`` when you want to run one of the built-in example policies by name instead of providing a local policy file with ``--file``. Example policies are useful for quick checks or automated examples/tests. +Use ``--existing-policy`` when you want to run one of the built-in policies by name instead of providing a local policy file with ``--file``. Pre-defined policies are useful for quick checks or automated examples/tests. ------- Example ------- -Run the ``malware-detection`` example policy against a package URL: +Run the ``malware-detection`` policy against a package URL: .. code-block:: shell diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index 63d062a23..9c6e4a156 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -205,6 +205,18 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: return os.EX_OK policy_content = None + if verify_policy_args.list_policies: + policy_dir = os.path.join(macaron.MACARON_PATH, "resources", "policies", "datalog") + policy_suffix = ".dl" + template_suffix = f"{policy_suffix}.template" + available_policies = [ + os.path.splitext(policy)[0].replace(policy_suffix, "") + for policy in os.listdir(policy_dir) + if policy.endswith(template_suffix) + ] + logger.info("Available policies are:\n\t%s", "\n\t".join(available_policies)) + return os.EX_OK + if verify_policy_args.file: if not os.path.isfile(verify_policy_args.file): logger.critical('The policy file "%s" does not exist.', verify_policy_args.file) @@ -232,7 +244,8 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: with open(policy_path, encoding="utf-8") as file: policy_content = file.read() try: - PackageURL.from_string(verify_policy_args.package_url) + validation_package_url = verify_policy_args.package_url.replace("*", "") + PackageURL.from_string(validation_package_url) policy_content = policy_content.replace("", verify_policy_args.package_url) except ValueError as err: logger.error("The package url %s is not valid. Error: %s", verify_policy_args.package_url, err) @@ -603,6 +616,7 @@ def main(argv: list[str] | None = None) -> None: vp_parser.add_argument("-purl", "--package-url", help="PackageURL for policy template.") vp_group.add_argument("-f", "--file", type=str, help="Path to the Datalog policy.") vp_group.add_argument("-e", "--existing-policy", help="Name of the existing policy to run.") + vp_group.add_argument("-l", "--list-policies", action="store_true", help="List the existing policy to run.") vp_group.add_argument("-s", "--show-prelude", action="store_true", help="Show policy prelude.") # Find the repo and commit of a passed PURL, or the commit of a passed PURL and repo. diff --git a/src/macaron/resources/policies/datalog/check-github-actions.dl.template b/src/macaron/resources/policies/datalog/check-github-actions.dl.template index 35ec0b65d..2ca898210 100644 --- a/src/macaron/resources/policies/datalog/check-github-actions.dl.template +++ b/src/macaron/resources/policies/datalog/check-github-actions.dl.template @@ -5,4 +5,4 @@ Policy("github_actions_vulns", component_id, "GitHub Actions Vulnerability Detec apply_policy_to("github_actions_vulns", component_id) :- is_component(component_id, purl), - match("*", purl). + match("", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template index 1d93c56d5..81e865221 100644 --- a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template +++ b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template @@ -7,4 +7,4 @@ Policy("check-dependencies", component_id, "Check the dependencies of component. apply_policy_to("check-dependencies", component_id) :- is_component(component_id, purl), - match("*", purl). + match("", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection.dl.template b/src/macaron/resources/policies/datalog/malware-detection.dl.template index 8b2969aaf..77eedc5cf 100644 --- a/src/macaron/resources/policies/datalog/malware-detection.dl.template +++ b/src/macaron/resources/policies/datalog/malware-detection.dl.template @@ -6,4 +6,4 @@ Policy("check-component", component_id, "Check component artifacts.") :- apply_policy_to("check-component", component_id) :- is_component(component_id, purl), - match("*", purl). + match("", purl). diff --git a/tests/policy_engine/test_existing_policy.py b/tests/policy_engine/test_existing_policy.py index 359c07f1d..4a347efad 100644 --- a/tests/policy_engine/test_existing_policy.py +++ b/tests/policy_engine/test_existing_policy.py @@ -13,8 +13,9 @@ def test_verify_existing_policy_success(tmp_path: Path) -> None: """When an existing policy is provided and package-url is valid, verify_policy returns EX_OK.""" - db_file = tmp_path / "macaron.db" - db_file.write_text("") + db_file = os.path.join(tmp_path, "macaron.db") + with open(db_file, "w", encoding="utf-8") as f: + f.write("") # Use a MagicMock for the handler. mock_handler = MagicMock() @@ -48,8 +49,9 @@ def test_verify_existing_policy_success(tmp_path: Path) -> None: def test_verify_existing_policy_not_found(tmp_path: Path) -> None: """Requesting a non-existent policy returns usage error.""" - db_file = tmp_path / "macaron.db" - db_file.write_text("") + db_file = os.path.join(tmp_path, "macaron.db") + with open(db_file, "w", encoding="utf-8") as f: + f.write("") policy_args = argparse.Namespace( database=str(db_file), show_prelude=False, From d31c0cb857ea7455f15528863ab65e4e94e4547e Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Tue, 11 Nov 2025 11:28:23 +0530 Subject: [PATCH 09/15] refactor: add --list-policies flag to check for available policies. Signed-off-by: Demolus13 --- tests/policy_engine/test_existing_policy.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/policy_engine/test_existing_policy.py b/tests/policy_engine/test_existing_policy.py index 4a347efad..4d8a45af6 100644 --- a/tests/policy_engine/test_existing_policy.py +++ b/tests/policy_engine/test_existing_policy.py @@ -40,6 +40,7 @@ def test_verify_existing_policy_success(tmp_path: Path) -> None: database=str(db_file), show_prelude=False, file=None, + list_policies=False, existing_policy="malware-detection", package_url="pkg:pypi/django", ) @@ -56,6 +57,7 @@ def test_verify_existing_policy_not_found(tmp_path: Path) -> None: database=str(db_file), show_prelude=False, file=None, + list_policies=False, existing_policy="no-such-policy", package_url="pkg:pypi/django", ) From 311845e781d4028b0f641150a726282709512d3e Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Wed, 12 Nov 2025 18:21:16 +0530 Subject: [PATCH 10/15] chore: add descriptions for each existing policy and a test to verify the .description file Signed-off-by: Demolus13 --- src/macaron/resources/policies/README.md | 12 ++++++++++ .../resources/policies/datalog/README.md | 13 ++++++++++ .../datalog/check-github-actions.description | 1 + .../datalog/check-github-actions.dl.template | 6 ++--- ...malware-detection-dependencies.description | 0 ...malware-detection-dependencies.dl.template | 6 ++--- .../datalog/malware-detection.description | 1 + .../policy_engine/test_datalog_description.py | 24 +++++++++++++++++++ 8 files changed, 57 insertions(+), 6 deletions(-) create mode 100644 src/macaron/resources/policies/README.md create mode 100644 src/macaron/resources/policies/datalog/README.md create mode 100644 src/macaron/resources/policies/datalog/check-github-actions.description create mode 100644 src/macaron/resources/policies/datalog/malware-detection-dependencies.description create mode 100644 src/macaron/resources/policies/datalog/malware-detection.description create mode 100644 tests/policy_engine/test_datalog_description.py diff --git a/src/macaron/resources/policies/README.md b/src/macaron/resources/policies/README.md new file mode 100644 index 000000000..b086526ad --- /dev/null +++ b/src/macaron/resources/policies/README.md @@ -0,0 +1,12 @@ +Policies +======= + +This directory contains policy resources used by Macaron. Policies in this folder are packaged as templates that the verify-policy command can use. + +Common files and conventions +--------------------------- +- `*.dl.template` - datalog policy templates. +- `*.description` - short descriptions that explain the policy's intent. +- `*.cue.template` - CUE-based expectation templates used by the GDK. + +Example policies are exposed to the user via Macaron commands `verify-policy --existing-policy `. diff --git a/src/macaron/resources/policies/datalog/README.md b/src/macaron/resources/policies/datalog/README.md new file mode 100644 index 000000000..43a9f6450 --- /dev/null +++ b/src/macaron/resources/policies/datalog/README.md @@ -0,0 +1,13 @@ +Datalog policy templates +========================= + +- This folder contains Datalog-based policy templates and accompanying `.description` files used by Macaron's policy engine. + +- These `.dl.template` templates are intended as examples and starting points. They can be used by name using `--existing-policy` flag. + +- `*.description` - descriptions for each template. These are intended to be shown in UIs or documentation to help users choose an appropriate example policy. + +Extending or adding templates +----------------------------- +- Add a new `.dl.template` file and a matching `.description` file. +- Update documentation or the tutorials page if you add new example policies that should be exposed to users. diff --git a/src/macaron/resources/policies/datalog/check-github-actions.description b/src/macaron/resources/policies/datalog/check-github-actions.description new file mode 100644 index 000000000..65292bbd8 --- /dev/null +++ b/src/macaron/resources/policies/datalog/check-github-actions.description @@ -0,0 +1 @@ +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. diff --git a/src/macaron/resources/policies/datalog/check-github-actions.dl.template b/src/macaron/resources/policies/datalog/check-github-actions.dl.template index 2ca898210..08f456e81 100644 --- a/src/macaron/resources/policies/datalog/check-github-actions.dl.template +++ b/src/macaron/resources/policies/datalog/check-github-actions.dl.template @@ -1,8 +1,8 @@ #include "prelude.dl" Policy("github_actions_vulns", component_id, "GitHub Actions Vulnerability Detection") :- - check_passed(component_id, "mcn_githubactions_vulnerabilities_1"). + check_passed(component_id, "mcn_githubactions_vulnerabilities_1"). apply_policy_to("github_actions_vulns", component_id) :- - is_component(component_id, purl), - match("", purl). + is_component(component_id, purl), + match("", purl). diff --git a/src/macaron/resources/policies/datalog/malware-detection-dependencies.description b/src/macaron/resources/policies/datalog/malware-detection-dependencies.description new file mode 100644 index 000000000..e69de29bb diff --git a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template index 81e865221..54b83bf27 100644 --- a/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template +++ b/src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template @@ -1,9 +1,9 @@ #include "prelude.dl" Policy("check-dependencies", component_id, "Check the dependencies of component.") :- - transitive_dependency(component_id, dependency), - check_passed(component_id, "mcn_detect_malicious_metadata_1"), - check_passed(dependency, "mcn_detect_malicious_metadata_1"). + transitive_dependency(component_id, dependency), + check_passed(component_id, "mcn_detect_malicious_metadata_1"), + check_passed(dependency, "mcn_detect_malicious_metadata_1"). apply_policy_to("check-dependencies", component_id) :- is_component(component_id, purl), diff --git a/src/macaron/resources/policies/datalog/malware-detection.description b/src/macaron/resources/policies/datalog/malware-detection.description new file mode 100644 index 000000000..0bd04a45f --- /dev/null +++ b/src/macaron/resources/policies/datalog/malware-detection.description @@ -0,0 +1 @@ +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. diff --git a/tests/policy_engine/test_datalog_description.py b/tests/policy_engine/test_datalog_description.py new file mode 100644 index 000000000..d0450a2c4 --- /dev/null +++ b/tests/policy_engine/test_datalog_description.py @@ -0,0 +1,24 @@ +# Copyright (c) 2025 - 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/. + +"""Tests that every Datalog template has a matching .description file.""" + +from pathlib import Path + +import macaron + + +def test_datalog_templates_have_descriptions() -> None: + """Verify each ``*.dl.template`` has a corresponding ``*.description``.""" + datalog_dir = Path(macaron.__file__).resolve().parent.joinpath("resources", "policies", "datalog") + templates = sorted(datalog_dir.glob("*.dl.template")) + + missing = [] + for tmpl in templates: + expected_desc = datalog_dir.joinpath(tmpl.name.replace(".dl.template", ".description")) + if not expected_desc.exists(): + missing.append((tmpl.name, expected_desc)) + + if templates and missing: + missing_list = ", ".join(f"{t} -> {d}" for t, d in missing) + raise AssertionError("Missing .description files for the following templates: " + missing_list) From 0fd55bacde4b9a0cd4a630c83863ff76741e6739 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Sun, 16 Nov 2025 13:28:05 +0530 Subject: [PATCH 11/15] refactor: improve UI to show the available policies. Signed-off-by: Demolus13 --- src/macaron/__main__.py | 31 +++++++++++++++---- src/macaron/console.py | 28 ++++++++++++++++- ...malware-detection-dependencies.description | 1 + 3 files changed, 53 insertions(+), 7 deletions(-) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index 9c6e4a156..36eeadd11 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -209,12 +209,31 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: policy_dir = os.path.join(macaron.MACARON_PATH, "resources", "policies", "datalog") policy_suffix = ".dl" template_suffix = f"{policy_suffix}.template" - available_policies = [ - os.path.splitext(policy)[0].replace(policy_suffix, "") - for policy in os.listdir(policy_dir) - if policy.endswith(template_suffix) - ] - logger.info("Available policies are:\n\t%s", "\n\t".join(available_policies)) + description_suffix = ".description" + + policies_with_desc: dict[str, str] = {} + try: + for policy_file in os.listdir(policy_dir): + if not policy_file.endswith(template_suffix): + continue + policy = os.path.splitext(policy_file)[0].replace(policy_suffix, "") + description_path = os.path.join(policy_dir, f"{policy}{description_suffix}") + try: + with open(description_path, encoding="utf-8") as f: + desc = f.read().strip() + if not desc: + desc = "No description available." + except OSError: + desc = "Could not read policy description." + policies_with_desc[policy] = desc + except FileNotFoundError: + logger.error("Policy directory %s not found.", policy_dir) + return os.EX_OSFILE + + rich_handler = access_handler.get_handler() + rich_handler.set_available_policies(policies_with_desc) + + logger.info("Available policies are:\n\t%s", "\n\t".join(sorted(policies_with_desc))) return os.EX_OK if verify_policy_args.file: diff --git a/src/macaron/console.py b/src/macaron/console.py index eedaae962..a76052d85 100644 --- a/src/macaron/console.py +++ b/src/macaron/console.py @@ -76,6 +76,16 @@ def _make_reports_table(reports: dict) -> Table: table.add_row(report_type, report_path, style="blue") return table + @staticmethod + def _make_policies_table(policies: dict[str, str]) -> Table: + """Build a two-column table of policy name and a short description.""" + table = Table(box=None) + table.add_column("Policy", justify="left", style="bold") + table.add_column("Description", justify="left") + for name, desc in policies.items(): + table.add_row(name, desc) + return table + class Dependency(TableBuilder): """A class to manage the display of dependency analysis in the console.""" @@ -289,6 +299,8 @@ def __init__(self, *args: Any, verbose: bool = False, **kwargs: Any) -> None: self.if_dependency: bool = False self.dependency_analysis_map: dict[str, int] = {} self.dependency_analysis_list: list[Dependency] = [] + self.available_policies: dict[str, str] = {} + self.policies_table = Table(box=None) self.components_violates_table = Table(box=None) self.components_satisfy_table = Table(box=None) self.policy_summary_table = Table(show_header=False, box=None) @@ -484,6 +496,18 @@ def update_policy_report(self, report_path: str) -> None: self.policy_summary["Policy Report"] = report_path self.generate_policy_summary_table() + def set_available_policies(self, policies: dict[str, str]) -> None: + """ + Store available policies and build the policies table. + + Parameters + ---------- + policies : dict[str, str] + Mapping of policy name to short description. + """ + self.available_policies = policies + self.policies_table = self._make_policies_table(self.available_policies) + def update_vsa(self, vsa_path: str) -> None: """ Update the verification summary attestation path. @@ -705,7 +729,9 @@ def make_layout(self) -> Group: self.report_table, ] elif self.command == "verify-policy": - if self.policy_summary_table.row_count > 0: + if self.policies_table.row_count > 0: + layout = layout + [self.policies_table] + elif self.policy_summary_table.row_count > 0: if self.components_satisfy_table.row_count > 0: layout = layout + [ "[bold green] Components Satisfy Policy[/]", diff --git a/src/macaron/resources/policies/datalog/malware-detection-dependencies.description b/src/macaron/resources/policies/datalog/malware-detection-dependencies.description index e69de29bb..544cdccfc 100644 --- a/src/macaron/resources/policies/datalog/malware-detection-dependencies.description +++ b/src/macaron/resources/policies/datalog/malware-detection-dependencies.description @@ -0,0 +1 @@ +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. From c3494233d26721ce14b46aa6f74289bec160bed9 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Mon, 17 Nov 2025 08:34:20 +0530 Subject: [PATCH 12/15] docs: update tutorial to show the use of wildcard. Signed-off-by: Demolus13 --- .../tutorials/verify_with_existing_policy.rst | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/source/pages/tutorials/verify_with_existing_policy.rst b/docs/source/pages/tutorials/verify_with_existing_policy.rst index bd799ecda..26d9eaf9c 100644 --- a/docs/source/pages/tutorials/verify_with_existing_policy.rst +++ b/docs/source/pages/tutorials/verify_with_existing_policy.rst @@ -27,7 +27,7 @@ Run the ``malware-detection`` policy against a package URL: ./run_macaron.sh verify-policy \ --database output/macaron.db \ --existing-policy malware-detection \ - --package-url "pkg:pypi/django" + --package-url "pkg:pypi/django@5.0.6" The result of this command should show that the policy succeeds with a zero exit code (if a policy fails to pass, Macaron returns a none-zero error code): @@ -44,6 +44,39 @@ The result of this command should show that the policy succeeds with a zero exit Verification Summary Attestation output/vsa.intoto.jsonl Decode and Inspect the Content cat output/vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq +Run the ``malware-detection`` policy using wildcard: + +.. code-block:: shell + + ./run_macaron.sh analyze -purl pkg:pypi/django@5.0.6 + ./run_macaron.sh analyze -purl pkg:pypi/django@1.11.1 + +.. note:: By default, Macaron clones the repositories and creates output files under the ``output`` directory. To understand the structure of this directory please see :ref:`Output Files Guide `. + +.. code-block:: shell + + ./run_macaron.sh verify-policy \ + --database output/macaron.db \ + --existing-policy malware-detection \ + --package-url "pkg:pypi/django@*" + +It uses the wildcard '*' to checks for components satisfying the expression "pkg:pypi/django@*". +The result of this command should show that the policy succeeds with a zero exit code (if a policy fails to pass, Macaron returns a none-zero error code): + +.. code-block:: shell + + Components Satisfy Policy + 1 pkg:pypi/django@5.0.6 check-component + 1 pkg:pypi/django@1.11.1 check-component + + Components Violate Policy None + + Passed Policies check-component + Failed Policies None + Policy Report output/policy_report.json + Verification Summary Attestation output/vsa.intoto.jsonl + Decode and Inspect the Content cat output/vsa.intoto.jsonl | jq -r '.payload' | base64 -d | jq + ----------------- Related tutorials ----------------- From 94feadc1bff15c13338d342e2bc45941d2df05d1 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Tue, 18 Nov 2025 09:36:06 +0530 Subject: [PATCH 13/15] refactor: handle action_args for verify-policy. Signed-off-by: Demolus13 --- src/macaron/__main__.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index 36eeadd11..f60e9df24 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -196,7 +196,7 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: int Returns os.EX_OK if successful or the corresponding error code on failure. """ - if not os.path.isfile(verify_policy_args.database): + if not verify_policy_args.list_policies and not os.path.isfile(verify_policy_args.database): logger.critical("The database file does not exist.") return os.EX_OSFILE @@ -375,6 +375,9 @@ def perform_action(action_args: argparse.Namespace) -> None: case "verify-policy": if not action_args.disable_rich_output: rich_handler.start("verify-policy") + if not action_args.list_policies and not action_args.database: + logger.error("macaron verify-policy: error: the following arguments are required: -d/--database") + sys.exit(os.EX_USAGE) sys.exit(verify_policy(action_args)) case "analyze": @@ -631,7 +634,7 @@ def main(argv: list[str] | None = None) -> None: vp_parser = sub_parser.add_parser(name="verify-policy") vp_group = vp_parser.add_mutually_exclusive_group(required=True) - vp_parser.add_argument("-d", "--database", required=True, type=str, help="Path to the database.") + vp_parser.add_argument("-d", "--database", type=str, help="Path to the database.") vp_parser.add_argument("-purl", "--package-url", help="PackageURL for policy template.") vp_group.add_argument("-f", "--file", type=str, help="Path to the Datalog policy.") vp_group.add_argument("-e", "--existing-policy", help="Name of the existing policy to run.") From 901058276c2603a9bb497fa873a88de5b4dd542b Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Tue, 18 Nov 2025 11:43:26 +0530 Subject: [PATCH 14/15] refactor: improve list-policies UI. Signed-off-by: Demolus13 --- src/macaron/__main__.py | 5 ++++- src/macaron/console.py | 7 +++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/macaron/__main__.py b/src/macaron/__main__.py index f60e9df24..ec6f01e7d 100644 --- a/src/macaron/__main__.py +++ b/src/macaron/__main__.py @@ -230,10 +230,13 @@ def verify_policy(verify_policy_args: argparse.Namespace) -> int: logger.error("Policy directory %s not found.", policy_dir) return os.EX_OSFILE + policies_with_desc = dict(sorted(policies_with_desc.items())) rich_handler = access_handler.get_handler() rich_handler.set_available_policies(policies_with_desc) - logger.info("Available policies are:\n\t%s", "\n\t".join(sorted(policies_with_desc))) + logger.info( + "Available policies are:\n%s", "\n".join(f"{name}\n{desc}\n" for name, desc in policies_with_desc.items()) + ) return os.EX_OK if verify_policy_args.file: diff --git a/src/macaron/console.py b/src/macaron/console.py index a76052d85..10a624dd4 100644 --- a/src/macaron/console.py +++ b/src/macaron/console.py @@ -80,10 +80,13 @@ def _make_reports_table(reports: dict) -> Table: def _make_policies_table(policies: dict[str, str]) -> Table: """Build a two-column table of policy name and a short description.""" table = Table(box=None) - table.add_column("Policy", justify="left", style="bold") + table.add_column("[blue]Policy[/]", justify="left", style="blue bold") table.add_column("Description", justify="left") - for name, desc in policies.items(): + total_policies = len(policies) + for i, (name, desc) in enumerate(policies.items()): table.add_row(name, desc) + if i < total_policies - 1: + table.add_row() return table From 2bf5a58e94b7d6dd0c49444c3db2c4c74c3c96c7 Mon Sep 17 00:00:00 2001 From: Demolus13 Date: Tue, 18 Nov 2025 19:30:41 +0530 Subject: [PATCH 15/15] docs: correct usage in tutorial. Signed-off-by: Demolus13 --- docs/source/pages/tutorials/verify_with_existing_policy.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/pages/tutorials/verify_with_existing_policy.rst b/docs/source/pages/tutorials/verify_with_existing_policy.rst index 26d9eaf9c..4a61b3f17 100644 --- a/docs/source/pages/tutorials/verify_with_existing_policy.rst +++ b/docs/source/pages/tutorials/verify_with_existing_policy.rst @@ -58,16 +58,16 @@ Run the ``malware-detection`` policy using wildcard: ./run_macaron.sh verify-policy \ --database output/macaron.db \ --existing-policy malware-detection \ - --package-url "pkg:pypi/django@*" + --package-url "pkg:pypi/django@.*" -It uses the wildcard '*' to checks for components satisfying the expression "pkg:pypi/django@*". +It uses the wildcard '*' to checks for components satisfying the expression "pkg:pypi/django@.*". The result of this command should show that the policy succeeds with a zero exit code (if a policy fails to pass, Macaron returns a none-zero error code): .. code-block:: shell Components Satisfy Policy 1 pkg:pypi/django@5.0.6 check-component - 1 pkg:pypi/django@1.11.1 check-component + 2 pkg:pypi/django@1.11.1 check-component Components Violate Policy None