bitwarden_workflow_linter 0.8.1__tar.gz → 0.9.0__tar.gz

{bitwarden_workflow_linter-0.8.1 → bitwarden_workflow_linter-0.9.0}/.github/workflows/ci.yml

@@ -7,6 +7,8 @@ on:
       - "tests/**"
   workflow_dispatch:
 
+permissions: read-all
+
 jobs:
   test:
     name: CI workflow-linter (v2)
@@ -31,3 +33,15 @@ jobs:
 
       - name: Check type hinting
         run: pipenv run pytype src
+
+      - name: Test against example workflows
+        # run notes:
+        # - Changing directories will help catch any repo specific paths in the linter
+        #   that would not work in a different repository
+        # - Changing directories utilizes the default_settings.yaml rather than this repos
+        #   settings.yaml, which better simulates running from another repository
+        # - Using strict to ensure that our examples pass all checks including warnings
+        run: |
+          pipenv run pip install -e .
+          cd .github/workflows
+          pipenv run bwwl lint --strict -f ./examples

{bitwarden_workflow_linter-0.8.1 → bitwarden_workflow_linter-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitwarden_workflow_linter
-Version: 0.8.1
+Version: 0.9.0
 Summary: Custom GitHub Action Workflow Linter
 Project-URL: Homepage, https://github.com/bitwarden/workflow-linter
 Project-URL: Issues, https://github.com/bitwarden/workflow-linter/issues
@@ -60,20 +60,20 @@ the below and create a `settings.yaml` in the directory that `bwwl` will be runn
 
 ```yaml
 enabled_rules:
-  - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
-    level: error
-  - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
-    level: error
-  - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
-    level: error
-  - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
-    level: warning
-  - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
-    level: warning
+    - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+      level: error
+    - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+      level: error
+    - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+      level: error
+    - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
+      level: warning
+    - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+      level: warning
 
 approved_actions_path: default_actions.json
 ```
@@ -187,7 +187,10 @@ By default, a new Rule needs five things:
 not support Rules that check against multiple objects at a time OR file level formatting (one empty between each step or
 two empty lines between each job)
 
-To activate a rule after implementing it, add it to `settings.yaml` in the project's base folder
+_IMPORTANT: A rule must be implemented and tested then merged into `main` before it can be activated.<br>_
+This is because the released version of bwwl will use the current `settings.yaml` file, but it will not have the new rule functionality yet and cause an error in the workflow linting of this repository.
+
+To activate a rule after implementing and releasing it, add it to `settings.yaml` in the project's base folder
 and `src/bitwarden_workflow_linter/default_settings.yaml` to make the rule default
 
 Before creating a new rule please read the [Workflow linter rule rollout process](./RULE_ROLLOUT.md) document in which you'll find the process for rolling out new workflow linter rules.

{bitwarden_workflow_linter-0.8.1 → bitwarden_workflow_linter-0.9.0}/README.md

@@ -34,20 +34,20 @@ the below and create a `settings.yaml` in the directory that `bwwl` will be runn
 
 ```yaml
 enabled_rules:
-  - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
-    level: error
-  - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
-    level: error
-  - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
-    level: error
-  - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
-    level: warning
-  - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
-    level: warning
+    - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+      level: error
+    - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+      level: error
+    - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+      level: error
+    - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
+      level: warning
+    - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+      level: warning
 
 approved_actions_path: default_actions.json
 ```
@@ -161,7 +161,10 @@ By default, a new Rule needs five things:
 not support Rules that check against multiple objects at a time OR file level formatting (one empty between each step or
 two empty lines between each job)
 
-To activate a rule after implementing it, add it to `settings.yaml` in the project's base folder
+_IMPORTANT: A rule must be implemented and tested then merged into `main` before it can be activated.<br>_
+This is because the released version of bwwl will use the current `settings.yaml` file, but it will not have the new rule functionality yet and cause an error in the workflow linting of this repository.
+
+To activate a rule after implementing and releasing it, add it to `settings.yaml` in the project's base folder
 and `src/bitwarden_workflow_linter/default_settings.yaml` to make the rule default
 
 Before creating a new rule please read the [Workflow linter rule rollout process](./RULE_ROLLOUT.md) document in which you'll find the process for rolling out new workflow linter rules.

bitwarden_workflow_linter-0.9.0/settings.yaml

@@ -0,0 +1,24 @@
+enabled_rules:
+    - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+      level: error
+    - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+      level: error
+    - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+      level: error
+    #   - id: bitwarden_workflow_linter.rules.step_approved.RuleStepUsesApproved
+    #     level: error
+    - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
+      level: warning
+    - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+      level: warning
+    - id: bitwarden_workflow_linter.rules.check_pr_target.RuleCheckPrTarget
+      level: warning
+    # Cannot add this in until the rule functionality is merged through to main
+    # - id: bitwarden_workflow_linter.rules.permissions_exist.RulePermissionsExist
+    #   level: warning
+
+approved_actions_path: default_actions.json

{bitwarden_workflow_linter-0.8.1 → bitwarden_workflow_linter-0.9.0}/src/bitwarden_workflow_linter/__about__.py

@@ -1,3 +1,3 @@
 """Metadata for Workflow Linter."""
 
-__version__ = "0.8.1"
+__version__ = "0.9.0"

bitwarden_workflow_linter-0.9.0/src/bitwarden_workflow_linter/default_settings.yaml

@@ -0,0 +1,24 @@
+enabled_rules:
+    - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
+      level: error
+    - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
+      level: error
+    - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
+      level: error
+    #   - id: bitwarden_workflow_linter.rules.step_approved.RuleStepUsesApproved
+    #     level: error
+    - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
+      level: error
+    - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
+      level: warning
+    - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+      level: warning
+    - id: bitwarden_workflow_linter.rules.check_pr_target.RuleCheckPrTarget
+      level: warning
+    # Cannot add this in until the rule functionality is merged through to main
+    # - id: bitwarden_workflow_linter.rules.permissions_exist.RulePermissionsExist
+    #   level: warning
+
+approved_actions_path: default_actions.json

{bitwarden_workflow_linter-0.8.1 → bitwarden_workflow_linter-0.9.0}/src/bitwarden_workflow_linter/lint.py

@@ -4,7 +4,6 @@ Workflows."""
 import argparse
 import os
 
-from functools import reduce
 from typing import Optional
 
 from .load import WorkflowBuilder, Rules
@@ -115,6 +114,7 @@ class LinterCmd:
         if len(findings) > 0:
             for finding in findings:
                 print(f" - {finding}")
+            print(f"Issues found by {len(findings)} rules in {filename}")
             print()
 
         max_error_level = self.get_max_error_level(findings)
@@ -162,9 +162,28 @@ class LinterCmd:
         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)
-            )
+            files_with_issues = []
+            return_code = 0
+            for file in files:
+                return_value = self.lint_file(file)
+                if return_value > 0:
+                    files_with_issues.append(file)
+                    return_code = max(return_code, return_value)
+
+            if len(files_with_issues) > 0:
+                newline = "\n"  # For compatibility with Python 3.11
+                print(
+                    f"""Found {len(files_with_issues)} file(s) with issues:
+  {f"{newline}  ".join(files_with_issues)}
+
+For help, refer to
+  - Workflow Syntax: \
+https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+  - Bitwarden Examples: \
+https://github.com/bitwarden/workflow-linter/tree/main/.github/workflows/examples")"""
+                )
+            else:
+                print("No issues found")
 
             if return_code == 1 and not strict:
                 return_code = 0

