shieldctl 0.1.0__py3-none-any.whl

shieldctl/cli.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from .config import load_config
+from .dispatcher import run_scan
+from .models import Severity
+
+app = typer.Typer(
+    name="shieldctl",
+    help="Infrastructure security scanner for Terraform, shell, YAML, Dockerfiles, and Python.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+class OutputFormat(str, Enum):
+    terminal = "terminal"
+    json = "json"
+    html = "html"
+
+
+class FailOn(str, Enum):
+    INFO = "INFO"
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+
+@app.command()
+def scan(
+    path: Path = typer.Argument(Path("."), help="Path to scan"),
+    fail_on: FailOn = typer.Option(
+        None,
+        "--fail-on",
+        help="Minimum severity that causes a non-zero exit. Overrides .shieldctl.yaml.",
+    ),
+    format: OutputFormat = typer.Option(OutputFormat.terminal, "--format", "-f"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Write report to file"),
+    changed_only: bool = typer.Option(
+        False, "--changed-only", help="Only scan files changed vs git HEAD / main"
+    ),
+    scanner: Optional[str] = typer.Option(
+        None, "--scanner", help="Run a single scanner by name (e.g. terraform, bash)"
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Fail immediately if a required scanner tool is not installed.",
+    ),
+) -> None:
+    root = path.resolve()
+    if not root.exists():
+        typer.echo(f"Error: path '{root}' does not exist", err=True)
+        raise typer.Exit(1)
+
+    config = load_config(root)
+    if fail_on is not None:
+        config.fail_on = Severity.from_str(fail_on.value)
+
+    from .scanners.base import ScannerError
+    try:
+        findings = run_scan(
+            root, config,
+            changed_only=changed_only,
+            scanner_filter=scanner,
+            strict=strict,
+        )
+    except ScannerError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(4)
+
+    # Select reporter
+    if format == OutputFormat.terminal:
+        from .reporters.terminal import TerminalReporter
+        reporter = TerminalReporter()
+    elif format == OutputFormat.json:
+        from .reporters.json_reporter import JsonReporter
+        reporter = JsonReporter()
+    else:
+        from .reporters.html_reporter import HtmlReporter
+        reporter = HtmlReporter()
+
+    content = reporter.render(findings)
+
+    if output:
+        output.write_text(content)
+        typer.echo(f"Report written to {output}")
+    elif format != OutputFormat.terminal:
+        typer.echo(content)
+    # terminal reporter prints directly to stdout via rich
+
+    # Exit code based on highest severity found
+    if not findings:
+        raise typer.Exit(0)
+
+    max_sev = max(f.severity for f in findings)
+    if max_sev >= config.fail_on:
+        raise typer.Exit(3)
+    elif max_sev >= Severity.MEDIUM:
+        raise typer.Exit(2)
+    else:
+        raise typer.Exit(1)
+
+
+@app.command("install-tools")
+def install_tools(
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would be installed without doing it."
+    ),
+) -> None:
+    """Install all scanner dependencies (checkov, tfsec, shellcheck, etc.)."""
+    from rich.console import Console
+    from rich.table import Table
+    from rich import box
+    from .install import install_all
+
+    con = Console()
+    con.print("\n[bold]Installing shieldctl scanner dependencies…[/bold]\n")
+
+    results = install_all(dry_run=dry_run)
+
+    table = Table(box=box.SIMPLE_HEAD)
+    table.add_column("Tool", width=14)
+    table.add_column("Status", width=10)
+    table.add_column("Note")
+
+    status_style = {"ok": "green", "skipped": "dim", "failed": "red"}
+    failed = []
+    for r in results:
+        style = status_style.get(r.status, "")
+        table.add_row(r.tool, f"[{style}]{r.status}[/{style}]", r.note)
+        if r.status == "failed":
+            failed.append(r.tool)
+
+    con.print(table)
+
+    if failed:
+        con.print(f"\n[red]Failed to install: {', '.join(failed)}[/red]")
+        con.print("Install them manually — see each tool's documentation.")
+        raise typer.Exit(1)
+    else:
+        con.print("[green]All tools ready.[/green]\n")
+
+
+@app.command(hidden=True)
+def version() -> None:
+    """Print version."""
+    typer.echo("shieldctl 0.1.0")

shieldctl/config.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .models import Severity
+
+_DEFAULTS = {
+    "fail_on": "HIGH",
+    "exclude_paths": [
+        "**/.terraform/**",
+        "**/.terragrunt-cache/**",
+        "**/node_modules/**",
+        "**/.git/**",
+    ],
+    "suppress": [],
+}
+
+
+@dataclass
+class Suppression:
+    rule: str
+    reason: str = ""
+
+
+@dataclass
+class ShieldConfig:
+    fail_on: Severity
+    exclude_paths: list[str]
+    suppress: list[Suppression]
+
+    def is_suppressed(self, rule: str) -> bool:
+        return any(s.rule == rule for s in self.suppress)
+
+
+def load_config(path: Path) -> ShieldConfig:
+    raw = dict(_DEFAULTS)
+    config_file = path / ".shieldctl.yaml"
+    if config_file.exists():
+        try:
+            with config_file.open() as f:
+                override = yaml.safe_load(f) or {}
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid .shieldctl.yaml: {e}")
+        raw.update(override)
+
+    suppressions = [
+        Suppression(rule=s["rule"], reason=s.get("reason", ""))
+        for s in raw.get("suppress", [])
+        if s.get("rule")
+    ]
+
+    return ShieldConfig(
+        fail_on=Severity.from_str(raw["fail_on"]),
+        exclude_paths=raw["exclude_paths"],
+        suppress=suppressions,
+    )

shieldctl/dispatcher.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import dataclasses
+import fnmatch
+import subprocess
+from pathlib import Path
+
+from .config import ShieldConfig
+from .models import Finding
+from .scanners.base import BaseScanner, ScannerError
+from .scanners.terraform import TerraformScanner
+from .scanners.secrets import SecretsScanner
+from .scanners.bash import BashScanner
+from .scanners.yaml_scanner import YamlScanner
+from .scanners.dockerfile import DockerfileScanner
+from .scanners.python_scanner import PythonScanner
+from .scanners.kubernetes import KubernetesScanner
+from .scanners.gha import GhaScanner
+from .scanners.pip_audit import PipAuditScanner
+
+import rich.console
+
+console = rich.console.Console(stderr=True)
+
+_ALL_SCANNERS: list[BaseScanner] = [
+    TerraformScanner(),
+    SecretsScanner(),
+    BashScanner(),
+    YamlScanner(),
+    DockerfileScanner(),
+    PythonScanner(),
+    KubernetesScanner(),
+    GhaScanner(),
+    PipAuditScanner(),
+]
+
+
+def _is_excluded(path: Path, root: Path, patterns: list[str]) -> bool:
+    try:
+        rel = path.relative_to(root)
+    except ValueError:
+        return False
+    rel_str = str(rel)
+    parts = rel.parts
+    for pat in patterns:
+        if fnmatch.fnmatch(rel_str, pat):
+            return True
+        # Handle ** glob patterns: extract non-wildcard segments and check
+        # that each one matches at least one actual path component.
+        # e.g. "**/.terraform/**" → segment ".terraform" must appear in parts.
+        if "**" in pat:
+            segments = [s for s in pat.replace("\\", "/").split("/")
+                        if s and s != "**"]
+            if segments and all(
+                any(fnmatch.fnmatch(part, seg) for part in parts)
+                for seg in segments
+            ):
+                return True
+    return False
+
+
+def _changed_files(root: Path) -> list[Path]:
+    result = subprocess.run(
+        ["git", "diff", "--name-only", "HEAD"],
+        capture_output=True,
+        text=True,
+        cwd=root,
+    )
+    if result.returncode != 0:
+        # Fall back to diff against main/master
+        for base in ("main", "master", "origin/main", "origin/master"):
+            result = subprocess.run(
+                ["git", "diff", "--name-only", base],
+                capture_output=True,
+                text=True,
+                cwd=root,
+            )
+            if result.returncode == 0:
+                break
+    files = [root / f.strip() for f in result.stdout.splitlines() if f.strip()]
+    return [f for f in files if f.exists()]
+
+
+def run_scan(
+    root: Path,
+    config: ShieldConfig,
+    changed_only: bool = False,
+    scanner_filter: str | None = None,
+    strict: bool = False,
+) -> list[Finding]:
+    if changed_only:
+        all_files = _changed_files(root)
+        console.print(f"[dim]--changed-only: {len(all_files)} file(s) in scope[/dim]")
+    else:
+        all_files = [
+            p for p in root.rglob("*")
+            if p.is_file() and not _is_excluded(p, root, config.exclude_paths)
+        ]
+
+    scanners = _ALL_SCANNERS
+    if scanner_filter:
+        name = scanner_filter.lower()
+        # Match by class name prefix (e.g. "terraform" matches TerraformScanner)
+        scanners = [s for s in scanners if type(s).__name__.lower().startswith(name)]
+        if not scanners:
+            console.print(f"[yellow]No scanner matches '{scanner_filter}'[/yellow]")
+            return []
+
+    findings: list[Finding] = []
+    seen: set[tuple] = set()
+
+    for scanner in scanners:
+        if not scanner.available():
+            tool = scanner._primary_tool() or type(scanner).__name__
+            if strict:
+                console.print(
+                    f"[bold red]--strict: tool '{tool}' not found. "
+                    f"Run 'shieldctl install-tools' to install all dependencies.[/bold red]"
+                )
+                raise ScannerError(f"Required tool '{tool}' not found (--strict mode).")
+            console.print(
+                f"[dim]Skipping {type(scanner).__name__} ({tool} not found)[/dim]"
+            )
+            continue
+
+        if scanner.extensions:
+            targets = [
+                f for f in all_files
+                if f.suffix in scanner.extensions
+                or f.name in scanner.extensions
+                or any(f.name.startswith(e.lstrip("*")) for e in scanner.extensions if "*" in e)
+            ]
+            if not targets:
+                continue
+        else:
+            # Repo-wide scanner — pass root
+            targets = [root]
+
+        label = scanner._primary_tool() or type(scanner).__name__
+        if len(targets) == 1:
+            t = targets[0]
+            target_summary = t.name if t.is_file() else f"{t.name}/"
+        else:
+            target_summary = f"{len(targets)} files"
+        console.print(f"[dim]→ {label}  {target_summary}[/dim]")
+
+        try:
+            raw = scanner.run(targets)
+        except ScannerError as e:
+            console.print(f"[red]Scanner error:[/red] {e}")
+            continue
+
+        for f in raw:
+            # Drop findings in remote/downloaded modules — not actionable
+            if f.file.startswith("git::"):
+                continue
+            if config.is_suppressed(f.rule):
+                continue
+            # Normalize to path relative to scan root
+            try:
+                rel = str(Path(f.file).relative_to(root))
+                f = dataclasses.replace(f, file=rel)
+            except ValueError:
+                pass  # file not under root — leave as-is
+            key = f.dedup_key()
+            if key not in seen:
+                seen.add(key)
+                findings.append(f)
+
+    return findings

shieldctl/install.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import stat
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+console = Console()
+
+# Python tools installed via the same pip that installed shieldctl
+_PIP_TOOLS: dict[str, str] = {
+    "checkov": "checkov",
+    "yamllint": "yamllint",
+    "bandit": "bandit",
+    "safety": "safety",
+}
+
+# Brew package name for each binary tool (macOS)
+_BREW_PACKAGES: dict[str, str] = {
+    "tfsec": "tfsec",
+    "shellcheck": "shellcheck",
+    "hadolint": "hadolint",
+    "gitleaks": "gitleaks",
+}
+
+# GitHub release asset patterns per tool and arch (Linux)
+# {ver} is replaced with the tag version (without leading 'v' where noted)
+_GITHUB_ASSETS: dict[str, dict] = {
+    "tfsec": {
+        "repo": "aquasecurity/tfsec",
+        "amd64": "tfsec-linux-amd64",
+        "arm64": "tfsec-linux-arm64",
+        "extract": False,
+    },
+    "shellcheck": {
+        "repo": "koalaman/shellcheck",
+        "amd64": "shellcheck-{vtag}.linux.x86_64.tar.xz",
+        "arm64": "shellcheck-{vtag}.linux.aarch64.tar.xz",
+        "extract": True,
+        "binary_in_archive": "shellcheck-{vtag}/shellcheck",
+    },
+    "hadolint": {
+        "repo": "hadolint/hadolint",
+        "amd64": "hadolint-Linux-x86_64",
+        "arm64": "hadolint-Linux-arm64",
+        "extract": False,
+    },
+    "gitleaks": {
+        "repo": "gitleaks/gitleaks",
+        "amd64": "gitleaks_{ver}_linux_x64.tar.gz",
+        "arm64": "gitleaks_{ver}_linux_arm64.tar.gz",
+        "extract": True,
+        "binary_in_archive": "gitleaks",
+    },
+}
+
+
+@dataclass
+class InstallResult:
+    tool: str
+    status: str   # "ok", "skipped", "failed"
+    note: str = ""
+
+
+def _arch() -> str:
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        return "amd64"
+    if machine in ("aarch64", "arm64"):
+        return "arm64"
+    return machine
+
+
+def _pip_executable() -> str:
+    # Use the pip that belongs to the current Python (same venv as shieldctl)
+    return str(Path(sys.executable).parent / "pip")
+
+
+def _install_bin_dir() -> Path:
+    """Return a writable directory on PATH for binary installs."""
+    for candidate in ("/usr/local/bin", str(Path.home() / ".local" / "bin")):
+        p = Path(candidate)
+        try:
+            p.mkdir(parents=True, exist_ok=True)
+            # Check writability
+            test = p / ".shieldctl_write_test"
+            test.touch()
+            test.unlink()
+            return p
+        except (PermissionError, OSError):
+            continue
+    raise RuntimeError(
+        "No writable bin directory found. "
+        "Try running with sudo or add ~/.local/bin to your PATH."
+    )
+
+
+def _latest_github_release(repo: str) -> str:
+    url = f"https://api.github.com/repos/{repo}/releases/latest"
+    req = urllib.request.Request(url, headers={"User-Agent": "shieldctl"})
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        import json
+        data = json.load(resp)
+    return data["tag_name"]  # e.g. "v1.2.3"
+
+
+def _download(url: str, dest: Path) -> None:
+    req = urllib.request.Request(url, headers={"User-Agent": "shieldctl"})
+    with urllib.request.urlopen(req, timeout=60) as resp, dest.open("wb") as f:
+        while chunk := resp.read(65536):
+            f.write(chunk)
+
+
+def _install_github_binary(tool: str, dry_run: bool) -> InstallResult:
+    spec = _GITHUB_ASSETS[tool]
+    arch = _arch()
+    if arch not in ("amd64", "arm64"):
+        return InstallResult(tool, "failed", f"Unsupported architecture: {arch}")
+
+    try:
+        vtag = _latest_github_release(spec["repo"])
+    except Exception as e:
+        return InstallResult(tool, "failed", f"Could not fetch latest release: {e}")
+
+    ver = vtag.lstrip("v")
+    asset_name = spec[arch].format(vtag=vtag, ver=ver)
+    download_url = f"https://github.com/{spec['repo']}/releases/download/{vtag}/{asset_name}"
+
+    if dry_run:
+        return InstallResult(tool, "ok", f"would download {download_url}")
+
+    try:
+        bin_dir = _install_bin_dir()
+    except RuntimeError as e:
+        return InstallResult(tool, "failed", str(e))
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp = Path(tmpdir)
+        download_path = tmp / asset_name
+        try:
+            _download(download_url, download_path)
+        except Exception as e:
+            return InstallResult(tool, "failed", f"Download failed: {e}")
+
+        dest = bin_dir / tool
+
+        if spec.get("extract"):
+            archive_member = spec.get("binary_in_archive", tool).format(vtag=vtag, ver=ver)
+            try:
+                if asset_name.endswith(".tar.xz") or asset_name.endswith(".tar.gz"):
+                    with tarfile.open(download_path) as tf:
+                        member = tf.getmember(archive_member)
+                        extracted = tf.extractfile(member)
+                        if extracted:
+                            dest.write_bytes(extracted.read())
+                else:
+                    return InstallResult(tool, "failed", f"Unknown archive format: {asset_name}")
+            except Exception as e:
+                return InstallResult(tool, "failed", f"Extraction failed: {e}")
+        else:
+            shutil.copy2(download_path, dest)
+
+        dest.chmod(dest.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+    return InstallResult(tool, "ok", f"installed to {bin_dir / tool}")
+
+
+def _install_via_brew(tool: str, pkg: str, dry_run: bool) -> InstallResult:
+    if not shutil.which("brew"):
+        return InstallResult(tool, "failed", "brew not found")
+    if dry_run:
+        return InstallResult(tool, "ok", f"would run: brew install {pkg}")
+    result = subprocess.run(["brew", "install", pkg], capture_output=True, text=True)
+    if result.returncode != 0:
+        lines = result.stderr.strip().splitlines()
+        return InstallResult(tool, "failed", lines[-1] if lines else "brew error")
+    return InstallResult(tool, "ok", f"brew install {pkg}")
+
+
+def _install_via_pip(tool: str, pkg: str, dry_run: bool) -> InstallResult:
+    pip = _pip_executable()
+    if dry_run:
+        return InstallResult(tool, "ok", f"would run: pip install {pkg}")
+    result = subprocess.run([pip, "install", "--quiet", pkg], capture_output=True, text=True)
+    if result.returncode != 0:
+        lines = result.stderr.strip().splitlines()
+        return InstallResult(tool, "failed", lines[-1] if lines else "pip error")
+    return InstallResult(tool, "ok", f"pip install {pkg}")
+
+
+def install_all(dry_run: bool = False) -> list[InstallResult]:
+    is_macos = platform.system() == "Darwin"
+    results: list[InstallResult] = []
+
+    # Python tools — always via pip
+    for tool, pkg in _PIP_TOOLS.items():
+        if shutil.which(tool):
+            results.append(InstallResult(tool, "skipped", "already installed"))
+            continue
+        console.print(f"  Installing [bold]{tool}[/bold] via pip...")
+        results.append(_install_via_pip(tool, pkg, dry_run))
+
+    # Binary tools
+    for tool in _GITHUB_ASSETS:
+        if shutil.which(tool):
+            results.append(InstallResult(tool, "skipped", "already installed"))
+            continue
+        console.print(f"  Installing [bold]{tool}[/bold]...")
+        if is_macos:
+            results.append(_install_via_brew(tool, _BREW_PACKAGES[tool], dry_run))
+        else:
+            results.append(_install_github_binary(tool, dry_run))
+
+    return results

shieldctl/models.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class Severity(IntEnum):
+    INFO = 0
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+    @classmethod
+    def from_str(cls, value: str) -> "Severity":
+        try:
+            return cls[value.upper()]
+        except KeyError:
+            valid = ", ".join(m.name for m in cls)
+            raise ValueError(f"Invalid severity '{value}'. Valid values: {valid}")
+
+    def label(self) -> str:
+        return self.name
+
+
+@dataclass
+class Finding:
+    file: str
+    line: int | None
+    rule: str
+    severity: Severity
+    message: str
+    remediation: str
+    scanner: str
+    owasp: str | None = field(default=None)
+
+    def dedup_key(self) -> tuple:
+        return (self.file, self.line, self.rule, self.scanner)