MDE Client Documentation

This documentation covers the mde-client package from four angles:

• Tutorials help a new user reach a first successful outcome.
• How-to guides solve common package tasks.
• Reference pages describe the package surface as it exists today.
• Explanation pages clarify the design choices behind the client.

mde-client is a Python client for Microsoft Defender for Endpoint built around a single MDEClient, endpoint properties such as client.machines and client.alerts, and lazy result wrappers that materialize only when you call a terminal method such as to_dicts() or to_polars().

Choose a starting point

• New to the package: Get started
• Need to solve one task: How-to guides
• Need exact API details: Reference
• Need to understand the design: Explanation

Package overview

The current package surface is organized around these ideas:

• MDEClient manages authentication and the underlying HTTP session.
• Each endpoint family is exposed as a property on the client.
• Most endpoint methods return a lazy results wrapper instead of fetching immediately.
• The same result wrapper pattern is used across JSON-backed and export-backed endpoints.
• httpx.Client and msal.TokenCache can be injected for testing and customization.

Documentation map

Tutorials

• Get started: install the package, authenticate, and fetch your first machine records.

How-to guides

• How-to index
• Authenticate with client credentials
• List and filter machines
• Get related data for one machine
• Run an advanced hunting query
• Work with result formats
• Use export-backed endpoints
• Inject a custom HTTP client or token cache
• Handle errors and retries
• Tune performance
• Test code that uses mde-client
• Build multi-endpoint workflows

Reference

• Reference index
• MDEClient
• Authentication
• Results wrappers
• Query models
• ViaFiles
• Endpoint reference

Explanation

• Explanation index
• Lazy results and caching
• Result materialization model
• Why query models keep Defender field names
• How export-backed endpoints work
• Why the client supports dependency injection

Scope of this docs set

This docs tree focuses on the mde-client package under src/mde-client/. It does not try to cover Azure portal setup step by step, and it does not replace the repository-level workflow notes in the root README.