feat: add --existing-policy flag in verify-policy command for example policies #1189

Demolus13 · 2025-09-28T14:06:09Z

Summary

This Pull Request introduces a new --existing-policy flag to the verify-policy command, allowing users to run example policies by name without specifying a file path. It also adds support for policy templates.

The new --existing-policy (-e) flag executes a predefined policy template by name. If the template exists, it populates the <PACKAGE_PURL> placeholder with the value from the --package-url (-purl) argument and runs the policy. If the template name is not found, it lists all available templates.

Example policies

A malware detection policy for the package (based on the malware detection tutorial)

macaron analyze -purl pkg:pypi/[email protected]
macaron verify-policy --database output/macaron.db --existing-policy malware-detection -purl pkg:pypi/django

A malware detection policy for the package and all its dependencies (based on the malware detection tutorial)

python3.11 -m venv /tmp/.django_venv
/tmp/.django_venv/bin/pip install django==5.0.6
macaron analyze -purl pkg:pypi/[email protected] --python-venv "/tmp/.django_venv" --deps-depth=1  
macaron verify-policy --database output/macaron.db --existing-policy malware-detection-dependencies -purl pkg:pypi/django

Analyzing GitHub Actions (tutorial)

macaron analyze -purl pkg:maven/org.apache.logging.log4j/[email protected]
macaron verify-policy --database output/macaron.db --existing-policy check-github-actions -purl pkg:maven/org.apache.logging.log4j/log4j-core

Description of changes

Added a --existing-policy (-e) argument to the verify-policy CLI command, enabling users to select and run example policies from the built-in resources.
Updated the policy loading logic to support both file-based and named example policies. If a policy name is provided, the command loads the corresponding template from the resources/policies/datalog directory.
Added support for the --package-url (-purl) argument to substitute the <PACKAGE_PURL> placeholder in policy templates.
Added new example policy templates for common use cases.
Added new test cases for --existing-policy (-e) flag in tests/policy_engine/test_existing_policy.py

Related issues

N/A

Checklist

I have reviewed the contribution guide.
My PR title and commits follow the Conventional Commits convention.
My commits include the "Signed-off-by" line.
I have signed my commits following the instructions provided by GitHub. Note that we run GitHub's commit verification tool to check the commit signatures. A green verified label should appear next to all of your commits on GitHub.
I have updated the relevant documentation, if applicable.
I have tested my changes and verified they work as expected.

behnazh-w

Please add a unit test to tests/policy_engine/test_policy.py. Also add an integration test.

src/macaron/__main__.py

behnazh-w · 2025-10-30T01:29:46Z

src/macaron/__main__.py

            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")]


It would be good to avoid hardcoding [:-12].

Suggested change

available_policies = [policy[:-12] for policy in os.listdir(policy_dir) if policy.endswith(".dl.template")]

policy_suffix = ".dl.template"

available_policies = [

os.path.splitext(policy)[0].replace(policy_suffix, "")

for policy in os.listdir(policy_dir)

if policy.endswith(policy_suffix)

]

behnazh-w · 2025-10-30T06:40:56Z

src/macaron/__main__.py

+        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:


Let's check that the PURL using the packageurl library, which is already a dependency of Macaron:

try: PackageURL.from_string(verify_policy_args.package_url) except ValueError as error: logger.error("The package url %s is not valid.", verify_policy_args.package_url) return os.EX_USAGE

src/macaron/__main__.py

behnazh-w · 2025-11-04T05:58:30Z

src/macaron/resources/policies/datalog/malware-detection-dependencies.dl.template

+
+apply_policy_to("check-dependencies", component_id) :-
+    is_component(component_id, purl),
+    match("<PACKAGE_PURL>@.*", purl).


What if the user provides a PURL that contains version as well? Then the policy won't match the PURL.

Does removing @.* resolve the issue?

from

match("<PACKAGE_PURL>@.*", purl).

to

match("<PACKAGE_PURL>", purl).

Yes, but that would mean we can't use wildcards, which are useful for creating more generic policies that apply to all versions. Alternatively, we could allow the wildcard within the PURL argument itself 🤔

behnazh-w

I suggest we add a --list-policies option to verify-policy, allowing users to easily see and choose from the available policies. We should also update the tutorial to include this new option. Additionally, we can provide a description file for each template policy and display that information when the command is used. To ensure consistency, let’s add a unit test that verifies every template policy has an associated description file.

behnazh-w · 2025-11-11T04:35:20Z