flowsec 0.1.0__py3-none-any.whl

flowsec-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: flowsec
+Version: 0.1.0
+Summary: CI/CD pipeline security analyzer — scans GitHub Actions, GitLab CI, and Azure DevOps configs for attack vectors
+Author-email: Vansh Bhardwaj <Scorpio.vansh@gmail.com>
+License: MIT
+Keywords: cicd,devsecops,github-actions,pipeline-security,sast,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.28.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: jsonpath-ng>=1.6.1
+Requires-Dist: pygithub>=2.1.1
+Requires-Dist: pygments>=2.18.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: python-gitlab>=4.4.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.8; extra == 'dev'
+Requires-Dist: hatch>=1.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: responses>=0.25.3; extra == 'dev'
+Requires-Dist: ruff>=0.4.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FlowSec
+
+> A Python security tool that scans CI/CD pipeline configurations for attack vectors across GitHub Actions, GitLab CI, and Azure DevOps. Every finding maps to a MITRE ATT&CK technique and OWASP CICD Top 10 category.
+>
+> The pipeline is the attack surface. FlowSec treats it that way.
+
+**[Full documentation](docs/FULL_README.md)**
+
+---
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/VanshBhardwaj1945/FlowSec)
+
+---
+
+## What it catches
+
+| ID | Rule | Severity | MITRE | OWASP |
+|---|---|---|---|---|
+| FS001 | Hardcoded Secret — Plaintext Credential in Workflow | CRITICAL | T1552.001 | CICD-SEC-6 |
+| FS002 | Unpinned Action — Supply Chain Attack Vector | CRITICAL | T1195.001 | CICD-SEC-3 |
+| FS003 | Excessive Permissions — Overprivileged Workflow Token | HIGH | T1078 | CICD-SEC-5 |
+| FS004 | Missing OIDC — Long-Lived Cloud Credential in Use | HIGH | T1552.004 | CICD-SEC-6 |
+| FS005 | Pull Request Target — Secrets Exposed to Fork Code | CRITICAL | T1611 | CICD-SEC-4 |
+| FS006 | Missing Timeout — Job Runs Up to 6 Hours Unchecked | LOW | T1499 | CICD-SEC-10 |
+| FS007 | Self-Hosted Runner — Persistent Environment Risk | HIGH | T1053 | CICD-SEC-7 |
+| FS008 | Missing Artifact Signing — No Tamper Protection | MEDIUM | T1553 | CICD-SEC-8 |
+| FS009 | Unpinned Dependency — Package Installed Without Version Lock | HIGH | T1195.002 | CICD-SEC-3 |
+| FS010 | Secret in Run Command — Plaintext Credential in Shell Step | CRITICAL | T1552.001 | CICD-SEC-6 |
+| FS011 | Missing Branch Protection — Direct Push to Default Branch Possible | HIGH | T1098 | CICD-SEC-1 |
+| FS012 | Missing Environment Protection — Deploy Job Has No Approval Gate | HIGH | T1078 | CICD-SEC-5 |
+| FS013 | Workflow Dispatch Injection — Unvalidated Input in Shell Command | CRITICAL | T1059 | CICD-SEC-9 |
+
+---
+
+## Platforms supported
+
+| Platform | How to scan |
+|---|---|
+| GitHub Actions | `flowsec scan --repo owner/repo` or `--file workflow.yml` |
+| GitLab CI | `flowsec scan --gitlab .gitlab-ci.yml` |
+| Azure DevOps | `flowsec scan --azure azure-pipelines.yml` |
+
+---
+
+## Real findings on a real repo
+
+Scanned `VanshBhardwaj1945/cloud-resume-challenge-azure` — 13 findings across 2 workflow files:
+
+```
+[CRITICAL] FS002 - Unpinned Action — Supply Chain Attack Vector
+  File: .github/workflows/backend.main.yaml
+  Action 'actions/checkout@v4' is not pinned to a commit hash
+
+[HIGH]     FS003 - Excessive Permissions — Overprivileged Workflow Token
+  File: .github/workflows/backend.main.yaml
+  Pipeline permissions set to 'None' — GitHub defaults apply
+
+[HIGH]     FS004 - Missing OIDC — Long-Lived Cloud Credential in Use
+  File: .github/workflows/backend.main.yaml
+  Cloud provider action present but no id-token: write permission
+
+[LOW]      FS006 - Missing Timeout — Job Runs Up to 6 Hours Unchecked
+  File: .github/workflows/backend.main.yaml
+  Job 'build-and-deploy' has no timeout — GitHub default is 6 hours
+```
+
+---
+
+## Stack
+
+| Layer | Tools |
+|---|---|
+| Language | Python 3.11 |
+| GitHub Connection | PyGithub |
+| YAML Parsing | PyYAML with custom line-tracking loader |
+| Terminal Output | rich |
+| HTML Reports | Jinja2 — interactive filtering, expandable findings, PDF export |
+| AI Narratives | Anthropic Claude API with local caching |
+| Linting | ruff, mypy, bandit |
+| Packaging | hatch, pyproject.toml |
+| Containerization | Docker |
+
+---
+
+## Quick Start
+
+Click the Codespaces button above to run FlowSec in your browser with zero setup. Or run locally:
+
+```bash
+git clone https://github.com/VanshBhardwaj1945/FlowSec.git
+cd FlowSec
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+cp .env.example .env
+# Add your GITHUB_TOKEN to .env
+
+flowsec scan --repo owner/repo
+flowsec scan --file .github/workflows/ci.yml
+flowsec scan --gitlab .gitlab-ci.yml
+flowsec scan --azure azure-pipelines.yml
+flowsec scan --repo owner/repo --ai --output report.html
+```
+
+---
+
+## Use as a Pipeline Gate
+
+Add FlowSec to your own GitHub Actions workflow to automatically block PRs that introduce security misconfigurations:
+
+```yaml
+name: FlowSec Security Scan
+on: [push, pull_request]
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install FlowSec
+        run: pip install flowsec
+      - name: Run FlowSec
+        run: flowsec scan --file .github/workflows/ --fail-on critical
+```
+
+`--fail-on critical` exits with code 1 if any CRITICAL findings are found, failing the pipeline and blocking the PR. Supports `critical`, `high`, `medium`, and `low` thresholds.
+
+---
+
+## Status
+
+| Component | Status |
+|---|---|
+| Rule engine — BaseRule, Finding, Severity | Complete |
+| YAML parser with line number tracking | Complete |
+| 13 security rules FS001-FS013 | Complete |
+| MITRE ATT&CK + OWASP CICD Top 10 mapping | Complete |
+| Platform-aware rule engine | Complete |
+| GitHub Actions scanner — API and local file | Complete |
+| GitLab CI scanner | Complete |
+| Azure DevOps scanner | Complete |
+| CLI — --repo, --file, --gitlab, --azure, --ai, --output, --fail-on | Complete |
+| Rich terminal output with risk score | Complete |
+| HTML report with filtering, PDF export | Complete |
+| AI attack narratives with local caching | Complete |
+| Line number tracking | Complete |
+| Pipeline gate flag --fail-on | Complete |
+| GitHub Codespace config | Complete |
+| PyPI publish | Pending |
+| Web app — FastAPI + frontend | Pending |
+| Web app — Azure Container Apps deployment | Pending |
+
+---
+
+## Roadmap
+
+**Phase 1 — Core CLI**
+PyPI publish so anyone can `pip install flowsec`.
+
+**Phase 2 — Web App**
+FastAPI backend, frontend for repo input and file upload, deployed to Azure Container Apps via GitHub Actions. Anyone can scan a pipeline from a browser without installing anything.
+
+**Phase 3 — Expansion**
+Jenkins support, AWS CodePipeline, 20+ rule library, rate limiting.
+
+---
+
+## About this project
+
+Built as a security engineering portfolio project. The goal was to build an actual security tool — not run existing ones — and document every decision along the way.
+
+**[Read the full documentation](docs/FULL_README.md)**

