flowsec 0.1.0__py3-none-any.whl

pipelineguard/rules/dependency_pinning.py

@@ -0,0 +1,72 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+PACKAGE_MANAGERS = ["pip install", "pip3 install", "npm install", "yarn add", "npm i"]
+
+
+class DependencyPinningRule(BaseRule):
+    rule_id = "FS009"
+    title = "Unpinned Dependency — Package Installed Without Version Lock"
+    severity = Severity.HIGH
+
+    def _is_pinned(self, command: str) -> bool:
+        for manager in PACKAGE_MANAGERS:
+            if manager in command:
+                parts = command.split(manager, 1)
+                if len(parts) < 2:
+                    return False
+                packages = parts[1].strip().split()
+                for pkg in packages:
+                    if pkg.startswith("-"):
+                        continue
+                    if "==" not in pkg and "@" not in pkg:
+                        return False
+        return True
+
+    def _check_commands(self, commands: list[str], file_path: str) -> list[Finding]:
+        findings = []
+        for command in commands:
+            for line in command.split("\n"):
+                line = line.strip()
+                for manager in PACKAGE_MANAGERS:
+                    if manager in line and not self._is_pinned(line):
+                        findings.append(Finding(
+                            rule_id=self.rule_id,
+                            title=self.title,
+                            severity=self.severity,
+                            description=f"Command '{line.strip()}' installs dependencies without version pins.",
+                            remediation="Pin all dependencies to exact versions. Use 'pip install requests==2.31.0' instead of 'pip install requests'.",
+                            mitre_technique="T1195.002",
+                            owasp_category="CICD-SEC-3",
+                            file_path=file_path,
+                        ))
+                        break
+        return findings
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        findings = []
+
+        if platform == "github":
+            jobs = config.get("jobs", {})
+            for job in jobs.values():
+                if not isinstance(job, dict):
+                    continue
+                for step in job.get("steps", []):
+                    if not isinstance(step, dict):
+                        continue
+                    run = step.get("run", "")
+                    if run:
+                        findings.extend(self._check_commands([run], file_path))
+
+        elif platform in ("gitlab", "azure"):
+            for key, value in config.items():
+                if not isinstance(value, dict):
+                    continue
+                scripts = value.get("script", [])
+                if isinstance(scripts, str):
+                    scripts = [scripts]
+                if isinstance(scripts, list):
+                    string_scripts = [s for s in scripts if isinstance(s, str)]
+                    findings.extend(self._check_commands(string_scripts, file_path))
+
+        return findings

pipelineguard/rules/excessive_permissions.py

@@ -0,0 +1,40 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class ExcessivePermissions(BaseRule):
+    rule_id = "FS003"
+    title = "Excessive Permissions — Overprivileged Workflow Token"
+    severity = Severity.HIGH #
+    
+    SUSPICIOUS_PATTERNS = [
+        "write-all", "read-all"
+    ]
+
+    def _extract_permissions_(self, config: dict[str, Any]) -> Any:
+        return config.get("permissions", None)
+
+        
+            
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        if platform != "github":
+            return []        
+        findings = []
+        permission = self._extract_permissions_(config)
+
+        if (permission in self.SUSPICIOUS_PATTERNS) or (permission is None) :
+            findings.append(Finding( 
+                rule_id = self.rule_id,
+                title = self.title,
+                severity = self.severity,
+                description = f"Pipeline permissions are set to '{permission}' giving the workflow token broad access across the repository. An attacker who compromises this pipeline can read code, write to branches, modify releases, and exfiltrate secrets.",
+                remediation = f"Define permissions explicitly at the workflow level using least privilege. Only grant the specific scopes the job needs. Example: 'permissions: contents: read'. Never use write-all or read-all.",
+                mitre_technique="T1078",
+                file_path=file_path,
+                owasp_category="CICD-SEC-5",
+
+            ))
+            
+
+        return findings

