bitwarden_workflow_linter 0.5.6__tar.gz → 0.5.7__tar.gz

{bitwarden_workflow_linter-0.5.6 → bitwarden_workflow_linter-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitwarden_workflow_linter
-Version: 0.5.6
+Version: 0.5.7
 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

{bitwarden_workflow_linter-0.5.6 → bitwarden_workflow_linter-0.5.7}/settings.yaml

@@ -7,5 +7,6 @@ enabled_rules:
   - bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
   - bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
   - bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+  - bitwarden_workflow_linter.rules.check_pr_target.RuleCheckPrTarget
 
 approved_actions_path: default_actions.json

{bitwarden_workflow_linter-0.5.6 → bitwarden_workflow_linter-0.5.7}/src/bitwarden_workflow_linter/__about__.py

@@ -1,3 +1,3 @@
 """Metadata for Workflow Linter."""
 
-__version__ = "0.5.6"
+__version__ = "0.5.7"

{bitwarden_workflow_linter-0.5.6 → bitwarden_workflow_linter-0.5.7}/src/bitwarden_workflow_linter/default_settings.yaml

@@ -7,5 +7,6 @@ enabled_rules:
   - bitwarden_workflow_linter.rules.step_pinned.RuleStepUsesPinned
   - bitwarden_workflow_linter.rules.underscore_outputs.RuleUnderscoreOutputs
   - bitwarden_workflow_linter.rules.run_actionlint.RunActionlint
+  - bitwarden_workflow_linter.rules.check_pr_target.RuleCheckPrTarget
 
 approved_actions_path: default_actions.json

{bitwarden_workflow_linter-0.5.6 → bitwarden_workflow_linter-0.5.7}/src/bitwarden_workflow_linter/models/job.py

@@ -23,6 +23,7 @@ class Job:
     key: Optional[str] = None
     name: Optional[str] = None
     env: Optional[CommentedMap] = None
+    needs: Optional[List[str]] = None
     steps: Optional[List[Step]] = None
     uses: Optional[str] = None
     uses_path: Optional[str] = None
@@ -32,6 +33,13 @@ class Job:
     )
     outputs: Optional[CommentedMap] = None
 
+    @classmethod
+    def parse_needs(cls: Self, value):
+        """Parser to make all needs values lists that can be searched by linter."""
+        if isinstance(value, str):
+            return [value]
+        return value
+
     @classmethod
     def init(cls: Self, key: str, data: CommentedMap) -> Self:
         """Custom dataclass constructor to map job data to a Job."""
@@ -40,6 +48,7 @@ class Job:
             "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,
+            "needs": Job.parse_needs(data["needs"]) if "needs" in data else None,
             "outputs": data["outputs"] if "outputs" in data else None,
         }
 

bitwarden_workflow_linter-0.5.7/src/bitwarden_workflow_linter/rules/check_pr_target.py

