helmgate 0.1.0__tar.gz

helmgate-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: helmgate
+Version: 0.1.0
+Summary: Helm chart linter and policy enforcement CLI
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: cryptography>=42.0

helmgate-0.1.0/README.md

@@ -0,0 +1,130 @@
+# helmgate
+
+Helm chart linter and policy enforcement CLI. Scans Kubernetes Helm charts for security vulnerabilities and best-practice violations.
+
+## Installation
+
+```bash
+pip install helmgate
+```
+
+## Usage
+
+```bash
+# Scan a chart (table output, default)
+helmgate scan ./my-chart
+
+# Pro: export as JSON
+helmgate scan ./my-chart --output json
+```
+
+### `--fail-on` — CI/CD exit code control
+
+Controls at which severity level the CLI exits with code `1`. Useful for blocking deployments in CI pipelines.
+
+| Value | Behavior |
+|---|---|
+| `CRITICAL` | Exit 1 only if CRITICAL findings exist (default) |
+| `HIGH` | Exit 1 if HIGH or above findings exist |
+| `MEDIUM` | Exit 1 if MEDIUM or above findings exist |
+| `LOW` | Exit 1 if LOW or above findings exist |
+| `INFO` | Exit 1 if any findings exist |
+| `NONE` | Never exit 1 regardless of findings |
+
+```bash
+# Fail the build on any CRITICAL finding (default)
+helmgate scan ./my-chart
+
+# Fail the build on HIGH or above
+helmgate scan ./my-chart --fail-on HIGH
+
+# Scan without failing the build (report only)
+helmgate scan ./my-chart --fail-on NONE
+
+# JSON output without failing the build (Pro)
+helmgate scan ./my-chart --output json --fail-on NONE
+```
+
+**GitHub Actions example:**
+
+```yaml
+- name: Scan Helm chart
+  run: helmgate scan ./chart --fail-on HIGH
+```
+
+## Free vs Pro
+
+| Feature | Free | Pro |
+|---|---|---|
+| CRITICAL & HIGH rules (13 rules) | ✓ | ✓ |
+| MEDIUM & LOW rules (29 rules) | — | ✓ |
+| JSON output | — | ✓ |
+| Price | Free | $9 one-time (lifetime) |
+
+**To get a Pro license key**, send an email to [yunus.olgun@outlook.com](mailto:yunus.olgun@outlook.com) with the subject `helmgate Pro License`.
+
+Once you have a key:
+
+```bash
+helmgate activate HGATE-<your-key>
+```
+
+Or set it as an environment variable:
+
+```bash
+export HELMGATE_LICENSE_KEY=HGATE-<your-key>
+```
+
+## Rules
+
+### Security (SEC) — 20 rules
+
+| ID | Severity | Description |
+|---|---|---|
+| SEC001 | HIGH | Container runs as root |
+| SEC002 | CRITICAL | Privileged container |
+| SEC003 | HIGH | Privilege escalation allowed |
+| SEC004 | MEDIUM | Root filesystem not read-only |
+| SEC005 | HIGH | Host network namespace shared |
+| SEC006 | HIGH | Host PID namespace shared |
+| SEC007 | HIGH | Linux capabilities not dropped |
+| SEC008 | MEDIUM | Secret passed as plain-text env var |
+| SEC009 | HIGH | Host IPC namespace shared |
+| SEC010 | MEDIUM | Seccomp profile not set |
+| SEC011 | HIGH | Dangerous capability added (SYS_ADMIN, NET_ADMIN, etc.) |
+| SEC012 | HIGH | hostPath volume mounted |
+| SEC013 | MEDIUM | Service account token auto-mounted |
+| SEC014 | MEDIUM | Host port used |
+| SEC015 | MEDIUM | AppArmor profile not configured |
+| SEC016 | HIGH | Container runs with root group (runAsGroup: 0) |
+| SEC017 | HIGH | Unsafe sysctls present |
+| SEC018 | MEDIUM | shareProcessNamespace enabled |
+| SEC019 | MEDIUM | subPath used in volumeMount |
+| SEC020 | LOW | No pod-level securityContext |
+
+### Best Practices (BP) — 22 rules
+
+| ID | Severity | Description |
+|---|---|---|
+| BP001 | HIGH | Missing CPU/memory limits |
+| BP002 | MEDIUM | Missing CPU/memory requests |
+| BP003 | HIGH | Image uses `latest` tag |
+| BP004 | MEDIUM | No liveness probe |
+| BP005 | MEDIUM | No readiness probe |
+| BP006 | LOW | Fewer than 2 replicas |
+| BP007 | MEDIUM | Image from untrusted registry |
+| BP008 | LOW | Deployed to default namespace |
+| BP009 | LOW | No startup probe |
+| BP010 | LOW | imagePullPolicy not IfNotPresent |
+| BP011 | MEDIUM | Uses default service account |
+| BP012 | LOW | Missing standard labels (app.kubernetes.io/name, version) |
+| BP013 | LOW | terminationGracePeriodSeconds not set |
+| BP014 | LOW | Unnamed container port |
+| BP015 | MEDIUM | Image not pinned to digest |
+| BP016 | LOW | No pod anti-affinity defined |
+| BP017 | LOW | revisionHistoryLimit not set (Deployment) |
+| BP018 | LOW | progressDeadlineSeconds not set (Deployment) |
+| BP019 | MEDIUM | updateStrategy not defined (StatefulSet/DaemonSet) |
+| BP020 | LOW | minReadySeconds not set (Deployment) |
+| BP021 | LOW | priorityClassName not set |
+| BP022 | MEDIUM | CronJob concurrencyPolicy is Allow |

