Microsoft 365 Defender

Supported OS Linux Windows Mac OS

marketplace
Integration version2.1.5
CDS Microsoft 365 Defender - Endpoints
CDS Microsoft 365 Defender- Endpoint Software
CDS Microsoft 365 Defender - Endpoint Threats and Vulnerabilities
CDS Microsoft 365 Defender - Alerts
CDS Microsoft 365 Defender - Incidents
CDS Microsoft 365 Defender - Email Events
CDS Microsoft 365 Defender - Cloud App Events
CDS Microsoft 365 Defender - Identity

Overview

Microsoft 365 Defender is a unified pre- and post-breach enterprise defense suite that natively coordinates detection, prevention, investigation, and response across endpoints, identities, email, and applications to provide integrated protection against sophisticated attacks.

This integration collects log data of alerts, incidents, endpoints, identities, email, security scores, secure score control profiles, software, vulnerabilities, and investigations from Microsoft 365 Defender.

Data Collected

Metrics

cds.ms.365.defender.organization_exposure_level
(gauge)		Provides the organization exposure level score
cds.ms.365.defender.software_version_vulnerabilities
(gauge)		Number of vulnerabilities for each software version
cds.ms.365.defender.software_version_installations
(gauge)		Number of installations for each software version
cds.ms.365.defender.current_score.current_score
(gauge)		This shows Tenant current attained score on specified date
cds.ms.defender.endpoint.organization_exposure_level
(gauge)		Provides the organization exposure level score

Datadog Integration Installation

To install the integration, run the following command:

  • Linux:
    sudo -u dd-agent datadog-agent integration install --third-party datadog-crest_data_systems_microsoft_defender==2.1.5
  • Windows:
    "%programfiles%\Datadog\Datadog Agent\bin\agent.exe" integration install --third-party datadog-crest_data_systems_microsoft_defender==2.1.5

Set up datadog.yaml

  1. The app_key and api_key needs to be set in the datadog.yaml file if not already configured. For more information, see Agent Configuration Files and API and Application Keys.

       ## @param api_key - string - required
   ## Datadog API Key
   #
   api_key: <API_KEY>

   ## @param app_key - string - required
   ## Datadog App Key
   #
   app_key: <APP_KEY>

   ## @param site - string - optional - default: datadoghq.com
   ## The site of the Datadog intake to send Agent data to.
   ## Set to 'datadoghq.eu' to send data to the EU site.
   ## Set to 'us3.datadoghq.com' to send data to the US3 site.
   ## Set to 'us5.datadoghq.com' to send data to the US5 site.
   #
   site: <URL>

Datadog Integration Configuration

  1. Copy the conf.yaml.example file:

    cp /etc/datadog-agent/conf.d/crest_data_systems_microsoft_defender.d/conf.yaml.example /etc/datadog-agent/conf.d/crest_data_systems_microsoft_defender.d/conf.yaml

  2. Edit the crest_data_systems_microsoft_defender.d/conf.yaml file to add the configuration of Client ID, Client Secret, Tenant ID, events, and proxy settings:

    init_config:

