bitwarden_workflow_linter 0.0.3__py3-none-any.whl

bitwarden_workflow_linter/rules/name_capitalized.py

@@ -0,0 +1,56 @@
+"""A Rule to enforce all 'name' values start with a capital letter."""
+
+from typing import Optional, Tuple, Union
+
+from ..models.job import Job
+from ..models.step import Step
+from ..models.workflow import Workflow
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleNameCapitalized(Rule):
+    """Rule to enforce all 'name' values start with a capital letter.
+
+    A simple standard to help keep uniformity in naming.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Constructor for RuleNameCapitalized 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 = "name must capitalized"
+        self.on_fail = LintLevels.ERROR
+        self.settings = settings
+
+    def fn(self, obj: Union[Workflow, Job, Step]) -> Tuple[bool, str]:
+        """Enforces capitalization of the first letter of any name key.
+
+        Example:
+        ---
+        name: Test Workflow
+
+        on:
+          workflow_dispatch:
+
+        jobs:
+          job-key:
+            name: Test
+            runs-on: ubuntu-latest
+            steps:
+              - name: Test
+                run: echo test
+
+        'Test Workflow', 'Test', and 'Test' all start with a capital letter.
+
+        See tests/rules/test_name_capitalized.py for examples of incorrectly
+        capitalized names. This Rule DOES NOT enforce that the name exists.
+        It only enforces capitalization IF it does.
+        """
+        if obj.name:
+            return obj.name[0].isupper(), self.message
+        return True, ""  # Force passing if obj.name doesn't exist

bitwarden_workflow_linter/rules/name_exists.py

@@ -0,0 +1,59 @@
+"""A Rule to enforce that a 'name' key exists."""
+
+from typing import Optional, Tuple, Union
+
+from ..models.workflow import Workflow
+from ..models.job import Job
+from ..models.step import Step
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleNameExists(Rule):
+    """Rule to enforce a 'name' key exists for every object in GitHub Actions.
+
+    For pipeline run troubleshooting and debugging, it is helpful to have a
+    name to immediately identify a Workflow, Job, or Step while moving between
+    run and the code.
+
+    It also helps with uniformity of runs.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Constructor for RuleNameCapitalized to override Rule class.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.message = "name must exist"
+        self.on_fail = LintLevels.ERROR
+        self.settings = settings
+
+    def fn(self, obj: Union[Workflow, Job, Step]) -> Tuple[bool, str]:
+        """Enforces the existence of names.
+
+        Example:
+        ---
+        name: Test Workflow
+
+        on:
+          workflow_dispatch:
+
+        jobs:
+          job-key:
+            name: Test
+            runs-on: ubuntu-latest
+            steps:
+              - name: Test
+                run: echo test
+
+        'Test Workflow', 'Test', and 'Test' all exist.
+
+        See tests/rules/test_name_exists.py for examples where a name does not
+        exist.
+        """
+        if obj.name is not None:
+            return True, ""
+        return False, self.message

bitwarden_workflow_linter/rules/pinned_job_runner.py