pipelineguard/rules/hardcoded_secrets.py

@@ -0,0 +1,119 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class HardcodedSecretsRule(BaseRule):
+    rule_id = "FS001"
+    title = "Hardcoded Secret — Plaintext Credential in Workflow"
+    severity = Severity.CRITICAL
+
+    SUSPICIOUS_PATTERNS = [
+        "api_key", "apikey", "api_token", "access_token",
+        "secret", "password", "passwd", "token",
+        "private_key", "client_secret", "auth_token",
+        "subscription_id", "account_key", "login", "private"
+    ]
+
+    def _extract_github_env_vars(self, config: dict[str, Any]) -> dict[str, Any]:
+        env_vars = {}
+        jobs = config.get("jobs", {})
+        for job in jobs.values():
+            if not isinstance(job, dict):
+                continue
+            env_vars.update({
+                k: v for k, v in job.get("env", {}).items()
+                if not k.startswith("__line_")
+            })
+            for step in job.get("steps", []):
+                if not isinstance(step, dict):
+                    continue
+                env_vars.update({
+                    k: v for k, v in step.get("env", {}).items()
+                    if not k.startswith("__line_")
+                })
+        return env_vars
+
+    def _extract_gitlab_variables(self, config: dict[str, Any]) -> dict[str, Any]:
+        variables = {}
+        top_level = config.get("variables", {})
+        if isinstance(top_level, dict):
+            variables.update({
+                k: v for k, v in top_level.items()
+                if not k.startswith("__line_")
+            })
+        for key, value in config.items():
+            if isinstance(value, dict) and "script" in value:
+                job_vars = value.get("variables", {})
+                if isinstance(job_vars, dict):
+                    variables.update({
+                        k: v for k, v in job_vars.items()
+                        if not k.startswith("__line_")
+                    })
+        return variables
+
+    def _extract_azure_variables(self, config: dict[str, Any]) -> dict[str, Any]:
+        variables = {}
+        top_level = config.get("variables", {})
+        if isinstance(top_level, dict):
+            variables.update({
+                k: v for k, v in top_level.items()
+                if not k.startswith("__line_")
+            })
+        return variables
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        findings = []
+
+        if platform == "github":
+            jobs = config.get("jobs", {})
+            for job in jobs.values():
+                if not isinstance(job, dict):
+                    continue
+                all_envs = [job.get("env", {})]
+                for step in job.get("steps", []):
+                    if isinstance(step, dict):
+                        all_envs.append(step.get("env", {}))
+                for env in all_envs:
+                    for var_name, var_value in env.items():
+                        if var_name.startswith("__line_"):
+                            continue
+                        if not isinstance(var_value, str):
+                            continue
+                        if any(pattern in var_name.lower() for pattern in self.SUSPICIOUS_PATTERNS):
+                            if not var_value.startswith("${{"):
+                                findings.append(Finding(
+                                    rule_id=self.rule_id,
+                                    title=self.title,
+                                    severity=self.severity,
+                                    description=f"Hardcoded secret found in environment variable '{var_name}'",
+                                    remediation=f"Move '{var_name}' to GitHub Secrets and reference it as ${{{{ secrets.{var_name} }}}}",
+                                    mitre_technique="T1552.001",
+                                    owasp_category="CICD-SEC-6",
+                                    file_path=file_path,
+                                    line_number=env.get(f"__line_{var_name}__", 0),
+                                ))
+
+        elif platform in ("gitlab", "azure"):
+            if platform == "gitlab":
+                env_vars = self._extract_gitlab_variables(config)
+            else:
+                env_vars = self._extract_azure_variables(config)
+
+            for var_name, var_value in env_vars.items():
+                if not isinstance(var_value, str):
+                    continue
+                if any(pattern in var_name.lower() for pattern in self.SUSPICIOUS_PATTERNS):
+                    safe_prefixes = ("${{", "${", "$CI_", "$AZURE_")
+                    if not any(var_value.startswith(p) for p in safe_prefixes):
+                        findings.append(Finding(
+                            rule_id=self.rule_id,
+                            title=self.title,
+                            severity=self.severity,
+                            description=f"Hardcoded secret found in variable '{var_name}'",
+                            remediation=f"Move '{var_name}' to your platform's secret manager and reference it as an environment variable.",
+                            mitre_technique="T1552.001",
+                            owasp_category="CICD-SEC-6",
+                            file_path=file_path,
+                        ))
+
+        return findings