{bitwarden_workflow_linter-0.8.1 → bitwarden_workflow_linter-0.9.0}/src/bitwarden_workflow_linter/models/workflow.py

@@ -27,6 +27,7 @@ class Workflow:
     name: Optional[str] = None
     on: Optional[CommentedMap] = None
     jobs: Optional[Dict[str, Job]] = None
+    permissions: Optional[object] = None  # This can be a CommentedMap or a string
 
     @classmethod
     def init(cls: Self, key: str, filename: str, data: CommentedMap) -> Self:
@@ -35,6 +36,7 @@ class Workflow:
             "filename": filename,
             "name": data["name"] if "name" in data else None,
             "on": data["on"] if "on" in data else None,
+            "permissions": data["permissions"] if "permissions" in data else None,
         }
 
         new_workflow = cls.from_dict(init_data)

bitwarden_workflow_linter-0.9.0/src/bitwarden_workflow_linter/rules/permissions_exist.py

@@ -0,0 +1,43 @@
+"""A Rule to enforce that the required permissions are specified on every workflow"""
+
+from typing import Optional, Tuple
+
+from ..models.workflow import Workflow
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RulePermissionsExist(Rule):
+    """
+    Rule to enforce that the required permissions are specified on every workflow.
+
+    To allow for keeping repository default GITHUB_TOKEN permissions to a minimum,
+    each workflow must specify the permissions block (including read).
+
+    This has 2 benefits:
+    1) When changing the default repository setting to a more restrictive one,
+       the workflows will not be affected.
+    2) It is clear to the user what permissions are required for the workflow to run.
+    """
+
+    def __init__(
+        self,
+        settings: Optional[Settings] = None,
+        lint_level: Optional[LintLevels] = LintLevels.NONE,
+    ) -> None:
+        self.message = (
+            "A top-level permissions section must be configured in the workflow."
+        )
+        self.on_fail = lint_level
+        self.compatibility = [Workflow]
+        self.settings = settings
+
+    def permissions_exist(self, obj: Workflow) -> bool:
+        if obj.permissions is None:
+            return False
+        return True
+
+    def fn(self, obj: Workflow) -> Tuple[bool, str]:
+        if not self.permissions_exist(obj):
+            return False, f"{self.message}"
+        return True, ""