@@ -0,0 +1,52 @@
+"""A Rule to enforce pinning runners to a specific OS version."""
+
+from typing import Optional, Tuple
+
+from ..models.job import Job
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleJobRunnerVersionPinned(Rule):
+    """Rule to enforce pinned Runner OS versions.
+
+    Using `*-latest` versions will update automatically and has broken all of
+    our workflows in the past. To avoid this and prevent a single event from
+    breaking the majority of our pipelines, we pin the versions.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Constructor for RuleJobRunnerVersionPinned to override Rule class.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.message = "Workflow runner must be pinned"
+        self.on_fail = LintLevels.ERROR
+        self.compatibility = [Job]
+        self.settings = settings
+
+    def fn(self, obj: Job) -> Tuple[bool, str]:
+        """Enforces runners are pinned to a version
+
+        Example:
+        ---
+        on:
+          workflow_dispatch:
+
+        jobs:
+          job-key:
+            runs-on: ubuntu-22.04
+            steps:
+              - run: echo test
+
+        call-workflow:
+          uses: bitwarden/server/.github/workflows/workflow-linter.yml@master
+
+        'runs-on' is pinned to '22.04' instead of 'latest'
+        """
+        if obj.runs_on is not None and "latest" in obj.runs_on:
+            return False, self.message
+        return True, ""

bitwarden_workflow_linter/rules/step_approved.py

@@ -0,0 +1,101 @@
+"""A Rule to enforce the use of a list of pre-approved Actions."""
+
+from typing import Optional, Tuple
+
+from ..models.step import Step
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleStepUsesApproved(Rule):
+    """Rule to enforce that all Actions have been pre-approved.
+
+    To limit the surface area of a supply chain attack in our pipelines, all Actions
+    are required to pass a security review and be added to the pre-approved list to
+    check against.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Constructor for RuleStepUsesApproved to override Rule class.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.on_fail = LintLevels.WARNING
+        self.compatibility = [Step]
+        self.settings = settings
+
+    def skip(self, obj: Step) -> bool:
+        """Skip this Rule on some Steps.
+
+        This Rule does not apply to a few types of Steps. These
+        Rules are skipped.
+        """
+        ## Force pass for any shell steps
+        if not obj.uses:
+            return True
+
+        ## Force pass for any local actions
+        if "@" not in obj.uses:
+            return True
+
+        ## Force pass for any bitwarden/gh-actions
+        if obj.uses.startswith("bitwarden/gh-actions"):
+            return True
+
+        return False
+
+    def fn(self, obj: Step) -> Tuple[bool, str]:
+        """Enforces all externally used Actions are on the pre-approved list.
+
+        The pre-approved list allows tight auditing on what Actions are trusted
+        and allowed to be run in our environments. This helps mitigate risks
+        against supply chain attacks in our pipelines.
+
+        Example:
+        ---
+        on:
+          workflow_dispatch:
+
+        jobs:
+          job-key:
+            runs-on: ubuntu-22.04
+            steps:
+              - name: Checkout Branch
+                uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+              - name: Test Bitwarden Action
+                uses: bitwarden/gh-actions/get-keyvault-secrets@main
+
+              - name: Test Local Action
+                uses: ./actions/test-action
+
+              - name: Test Run Action
+                run: echo "test"
+
+        In this example, 'actions/checkout' must be on the pre-approved list
+        and the metadata must match in order to succeed. The other three
+        Steps will be skipped.
+        """
+        if self.skip(obj):
+            return True, ""
+
+        # Actions in bitwarden/gh-actions are auto-approved
+        if obj.uses and not obj.uses_path in self.settings.approved_actions:
+            return False, (
+                f"New Action detected: {obj.uses_path}\nFor security purposes, "
+                "actions must be reviewed and be on the pre-approved list"
+            )
+
+        action = self.settings.approved_actions[obj.uses_path]
+
+        if obj.uses_version != action.version or obj.uses_ref != action.sha:
+            return False, (
+                "Action is out of date. Please update to:\n"
+                f"  commit: {action.version}"
+                f"  version: {action.sha}"
+            )
+
+        return True, ""

bitwarden_workflow_linter/rules/step_pinned.py

@@ -0,0 +1,98 @@
+"""A Rule to enforce Actions are pinned correctly."""
+
+from typing import Optional, Tuple
+
+from ..models.step import Step
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleStepUsesPinned(Rule):
+    """Rule to contain the enforcement logic for pinning Actions versions.
+
+    Definition of Internal Action:
+      An Action that exists in the `bitwarden/gh-actions` GitHub Repository.
+
+    For any external Action (any Action that does not fit the above definition of
+    an Internal Action), to mitigate the risks of supply chain attacks in our CI
+    pipelines, we pin any use of an Action to a specific hash that has been verified
+    and pre-approved after a security audit of the version of the Action.
+
+    All Internal Actions, should be pinned to 'main'. This prevents Renovate from
+    spamming a bunch of PRs across all of our repos when `bitwarden/gh-actions` is
+    updated.
+    """
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """Constructor for RuleStepUsesPinned to override base Rule.
+
+        Args:
+          settings:
+            A Settings object that contains any default, overridden, or custom settings
+            required anywhere in the application.
+        """
+        self.on_fail = LintLevels.ERROR
+        self.compatibility = [Step]
+        self.settings = settings
+
+    def skip(self, obj: Step) -> bool:
+        """Skip this Rule on some Steps.
+
+        This Rule does not apply to a few types of Steps. These
+        Rules are skipped.
+        """
+        if not obj.uses:
+            return True
+
+        ## Force pass for any local actions
+        if "@" not in obj.uses:
+            return True
+
+        return False
+
+    def fn(self, obj: Step) -> Tuple[bool, str]:
+        """Enforces all Actions to be pinned in a specific way.
+
+        Pinning external Action hashes prevents unknown updates that could
+        break the pipelines or be the entry point to a supply chain attack.
+
+        Pinning internal Actions to branches allow for less updates as work
+        is done on those repos. This is mainly to support our Action
+        monorepo architecture of our Actions.
+
+        Example:
+        - name: Checkout Branch
+          uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+        - name: Test Bitwarden Action
+          uses: bitwarden/gh-actions/get-keyvault-secrets@main
+
+        - name: Test Local Action
+          uses: ./actions/test-action
+
+        - name: Test Run Action
+          run: echo "test"
+
+        In this example, 'actions/checkout' must be pinned to the full commit
+        of the tag while 'bitwarden/gh-actions/get-keyvault-secrets' must be
+        pinned to 'main'. The other two Steps will be skipped.
+        """
+        if self.skip(obj):
+            return True, ""
+
+        path, ref = obj.uses.split("@")
+
+        if path.startswith("bitwarden/gh-actions"):
+            if ref == "main":
+                return True, ""
+            return False, "Please pin to main"
+
+        try:
+            int(ref, 16)
+        except ValueError:
+            return False, "Please pin the action to a commit sha"
+
+        if len(ref) != 40:
+            return False, "Please use the full commit sha to pin the action"
+
+        return True, ""

