chore: address comments from PR#873.

- Generate API documents for modified and new code.
- Make the repository verification check generic.
- Fix repo verification fact parameter docs.

Signed-off-by: Mohammad Abdollahpour <[email protected]>

docs/source/index.rst

@@ -89,6 +89,9 @@ the requirements that are currently supported by Macaron.
    * - ``mcn_provenance_derived_commit_1``
      - **Provenance derived commit** - Check if the analysis target's commit matches the commit in the provenance.
      - If there is no commit, this check will fail.
+   * - ``mcn_repo_verification_1``
+     - **Source version controlled** - Check if every change to the source is tracked in a version control system.
+     - If the claimed source repository provenance made by a package is not verified, this check will fail. If no claim of a source repository could be found or the build system is not supported, the result of the check will be "unknown".
 
 ****************************************************************************************
 Macaron checks that report integrity issues but do not map to SLSA requirements directly

docs/source/pages/developers_guide/apidoc/macaron.parsers.rst

@@ -40,3 +40,11 @@ macaron.parsers.github\_workflow\_model module
    :members:
    :undoc-members:
    :show-inheritance:
+
+macaron.parsers.pomparser module
+--------------------------------
+
+.. automodule:: macaron.parsers.pomparser
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pages/developers_guide/apidoc/macaron.repo_verifier.rst

@@ -0,0 +1,42 @@
+macaron.repo\_verifier package
+==============================
+
+.. automodule:: macaron.repo_verifier
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+macaron.repo\_verifier.repo\_verifier module
+--------------------------------------------
+
+.. automodule:: macaron.repo_verifier.repo_verifier
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+macaron.repo\_verifier.repo\_verifier\_base module
+--------------------------------------------------
+
+.. automodule:: macaron.repo_verifier.repo_verifier_base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+macaron.repo\_verifier.repo\_verifier\_gradle module
+----------------------------------------------------
+
+.. automodule:: macaron.repo_verifier.repo_verifier_gradle
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+macaron.repo\_verifier.repo\_verifier\_maven module
+---------------------------------------------------
+
+.. automodule:: macaron.repo_verifier.repo_verifier_maven
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pages/developers_guide/apidoc/macaron.rst

@@ -21,6 +21,7 @@ Subpackages
    macaron.parsers
    macaron.policy_engine
    macaron.repo_finder
+   macaron.repo_verifier
    macaron.slsa_analyzer
    macaron.vsa
 

docs/source/pages/developers_guide/apidoc/macaron.slsa_analyzer.checks.rst

@@ -121,6 +121,14 @@ macaron.slsa\_analyzer.checks.provenance\_witness\_l1\_check module
    :undoc-members:
    :show-inheritance:
 
+macaron.slsa\_analyzer.checks.repo\_verification\_check module
+--------------------------------------------------------------
+
+.. automodule:: macaron.slsa_analyzer.checks.repo_verification_check
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 macaron.slsa\_analyzer.checks.trusted\_builder\_l3\_check module
 ----------------------------------------------------------------
 

src/macaron/slsa_analyzer/checks/maven_repo_verification_check.py → src/macaron/slsa_analyzer/checks/repo_verification_check.py

@@ -1,7 +1,7 @@
 # Copyright (c) 2024 - 2024, 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/.
 
-"""A check to determine whether the source repository of a maven package can be independently verified."""
+"""A check to determine whether the source repository of a package can be independently verified."""
 
 import logging
 
@@ -14,59 +14,63 @@
 from macaron.repo_verifier.repo_verifier_base import RepositoryVerificationStatus
 from macaron.slsa_analyzer.analyze_context import AnalyzeContext
 from macaron.slsa_analyzer.checks.base_check import BaseCheck
-from macaron.slsa_analyzer.checks.check_result import CheckResultData, CheckResultType, Confidence
+from macaron.slsa_analyzer.checks.check_result import CheckResultData, CheckResultType, Confidence, JustificationType
 from macaron.slsa_analyzer.registry import registry
 
 logger: logging.Logger = logging.getLogger(__name__)
 
 
-class MavenRepoVerificationFacts(CheckFacts):
-    """The ORM mapping for justifications in maven source repo check."""
+class RepoVerificationFacts(CheckFacts):
+    """The ORM mapping for justifications in repo verification check."""
 
-    __tablename__ = "_maven_repo_verification_check"
+    __tablename__ = "_repo_verification_check"
 
     #: The primary key.
     id: Mapped[int] = mapped_column(ForeignKey("_check_facts.id"), primary_key=True)  # noqa: A003
 
-    group: Mapped[str] = mapped_column(String, nullable=False)
-    artifact: Mapped[str] = mapped_column(String, nullable=False)
-    version: Mapped[str] = mapped_column(String, nullable=False)
-
-    # Repository link identified by Macaron's repo finder.
+    #: Repository link identified by Macaron's repo finder.
     repo_link: Mapped[str] = mapped_column(String, nullable=True)
 