pipelineguard/rules/missing_branch_protection.py

@@ -0,0 +1,15 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+class MissingBranchProtectionRule(BaseRule):
+    rule_id = "FS011"
+    title = "Missing Branch Protection — Direct Push to Default Branch Possible"
+    severity = Severity.HIGH
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        if platform != "github":
+            return [] 
+        # Branch protection is a repo setting not a workflow config
+        # This rule is wired up via the GitHub API scanner
+        # Scaffold here — full implementation in scanner refactor
+        return []

pipelineguard/rules/missing_env_protection.py

@@ -0,0 +1,33 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+DEPLOY_KEYWORDS = ["deploy", "release", "publish", "prod", "production", "ship"]
+
+class MissingEnvProtectionRule(BaseRule):
+    rule_id = "FS012"
+    title = "Missing Environment Protection — Deploy Job Has No Approval Gate"
+    severity = Severity.HIGH
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        if platform != "github":
+            return []
+        findings = []
+        jobs = config.get("jobs", {})
+
+        for job_name, job in jobs.items():
+            job_name_lower = job_name.lower()
+            is_deploy = any(keyword in job_name_lower for keyword in DEPLOY_KEYWORDS)
+
+            if is_deploy and not job.get("environment"):
+                findings.append(Finding(
+                    rule_id=self.rule_id,
+                    title=self.title,
+                    severity=self.severity,
+                    description=f"Job '{job_name}' appears to be a deployment job but has no GitHub Environment configured. Without environment protection rules, deployments to production can happen automatically with no human approval required.",
+                    remediation="Add an 'environment: production' key to this job and configure required reviewers in your GitHub repository's Environment settings. This adds a manual approval gate before any production deployment.",
+                    mitre_technique="T1078",
+                    owasp_category="CICD-SEC-5",
+                    file_path=file_path,
+                ))
+
+        return findings

pipelineguard/rules/missing_oidc.py

@@ -0,0 +1,56 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class MissingOIDCRule(BaseRule):
+    rule_id = "FS004"
+    title = "Missing OIDC — Long-Lived Cloud Credential in Use"
+    severity = Severity.HIGH #
+    
+    SAFE_PATTERNS = [
+    "aws-actions/", "azure/login", "google-github-actions/"
+    ]
+
+    def _extract_uses(self, config: dict[str, Any], ) -> list[str]:
+        uses = []
+        jobs = config.get("jobs", {})
+        for job in jobs.values():
+            for step in job.get("steps", []):
+                if "uses" in step:
+                    uses.append(step["uses"])
+        return uses
+
+    def _extract_permissions(self, config: dict[str, Any]) -> Any:
+        return config.get("permissions", None)
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        if platform != "github":
+            return []        
+        findings = []
+        uses = self._extract_uses(config)
+        permissions = self._extract_permissions(config)
+
+        uses_cloud_provider = any(
+            any(pattern in step for pattern in self.SAFE_PATTERNS)
+            for step in uses
+        )
+
+        has_oidc = (
+            isinstance(permissions, dict) and
+            permissions.get("id-token") == "write"
+        )
+
+        if uses_cloud_provider and not has_oidc:
+            findings.append(Finding(
+                rule_id=self.rule_id,
+                title=self.title,
+                severity=self.severity,
+                description=f"This pipeline connects to a cloud provider but does not use OIDC for authentication. Long-lived credentials stored as secrets can be stolen through a compromised action or leaked pipeline log and will remain valid until manually rotated.",
+                remediation="Add 'id-token: write' to the workflow permissions block and replace long-lived credential secrets with a role-to-assume (AWS) or client-id/tenant-id (Azure). This ensures credentials expire automatically after each run.",
+                mitre_technique="T1552.004",
+                file_path=file_path,
+                owasp_category="CICD-SEC-6",
+
+            ))
+
+        return findings

