check-msdefender 1.0.0__py3-none-any.whl

check_msdefender/core/defender.py

@@ -0,0 +1,176 @@
+"""Microsoft Defender API client."""
+
+import time
+import requests
+from typing import Any, Dict, cast
+from check_msdefender.core.exceptions import DefenderAPIError
+from check_msdefender.core.logging_config import get_verbose_logger
+
+
+class DefenderClient:
+    """Client for Microsoft Defender API."""
+
+    application_json = "application/json"
+
+    def __init__(
+        self, authenticator: Any, timeout: int = 5, region: str = "eu3", verbose_level: int = 0
+    ) -> None:
+        """Initialize with authenticator and optional region.
+
+        Args:
+            authenticator: Authentication provider
+            timeout: Request timeout in seconds
+            region: Geographic region (eu, eu3, us, uk)
+            verbose_level: Verbosity level for logging
+        """
+        self.authenticator = authenticator
+        self.timeout = timeout
+        self.region = region
+        self.base_url = self._get_base_url(region)
+        self.logger = get_verbose_logger(__name__, verbose_level)
+
+    def _get_base_url(self, region: str) -> str:
+        """Get base URL for the specified region."""
+        endpoints = {
+            "eu": "https://api-eu.securitycenter.microsoft.com",
+            "eu3": "https://api-eu3.securitycenter.microsoft.com",
+            "us": "https://api.securitycenter.microsoft.com",
+            "uk": "https://api-uk.securitycenter.microsoft.com",
+        }
+        return endpoints.get(region, endpoints["eu3"])
+
+    def get_machine_by_dns_name(self, dns_name: str) -> Dict[str, Any]:
+        """Get machine information by DNS name."""
+        self.logger.method_entry("get_machine_by_dns_name", dns_name=dns_name)
+
+        token = self._get_token()
+
+        url = f"{self.base_url}/api/machines"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": DefenderClient.application_json,
+        }
+
+        params = {"$filter": f"computerDnsName eq '{dns_name}'", "$select": "id"}
+
+        try:
+            start_time = time.time()
+            self.logger.info(f"Querying machine by DNS name: {dns_name}")
+            response = requests.get(url, headers=headers, params=params, timeout=self.timeout)
+            elapsed = time.time() - start_time
+
+            self.logger.api_call("GET", url, response.status_code, elapsed)
+            response.raise_for_status()
+
+            result = cast(Dict[str, Any], response.json())
+            self.logger.json_response(str(result))
+            self.logger.method_exit("get_machine_by_dns_name", result)
+            return result
+        except requests.RequestException as e:
+            self.logger.debug(f"API request failed: {str(e)}")
+            if hasattr(e, "response") and e.response is not None:
+                self.logger.debug(f"Response: {str(e.response.content)}")
+            raise DefenderAPIError(f"Failed to query MS Defender API: {str(e)}")
+
+    def get_machine_by_id(self, machine_id: str) -> Dict[str, Any]:
+        """Get machine information by machine ID."""
+        self.logger.method_entry("get_machine_by_id", machine_id=machine_id)
+
+        token = self._get_token()
+
+        url = f"{self.base_url}/api/machines/{machine_id}"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": DefenderClient.application_json,
+        }
+
+        try:
+            start_time = time.time()
+            self.logger.info(f"Querying machine by ID: {machine_id}")
+            response = requests.get(url, headers=headers, timeout=self.timeout)
+            elapsed = time.time() - start_time
+
+            self.logger.api_call("GET", url, response.status_code, elapsed)
+            response.raise_for_status()
+
+            result = cast(Dict[str, Any], response.json())
+            self.logger.json_response(str(result))
+            self.logger.method_exit("get_machine_by_id", result)
+            return result
+        except requests.RequestException as e:
+            self.logger.debug(f"API request failed: {str(e)}")
+            if hasattr(e, "response") and e.response is not None:
+                self.logger.debug(f"Response: {str(e.response.content)}")
+            raise DefenderAPIError(f"Failed to query MS Defender API: {str(e)}")
+
+    def get_machine_vulnerabilities(self, machine_id: str) -> Dict[str, Any]:
+        """Get vulnerabilities for a machine."""
+        self.logger.method_entry("get_machine_vulnerabilities", machine_id=machine_id)
+
+        token = self._get_token()
+
+        url = f"{self.base_url}/api/machines/{machine_id}/vulnerabilities"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": DefenderClient.application_json,
+        }
+
+        try:
+            start_time = time.time()
+            self.logger.info(f"Querying vulnerabilities for machine: {machine_id}")
+            response = requests.get(url, headers=headers, timeout=self.timeout)
+            elapsed = time.time() - start_time
+
+            self.logger.api_call("GET", url, response.status_code, elapsed)
+            response.raise_for_status()
+
+            result = cast(Dict[str, Any], response.json())
+            self.logger.json_response(str(result))
+            self.logger.method_exit("get_machine_vulnerabilities", result)
+            return result
+        except requests.RequestException as e:
+            self.logger.debug(f"API request failed: {str(e)}")
+            if hasattr(e, "response") and e.response is not None:
+                self.logger.debug(f"Response: {str(e.response.content)}")
+            raise DefenderAPIError(f"Failed to query MS Defender API: {str(e)}")
+
+    def list_machines(self) -> Dict[str, Any]:
+        """Get list of all machines."""
+        self.logger.method_entry("list_machines")
+
+        token = self._get_token()
+
+        url = f"{self.base_url}/api/machines"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": DefenderClient.application_json,
+        }
+
+        params = {"$select": "id,computerDnsName,onboardingStatus,osPlatform"}
+
+        try:
+            start_time = time.time()
+            self.logger.info("Querying all machines")
+            response = requests.get(url, headers=headers, params=params, timeout=self.timeout)
+            elapsed = time.time() - start_time
+
+            self.logger.api_call("GET", url, response.status_code, elapsed)
+            response.raise_for_status()
+
+            result = cast(Dict[str, Any], response.json())
+            self.logger.json_response(str(result))
+            self.logger.method_exit("list_machines", result)
+            return result
+        except requests.RequestException as e:
+            self.logger.debug(f"API request failed: {str(e)}")
+            if hasattr(e, "response") and e.response is not None:
+                self.logger.debug(f"Response: {str(e.response.content)}")
+            raise DefenderAPIError(f"Failed to query MS Defender API: {str(e)}")
+
+    def _get_token(self) -> str:
+        """Get access token from authenticator."""
+        self.logger.trace("Getting access token from authenticator")
+        scope = "https://api.securitycenter.microsoft.com/.default"
+        token = self.authenticator.get_token(scope)
+        self.logger.trace(f"Token acquired successfully (expires: {token.expires_on})")
+        return str(token.token)