flowsec-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+pipelineguard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pipelineguard/ai_narrative.py,sha256=WQHwsDP488vMnctyNf_NGdnJ9Qjrc6fOWUb66eGevw8,2411
+pipelineguard/cli.py,sha256=YTlpkrpnzDjZF5AZ1LY5DR6i02QTKIzxzyZtp52Qiv0,5662
+pipelineguard/parser.py,sha256=snrYk8W579UkBuIT2PLEO72NYhnBbT0QcfGheFaSC4E,808
+pipelineguard/report.py,sha256=LvPtJ_XPmcxyCavn7FTKq7urld0CfI0JrYUEOQZCnAI,1224
+pipelineguard/scanner.py,sha256=Ag_zF3jDIXxxxvU7B5FuwdQNiSL5la683btpq0ya_Qo,2863
+pipelineguard/scoring.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pipelineguard/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pipelineguard/rules/artifact_signing.py,sha256=JIknEweoCs-nAEnC033lfQYSxoMMFyWdD50Hei_DzdM,2385
+pipelineguard/rules/base.py,sha256=7tprAb2MpjuWSNtQE7wgwKepn7Ff439FkDip5M7VFDk,684
+pipelineguard/rules/dependency_pinning.py,sha256=8e3V_VxNTQW5U1eJTxv1RvQCnUolAug25y20Fb3TV7I,3043
+pipelineguard/rules/excessive_permissions.py,sha256=0oDNBcMhACGQ2WFWbmJX_4TnxQEXV4N-UHIz8_9tc0A,1588
+pipelineguard/rules/hardcoded_secrets.py,sha256=qH8AJ2tQw_Nx_ZlDPNBSZVQeJraBca5jaRqw_mG0j6E,5325
+pipelineguard/rules/missing_branch_protection.py,sha256=NblY4Z4hzLVncsxiSkEpYezy6G9IWWltra26Nxsq0rI,622
+pipelineguard/rules/missing_env_protection.py,sha256=n77Qd7sjXy3nYttzSs2kBYKNiwktMUuGUG2oPmnWYoo,1605
+pipelineguard/rules/missing_oidc.py,sha256=-F24Lxnai8yvPj5BWZcuAB0ksf4XVEVc89qSLbk_LrQ,2183
+pipelineguard/rules/missing_timeout.py,sha256=EEA4-cHWqk3Fd-5ULtRnQ85f0P6OaTAlhAI-BX8toXU,2873
+pipelineguard/rules/pull_request_target.py,sha256=JCCYh8sEOYvOlqqLGqLMWdsOXUFU6cl2Kb0fpHe8J10,2497
+pipelineguard/rules/secrets_in_run.py,sha256=X_n3RybHmi4eXpRoGlzXAWfpiwwOPNX6_CzY9qPm6QQ,2859
+pipelineguard/rules/self_hosted_runner.py,sha256=6zteDVpbCyBJKkyypJo6o1AZEsfXNhQ3I7K4F7Qcu3s,3819
+pipelineguard/rules/unpinned_actions.py,sha256=u11S4jlU__1vr2FldzLHGavDKUtnej9pvbNsVUQjOGY,1770
+pipelineguard/rules/workflow_dispatch_injection.py,sha256=fbKFKzK3CmIGdgIblWmb36_v_LKZ45Vy-LB1mx4R1jg,2127
+flowsec-0.1.0.dist-info/METADATA,sha256=OlrmMdQL2tCN-HJJgjxx10nbXIHkF0nt1z9tTdfvsTU,7553
+flowsec-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+flowsec-0.1.0.dist-info/entry_points.txt,sha256=98BGjj8_rTlHPCtlS8fQyHNKPViKzvprQwDpKWRKEoM,51
+flowsec-0.1.0.dist-info/RECORD,,

