check-msdefender 1.0.0__tar.gz → 1.1.0__tar.gz

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/.claude/settings.local.json

@@ -10,7 +10,8 @@
       "Bash(python:*)",
       "Bash(find:*)",
       "Bash(echo \"Exit code: $?\")",
-      "Bash(mypy:*)"
+      "Bash(mypy:*)",
+      "Bash(black:*)"
     ],
     "deny": [],
     "ask": []

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: check-msdefender
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Nagios plugin for monitoring Microsoft Defender API endpoints
 Author-email: ldvchosal <ldvchosal@github.com>
 License: MIT

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/check_msdefender/cli/commands/__init__.py

@@ -6,6 +6,7 @@ from .vulnerabilities import register_vulnerability_commands
 from .onboarding import register_onboarding_commands
 from .machines import register_machines_commands
 from .detail import register_detail_commands
+from .alerts import register_alerts_commands
 
 
 def register_all_commands(main_group: Any) -> None:
@@ -15,3 +16,4 @@ def register_all_commands(main_group: Any) -> None:
     register_onboarding_commands(main_group)
     register_machines_commands(main_group)
     register_detail_commands(main_group)
+    register_alerts_commands(main_group)

check_msdefender-1.1.0/check_msdefender/cli/commands/alerts.py

@@ -0,0 +1,61 @@
+"""Alerts commands for CLI."""
+
+import sys
+import click
+from typing import Optional, Any
+
+from check_msdefender.core.auth import get_authenticator
+from check_msdefender.core.config import load_config
+from check_msdefender.core.defender import DefenderClient
+from check_msdefender.core.nagios import NagiosPlugin
+from check_msdefender.services.alerts_service import AlertsService
+from ..decorators import common_options
+
+
+def register_alerts_commands(main_group: Any) -> None:
+    """Register alerts commands with the main CLI group."""
+
+    @main_group.command("alerts")
+    @common_options
+    def alerts_cmd(
+        config: str,
+        verbose: int,
+        machine_id: Optional[str],
+        dns_name: Optional[str],
+        warning: Optional[float],
+        critical: Optional[float],
+    ) -> None:
+        """Check alerts for Microsoft Defender."""
+        warning = warning if warning is not None else 1
+        critical = critical if critical is not None else 0
+
+        try:
+            # Load configuration
+            cfg = load_config(config)
+
+            # Get authenticator
+            authenticator = get_authenticator(cfg)
+
+            # Create Defender client
+            client = DefenderClient(authenticator, verbose_level=verbose)
+
+            # Create the alerts service
+            service = AlertsService(client, verbose_level=verbose)
+
+            # Create Nagios plugin
+            plugin = NagiosPlugin(service, "alerts")
+
+            # Execute check
+            result = plugin.check(
+                machine_id=machine_id,
+                dns_name=dns_name,
+                warning=warning,
+                critical=critical,
+                verbose=verbose,
+            )
+
+            sys.exit(result or 0)
+
+        except Exception as e:
+            print(f"UNKNOWN: {str(e)}")
+            sys.exit(3)

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/check_msdefender/core/defender.py

@@ -167,6 +167,44 @@ class DefenderClient:
                 self.logger.debug(f"Response: {str(e.response.content)}")
             raise DefenderAPIError(f"Failed to query MS Defender API: {str(e)}")
 
+    def get_alerts(self) -> Dict[str, Any]:
+        """Get alerts from Microsoft Defender."""
+        self.logger.method_entry("get_alerts")
+
+        token = self._get_token()
+
+        url = f"{self.base_url}/api/alerts"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": DefenderClient.application_json,
+        }
+
+        params = {
+            "$top": "100",
+            "$expand": "evidence",
+            "$orderby": "alertCreationTime desc",
+            "$select": "status,title,machineId,computerDnsName,alertCreationTime,firstEventTime,lastEventTime,lastUpdateTime,severity",
+        }
+
+        try:
+            start_time = time.time()
+            self.logger.info("Querying alerts")
+            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_alerts", 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")