@@ -0,0 +1,81 @@
+"""A Rule to enforce check-run is run when workflow uses pull_request_target."""
+
+from typing import Optional, Tuple
+
+from ..models.workflow import Workflow
+from ..rule import Rule
+from ..utils import LintLevels, Settings
+
+
+class RuleCheckPrTarget(Rule):
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        """
+        To ensure pull_request_target is safe to use, the check-run step is added 
+        to all jobs as a dependency.
+
+        Once a branch is pushed to Github, it already opens up a vulnerability 
+        even if the check-run scan fails to detect this. 
+        
+        In order to prevent a vulnerable branch from being used for an attack 
+        prior to being caught through vetting, all pull_request_target workflows 
+        should only be run by users with appropriate permissions.  
+
+        This greatly reduces the risk as community contributors can't use a fork to run a compromised workflow that uses pull_request_target.
+        """
+        self.message = "A check-run job must be included as a direct job dependency when pull_request_target is used and the workflow may only apply to runs on the main branch"
+        self.on_fail = LintLevels.WARNING
+        self.compatibility = [Workflow]
+        self.settings = settings
+    
+    def targets_main_branch(self, obj:Workflow) -> bool:
+        if obj.on["pull_request_target"].get("branches"):
+            branches_list = obj.on["pull_request_target"].get("branches")
+            if isinstance(branches_list, str):
+                branches_list = [branches_list]
+            if any(branch != 'main' for branch in branches_list):
+                return False
+        else:
+            return False
+        return True
+
+    def has_check_run(self, obj: Workflow) -> Tuple[bool, str]:
+        for name, job in obj.jobs.items():
+            if job.uses == "bitwarden/gh-actions/.github/workflows/check-run.yml@main":
+                return True, name
+        return False, ""
+    
+    def check_run_required(self, obj:Workflow, check_job:str) -> list:
+        missing_jobs = []
+        for job in list(obj.jobs.keys()):
+            if job is not check_job:
+                job_list = obj.jobs[job].needs
+                if job_list:
+                    if check_job not in job_list:
+                        missing_jobs.append(job)
+                else:
+                    missing_jobs.append(job)
+        return missing_jobs
+
+    def fn(self, obj: Workflow) -> Tuple[bool, str]:
+        Errors = []
+        if obj.on.get("pull_request_target"):
+            result, check_job = self.has_check_run(obj)
+            main_branch_only = self.targets_main_branch(obj)
+            if not main_branch_only:
+                Errors.append("Workflows using pull_request_target can only target the main branch")
+            if result:
+                missing_jobs = self.check_run_required(obj, check_job)
+                if missing_jobs:
+                    job_list = ', '.join(missing_jobs)
+                    message = f"Check-run is missing from the following jobs in the workflow: {job_list}"
+                    Errors.append(message)
+            else:
+                message = f"A check-run job must be included as a direct job dependency when pull_request_target is used"
+                Errors.append(message)
+            if Errors:
+                self.message = "\n".join(Errors)
+                return False, f"{self.message}"
+            else:
+                return True, ""
+        else:
+            return True, ""

bitwarden_workflow_linter-0.5.7/tests/rules/test_check_pr_target.py

