guarddog 2.5.0__py3-none-any.whl → 2.6.0__py3-none-any.whl

guarddog/reporters/reporter_factory.py

@@ -0,0 +1,50 @@
+from enum import Enum, auto
+from typing import Optional
+
+from guarddog.reporters import BaseReporter
+from guarddog.reporters.human_readable import HumanReadableReporter
+from guarddog.reporters.sarif import SarifReporter
+from guarddog.reporters.json import JsonReporter
+
+
+class ReporterType(Enum):
+    """
+    Enum representing the different types of reporters available.
+    """
+
+    HUMAN_READABLE = auto()
+    SARIF = auto()
+    JSON = auto()
+
+    @classmethod
+    def from_str(cls, type: Optional[str]) -> "ReporterType":
+        if not type:
+            return cls.HUMAN_READABLE
+        match (type).lower():
+            case "human_readable":
+                return cls.HUMAN_READABLE
+            case "sarif":
+                return cls.SARIF
+            case "json":
+                return cls.JSON
+            case _:
+                raise ValueError(f"Unsupported reporter type: {type}")
+
+
+class ReporterFactory:
+    """
+    Factory class for creating reporter instances based on the reporter type.
+    """
+
+    @staticmethod
+    def create_reporter(reporter_type: ReporterType) -> type[BaseReporter]:
+        """
+        Create a reporter instance based on the reporter type.
+        """
+        match reporter_type:
+            case ReporterType.HUMAN_READABLE:
+                return HumanReadableReporter
+            case ReporterType.SARIF:
+                return SarifReporter
+            case ReporterType.JSON:
+                return JsonReporter

guarddog/reporters/sarif.py

@@ -4,181 +4,187 @@ import json
 from guarddog.analyzer.sourcecode import get_sourcecode_rules
 from guarddog.analyzer.metadata import get_metadata_detectors
 from guarddog.ecosystems import ECOSYSTEM
