{"id":37078481,"url":"https://github.com/lduchosal/check_msdefender","last_synced_at":"2026-01-14T09:11:15.028Z","repository":{"id":314496483,"uuid":"1055647313","full_name":"lduchosal/check_msdefender","owner":"lduchosal","description":"Nagios plugin for MS Defender API","archived":false,"fork":false,"pushed_at":"2025-12-10T10:54:24.000Z","size":224,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-05T03:07:42.150Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lduchosal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T15:22:26.000Z","updated_at":"2025-12-10T10:54:28.000Z","dependencies_parsed_at":"2025-09-12T21:10:40.066Z","dependency_job_id":"ceb1cc1a-17be-43b5-bf13-e541558cb304","html_url":"https://github.com/lduchosal/check_msdefender","commit_stats":null,"previous_names":["lduchosal/check_msdefender"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lduchosal/check_msdefender","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lduchosal%2Fcheck_msdefender","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lduchosal%2Fcheck_msdefender/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lduchosal%2Fcheck_msdefender/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lduchosal%2Fcheck_msdefender/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lduchosal","download_url":"https://codeload.github.com/lduchosal/check_msdefender/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lduchosal%2Fcheck_msdefender/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T09:11:13.332Z","updated_at":"2026-01-14T09:11:15.023Z","avatar_url":"https://github.com/lduchosal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ Check MS Defender\n\n[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/lduchosal/check_msdefender)\n\nA comprehensive **Nagios plugin** for monitoring Microsoft Defender for Endpoint API endpoints. Built with modern Python practices and designed for enterprise monitoring environments.\n\n## ✨ Features\n\n- 🔐 **Dual Authentication** - Support for Client Secret and Certificate-based authentication\n- 🎯 **Multiple Endpoints** - Monitor onboarding status, last seen, vulnerabilities, products with CVEs, alerts, and machine details\n- 📊 **Nagios Compatible** - Standard exit codes and performance data output\n- 🏗️ **Clean Architecture** - Modular design with testable components\n- 🔧 **Flexible Configuration** - File-based configuration with sensible defaults\n- 📈 **Verbose Logging** - Multi-level debugging support\n- 🐍 **Modern Python** - Built with Python 3.9+ using type hints and async patterns\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Create virtual environment (recommended)\npython -m venv /usr/local/libexec/nagios/check_msdefender\nsource /usr/local/libexec/nagios/check_msdefender/bin/activate\n\n# Install from source\npip install git+https://github.com/lduchosal/check_msdefender.git\n```\n\n### Basic Usage\n\n```bash\n# Check machine onboarding status\ncheck_msdefender onboarding -d machine.domain.tld\n\n# Check last seen (with custom thresholds)\ncheck_msdefender lastseen -d machine.domain.tld -W 7 -C 30\n\n# Check vulnerabilities\ncheck_msdefender vulnerabilities -d machine.domain.tld -W 10 -C 100\n\n# Check products with CVE vulnerabilities\ncheck_msdefender products -d machine.domain.tld -W 5 -C 1\n\n# Check alerts\ncheck_msdefender alerts -d machine.domain.tld -W 1 -C 5\n\n# List all machines\ncheck_msdefender machines\n\n# Get detailed machine info\ncheck_msdefender detail -d machine.domain.tld\n```\n\n## 📋 Available Commands\n\n| Command | Description | Default Thresholds |\n|---------|-------------|-------------------|\n| `onboarding` | Check machine onboarding status | W:1, C:2 |\n| `lastseen` | Days since machine last seen | W:7, C:30 |\n| `vulnerabilities` | Vulnerability score calculation | W:10, C:100 |\n| `products` | Count of vulnerable software with CVEs | W:5, C:1 |\n| `alerts` | Count of unresolved alerts | W:1, C:0 |\n| `machines` | List all machines | W:10, C:25 |\n| `detail` | Get detailed machine information | - |\n\n### Vulnerability Scoring\n\nThe vulnerability score is calculated as:\n- **Critical vulnerabilities** × 100\n- **High vulnerabilities** × 10\n- **Medium vulnerabilities** × 5\n- **Low vulnerabilities** × 1\n\n### Products CVE Monitoring\n\nThe products command monitors installed software with known CVE vulnerabilities:\n- **Groups CVEs by software** (name, version, vendor)\n- **Shows CVE details** including severity levels and disk paths\n- **Counts vulnerable software** (not individual CVEs)\n- **Default thresholds**: Warning at 5 vulnerable software, Critical at 1\n- **Displays up to 10 software entries** with first 5 CVEs per software\n\n### Alert Monitoring\n\nThe alerts command monitors unresolved security alerts for a machine:\n- **Counts only unresolved alerts** (status ≠ \"Resolved\")\n- **Excludes informational alerts** when critical/warning alerts exist\n- **Shows alert details** including creation time, title, and severity\n- **Default thresholds**: Warning at 1 alert, Critical at 0 (meaning any alert triggers warning)\n\n### Onboarding Status Values\n\n- `0` - Onboarded ✅\n- `1` - InsufficientInfo ⚠️\n- `2` - Unknown ❌\n\n## ⚙️ Configuration\n\n### Authentication Setup\n\nCreate `check_msdefender.ini` in your Nagios directory or current working directory:\n\n#### Client Secret Authentication\n```ini\n[auth]\nclient_id = your-application-client-id\nclient_secret = your-client-secret\ntenant_id = your-azure-tenant-id\n\n[settings]\ntimeout = 5\n```\n\n#### Certificate Authentication\n```ini\n[auth]\nclient_id = your-application-client-id\ntenant_id = your-azure-tenant-id\ncertificate_path = /path/to/certificate.pem\nprivate_key_path = /path/to/private_key.pem\n\n[settings]\ntimeout = 5\n```\n\n### Microsoft Defender API Setup\n\n1. **Register Application** in Azure Active Directory\n2. **Grant API Permissions**:\n   - `Machine.Read.All`\n   - `Vulnerability.Read`\n   - `Vulnerability.Read.All`\n   - `Alert.Read.All`\n3. **Create Authentication** (Secret or Certificate)\n4. **Note Credentials** (Client ID, Tenant ID, Secret/Certificate)\n\n📚 [Complete API Setup Guide](https://learn.microsoft.com/en-us/defender-endpoint/api/api-hello-world)\n\n## 🔧 Command Line Options\n\n| Option | Description | Example |\n|--------|-------------|---------|\n| `-c, --config` | Configuration file path | `-c /custom/path/config.ini` |\n| `-m, --machineId` | Machine ID (GUID) | `-m \"12345678-1234-1234-1234-123456789abc\"` |\n| `-d, --computerDnsName` | Computer DNS Name (FQDN) | `-d \"server.domain.com\"` |\n| `-W, --warning` | Warning threshold | `-W 10` |\n| `-C, --critical` | Critical threshold | `-C 100` |\n| `-v, --verbose` | Verbosity level | `-v`, `-vv`, `-vvv` |\n| `--version` | Show version | `--version` |\n\n## 🏢 Nagios Integration\n\n### Command Definitions\n\n```cfg\n# Microsoft Defender Commands\ndefine command {\n    command_name    check_defender_onboarding\n    command_line    $USER1$/check_msdefender/bin/check_msdefender onboarding -d $HOSTALIAS$\n}\n\ndefine command {\n    command_name    check_defender_lastseen\n    command_line    $USER1$/check_msdefender/bin/check_msdefender lastseen -d $HOSTALIAS$ -W 7 -C 30\n}\n\ndefine command {\n    command_name    check_defender_vulnerabilities\n    command_line    $USER1$/check_msdefender/bin/check_msdefender vulnerabilities -d $HOSTALIAS$ -W 10 -C 100\n}\n\ndefine command {\n    command_name    check_defender_products\n    command_line    $USER1$/check_msdefender/bin/check_msdefender products -d $HOSTALIAS$ -W 5 -C 1\n}\n\ndefine command {\n    command_name    check_defender_alerts\n    command_line    $USER1$/check_msdefender/bin/check_msdefender alerts -d $HOSTALIAS$ -W 1 -C 5\n}\n```\n\n### Service Definitions\n\n```cfg\n# Microsoft Defender Services\ndefine service {\n    use                     generic-service\n    service_description     DEFENDER_ONBOARDING\n    check_command           check_defender_onboarding\n    hostgroup_name          msdefender\n}\n\ndefine service {\n    use                     generic-service\n    service_description     DEFENDER_LASTSEEN\n    check_command           check_defender_lastseen\n    hostgroup_name          msdefender\n}\n\ndefine service {\n    use                     generic-service\n    service_description     DEFENDER_VULNERABILITIES\n    check_command           check_defender_vulnerabilities\n    hostgroup_name          msdefender\n}\n\ndefine service {\n    use                     generic-service\n    service_description     DEFENDER_PRODUCTS\n    check_command           check_defender_products\n    hostgroup_name          msdefender\n}\n\ndefine service {\n    use                     generic-service\n    service_description     DEFENDER_ALERTS\n    check_command           check_defender_alerts\n    hostgroup_name          msdefender\n}\n```\n\n## 🏗️ Architecture\n\nThis plugin follows **clean architecture** principles with clear separation of concerns:\n\n```\ncheck_msdefender/\n├── 📁 cli/                     # Command-line interface\n│   ├── commands/               # Individual command handlers\n│   │   ├── onboarding.py      # Onboarding status command\n│   │   ├── lastseen.py        # Last seen command\n│   │   ├── vulnerabilities.py # Vulnerabilities command\n│   │   ├── products.py        # Products CVE monitoring command\n│   │   ├── alerts.py          # Alerts monitoring command\n│   │   ├── machines.py        # List machines command\n│   │   └── detail.py          # Machine detail command\n│   ├── decorators.py          # Common CLI decorators\n│   └── handlers.py            # CLI handlers\n├── 📁 core/                    # Core business logic\n│   ├── auth.py                # Authentication management\n│   ├── config.py              # Configuration handling\n│   ├── defender.py            # Defender API client\n│   ├── exceptions.py          # Custom exceptions\n│   ├── nagios.py              # Nagios plugin framework\n│   └── logging_config.py      # Logging configuration\n├── 📁 services/                # Business services\n│   ├── onboarding_service.py  # Onboarding business logic\n│   ├── lastseen_service.py    # Last seen business logic\n│   ├── vulnerabilities_service.py # Vulnerability business logic\n│   ├── products_service.py    # Products CVE monitoring business logic\n│   ├── alerts_service.py      # Alerts monitoring business logic\n│   ├── machines_service.py    # Machines business logic\n│   ├── detail_service.py      # Detail business logic\n│   └── models.py              # Data models\n└── 📁 tests/                   # Comprehensive test suite\n    ├── unit/                   # Unit tests\n    ├── integration/            # Integration tests\n    └── fixtures/               # Test fixtures\n```\n\n### Key Design Principles\n\n- **🎯 Single Responsibility** - Each module has one clear purpose\n- **🔌 Dependency Injection** - Easy testing and mocking\n- **🧪 Testable** - Comprehensive test coverage\n- **📈 Extensible** - Easy to add new commands and features\n- **🔒 Secure** - No secrets in code, proper credential handling\n\n## 🧪 Development\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/lduchosal/check_msdefender.git\ncd check_msdefender\n\n# Create development environment\npython -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n```\n\n### Code Quality Tools\n\n```bash\n# Format code\nblack check_msdefender/\n\n# Lint code\nflake8 check_msdefender/\n\n# Type checking\nmypy check_msdefender/\n\n# Run tests\npytest tests/ -v --cov=check_msdefender\n```\n\n### Building \u0026 Publishing\n\n```bash\n# Build package\npython -m build\n\n# Test installation\npip install dist/*.whl\n\n# Publish to PyPI\npython -m twine upload dist/*\n```\n\n## 🔍 Output Examples\n\n### Successful Check\n```\nDEFENDER OK - Onboarding status: 0 (Onboarded) | onboarding=0;1;2;0;2\n```\n\n### Warning State\n```\nDEFENDER WARNING - Last seen: 10 days ago | lastseen=10;7;30;0;\n```\n\n### Critical State\n```\nDEFENDER CRITICAL - Vulnerability score: 150 (1 Critical, 5 High) | vulnerabilities=150;10;100;0;\n```\n\n### Alerts Warning\n```\nDEFENDER WARNING - Unresolved alerts for machine.domain.com | alerts=2;1;5;0;\nUnresolved alerts for machine.domain.com\n2025-09-14T10:22:14.12Z - Suspicious activity detected (New high)\n2025-09-14T12:00:00.00Z - Malware detection (InProgress medium)\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| **Authentication Errors** | Verify Azure app permissions and credentials |\n| **Network Connectivity** | Check firewall rules for Microsoft endpoints |\n| **Import Errors** | Ensure all dependencies are installed |\n| **Configuration Issues** | Validate config file syntax and paths |\n\n### Debug Mode\n\nEnable verbose logging for detailed troubleshooting:\n\n```bash\n# Maximum verbosity\ncheck_msdefender vulnerabilities -d machine.domain.tld -vvv\n\n# Check specific configuration\ncheck_msdefender onboarding -c /path/to/config.ini -d machine.domain.tld -vv\n```\n\n### Required Network Access\n\nEnsure connectivity to:\n- `login.microsoftonline.com`\n- `api.securitycenter.microsoft.com`\n- `api-eu.securitycenter.microsoft.com`\n- `api-eu3.securitycenter.microsoft.com`\n- `api-uk.securitycenter.microsoft.com`\n\n## 📊 Exit Codes\n\n| Code | Status | Description |\n|------|--------|-------------|\n| `0` | OK | Value within acceptable range |\n| `1` | WARNING | Value exceeds warning threshold |\n| `2` | CRITICAL | Value exceeds critical threshold |\n| `3` | UNKNOWN | Error occurred during execution |\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Development Guidelines\n\n- Follow [PEP 8](https://pep8.org/) style guide\n- Add tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [nagiosplugin](https://nagiosplugin.readthedocs.io/) framework\n- Uses [Azure Identity SDK](https://docs.microsoft.com/python/api/azure-identity/) for authentication\n- Powered by [Click](https://click.palletsprojects.com/) for CLI interface\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⭐ Star this repository](https://github.com/lduchosal/check_msdefender)** if you find it useful!\n\n[🐛 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)\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flduchosal%2Fcheck_msdefender","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flduchosal%2Fcheck_msdefender","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flduchosal%2Fcheck_msdefender/lists"}