Windows Defender response Integration by API

Windows Defender response Integration by API

Windows Defender response Integration by API

This article shows how to leverage the Lumu Defender API to integrate API indicators from Windows Defender


Figure 1 - Lumu Event API data collection configuration


Requirements

  • Lumu Defender API key.
  • Windows Defender Cloud (Endpoint Plan 1 or 2)
  • Azure Application
    • The Azure application must have API Permissions Ti.readWrite.All, Ti.ReadWrite, and Ti.Read.All.
  • Scripting Host
    • Requires a host with Python v3.6+ and network visibility to Azure API and Defender API endpoints.
  • Script package.
    • Contact the Lumu Support team to request the package we created to deploy the required files.

Set up Azure

Add a new application

To integrate with Windows Defender, you must add a new application using the Microsoft Azure Active Directory portal.

  1. In the Microsoft Azure Active Directory portal, go to the App Registrations menu under the Manage section in the left navigation bar. Click on the New registration button 

  2. Fill in the requested data in the Register an application form. Give the app a name you can associate later with the integration (i.e., Lumu). In the Supported account types field, select Accounts in this organizational directory only. The Redirect URL is not required. Click the Register button.




Assign a secret to your Lumu application

You must associate a secret key to the application added before.

  1. After adding the new application, you will see the details of your new application. Next to the Client credentials label, click the Add a certificate or secret link. Take note of the values for the fields Application (client) ID and Directory (tenant) ID. These will be required to deploy the integration script. 
  2. Click the New client secret button in the Certificates & Secrets form. Fill in the requested data. It’s recommended to set the Expire field to 12 months.

It’s important to renew this key after this token has expired otherwise, the integration will stop working.

  1. Copy the Value of the key from the Certificates & Secret page. Keep this value at hand, it will be required by the integration script.



Add required API permissions to the Lumu application

The new application created for Lumu integration requires the permissions Ti.Read.All , Ti.ReadWrite , and Ti.ReadWrite.All .

  1. In the App Registrations menu, under the Manage section, select the application created in the steps above.



  1. On the application page, click the API permissions menu under the Manage section. Click the Add a permission button.
  2. In the Request API permissions screen, select the tab APIs my organization uses. Write windowsdefenderatp  in the search field. From the results, click on the WindowsDefenderATP option.


  1. In the WindowsDefenderATP permissions window, click the Application permissions box.


  1. In the detailed permissions screen, use the search box to type Ti. From the results, toggle the checkboxes near the Ti.Read.AllTi.ReadWrite, and Ti.ReadWrite.All options. Then, click the Add permissions button.


  1. Grant admin content to the added permissions by clicking the Grant admin consent button. Give your confirmation when prompted.



Deploy the script

First, contact the Lumu Support team to request the package we created to deploy the required files.

Script location

Unpack the deployed package provided by Lumu in your preferred path/folder. Keep in mind this location, as it will be required for further configurations. From now on, we will refer to this folder as <windows_defender_lumu_root>.

Install requirements

The file requirements.txt contains the list of dependencies for this data collector. After deploying the package locally, run the following command from the deployment folder:

[sudo] pip install -r ./requirements.txt

Script details

For using the script, you must locate yourself on the path selected for deployment (<windows_defender_response>). Use the following command to show all options available for the package:

python wdefender_response.py --help

Usage: wdefender_response .py [options]

Options

Description

-h, --help

show this help message and exit

--config CONFIG

Load options from config file

--proxy-host PROXY_HOST   --proxy-port PROXY_PORT

--proxy-user PROXY_USER              

--proxy-password PROXY_PASSWORD                        

Proxy host (if required)

Proxy port (if required)

Proxy user (if required)

Proxy password (if required)

--company_key COMPANY_KEY

Lumu Company Key (Defender API).

--tenant-id TENANT-ID

--app-id APP-ID        

--app-secret APP-SECRET

                       

--type-indicators {HASH, URL, DOMAIN, ALL, CLEAR}

                       

ID Tenant.

Application ID in Azure.

Value of App Secret generated in Certificated and Secrets.

Type of indicators to upload into Windows Defender.

--logging {screen,file}

--verbose, -v        

--time_days TIME      

Logging option (default screen).

Verbosity level.

Days to search adversaries.

Usage examples

By default

Use the following command to fetch and push all adversaries detected by Lumu in the last 7 days to windows defender.

python   wdefender_response.py --company-api-key <company-key> --tenant-id <tenant-id> --app-id <app-id> --app-secret <app-secret> --type-indicators ALL

NOTE: Each time the script is run, it will overwrite the locks and execute locks by web access.

Clear Function

Use the following command to clear all indicators uploaded into windows defender.

python wdefender_response.py --company-api-key <company-key> --tenant-id <tenant-id> --app-id <app-id> --app-secret <app-secret> --type-indicators CLEAR


Expected results:

After running the script, all adversaries will be pushed into Microsoft 365 Defender. You can check the uploaded IOCs using your Microsoft Defender Portal. Go to Settings > Endpoints. In the Endpoints screen, click the Indicators menu under the Rules section. There, you will see the IOCs populated by Lumu under its own category: File hashes and URLs/Domains.

Added IOCs - File hashes:



Added IOCs - URLs/Domains



Troubleshooting

To identify failures on the script, please use the -v flag. This will allow you to identify failures in the script execution.



        • Related Articles

        • Crowdstrike Custom Response Integration with Lumu Defender API

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...
        • VMWare Carbon Black EDR Custom Response Integration with Lumu Defender API

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...
        • Symantec Endpoint Protection Custom Response Integration

          Before going through this article, check our  Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...
        • Defender API

          Some enterprises may already be using diverse defense solutions such as Security Information and Event Management (SIEM), Security Orchestration, Automation, and Response (SOAR) technologies, etc. Lumu provides an easy-to-use and comprehensive API ...
        • Cisco Umbrella Custom Response Integration with Lumu Defender API

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...