Lab Setup for Microsoft Defender (MDE) Integration

Basic Lab Setup

Complete the basic Xshield Lab setup before proceeding with this guide.

Refer to the Basic Lab Environment Setup for installation instructions.

Prerequisites

1. Microsoft Defender Portal Access: Tenant/Organization access to download Onboarding and Offboarding packages. Contact your Microsoft Defender tenant administrator to obtain access.

Deploying Microsoft Defender Lab

In this lab setup, we will deploy a Microsoft Defender environment to demonstrate the integration between Xshield and Microsoft Defender.

The setup will create 5 Docker containers on the lab machine and install Microsoft Defender (MDE) agents on 3 of them as managed endpoints and remaining 2 will be as unmanaged networks.

The containers will be configured to generate traffic on specific ports to simulate real-world scenarios.

Note: The number of containers can be configured in mde_lab.yaml, and traffic/ports can be configured in mde_lab_traffic.yaml files located in /etc/colortokens/config/lab_data/ on the lab VM.

Follow these steps to deploy the lab:

Steps to deploy Microsoft Defender Lab Environment

1. Generate API credentials for Microsoft Defender integration with Xshield

   If you already have the API credentials, skip to step 2.

   Follow the Generate API Credentials for Integrating Microsoft Defender for Endpoint with Xshield platform using Terraform guide to generate API credentials.

2. Verify Entra ID Application Permissions

   Ensure your application registered on Microsoft Entra ID (entra.microsoft.com) has ReadWrite permissions in addition to the default ReadAll permissions. This is required to make configuration changes to the Microsoft Defender platform.

   Contact your Application Administrator to set the appropriate permissions.

important

The Microsoft Defender API credentials will be used in the next steps to deploy the lab environment, please note them down client_id, tenant_id, client_secret, storage_account_name, and queue_name

3. Deploy the Microsoft Defender lab environment using Xshield Lab

   Navigate to the directory containing the xshield_lab.py script and activate the Python virtual environment:

   Note: If the Python virtual environment is already activated from the installation steps, skip the activation command and proceed directly to launching the tool.

cd /etc/colortokens/lab

source .venv/bin/activate

python3 xshield_lab.py

The following menu will be displayed:

Welcome to the Xshield Lab Environment setup tool.


Please select an option:
1. Create Lab Environment for Server Segmentation
2. Create Lab Environment for Container Segmentation
3. Create Lab Environment for Gatekeeper
4. Create Lab Environment for User Segmentation
5. Create Lab Environment for EDR Segmentation (CrowdStrike/MDE)
6. Create Lab Environment for Cloud Segmentation (Beta)
7. Customize Lab Environment
8. Remove Lab Environment
9. Remove Docker Images
10. Exit

4. Select the EDR Segmentation option

   Enter 5 to select Create Lab Environment for EDR Segmentation (CrowdStrike/MDE).

   A sub-menu will appear with options for CrowdStrike and Microsoft Defender (MDE) integration.

   Enter 2 to select Create Lab Environment for Microsoft Defender (MDE).

5. Provide the Onboarding package

   The script will check if the Onboarding package is available on the VM. If not found, you will be prompted to download it from the Microsoft Defender portal and place it in the specified directory.

   Note: You must have an account with Microsoft Defender for Endpoint to download the onboarding package.

6. Enter Microsoft Defender API credentials

   You will be prompted to enter the Microsoft Defender API credentials. Provide the values noted in step 2:

tenantId: <Enter Microsoft Defender API tenant ID>
clientId: <Enter Microsoft Defender API client ID>
clientSecret: <Enter Microsoft Defender API client secret>
storageaccount: <Enter Microsoft Defender API storage account name>
storagequeue: <Enter Microsoft Defender API storage queue name>

Once the API credentials are validated, the script will start to create the Docker images with the onboarding package provided.

7. Provide a unique identifier for the lab endpoints

   After the Docker images are created, you will be prompted to provide a unique name for the endpoints. This identifier distinguishes between multiple lab instances on the same MDE tenant.

   The unique name will be:

   • Added to each endpoint onboarded to the MDE platform
   • Used to tag these endpoints for identification

   Recommendation: Use your name or initials as the unique identifier.

Final Outcome

Once the steps are completed successfully, the Xshield Lab tool executes the following actions:

1. Creates Linux docker containers based on the mde_lab.yaml file with the respective ports opened.
2. Installs the Microsoft Defender agent on containers using the provided onboarding package.
3. Configures ports and initiates traffic between containers based on the mde_lab_traffic.yaml file.
4. Validates that endpoints are successfully onboarded to the MDE platform.
5. Assigns a tag to onboarded endpoints in MDE with the name XshieldLab-<unique name>.
6. Performs the EDR integration between MDE and Xshield platform.
7. Imports the assigned tag from MDE to Xshield platform.
8. Activates the imported tag in Xshield platform.
9. Syncs devices and updates the Xshield platform with the endpoints onboarded to MDE.

Remove the Lab Environment

To remove the lab environment, follow these steps:

1. Launch the Xshield Lab tool

   On the lab VM under path /etc/colortokens/lab, run:

   python3 xshield_lab.py

2. Select the removal option

   Select 8. Remove Lab Environment.

   The following cleanup actions will be performed:

   1. You will be prompted to download and provide the Offboarding package from the Microsoft Defender portal.
   2. The offboarding package will be copied and executed on all Docker containers to remove the Microsoft Defender agent.
   3. All Docker containers will be removed.
   4. The tag imported from the MDE platform will be inactivated.
   5. The tag assigned to onboarded endpoints in MDE will be removed and replaced with Decommissioned.
   6. Tags and devices imported from the MDE platform will be removed.
   7. Assets onboarded from the MDE platform will be removed from Xshield.

Note:

1. You will need to manually remove the endpoints from the Microsoft Defender portal by adding them to the Exclude list.
2. You can remove the docker images created during lab setup by selecting 9. Remove Docker Images option from Xshield Lab menu