check_msdefender/core/exceptions.py

@@ -0,0 +1,31 @@
+"""Custom exceptions for check_msdefender."""
+
+
+class CheckMSDefenderError(Exception):
+    """Base exception for check_msdefender."""
+
+    pass
+
+
+class ConfigurationError(CheckMSDefenderError):
+    """Raised when there's a configuration error."""
+
+    pass
+
+
+class AuthenticationError(CheckMSDefenderError):
+    """Raised when there's an authentication error."""
+
+    pass
+
+
+class DefenderAPIError(CheckMSDefenderError):
+    """Raised when there's an error with the Defender API."""
+
+    pass
+
+
+class ValidationError(CheckMSDefenderError):
+    """Raised when there's a validation error."""
+
+    pass

check_msdefender/core/logging_config.py

@@ -0,0 +1,116 @@
+"""Logging configuration for verbose mode."""
+
+import logging
+import sys
+from typing import Optional, Any
+
+
+class VerboseLogger:
+    """Logger configured for different verbosity levels."""
+
+    def __init__(self, name: str, verbose_level: int = 0):
+        """Initialize logger with verbosity level.
+
+        Args:
+            name: Logger name
+            verbose_level: Verbosity level (0=none, 1=info, 2=debug, 3+=trace)
+        """
+        self.logger = logging.getLogger(name)
+        self.verbose_level = verbose_level
+        self._configure_logger()
+
+    def _configure_logger(self) -> None:
+        """Configure logger based on verbosity level."""
+        # Clear any existing handlers
+        self.logger.handlers.clear()
+
+        if self.verbose_level == 0:
+            # No verbose logging
+            self.logger.setLevel(logging.WARNING)
+            return
+
+        # Create console handler
+        handler = logging.StreamHandler(sys.stderr)
+
+        # Set format based on verbosity
+        if self.verbose_level >= 3:
+            # Full trace format
+            formatter = logging.Formatter(
+                "[%(levelname)s] %(asctime)s %(name)s:%(lineno)d - %(message)s", datefmt="%H:%M:%S"
+            )
+        elif self.verbose_level >= 2:
+            # Debug format
+            formatter = logging.Formatter("[%(levelname)s] %(name)s - %(message)s")
+        else:
+            # Basic format
+            formatter = logging.Formatter("%(message)s")
+
+        handler.setFormatter(formatter)
+        self.logger.addHandler(handler)
+
+        # Set level based on verbosity
+        if self.verbose_level >= 3:
+            self.logger.setLevel(logging.DEBUG)
+        elif self.verbose_level >= 2:
+            self.logger.setLevel(logging.DEBUG)
+        else:
+            self.logger.setLevel(logging.INFO)
+
+    def info(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log info message if verbose >= 1."""
+        if self.verbose_level >= 1:
+            self.logger.info(message, *args, **kwargs)
+
+    def debug(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log debug message if verbose >= 2."""
+        if self.verbose_level >= 2:
+            self.logger.debug(message, *args, **kwargs)
+
+    def trace(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log trace message if verbose >= 3."""
+        if self.verbose_level >= 3:
+            self.logger.debug(f"TRACE: {message}", *args, **kwargs)
+
+    def api_call(
+        self,
+        method: str,
+        url: str,
+        status_code: Optional[int] = None,
+        response_time: Optional[float] = None,
+    ) -> None:
+        """Log API call details if verbose >= 2."""
+        if self.verbose_level >= 2:
+            if status_code and response_time:
+                self.logger.debug(f"API {method} {url} -> {status_code} ({response_time:.3f}s)")
+            else:
+                self.logger.debug(f"API {method} {url}")
+
+    def json_response(self, data: str) -> None:
+        """Log JSON response if verbose >= 2."""
+        if self.verbose_level >= 2:
+            self.logger.debug(f"JSON Response: {data}")
+
+    def method_entry(self, method_name: str, **kwargs: Any) -> None:
+        """Log method entry if verbose >= 3."""
+        if self.verbose_level >= 3:
+            args_str = ", ".join(f"{k}={v}" for k, v in kwargs.items())
+            self.logger.debug(f"TRACE: -> {method_name}({args_str})")
+
+    def method_exit(self, method_name: str, result: Any = None) -> None:
+        """Log method exit if verbose >= 3."""
+        if self.verbose_level >= 3:
+            result_str = f" = {result}" if result is not None else ""
+            self.logger.debug(f"TRACE: <- {method_name}{result_str}")
+
+
+def get_verbose_logger(name: str, verbose_level: int = 0) -> VerboseLogger:
+    """Get a configured verbose logger.
+
+    Args:
+        name: Logger name (typically __name__)
+        verbose_level: Verbosity level from CLI
+
+    Returns:
+        Configured VerboseLogger instance
+    """
+    return VerboseLogger(name, verbose_level)

check_msdefender/core/nagios.py

@@ -0,0 +1,169 @@
+"""Nagios plugin implementation."""
+
+import nagiosplugin
+from typing import List, Optional, Union, Any
+
+
+class DefenderScalarContext(nagiosplugin.ScalarContext):
+    """Custom scalar context with modified threshold logic for detail command."""
+
+    def __init__(
+        self,
+        name: str,
+        warning: Optional[Union[float, int]] = None,
+        critical: Optional[Union[float, int]] = None,
+    ) -> None:
+        """Initialize with custom threshold logic."""
+        # Store original values to know what was actually set
+        self._original_warning = warning
+        self._original_critical = critical
+        super().__init__(name, warning, critical)
+
+    def evaluate(
+        self, metric: nagiosplugin.Metric, resource: nagiosplugin.Resource
+    ) -> nagiosplugin.Result:
+        """Evaluate metric against thresholds with <= logic for detail command."""
+        if self.name == "found":
+            # For detail command, use <= threshold logic (not < threshold)
+            # Use original values instead of Range objects for threshold comparison
+            critical_val = self._original_critical
+            warning_val = self._original_warning
+
+            # Check most restrictive threshold first
+            warning_triggered = (
+                self._original_warning is not None
+                and warning_val is not None
+                and metric.value <= warning_val
+            )
+            critical_triggered = (
+                self._original_critical is not None
+                and critical_val is not None
+                and metric.value <= critical_val
+            )
+
+            if critical_triggered and warning_triggered:
+                # Both triggered - determine priority based on which threshold is more restrictive
+                # For this application, choose the threshold that equals the metric value
+                if warning_val == metric.value:
+                    return self.result_cls(
+                        nagiosplugin.Warn,
+                        f"{metric.name} is {metric.value} (outside range {warning_val}:)",
+                        metric,
+                    )
+                elif critical_val == metric.value:
+                    return self.result_cls(
+                        nagiosplugin.Critical,
+                        f"{metric.name} is {metric.value} (outside range {critical_val}:)",
+                        metric,
+                    )
+                else:
+                    # If no exact match, use the more severe one (critical)
+                    return self.result_cls(
+                        nagiosplugin.Critical,
+                        f"{metric.name} is {metric.value} (outside range {critical_val}:)",
+                        metric,
+                    )
+            elif critical_triggered:
+                return self.result_cls(
+                    nagiosplugin.Critical,
+                    f"{metric.name} is {metric.value} (outside range {critical_val}:)",
+                    metric,
+                )
+            elif warning_triggered:
+                return self.result_cls(
+                    nagiosplugin.Warn,
+                    f"{metric.name} is {metric.value} (outside range {warning_val}:)",
+                    metric,
+                )
+            else:
+                return self.result_cls(nagiosplugin.Ok, None, metric)
+        else:
+            # For other commands, use standard threshold logic
+            return super().evaluate(metric, resource)
+
+
+class DefenderSummary(nagiosplugin.Summary):
+    """Custom summary class for detailed Nagios output."""
+
+    def __init__(self, details: Optional[List[str]]) -> None:
+        """Initialize with detailed output lines."""
+        self.details = details or []
+
+    def ok(self, results: nagiosplugin.Results) -> str:
+        """Return detailed output for OK state."""
+        return self._format_details()
+
+    def problem(self, results: nagiosplugin.Results) -> str:
+        """Return detailed output for problem states (WARNING, CRITICAL)."""
+        return self._format_details()
+
+    def _format_details(self) -> str:
+        """Format details for output."""
+        if not self.details:
+            return ""
+        return "\n" + "\n".join(self.details)
+
+
+class NagiosPlugin:
+    """Nagios plugin for Microsoft Defender monitoring."""
+
+    def __init__(self, service: Any, command_name: str) -> None:
+        """Initialize with a service and command name."""
+        self.service = service
+        self.command_name = command_name
+
+    def check(
+        self,
+        machine_id: Optional[str] = None,
+        dns_name: Optional[str] = None,
+        warning: Optional[Union[float, int]] = None,
+        critical: Optional[Union[float, int]] = None,
+        verbose: int = 0,
+    ) -> int:
+        """Execute the check and return Nagios exit code."""
+        try:
+            result = self.service.get_result(machine_id=machine_id, dns_name=dns_name)
+            value = result["value"]
+            details = result.get("details", [])
+
+            # Create Nagios check with custom summary
+            # Use 'found' as context name for detail command, otherwise use command name
+            context_name = "found" if self.command_name == "detail" else self.command_name
+            check = nagiosplugin.Check(
+                DefenderResource(self.command_name, value),
+                DefenderScalarContext(context_name, warning, critical),
+                DefenderSummary(details),
+            )
+
+            # Set verbosity
+            check.verbosity = verbose
+
+            # Run check and return exit code instead of exiting
+            try:
+                check.main()
+                return 0  # If main() doesn't exit, it's OK
+            except SystemExit as e:
+                return int(e.code) if e.code is not None else 0
+
+        except Exception as e:
+            print(f"UNKNOWN: {str(e)}")
+            return 3
+
+
+class DefenderResource(nagiosplugin.Resource):
+    """Defender resource for getting values with custom service name."""
+
+    def __init__(self, command_name: str, value: Union[int, float]) -> None:
+        super().__init__()
+        self.command_name = command_name
+        self.value = value
+
+    @property
+    def name(self) -> str:
+        """Return custom service name."""
+        return "DEFENDER"
+
+    def probe(self) -> List[nagiosplugin.Metric]:
+        # Use 'found' as metric name for detail command, otherwise use command name
+        metric_name = "found" if self.command_name == "detail" else self.command_name
+        return [nagiosplugin.Metric(metric_name, self.value)]

check_msdefender/services/__init__.py

@@ -0,0 +1 @@
+"""Services module for check_msdefender."""

check_msdefender/services/detail_service.py

@@ -0,0 +1,77 @@
+"""Detail service implementation."""
+
+import json
+from typing import Dict, Optional, Any
+from check_msdefender.core.exceptions import ValidationError
+from check_msdefender.core.logging_config import get_verbose_logger
+
+
+class DetailService:
+    """Service for getting machine details."""
+
+    def __init__(self, defender_client: Any, verbose_level: int = 0) -> None:
+        """Initialize with Defender client."""
+        self.defender = defender_client
+        self.logger = get_verbose_logger(__name__, verbose_level)
+
+    def get_result(
+        self, machine_id: Optional[str] = None, dns_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Get machine details result with value and details.
+
+        Returns:
+            dict: Result with value (1 or 0) and details list
+        """
+        self.logger.method_entry("get_result", machine_id=machine_id, dns_name=dns_name)
+
+        if not machine_id and not dns_name:
+            raise ValidationError("Either machine_id or dns_name must be provided")
+
+        try:
+            # Get machine information
+            if dns_name:
+                self.logger.info(f"Fetching machine data by DNS name: {dns_name}")
+                machines_data = self.defender.get_machine_by_dns_name(dns_name)
+                if not machines_data.get("value"):
+                    self.logger.info(f"Machine not found with DNS name: {dns_name}")
+                    result = {
+                        "value": 0,
+                        "details": [f"Machine not found with DNS name: {dns_name}"],
+                    }
+                    self.logger.method_exit("get_result", result)
+                    return result
+                machine_data = machines_data["value"][0]
+                self.logger.debug(f"Found machine: {machine_data.get('id', 'unknown')}")
+                machine_id = machine_data.get("id")
+
+            # Get detailed machine information by ID
+            self.logger.info(f"Fetching detailed machine data by ID: {machine_id}")
+            machine_details = self.defender.get_machine_by_id(machine_id)
+
+            # Store the details for output formatting
+            self._machine_details = machine_details
+
+            # Create detailed output
+            details = []
+            details.append(f"Machine ID: {machine_details.get('id', 'Unknown')}")
+            details.append(f"Computer Name: {machine_details.get('computerDnsName', 'Unknown')}")
+            details.append(f"OS Platform: {machine_details.get('osPlatform', 'Unknown')}")
+            details.append(f"OS Version: {machine_details.get('osVersion', 'Unknown')}")
+            details.append(f"Health Status: {machine_details.get('healthStatus', 'Unknown')}")
+            details.append(f"Risk Score: {machine_details.get('riskScore', 'Unknown')}")
+
+            result = {"value": 1, "details": details}
+
+            self.logger.info(f"Machine details retrieved successfully")
+            self.logger.method_exit("get_result", result)
+            return result
+
+        except Exception as e:
+            self.logger.debug(f"Failed to get machine details: {str(e)}")
+            raise
+
+    def get_machine_details_json(self) -> Optional[str]:
+        """Get the machine details as formatted JSON string."""
+        if not hasattr(self, "_machine_details"):
+            return None
+        return json.dumps(self._machine_details, indent=2)

check_msdefender/services/lastseen_service.py

@@ -0,0 +1,70 @@
+"""Last seen service implementation."""
+
+import re
+from datetime import datetime
+from typing import Dict, Optional, Any
+from check_msdefender.core.exceptions import ValidationError
+from check_msdefender.core.logging_config import get_verbose_logger
+
+
+class LastSeenService:
+    """Service for checking last seen status."""
+
+    def __init__(self, defender_client: Any, verbose_level: int = 0) -> None:
+        """Initialize with Defender client."""
+        self.defender = defender_client
+        self.logger = get_verbose_logger(__name__, verbose_level)
+
+    def get_result(
+        self, machine_id: Optional[str] = None, dns_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Get last seen result with value and details for a machine."""
+        self.logger.method_entry("get_result", machine_id=machine_id, dns_name=dns_name)
+
+        if not machine_id and not dns_name:
+            raise ValidationError("Either machine_id or dns_name must be provided")
+
+        # Get machine information
+        if dns_name:
+            self.logger.info(f"Fetching machine data by DNS name: {dns_name}")
+            machines_data = self.defender.get_machine_by_dns_name(dns_name)
+            if not machines_data.get("value"):
+                raise ValidationError(f"Machine not found with DNS name: {dns_name}")
+            machine_data = machines_data["value"][0]
+            self.logger.debug(f"Found machine: {machine_data.get('id', 'unknown')}")
+            machine_id = machine_data.get("id")
+
+        # Extract last seen timestamp
+        machine_details = self.defender.get_machine_by_id(machine_id)
+        last_seen_str = machine_details.get("lastSeen")
+        if not last_seen_str:
+            raise ValidationError("No lastSeen data available for machine")
+
+        self.logger.debug(f"Last seen timestamp from API: {last_seen_str}")
+
+        # Parse timestamp and calculate days difference
+        try:
+            # Handle high-precision microseconds by truncating to 6 digits
+            timestamp_str = last_seen_str.replace("Z", "+00:00")
+            # Regex to find and truncate microseconds longer than 6 digits
+            timestamp_str = re.sub(r"\.(\d{6})\d+", r".\1", timestamp_str)
+
+            last_seen = datetime.fromisoformat(timestamp_str)
+            now = datetime.now(last_seen.tzinfo)
+            days_diff = (now - last_seen).days
+
+            # Create detailed output
+            computer_name = machine_details.get("computerDnsName", "Unknown")
+            last_seen_formatted = last_seen.strftime("%Y-%m-%d %H:%M:%S %Z")
+            details = [
+                f"Machine: {computer_name} - Last seen {days_diff} days ago ({last_seen_formatted})"
+            ]
+
+            result = {"value": days_diff, "details": details}
+
+            self.logger.info(f"Machine last seen {days_diff} days ago ({last_seen_str})")
+            self.logger.method_exit("get_result", result)
+            return result
+        except (ValueError, TypeError) as e:
+            self.logger.debug(f"Failed to parse timestamp: {str(e)}")
+            raise ValidationError(f"Invalid lastSeen timestamp: {str(e)}")