+from guarddog.reporters import BaseReporter
+from guarddog.scanners.scanner import DependencyFile
+from typing import List
+from guarddog.reporters.human_readable import HumanReadableReporter
+
+
+class SarifReporter(BaseReporter):
+    """
+    Sarif is a class that formats and prints scan results in the SARIF format.
+    """
+
+    @staticmethod
+    def render_verify(
+        dependency_files: List[DependencyFile],
+        rule_names: list[str],
+        scan_results: list[dict],
+        ecosystem: ECOSYSTEM,
+    ) -> tuple[str, str]:
+        """
+        Report the scans results in the SARIF format.
+
+        Args:
+            scan_results (dict): The scan results to be reported.
+        """
+
+        def build_rules_help_list() -> dict:
+            """
+            Builds a dict with the names of all available rules and their documentation
+            @return: dict[name_of_rule, rule_description]
+            """
+            rules_documentation = {}
+            for ecosystem in ECOSYSTEM:
+                rules = get_metadata_detectors(ecosystem)
+                for name, instance in rules.items():
+                    detector_class = instance.__class__.__base__
+                    rules_documentation[name] = detector_class.__doc__
+                for sourcecode_rule in get_sourcecode_rules(ecosystem):
+                    rules_documentation[sourcecode_rule.id] = (
+                        sourcecode_rule.description
+                    )
+            return rules_documentation
+
+        def get_sarif_log(runs):
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#sariflog-object
+            """
+            return {
+                "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+                "version": "2.1.0",
+                "runs": runs,
+            }
 
+        def get_run(results, driver):
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#run-object
+            """
+            return {"tool": {"driver": driver}, "results": results}
+
+        def get_driver(rules, ecosystem: str):
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#toolcomponent-object
+            """
+            return {
+                "name": f"GuardDog-{ecosystem}",
+                "informationUri": "https://github.com/DataDog/guarddog",
+                "rules": rules,
+            }
 
-def build_rules_help_list() -> dict:
-    """
-    Builds a dict with the names of all available rules and their documentation
-    @return: dict[name_of_rule, rule_description]
-    """
-    rules_documentation = {}
-    for ecosystem in ECOSYSTEM:
-        rules = get_metadata_detectors(ecosystem)
-        for name, instance in rules.items():
-            detector_class = instance.__class__.__base__
-            rules_documentation[name] = detector_class.__doc__
-        for sourcecode_rule in get_sourcecode_rules(ecosystem):
-            rules_documentation[sourcecode_rule.id] = sourcecode_rule.description
-    return rules_documentation
-
-
-def get_sarif_log(runs):
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#sariflog-object
-    """
-    return {
-        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
-        "version": "2.1.0",
-        "runs": runs
-    }
-
-
-def get_run(results, driver):
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#run-object
-    """
-    return {
-        "tool": {
-            "driver": driver
-        },
-        "results": results
-    }
-
-
-def get_driver(rules, ecosystem: str):
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#toolcomponent-object
-    """
-    return {
-        "name": f"GuardDog-{ecosystem}",
-        "rules": rules
-    }
-
-
-def get_rule(rule_name: str, rules_documentation) -> dict:
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#reportingdescriptor-object
-    """
-    message = rules_documentation[rule_name] if rules_documentation[rule_name] is not None else ""
-    return {
-        "id": rule_name,
-        "defaultConfiguration": {
-            "level": "warning"
-        },
-        "shortDescription": {
-            "text": f"GuardDog rule: {rule_name}"
-        },
-        "fullDescription": {
-            "text": message
-        },
-        "help": {
-            "text": message,
-            "markdown": message
-        },
-        "properties": {
-            "precision": "medium"
-        }
-    }
-
-
-def get_result(rule_name, locations, text, partial_fingerprints):
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#result-object
-    """
-    return {
-        "ruleId": rule_name,
-        "message": {
-            "text": text
-        },
-        "locations": locations,
-        "partialFingerprints": partial_fingerprints
-    }
-
-
-def get_location(physical_location):
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#location-object
-    """
-    return {
-        "physicalLocation": physical_location
-    }
+        def get_rule(rule_name: str, rules_documentation) -> dict:
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#reportingdescriptor-object
+            """
+            message = (
+                rules_documentation[rule_name]
+                if rules_documentation[rule_name] is not None
+                else ""
+            )
+            return {
+                "id": rule_name,
+                "defaultConfiguration": {"level": "warning"},
+                "shortDescription": {"text": f"GuardDog rule: {rule_name}"},
+                "fullDescription": {"text": message},
+                "help": {"text": message, "markdown": message},
+                "properties": {"precision": "medium"},
+            }
 
+        def get_result(rule_name, locations, text, partial_fingerprints):
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#result-object
+            """
+            return {
+                "ruleId": rule_name,
+                "message": {"text": text},
+                "locations": locations,
+                "partialFingerprints": partial_fingerprints,
+            }
 
-def get_physical_location(uri, region):
-    """
-    https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#physicallocation-object
-    """
-    return {
-        "artifactLocation": {
-            "uri": uri
-        },
-        "region": region
-    }
-
-
-def get_region(package_raw: str, package: str) -> dict:
-    start_line = 0
-    start_column = 0
-    end_column = 0
-    for idx, val in enumerate(package_raw.split("\n")):
-        if package in val:
-            start_line = idx + 1
-            start_column = val.index(package) + 1
-            end_column = start_column + len(package)
-
-    return {
-        "startLine": start_line,
-        "endLine": start_line,
-        "startColumn": start_column,
-        "endColumn": end_column,
-    }
-
-
-def report_verify_sarif(
-    package_path: str,
-    rule_names: list[str],
-    scan_results: list[dict],
-    ecosystem: ECOSYSTEM,
-) -> str:
-    rules_documentation = build_rules_help_list()
-    rules = list(map(
-        lambda s: get_rule(s, rules_documentation),
-        rule_names
-    ))
-    driver = get_driver(rules, ecosystem.value)
-    results = []
-
-    with open(package_path, "r") as file:
-        package_raw = file.read()
-
-    for entry in scan_results:
-        if entry["result"]["issues"] == 0:
-            continue
-
-        region = get_region(package_raw, entry["dependency"])
-        uri = package_path[2:] if package_path.startswith('./') else package_path
-        physical_location = get_physical_location(uri, region)
-        location = get_location(physical_location)
-        scan_result_details = entry["result"]["results"]
-        package = entry["dependency"]
-        version = entry["version"]
-        for rule_name in scan_result_details.keys():
-            if scan_result_details[rule_name] is None or len(scan_result_details[rule_name]) == 0:
+        def get_location(physical_location):
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#location-object
+            """
+            return {"physicalLocation": physical_location}
+
+        def get_physical_location(uri, region):
+            """
+            https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#physicallocation-object
+            """
+            return {"artifactLocation": {"uri": uri}, "region": region}
+
+        def get_region(
+            dependency_files: List[DependencyFile], package: str
+        ) -> tuple[DependencyFile, dict]:
+            for dependency_file in dependency_files:
+                for d in dependency_file.dependencies:
+                    if d.name == package:
+                        return dependency_file, {
+                            "startLine": list(d.versions)[0].location,
+                            "endLine": list(d.versions)[0].location,
+                            "startColumn": 1,
+                            "endColumn": len(package),
+                        }
+            raise ValueError(
+                f"Could not find the package {package} in the dependency files"
+            )
+
+        rules_documentation = build_rules_help_list()
+        rules = list(map(lambda s: get_rule(s, rules_documentation), rule_names))
+        driver = get_driver(rules, ecosystem.value)
+        results = []
+
+        for entry in scan_results:
+            if entry["result"]["issues"] == 0:
                 continue