pipelineguard/rules/missing_timeout.py

@@ -0,0 +1,65 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class MissingTimeoutRule(BaseRule):
+    rule_id = "FS006"
+    title = "Missing Timeout — Job Runs Up to 6 Hours Unchecked"
+    severity = Severity.LOW
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        findings = []
+
+        if platform == "github":
+            jobs = config.get("jobs", {})
+            for job_name, job in jobs.items():
+                if not isinstance(job, dict):
+                    continue
+                if "timeout-minutes" not in job:
+                    findings.append(Finding(
+                        rule_id=self.rule_id,
+                        title=self.title,
+                        severity=self.severity,
+                        description=f"Job '{job_name}' has no timeout defined. GitHub's default timeout is 6 hours.",
+                        remediation=f"Add 'timeout-minutes: 15' to job '{job_name}'.",
+                        mitre_technique="T1499",
+                        owasp_category="CICD-SEC-10",
+                        file_path=file_path,
+                    ))
+
+        elif platform == "gitlab":
+            for key, value in config.items():
+                if not isinstance(value, dict):
+                    continue
+                if "script" in value and "timeout" not in value:
+                    findings.append(Finding(
+                        rule_id=self.rule_id,
+                        title=self.title,
+                        severity=self.severity,
+                        description=f"GitLab job '{key}' has no timeout defined. GitLab's default timeout is 1 hour.",
+                        remediation=f"Add 'timeout: 15 minutes' to job '{key}'.",
+                        mitre_technique="T1499",
+                        owasp_category="CICD-SEC-10",
+                        file_path=file_path,
+                    ))
+
+        elif platform == "azure":
+            jobs = config.get("jobs", [])
+            if isinstance(jobs, list):
+                for job in jobs:
+                    if not isinstance(job, dict):
+                        continue
+                    job_name = job.get("job", "unknown")
+                    if "timeoutInMinutes" not in job:
+                        findings.append(Finding(
+                            rule_id=self.rule_id,
+                            title=self.title,
+                            severity=self.severity,
+                            description=f"Azure DevOps job '{job_name}' has no timeout defined.",
+                            remediation=f"Add 'timeoutInMinutes: 15' to job '{job_name}'.",
+                            mitre_technique="T1499",
+                            owasp_category="CICD-SEC-10",
+                            file_path=file_path,
+                        ))
+
+        return findings

pipelineguard/rules/pull_request_target.py

@@ -0,0 +1,58 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class PullRequestTargetRule(BaseRule):
+    rule_id = "FS005"
+    title = "Pull Request Target — Secrets Exposed to Fork Code"
+    severity = Severity.CRITICAL
+
+    def _extract_triggers(self, config: dict[str, Any]) -> list[str]:
+        triggers = config.get(True, {})  # PyYAML converts 'on' to True
+        if isinstance(triggers, dict):
+            return list(triggers.keys())
+        if isinstance(triggers, list):
+            return triggers
+        return []
+
+    def _extract_uses(self, config: dict[str, Any]) -> list[str]:
+        uses = []
+        jobs = config.get("jobs", {})
+        for job in jobs.values():
+            for step in job.get("steps", []):
+                if "uses" in step:
+                    uses.append(step["uses"])
+        return uses
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        if platform != "github":
+            return [] 
+        findings = []
+        triggers = self._extract_triggers(config)
+        uses = self._extract_uses(config)
+
+        if "pull_request_target" not in triggers:
+            return findings
+
+        # pull_request_target is dangerous when combined with
+        # checking out untrusted code from the PR
+        dangerous_actions = [
+            "actions/checkout",
+        ]
+
+        for use in uses:
+            if any(action in use for action in dangerous_actions):
+                findings.append(Finding(
+                    rule_id=self.rule_id,
+                    title=self.title,
+                    severity=self.severity,
+                    description="This workflow uses 'pull_request_target' and checks out code from the pull request. 'pull_request_target' runs in the context of the base branch with access to secrets — combined with checking out PR code, an attacker can submit a malicious PR that executes arbitrary code with access to your repository secrets.",
+                    remediation="Do not combine pull_request_target with actions/checkout of the PR head. If you need to run code from a PR, use the pull_request event instead which does not have access to secrets. If pull_request_target is required, never check out or execute code from the PR branch.",
+                    mitre_technique="T1611",
+                    file_path=file_path,
+                    owasp_category="CICD-SEC-4",
+
+                ))
+                break
+
+        return findings