bitwarden_workflow_linter/utils.py

@@ -0,0 +1,179 @@
+"""Module of a collection of random utilities."""
+
+import importlib.resources
+import json
+import os
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, Self, TypeVar
+
+from ruamel.yaml import YAML
+
+
+yaml = YAML()
+
+
+@dataclass
+class Colors:
+    """Class containing color codes for printing strings to output."""
+
+    black = "30m"
+    red = "31m"
+    green = "32m"
+    yellow = "33m"
+    blue = "34m"
+    magenta = "35m"
+    cyan = "36m"
+    white = "37m"
+
+
+@dataclass
+class LintLevel:
+    """Class to contain the numeric level and color of linting."""
+
+    code: int
+    color: Colors
+
+
+class LintLevels(LintLevel, Enum):
+    """Collection of the different types of LintLevels available."""
+
+    NONE = 0, Colors.white
+    WARNING = 1, Colors.yellow
+    ERROR = 2, Colors.red
+
+
+class LintFinding:
+    """Represents a problem detected by linting."""
+
+    def __init__(self, description: str, level: LintLevels) -> None:
+        self.description = description
+        self.level = level
+
+    def __str__(self) -> str:
+        """String representation of the class.
+
+        Returns:
+        String representation of itself.
+        """
+        return (
+            f"\033[{self.level.color}{self.level.name.lower()}\033[0m "
+            f"{self.description}"
+        )
+
+
+@dataclass
+class Action:
+    """Collection of the metadata associated with a GitHub Action."""
+
+    name: str
+    version: str = ""
+    sha: str = ""
+
+    def __eq__(self, other: Self) -> bool:
+        """Override Action equality.
+
+        Args:
+          other:
+            Another Action type object to compare
+
+        Return
+          The state of equality
+        """
+        return (
+            self.name == other.name
+            and self.version == other.version
+            and self.sha == other.sha
+        )
+
+    def __ne__(self, other: Self) -> bool:
+        """Override Action unequality.
+
+        Args:
+          other:
+            Another Action type object to compare
+
+        Return
+          The negation of the state of equality
+        """
+        return not self.__eq__(other)
+
+
+class SettingsError(Exception):
+    """Custom Exception to indicate an error with loading Settings."""
+
+    pass
+
+
+SettingsFromFactory = TypeVar("SettingsFromFactory", bound="Settings")
+
+
+class Settings:
+    """Class that contains configuration-as-code for any portion of the app."""
+
+    enabled_rules: list[str]
+    approved_actions: dict[str, Action]
+
+    def __init__(
+        self,
+        enabled_rules: Optional[list[str]] = None,
+        approved_actions: Optional[dict[str, dict[str, str]]] = None,
+    ) -> None:
+        """Settings object that can be overridden in settings.py.
+
+        Args:
+          enabled_rules:
+            All of the python modules that implement a Rule to be run against
+            the workflows. These must be available somewhere on the PYTHONPATH
+          approved_actions:
+            The colleciton of GitHub Actions that are pre-approved to be used
+            in any workflow (Required by src.rules.step_approved)
+        """
+        if enabled_rules is None:
+            enabled_rules = []
+
+        if approved_actions is None:
+            approved_actions = {}
+
+        self.enabled_rules = enabled_rules
+        self.approved_actions = {
+            name: Action(**action) for name, action in approved_actions.items()
+        }
+
+    @staticmethod
+    def factory() -> SettingsFromFactory:
+        with (
+            importlib.resources.files("bitwarden_workflow_linter")
+            .joinpath("default_settings.yaml")
+            .open("r", encoding="utf-8") as file
+        ):
+            settings = yaml.load(file)
+
+        settings_filename = "settings.yaml"
+        local_settings = None
+
+        if os.path.exists(settings_filename):
+            with open(settings_filename, encoding="utf8") as settings_file:
+                local_settings = yaml.load(settings_file)
+
+        if local_settings:
+            settings.update(local_settings)
+
+        if settings["approved_actions_path"] == "default_actions.json":
+            with (
+                importlib.resources.files("bitwarden_workflow_linter")
+                .joinpath("default_actions.json")
+                .open("r", encoding="utf-8") as file
+            ):
+                settings["approved_actions"] = json.load(file)
+        else:
+            with open(
+                settings["approved_actions_path"], "r", encoding="utf8"
+            ) as action_file:
+                settings["approved_actions"] = json.load(action_file)
+
+        return Settings(
+            enabled_rules=settings["enabled_rules"],
+            approved_actions=settings["approved_actions"],
+        )