-            text = f"On package: {package} version: {version}\n" + "\n".join(map(
-                lambda x: x["message"],
-                scan_result_details[rule_name]
-            )) if isinstance(scan_result_details[rule_name], list) else scan_result_details[rule_name]
-            key = f"{rule_name}-{text}"
-            partial_fingerprints = {
-                f"guarddog/v1/{rule_name}": hashlib.sha256(key.encode('utf-8')).hexdigest()
-            }
-            result = get_result(rule_name,
-                                [location],
-                                text,
-                                partial_fingerprints)
-            results.append(result)
-
-    runs = get_run(results, driver)
-    log = get_sarif_log([runs])
-    return json.dumps(log, indent=2)
+
+            dep_file, region = get_region(
+                dependency_files=dependency_files, package=entry["dependency"]
+            )
+            package_path = dep_file.file_path
+            uri = package_path[2:] if package_path.startswith("./") else package_path
+            physical_location = get_physical_location(uri, region)
+            location = get_location(physical_location)
+            scan_result_details = entry["result"]["results"]
+            package = entry["dependency"]
+            version = entry["version"]
+            for rule_name in scan_result_details.keys():
+                if (
+                    scan_result_details[rule_name] is None
+                    or len(scan_result_details[rule_name]) == 0
+                ):
+                    continue
+
+                text = (
+                    f"On package: {package} version: {version}\n"
+                    + "\n".join(
+                        map(
+                            lambda x: f"{x['message']} in file {x['location']}",
+                            scan_result_details[rule_name],
+                        )
+                    )
+                    if isinstance(scan_result_details[rule_name], list)
+                    else scan_result_details[rule_name]
+                )
+                key = f"{rule_name}-{text}"
+                partial_fingerprints = {
+                    f"guarddog/v1/{rule_name}": hashlib.sha256(
+                        key.encode("utf-8")
+                    ).hexdigest()
+                }
+                result = get_result(rule_name, [location], text, partial_fingerprints)
+                results.append(result)
+
+        runs = get_run(results, driver)
+        log = get_sarif_log([runs])
+
+        errors = "\n".join(
+            [
+                HumanReadableReporter.print_errors(
+                    identifier=r["dependency"], results=r["result"]
+                )
+                for r in scan_results
+            ]
+        )
+
+        return (json.dumps(log, indent=2), errors)

guarddog/scanners/github_action_project_scanner.py

@@ -1,4 +1,5 @@
 import logging
+import os
 from typing import List, Dict, TypedDict
 from typing_extensions import NotRequired
 
@@ -7,6 +8,7 @@ import re
 
 from guarddog.scanners.github_action_scanner import GithubActionScanner
 from guarddog.scanners.scanner import ProjectScanner
