check-msdefender 1.1.17

A Nagios plugin for monitoring Microsoft Defender API endpoints

🛡️ Check MS Defender

A comprehensive Nagios plugin for monitoring Microsoft Defender for Endpoint API endpoints. Built with modern Python practices and designed for enterprise monitoring environments.

✨ Features

• 🔐 Dual Authentication - Support for Client Secret and Certificate-based authentication
• 🎯 Multiple Endpoints - Monitor onboarding status, last seen, vulnerabilities, products with CVEs, alerts, and machine details
• 📊 Nagios Compatible - Standard exit codes and performance data output
• 🏗️ Clean Architecture - Modular design with testable components
• 🔧 Flexible Configuration - File-based configuration with sensible defaults
• 📈 Verbose Logging - Multi-level debugging support
• 🐍 Modern Python - Built with Python 3.9+ using type hints and async patterns

🚀 Quick Start

Installation

# Create virtual environment (recommended)
python -m venv /usr/local/libexec/nagios/check_msdefender
source /usr/local/libexec/nagios/check_msdefender/bin/activate

# Install from source
pip install git+https://github.com/lduchosal/check_msdefender.git

Basic Usage

# Check machine onboarding status
check_msdefender onboarding -d machine.domain.tld

# Check last seen (with custom thresholds)
check_msdefender lastseen -d machine.domain.tld -W 7 -C 30

# Check vulnerabilities
check_msdefender vulnerabilities -d machine.domain.tld -W 10 -C 100

# Check products with CVE vulnerabilities
check_msdefender products -d machine.domain.tld -W 5 -C 1

# Check alerts
check_msdefender alerts -d machine.domain.tld -W 1 -C 5

# List all machines
check_msdefender machines

# Get detailed machine info
check_msdefender detail -d machine.domain.tld

📋 Available Commands

Command	Description	Default Thresholds
onboarding	Check machine onboarding status	W:1, C:2
lastseen	Days since machine last seen	W:7, C:30
vulnerabilities	Vulnerability score calculation	W:10, C:100
products	Count of vulnerable software with CVEs	W:5, C:1
alerts	Count of unresolved alerts	W:1, C:0
machines	List all machines	W:10, C:25
detail	Get detailed machine information	-

Vulnerability Scoring

The vulnerability score is calculated as:

• Critical vulnerabilities × 100
• High vulnerabilities × 10
• Medium vulnerabilities × 5
• Low vulnerabilities × 1

Products CVE Monitoring

The products command monitors installed software with known CVE vulnerabilities:

• Groups CVEs by software (name, version, vendor)
• Shows CVE details including severity levels and disk paths
• Counts vulnerable software (not individual CVEs)
• Default thresholds: Warning at 5 vulnerable software, Critical at 1
• Displays up to 10 software entries with first 5 CVEs per software

Alert Monitoring

The alerts command monitors unresolved security alerts for a machine:

• Counts only unresolved alerts (status ≠ "Resolved")
• Excludes informational alerts when critical/warning alerts exist
• Shows alert details including creation time, title, and severity
• Default thresholds: Warning at 1 alert, Critical at 0 (meaning any alert triggers warning)

Onboarding Status Values

• 0 - Onboarded ✅
• 1 - InsufficientInfo ⚠️
• 2 - Unknown ❌

⚙️ Configuration

Authentication Setup

Create check_msdefender.ini in your Nagios directory or current working directory:

Client Secret Authentication

[auth]
client_id = your-application-client-id
client_secret = your-client-secret
tenant_id = your-azure-tenant-id

[settings]
timeout = 5

Certificate Authentication

[auth]
client_id = your-application-client-id
tenant_id = your-azure-tenant-id
certificate_path = /path/to/certificate.pem
private_key_path = /path/to/private_key.pem

[settings]
timeout = 5

Microsoft Defender API Setup

1. Register Application in Azure Active Directory
2. Grant API Permissions:
   • Machine.Read.All
   • Vulnerability.Read
   • Vulnerability.Read.All
   • Alert.Read.All
3. Create Authentication (Secret or Certificate)
4. Note Credentials (Client ID, Tenant ID, Secret/Certificate)

📚 Complete API Setup Guide

🔧 Command Line Options

Option	Description	Example
-c, --config	Configuration file path	-c /custom/path/config.ini
-m, --machineId	Machine ID (GUID)	-m "12345678-1234-1234-1234-123456789abc"
-d, --computerDnsName	Computer DNS Name (FQDN)	-d "server.domain.com"
-W, --warning	Warning threshold	-W 10
-C, --critical	Critical threshold	-C 100
-v, --verbose	Verbosity level	-v, -vv, -vvv
--version	Show version	--version

🏢 Nagios Integration

Command Definitions

# Microsoft Defender Commands
define command {
    command_name    check_defender_onboarding
    command_line    $USER1$/check_msdefender/bin/check_msdefender onboarding -d $HOSTALIAS$
}

define command {
    command_name    check_defender_lastseen
    command_line    $USER1$/check_msdefender/bin/check_msdefender lastseen -d $HOSTALIAS$ -W 7 -C 30
}

define command {
    command_name    check_defender_vulnerabilities
    command_line    $USER1$/check_msdefender/bin/check_msdefender vulnerabilities -d $HOSTALIAS$ -W 10 -C 100
}

define command {
    command_name    check_defender_products
    command_line    $USER1$/check_msdefender/bin/check_msdefender products -d $HOSTALIAS$ -W 5 -C 1
}

