refactor: add --list-policies flag to check for available policies.

Signed-off-by: Demolus13 <[email protected]>

Author: Demolus13

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
 

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("<PACKAGE_PURL>", 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.

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("<PACKAGE_PURL>*", purl).
+  match("<PACKAGE_PURL>", purl).

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("<PACKAGE_PURL>*", purl).
+    match("<PACKAGE_PURL>", purl).

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("<PACKAGE_PURL>*", purl).
+    match("<PACKAGE_PURL>", purl).

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,