helmgate-0.1.0/helmgate/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

helmgate-0.1.0/helmgate/cli.py

@@ -0,0 +1,120 @@
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from .scanner import scan
+from .report import print_report
+from .license import is_pro, activate as activate_license
+from . import __version__
+
+app = typer.Typer(
+    name="helmgate",
+    help="Helm chart linter and policy enforcement tool.",
+    add_completion=False,
+)
+console = Console()
+
+
+@app.command(name="scan")
+def scan_cmd(
+    chart: Path = typer.Argument(..., help="Path to the Helm chart directory."),
+    fail_on: str = typer.Option(
+        "CRITICAL",
+        "--fail-on",
+        help="Exit with code 1 if findings at or above this severity exist. "
+             "Choices: CRITICAL, HIGH, MEDIUM, LOW, INFO, NONE",
+    ),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table, json"),
+):
+    """Scan a Helm chart for security and best-practice issues."""
+    if not chart.is_dir():
+        console.print(f"[red]Error:[/red] '{chart}' is not a directory.")
+        raise typer.Exit(1)
+
+    pro = is_pro()
+
+    if output == "json" and not pro:
+        console.print(
+            "[yellow]JSON output requires a Pro license.[/yellow]\n"
+            "Activate with: [bold]helmgate activate <key>[/bold]\n"
+            "Get a license key: [bold]yunus.olgun@outlook.com[/bold]"
+        )
+        raise typer.Exit(1)
+
+    from .rules import ALL_RULES, FREE_RULES
+    rules = ALL_RULES if pro else FREE_RULES
+
+    if not pro:
+        hidden = len(ALL_RULES) - len(FREE_RULES)
+        console.print(
+            f"[dim]Free tier: scanning with CRITICAL and HIGH rules only "
+            f"({hidden} MEDIUM/LOW rules hidden). "
+            f"Upgrade at helmgate.io/pricing[/dim]\n"
+        )
+
+    findings = scan(chart, rules=rules)
+
+    if output == "json":
+        import json
+        data = [
+            {
+                "rule_id": f.rule_id,
+                "severity": f.severity.value,
+                "path": f.path,
+                "message": f.message,
+                "hint": f.line_hint,
+            }
+            for f in findings
+        ]
+        print(json.dumps(data, indent=2))
+    else:
+        print_report(findings, str(chart))
+
+    if not pro and findings:
+        console.print(
+            "\n[dim]Upgrade to Pro to scan with all rules and export JSON reports.[/dim]"
+        )
+
+    if fail_on != "NONE":
+        from .rules import Severity
+        try:
+            threshold = Severity(fail_on)
+        except ValueError:
+            console.print(f"[red]Unknown severity:[/red] {fail_on}")
+            raise typer.Exit(1)
+
+        severity_order = list(Severity)
+        threshold_idx = severity_order.index(threshold)
+        should_fail = any(
+            severity_order.index(f.severity) <= threshold_idx for f in findings
+        )
+        if should_fail:
+            raise typer.Exit(1)
+
+
+@app.command()
+def activate(
+    key: str = typer.Argument(..., help="Your Pro license key (format: HGATE-XXXX-XXXX-XXXX-XXXX)"),
+):
+    """Activate a Pro license key."""
+    if activate_license(key):
+        console.print(f"[green]License activated![/green] helmgate Pro is now enabled.")
+    else:
+        console.print(
+            "[red]Invalid license key.[/red] "
+            "Check the key and try again, or visit helmgate.io/pricing"
+        )
+        raise typer.Exit(1)
+
+
+@app.command()
+def version():
+    """Show helmgate version."""
+    tier = "Pro" if is_pro() else "Free"
+    console.print(f"helmgate v{__version__} [{tier}]")
+
+
+if __name__ == "__main__":
+    app()

helmgate-0.1.0/helmgate/license.py