define command {
    command_name    check_defender_alerts
    command_line    $USER1$/check_msdefender/bin/check_msdefender alerts -d $HOSTALIAS$ -W 1 -C 5
}

Service Definitions

# Microsoft Defender Services
define service {
    use                     generic-service
    service_description     DEFENDER_ONBOARDING
    check_command           check_defender_onboarding
    hostgroup_name          msdefender
}

define service {
    use                     generic-service
    service_description     DEFENDER_LASTSEEN
    check_command           check_defender_lastseen
    hostgroup_name          msdefender
}

define service {
    use                     generic-service
    service_description     DEFENDER_VULNERABILITIES
    check_command           check_defender_vulnerabilities
    hostgroup_name          msdefender
}

define service {
    use                     generic-service
    service_description     DEFENDER_PRODUCTS
    check_command           check_defender_products
    hostgroup_name          msdefender
}

define service {
    use                     generic-service
    service_description     DEFENDER_ALERTS
    check_command           check_defender_alerts
    hostgroup_name          msdefender
}

🏗️ Architecture

This plugin follows clean architecture principles with clear separation of concerns:

check_msdefender/
├── 📁 cli/                     # Command-line interface
│   ├── commands/               # Individual command handlers
│   │   ├── onboarding.py      # Onboarding status command
│   │   ├── lastseen.py        # Last seen command
│   │   ├── vulnerabilities.py # Vulnerabilities command
│   │   ├── products.py        # Products CVE monitoring command
│   │   ├── alerts.py          # Alerts monitoring command
│   │   ├── machines.py        # List machines command
│   │   └── detail.py          # Machine detail command
│   ├── decorators.py          # Common CLI decorators
│   └── handlers.py            # CLI handlers
├── 📁 core/                    # Core business logic
│   ├── auth.py                # Authentication management
│   ├── config.py              # Configuration handling
│   ├── defender.py            # Defender API client
│   ├── exceptions.py          # Custom exceptions
│   ├── nagios.py              # Nagios plugin framework
│   └── logging_config.py      # Logging configuration
├── 📁 services/                # Business services
│   ├── onboarding_service.py  # Onboarding business logic
│   ├── lastseen_service.py    # Last seen business logic
│   ├── vulnerabilities_service.py # Vulnerability business logic
│   ├── products_service.py    # Products CVE monitoring business logic
│   ├── alerts_service.py      # Alerts monitoring business logic
│   ├── machines_service.py    # Machines business logic
│   ├── detail_service.py      # Detail business logic
│   └── models.py              # Data models
└── 📁 tests/                   # Comprehensive test suite
    ├── unit/                   # Unit tests
    ├── integration/            # Integration tests
    └── fixtures/               # Test fixtures

Key Design Principles

• 🎯 Single Responsibility - Each module has one clear purpose
• 🔌 Dependency Injection - Easy testing and mocking
• 🧪 Testable - Comprehensive test coverage
• 📈 Extensible - Easy to add new commands and features
• 🔒 Secure - No secrets in code, proper credential handling

🧪 Development

Development Setup

# Clone repository
git clone https://github.com/lduchosal/check_msdefender.git
cd check_msdefender

# Create development environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

Code Quality Tools

# Format code
black check_msdefender/

# Lint code
flake8 check_msdefender/

# Type checking
mypy check_msdefender/

# Run tests
pytest tests/ -v --cov=check_msdefender

Building & Publishing

# Build package
python -m build

# Test installation
pip install dist/*.whl

# Publish to PyPI
python -m twine upload dist/*

🔍 Output Examples

Successful Check

DEFENDER OK - Onboarding status: 0 (Onboarded) | onboarding=0;1;2;0;2

Warning State

DEFENDER WARNING - Last seen: 10 days ago | lastseen=10;7;30;0;

Critical State

DEFENDER CRITICAL - Vulnerability score: 150 (1 Critical, 5 High) | vulnerabilities=150;10;100;0;

Alerts Warning

DEFENDER WARNING - Unresolved alerts for machine.domain.com | alerts=2;1;5;0;
Unresolved alerts for machine.domain.com
2025-09-14T10:22:14.12Z - Suspicious activity detected (New high)
2025-09-14T12:00:00.00Z - Malware detection (InProgress medium)

🔧 Troubleshooting

Common Issues

Issue	Solution
Authentication Errors	Verify Azure app permissions and credentials
Network Connectivity	Check firewall rules for Microsoft endpoints
Import Errors	Ensure all dependencies are installed
Configuration Issues	Validate config file syntax and paths

Debug Mode

Enable verbose logging for detailed troubleshooting:

# Maximum verbosity
check_msdefender vulnerabilities -d machine.domain.tld -vvv

# Check specific configuration
check_msdefender onboarding -c /path/to/config.ini -d machine.domain.tld -vv

Required Network Access

Ensure connectivity to:

• login.microsoftonline.com
• api.securitycenter.microsoft.com
• api-eu.securitycenter.microsoft.com
• api-eu3.securitycenter.microsoft.com
• api-uk.securitycenter.microsoft.com

📊 Exit Codes

Code	Status	Description
0	OK	Value within acceptable range
1	WARNING	Value exceeds warning threshold
2	CRITICAL	Value exceeds critical threshold
3	UNKNOWN	Error occurred during execution

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with nagiosplugin framework
• Uses Azure Identity SDK for authentication
• Powered by Click for CLI interface

---

⭐ Star this repository if you find it useful!

🐛 Report Bug • 💡 Request Feature • 📖 Documentation