bitwarden_workflow_linter 0.0.3__py3-none-any.whl

bitwarden_workflow_linter/lint.py

@@ -0,0 +1,173 @@
+"""Module providing Lint subcommand to run custom linting rules against GitHub Action
+Workflows."""
+
+import argparse
+import os
+
+from functools import reduce
+from typing import Optional
+
+from .load import WorkflowBuilder, Rules
+from .utils import LintFinding, Settings
+
+
+class LinterCmd:
+    """Command to lint GitHub Action Workflow files
+
+    This class contains logic to lint workflows that are passed in.
+    Supporting logic is supplied to:
+      - build out the list of Rules desired
+      - select and validate the workflow files to lint
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Initailize the LinterCmd class.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.rules = Rules(settings=settings)
+
+    @staticmethod
+    def extend_parser(
+        subparsers: argparse._SubParsersAction,
+    ) -> argparse._SubParsersAction:
+        """Extends the CLI subparser with the options for LintCmd.
+
+        Add 'lint' as a subcommand along with its options and arguments
+
+        Args:
+          subparsers:
+            The main argument parser to add subcommands and arguments to
+        """
+        parser_lint = subparsers.add_parser(
+            "lint",
+            help="Verify that a GitHub Action Workflow follows all of the Rules.",
+        )
+        parser_lint.add_argument(
+            "-s",
+            "--strict",
+            action="store_true",
+            help="return non-zero exit code on warnings as well as errors",
+        )
+        parser_lint.add_argument("-f", "--files", action="append", help="files to lint")
+        parser_lint.add_argument(
+            "--output",
+            action="store",
+            help="output format: [stdout|json|md]",
+            default="stdout",
+        )
+        return subparsers
+
+    def get_max_error_level(self, findings: list[LintFinding]) -> int:
+        """Get max error level from list of findings.
+
+        Compute the maximum error level to determine the exit code required.
+        # if max(error) return exit(1); else return exit(0)
+
+        Args:
+          findings:
+            All of the findings that the linter found while linting a workflow.
+
+        Return:
+          The numeric value of the maximum lint finding
+        """
+        if len(findings) == 0:
+            return 0
+        return max(findings, key=lambda finding: finding.level.code).level.code
+
+    def lint_file(self, filename: str) -> int:
+        """Lint a single workflow.
+
+        Run all of the Workflow, Job, and Step level rules that have been enabled.
+
+        Args:
+          filename:
+            The name of the file that contains the workflow to lint
+
+        Returns:
+          The maximum error level found in the file (none, warning, error) to
+          calculate the exit code from.
+        """
+        findings = []
+        max_error_level = 0
+
+        print(f"Linting: {filename}")
+        workflow = WorkflowBuilder.build(filename)
+
+        for rule in self.rules.workflow:
+            findings.append(rule.execute(workflow))
+
+        for _, job in workflow.jobs.items():
+            for rule in self.rules.job:
+                findings.append(rule.execute(job))
+
+            if job.steps is not None:
+                for step in job.steps:
+                    for rule in self.rules.step:
+                        findings.append(rule.execute(step))
+
+        findings = list(filter(lambda a: a is not None, findings))
+
+        if len(findings) > 0:
+            for finding in findings:
+                print(f" - {finding}")
+            print()
+
+        max_error_level = self.get_max_error_level(findings)
+
+        return max_error_level
+
+    def generate_files(self, files: list[str]) -> list[str]:
+        """Generate the list of files to lint.
+
+        Searches the list of directory and/or files taken from the CLI.
+
+        Args:
+          files:
+            list of file names or directory names.
+
+        Returns:
+          A sorted set of all workflow files in the path(s) specified.
+        """
+        workflow_files = []
+        for path in files:
+            if os.path.isfile(path):
+                workflow_files.append(path)
+            elif os.path.isdir(path):
+                for subdir, _, files in os.walk(path):
+                    for filename in files:
+                        filepath = subdir + os.sep + filename
+                        if filepath.endswith((".yml", ".yaml")):
+                            workflow_files.append(filepath)
+
+        return sorted(set(workflow_files))
+
+    def run(self, input_files: list[str], strict: bool = False) -> int:
+        """Execute the LinterCmd.
+
+        Args:
+          input_files:
+            list of file names or directory names.
+          strict:
+            fail on WARNING instead of succeed
+
+        Returns
+          The return_code for the entire CLI to indicate success/failure
+        """
+        files = self.generate_files(input_files)
+
+        if len(input_files) > 0:
+            return_code = reduce(
+                lambda a, b: a if a > b else b, map(self.lint_file, files)
+            )
+
+            if return_code == 1 and not strict:
+                return_code = 0
+
+            return return_code
+        else:
+            print(f'File(s)/Directory: "{input_files}" does not exist, exiting.')
+            return -1

bitwarden_workflow_linter/load.py

@@ -0,0 +1,146 @@
+"""Module to load for Workflows and Rules."""
+
+import importlib
+
+from typing import List, Optional
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+
+from .models.job import Job
+from .models.step import Step
+from .models.workflow import Workflow
+from .rule import Rule
+from .utils import Settings
+
+
+yaml = YAML()
+
+
+class WorkflowBuilderError(Exception):
+    """Exception to indicate an error with the WorkflowBuilder."""
+
+    pass
+
+
+class WorkflowBuilder:
+    """Collection of methods to build Workflow objects."""
+
+    @classmethod
+    def __load_workflow_from_file(cls, filename: str) -> CommentedMap:
+        """Load YAML from disk.
+
+        Args:
+          filename:
+            The name of the YAML file to read.
+
+        Returns:
+          A CommentedMap that contains the dict() representation of the
+          YAML file. It includes the comments as a part of their respective
+          objects (depending on their location in the file).
+        """
+        with open(filename, encoding="utf8") as file:
+            return yaml.load(file)
+
+    @classmethod
+    def __build_workflow(cls, loaded_yaml: CommentedMap) -> Workflow:
+        """Parse the YAML and build out the workflow to run Rules against.
+
+        Args:
+          loaded_yaml:
+            YAML that was loaded from either code or a file
+
+        Returns
+          A Workflow to run linting Rules against
+        """
+        return Workflow.init("", loaded_yaml)
+
+    @classmethod
+    def build(
+        cls,
+        filename: Optional[str] = None,
+        workflow: Optional[CommentedMap] = None,
+        from_file: bool = True,
+    ) -> Workflow:
+        """Build a Workflow from either code or a file.
+
+        This is a method that assists in testing by abstracting the disk IO
+        and allows for passing in a YAML object in code.
+
+        Args:
+          filename:
+            The name of the file to load the YAML workflow from
+          yaml:
+            Pre-loaded YAML of a workflow
+          from_file:
+            Flag to determine if the YAML has already been loaded or needs to
+            be loaded from disk
+        """
+        if from_file and filename is not None:
+            return cls.__build_workflow(cls.__load_workflow_from_file(filename))
+        elif not from_file and workflow is not None:
+            return cls.__build_workflow(workflow)
+
+        raise WorkflowBuilderError(
+            "The workflow must either be built from a file or from a CommentedMap"
+        )
+
+
+class LoadRulesError(Exception):
+    """Exception to indicate an error with loading rules."""
+
+    pass
+
+
+class Rules:
+    """A collection of all of the types of rules.
+
+    Rules is used as a collection of which Rules apply to which parts of the
+    workflow. It also assists in making sure the Rules that apply to multiple
+    types are not skipped.
+    """
+
+    workflow: List[Rule] = []
+    job: List[Rule] = []
+    step: List[Rule] = []
+
+    def __init__(self, settings: Settings) -> None:
+        """Initializes the Rules
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        # [TODO]: data resiliency
+        for rule in settings.enabled_rules:
+            module_name = rule.split(".")
+            module_name = ".".join(module_name[:-1])
+            rule_name = rule.split(".")[-1]
+
+            try:
+                rule_class = getattr(importlib.import_module(module_name), rule_name)
+                rule_inst = rule_class(settings=settings)
+
+                if Workflow in rule_inst.compatibility:
+                    self.workflow.append(rule_inst)
+                if Job in rule_inst.compatibility:
+                    self.job.append(rule_inst)
+                if Step in rule_inst.compatibility:
+                    self.step.append(rule_inst)
+            except LoadRulesError as err:
+                print(f"Error loading: {rule}\n{err}")
+
+    def list(self) -> None:
+        """Print the loaded Rules."""
+        print("===== Loaded Rules =====")
+        print("workflow rules:")
+        for rule in self.workflow:
+            print(f" - {type(rule).__name__}")
+        print("job rules:")
+        for rule in self.job:
+            print(f" - {type(rule).__name__}")
+        print("step rules:")
+        for rule in self.step:
+            print(f" - {type(rule).__name__}")
+        print("========================\n")

