check-msdefender 1.0.0__py3-none-any.whl

check_msdefender-1.0.0.dist-info/METADATA

@@ -0,0 +1,396 @@
+Metadata-Version: 2.4
+Name: check-msdefender
+Version: 1.0.0
+Summary: A Nagios plugin for monitoring Microsoft Defender API endpoints
+Author-email: ldvchosal <ldvchosal@github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lduchosal/check_msdefender
+Project-URL: Bug Reports, https://github.com/lduchosal/check_msdefender/issues
+Project-URL: Source, https://github.com/lduchosal/check_msdefender
+Project-URL: Documentation, https://github.com/lduchosal/check_msdefender/blob/main/README.md
+Keywords: nagios,monitoring,microsoft,graph,api,azure
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nagiosplugin>=1.4.0
+Requires-Dist: azure-identity>=1.12.0
+Requires-Dist: click<9.0,>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Dynamic: license-file
+
+# 🛡️ Check MS Defender
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/lduchosal/check_msdefender)
+
+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, 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+# 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 |
+| `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
+
+### 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
+```ini
+[auth]
+client_id = your-application-client-id
+client_secret = your-client-secret
+tenant_id = your-azure-tenant-id
+
+[settings]
+timeout = 5
+```
+
+#### Certificate Authentication
+```ini
+[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`
+3. **Create Authentication** (Secret or Certificate)
+4. **Note Credentials** (Client ID, Tenant ID, Secret/Certificate)
+
+📚 [Complete API Setup Guide](https://learn.microsoft.com/en-us/defender-endpoint/api/api-hello-world)
+
+## 🔧 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
+
+```cfg
+# 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
+}
+```
+
+### Service Definitions
+
+```cfg
+# 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
+}
+```
+
+## 🏗️ 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
+│   │   ├── 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
+│   ├── 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
+
+```bash
+# 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 .
+pip install -r requirements-dev.txt
+```
+
+### Code Quality Tools
+
+```bash
+# 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
+
+```bash
+# 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;
+```
+
+## 🔧 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:
+
+```bash
+# 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](https://pep8.org/) 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](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [nagiosplugin](https://nagiosplugin.readthedocs.io/) framework
+- Uses [Azure Identity SDK](https://docs.microsoft.com/python/api/azure-identity/) for authentication
+- Powered by [Click](https://click.palletsprojects.com/) for CLI interface
+
+---
+
+<div align="center">
+
+**[⭐ Star this repository](https://github.com/lduchosal/check_msdefender)** if you find it useful!
+
+[🐛 Report Bug](https://github.com/lduchosal/check_msdefender/issues) • [💡 Request Feature](https://github.com/lduchosal/check_msdefender/issues) • [📖 Documentation](https://github.com/lduchosal/check_msdefender/blob/main/README.md)
+
+</div>

check_msdefender-1.0.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+check_msdefender/__init__.py,sha256=HDn1Ub7Ohqkfko0kUPT8w7HqU52jXwo-leSTImO1x_k,161
+check_msdefender/__main__.py,sha256=TuNsRSdnkQm9OdBTAwD5aB2zV_Irc50WgylVWhrfnLY,124
+check_msdefender/check_msdefender.py,sha256=M_i2CIZWxfPisxxiWTFqGVAjoAS89euyVbbbtmaikQk,148
+check_msdefender/cli/__init__.py,sha256=NWaS5ZI9_252AcReugF_WGPMOvQ_B7sC_s3pSrGujcI,291
+check_msdefender/cli/__main__.py,sha256=TuNsRSdnkQm9OdBTAwD5aB2zV_Irc50WgylVWhrfnLY,124
+check_msdefender/cli/decorators.py,sha256=iMd2zrQI2SVSTa9hD8w4AjFqsctFaWUIzdT8_cSTVG8,772
+check_msdefender/cli/handlers.py,sha256=RAUsH8gI_fQV4ZNvs3Ih1lCoSOSortpVWRhyQHXe6yU,1418
+check_msdefender/cli/commands/__init__.py,sha256=mKF0lp4uMI9VYQGFg7N4W74GOLmACeXWVxpReLvre34,644
+check_msdefender/cli/commands/detail.py,sha256=k2pDCGXtiGbKmXxDYUvkmUgmQA60jKdIzTY-Jt160jE,2532
+check_msdefender/cli/commands/lastseen.py,sha256=TJHArqLkQtXF1XL5U5Dk_ExfVhK95C2TJQg0WBHbyp8,1891
+check_msdefender/cli/commands/machines.py,sha256=uHpxc2j4iJnbhp2MRAW-KR1K0NPrqdqQtJbGgSRO5tk,1737
+check_msdefender/cli/commands/onboarding.py,sha256=I_hKWngVdSITkEFQ3pDE2oIGlYsCurG7XbCi_fKNoAM,1925
+check_msdefender/cli/commands/vulnerabilities.py,sha256=EzllIUw67qAnarKVTy-zx4nWVHDxg2icRsC1irdBhnU,1944
+check_msdefender/core/__init__.py,sha256=naBiEkixiWTuHU3GENk8fqC8H3p_hkzRsmSY2uiM_TQ,47
+check_msdefender/core/auth.py,sha256=7mkGmhGHy4t38O0e4Rz7dQ52xfMbK3IUXMlw3u83aB4,1585
+check_msdefender/core/config.py,sha256=IoWBL_DB110F4i6hFfli6iFDBXx57dHh32lCuLkcgNk,1170
+check_msdefender/core/defender.py,sha256=5_Mq1p9WxlttQeeqnY9RCWgDbf2Wbagw4LUFY2aqrrA,7315
+check_msdefender/core/exceptions.py,sha256=X4s_XM64SEVSs-4mGKqnF8xXwGFY3E0buvkgRNuCCX4,600
+check_msdefender/core/logging_config.py,sha256=27gLjvbP_AgedDQWZQEFfn_CGn5y6HcJQlI5jlxQHow,4067
+check_msdefender/core/nagios.py,sha256=nZSo-1VV57WFSieyRp456tw_OqpjXOoM_MEjnLkgxlE,6600
+check_msdefender/services/__init__.py,sha256=_fiKXxcz263IghXn9BnUWDKPgedhUPoSakEN3tBd2SU,44
+check_msdefender/services/detail_service.py,sha256=i-jXubNfsNf-fS6ba2MQecN886GzU0UC40DwS3HrnnY,3382
+check_msdefender/services/lastseen_service.py,sha256=LiNVeUbAoMzowMvE90P7zCtKFHBLbIDp5mmkVHRLwqs,3128
+check_msdefender/services/machines_service.py,sha256=5s5BXB4GUMQ8z3rPy32lybp0DslG0QVhWxm-n_AU97k,3119
+check_msdefender/services/models.py,sha256=8p8UHh86h9TjeYahhu_qCBpfuGGS3tObhtlpYk9kB8I,985
+check_msdefender/services/onboarding_service.py,sha256=RIOsvALCoKV0YqnCHKYRkelSPrO-F-6vNBLlto4MpiI,2686
+check_msdefender/services/vulnerabilities_service.py,sha256=ikD6E-hg7LtvCiTg7cTCqGSTly6Wgtql82NJD81D2n0,6812
+check_msdefender-1.0.0.dist-info/licenses/LICENSE,sha256=kW3DwIsKc9HVYdS4f4tI6sLo-EPqBQbz-WmuvHU4Nak,1065
+check_msdefender-1.0.0.dist-info/METADATA,sha256=feCju74gUaR5YTuoshCDVnYagetTZWpFt64Itep5ckw,12750
+check_msdefender-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+check_msdefender-1.0.0.dist-info/entry_points.txt,sha256=EMA_qKSvf5dC6yRrajd0W-UgS3C5Ce0o04i3_5A34Cs,63
+check_msdefender-1.0.0.dist-info/top_level.txt,sha256=0XgjD7gBWFImxE44zghS94ZGdonRZlfVEpfspnBnG5A,17
+check_msdefender-1.0.0.dist-info/RECORD,,

check_msdefender-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

check_msdefender-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+check_msdefender = check_msdefender.cli:main

check_msdefender-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ldvchosal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

check_msdefender-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+check_msdefender