Skip to content

Microsoft Defender

Overview

LimaCharlie can ingest Microsoft 365 Defender logs via three methods Azure Event Hub Adapter, the Microsoft Defender API, or a Custom Webhook

Documentation for creating an event hub can be found here here.

Telemetry Platform: msdefender

Data Collected

API vs Event Hub Comparison

Method Data Source What You Get Use Case
Defender API Microsoft Graph API Security Alerts only Alert-focused monitoring
Azure Event Hub Defender Streaming API Raw telemetry events Full visibility into endpoint activity

Microsoft Defender API

The API adapter polls Microsoft Graph's /security/alerts_v2 endpoint every 30 seconds. This provides security alerts from Microsoft Defender products including:

  • Defender for Endpoint
  • Defender for Office 365
  • Defender for Identity
  • Defender for Cloud Apps

These are curated, high-fidelity alerts that Microsoft has already correlated and enriched.

For alert schema details, see Microsoft's alerts_v2 API documentation.

Azure Event Hub (Streaming API)

When using Event Hub with Defender, you receive raw telemetry via the Defender Streaming API. This includes detailed event tables such as:

  • DeviceProcessEvents - Process creation and execution
  • DeviceNetworkEvents - Network connections
  • DeviceFileEvents - File operations
  • DeviceLogonEvents - Authentication events
  • DeviceRegistryEvents - Registry modifications
  • DeviceEvents - Miscellaneous security events

This provides full endpoint telemetry for custom detection rules and threat hunting.

For the complete list of supported streaming event types, see Microsoft's Defender XDR streaming event types documentation.

Defender API Configuration

To collect data via the Microsoft Defender API, configure an App Registration in Azure with the following permission:

  • SecurityAlert.Read.All

Then create a Defender adapter in LimaCharlie with:

  • Tenant ID
  • Client ID
  • Client Secret

Deployment Configurations

All adapters support the same client_options, which you should always specify if using the binary adapter or creating a webhook adapter. If you use any of the Adapter helpers in the web app, you will not need to specify these values.

  • client_options.identity.oid: the LimaCharlie Organization ID (OID) this adapter is used with.
  • client_options.identity.installation_key: the LimaCharlie Installation Key this adapter should use to identify with LimaCharlie.
  • client_options.platform: the type of data ingested through this adapter, like text, json, gcp, carbon_black, etc.
  • client_options.sensor_seed_key: an arbitrary name for this adapter which Sensor IDs (SID) are generated from, see below.

Adapter-specific Options

  • connection_string - The connection string provided in Azure for connecting to the Azure Event Hub, including the EntityPath=... at the end which identifies the Hub Name (this component is sometimes now shown in the connection string provided by Azure).

Guided Deployment

In the LimaCharlie web app, you can find a Microsoft Defender helper for connecting to an existing Azure Event Hub and ingesting Microsoft Defender logs.

CLI Deployment

The following example configuration ingests Microsoft Defender logs from an Azure Event Hub to LimaCharlie.

./lc_adapter azure_event_hub client_options.identity.installation_key=<INSTALLATION_KEY> \
client_options.identity.oid=<OID> \
client_options.platform=msdefender \
client_options.sensor_seed_key=<SENSOR_SEED_KEY> \
client_options.hostname=msdefender \
"connection_string=Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=fnaaaaaaaaaaaaaaak0g54alYbbbbbbbbbbbbbbbALQ=;EntityPath=lc-stream"

Infrastructure as Code Deployment

# Adapter Documentation: https://docs.limacharlie.io/docs/adapter-types
# For cloud sensor deployment, store credentials as hive secrets:

#   tenant_id: "hive://secret/azure-tenant-id"
#   client_id: "hive://secret/defender-client-id"
#   client_secret: "hive://secret/defender-client-secret"

sensor_type: "defender"
defender:
  tenant_id: "hive://secret/azure-tenant-id"
  client_id: "hive://secret/azure-defender-client-id"
  client_secret: "hive://secret/azure-defender-client-secret"
  client_options:
    identity:
      oid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      installation_key: "YOUR_LC_INSTALLATION_KEY_DEFENDER"
    hostname: "ms-defender-adapter"
    platform: "json"
    sensor_seed_key: "defender-sensor"
    mapping:
      sensor_hostname_path: "machineDnsName"
      event_type_path: "alertType"
      event_time_path: "lastUpdateTime"
    indexing: []