flowsec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flowsec-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flowsec = pipelineguard.cli:main

pipelineguard/ai_narrative.py

@@ -0,0 +1,73 @@
+import os
+import json
+import hashlib
+from pathlib import Path
+from anthropic import Anthropic
+from dotenv import load_dotenv
+from .rules.base import Finding
+
+load_dotenv()
+
+CACHE_FILE = Path.home() / ".flowsec_cache.json"
+
+def _get_cache_key(finding: Finding) -> str:
+    content = f"{finding.rule_id}:{finding.description}"
+    return hashlib.md5(content.encode()).hexdigest()
+
+def _load_cache() -> dict:
+    if CACHE_FILE.exists():
+        with open(CACHE_FILE) as f:
+            return json.load(f)
+    return {}
+
+def _save_cache(cache: dict) -> None:
+    with open(CACHE_FILE, "w") as f:
+        json.dump(cache, f, indent=2)
+
+def generate_narrative(finding: Finding) -> str:
+    cache = _load_cache()
+    key = _get_cache_key(finding)
+
+    if key in cache:
+        return cache[key]
+
+    client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+
+    prompt = f"""
+
+            You are an offensive security engineer specializing in CI/CD pipeline attacks and supply chain security.
+            You are writing a threat intelligence brief for a security team that has just received a finding from an automated pipeline scanner.
+            Your job is to write a concise, specific attack narrative for this finding.
+            Do not write generic advice. 
+
+            Write exactly how a real attacker would exploit this specific misconfiguration — what they would do first, what access they would gain, and what the realistic impact is on this organization.
+
+            Write exactly this structure, no markdown, no asterisks, no bold syntax:
+            
+            **Attack Vector:** [1-2 sentence — how they get in]
+            **What They Gain:** [1-2 sentence — what access/capability]  
+            **Blast Radius:** [1-2 sentence — realistic worst case impact]
+            **Ways to Fix:** [1-2 sentence — Explain ways to fix this]
+ 
+            Rule: {finding.rule_id} — {finding.title}
+            Description: {finding.description}
+            MITRE Technique: {finding.mitre_technique}
+
+            Write only the attack narrative, no preamble.
+
+            """
+
+    message = client.messages.create(
+        model="claude-haiku-4-5-20251001",
+        max_tokens=200,
+        messages=[
+            {"role": "user", "content": prompt}
+        ]
+    )
+
+    response_text = message.content[0].text
+
+    cache[key] = response_text
+    _save_cache(cache)
+
+    return response_text