check_msdefender-1.1.0/check_msdefender/services/alerts_service.py

@@ -0,0 +1,98 @@
+"""Alerts service implementation."""
+
+from datetime import datetime
+from typing import Dict, Optional, Any, List
+from check_msdefender.core.exceptions import ValidationError
+from check_msdefender.core.logging_config import get_verbose_logger
+
+
+class AlertsService:
+    """Service for checking machine alerts."""
+
+    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 alerts 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
+        target_dns_name = dns_name
+        target_machine_id = machine_id
+
+        if machine_id:
+            # Get DNS name from machine_id
+            machine_details = self.defender.get_machine_by_id(machine_id)
+            target_dns_name = machine_details.get("computerDnsName", "Unknown")
+        elif dns_name:
+            # Get machine_id from dns_name
+            dns_response = self.defender.get_machine_by_dns_name(dns_name)
+            machines = dns_response.get("value", [])
+            if not machines:
+                raise ValidationError(f"Machine not found with DNS name: {dns_name}")
+            target_machine_id = machines[0].get("id")
+            target_dns_name = dns_name
+
+        # Get all alerts
+        self.logger.info("Fetching alerts from Microsoft Defender")
+        alerts_data = self.defender.get_alerts()
+        all_alerts = alerts_data.get("value", [])
+
+        # Filter alerts for the specific machine
+        machine_alerts = [
+            alert
+            for alert in all_alerts
+            if alert.get("machineId") == target_machine_id
+            or alert.get("computerDnsName") == target_dns_name
+        ]
+
+        self.logger.info(f"Found {len(machine_alerts)} alerts for machine {target_dns_name}")
+
+        # Categorize alerts by status and severity
+        unresolved_alerts = [alert for alert in machine_alerts if alert.get("status") != "Resolved"]
+        informational_alerts = [
+            alert for alert in unresolved_alerts if alert.get("severity") == "Informational"
+        ]
+        critical_warning_alerts = [
+            alert
+            for alert in unresolved_alerts
+            if alert.get("severity") in ["High", "Medium", "Low"]
+        ]
+
+        # Create details for output
+        details = []
+        if unresolved_alerts:
+            summary_line = f"Unresolved alerts for {target_dns_name}"
+            if informational_alerts and not critical_warning_alerts:
+                summary_line = f"Unresolved informational alerts for {target_dns_name}"
+            elif critical_warning_alerts:
+                summary_line = f"Unresolved alerts for {target_dns_name}"
+            details.append(summary_line)
+
+            # Add individual alerts (limit to 10)
+            for alert in unresolved_alerts[:10]:
+                creation_time = alert.get("alertCreationTime", "Unknown")
+                title = alert.get("title", "Unknown alert")
+                status = alert.get("status", "Unknown")
+                severity = alert.get("severity", "Unknown")
+                details.append(f"{creation_time} - {title} ({status} {severity.lower()})")
+
+        # Return the number of unresolved alerts as the value
+        # This will be used by Nagios plugin for determining status based on thresholds
+        value = len(unresolved_alerts)
+
+        result = {
+            "value": value,
+            "details": details,
+        }
+
+        self.logger.info(f"Alert analysis complete: {len(unresolved_alerts)} unresolved alerts")
+        self.logger.method_exit("get_result", result)
+        return result

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/check_msdefender.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: check-msdefender
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Nagios plugin for monitoring Microsoft Defender API endpoints
 Author-email: ldvchosal <ldvchosal@github.com>
 License: MIT

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/check_msdefender.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ check_msdefender/cli/__main__.py
 check_msdefender/cli/decorators.py
 check_msdefender/cli/handlers.py
 check_msdefender/cli/commands/__init__.py
+check_msdefender/cli/commands/alerts.py
 check_msdefender/cli/commands/detail.py
 check_msdefender/cli/commands/lastseen.py
 check_msdefender/cli/commands/machines.py