pipelineguard/rules/secrets_in_run.py

@@ -0,0 +1,64 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+SUSPICIOUS_PATTERNS = [
+    "password=", "passwd=", "token=", "api_key=", "apikey=",
+    "secret=", "Authorization: Bearer", "Authorization: Token",
+    "access_key=", "private_key=", "client_secret=",
+]
+
+
+class SecretsInRunRule(BaseRule):
+    rule_id = "FS010"
+    title = "Secret in Run Command — Plaintext Credential in Shell Step"
+    severity = Severity.CRITICAL
+
+    def _check_commands(self, commands: list[str], file_path: str) -> list[Finding]:
+        findings = []
+        for command in commands:
+            for line in command.split("\n"):
+                line_lower = line.lower()
+                for pattern in SUSPICIOUS_PATTERNS:
+                    if pattern.lower() in line_lower:
+                        after = line_lower.split(pattern.lower(), 1)[1].strip()
+                        if after and not after.startswith("${{") and not after.startswith("${"):
+                            findings.append(Finding(
+                                rule_id=self.rule_id,
+                                title=self.title,
+                                severity=self.severity,
+                                description=f"Run command contains what appears to be a hardcoded credential matching pattern '{pattern}'.",
+                                remediation="Move the credential to your platform's secret manager and reference it as an environment variable.",
+                                mitre_technique="T1552.001",
+                                owasp_category="CICD-SEC-6",
+                                file_path=file_path,
+                            ))
+                            break
+        return findings
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        findings = []
+
+        if platform == "github":
+            jobs = config.get("jobs", {})
+            for job in jobs.values():
+                if not isinstance(job, dict):
+                    continue
+                for step in job.get("steps", []):
+                    if not isinstance(step, dict):
+                        continue
+                    run = step.get("run", "")
+                    if run:
+                        findings.extend(self._check_commands([run], file_path))
+
+        elif platform in ("gitlab", "azure"):
+            for key, value in config.items():
+                if not isinstance(value, dict):
+                    continue
+                scripts = value.get("script", [])
+                if isinstance(scripts, str):
+                    scripts = [scripts]
+                if isinstance(scripts, list):
+                    string_scripts = [s for s in scripts if isinstance(s, str)]
+                    findings.extend(self._check_commands(string_scripts, file_path))
+
+        return findings

pipelineguard/rules/self_hosted_runner.py