-    # Repository link identified by deps.dev.
-    deps_dev_repo_link: Mapped[str | None] = mapped_column(String, nullable=True)
+    #: Repository link identified by deps.dev.
+    deps_dev_repo_link: Mapped[str | None] = mapped_column(
+        String, nullable=True, info={"justification": JustificationType.HREF}
+    )
 
-    # Number of stars on the repository identified by deps.dev.
-    deps_dev_stars_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    #: Number of stars on the repository identified by deps.dev.
+    deps_dev_stars_count: Mapped[int | None] = mapped_column(
+        Integer, nullable=True, info={"justification": JustificationType.TEXT}
+    )
 
-    # Number of forks on the repository identified by deps.dev.
-    deps_dev_fork_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    #: Number of forks on the repository identified by deps.dev.
+    deps_dev_fork_count: Mapped[int | None] = mapped_column(
+        Integer, nullable=True, info={"justification": JustificationType.TEXT}
+    )
 
-    # The status of the check: passed, failed, or unknown.
-    status: Mapped[str] = mapped_column(String, nullable=False)
+    #: The status of the check: passed, failed, or unknown.
+    status: Mapped[str] = mapped_column(String, nullable=False, info={"justification": JustificationType.TEXT})
 
-    # The reason for the status.
-    reason: Mapped[str] = mapped_column(String, nullable=False)
+    #: The reason for the status.
+    reason: Mapped[str] = mapped_column(String, nullable=False, info={"justification": JustificationType.TEXT})
 
-    # The build tool used to build the package.
-    build_tool: Mapped[str] = mapped_column(String, nullable=False)
+    #: The build tool used to build the package.
+    build_tool: Mapped[str] = mapped_column(String, nullable=False, info={"justification": JustificationType.TEXT})
 
     __mapper_args__ = {
-        "polymorphic_identity": "_maven_repo_verification_check",
+        "polymorphic_identity": "_repo_verification_check",
     }
 
 
-class MavenRepoVerificationCheck(BaseCheck):
-    """Check whether the claims of a source repository provenance made by a maven package can be independently verified."""
+class RepoVerificationCheck(BaseCheck):
+    """Check whether the claims of a source repository provenance made by a package can be independently verified."""
 
     def __init__(self) -> None:
         """Initialize a check instance."""