@@ -0,0 +1,276 @@
+"""Test src/bitwarden_workflow_linter/rules/check_pr_target."""
+
+import pytest
+
+from ruamel.yaml import YAML
+
+from src.bitwarden_workflow_linter.load import WorkflowBuilder
+from src.bitwarden_workflow_linter.rules.check_pr_target import (
+    RuleCheckPrTarget,
+)
+
+yaml = YAML()
+message = "A check-run job must be included as a direct job dependency when pull_request_target is used and the workflow may only apply to runs on the main branch"
+
+@pytest.fixture(name="correct_workflow")
+def fixture_correct_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+    branches:
+      - 'main'
+
+jobs:
+  check-run:
+    name: Check PR run
+    uses: bitwarden/gh-actions/.github/workflows/check-run.yml@main
+  
+  quality:
+    name: Quality scan
+    needs: check-run
+    steps:
+      - run: echo test
+ 
+  dependent-job:
+     name: Another Dependent Job
+     needs:
+       - quality
+       - check-run
+     steps:
+       - run: echo another dependent job
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="no_check_workflow")
+def fixture_no_check_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+    branches:
+      - 'main'
+
+jobs:
+  job-key:
+    runs-on: ubuntu-22.04
+    steps:
+      - run: echo test
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="no_needs_workflow")
+def fixture_no_needs_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+    branches: main
+
+jobs:
+  check-run:
+    name: Check PR run
+    uses: bitwarden/gh-actions/.github/workflows/check-run.yml@main
+
+  job-key:
+    runs-on: ubuntu-22.04
+    steps:
+      - run: echo test
+  
+  quality:
+    name: Quality scan
+    steps:
+      - run: echo test
+
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="no_target_workflow")
+def fixture_no_target_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+
+jobs:
+  job-key:
+    runs-on: ubuntu-22.04
+    steps:
+      - run: echo test
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="dependent_missing_check_workflow")
+def dependent_missing_check_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+    branches:
+      - 'main'
+
+jobs:
+  check-run:
+    name: Check PR run
+    uses: bitwarden/gh-actions/.github/workflows/check-run.yml@main
+  
+  quality:
+    name: Quality scan
+    needs: check-run
+    steps:
+      - run: echo test
+ 
+  dependent-job:
+     name: Another Dependent Job
+     needs:
+       - quality
+     steps:
+       - run: echo another dependent job
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="no_branches_workflow")
+def fixture_no_branches_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+
+jobs:
+  check-run:
+    name: Check PR run
+    uses: bitwarden/gh-actions/.github/workflows/check-run.yml@main
+  
+  quality:
+    name: Quality scan
+    needs: check-run
+    steps:
+      - run: echo test
+ 
+  dependent-job:
+     name: Another Dependent Job
+     needs:
+       - quality
+       - check-run
+     steps:
+       - run: echo another dependent job
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="bad_branches_workflow")
+def fixture_bad_branches_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+    branches:
+      - 'main'
+      - 'not main'
+
+jobs:
+  check-run:
+    name: Check PR run
+    uses: bitwarden/gh-actions/.github/workflows/check-run.yml@main
+  
+  quality:
+    name: Quality scan
+    needs: check-run
+    steps:
+      - run: echo test
+ 
+  dependent-job:
+     name: Another Dependent Job
+     needs:
+       - quality
+       - check-run
+     steps:
+       - run: echo another dependent job
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="two_failures_workflow")
+def fixture_two_failures_workflow():
+    workflow = """\
+---
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize]
+
+jobs:
+  check-run:
+    name: Check PR run
+    uses: bitwarden/some-other-repo/.github/workflows/check-run.yml@main
+  
+  quality:
+    name: Quality scan
+    needs: check-run
+    steps:
+      - run: echo test
+ 
+  dependent-job:
+     name: Another Dependent Job
+     needs:
+       - quality
+       - check-run
+     steps:
+       - run: echo another dependent job
+"""
+    return WorkflowBuilder.build(workflow=yaml.load(workflow), from_file=False)
+
+@pytest.fixture(name="rule")
+def fixture_rule():
+    return RuleCheckPrTarget()
+
+def test_rule_on_correct_workflow(rule, correct_workflow):
+    result, message = rule.fn(correct_workflow)
+    assert result is True
+    assert message == ""
+
+
+def test_rule_on_no_checkworkflow(rule, no_check_workflow):
+    result, message = rule.fn(no_check_workflow)
+    assert result is False
+    assert message == message
+
+def test_rule_on_no_target_workflow(rule, no_target_workflow):
+    result, message = rule.fn(no_target_workflow)
+    assert result is True
+    assert message == ""
+
+def test_rule_on_jobs_without_needs(rule, no_needs_workflow):
+    result, message = rule.fn(no_needs_workflow)
+    assert result is False
+    assert message == message, "check-run is missing from the following jobs in the workflow: quality"
+
+def test_rule_on_dependencies_without_check(rule, dependent_missing_check_workflow):
+    result, message = rule.fn(dependent_missing_check_workflow)
+    assert result is False
+    assert message == message, "check-run is missing from the following jobs in the workflow: dependent-job"
+
+def test_rule_on_no_branches_workflow(rule, no_branches_workflow):
+    result, message = rule.fn(no_branches_workflow)
+    assert result is False
+    assert message == "Workflows using pull_request_target can only target the main branch"
+
+def test_rule_on_only_target_main(rule, bad_branches_workflow):
+    result, message = rule.fn(bad_branches_workflow)
+    assert result is False
+    assert message == "Workflows using pull_request_target can only target the main branch"
+
+def test_rule_on_two_failures(rule, two_failures_workflow):
+    result, message = rule.fn(two_failures_workflow)
+    assert result is False
+    assert message == "Workflows using pull_request_target can only target the main branch\nA check-run job must be included as a direct job dependency when pull_request_target is used"