pipelineguard/cli.py

@@ -0,0 +1,141 @@
+import argparse
+import sys
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from .scanner import scan_file, scan_repo, scan_gitlab_file, scan_azure_file
+
+from .rules.base import Finding
+from .scanner import scan_file, scan_repo, scan_gitlab_file
+
+console = Console()
+
+SEVERITY_COLORS = {
+    "critical": "bold red",
+    "high": "bold orange3",
+    "medium": "bold yellow",
+    "low": "bold blue",
+}
+
+
+def display_findings(findings: list[Finding]) -> None:
+    console.print()
+    console.print(Panel("[bold white]FlowSec Security Report[/bold white]", style="blue"))
+    console.print()
+
+    table = Table(box=box.ROUNDED, show_header=True, header_style="bold white")
+    table.add_column("Severity", width=8)
+    table.add_column("Rule ID", width=8)
+    table.add_column("Title", width=50)
+    table.add_column("OWASP", width=12)
+    table.add_column("File", width=40)
+
+    for f in findings:
+        color = SEVERITY_COLORS.get(f.severity.value, "white")
+        table.add_row(
+            f"[{color}]{f.severity.value.upper()}[/{color}]",
+            f.rule_id,
+            f.title,
+            f.owasp_category or "",
+            f.file_path,
+        )
+
+    console.print(table)
+    console.print()
+
+    critical = sum(1 for f in findings if f.severity.value == "critical")
+    high = sum(1 for f in findings if f.severity.value == "high")
+    medium = sum(1 for f in findings if f.severity.value == "medium")
+    low = sum(1 for f in findings if f.severity.value == "low")
+    score = (critical * 10) + (high * 5) + (medium * 3) + (low * 1)
+
+    summary = (
+        f"[bold red]Critical: {critical}[/bold red]  "
+        f"[bold orange3]High: {high}[/bold orange3]  "
+        f"[bold yellow]Medium: {medium}[/bold yellow]  "
+        f"[bold blue]Low: {low}[/bold blue]\n\n"
+        f"[bold white]Total Findings: {len(findings)}[/bold white]  |  "
+        f"[bold white]Risk Score: {score}[/bold white]"
+    )
+
+    console.print(Panel(summary, title="[bold white]Summary[/bold white]", style="blue"))
+    console.print()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="FlowSec - CI/CD pipeline security analyzer")
+    subparsers = parser.add_subparsers(dest="command")
+
+    scan_parser = subparsers.add_parser("scan", help="Scan a pipeline")
+    scan_parser.add_argument("--repo", help="GitHub repo name e.g. owner/repo")
+    scan_parser.add_argument("--file", help="Path to a local GitHub Actions workflow file")
+    scan_parser.add_argument("--gitlab", help="Path to a local GitLab CI file")
+    scan_parser.add_argument("--azure", help="Path to a local Azure DevOps pipeline file")
+    scan_parser.add_argument("--output", help="Save HTML report to this path")
+    scan_parser.add_argument("--ai", action="store_true", help="Generate AI attack narratives per finding")
+    scan_parser.add_argument(
+        "--fail-on",
+        choices=["critical", "high", "medium", "low"],
+        help="Exit with code 1 if findings at or above this severity are found"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "scan":
+        findings: list[Finding] = []
+
+        if args.repo:
+            console.print(f"\n[bold blue]Scanning[/bold blue] [white]{args.repo}[/white]...\n")
+            findings = scan_repo(args.repo)
+        elif args.file:
+            console.print(f"\n[bold blue]Scanning[/bold blue] [white]{args.file}[/white]...\n")
+            findings = scan_file(args.file)
+        elif args.gitlab:
+            console.print(f"\n[bold blue]Scanning GitLab CI[/bold blue] [white]{args.gitlab}[/white]...\n")
+            findings = scan_gitlab_file(args.gitlab)
+        elif args.azure:
+            console.print(f"\n[bold blue]Scanning Azure DevOps[/bold blue] [white]{args.azure}[/white]...\n")
+            from .scanner import scan_azure_file
+            findings = scan_azure_file(args.azure)
+        else:
+            console.print("[bold red]Error:[/bold red] provide --repo, --file, or --gitlab")
+            return
+
+        if not findings:
+            console.print(Panel("[bold green]No findings. Pipeline looks clean.[/bold green]", style="green"))
+            return
+
+        if args.ai:
+            from .ai_narrative import generate_narrative
+            console.print("\n[bold blue]Generating AI attack narratives...[/bold blue]\n")
+            for f in findings:
+                f.narrative = generate_narrative(f)
+
+        display_findings(findings)
+
+        if args.ai:
+            console.print()
+            console.print(Panel("[bold white]AI Attack Narratives[/bold white]", style="blue"))
+            console.print()
+            for f in findings:
+                if f.narrative:
+                    console.print(f"[bold]{f.rule_id}[/bold] — {f.title}")
+                    console.print(f"[dim]{f.narrative}[/dim]")
+                    console.print()
+
+        if args.output:
+            from .report import generateReport
+            generateReport(findings, args.repo or args.file or args.gitlab or args.azure or "local scan", args.output)
+            console.print(f"\n[bold green]Report saved to {args.output}[/bold green]")
+
+        if args.fail_on:
+            SEVERITY_ORDER = ["low", "medium", "high", "critical"]
+            threshold = SEVERITY_ORDER.index(args.fail_on.lower())
+            failing = [f for f in findings if SEVERITY_ORDER.index(f.severity.value) >= threshold]
+            if failing:
+                console.print(f"\n[bold red]Pipeline failed — {len(failing)} finding(s) at or above {args.fail_on.upper()} severity.[/bold red]")
+                sys.exit(1)
+
+    else:
+        parser.print_help()

pipelineguard/parser.py

@@ -0,0 +1,33 @@
+import yaml
+from yaml.resolver import BaseResolver
+
+
+class LineLoader(yaml.SafeLoader):
+    pass
+
+
+def construct_mapping(loader, node):
+    loader.flatten_mapping(node)
+    mapping = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node)
+        value = loader.construct_object(value_node)
+        mapping[key] = value
+        if isinstance(value, str):
+            mapping[f"__line_{key}__"] = key_node.start_mark.line + 1
+    return mapping
+
+
+LineLoader.add_constructor(
+    BaseResolver.DEFAULT_MAPPING_TAG,
+    construct_mapping,
+)
+
+
+def parse_pipeline(file_path: str) -> dict:
+    with open(file_path, "r") as f:
+        return yaml.load(f, Loader=LineLoader)
+
+
+def parse_pipeline_with_lines(content: str) -> dict:
+    return yaml.load(content, Loader=LineLoader)

