devguard 0.2.0__py3-none-any.whl

devguard/mcp_server.py

@@ -0,0 +1,259 @@
+"""MCP Server for Guardian.
+
+This module exposes Guardian's capabilities as a Model Context Protocol (MCP) server,
+allowing AI assistants to directly run security checks and retrieve reports.
+"""
+
+import json
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+from devguard.config import get_settings
+from devguard.core import Guardian
+from devguard.models import GuardianReport
+from devguard.reporting import Reporter
+
+# Initialize FastMCP server
+mcp = FastMCP("devguard")
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def run_checks(
+    json_output: bool = True,
+    npm_packages: list[str] | None = None,
+    github_repos: list[str] | None = None,
+) -> str:
+    """Run security checks and return the report.
+
+    Args:
+        json_output: Whether to return JSON (default: True)
+        npm_packages: Optional list of npm packages to check (overrides config)
+        github_repos: Optional list of GitHub repos to check (overrides config)
+    """
+    # Validate inputs to prevent injection or malicious patterns
+    if npm_packages:
+        for pkg in npm_packages:
+            if not pkg or any(c in pkg for c in [";", "&", "|", "`", "$"]):
+                return json.dumps({"error": f"Invalid package name: {pkg}"})
+
+    if github_repos:
+        for repo in github_repos:
+            if not repo or not all(c.isalnum() or c in "/-._" for c in repo):
+                return json.dumps({"error": f"Invalid repo format: {repo}"})
+
+    settings = get_settings()
+
+    # Override settings if provided
+    if npm_packages:
+        settings.npm_packages_to_monitor = npm_packages
+    if github_repos:
+        settings.github_repos_to_monitor = github_repos
+
+    guardian = Guardian(settings)
+    report = await guardian.run_checks()
+
+    if json_output:
+        # Convert to dict for JSON serialization
+        reporter = Reporter(settings)
+        # We redact sensitive info before returning via MCP
+        report_dict = reporter._report_to_dict(report)
+        return json.dumps(report_dict, indent=2)
+
+    return _format_text_report(report)
+
+
+@mcp.tool()
+async def scan_npm_package(package_name: str) -> str:
+    """Deep scan a specific npm package for vulnerabilities.
+
+    Args:
+        package_name: The name of the npm package to scan
+    """
+    settings = get_settings()
+    # Enable deep security scanning
+    settings.npm_security_enabled = True
+    settings.npm_packages_to_monitor = [package_name]
+
+    guardian = Guardian(settings)
+
+    # Run only the npm checker using the new checker_types parameter
+    report = await guardian.run_checks(checker_types=["npm"])
+
+    # Get npm results (should be only one)
+    npm_checks = [c for c in report.checks if c.check_type == "npm"]
+    if not npm_checks:
+        return f"No results found for {package_name}"
+
+    result = npm_checks[0]
+    return json.dumps(
+        {
+            "success": result.success,
+            "vulnerabilities": [v.model_dump() for v in result.vulnerabilities],
+            "metadata": result.metadata,
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+async def get_email_history(limit: int = 10) -> str:
+    """Get recent email alert history for introspection.
+
+    Returns JSON array of recent emails with their summaries, issues, and metadata.
+    If USE_SMART_EMAIL is enabled, reads from unified SQLite database (includes Guardian + agent alerts).
+    Otherwise, reads from Guardian's JSON history.
+
+    Useful for agents to understand email patterns and decide when/how to send alerts.
+
+    Args:
+        limit: Maximum number of recent emails to return (default: 10, max: 100)
+    """
+    from devguard.reporting import Reporter
+
+    settings = get_settings()
+    reporter = Reporter(settings)
+    history = reporter.get_email_history(limit=min(limit, 100))
+
+    return json.dumps(history, indent=2, default=str)
+
+
+@mcp.tool()
+async def get_unified_alert_history(limit: int = 20, topic: str | None = None) -> str:
+    """Get unified alert history from smart_email system (all agents + Guardian).
+
+    Returns alerts from all sources (Guardian, SRE Agent, Watchdog, etc.) in a unified format.
+    Only works if smart_email system is available.
+
+    Args:
+        limit: Maximum number of alerts to return (default: 20, max: 100)
+        topic: Optional topic filter (e.g., 'security_posture', 'cost_anomaly')
+    """
+    settings = get_settings()
+    use_smart_email = getattr(settings, "use_smart_email", False)
+
+    if not use_smart_email:
+        return json.dumps(
+            {
+                "error": "smart_email not enabled. Set USE_SMART_EMAIL=true to use unified history.",
+                "fallback": "Use get_email_history() for Guardian-only history",
+            },
+            indent=2,
+        )
+
+    try:
+        import sqlite3
+
+        from devguard.utils import get_smart_email_db_path, import_smart_email
+
+        smart_email = import_smart_email()
+        if not smart_email:
+            return json.dumps(
+                {
+                    "error": "smart_email not enabled. Set USE_SMART_EMAIL=true to use unified history.",
+                    "fallback": "Use get_email_history() for Guardian-only history",
+                },
+                indent=2,
+            )
+
+        init_db = smart_email.init_db
+        db_path = get_smart_email_db_path(settings)
+
+        init_db(db_path)
+        conn = sqlite3.connect(str(db_path))
+
+        # Query all alerts (optionally filtered by topic)
+        if topic:
+            rows = conn.execute(
+                """
+                SELECT topic, severity, subject, sent_at, author, metadata_json
+                FROM alert_history
+                WHERE topic LIKE ?
+                ORDER BY sent_at DESC
+                LIMIT ?
+            """,
+                (f"%{topic}%", min(limit, 100)),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                """
+                SELECT topic, severity, subject, sent_at, author, metadata_json
+                FROM alert_history
+                ORDER BY sent_at DESC
+                LIMIT ?
+            """,
+                (min(limit, 100),),
+            ).fetchall()
+
+        conn.close()
+
+        # Convert to unified format with all preserved metadata
+        alerts = []
+        for row in rows:
+            if len(row) >= 7:  # New format with message_preview
+                topic_val, severity, subject, sent_at, author, message_preview, metadata_json = row
+            else:  # Old format without message_preview
+                topic_val, severity, subject, sent_at, author, metadata_json = row[:6]
+                message_preview = ""
+
+            metadata = json.loads(metadata_json) if metadata_json else {}
+
+            # Extract all useful information for analysis
+            alert_entry = {
+                "timestamp": sent_at,
+                "topic": topic_val,
+                "severity": severity,
+                "subject": subject,
+                "author": author or "unknown",
+                "message_preview": message_preview,
+                "summary": metadata.get("summary", {}),
+                "issues": metadata.get("issues", {}),
+                "llm_decision": metadata.get("llm_decision"),
+                "llm_reasoning": metadata.get("llm_reasoning", {}),
+                "report_summary": metadata.get("report_summary", {}),
+                "actionable": metadata.get("actionable", False),
+                "context": metadata.get("context", {}),  # Alert context (occurrence counts, trends)
+                "full_metadata": metadata,  # Complete metadata for deep analysis
+            }
+
+            alerts.append(alert_entry)
+
+        return json.dumps({"total": len(alerts), "alerts": alerts}, indent=2, default=str)
+
+    except Exception as e:
+        logger.error(f"Failed to get unified alert history: {e}")
+        return json.dumps(
+            {"error": str(e), "message": "Could not read from smart_email database"}, indent=2
+        )
+
+
+def _format_text_report(report: GuardianReport) -> str:
+    """Format report as text."""
+    lines = ["Guardian Security Report", "=" * 24, ""]
+
+    summary = report.summary
+    lines.append(f"Total Checks: {summary.get('total_checks', 0)}")
+    lines.append(f"Vulnerabilities: {summary.get('total_vulnerabilities', 0)}")
+    lines.append(f"Critical: {summary.get('critical_vulnerabilities', 0)}")
+    lines.append("")
+
+    for check in report.checks:
+        status = "✓" if check.success else "✗"
+        lines.append(f"[{status}] {check.check_type.upper()}")
+
+        for vuln in check.vulnerabilities:
+            lines.append(f"  - [{vuln.severity}] {vuln.summary}")
+            if vuln.description:
+                lines.append(f"    {vuln.description}")
+
+        if check.errors:
+            for error in check.errors:
+                lines.append(f"  ! {error}")
+
+    return "\n".join(lines)
+
+
+def run_mcp_server():
+    """Run the MCP server."""
+    mcp.run()

devguard/metrics.py

@@ -0,0 +1,144 @@
+"""Prometheus metrics exporter for Guardian."""
+
+import logging
+
+from prometheus_client import (
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+    start_http_server,
+)
+
+from devguard.models import GuardianReport
+
+logger = logging.getLogger(__name__)
+
+# Metrics definitions
+check_total = Counter(
+    "devguard_checks_total",
+    "Total number of checks performed",
+    ["check_type", "status"],
+)
+
+check_duration = Histogram(
+    "devguard_check_duration_seconds",
+    "Time spent performing checks",
+    ["check_type"],
+    buckets=[0.1, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0],
+)
+
+vulnerabilities_total = Gauge(
+    "devguard_vulnerabilities_total",
+    "Total number of vulnerabilities",
+    ["check_type", "severity"],
+)
+
+deployments_total = Gauge(
+    "devguard_deployments_total",
+    "Total number of deployments",
+    ["check_type", "status"],
+)
+
+repository_alerts_total = Gauge(
+    "devguard_repository_alerts_total",
+    "Total number of repository alerts",
+    ["check_type", "state"],
+)
+
+# Cost metrics
+service_cost = Gauge(
+    "devguard_service_cost_usd",
+    "Cost for a service in USD",
+    ["service", "period"],
+)
+
+service_usage = Gauge(
+    "devguard_service_usage",
+    "Usage amount for a service",
+    ["service", "unit"],
+)
+
+service_usage_percent = Gauge(
+    "devguard_service_usage_percent",
+    "Usage percentage for a service (0-100)",
+    ["service"],
+)
+
+service_usage_limit = Gauge(
+    "devguard_service_usage_limit",
+    "Usage limit for a service",
+    ["service", "unit"],
+)
+
+check_errors_total = Counter(
+    "devguard_check_errors_total",
+    "Total number of check errors",
+    ["check_type", "error_type"],
+)
+
+
+def update_metrics_from_report(report: GuardianReport) -> None:
+    """Update Prometheus metrics from a Guardian report."""
+    for check in report.checks:
+        # Update check counters
+        status = "success" if check.success else "failure"
+        check_total.labels(check_type=check.check_type, status=status).inc()
+
+        # Update vulnerability metrics
+        for vuln in check.vulnerabilities:
+            vulnerabilities_total.labels(
+                check_type=check.check_type, severity=vuln.severity.value
+            ).inc()
+
+        # Update deployment metrics
+        for deployment in check.deployments:
+            deployments_total.labels(
+                check_type=check.check_type, status=deployment.status.value
+            ).inc()
+
+        # Update repository alert metrics
+        for alert in check.repository_alerts:
+            repository_alerts_total.labels(check_type=check.check_type, state=alert.state).inc()
+
+        # Update cost metrics
+        for cost in check.cost_metrics:
+            if cost.amount is not None:
+                service_cost.labels(service=cost.service, period=cost.period).set(cost.amount)
+
+            if cost.usage is not None:
+                unit = cost.metadata.get("unit", "credits")
+                service_usage.labels(service=cost.service, unit=unit).set(cost.usage)
+
+            if cost.usage_percent is not None:
+                service_usage_percent.labels(service=cost.service).set(cost.usage_percent)
+
+            if cost.limit is not None:
+                unit = cost.metadata.get("unit", "credits")
+                service_usage_limit.labels(service=cost.service, unit=unit).set(cost.limit)
+
+        # Update error metrics
+        for error in check.errors:
+            error_type = "unknown"
+            if "HTTP" in error:
+                error_type = "http"
+            elif "Network" in error or "timeout" in error.lower():
+                error_type = "network"
+            elif "Authentication" in error or "Unauthorized" in error:
+                error_type = "auth"
+            check_errors_total.labels(check_type=check.check_type, error_type=error_type).inc()
+
+
+def get_metrics() -> bytes:
+    """Get Prometheus metrics in text format."""
+    return generate_latest()
+
+
+def start_metrics_server(port: int = 9090) -> None:
+    """Start Prometheus metrics HTTP server."""
+    try:
+        start_http_server(port)
+        logger.info(f"Prometheus metrics server started on port {port}")
+    except OSError as e:
+        logger.error(f"Failed to start metrics server on port {port}: {e}")
+        raise

devguard/models.py

@@ -0,0 +1,208 @@
+"""Data models for Guardian monitoring results."""
+
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Severity(str, Enum):
+    """Vulnerability severity levels."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+    WARNING = "warning"  # For informational findings that aren't vulnerabilities
+
+
+class CheckStatus(str, Enum):
+    """Status of a health check."""
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    UNKNOWN = "unknown"
+    DEGRADED = "degraded"
+
+
+class CostMetric(BaseModel):
+    """Represents cost/usage metrics for a service."""
+
+    service: str  # "vercel", "fly", "firecrawl", "tavily", etc.
+    period: str  # "daily", "monthly", "billing_period"
+    amount: float | None = None  # Cost in USD
+    usage: float | None = None  # Usage amount (credits, requests, etc.)
+    limit: float | None = None  # Usage limit
+    usage_percent: float | None = None  # Usage percentage (0-100)
+    currency: str = "USD"
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Vulnerability(BaseModel):
+    """Represents a security vulnerability."""
+
+    package_name: str
+    package_version: str
+    severity: Severity
+    advisory_id: str | None = None
+    cve_id: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    first_patched_version: str | None = None
+    vulnerable_version_range: str | None = None
+    published_at: datetime | None = None
+    discovered_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    source: str  # "npm", "gh", "snyk", etc.
+    references: list[str] = Field(default_factory=list)  # URLs to documentation/advisories
+
+
+class Finding(BaseModel):
+    """Represents a security finding (more general than a vulnerability).
+
+    Used for IAM issues, configuration problems, and other security concerns
+    that don't fit the package-based vulnerability model.
+    """
+
+    severity: Severity
+    title: str
+    description: str
+    resource: str  # The resource being checked (role name, instance ID, etc.)
+    remediation: str | None = None  # Suggested fix
+    discovered_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class APIUsage(BaseModel):
+    """API usage/credits for a service provider."""
+
+    service: str  # "openrouter", "anthropic", "openai", "perplexity", "groq"
+    credits_total: float | None = None  # Total credits purchased
+    credits_used: float | None = None  # Credits consumed
+    credits_remaining: float | None = None  # Credits left
+    usage_percent: float = 0.0  # Percentage used (0-100)
+    period_start: str | None = None  # Start of usage period
+    period_end: str | None = None  # End of usage period
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class DeploymentStatus(BaseModel):
+    """Status of a deployment."""
+
+    platform: str  # "vercel", "fly"
+    project_name: str
+    deployment_id: str
+    status: CheckStatus
+    url: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    health_check_status: CheckStatus | None = None
+    error_message: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RepositoryAlert(BaseModel):
+    """Security alert from a GitHub repository."""
+
+    repository: str  # "owner/repo"
+    alert_id: int
+    state: str  # "open", "dismissed", "fixed"
+    severity: Severity
+    dependency: dict[str, Any]
+    security_advisory: dict[str, Any]
+    created_at: datetime
+    updated_at: datetime
+    dismissed_at: datetime | None = None
+    fixed_at: datetime | None = None
+
+
+class CheckResult(BaseModel):
+    """Result of a monitoring check."""
+
+    check_type: str  # "npm", "gh", "fly", "vercel", "aws_iam"
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    success: bool
+    vulnerabilities: list[Vulnerability] = Field(default_factory=list)
+    deployments: list[DeploymentStatus] = Field(default_factory=list)
+    repository_alerts: list[RepositoryAlert] = Field(default_factory=list)
+    findings: list[Finding] = Field(default_factory=list)  # General security findings
+    errors: list[str] = Field(default_factory=list)
+    cost_metrics: list[CostMetric] = Field(default_factory=list)
+    api_usage: list[APIUsage] = Field(default_factory=list)  # API credits/usage
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class GuardianReport(BaseModel):
+    """Unified report from all monitoring checks."""
+
+    generated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    checks: list[CheckResult] = Field(default_factory=list)
+    summary: dict[str, Any] = Field(default_factory=dict)
+
+    def get_total_vulnerabilities(self) -> int:
+        """Get total number of vulnerabilities across all checks."""
+        return sum(len(check.vulnerabilities) for check in self.checks)
+
+    def get_critical_vulnerabilities(self) -> list[Vulnerability]:
+        """Get all critical vulnerabilities."""
+        critical = []
+        for check in self.checks:
+            critical.extend([v for v in check.vulnerabilities if v.severity == Severity.CRITICAL])
+        return critical
+
+    def get_unhealthy_deployments(self) -> list[DeploymentStatus]:
+        """Get all unhealthy deployments."""
+        unhealthy = []
+        for check in self.checks:
+            unhealthy.extend([d for d in check.deployments if d.status != CheckStatus.HEALTHY])
+        return unhealthy
+
+    def get_open_repository_alerts(self) -> list[RepositoryAlert]:
+        """Get all open repository security alerts."""
+        open_alerts = []
+        for check in self.checks:
+            open_alerts.extend([a for a in check.repository_alerts if a.state == "open"])
+        return open_alerts
+
+    def get_total_cost(self) -> float:
+        """Get total cost across all services."""
+        total = 0.0
+        for check in self.checks:
+            for cost in check.cost_metrics:
+                if cost.amount is not None:
+                    total += cost.amount
+        return total
+
+    def get_cost_metrics(self) -> list[CostMetric]:
+        """Get all cost metrics."""
+        metrics = []
+        for check in self.checks:
+            metrics.extend(check.cost_metrics)
+        return metrics
+
+    def get_total_findings(self) -> int:
+        """Get total number of findings across all checks."""
+        return sum(len(check.findings) for check in self.checks)
+
+    def get_critical_findings(self) -> list[Finding]:
+        """Get all critical findings."""
+        critical = []
+        for check in self.checks:
+            critical.extend([f for f in check.findings if f.severity == Severity.CRITICAL])
+        return critical
+
+    def get_high_findings(self) -> list[Finding]:
+        """Get all high severity findings."""
+        high = []
+        for check in self.checks:
+            high.extend([f for f in check.findings if f.severity == Severity.HIGH])
+        return high
+
+    def get_findings_by_check(self, check_type: str) -> list[Finding]:
+        """Get all findings from a specific check type."""
+        for check in self.checks:
+            if check.check_type == check_type:
+                return check.findings
+        return []