devguard 0.2.0__py3-none-any.whl

devguard/checkers/tailscale.py

@@ -0,0 +1,143 @@
+"""Tailscale node 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 TailscaleChecker(BaseChecker):
+    """Check Tailscale mesh network health."""
+
+    check_type = "tailscale"
+
+    async def check(self) -> CheckResult:
+        """Check Tailscale node status."""
+        deployments: list[DeploymentStatus] = []
+        findings: list[Finding] = []
+        errors: list[str] = []
+
+        expected_nodes = set(self.settings.tailscale_expected_nodes)
+
+        try:
+            # Run tailscale status --json
+            proc = await asyncio.create_subprocess_exec(
+                "tailscale",
+                "status",
+                "--json",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10.0)
+
+            if proc.returncode != 0:
+                errors.append(f"tailscale status failed: {stderr.decode()}")
+                return CheckResult(
+                    check_type=self.check_type,
+                    success=False,
+                    errors=errors,
+                )
+
+            status = json.loads(stdout.decode())
+            peers = status.get("Peer", {})
+            self_node = status.get("Self", {})
+
+            # Check self node
+            if self_node:
+                self_name = self_node.get("HostName", "unknown")
+                deployments.append(
+                    DeploymentStatus(
+                        platform="tailscale",
+                        project_name=self_name,
+                        deployment_id=self_node.get("PublicKey", "")[:16],
+                        status=CheckStatus.HEALTHY,
+                        url=f"tailscale://{self_name}",
+                        metadata={"role": "self", "online": True},
+                    )
+                )
+
+            # Check all peers
+            seen_nodes = {self_node.get("HostName", "")}
+            for pubkey, peer in peers.items():
+                hostname = peer.get("HostName", "unknown")
+                seen_nodes.add(hostname)
+                online = peer.get("Online", False)
+
+                is_expected = hostname in expected_nodes
+
+                if online:
+                    status_val = CheckStatus.HEALTHY
+                elif is_expected:
+                    status_val = CheckStatus.UNHEALTHY
+                    findings.append(
+                        Finding(
+                            severity=Severity.HIGH,
+                            title=f"Expected node offline: {hostname}",
+                            description=f"{hostname} is offline but listed in expected nodes",
+                            resource=hostname,
+                            remediation=f"Check {hostname} connectivity",
+                        )
+                    )
+                else:
+                    status_val = CheckStatus.UNKNOWN
+
+                deployments.append(
+                    DeploymentStatus(
+                        platform="tailscale",
+                        project_name=hostname,
+                        deployment_id=pubkey[:16],
+                        status=status_val,
+                        url=f"tailscale://{hostname}",
+                        metadata={
+                            "online": online,
+                            "expected": is_expected,
+                            "exit_node": peer.get("ExitNode", False),
+                            "exit_node_option": peer.get("ExitNodeOption", False),
+                        },
+                    )
+                )
+
+            # Check for missing expected nodes
+            for node_name in expected_nodes:
+                if node_name not in seen_nodes:
+                    findings.append(
+                        Finding(
+                            severity=Severity.HIGH,
+                            title=f"Expected node not in mesh: {node_name}",
+                            description=f"{node_name} is not visible in Tailscale mesh",
+                            resource=node_name,
+                            remediation="Check if node is registered with Tailscale",
+                        )
+                    )
+
+        except TimeoutError:
+            errors.append("tailscale status timed out after 10s")
+        except FileNotFoundError:
+            errors.append("tailscale CLI not found")
+        except json.JSONDecodeError as e:
+            errors.append(f"Failed to parse tailscale status: {e}")
+        except Exception as e:
+            errors.append(f"Tailscale check failed: {e}")
+
+        expected_offline = sum(
+            1
+            for d in deployments
+            if d.metadata.get("expected") and d.status == CheckStatus.UNHEALTHY
+        )
+
+        return CheckResult(
+            check_type=self.check_type,
+            success=len(errors) == 0 and expected_offline == 0,
+            deployments=deployments,
+            findings=findings,
+            errors=errors,
+            metadata={
+                "total_nodes": len(deployments),
+                "online_nodes": sum(1 for d in deployments if d.status == CheckStatus.HEALTHY),
+                "expected_offline": expected_offline,
+            },
+        )

devguard/checkers/tailsnitch.py

@@ -0,0 +1,303 @@
+"""Tailsnitch security auditor for Tailscale ACLs."""
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+
+from devguard.checkers.base import BaseChecker
+from devguard.models import CheckResult, Finding, Severity
+
+logger = logging.getLogger(__name__)
+
+
+class TailsnitchChecker(BaseChecker):
+    """Check Tailscale ACL security using Tailsnitch.
+    
+    Tailsnitch scans Tailscale ACL policies for 50+ security misconfigurations,
+    overly permissive access controls, and best practice violations.
+    
+    Requires:
+    - Tailsnitch binary installed (see https://github.com/Adversis/tailsnitch)
+    - Tailscale authentication (TSKEY or OAuth credentials)
+    """
+
+    check_type = "tailsnitch"
+
+    def __init__(self, settings):
+        """Initialize Tailsnitch checker."""
+        super().__init__(settings)
+        # Use custom path if provided, otherwise auto-detect
+        self.tailsnitch_path = (
+            settings.tailsnitch_binary_path
+            if settings.tailsnitch_binary_path
+            else self._find_tailsnitch()
+        )
+        self.tailnet = settings.tailsnitch_tailnet
+
+        # Read auth from environment (pydantic-settings loads .env automatically)
+        # Support both TSKEY and TS_API_KEY for compatibility
+        self.tskey = os.getenv("TSKEY") or os.getenv("TS_API_KEY")
+        self.ts_oauth_client_id = os.getenv("TS_OAUTH_CLIENT_ID")
+        self.ts_oauth_client_secret = os.getenv("TS_OAUTH_CLIENT_SECRET")
+
+        logger.debug(
+            "TailsnitchChecker initialized",
+            extra={
+                "tailsnitch_path": self.tailsnitch_path,
+                "has_api_key": bool(self.tskey),
+                "has_oauth": bool(self.ts_oauth_client_id and self.ts_oauth_client_secret),
+                "tailnet": self.tailnet,
+            },
+        )
+
+    def _find_tailsnitch(self) -> str | None:
+        """Find tailsnitch binary in PATH or common locations."""
+        # Check PATH first
+        path = shutil.which("tailsnitch")
+        if path:
+            logger.debug(f"Found tailsnitch in PATH: {path}")
+            return path
+
+        # Check common install locations
+        common_paths = [
+            "/usr/local/bin/tailsnitch",
+            "/opt/homebrew/bin/tailsnitch",
+            os.path.expanduser("~/bin/tailsnitch"),
+            os.path.expanduser("~/.local/bin/tailsnitch"),
+        ]
+
+        for path in common_paths:
+            if os.path.exists(path) and os.access(path, os.X_OK):
+                logger.debug(f"Found tailsnitch at: {path}")
+                return path
+
+        logger.debug("Tailsnitch binary not found in PATH or common locations")
+        return None
+
+    async def check(self) -> CheckResult:
+        """Run Tailsnitch security audit."""
+        findings: list[Finding] = []
+        errors: list[str] = []
+
+        if not self.tailsnitch_path:
+            install_instructions = (
+                "Install Tailsnitch:\n"
+                "  1. Download from https://github.com/Adversis/tailsnitch/releases\n"
+                "  2. Or install via Go: go install github.com/Adversis/tailsnitch@latest\n"
+                "  3. Or set TAILSNITCH_BINARY_PATH in .env to custom location"
+            )
+            errors.append(f"Tailsnitch binary not found. {install_instructions}")
+            logger.warning("Tailsnitch binary not found", extra={"check_type": self.check_type})
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                errors=errors,
+            )
+
+        # Check authentication
+        if not self.tskey and not (self.ts_oauth_client_id and self.ts_oauth_client_secret):
+            auth_instructions = (
+                "Tailscale authentication required. Set one of:\n"
+                "  - TSKEY or TS_API_KEY (API key from https://login.tailscale.com/admin/settings/keys)\n"
+                "  - TS_OAUTH_CLIENT_ID + TS_OAUTH_CLIENT_SECRET (OAuth from https://login.tailscale.com/admin/settings/oauth)\n"
+                "Add to .env file or export as environment variables"
+            )
+            errors.append(auth_instructions)
+            logger.warning("Tailscale authentication not configured", extra={"check_type": self.check_type})
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                errors=errors,
+            )
+
+        try:
+            # Build command
+            cmd = [self.tailsnitch_path, "--json"]
+
+            # Add tailnet flag if specified
+            if self.tailnet:
+                cmd.extend(["--tailnet", self.tailnet])
+                logger.debug(f"Auditing specific tailnet: {self.tailnet}")
+
+            # Set environment variables for Tailsnitch
+            env = os.environ.copy()
+            if self.tskey:
+                env["TSKEY"] = self.tskey
+                logger.debug("Using TSKEY authentication")
+            if self.ts_oauth_client_id:
+                env["TS_OAUTH_CLIENT_ID"] = self.ts_oauth_client_id
+                logger.debug("Using OAuth client ID")
+            if self.ts_oauth_client_secret:
+                env["TS_OAUTH_CLIENT_SECRET"] = self.ts_oauth_client_secret
+                logger.debug("Using OAuth client secret")
+
+            logger.info("Running Tailsnitch security audit", extra={"command": " ".join(cmd[:3])})
+
+            # Run Tailsnitch
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+            )
+
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=60.0)
+
+            if proc.returncode != 0:
+                stderr_text = stderr.decode() if stderr else ""
+                stdout_preview = stdout.decode()[:200] if stdout else ""
+                error_msg = f"Tailsnitch failed (exit {proc.returncode})"
+                if stderr_text:
+                    error_msg += f": {stderr_text[:500]}"
+                elif stdout_preview:
+                    error_msg += f": {stdout_preview}"
+                errors.append(error_msg)
+                logger.error(
+                    "Tailsnitch execution failed",
+                    extra={
+                        "exit_code": proc.returncode,
+                        "stderr_preview": stderr_text[:200] if stderr_text else None,
+                    },
+                )
+                return CheckResult(
+                    check_type=self.check_type,
+                    success=False,
+                    errors=errors,
+                )
+
+            # Parse JSON output
+            try:
+                output = json.loads(stdout.decode())
+            except json.JSONDecodeError as e:
+                errors.append(f"Failed to parse Tailsnitch JSON output: {e}")
+                return CheckResult(
+                    check_type=self.check_type,
+                    success=False,
+                    errors=errors,
+                )
+
+            # Convert Tailsnitch findings to Guardian Findings
+            suggestions = output.get("suggestions", [])
+            summary = output.get("summary", {})
+            tailnet_name = output.get("tailnet", "unknown")
+
+            logger.info(
+                "Tailsnitch audit completed",
+                extra={
+                    "tailnet": tailnet_name,
+                    "total_checks": summary.get("total", 0),
+                    "failed": summary.get("failed", 0),
+                    "critical": summary.get("critical", 0),
+                    "high": summary.get("high", 0),
+                },
+            )
+
+            for suggestion in suggestions:
+                if suggestion.get("pass", True):
+                    continue  # Skip passing checks
+
+                check_id = suggestion.get("id", "UNKNOWN")
+                title = suggestion.get("title", "Unknown issue")
+                severity_str = suggestion.get("severity", "info").upper()
+                description = suggestion.get("description", "")
+                remediation = suggestion.get("remediation", "")
+                category = suggestion.get("category", "")
+
+                # Map Tailsnitch severity to Guardian severity
+                severity_map = {
+                    "CRITICAL": Severity.CRITICAL,
+                    "HIGH": Severity.HIGH,
+                    "MEDIUM": Severity.MEDIUM,
+                    "LOW": Severity.LOW,
+                    "INFO": Severity.WARNING,
+                }
+                severity = severity_map.get(severity_str, Severity.WARNING)
+
+                # Extract resource from suggestion (can be string, dict, or list)
+                resource = suggestion.get("resource", tailnet_name)
+                if isinstance(resource, dict):
+                    resource = (
+                        resource.get("name")
+                        or resource.get("id")
+                        or resource.get("hostname")
+                        or tailnet_name
+                    )
+                elif isinstance(resource, list) and resource:
+                    # If resource is a list, use first item or join
+                    resource = str(resource[0]) if len(resource) == 1 else f"{tailnet_name} ({len(resource)} resources)"
+                elif not resource or resource == "tailnet":
+                    resource = tailnet_name
+
+                # Build remediation with admin URL if available
+                fix_info = suggestion.get("fix", {})
+                admin_url = fix_info.get("admin_url")
+                full_remediation = remediation
+                if admin_url:
+                    full_remediation = f"{remediation}\n\nFix in admin console: {admin_url}"
+
+                findings.append(
+                    Finding(
+                        severity=severity,
+                        title=f"{check_id}: {title}",
+                        description=description,
+                        resource=str(resource),
+                        remediation=full_remediation,
+                        metadata={
+                            "check_id": check_id,
+                            "category": category,
+                            "tailsnitch_severity": severity_str,
+                            "admin_url": admin_url,
+                            "tailnet": tailnet_name,
+                            "details": suggestion.get("details"),  # Additional context
+                        },
+                    )
+                )
+
+            # Determine overall success
+            critical_count = summary.get("critical", 0)
+            high_count = summary.get("high", 0)
+            success = critical_count == 0 and high_count == 0
+
+            return CheckResult(
+                check_type=self.check_type,
+                success=success,
+                findings=findings,
+                errors=errors,
+                metadata={
+                    "total_checks": summary.get("total", 0),
+                    "passed": summary.get("passed", 0),
+                    "failed": summary.get("failed", 0),
+                    "critical": critical_count,
+                    "high": high_count,
+                    "medium": summary.get("medium", 0),
+                    "low": summary.get("low", 0),
+                    "info": summary.get("info", 0),
+                    "tailnet": output.get("tailnet", "unknown"),
+                },
+            )
+
+        except TimeoutError:
+            errors.append("Tailsnitch timed out after 60s")
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                errors=errors,
+            )
+        except FileNotFoundError:
+            errors.append(f"Tailsnitch binary not found at {self.tailsnitch_path}")
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                errors=errors,
+            )
+        except Exception as e:
+            errors.append(f"Tailsnitch check failed: {e}")
+            logger.exception("Tailsnitch check exception")
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                errors=errors,
+            )
+

devguard/checkers/tavily.py

@@ -0,0 +1,179 @@
+"""Tavily API usage checker."""
+
+import logging
+
+import httpx
+
+from devguard.checkers.base import BaseChecker
+from devguard.http_client import create_client, retry_with_backoff
+from devguard.models import CheckResult, CostMetric
+
+logger = logging.getLogger(__name__)
+
+
+class TavilyChecker(BaseChecker):
+    """Check Tavily API usage."""
+
+    check_type = "tavily"
+
+    async def check(self) -> CheckResult:
+        """Check Tavily usage."""
+        errors: list[str] = []
+
+        if not self.settings.tavily_api_key:
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                deployments=[],
+                errors=["Tavily API key not configured"],
+            )
+
+        # Handle SecretStr
+        tavily_key = self.settings.tavily_api_key
+        if hasattr(tavily_key, "get_secret_value"):
+            tavily_key = tavily_key.get_secret_value()
+
+        headers = {
+            "Authorization": f"Bearer {tavily_key}",
+        }
+
+        try:
+            async with create_client() as client:
+
+                async def fetch_usage():
+                    response = await client.get(
+                        "https://api.tavily.com/usage",
+                        headers=headers,
+                        timeout=10.0,
+                    )
+                    response.raise_for_status()
+                    return response
+
+                response = await retry_with_backoff(fetch_usage, max_retries=3)
+                data = response.json()
+
+                # Extract usage data
+                key_usage = data.get("key", {})
+                account_usage = data.get("account", {})
+
+                # Safely extract numeric values, defaulting to 0 if None
+                key_usage_val = float(key_usage.get("usage") or 0)
+                key_limit_val = float(key_usage.get("limit") or 0)
+                account_usage_val = float(account_usage.get("plan_usage") or 0)
+                account_limit_val = float(account_usage.get("plan_limit") or 0)
+
+                key_usage_pct = (key_usage_val / key_limit_val * 100) if key_limit_val > 0 else 0.0
+                account_usage_pct = (
+                    (account_usage_val / account_limit_val * 100) if account_limit_val > 0 else 0.0
+                )
+
+                # Use the higher usage percentage
+                usage_percent = max(key_usage_pct, account_usage_pct)
+
+                metadata = {
+                    "key_usage": key_usage_val,
+                    "key_limit": key_limit_val,
+                    "account_plan": account_usage.get("current_plan"),
+                    "account_usage": account_usage_val,
+                    "account_limit": account_limit_val,
+                    "usage_percent": round(usage_percent, 2),
+                }
+
+                # Create cost metrics with estimated costs
+                # Tavily pricing: $0.008 per credit (pay-as-you-go)
+                # Free: 1000 credits/month = $0
+                # Monthly plans reduce per-credit cost
+                plan = account_usage.get("current_plan", "free")
+                # Use $0.008 per request as standard estimate for paid plans
+                cost_per_request = 0.0 if plan == "free" else 0.008
+
+                key_cost = key_usage_val * cost_per_request if cost_per_request > 0 else None
+                account_cost = (
+                    account_usage_val * cost_per_request if cost_per_request > 0 else None
+                )
+
+                cost_metrics = [
+                    CostMetric(
+                        service="tavily",
+                        period="monthly",
+                        amount=key_cost,
+                        usage=key_usage_val,
+                        limit=key_limit_val,
+                        usage_percent=round(key_usage_pct, 2),
+                        metadata={
+                            "unit": "requests",
+                            "type": "key",
+                            "cost_per_request": cost_per_request,
+                            "estimated": cost_per_request > 0,
+                        },
+                    ),
+                    CostMetric(
+                        service="tavily",
+                        period="monthly",
+                        amount=account_cost,
+                        usage=account_usage_val,
+                        limit=account_limit_val,
+                        usage_percent=round(account_usage_pct, 2),
+                        metadata={
+                            "unit": "requests",
+                            "type": "account",
+                            "plan": plan,
+                            "cost_per_request": cost_per_request,
+                            "estimated": cost_per_request > 0,
+                        },
+                    ),
+                ]
+
+                return CheckResult(
+                    check_type=self.check_type,
+                    success=True,
+                    deployments=[],
+                    errors=[],
+                    cost_metrics=cost_metrics,
+                    metadata=metadata,
+                )
+
+        except httpx.HTTPStatusError as e:
+            status_code = e.response.status_code
+            error_text = e.response.text[:100]
+            errors.append(f"HTTP {status_code}: {error_text}")
+            # Try to extract partial cost data from error response if available
+            cost_metrics = []
+            try:
+                error_data = e.response.json()
+                if isinstance(error_data, dict):
+                    # Try to get any usage info from error response
+                    key_usage = error_data.get("key", {})
+                    if key_usage:
+                        cost_metrics.append(
+                            CostMetric(
+                                service="tavily",
+                                period="monthly",
+                                amount=None,
+                                usage=float(key_usage.get("usage") or 0),
+                                limit=float(key_usage.get("limit") or 0),
+                                usage_percent=0.0,
+                                metadata={"error": True, "status_code": status_code},
+                            )
+                        )
+            except Exception:
+                pass
+            return CheckResult(
+                check_type=self.check_type,
+                success=False,
+                deployments=[],
+                errors=errors,
+                cost_metrics=cost_metrics,
+            )
+        except httpx.RequestError as e:
+            errors.append(f"Network error: {str(e)}")
+        except Exception as e:
+            errors.append(f"Unexpected error: {str(e)}")
+
+        return CheckResult(
+            check_type=self.check_type,
+            success=False,
+            deployments=[],
+            errors=errors,
+            cost_metrics=[],
+        )