pipelineguard/report.py

@@ -0,0 +1,35 @@
+from jinja2 import Environment, FileSystemLoader
+from datetime import datetime
+from pathlib import Path
+from .rules.base import Finding
+
+def generateReport(findings: list[Finding], repo_name: str, output_path: str)-> None:
+
+    env = Environment(loader=FileSystemLoader(
+        Path(__file__).parent / "templates"
+    ))
+    template = env.get_template("report.html")
+
+    critical = sum(1 for f in findings if f.severity.value == "critical")
+    high = sum(1 for f in findings if f.severity.value == "high")
+    medium = sum(1 for f in findings if f.severity.value == "medium")
+    low = sum(1 for f in findings if f.severity.value == "low")
+    risk_score = (critical * 10) + (high * 5) + (medium * 3) + (low * 1)
+
+    data = {
+        "repo_name": repo_name,
+        "scan_date": datetime.now().strftime("%B %d, %Y %I:%M %p"),
+        "file_count": len(set(f.file_path for f in findings)),
+        "total": len(findings),
+        "critical": critical,
+        "high": high,
+        "medium": medium,
+        "low": low,
+        "risk_score": risk_score,
+        "findings": findings,
+    }
+
+    rendered_html = template.render(data)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(rendered_html)

pipelineguard/rules/artifact_signing.py