-        check_id = "mcn_maven_repo_verification_1"
+        check_id = "mcn_repo_verification_1"
         description = (
             "Check whether the claims of a source repository provenance"
-            " made by a maven package can be independently verified."
+            " made by a package can be independently verified."
+            " At this moment, this check only supports Maven packages"
+            " and returns UNKNOWN for others."
         )
 
         super().__init__(
@@ -87,6 +91,8 @@ def run_check(self, ctx: AnalyzeContext) -> CheckResultData:
         CheckResultData
             The result of the check.
         """
+        # Only support Maven at the moment.
+        # TODO: Add support for other systems.
         if ctx.component.type != "maven":
             return CheckResultData(result_tables=[], result_type=CheckResultType.UNKNOWN)
 
@@ -105,10 +111,7 @@ def run_check(self, ctx: AnalyzeContext) -> CheckResultData:
         result_tables: list[CheckFacts] = []
         for verification_result in ctx.dynamic_data.get("repo_verification", []):
             result_tables.append(
-                MavenRepoVerificationFacts(
-                    group=ctx.component.namespace,
-                    artifact=ctx.component.name,
-                    version=ctx.component.version,
+                RepoVerificationFacts(
                     repo_link=ctx.component.repository.remote_path if ctx.component.repository else None,
                     reason=verification_result.reason,
                     status=verification_result.status.value,
@@ -129,4 +132,4 @@ def run_check(self, ctx: AnalyzeContext) -> CheckResultData:
         return CheckResultData(result_tables=result_tables, result_type=result_type)
 
 
-registry.register(MavenRepoVerificationCheck())
+registry.register(RepoVerificationCheck())

tests/integration/cases/maven_repo_verification/config.ini → tests/integration/cases/repo_verification/config.ini

@@ -3,4 +3,4 @@
 
 [analysis.checks]
 exclude =
-include = mcn_maven_repo_verification_1
+include = mcn_repo_verification_1

tests/integration/cases/maven_repo_verification/policy_fail_1.dl → tests/integration/cases/repo_verification/policy_fail_1.dl

@@ -4,7 +4,7 @@
 #include "prelude.dl"
 
 Policy("test_policy", component_id, "") :-
-    check_failed(component_id, "mcn_maven_repo_verification_1").
+    check_failed(component_id, "mcn_repo_verification_1").
 
 apply_policy_to("test_policy", component_id) :-
     is_component(component_id, "pkg:maven/com.alibaba.ververica/[email protected]").

tests/integration/cases/maven_repo_verification/policy_pass_1.dl → tests/integration/cases/repo_verification/policy_pass_1.dl

@@ -4,7 +4,7 @@
 #include "prelude.dl"
 
 Policy("test_policy", component_id, "") :-
-    check_passed(component_id, "mcn_maven_repo_verification_1").
+    check_passed(component_id, "mcn_repo_verification_1").
 
 apply_policy_to("test_policy", component_id) :-
     is_component(component_id, "pkg:maven/org.antlr/[email protected]").

tests/integration/cases/maven_repo_verification/policy_pass_2.dl → tests/integration/cases/repo_verification/policy_pass_2.dl

@@ -4,7 +4,7 @@
 #include "prelude.dl"
 
 Policy("test_policy", component_id, "") :-
-    check_passed(component_id, "mcn_maven_repo_verification_1").
+    check_passed(component_id, "mcn_repo_verification_1").
 
 apply_policy_to("test_policy", component_id) :-
     is_component(component_id, "pkg:maven/org.neo4j/[email protected]").

tests/integration/cases/maven_repo_verification/test.yaml → tests/integration/cases/repo_verification/test.yaml

@@ -2,7 +2,7 @@
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 description: |
-  Integration tests for mcn_maven_repo_verification_1 check.
+  Integration tests for mcn_repo_verification_1 check.
 
 tags:
 - macaron-python-package

tests/slsa_analyzer/checks/test_maven_repo_verification_check.py → tests/slsa_analyzer/checks/test_repo_verification_check.py

@@ -1,14 +1,14 @@
 # Copyright (c) 2024 - 2024, 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/.
 
-"""Module to test the maven repository verification check."""
+"""Module to test the repository verification check."""
 
 from pathlib import Path
 
 from macaron.repo_verifier.repo_verifier_base import RepositoryVerificationResult, RepositoryVerificationStatus
 from macaron.slsa_analyzer.build_tool.base_build_tool import BaseBuildTool
 from macaron.slsa_analyzer.checks.check_result import CheckResultType
-from macaron.slsa_analyzer.checks.maven_repo_verification_check import MavenRepoVerificationCheck
+from macaron.slsa_analyzer.checks.repo_verification_check import RepoVerificationCheck
 from macaron.slsa_analyzer.package_registry import PyPIRegistry
 from macaron.slsa_analyzer.package_registry.maven_central_registry import MavenCentralRegistry
 from macaron.slsa_analyzer.specs.package_registry_spec import PackageRegistryInfo
@@ -19,7 +19,7 @@
 
 def test_repo_verification_pass(maven_tool: BaseBuildTool, macaron_path: Path) -> None:
     """Test that the check passes when the repository is verified."""
-    check = MavenRepoVerificationCheck()
+    check = RepoVerificationCheck()
 
     ctx = MockAnalyzeContext(macaron_path=macaron_path, output_dir="", purl="pkg:maven/test/test")
     maven_registry = MavenCentralRegistry()
@@ -37,7 +37,7 @@ def test_repo_verification_pass(maven_tool: BaseBuildTool, macaron_path: Path) -
 
 def test_repo_verification_fail(maven_tool: BaseBuildTool, macaron_path: Path) -> None:
     """Test that the check fails when the repository verification is failed."""
-    check = MavenRepoVerificationCheck()
+    check = RepoVerificationCheck()
 
     ctx = MockAnalyzeContext(macaron_path=macaron_path, output_dir="", purl="pkg:maven/test/test")
     maven_registry = MavenCentralRegistry()
@@ -55,7 +55,7 @@ def test_repo_verification_fail(maven_tool: BaseBuildTool, macaron_path: Path) -
 
 def test_repo_verification_unknown_for_unknown_repo_verification(maven_tool: BaseBuildTool, macaron_path: Path) -> None:
     """Test that the check returns unknown when the repository verification is unknown."""
-    check = MavenRepoVerificationCheck()
+    check = RepoVerificationCheck()
 
     ctx = MockAnalyzeContext(macaron_path=macaron_path, output_dir="", purl="pkg:maven/test/test")
     maven_registry = MavenCentralRegistry()
@@ -73,7 +73,7 @@ def test_repo_verification_unknown_for_unknown_repo_verification(maven_tool: Bas
 
 def test_repo_verification_unknown_for_unsupported_build_tools(pip_tool: BaseBuildTool, macaron_path: Path) -> None:
     """Test that the check returns unknown for unsupported build tools."""
-    check = MavenRepoVerificationCheck()
+    check = RepoVerificationCheck()
 
     ctx = MockAnalyzeContext(macaron_path=macaron_path, output_dir="", purl="pkg:pypi/test/test")
     pypi_registry = PyPIRegistry()