@@ -0,0 +1,79 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class SelfHostedRunnerRule(BaseRule):
+    rule_id = "FS007"
+    title = "Self-Hosted Runner — Persistent Environment Risk"
+    severity = Severity.HIGH
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        findings = []
+
+        if platform == "github":
+            jobs = config.get("jobs", {})
+            for job_name, job in jobs.items():
+                if not isinstance(job, dict):
+                    continue
+                runs_on = job.get("runs-on", "")
+                if isinstance(runs_on, list):
+                    runs_on_str = " ".join(runs_on).lower()
+                else:
+                    runs_on_str = str(runs_on).lower()
+                if "self-hosted" in runs_on_str:
+                    findings.append(Finding(
+                        rule_id=self.rule_id,
+                        title=self.title,
+                        severity=self.severity,
+                        description=f"Job '{job_name}' runs on a self-hosted runner. Self-hosted runners persist between jobs and are not automatically cleaned up.",
+                        remediation="Use ephemeral containerized runners or configure the runner to reset to a clean state after every job.",
+                        mitre_technique="T1053",
+                        owasp_category="CICD-SEC-7",
+                        file_path=file_path,
+                    ))
+
+        elif platform == "gitlab":
+            for key, value in config.items():
+                if not isinstance(value, dict):
+                    continue
+                if "script" not in value:
+                    continue
+                tags = value.get("tags", [])
+                if isinstance(tags, list):
+                    tags_str = " ".join(tags).lower()
+                else:
+                    tags_str = str(tags).lower()
+                if "self-hosted" in tags_str or "self_hosted" in tags_str:
+                    findings.append(Finding(
+                        rule_id=self.rule_id,
+                        title=self.title,
+                        severity=self.severity,
+                        description=f"GitLab job '{key}' uses a self-hosted runner via tags. Self-hosted runners persist between jobs.",
+                        remediation="Use ephemeral containerized runners or configure the runner to reset after every job.",
+                        mitre_technique="T1053",
+                        owasp_category="CICD-SEC-7",
+                        file_path=file_path,
+                    ))
+
+        elif platform == "azure":
+            jobs = config.get("jobs", [])
+            if isinstance(jobs, list):
+                for job in jobs:
+                    if not isinstance(job, dict):
+                        continue
+                    pool = job.get("pool", {})
+                    if isinstance(pool, dict):
+                        name = pool.get("name", "").lower()
+                        if name and "azure pipelines" not in name:
+                            findings.append(Finding(
+                                rule_id=self.rule_id,
+                                title=self.title,
+                                severity=self.severity,
+                                description=f"Azure DevOps job uses a self-hosted agent pool '{pool.get('name')}'. Self-hosted agents persist between jobs.",
+                                remediation="Use Microsoft-hosted agents where possible or configure self-hosted agents to reset after every job.",
+                                mitre_technique="T1053",
+                                owasp_category="CICD-SEC-7",
+                                file_path=file_path,
+                            ))
+
+        return findings

pipelineguard/rules/unpinned_actions.py

@@ -0,0 +1,45 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class UnpinnedActionsRule(BaseRule):
+    rule_id = "FS002"
+    title = "Unpinned Action — Supply Chain Attack Vector"
+    severity = Severity.CRITICAL   # Supply chain attacks are in OWASP top 10 right now (04/14/2026)
+    
+
+    def _extract_uses(self, config: dict[str, Any]) -> dict[str, str]:
+        uses = []                                   # Creating list of ENV Variable
+        jobs = config.get("jobs", {})                   # jobs is set too whats inside {} for jobs
+        for job in jobs.values():
+            for step in job.get("steps",[]):
+                if "uses" in step:
+                    uses.append(step["uses"])
+        return uses
+
+            
+
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        if platform != "github":
+            return []
+        findings = []
+        uses = self._extract_uses(config)
+
+        for use in uses:
+            before, separator, after = use.partition("@") 
+            is_pinned = len(after) == 40 and all(c in "0123456789abcdef" for c in after)
+
+            if not is_pinned:
+                findings.append(Finding( 
+                    rule_id=self.rule_id,
+                    title=self.title,
+                    severity=self.severity,
+                    description=f"Action '{use}' is not pinned to a commit hash",
+                    remediation=f"Pin '{use}' to a full commit SHA instead of a branch or tag. Example: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae1",
+                    mitre_technique="T1195.001",
+                    file_path=file_path,
+                    owasp_category="CICD-SEC-3",
+
+                ))
+
+        return findings