devguard 0.2.0__py3-none-any.whl

devguard/checkers/secret.py

@@ -0,0 +1,279 @@
+"""Secret scanning checker using trufflehog with fallback."""
+
+import asyncio
+import json
+import logging
+import re
+import shutil
+from pathlib import Path
+
+from devguard.checkers.base import BaseChecker
+from devguard.config import Settings
+from devguard.models import CheckResult, Severity, Vulnerability
+
+logger = logging.getLogger(__name__)
+
+
+class SecretChecker(BaseChecker):
+    """Check git repositories for leaked secrets using trufflehog or fallback regex.
+
+    Scans:
+    1. Configured git repos for secrets in history
+    2. Filesystem for current secrets (excluding .env files)
+
+    Uses trufflehog (Go-based, fast) if available.
+    Falls back to regex scanning if trufflehog is not installed.
+    """
+
+    check_type = "secret"
+
+    # Fallback patterns if trufflehog is missing
+    FALLBACK_PATTERNS = [
+        (r"AWS_ACCESS_KEY_ID\s*=\s*['\"]?(AKIA[0-9A-Z]{16})['\"]?", "AWS Access Key"),
+        (r"AWS_SECRET_ACCESS_KEY\s*=\s*['\"]?([0-9a-zA-Z/+]{40})['\"]?", "AWS Secret Key"),
+        (r"PRIVATE_KEY\s*=\s*['\"]?(-+BEGIN PRIVATE KEY-+)['\"]?", "Private Key"),
+        (r"ghp_[a-zA-Z0-9]{36}", "GitHub Personal Access Token"),
+        (r"xox[baprs]-([0-9a-zA-Z]{10,48})", "Slack Token"),
+        (r"sk_live_[0-9a-zA-Z]{24}", "Stripe Secret Key"),
+        (r"api_key\s*=\s*['\"]?([a-zA-Z0-9]{32,})['\"]?", "Generic API Key"),
+    ]
+
+    def __init__(self, settings: Settings):
+        """Initialize secret checker."""
+        super().__init__(settings)
+        self.trufflehog_path = shutil.which("trufflehog")
+
+    async def check(self) -> CheckResult:
+        """Check for leaked secrets."""
+        vulnerabilities: list[Vulnerability] = []
+        errors: list[str] = []
+        metadata: dict = {
+            "repos_scanned": [],
+            "total_findings": 0,
+            "engine": "trufflehog" if self.trufflehog_path else "regex-fallback",
+        }
+
+        # Scan configured repos.
+        #
+        # Important: when TruffleHog is missing, the regex fallback is both limited
+        # in quality and potentially very slow on large repos. In that mode we only
+        # scan explicitly configured paths to avoid accidental multi-repo sweeps.
+        repos_to_scan = self._get_repos_to_scan()
+        if not self.trufflehog_path and not self.settings.secret_scan_paths:
+            repos_to_scan = []
+
+        for repo_path in repos_to_scan:
+            try:
+                if self.trufflehog_path:
+                    findings = await self._scan_git_history(repo_path)
+                else:
+                    findings = await self._scan_with_regex(repo_path)
+                    if not findings and not errors:  # Only warn once or if we find nothing
+                        pass  # Silence is golden, but we should note it
+
+                vulnerabilities.extend(findings)
+                metadata["repos_scanned"].append(str(repo_path))
+            except Exception as e:
+                errors.append(f"Error scanning {repo_path}: {str(e)}")
+
+        if not self.trufflehog_path:
+            errors.append(
+                "Warning: trufflehog not found. Using limited regex fallback. Install with `brew install trufflehog` for better security."
+            )
+            if not self.settings.secret_scan_paths:
+                errors.append(
+                    "No secret_scan_paths configured; skipping regex fallback scan to avoid slow large-repo sweeps."
+                )
+
+        metadata["total_findings"] = len(vulnerabilities)
+
+        return CheckResult(
+            check_type=self.check_type,
+            success=len(vulnerabilities) == 0,
+            vulnerabilities=vulnerabilities,
+            errors=errors,
+            metadata=metadata,
+        )
+
+    def _get_repos_to_scan(self) -> list[Path]:
+        """Get list of git repos to scan for secrets."""
+        repos = []
+
+        def is_git_repo(p: Path) -> bool:
+            # Support both .git directories and gitfiles (worktrees/submodules)
+            return (p / ".git").is_dir() or (p / ".git").is_file()
+
+        def find_git_root(start: Path) -> Path | None:
+            cur = start.resolve()
+            for parent in [cur, *cur.parents]:
+                if is_git_repo(parent):
+                    return parent
+            return None
+
+        # Check configured secret scan paths
+        if self.settings.secret_scan_paths:
+            for path_str in self.settings.secret_scan_paths:
+                path = Path(path_str).expanduser()
+                if path.exists() and is_git_repo(path):
+                    repos.append(path)
+                elif path.is_dir():
+                    # Look for .git in subdirectories
+                    for git_dir in path.glob("*/.git"):
+                        repos.append(git_dir.parent)
+
+        # Default: try to find "nearby" repos (works both when Guardian lives inside
+        # a larger super-workspace and when it's a standalone repo).
+        if not repos:
+            # 1) If we are in a super-workspace, scan sibling repos if present.
+            # We use the current repo's parent as the "workspace root" candidate.
+            # When Guardian is installed (e.g., in CI), `__file__` will live under
+            # site-packages and won't have a `.git` ancestor. Prefer CWD first.
+            this_repo = find_git_root(Path.cwd()) or find_git_root(Path(__file__))
+            workspace_root = this_repo.parent if this_repo else Path.cwd()
+
+            for rel in [
+                "_infra",  # umbrella dir (may itself be a git repo in some setups)
+                "_infra/infra",  # common layout: infra repo inside _infra
+                "accounting",
+                "dossier",
+                "www",
+                "ops",
+            ]:
+                p = (workspace_root / rel).resolve()
+                if p.exists() and is_git_repo(p):
+                    repos.append(p)
+
+            # 2) Always fall back to scanning Guardian itself (first application on itself).
+            if not repos and this_repo and is_git_repo(this_repo):
+                repos.append(this_repo)
+
+        return repos
+
+    async def _scan_git_history(self, repo_path: Path) -> list[Vulnerability]:
+        """Scan a git repo's history for secrets using trufflehog."""
+        if not self.trufflehog_path:
+            return []
+
+        vulnerabilities: list[Vulnerability] = []
+
+        cmd = [
+            self.trufflehog_path,
+            "git",
+            f"file://{repo_path}",
+            "--no-update",
+            "--only-verified",
+            "--json",
+        ]
+
+        proc = None
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=60.0)
+        except TimeoutError:
+            logger.warning(f"Timeout scanning {repo_path}")
+            if proc:
+                try:
+                    proc.kill()
+                    await proc.wait()
+                except ProcessLookupError:
+                    pass  # Process already terminated
+            return []
+        except Exception as e:
+            logger.warning(f"Error running trufflehog on {repo_path}: {e}")
+            if proc:
+                try:
+                    proc.kill()
+                    await proc.wait()
+                except ProcessLookupError:
+                    pass
+            return []
+
+        # Parse JSON lines output
+        for line in stdout.decode("utf-8", errors="replace").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                finding = json.loads(line)
+                vuln = self._parse_finding(finding, repo_path)
+                if vuln:
+                    vulnerabilities.append(vuln)
+            except json.JSONDecodeError:
+                continue
+
+        return vulnerabilities
+
+    async def _scan_with_regex(self, repo_path: Path) -> list[Vulnerability]:
+        """Scan files in repo using fallback regex."""
+        vulnerabilities = []
+
+        # Walk through files, ignoring .git and node_modules
+        for path in repo_path.rglob("*"):
+            if not path.is_file():
+                continue
+            if any(p in str(path) for p in [".git", "node_modules", "venv", "__pycache__"]):
+                continue
+            # Skip large files
+            if path.stat().st_size > 1024 * 1024:  # 1MB
+                continue
+
+            try:
+                content = path.read_text(errors="ignore")
+                for pattern, name in self.FALLBACK_PATTERNS:
+                    if re.search(pattern, content):
+                        vulnerabilities.append(
+                            Vulnerability(
+                                package_name=f"{repo_path.name}/{path.relative_to(repo_path)}",
+                                package_version="HEAD",
+                                severity=Severity.HIGH,
+                                summary=f"Possible {name} found (Regex)",
+                                description=f"Found pattern matching {name} in file. Please verify.",
+                                source="devguard-regex-fallback",
+                            )
+                        )
+            except Exception:
+                continue
+
+        return vulnerabilities
+
+    def _parse_finding(self, finding: dict, repo_path: Path) -> Vulnerability | None:
+        """Parse a trufflehog finding into a Vulnerability."""
+        try:
+            detector_type = finding.get("DetectorName", "unknown")
+            verified = finding.get("Verified", False)
+
+            # Only report verified findings
+            if not verified:
+                return None
+
+            # Get source metadata
+            source_metadata = finding.get("SourceMetadata", {}).get("Data", {})
+            git_data = source_metadata.get("Git", {})
+
+            file_path = git_data.get("file", "unknown")
+            commit = git_data.get("commit", "")[:8] if git_data.get("commit") else ""
+
+            # Redact the actual secret
+            raw = finding.get("Raw", "")
+            redacted = raw[:4] + "..." + raw[-4:] if len(raw) > 8 else "[redacted]"
+
+            summary = f"Verified {detector_type} secret in {repo_path.name}/{file_path}"
+            if commit:
+                summary += f" (commit {commit})"
+
+            return Vulnerability(
+                package_name=f"{repo_path.name}/{file_path}",
+                package_version=commit or "HEAD",
+                severity=Severity.CRITICAL,  # Verified secrets are always critical
+                summary=summary,
+                description=f"Verified {detector_type} credential found. Value: {redacted}",
+                source="trufflehog",
+            )
+        except Exception as e:
+            logger.warning(f"Error parsing trufflehog finding: {e}")
+            return None