bitwarden_workflow_linter-0.9.0/tests/rules/test_permissions_exist.py

@@ -0,0 +1,96 @@
+"""Test src/bitwarden_workflow_linter/rules/permissions_exist.py."""
+
+import pytest
+
+from ruamel.yaml import YAML
+
+from src.bitwarden_workflow_linter.load import WorkflowBuilder
+from src.bitwarden_workflow_linter.rules.permissions_exist import RulePermissionsExist
+
+
+yaml = YAML()
+
+
+@pytest.fixture(name="correct_workflow_read_all")
+def fixture_correct_workflow_read_all():
+    workflow = """\
+---
+name: Test Workflow
+
+on:
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  job-key:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Test
+        run: echo test
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+
+@pytest.fixture(name="correct_workflow_scoped_permissions")
+def fixture_correct_workflow_scoped_permissions():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+
+permissions:
+  checks: write
+  contents: read
+  id-token: write
+  pull-requests: write
+
+
+jobs:
+  job-key:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+
+@pytest.fixture(name="incorrect_workflow_missing_permissions")
+def fixture_incorrect_workflow_missing_permissions():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+
+jobs:
+  job-key:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+
+@pytest.fixture(name="rule")
+def fixture_rule():
+    return RulePermissionsExist()
+
+
+def test_rule_on_correct_workflow_read_all(rule, correct_workflow_read_all):
+    result, _ = rule.fn(correct_workflow_read_all)
+    assert result is True
+
+
+def test_rule_on_correct_workflow_scoped_permissions(
+    rule, correct_workflow_scoped_permissions
+):
+    result, _ = rule.fn(correct_workflow_scoped_permissions)
+    assert result is True
+
+
+def test_rule_on_incorrect_workflow_missing_permissions(
+    rule, incorrect_workflow_missing_permissions
+):
+    result, _ = rule.fn(incorrect_workflow_missing_permissions)
+    assert result is False

bitwarden_workflow_linter-0.8.1/.github/workflows/lint-examples.yml

@@ -1,37 +0,0 @@
-name: Lint Example Workflows
-
-on:
-  pull_request:
-    branches:
-      - "main"
-  merge_group:
-    types: [checks_requested]
-  workflow_call:
-  workflow_dispatch:  
-
-jobs:
-  test-lint-workflow:
-    name: Test Lint Workflow
-    runs-on: ubuntu-24.04
-    steps:
-      - name: Checkout Branch
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get workflow list
-        id: workflow-list
-        run: |
-          WORKFLOW_LIST=$(find .github/workflows/examples -maxdepth 1 -type f | xargs -I {} echo -n "{} ")
-          echo "workflow-list=$WORKFLOW_LIST" >> $GITHUB_OUTPUT
-
-      - name: Lint examples
-        id: lint-examples
-        uses: bitwarden/gh-actions/lint-workflow@main
-        with:
-          workflows: ${{ steps.workflow-list.outputs.workflow-list }}
-
-      - name: Failure message
-        if: ${{ failure() && steps.lint-examples.conclusion == 'failure' }}
-        run: |
-          echo "Changes to the workflow linter should include updating workflow \
-          examples in .github/workflows/examples directory"
-          exit 1

bitwarden_workflow_linter-0.8.1/settings.yaml

@@ -1,21 +0,0 @@
-enabled_rules:
-  - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
-    level: error
-  - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
-    level: error
-  - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
-    level: error
-#   - id: bitwarden_workflow_linter.rules.step_approved.RuleStepUsesApproved
-#     level: error
-  - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
-    level: warning
-  - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
-    level: warning
-  - id: bitwarden_workflow_linter.rules.check_pr_target.RuleCheckPrTarget
-    level: warning
-
-approved_actions_path: default_actions.json

bitwarden_workflow_linter-0.8.1/src/bitwarden_workflow_linter/default_settings.yaml

@@ -1,21 +0,0 @@
-enabled_rules:
-  - id: bitwarden_workflow_linter.rules.name_exists.RuleNameExists
-    level: error
-  - id: bitwarden_workflow_linter.rules.name_capitalized.RuleNameCapitalized
-    level: error
-  - id: bitwarden_workflow_linter.rules.pinned_job_runner.RuleJobRunnerVersionPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.job_environment_prefix.RuleJobEnvironmentPrefix
-    level: error
-#   - id: bitwarden_workflow_linter.rules.step_approved.RuleStepUsesApproved
-#     level: error
-  - id: bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
-    level: error
-  - id: bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
-    level: warning
-  - id: bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
-    level: warning
-  - id: bitwarden_workflow_linter.rules.check_pr_target.RuleCheckPrTarget
-    level: warning
-
-approved_actions_path: default_actions.json