+from guarddog.scanners.scanner import Dependency, DependencyVersion
 
 log = logging.getLogger("guarddog")
 
@@ -66,17 +68,40 @@ class GitHubActionDependencyScanner(ProjectScanner):
     def __init__(self) -> None:
         super().__init__(GithubActionScanner())
 
-    def parse_requirements(self, raw_requirements: str) -> dict[str, set[str]]:
+    def parse_requirements(self, raw_requirements: str) -> List[Dependency]:
         actions = self.parse_workflow_3rd_party_actions(raw_requirements)
+        dependencies: List[Dependency] = []
 
-        requirements: dict[str, set[str]] = {}
         for action in actions:
-            repo, version = action["name"], action["ref"]
-            if repo in requirements:
-                requirements[repo].add(version)
-            else:
-                requirements[repo] = {version}
-        return requirements
+            name = action["name"]
+            version = action["ref"]
+            idx = next(
+                iter(
+                    [
+                        ix
+                        for ix, line in enumerate(raw_requirements.splitlines())
+                        if name in line
+                    ]
+                ),
+                0,
+            )
+            # find the dep with the same name or create a new one
+            dep_versions = [DependencyVersion(version=version, location=idx + 1)]
+
+            dep = next(
+                filter(
+                    lambda d: d.name == name,
+                    dependencies,
+                ),
+                None,
+            )
+            if not dep:
+                dep = Dependency(name=name, versions=set())
+                dependencies.append(dep)
+
+            dep.versions.update(dep_versions)
+
+        return dependencies
 
     def parse_workflow_3rd_party_actions(
         self, workflow_file: str
@@ -99,3 +124,17 @@ class GitHubActionDependencyScanner(ProjectScanner):
                 if action:
                     actions.append(action)
         return actions
+
+    def find_requirements(self, directory: str) -> list[str]:
+        requirement_files = []
+
+        if not os.path.isdir(os.path.join(directory, ".git")):
+            raise Exception(
+                "unable to find github workflows, not called from git directory"
+            )
+        workflow_folder = os.path.join(directory, ".github/workflows")
+        if os.path.isdir(workflow_folder):
+            for name in os.listdir(workflow_folder):
+                if re.match(r"^(.+)\.y(a)?ml$", name, flags=re.IGNORECASE):
+                    requirement_files.append(os.path.join(workflow_folder, name))
+        return requirement_files

guarddog/scanners/go_project_scanner.py

@@ -1,9 +1,12 @@
 import logging
+import os
+import re
 from dataclasses import dataclass
 from typing import List
 
 from guarddog.scanners.go_package_scanner import GoModuleScanner
 from guarddog.scanners.scanner import ProjectScanner
+from guarddog.scanners.scanner import Dependency, DependencyVersion
 
 log = logging.getLogger("guarddog")
 
@@ -26,13 +29,39 @@ class GoDependenciesScanner(ProjectScanner):
     def __init__(self) -> None:
         super().__init__(GoModuleScanner())
 
-    def parse_requirements(self, raw_requirements: str) -> dict[str, set[str]]:
+    def parse_requirements(self, raw_requirements: str) -> List[Dependency]:
         main_mod = self.parse_go_mod_file(raw_requirements)
 
-        return {
-            requirement.module: set([requirement.version])
-            for requirement in main_mod.requirements
-        }
+        dependencies: List[Dependency] = []
+        for dependency in main_mod.requirements:
+            version = dependency.version
+            name = dependency.module
+            idx = next(
+                iter(
+                    [
+                        ix
+                        for ix, line in enumerate(raw_requirements.splitlines())
+                        if name in line
+                    ]
+                ),
+                0,
+            )
+
+            dep_versions = [DependencyVersion(version=version, location=idx + 1)]
+
+            dep = next(
+                filter(
+                    lambda d: d.name == name,
+                    dependencies,
+                ),
+                None
+            )
+            if not dep:
+                dep = Dependency(name=name, versions=set())
+                dependencies.append(dep)
+
+            dep.versions.update(dep_versions)
+        return dependencies
 
     # Read https://go.dev/ref/mod#go-mod-file to learn more about the go.mod syntax
     def parse_go_mod_file(self, go_mod_content: str) -> GoModule:
@@ -66,3 +95,11 @@ class GoDependenciesScanner(ProjectScanner):
             # TODO: support exclude, replace and retract statements
 
         return GoModule(module, go, toolchain, requirements)
+
+    def find_requirements(self, directory: str) -> list[str]:
+        requirement_files = []
+        for root, dirs, files in os.walk(directory):
+            for name in files:
+                if re.match(r"^go\.mod$", name, flags=re.IGNORECASE):
+                    requirement_files.append(os.path.join(root, name))
+        return requirement_files

guarddog/scanners/npm_project_scanner.py

@@ -1,11 +1,15 @@
 import json
 import logging
+import os
+import re
+from typing import List
+
 import requests
 from semantic_version import NpmSpec, Version  # type:ignore
 
-from guarddog.utils.config import VERIFY_EXHAUSTIVE_DEPENDENCIES
 from guarddog.scanners.npm_package_scanner import NPMPackageScanner
-from guarddog.scanners.scanner import ProjectScanner
+from guarddog.scanners.scanner import Dependency, DependencyVersion, ProjectScanner
+from guarddog.utils.config import VERIFY_EXHAUSTIVE_DEPENDENCIES
 
 log = logging.getLogger("guarddog")
 
@@ -21,7 +25,7 @@ class NPMRequirementsScanner(ProjectScanner):
     def __init__(self) -> None:
         super().__init__(NPMPackageScanner())
 
-    def parse_requirements(self, raw_requirements: str) -> dict:
+    def parse_requirements(self, raw_requirements: str) -> List[Dependency]:
         """
         Parses requirements.txt specification and finds all valid
         versions of each dependency
@@ -40,8 +44,8 @@ class NPMRequirementsScanner(ProjectScanner):
             }
         """
         package = json.loads(raw_requirements)
-        dependencies = package["dependencies"] if "dependencies" in package else {}
-        dev_dependencies = (
+        dependencies_attr = package["dependencies"] if "dependencies" in package else {}
+        dev_dependencies_attr = (
             package["devDependencies"] if "devDependencies" in package else {}
         )
 
@@ -82,23 +86,63 @@ class NPMRequirementsScanner(ProjectScanner):
             return versions
 
         merged = {}  # type: dict[str, set[str]]
-        for package, selector in list(dependencies.items()) + list(
-            dev_dependencies.items()
+        for package, selector in list(dependencies_attr.items()) + list(
+            dev_dependencies_attr.items()
         ):
             if package not in merged:
                 merged[package] = set()
             merged[package].add(selector)
 
-        results = {}
+        dependencies: List[Dependency] = []
         for package, all_selectors in merged.items():
             versions = set()  # type: set[str]
             for selector in all_selectors:
                 versions = versions.union(
                     get_matched_versions(find_all_versions(package), selector)
                 )
+
             if len(versions) == 0:
                 log.error(f"Package/Version {package} not on NPM\n")
                 continue
 
-            results[package] = versions
-        return results
+            idx = next(
+                iter(
+                    [
+                        ix
+                        for ix, line in enumerate(raw_requirements.splitlines())
+                        if package in line
+                    ]
+                ),
+                0,
+            )
+
+            dep_versions = list(
+                map(
+                    lambda d: DependencyVersion(version=d, location=idx + 1),
+                    versions,
+                )
+            )
+
+            # find the dep with the same name or create a new one
+            dep = next(
+                filter(
+                    lambda d: d.name == package,
+                    dependencies,
+                ),
+                None,
+            )
+            if not dep:
+                dep = Dependency(name=package, versions=set())
+                dependencies.append(dep)
+
+            dep.versions.update(dep_versions)
+
+        return dependencies
+
+    def find_requirements(self, directory: str) -> list[str]:
+        requirement_files = []
+        for root, dirs, files in os.walk(directory):
+            for name in files:
+                if re.match(r"^package\.json$", name, flags=re.IGNORECASE):
+                    requirement_files.append(os.path.join(root, name))
+        return requirement_files