devguard/checkers/swarm.py

@@ -0,0 +1,376 @@
+"""Docker Swarm health checker."""
+
+import asyncio
+import json
+import logging
+
+from devguard.checkers.base import BaseChecker
+from devguard.models import CheckResult, CheckStatus, DeploymentStatus, Finding, Severity
+
+logger = logging.getLogger(__name__)
+
+
+class SwarmChecker(BaseChecker):
+    """Check Docker Swarm cluster health."""
+
+    check_type = "swarm"
+
+    async def check(self) -> CheckResult:
+        """Check Docker Swarm cluster status."""
+        deployments: list[DeploymentStatus] = []
+        findings: list[Finding] = []
+        errors: list[str] = []
+        metadata: dict = {}
+
+        expected_nodes = set(self.settings.swarm_expected_nodes)
+        critical_services = set(self.settings.swarm_critical_services)
+
+        # Check if we're in a swarm
+        swarm_info = await self._get_swarm_info()
+        if swarm_info.get("error"):
+            errors.append(swarm_info["error"])
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                errors=errors,
+            )
+
+        swarm_state = swarm_info.get("state", "inactive")
+        is_manager = swarm_info.get("is_manager", False)
+        metadata["local_state"] = swarm_state
+        metadata["is_manager"] = is_manager
+
+        if swarm_state == "inactive":
+            findings.append(
+                Finding(
+                    severity=Severity.WARNING,
+                    title="Local node not in swarm",
+                    description="This node is not part of a Docker Swarm cluster",
+                    resource="swarm",
+                    remediation="Run 'docker swarm init' or 'docker swarm join'",
+                )
+            )
+            return CheckResult(
+                check_type=self.check_type,
+                success=True,  # Not being in swarm isn't a failure
+                findings=findings,
+                errors=errors,
+                metadata=metadata,
+            )
+
+        # If we're a worker (not manager), we can't query cluster state
+        if not is_manager:
+            metadata["note"] = (
+                "Running on worker node - cannot query cluster state. Run on a manager node for full cluster visibility."
+            )
+            return CheckResult(
+                check_type=self.check_type,
+                success=True,  # Worker node is fine, just can't query
+                findings=findings,
+                errors=errors,
+                metadata=metadata,
+            )
+
+        if swarm_state == "pending":
+            findings.append(
+                Finding(
+                    severity=Severity.HIGH,
+                    title="Swarm node stuck in pending state",
+                    description="This node is trying to join a swarm but cannot connect to the manager",
+                    resource="swarm",
+                    remediation="Check network connectivity to swarm manager, or run 'docker swarm leave --force' and rejoin",
+                )
+            )
+
+        # If we're a manager, we can query cluster state
+        if is_manager:
+            nodes_result = await self._get_swarm_nodes()
+            if nodes_result.get("error"):
+                errors.append(nodes_result["error"])
+            else:
+                nodes = nodes_result.get("nodes", [])
+                metadata["total_nodes"] = len(nodes)
+
+                for node in nodes:
+                    hostname = node.get("hostname", "unknown")
+                    status = node.get("status", "unknown")
+                    availability = node.get("availability", "unknown")
+                    manager_status = node.get("manager_status", "")
+
+                    is_healthy = status == "ready" and availability == "active"
+                    is_expected = hostname in expected_nodes
+
+                    if is_healthy:
+                        check_status = CheckStatus.HEALTHY
+                    elif is_expected:
+                        check_status = CheckStatus.UNHEALTHY
+                        findings.append(
+                            Finding(
+                                severity=Severity.HIGH,
+                                title=f"Expected swarm node unhealthy: {hostname}",
+                                description=f"{hostname} status={status}, availability={availability}",
+                                resource=hostname,
+                                remediation=f"Check {hostname} Docker daemon and network",
+                            )
+                        )
+                    else:
+                        check_status = CheckStatus.UNKNOWN
+
+                    deployments.append(
+                        DeploymentStatus(
+                            platform="swarm",
+                            project_name=hostname,
+                            deployment_id=node.get("id", "")[:12],
+                            status=check_status,
+                            url=f"docker://{hostname}",
+                            metadata={
+                                "status": status,
+                                "availability": availability,
+                                "manager_status": manager_status,
+                                "role": "manager" if manager_status else "worker",
+                            },
+                        )
+                    )
+
+                # Check for missing expected nodes
+                seen_hostnames = {n.get("hostname") for n in nodes}
+                for expected_host in expected_nodes:
+                    if expected_host not in seen_hostnames:
+                        findings.append(
+                            Finding(
+                                severity=Severity.HIGH,
+                                title=f"Expected swarm node missing: {expected_host}",
+                                description=f"{expected_host} is not in the swarm cluster",
+                                resource=expected_host,
+                                remediation=f"Join {expected_host} to the swarm cluster",
+                            )
+                        )
+
+            # Check services
+            services_result = await self._get_swarm_services()
+            if services_result.get("error"):
+                # Not critical - maybe no stack deployed
+                logger.debug(f"Could not get swarm services: {services_result['error']}")
+            else:
+                services = services_result.get("services", [])
+                metadata["total_services"] = len(services)
+
+                for svc in services:
+                    name = svc.get("name", "unknown")
+                    replicas = svc.get("replicas", "0/0")
+                    mode = svc.get("mode", "unknown")
+
+                    # Parse replicas like "1/1" or "0/1"
+                    try:
+                        running, desired = replicas.split("/")
+                        is_healthy = int(running) >= int(desired) and int(desired) > 0
+                    except (ValueError, ZeroDivisionError):
+                        is_healthy = False
+
+                    if not is_healthy and name in critical_services:
+                        findings.append(
+                            Finding(
+                                severity=Severity.HIGH,
+                                title=f"Critical swarm service unhealthy: {name}",
+                                description=f"Service {name} has {replicas} replicas",
+                                resource=name,
+                                remediation=f"Check service logs: docker service logs {name}",
+                            )
+                        )
+
+                    # Check placement constraints compliance
+                    placement_result = await self._check_service_placement(name)
+                    if placement_result.get("violations"):
+                        for violation in placement_result["violations"]:
+                            findings.append(
+                                Finding(
+                                    severity=Severity.HIGH,
+                                    title=f"Service placement violation: {name}",
+                                    description=violation["description"],
+                                    resource=name,
+                                    remediation=violation["remediation"],
+                                )
+                            )
+
+        return CheckResult(
+            check_type=self.check_type,
+            success=len(errors) == 0
+            and not any(f.severity in [Severity.CRITICAL, Severity.HIGH] for f in findings),
+            deployments=deployments,
+            findings=findings,
+            errors=errors,
+            metadata=metadata,
+        )
+
+    async def _get_swarm_info(self) -> dict:
+        """Get local swarm state."""
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                "docker",
+                "info",
+                "--format",
+                '{"state":"{{.Swarm.LocalNodeState}}","is_manager":{{.Swarm.ControlAvailable}},"node_id":"{{.Swarm.NodeID}}"}',
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10.0)
+
+            if proc.returncode != 0:
+                return {"error": f"docker info failed: {stderr.decode()}"}
+
+            return json.loads(stdout.decode())
+
+        except TimeoutError:
+            return {"error": "docker info timed out"}
+        except FileNotFoundError:
+            return {"error": "docker CLI not found"}
+        except json.JSONDecodeError as e:
+            return {"error": f"Failed to parse docker info: {e}"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def _get_swarm_nodes(self) -> dict:
+        """Get swarm nodes (requires manager)."""
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                "docker",
+                "node",
+                "ls",
+                "--format",
+                '{"id":"{{.ID}}","hostname":"{{.Hostname}}","status":"{{.Status}}","availability":"{{.Availability}}","manager_status":"{{.ManagerStatus}}"}',
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10.0)
+
+            if proc.returncode != 0:
+                return {"error": stderr.decode()}
+
+            nodes = []
+            for line in stdout.decode().strip().split("\n"):
+                if line:
+                    nodes.append(json.loads(line))
+
+            return {"nodes": nodes}
+
+        except TimeoutError:
+            return {"error": "docker node ls timed out"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def _get_swarm_services(self) -> dict:
+        """Get swarm services (requires manager)."""
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                "docker",
+                "service",
+                "ls",
+                "--format",
+                '{"id":"{{.ID}}","name":"{{.Name}}","mode":"{{.Mode}}","replicas":"{{.Replicas}}"}',
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10.0)
+
+            if proc.returncode != 0:
+                return {"error": stderr.decode()}
+
+            services = []
+            for line in stdout.decode().strip().split("\n"):
+                if line:
+                    services.append(json.loads(line))
+
+            return {"services": services}
+
+        except TimeoutError:
+            return {"error": "docker service ls timed out"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def _check_service_placement(self, service_name: str) -> dict:
+        """Check if service tasks are placed according to constraints.
+
+        Verifies that services with node.hostname constraints are actually
+        running on the correct nodes (Swarm's equivalent of K8s taints/affinities).
+        """
+        violations: list[dict] = []
+
+        try:
+            # Get service inspect to see constraints
+            proc_inspect = await asyncio.create_subprocess_exec(
+                "docker",
+                "service",
+                "inspect",
+                service_name,
+                "--format",
+                "{{json .Spec.TaskTemplate.Placement.Constraints}}",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout_inspect, stderr_inspect = await asyncio.wait_for(
+                proc_inspect.communicate(), timeout=10.0
+            )
+
+            if proc_inspect.returncode != 0:
+                return {"violations": []}  # Can't check, not an error
+
+            constraints_json = stdout_inspect.decode().strip()
+            if not constraints_json or constraints_json == "null":
+                return {"violations": []}  # No constraints defined
+
+            constraints = json.loads(constraints_json) if constraints_json else []
+
+            # Extract expected hostname from constraints (e.g., "node.hostname == mynode")
+            expected_hostname = None
+            for constraint in constraints:
+                if constraint.startswith("node.hostname == "):
+                    expected_hostname = constraint.replace("node.hostname == ", "").strip()
+                    break
+
+            if not expected_hostname:
+                return {"violations": []}  # No hostname constraint
+
+            # Get actual task placements
+            proc_ps = await asyncio.create_subprocess_exec(
+                "docker",
+                "service",
+                "ps",
+                service_name,
+                "--format",
+                '{"id":"{{.ID}}","node":"{{.Node}}","desired_state":"{{.DesiredState}}","current_state":"{{.CurrentState}}"}',
+                "--no-trunc",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout_ps, stderr_ps = await asyncio.wait_for(proc_ps.communicate(), timeout=10.0)
+
+            if proc_ps.returncode != 0:
+                return {"violations": []}  # Can't check
+
+            # Parse task placements
+            for line in stdout_ps.decode().strip().split("\n"):
+                if not line:
+                    continue
+                try:
+                    task = json.loads(line)
+                    if task.get("current_state") == "Running":
+                        actual_node = task.get("node", "").split(".")[
+                            0
+                        ]  # Extract hostname from FQDN
+                        if actual_node != expected_hostname:
+                            violations.append(
+                                {
+                                    "description": f"Service {service_name} task {task.get('id', '')[:12]} is running on {actual_node}, but constraint requires {expected_hostname}",
+                                    "remediation": f"Check why task was placed on wrong node. Verify node.hostname constraint: docker service inspect {service_name}",
+                                }
+                            )
+                except (json.JSONDecodeError, KeyError):
+                    continue
+
+            return {"violations": violations}
+
+        except TimeoutError:
+            return {"violations": []}
+        except Exception as e:
+            logger.debug(f"Placement check failed for {service_name}: {e}")
+            return {"violations": []}