chore: add descriptions for each existing policy and a test to verify the .description file

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

Author: Demolus13

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 <policy-name>`.

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.

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.

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

src/macaron/resources/policies/datalog/malware-detection-dependencies.description

@@ -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),

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

@@ -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.

src/macaron/resources/policies/datalog/malware-detection.description

@@ -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)