@@ -47,6 +48,7 @@ check_msdefender/core/exceptions.py
 check_msdefender/core/logging_config.py
 check_msdefender/core/nagios.py
 check_msdefender/services/__init__.py
+check_msdefender/services/alerts_service.py
 check_msdefender/services/detail_service.py
 check_msdefender/services/lastseen_service.py
 check_msdefender/services/machines_service.py
@@ -58,6 +60,7 @@ doc/Feat-Click-Groups.md
 doc/Feat-Enhance-MsDefender-Vulnerabilities-Output.md
 doc/Feat-Fixture-Tests.md
 doc/Feat-Integration-Tests.md
+doc/Feat-MsDefender-Alerts.md
 doc/Feat-MsDefender-DetailMachine.md
 doc/Feat-MsDefender-ListMachines.md
 doc/Feat-MsDefender.md

check_msdefender-1.1.0/doc/Feat-MsDefender-Alerts.md

@@ -0,0 +1,116 @@
+# Alerts Machine Feature
+
+Get detailed machine alerts from Microsoft Defender.
+
+## API Endpoint
+- Base URL: `https://api.securitycenter.microsoft.com`
+- Endpoint: `/api/alerts`
+- Method: GET
+- Authentication: Bearer token (Azure AD)
+
+## Implementation
+
+### Command Structure
+```bash
+check_msdefender alerts -i <machine_id>
+check_msdefender alerts -d <dns_name>
+```
+
+### Service Class: `AlertsService`
+Location: `check_msdefender/services/alerts_service.py`
+
+**Methods:**
+- `get_alerts(machine_id=None, dns_name=None)` - Returns machine alerts
+- Inherits from base service pattern like `LastSeenService`
+
+### CLI Command: `alerts`
+Location: `check_msdefender/cli/commands/alerts.py`
+
+**Pattern follows existing commands:**
+- Uses `@common_options` decorator
+- Creates `DefenderClient` and `AlertsService`
+- Uses `NagiosPlugin` for output formatting
+
+### API Client Method
+Location: `check_msdefender/core/defender.py`
+- `get_alerts()`
+- Returns full alerts details JSON
+
+https://api.securitycenter.microsoft.com/api/alerts?$top=100&$expand=evidence&$orderby=alertCreationTime desc&$select=status,title,machineId,computerDnsName,alertCreationTime,firstEventTime,lastEventTime,lastUpdateTime
+
+https://api.securitycenter.microsoft.com
+/api/alerts
+$top=100
+$expand=evidence
+$orderby=alertCreationTime desc
+$select=status,title,machineId,computerDnsName,alertCreationTime,firstEventTime,lastEventTime,lastUpdateTime,severity
+
+```json
+{
+  "@odata.context": "https://api-eu3.securitycenter.microsoft.com/api/$metadata#Alerts(status,title,machineId,computerDnsName,alertCreationTime,firstEventTime,lastEventTime,lastUpdateTime,severity)",
+  "value": [
+    {
+      "severity": "Informational",
+      "status": "New",
+      "title": "Automated investigation started manually",
+      "alertCreationTime": "2025-09-12T21:22:14.12Z",
+      "firstEventTime": "2025-09-12T21:22:13.7175652Z",
+      "lastEventTime": "2025-09-12T21:22:13.7175652Z",
+      "lastUpdateTime": "2025-09-13T01:24:04.42Z",
+      "machineId": "89xxxxxxxxxxxxxxxxxxxxxxx41f",
+      "computerDnsName": "machine.domain.tld"
+    },
+    {
+      "severity": "Informational",
+      "status": "Resolved",
+      "title": "Automated investigation started manually",
+      "alertCreationTime": "2025-09-11T15:25:38.54Z",
+      "firstEventTime": "2025-09-11T15:25:38.1183588Z",
+      "lastEventTime": "2025-09-11T15:25:38.1183588Z",
+      "lastUpdateTime": "2025-09-12T11:05:46.9966667Z",
+      "machineId": "89xxxxxxxxxxxxxxxxxxxxxxx41f",
+      "computerDnsName": "machine.domain.tld"
+    }
+  ]
+}
+```
+
+## Output Format
+
+### Success (Machine Found)
+```
+DEFENDER WARNING - Unresolved informational alerts for machine.domain.tld | alerts=3;0;0
+2025-09-12T21:22:14.12Z - Automated investigation started manually (New informational)
+alertCreationTime - Alert title (status severity)
+alertCreationTime - Alert title (status severity)
+```
+
+### Failure States
+- **Warning**: `DEFENDER WARNING - Unresolved informational alerts | alerts=0;0;1` 
+- **Critical**: `DEFENDER CRITICAL - Unresolved alerts | alerts=0;1;0`
+- **Unknown**: `DEFENDER UNKNOWN - API error: <message>` (API failures)
+
+## Nagios Integration
+- **OK**: No unresolved or alerts
+- **WARNING**: Unresolved informational alerts 
+- **CRITICAL**: Unresolved alerts
+- **UNKNOWN**: API errors, authentication failures, network issues
+
+## File Structure
+```
+check_msdefender/
+├── cli/commands/alerts.py          # CLI command implementation
+├── services/alerts_service.py      # Business logic service
+└── core/defender.py               # API client (get_machine_by_id exists)
+```
+
+## Tests
+- Test units
+- Integration tests
+- Fixture tests
+
+## validation
+- black
+- flake8
+- mypy
+- pytest

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "check-msdefender"
-version = "1.0.0"
+version = "1.1.0"
 authors = [
     {name = "ldvchosal", email = "ldvchosal@github.com"},
 ]

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/tests/fixtures/machine_data.json