@@ -0,0 +1,63 @@
+from typing import Any
+from .base import BaseRule, Finding, Severity
+
+
+class ArtifactSigningRule(BaseRule):
+    rule_id = "FS008"
+    title = "Missing Artifact Signing — No Tamper Protection"
+    severity = Severity.MEDIUM
+
+    # Actions that publish artifacts or packages without signing
+    PUBLISHING_ACTIONS = [
+        "actions/upload-artifact",
+        "pypa/gh-action-pypi-publish",
+        "docker/build-push-action",
+        "softprops/action-gh-release",
+    ]
+
+    # Actions that indicate signing is present
+    SIGNING_ACTIONS = [
+        "sigstore/cosign-installer",
+        "anchore/sbom-action",
+        "slsa-framework/slsa-github-generator",
+    ]
+
+    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 = []
+        uses = self._extract_uses(config)
+
+        publishes_artifact = any(
+            any(action in step for action in self.PUBLISHING_ACTIONS)
+            for step in uses
+        )
+
+        has_signing = any(
+            any(action in step for action in self.SIGNING_ACTIONS)
+            for step in uses
+        )
+
+        if publishes_artifact and not has_signing:
+            findings.append(Finding(
+                rule_id=self.rule_id,
+                title=self.title,
+                severity=self.severity,
+                description="This pipeline publishes artifacts or packages without cryptographic signing. Without signed artifacts, consumers have no way to verify that what they downloaded was actually built by your pipeline and has not been tampered with in transit or storage.",
+                remediation="Add artifact signing using Sigstore/cosign or the SLSA framework. For Docker images use cosign to sign after push. For PyPI packages use sigstore. For GitHub releases attach SLSA provenance using slsa-framework/slsa-github-generator.",
+                mitre_technique="T1553",
+                file_path=file_path,
+                owasp_category="CICD-SEC-8",
+
+            ))
+
+        return findings

pipelineguard/rules/base.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class Severity(Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    title: str
+    severity: Severity
+    description: str
+    remediation: str
+    mitre_technique: str
+    file_path: str
+    line_number: int = 0
+    narrative: str = ""
+    owasp_category: str = ""
+
+
+
+
+class BaseRule(ABC):
+    rule_id: str
+    title: str
+    severity: Severity
+
+    @abstractmethod
+    def check(self, config: dict[str, Any], file_path: str, platform: str = "github") -> list[Finding]:
+        ...