@@ -0,0 +1,57 @@
+import base64
+import os
+import re
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.exceptions import InvalidSignature
+
+_LICENSE_FILE = Path.home() / ".helmgate" / "license"
+_KEY_PATTERN = re.compile(r"^HGATE-[A-Za-z0-9_-]{10,}$")
+
+# Public key only — safe to ship in open source.
+_PUBLIC_KEY_PEM = b"""-----BEGIN PUBLIC KEY-----
+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEw1VD4zF0z2qMQTMmrVh3ViG2xiKt
+dC3SHCrI1smn1dQWAvyg/tHWio97q/W2TXwMTvZm9JP6C4SO15b+IsD6cw==
+-----END PUBLIC KEY-----"""
+
+_public_key = serialization.load_pem_public_key(_PUBLIC_KEY_PEM)
+
+
+def validate_key(key: str) -> bool:
+    """Return True if the key has a valid ECDSA signature."""
+    if not _KEY_PATTERN.match(key):
+        return False
+    try:
+        payload = base64.urlsafe_b64decode(key[6:] + "==")  # strip "HGATE-"
+        nonce, signature = payload[:8], payload[8:]
+        _public_key.verify(signature, nonce, ec.ECDSA(hashes.SHA256()))
+        return True
+    except (InvalidSignature, Exception):
+        return False
+
+
+def get_license_key() -> str | None:
+    """Return the license key from env var or license file, or None if not set."""
+    key = os.environ.get("HELMGATE_LICENSE_KEY", "").strip()
+    if key:
+        return key
+    if _LICENSE_FILE.exists():
+        return _LICENSE_FILE.read_text().strip()
+    return None
+
+
+def is_pro() -> bool:
+    """Return True if a valid Pro license key is present."""
+    key = get_license_key()
+    return key is not None and validate_key(key)
+
+
+def activate(key: str) -> bool:
+    """Save a valid license key to the license file. Returns True on success."""
+    if not validate_key(key):
+        return False
+    _LICENSE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _LICENSE_FILE.write_text(key)
+    return True

helmgate-0.1.0/helmgate/report.py

@@ -0,0 +1,55 @@
+from rich.console import Console
+from rich.table import Table
+from rich import box
+from .rules import Finding, Severity
+
+console = Console()
+
+_SEVERITY_COLOR = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "red",
+    Severity.MEDIUM: "yellow",
+    Severity.LOW: "cyan",
+    Severity.INFO: "dim",
+}
+
+
+def print_report(findings: list[Finding], chart_path: str) -> None:
+    if not findings:
+        console.print(f"\n[bold green]✓ No issues found in {chart_path}[/bold green]\n")
+        return
+
+    table = Table(box=box.ROUNDED, show_lines=True)
+    table.add_column("ID", style="bold", no_wrap=True)
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("File", style="dim")
+    table.add_column("Message")
+    table.add_column("Hint", style="dim")
+
+    for f in sorted(findings, key=lambda x: list(Severity).index(x.severity)):
+        color = _SEVERITY_COLOR[f.severity]
+        table.add_row(
+            f.rule_id,
+            f"[{color}]{f.severity.value}[/{color}]",
+            f.path,
+            f.message,
+            f.line_hint,
+        )
+
+    console.print()
+    console.print(table)
+    _print_summary(findings)
+
+
+def _print_summary(findings: list[Finding]) -> None:
+    counts: dict[Severity, int] = {}
+    for f in findings:
+        counts[f.severity] = counts.get(f.severity, 0) + 1
+
+    parts = []
+    for sev in Severity:
+        if sev in counts:
+            color = _SEVERITY_COLOR[sev]
+            parts.append(f"[{color}]{counts[sev]} {sev.value}[/{color}]")
+
+    console.print(f"  Found {len(findings)} issue(s): " + "  ".join(parts) + "\n")

helmgate-0.1.0/helmgate/rules/__init__.py

@@ -0,0 +1,10 @@
+from .base import Rule, Severity, Finding
+from .security import SECURITY_RULES
+from .best_practices import BEST_PRACTICE_RULES
+
+ALL_RULES: list[Rule] = SECURITY_RULES + BEST_PRACTICE_RULES
+
+FREE_SEVERITIES = {Severity.CRITICAL, Severity.HIGH}
+FREE_RULES: list[Rule] = [r for r in ALL_RULES if r.severity in FREE_SEVERITIES]
+
+__all__ = ["Rule", "Severity", "Finding", "ALL_RULES", "FREE_RULES"]

helmgate-0.1.0/helmgate/rules/base.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class Severity(str, Enum):
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    INFO = "INFO"
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    severity: Severity
+    message: str
+    path: str  # e.g. "templates/deployment.yaml"
+    line_hint: str = ""  # human-readable context, not exact line number
+
+
+@dataclass
+class Rule:
+    id: str
+    name: str
+    severity: Severity
+    description: str
+
+    def check(self, manifest: dict[str, Any], path: str) -> list[Finding]:
+        """Run rule against a single parsed YAML manifest. Override in subclasses."""
+        raise NotImplementedError