@@ -44,6 +44,21 @@
       "rbacGroupId": 789,
       "riskScore": "High",
       "onboardingStatus": "Unknown"
+    },
+    "test-machine-4": {
+      "id": "test-machine-4",
+      "computerDnsName": "test-machine-4.domain.com",
+      "lastSeen": "2024-01-08T12:00:00Z",
+      "osPlatform": "Windows11",
+      "version": "22H2",
+      "osProcessor": "x64",
+      "lastIpAddress": "192.168.1.103",
+      "lastExternalIpAddress": "203.0.113.4",
+      "healthStatus": "Active",
+      "deviceValue": "Normal",
+      "rbacGroupId": 999,
+      "riskScore": "Low",
+      "onboardingStatus": "Onboarded"
     }
   },
   "machine_by_dns": {
@@ -61,6 +76,13 @@
         }
       ]
     },
+    "test-machine-3.domain.com": {
+      "value": [
+        {
+          "id": "test-machine-3"
+        }
+      ]
+    },
     "nonexistent.domain.com": {
       "value": []
     }

{check_msdefender-1.0.0 → check_msdefender-1.1.0}/tests/fixtures/mock_defender_client.py

@@ -21,6 +21,10 @@ class MockDefenderClient:
         with open(fixtures_dir / "vulnerability_data.json") as f:
             self.vulnerability_data = json.load(f)
 
+        # Load alerts data
+        with open(fixtures_dir / "alerts_data.json") as f:
+            self.alerts_data = json.load(f)
+
     def get_machine_by_id(self, machine_id):
         """Get machine by ID from fixtures."""
         machine = self.machine_data["machine_by_id"].get(machine_id)
@@ -35,3 +39,7 @@ class MockDefenderClient:
     def get_machine_vulnerabilities(self, machine_id):
         """Get vulnerabilities for machine from fixtures."""
         return self.vulnerability_data["vulnerabilities_by_machine"].get(machine_id, {"value": []})
+
+    def get_alerts(self):
+        """Get all alerts from fixtures."""
+        return self.alerts_data["alerts"]