bitwarden_workflow_linter/models/job.py

@@ -0,0 +1,56 @@
+"""Representation for a job in a GitHub Action workflow."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Self
+
+from dataclasses_json import config, dataclass_json, Undefined
+from ruamel.yaml.comments import CommentedMap
+
+from .step import Step
+
+
+@dataclass_json(undefined=Undefined.EXCLUDE)
+@dataclass
+class Job:
+    """Represents a job in a GitHub Action workflow.
+
+    This object contains all of the data that is required to run the current linting
+    Rules against. If a new Rule requires a key that is missing, the attribute should
+    be added to this class to make it available for use in linting.
+    """
+
+    runs_on: Optional[str] = field(metadata=config(field_name="runs-on"), default=None)
+    key: Optional[str] = None
+    name: Optional[str] = None
+    env: Optional[CommentedMap] = None
+    steps: Optional[List[Step]] = None
+    uses: Optional[str] = None
+    uses_path: Optional[str] = None
+    uses_ref: Optional[str] = None
+    uses_with: Optional[CommentedMap] = field(
+        metadata=config(field_name="with"), default=None
+    )
+
+    @classmethod
+    def init(cls: Self, key: str, data: CommentedMap) -> Self:
+        """Custom dataclass constructor to map job data to a Job."""
+        init_data = {
+            "key": key,
+            "name": data["name"] if "name" in data else None,
+            "runs-on": data["runs-on"] if "runs-on" in data else None,
+            "env": data["env"] if "env" in data else None,
+        }
+
+        new_job = cls.from_dict(init_data)
+
+        if "steps" in data:
+            new_job.steps = [
+                Step.init(idx, new_job.key, step_data)
+                for idx, step_data in enumerate(data["steps"])
+            ]
+        else:
+            new_job.uses = data["uses"].replace("\n", "")
+            if "@" in new_job.uses:
+                new_job.uses_path, new_job.uses_ref = new_job.uses.split("@")
+
+        return new_job

bitwarden_workflow_linter/models/step.py

@@ -0,0 +1,48 @@
+"""Representation for a job step in a GitHub Action workflow."""
+
+from dataclasses import dataclass, field
+from typing import Optional, Self
+
+from dataclasses_json import config, dataclass_json, Undefined
+from ruamel.yaml.comments import CommentedMap
+
+
+@dataclass_json(undefined=Undefined.EXCLUDE)
+@dataclass
+class Step:
+    """Represents a step in a GitHub Action workflow job.
+
+    This object contains all of the data that is required to run the current linting
+    Rules against. If a new Rule requires a key that is missing, the attribute should
+    be added to this class to make it available for use in linting.
+    """
+
+    key: Optional[int] = None
+    job: Optional[str] = None
+    name: Optional[str] = None
+    env: Optional[CommentedMap] = None
+    uses: Optional[str] = None
+    uses_path: Optional[str] = None
+    uses_ref: Optional[str] = None
+    uses_comment: Optional[str] = None
+    uses_version: Optional[str] = None
+    uses_with: Optional[CommentedMap] = field(
+        metadata=config(field_name="with"), default=None
+    )
+    run: Optional[str] = None
+
+    @classmethod
+    def init(cls: Self, idx: int, job: str, data: CommentedMap) -> Self:
+        """Custom dataclass constructor to map a job step data to a Step."""
+        new_step = cls.from_dict(data)
+
+        new_step.key = idx
+        new_step.job = job
+
+        if "uses" in data.ca.items and data.ca.items["uses"][2]:
+            new_step.uses_comment = data.ca.items["uses"][2].value.replace("\n", "")
+            if "@" in new_step.uses:
+                new_step.uses_path, new_step.uses_ref = new_step.uses.split("@")
+                new_step.uses_version = new_step.uses_comment.split(" ")[-1]
+
+        return new_step

bitwarden_workflow_linter/models/workflow.py

@@ -0,0 +1,45 @@
+"""Representation for an entire GitHub Action workflow."""
+
+from dataclasses import dataclass
+from typing import Dict, Optional, Self
+
+from dataclasses_json import dataclass_json, Undefined
+from ruamel.yaml.comments import CommentedMap
+
+from .job import Job
+
+
+@dataclass_json(undefined=Undefined.EXCLUDE)
+@dataclass
+class Workflow:
+    """Represents an entire workflow in a GitHub Action workflow.
+
+    This object contains all of the data that is required to run the current linting
+    Rules against. If a new Rule requires a key that is missing, the attribute should
+    be added to this class to make it available for use in linting.
+
+    See src/models/job.py for an example if the key in the workflow data does not map
+    one-to-one in the model (ex. 'with' => 'uses_with')
+    """
+
+    key: str = ""
+    name: Optional[str] = None
+    on: Optional[CommentedMap] = None
+    jobs: Optional[Dict[str, Job]] = None
+
+    @classmethod
+    def init(cls: Self, key: str, data: CommentedMap) -> Self:
+        init_data = {
+            "key": key,
+            "name": data["name"] if "name" in data else None,
+            "on": data["on"] if "on" in data else None,
+        }
+
+        new_workflow = cls.from_dict(init_data)
+
+        new_workflow.jobs = {
+            str(job_key): Job.init(job_key, job)
+            for job_key, job in data["jobs"].items()
+        }
+
+        return new_workflow

bitwarden_workflow_linter/rule.py

@@ -0,0 +1,101 @@
+"""Base Rule class to build rules by extending."""
+
+from typing import List, Optional, Tuple, Union
+
+from .models.workflow import Workflow
+from .models.job import Job
+from .models.step import Step
+from .utils import LintFinding, LintLevels, Settings
+
+
+class RuleExecutionException(Exception):
+    """Exception for the Base Rule class."""
+
+    pass
+
+
+class Rule:
+    """Base class of a Rule to extend to create a linting Rule."""
+
+    on_fail: LintLevels = LintLevels.ERROR
+    compatibility: List[Union[Workflow, Job, Step]] = [Workflow, Job, Step]
+    settings: Optional[Settings] = None
+
+    def fn(self, obj: Union[Workflow, Job, Step]) -> Tuple[bool, str]:
+        """Execute the Rule (this should be overridden in the extending class.
+
+        Args:
+          obj:
+            The object that the Rule is to be run against
+
+        Returns:
+          The success/failure of the result of the Rule ran on the input.
+        """
+        return False, f"{obj.name}: <default fail message>"
+
+    def build_lint_message(self, message: str, obj: Union[Workflow, Job, Step]) -> str:
+        """Build the lint failure message.
+
+        Build the lint failure message depending on the type of object that the
+        Rule is being run against.
+
+        Args:
+          message:
+            The message body of the failure
+          obj:
+            The object the Rule is being run against
+
+        Returns:
+          The type specific failure message
+        """
+        obj_type = type(obj)
+
+        if obj_type == Step:
+            return f"{obj_type.__name__} [{obj.job}.{obj.key}] => {message}"
+        elif obj_type == Job:
+            return f"{obj_type.__name__} [{obj.key}] => {message}"
+        else:
+            return f"{obj_type.__name__} => {message}"
+
+    def execute(self, obj: Union[Workflow, Job, Step]) -> Union[LintFinding, None]:
+        """Wrapper function to execute the overridden self.fn().
+
+        Run the Rule against the object and return the results. The result
+        could be an Exception message where the Rule cannot be run against
+        the object for whatever reason. If an exception doesn't occur, the
+        result is linting success or failure.
+
+        Args:
+          obj:
+            The object the Rule is being run against
+
+        Returns:
+          A LintFinding object that contains the message to print to the user
+          and a LintLevel that contains the level of error to calculate the
+          exit code with.
+        """
+        message = None
+
+        if type(obj) not in self.compatibility:
+            return LintFinding(
+                self.build_lint_message(
+                    f"{type(obj).__name__} not compatible with {type(self).__name__}",
+                    obj,
+                ),
+                LintLevels.ERROR,
+            )
+
+        try:
+            passed, message = self.fn(obj)
+
+            if passed:
+                return None
+        except RuleExecutionException as err:
+            return LintFinding(
+                self.build_lint_message(
+                    f"failed to apply {type(self).__name__}\n{err}", obj
+                ),
+                LintLevels.ERROR,
+            )
+
+        return LintFinding(self.build_lint_message(message, obj), self.on_fail)

bitwarden_workflow_linter/rules/job_environment_prefix.py

@@ -0,0 +1,72 @@
+"""A Rule to enforce prefixes environment variables."""
+
+from typing import Optional, Tuple
+
+from ..models.job import Job
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleJobEnvironmentPrefix(Rule):
+    """Rule to enforce specific prefixes for environment variables.
+
+    Automated testing is not easily written for GitHub Action Workflows. CI can also
+    get complicated really quickly and take up hundreds of lines. All of this can
+    make it very difficult to debug and troubleshoot, especially when environment
+    variables can be set in four different places: Workflow level, Job level, Step
+    level, and inside a shell Step.
+
+    To alleviate some of the pain, we have decided that all Job level environment
+    variables should be prefixed with an underscore. All Workflow environment
+    variables are normally at the top of the file and Step level ones are pretty
+    visible when debugging a shell Step.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """RuleJobEnvironmentPrefix constructor to override the Rule class.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.message = "Job environment vars should start with an underscore:"
+        self.on_fail = LintLevels.ERROR
+        self.compatibility = [Job]
+        self.settings = settings
+
+    def fn(self, obj: Job) -> Tuple[bool, str]:
+        """Enforces the underscore prefix standard on job envs.
+
+        Example:
+        ---
+        on:
+          workflow_dispatch:
+
+        jobs:
+          job-key:
+            runs-on: ubuntu-22.04
+            env:
+                _TEST_ENV: "test"
+            steps:
+              - run: echo test
+
+        All keys under jobs.job-key.env should be prefixed with an underscore
+        as in _TEST_ENV.
+
+        See tests/rules/test_job_environment_prefix.py for examples of
+        incorrectly named environment variables.
+        """
+        correct = True
+
+        if obj.env:
+            offending_keys = []
+            for key in obj.env.keys():
+                if key[0] != "_":
+                    offending_keys.append(key)
+                    correct = False
+
+        if correct:
+            return True, ""
+
+        return False, f"{self.message} ({' ,'.join(offending_keys)})"