instances:
  ## @param tenant_id - string - required
  ## Tenant ID of the registered Application in Azure.
  #
  - tenant_id: <TENANT_ID>

    ## @param client_id - string - required
    ## Client ID of the registered Application in Azure.
    #
    client_id: <CLIENT_ID>

    ## @param client_secret - string - required
    ## Client Secret of the registered Application in Azure.
    #
    client_secret: <CLIENT_SECRET>

    ## @param events - list of strings - optional - default: ['alerts', 'incidents', 'secure_score', 'secure_score_control_profiles', 'identity', 'email', 'cloud_app', 'endpoint', 'vulnerability', 'investigations', 'software']
    ## Provide the event endpoints to monitor the events data. Only lower case characters are accepted.
    #
    # events:
    #   - alerts
    #   - incidents
    #   - secure_score
    #   - secure_score_control_profiles
    #   - identity
    #   - email
    #   - cloud_app
    #   - endpoint
    #   - vulnerability
    #   - investigations
    #   - software

    ## @param proxy_type - string - optional
    ## Type of the proxy server. Allowed proxy types are http and https.
    ## Required if 'proxy_host' is provided and vice-versa.
    #
    # proxy_type: http

    ## @param proxy_host - string - optional
    ## Host of the proxy server.
    ## Required if 'proxy_type' is provided and vice-versa.
    #
    # proxy_host: 10.0.0.1

    ## @param proxy_port - integer - optional - default: 3128
    ## Port of the proxy server.
    #
    # proxy_port: 3128

    ## @param proxy_username - string - optional
    ## The username of the proxy server.
    ## Required if 'proxy_password' is provided and vice-versa.
    #
    # proxy_username: <PROXY_USERNAME>

    ## @param proxy_password - string - optional
    ## The password of the proxy server.
    ## Required if 'proxy_username' is provided and vice-versa.
    #
    # proxy_password: <PROXY_PASSWORD>

    ## @param verify_ssl - boolean - optional - default: false
    ## SSL verification while connecting to registered application in Azure.
    ## SSL verification flag 'verify_ssl' allows users to choose whether to verify
    ## the SSL certificate when connecting to the client server.
    ## Defaults to False if not specified.
    #
    # verify_ssl: false

    ## @param tags - list of strings - optional
    ## A list of tags to attach to every metric and service check emitted by this instance.
    ##
    ## Learn more about tagging at https://docs.datadoghq.com/tagging
    #
    # tags:
    #   - <KEY_1>:<VALUE_1>
    #   - <KEY_2>:<VALUE_2>

    ## @param service - string - optional
    ## Attach the tag `service:<SERVICE>` to every metric, event, and service check emitted by this integration.
    ##
    ## Overrides any `service` defined in the `init_config` section.
    #
    # service: <SERVICE>

    ## @param min_collection_interval - number - required
    ## This changes the collection interval of the check. For more information, see:
    ## https://docs.datadoghq.com/developers/write_agent_check/#collection-interval
    #
    min_collection_interval: 7200
  • Example for the conf.yaml when multiple instances of Microsoft 365 Defender Tenants are configured:
    init_config:
instances:
  - tenant_id: <TENANT_ID_1>
    client_id: <CLIENT_ID_1>
    client_secret: <CLIENT_SECRET_1>
    min_collection_interval: 7200
  - tenant_id: <TENANT_ID_2>
    client_id: <CLIENT_ID_2>
    client_secret: <CLIENT_SECRET_2>
    min_collection_interval: 7200
  1. Install the third-party dependency datadog-api-client python package:
  • Linux:
    sudo -Hu dd-agent /opt/datadog-agent/embedded/bin/pip install datadog-api-client>=2.16.0
  • Windows:
    "%programfiles%\Datadog\Datadog Agent\embedded\python.exe" -m pip install datadog-api-client>=2.16.0
  1. Restart the Agent.

Validation

Run the Agent’s status subcommand and look for crest_data_systems_microsoft_defender under the Checks section.

Alternatively, you can get detailed information about the integration using the following command:

  • Linux:
    sudo datadog-agent check crest_data_systems_microsoft_defender
  • Windows:
    "%programfiles%\Datadog\Datadog Agent\bin\agent.exe" check crest_data_systems_microsoft_defender

Monitor Configuration

  1. Navigate to the Monitors tab within Datadog.
  2. Click on New Monitor and then click on the New from Template tab.
  3. Search for the crest_data_systems_microsoft_defender monitor.

Upgrade Integration

  • Take the backup of your existing ‘conf.yaml’ file from your Datadog Agent’s crest_data_systems_microsoft_defender.d directory under conf.d directory.
  • Ensure that the dedicated app on the Microsoft Azure platform has the necessary permissions specified in the Microsoft Defender Configuration section.
  • Uninstall the currently installed version of Microsoft 365 Defender from the Datadog agent.
  • Install v2.1.1 of Microsoft 365 Defender into the Datadog agent.
  • Modify the configuration file as per the instructions provided in the Datadog Integration Configuration. Remove the app Key and API Key from the configuration file, and make sure to include them in the datadog.yaml file.

Service Checks

cds.ms.defender.endpoint.can_connect

Returns CRITICAL if authentication with Microsoft 365 Defender has failed. Returns OK otherwise.

Statuses: ok, critical

Support

For support or feature requests, contact Crest Data through the following channels:

This application is made available through the Marketplace and is supported by a Datadog Technology Partner. Click Here to purchase this application.