controlgate 0.1.0__py3-none-any.whl

controlgate/__init__.py

@@ -0,0 +1,3 @@
+"""ControlGate — NIST RMF Cloud Security Hardening Compliance Gate."""
+
+__version__ = "0.1.0"

controlgate/__main__.py

@@ -0,0 +1,297 @@
+"""ControlGate CLI entry point.
+
+Usage:
+    controlgate scan [--config PATH] [--format json|markdown|sarif] [--baseline low|moderate|high]
+    controlgate scan --diff-file PATH  # scan a saved diff file
+    python -m controlgate scan [options]
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from controlgate.catalog import CatalogIndex
+from controlgate.config import ControlGateConfig
+from controlgate.diff_parser import parse_diff
+from controlgate.engine import ControlGateEngine
+from controlgate.models import Action
+from controlgate.reporters.json_reporter import JSONReporter
+from controlgate.reporters.markdown_reporter import MarkdownReporter
+from controlgate.reporters.sarif_reporter import SARIFReporter
+
+
+def _get_diff(mode: str, target_branch: str = "main") -> str:
+    """Get diff text from git.
+
+    Args:
+        mode: 'pre-commit' for staged changes, 'pr' for branch diff.
+        target_branch: Target branch for PR mode diff.
+
+    Returns:
+        The unified diff text.
+    """
+    if mode == "pre-commit":
+        cmd = ["git", "diff", "--cached", "--unified=3"]
+    else:
+        cmd = ["git", "diff", f"{target_branch}...HEAD", "--unified=3"]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        return result.stdout
+    except subprocess.CalledProcessError as e:
+        print(f"Error running git diff: {e.stderr}", file=sys.stderr)
+        sys.exit(1)
+    except FileNotFoundError:
+        print("Error: git is not installed or not in PATH", file=sys.stderr)
+        sys.exit(1)
+
+
+def _resolve_catalog_path(config: ControlGateConfig) -> Path:
+    """Resolve the catalog path, auto-downloading if needed.
+
+    Search order:
+    1. Bundled/cached catalog in the package data dir
+    2. Explicit path from config
+    3. Relative to current directory or git root
+    4. Auto-download from GitHub (NCSB repository)
+    """
+    from controlgate.catalog_downloader import get_catalog_path
+
+    # 1. Check bundled/cached catalog (auto-downloads if missing)
+    try:
+        return get_catalog_path()
+    except ConnectionError:
+        pass  # Fall through to config-based resolution
+
+    # 2. Explicit config path (absolute)
+    catalog_path = Path(config.catalog_path)
+    if catalog_path.is_absolute() and catalog_path.exists():
+        return catalog_path
+
+    # 3. Relative to current directory
+    if catalog_path.exists():
+        return catalog_path
+
+    # 4. Relative to git project root
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        project_root = Path(result.stdout.strip())
+        resolved = project_root / catalog_path
+        if resolved.exists():
+            return resolved
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    print(
+        "Error: catalog file not found and download failed.\n"
+        "Run 'controlgate update-catalog' or set 'catalog' in .controlgate.yml.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def scan_command(args: argparse.Namespace) -> int:
+    """Execute the scan command."""
+    # Load config
+    config = ControlGateConfig.load(args.config)
+    if args.baseline:
+        config.baseline = args.baseline
+
+    # Resolve and load catalog
+    catalog_path = _resolve_catalog_path(config)
+    catalog = CatalogIndex(catalog_path)
+    print(f"📚 Loaded catalog: {catalog.count} controls", file=sys.stderr)
+
+    # Get diff
+    if args.diff_file:
+        diff_text = Path(args.diff_file).read_text(encoding="utf-8")
+    else:
+        diff_text = _get_diff(args.mode, args.target_branch)
+
+    if not diff_text.strip():
+        print("ℹ️  No changes to scan.", file=sys.stderr)
+        return 0
+
+    diff_files = parse_diff(diff_text)
+    print(
+        f"📄 Scanning {len(diff_files)} changed file(s)...",
+        file=sys.stderr,
+    )
+
+    # Run engine
+    engine = ControlGateEngine(config, catalog)
+    verdict = engine.scan(diff_files)
+
+    # Determine output format(s)
+    formats = args.format if args.format else config.report_formats
+
+    # Output reports
+    for fmt in formats:
+        if fmt == "json":
+            json_reporter = JSONReporter()
+            print(json_reporter.render(verdict))
+        elif fmt == "markdown":
+            md_reporter = MarkdownReporter()
+            print(md_reporter.render(verdict))
+        elif fmt == "sarif":
+            sarif_reporter = SARIFReporter()
+            print(sarif_reporter.render(verdict))
+
+    # Write to output dir if configured
+    if args.output_dir or config.output_dir:
+        output_dir = args.output_dir or config.output_dir
+        for fmt in formats:
+            if fmt == "json":
+                JSONReporter().write(verdict, f"{output_dir}/verdict.json")
+            elif fmt == "markdown":
+                MarkdownReporter().write(verdict, f"{output_dir}/verdict.md")
+            elif fmt == "sarif":
+                SARIFReporter().write(verdict, f"{output_dir}/verdict.sarif")
+        print(f"📁 Reports written to {output_dir}/", file=sys.stderr)
+
+    # Print summary to stderr
+    emoji = {"BLOCK": "🚫", "WARN": "⚠️", "PASS": "✅"}.get(verdict.verdict, "❓")
+    print(
+        f"\n{emoji} Verdict: {verdict.verdict} — {verdict.summary}",
+        file=sys.stderr,
+    )
+
+    # Exit code
+    if verdict.verdict == Action.BLOCK.value:
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="controlgate",
+        description="ControlGate — NIST RMF Cloud Security Hardening Compliance Gate",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # scan subcommand
+    scan_parser = subparsers.add_parser("scan", help="Scan code changes for security compliance")
+    scan_parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Path to .controlgate.yml config file",
+    )
+    scan_parser.add_argument(
+        "--format",
+        type=str,
+        nargs="+",
+        choices=["json", "markdown", "sarif"],
+        default=None,
+        help="Output format(s)",
+    )
+    scan_parser.add_argument(
+        "--baseline",
+        type=str,
+        choices=["low", "moderate", "high"],
+        default=None,
+        help="Target NIST baseline level",
+    )
+    scan_parser.add_argument(
+        "--mode",
+        type=str,
+        choices=["pre-commit", "pr"],
+        default="pre-commit",
+        help="Scan mode: pre-commit (staged) or pr (branch diff)",
+    )
+    scan_parser.add_argument(
+        "--target-branch",
+        type=str,
+        default="main",
+        help="Target branch for PR mode diff (default: main)",
+    )
+    scan_parser.add_argument(
+        "--diff-file",
+        type=str,
+        default=None,
+        help="Path to a saved diff file to scan (instead of git diff)",
+    )
+    scan_parser.add_argument(
+        "--output-dir",
+        type=str,
+        default=None,
+        help="Directory to write report files to",
+    )
+
+    # update-catalog subcommand
+    subparsers.add_parser(
+        "update-catalog",
+        help="Download the latest NIST catalog from NCSB",
+    )
+
+    # catalog-info subcommand
+    subparsers.add_parser(
+        "catalog-info",
+        help="Show information about the current catalog",
+    )
+
+    return parser
+
+
+def update_catalog_command() -> int:
+    """Download the latest catalog from GitHub."""
+    from controlgate.catalog_downloader import download_catalog
+
+    try:
+        path = download_catalog()
+        print(f"📦 Catalog saved to: {path}", file=sys.stderr)
+        return 0
+    except ConnectionError as e:
+        print(f"❌ {e}", file=sys.stderr)
+        return 1
+
+
+def catalog_info_command() -> int:
+    """Show info about the current catalog."""
+    from controlgate.catalog_downloader import catalog_info, get_catalog_path
+
+    try:
+        path = get_catalog_path()
+    except ConnectionError:
+        print("❌ No catalog available. Run 'controlgate update-catalog'.", file=sys.stderr)
+        return 1
+
+    info = catalog_info(path)
+    print("📚 NIST Catalog Info:")
+    print(f"   Project:    {info['project']}")
+    print(f"   Version:    {info['version']}")
+    print(f"   Framework:  {info['framework']}")
+    print(f"   Controls:   {info['control_count']}")
+    print(f"   Generated:  {info['generated_at']}")
+    print(f"   Path:       {info['path']}")
+    return 0
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "scan":
+        exit_code = scan_command(args)
+        sys.exit(exit_code)
+    elif args.command == "update-catalog":
+        sys.exit(update_catalog_command())
+    elif args.command == "catalog-info":
+        sys.exit(catalog_info_command())
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

controlgate/catalog.py

@@ -0,0 +1,115 @@
+"""NIST 800-53 Rev. 5 enriched catalog loader and query API."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from controlgate.models import Control
+
+# Mapping of gate names to the NIST control IDs they cover.
+GATE_CONTROL_MAP: dict[str, list[str]] = {
+    "secrets": ["IA-5", "IA-6", "SC-12", "SC-28"],
+    "crypto": ["SC-8", "SC-13", "SC-17", "SC-23"],
+    "iam": ["AC-3", "AC-4", "AC-5", "AC-6"],
+    "sbom": ["SR-3", "SR-11", "SA-10", "SA-11"],
+    "iac": ["CM-2", "CM-6", "CM-7", "SC-7"],
+    "input_validation": ["SI-7", "SI-10", "SI-11", "SI-16"],
+    "audit": ["AU-2", "AU-3", "AU-12"],
+    "change_control": ["CM-3", "CM-4", "CM-5"],
+}
+
+
+class CatalogIndex:
+    """Queryable index over the enriched NIST 800-53 R5 catalog.
+
+    Loads the JSON catalog file and builds in-memory indexes for fast lookups
+    by control_id, family, severity, and gate.
+    """
+
+    def __init__(self, catalog_path: str | Path) -> None:
+        self._controls: list[Control] = []
+        self._by_id: dict[str, Control] = {}
+        self._by_family: dict[str, list[Control]] = {}
+        self._by_severity: dict[str, list[Control]] = {}
+        self._load(catalog_path)
+
+    def _load(self, catalog_path: str | Path) -> None:
+        """Load the enriched catalog JSON and build indexes."""
+        path = Path(catalog_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Catalog file not found: {path}")
+
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+
+        controls_data = data.get("controls", [])
+        for entry in controls_data:
+            control = Control.from_dict(entry)
+            self._controls.append(control)
+            self._by_id[control.control_id] = control
+
+            # Index by family
+            family = control.family
+            if family not in self._by_family:
+                self._by_family[family] = []
+            self._by_family[family].append(control)
+
+            # Index by severity
+            severity = control.severity
+            if severity not in self._by_severity:
+                self._by_severity[severity] = []
+            self._by_severity[severity].append(control)
+
+    @property
+    def count(self) -> int:
+        """Total number of controls in the catalog."""
+        return len(self._controls)
+
+    def by_id(self, control_id: str) -> Control | None:
+        """Look up a single control by its ID (e.g. 'AC-3')."""
+        return self._by_id.get(control_id)
+
+    def by_family(self, family: str) -> list[Control]:
+        """Get all controls in a family (e.g. 'AC', 'SC')."""
+        return self._by_family.get(family, [])
+
+    def by_severity(self, severity: str) -> list[Control]:
+        """Get all controls at a given severity level."""
+        return self._by_severity.get(severity, [])
+
+    def non_negotiable(self) -> list[Control]:
+        """Get all controls marked as non-negotiable."""
+        return [c for c in self._controls if c.non_negotiable]
+
+    def for_gate(self, gate_name: str) -> list[Control]:
+        """Get the controls mapped to a specific security gate.
+
+        Args:
+            gate_name: One of 'secrets', 'crypto', 'iam', 'sbom',
+                       'iac', 'input_validation', 'audit', 'change_control'.
+        """
+        control_ids = GATE_CONTROL_MAP.get(gate_name, [])
+        controls = []
+        for cid in control_ids:
+            ctrl = self._by_id.get(cid)
+            if ctrl:
+                controls.append(ctrl)
+        return controls
+
+    def related_to(self, control_id: str) -> list[Control]:
+        """Get controls related to a given control ID."""
+        control = self._by_id.get(control_id)
+        if not control or not control.related_controls:
+            return []
+
+        related = []
+        # related_controls is a comma-separated string like "IA-1, PM-9, PS-8."
+        raw = control.related_controls.strip().rstrip(".")
+        if raw == "[None]":
+            return []
+        for ref in raw.split(","):
+            ref = ref.strip()
+            if ref and ref in self._by_id:
+                related.append(self._by_id[ref])
+        return related

controlgate/catalog_downloader.py

@@ -0,0 +1,103 @@
+"""Dynamic catalog downloader for ControlGate.
+
+Downloads the latest NIST 800-53 R5 enriched catalog from the
+NIST Cloud Security Baseline (NCSB) GitHub repository.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+# Source of truth for the enriched catalog
+CATALOG_REPO = "sadayamuthu/nist-cloud-security-baseline"
+CATALOG_BRANCH = "main"
+CATALOG_PATH = "baseline/nist80053r5_full_catalog_enriched.json"
+CATALOG_URL = f"https://raw.githubusercontent.com/{CATALOG_REPO}/{CATALOG_BRANCH}/{CATALOG_PATH}"
+
+# Where to cache the downloaded catalog
+_PACKAGE_DATA_DIR = Path(__file__).resolve().parent / "data"
+_CATALOG_FILENAME = "nist80053r5_full_catalog_enriched.json"
+
+
+def get_catalog_path() -> Path:
+    """Get the path to the catalog, downloading if needed.
+
+    Returns the path to the catalog JSON file. If no local copy exists,
+    downloads the latest from GitHub automatically.
+    """
+    local_path = _PACKAGE_DATA_DIR / _CATALOG_FILENAME
+    if local_path.exists():
+        return local_path
+
+    # Auto-download on first use
+    print("📥 No local catalog found. Downloading latest from NCSB...", file=sys.stderr)
+    return download_catalog()
+
+
+def download_catalog(target_dir: Path | None = None) -> Path:
+    """Download the latest enriched catalog from GitHub.
+
+    Args:
+        target_dir: Directory to save the catalog to.
+                    Defaults to the package's data/ directory.
+
+    Returns:
+        Path to the downloaded catalog file.
+
+    Raises:
+        ConnectionError: If the download fails.
+    """
+    dest_dir = target_dir or _PACKAGE_DATA_DIR
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_path = dest_dir / _CATALOG_FILENAME
+
+    try:
+        print(f"📥 Downloading catalog from {CATALOG_URL}...", file=sys.stderr)
+        req = urllib.request.Request(
+            CATALOG_URL,
+            headers={"User-Agent": "ControlGate/0.1.0"},
+        )
+        with urllib.request.urlopen(req, timeout=30) as response:
+            data = response.read()
+
+        # Validate it's valid JSON with the expected structure
+        catalog = json.loads(data)
+        if "controls" not in catalog:
+            raise ValueError("Downloaded file is not a valid NCSB catalog (missing 'controls' key)")
+
+        control_count = len(catalog.get("controls", []))
+
+        # Write atomically (write to tmp then rename)
+        tmp_path = dest_path.with_suffix(".tmp")
+        tmp_path.write_bytes(data)
+        tmp_path.rename(dest_path)
+
+        print(
+            f"✅ Catalog downloaded: {control_count} controls "
+            f"(v{catalog.get('project_version', 'unknown')})",
+            file=sys.stderr,
+        )
+        return dest_path
+
+    except urllib.error.URLError as e:
+        raise ConnectionError(f"Failed to download catalog from {CATALOG_URL}: {e}") from e
+    except (json.JSONDecodeError, ValueError) as e:
+        raise ConnectionError(f"Downloaded file is not valid: {e}") from e
+
+
+def catalog_info(catalog_path: Path) -> dict:
+    """Get metadata about a local catalog file."""
+    with open(catalog_path, encoding="utf-8") as f:
+        data = json.load(f)
+    return {
+        "path": str(catalog_path),
+        "project": data.get("project", "unknown"),
+        "version": data.get("project_version", "unknown"),
+        "generated_at": data.get("generated_at_utc", "unknown"),
+        "framework": data.get("framework", "unknown"),
+        "control_count": len(data.get("controls", [])),
+    }

controlgate/config.py

@@ -0,0 +1,152 @@
+"""Configuration management for ControlGate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml  # type: ignore
+
+_DEFAULT_CONFIG = {
+    "baseline": "moderate",
+    "catalog": "baseline/nist80053r5_full_catalog_enriched.json",
+    "gates": {
+        "secrets": {"enabled": True, "action": "block"},
+        "crypto": {"enabled": True, "action": "block"},
+        "iam": {"enabled": True, "action": "warn"},
+        "sbom": {"enabled": True, "action": "warn"},
+        "iac": {"enabled": True, "action": "block"},
+        "input": {"enabled": True, "action": "block"},
+        "audit": {"enabled": True, "action": "warn"},
+        "change": {"enabled": True, "action": "warn"},
+    },
+    "thresholds": {
+        "block_on": ["CRITICAL", "HIGH"],
+        "warn_on": ["MEDIUM"],
+        "ignore": ["LOW"],
+    },
+    "exclusions": {
+        "paths": ["tests/**", "docs/**", "*.md"],
+        "controls": ["AC-13", "AC-15"],
+    },
+    "reporting": {
+        "format": ["json", "markdown"],
+        "sarif": False,
+        "output_dir": ".controlgate/reports",
+    },
+}
+
+
+@dataclass
+class GateConfig:
+    """Configuration for a single gate."""
+
+    enabled: bool = True
+    action: str = "warn"
+
+
+@dataclass
+class ControlGateConfig:
+    """Full ControlGate configuration loaded from `.controlgate.yml`."""
+
+    baseline: str = "moderate"
+    catalog_path: str = "baseline/nist80053r5_full_catalog_enriched.json"
+    gates: dict[str, GateConfig] = field(default_factory=dict)
+    block_on: list[str] = field(default_factory=lambda: ["CRITICAL", "HIGH"])
+    warn_on: list[str] = field(default_factory=lambda: ["MEDIUM"])
+    ignore: list[str] = field(default_factory=lambda: ["LOW"])
+    excluded_paths: list[str] = field(default_factory=lambda: ["tests/**", "docs/**", "*.md"])
+    excluded_controls: list[str] = field(default_factory=lambda: ["AC-13", "AC-15"])
+    report_formats: list[str] = field(default_factory=lambda: ["json", "markdown"])
+    sarif_enabled: bool = False
+    output_dir: str = ".controlgate/reports"
+
+    @classmethod
+    def load(cls, config_path: str | Path | None = None) -> ControlGateConfig:
+        """Load configuration from a YAML file, falling back to defaults.
+
+        Search order:
+        1. Explicit ``config_path`` argument
+        2. ``.controlgate.yml`` in the current directory
+        3. Built-in defaults
+        """
+        raw: dict[str, Any] = dict(_DEFAULT_CONFIG)
+
+        search_paths: list[Path] = []
+        if config_path:
+            search_paths.append(Path(config_path))
+        search_paths.append(Path(".controlgate.yml"))
+
+        for path in search_paths:
+            if path.exists():
+                with open(path, encoding="utf-8") as f:
+                    loaded = yaml.safe_load(f)
+                if loaded and isinstance(loaded, dict):
+                    raw = _deep_merge(raw, loaded)
+                break
+
+        return cls._from_raw(raw)
+
+    @classmethod
+    def _from_raw(cls, raw: dict[str, Any]) -> ControlGateConfig:
+        """Build config from a raw dict (merged defaults + user overrides)."""
+        cfg = cls()
+        cfg.baseline = raw.get("baseline", cfg.baseline)
+        cfg.catalog_path = raw.get("catalog", cfg.catalog_path)
+
+        # Gates
+        gates_raw = raw.get("gates", {})
+        for name, settings in gates_raw.items():
+            if isinstance(settings, dict):
+                cfg.gates[name] = GateConfig(
+                    enabled=settings.get("enabled", True),
+                    action=settings.get("action", "warn"),
+                )
+
+        # Thresholds
+        thresholds = raw.get("thresholds", {})
+        cfg.block_on = thresholds.get("block_on", cfg.block_on)
+        cfg.warn_on = thresholds.get("warn_on", cfg.warn_on)
+        cfg.ignore = thresholds.get("ignore", cfg.ignore)
+
+        # Exclusions
+        exclusions = raw.get("exclusions", {})
+        cfg.excluded_paths = exclusions.get("paths", cfg.excluded_paths)
+        cfg.excluded_controls = exclusions.get("controls", cfg.excluded_controls)
+
+        # Reporting
+        reporting = raw.get("reporting", {})
+        cfg.report_formats = reporting.get("format", cfg.report_formats)
+        cfg.sarif_enabled = reporting.get("sarif", cfg.sarif_enabled)
+        cfg.output_dir = reporting.get("output_dir", cfg.output_dir)
+
+        return cfg
+
+    def is_gate_enabled(self, gate_name: str) -> bool:
+        """Check if a gate is enabled in the config."""
+        gc = self.gates.get(gate_name)
+        if gc is None:
+            return True  # enabled by default
+        return gc.enabled
+
+    def is_path_excluded(self, file_path: str) -> bool:
+        """Check if a file path is excluded by glob patterns."""
+        from fnmatch import fnmatch
+
+        return any(fnmatch(file_path, pattern) for pattern in self.excluded_paths)
+
+    def is_control_excluded(self, control_id: str) -> bool:
+        """Check if a control ID is explicitly excluded."""
+        return control_id in self.excluded_controls
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Deep-merge override dict into base dict."""
+    result = dict(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result