Deploy Microsoft Defender for Endpoint on Linux manually

Applies to:

Want to experience Defender for Endpoint? Sign up for a free trial.

This article describes how to deploy Microsoft Defender for Endpoint on Linux manually. A successful deployment requires the completion of all of the following tasks:

Prerequisites and system requirements

Before you get started, see Microsoft Defender for Endpoint on Linux for a description of prerequisites and system requirements for the current software version.

Configure the Linux software repository

Defender for Endpoint on Linux can be deployed from one of the following channels (denoted below as [channel]): insiders-fast, insiders-slow, or prod. Each of these channels corresponds to a Linux software repository. Instructions for configuring your device to use one of these repositories are provided below.

The choice of the channel determines the type and frequency of updates that are offered to your device. Devices in insiders-fast are the first ones to receive updates and new features, followed later by insiders-slow and lastly by prod.

In order to preview new features and provide early feedback, it is recommended that you configure some devices in your enterprise to use either insiders-fast or insiders-slow.

Warning

Switching the channel after the initial installation requires the product to be reinstalled. To switch the product channel: uninstall the existing package, re-configure your device to use the new channel, and follow the steps in this document to install the package from the new location.

RHEL and variants (CentOS, Fedora, Oracle Linux and Amazon Linux 2)

  • Install yum-utils if it isn't installed yet:

    sudo yum install yum-utils
    
  • Note your distribution and version, and identify the closest entry (by major, then minor) for it under https://packages.microsoft.com/config/rhel/.

    Use the following table to help guide you in locating the package:



    Distro & version Package
    For RHEL/Centos/Oracle 8.0-8.5 https://packages.microsoft.com/config/rhel/8/[channel].repo
    For RHEL/Centos/Oracle 7.2-7.9 & Amazon Linux 2 https://packages.microsoft.com/config/rhel/7/[channel].repo
    For RHEL/Centos 6.7-6.10 https://packages.microsoft.com/config/rhel/6/[channel].repo
    For Fedora 33 https://packages.microsoft.com/config/fedora/33/prod.repo
    For Fedora 34 https://packages.microsoft.com/config/fedora/34/prod.repo

    In the following commands, replace [version] and [channel] with the information you've identified:

    sudo yum-config-manager --add-repo=https://packages.microsoft.com/config/rhel/[version]/[channel].repo
    

    For example, if you are running CentOS 7 and want to deploy Defender for Endpoint on Linux from the prod channel:

    sudo yum-config-manager --add-repo=https://packages.microsoft.com/config/rhel/7/prod.repo
    

    Or if you wish to explore new features on selected devices, you might want to deploy Microsoft Defender for Endpoint on Linux to insiders-fast channel:

    sudo yum-config-manager --add-repo=https://packages.microsoft.com/config/rhel/7/insiders-fast.repo
    
  • Install the Microsoft GPG public key:

    sudo rpm --import http://packages.microsoft.com/keys/microsoft.asc
    
  • Download and make usable all the metadata for the currently enabled yum repositories:

    yum makecache
    

SLES and variants

  • Note your distribution and version, and identify the closest entry(by major, then minor) for it under https://packages.microsoft.com/config/sles/.

    In the following commands, replace [distro] and [version] with the information you've identified:

    sudo zypper addrepo -c -f -n microsoft-[channel] https://packages.microsoft.com/config/[distro]/[version]/[channel].repo
    

    For example, if you are running SLES 12 and wish to deploy Microsoft Defender for Endpoint on Linux from the prod channel:

    sudo zypper addrepo -c -f -n microsoft-prod https://packages.microsoft.com/config/sles/12/prod.repo
    
  • Install the Microsoft GPG public key:

    sudo rpm --import http://packages.microsoft.com/keys/microsoft.asc
    

Ubuntu and Debian systems

  • Install curl if it isn't installed yet:

    sudo apt-get install curl
    
  • Install libplist-utils if it isn't installed yet:

    sudo apt-get install libplist-utils
    
  • Note your distribution and version, and identify the closest entry (by major, then minor) for it under https://packages.microsoft.com/config/[distro]/.

    In the below command, replace [distro] and [version] with the information you've identified:

    curl -o microsoft.list https://packages.microsoft.com/config/[distro]/[version]/[channel].list
    

    For example, if you are running Ubuntu 18.04 and wish to deploy Microsoft Defender for Endpoint on Linux from the prod channel:

    curl -o microsoft.list https://packages.microsoft.com/config/ubuntu/18.04/prod.list
    
  • Install the repository configuration:

    sudo mv ./microsoft.list /etc/apt/sources.list.d/microsoft-[channel].list
    

    For example, if you chose prod channel:

    sudo mv ./microsoft.list /etc/apt/sources.list.d/microsoft-prod.list
    
  • Install the gpg package if not already installed:

    sudo apt-get install gpg
    

    If gpg is not available, then install gnupg.

  • Install the Microsoft GPG public key:

    curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
    
  • Install the https driver if it's not already present:

    sudo apt-get install apt-transport-https
    
  • Update the repository metadata:

    sudo apt-get update
    

Application installation

  • RHEL and variants (CentOS and Oracle Linux):

    sudo yum install mdatp
    

    If you have multiple Microsoft repositories configured on your device, you can be specific about which repository to install the package from. The following example shows how to install the package from the production channel if you also have the insiders-fast repository channel configured on this device. This situation can happen if you are using multiple Microsoft products on your device. Depending on the distribution and the version of your server, the repository alias might be different than the one in the following example.

    # list all repositories
    yum repolist
    
    ...
    packages-microsoft-com-prod               packages-microsoft-com-prod        316
    packages-microsoft-com-prod-insiders-fast packages-microsoft-com-prod-ins      2
    ...
    
    # install the package from the production repository
    sudo yum --enablerepo=packages-microsoft-com-prod install mdatp
    
  • SLES and variants:

    sudo zypper install mdatp
    

    If you have multiple Microsoft repositories configured on your device, you can be specific about which repository to install the package from. The following example shows how to install the package from the production channel if you also have the insiders-fast repository channel configured on this device. This situation can happen if you are using multiple Microsoft products on your device.

    zypper repos
    
    ...
    #  | Alias | Name | ...
    XX | packages-microsoft-com-insiders-fast | microsoft-insiders-fast | ...
    XX | packages-microsoft-com-prod | microsoft-prod | ...
    ...
    
    
    sudo zypper install packages-microsoft-com-prod:mdatp
    
  • Ubuntu and Debian system:

    sudo apt-get install mdatp
    

    If you have multiple Microsoft repositories configured on your device, you can be specific about which repository to install the package from. The following example shows how to install the package from the production channel if you also have the insiders-fast repository channel configured on this device. This situation can happen if you are using multiple Microsoft products on your device.

    cat /etc/apt/sources.list.d/*
    
    deb [arch=arm64,armhf,amd64] https://packages.microsoft.com/config/ubuntu/18.04/prod insiders-fast main
    deb [arch=amd64] https://packages.microsoft.com/config/ubuntu/18.04/prod bionic main
    
    sudo apt -t bionic install mdatp
    

Download the onboarding package

Download the onboarding package from Microsoft 365 Defender portal:

  1. In the Microsoft 365 Defender portal, go to Settings > Endpoints > Device management > Onboarding.

  2. In the first drop-down menu, select Linux Server as the operating system. In the second drop-down menu, select Local Script as the deployment method.

  3. Select Download onboarding package. Save the file as WindowsDefenderATPOnboardingPackage.zip.

    Microsoft 365 Defender portal screenshot.

  4. From a command prompt, verify that you have the file. Extract the contents of the archive:

    ls -l
    
    total 8
    -rw-r--r-- 1 test  staff  5752 Feb 18 11:22 WindowsDefenderATPOnboardingPackage.zip
    
    unzip WindowsDefenderATPOnboardingPackage.zip
    
    Archive:  WindowsDefenderATPOnboardingPackage.zip
    inflating: MicrosoftDefenderATPOnboardingLinuxServer.py
    

Client configuration

  1. Copy MicrosoftDefenderATPOnboardingLinuxServer.py to the target device.

    Initially the client device is not associated with an organization. Note that the orgId attribute is blank:

    mdatp health --field org_id
    
  2. Run MicrosoftDefenderATPOnboardingLinuxServer.py.

    Note

    To run this command, you must have python installed on the device. If you're running RHEL 8.x or Ubuntu 20.04 or higher, then you will need to use Python 3 instead of Python.

    python MicrosoftDefenderATPOnboardingLinuxServer.py
    
  3. Verify that the device is now associated with your organization and reports a valid organization identifier:

    mdatp health --field org_id
    
  4. A few minutes after you complete the installation, you can see the status by running the following command. A return value of 1 denotes that the product is functioning as expected:

    mdatp health --field healthy
    

    Important

    When the product starts for the first time, it downloads the latest antimalware definitions. Depending on your Internet connection, this can take up to a few minutes. During this time the above command returns a value of false. You can check the status of the definition update using the following command:

    mdatp health --field definitions_status
    

    Please note that you may also need to configure a proxy after completing the initial installation. See Configure Defender for Endpoint on Linux for static proxy discovery: Post-installation configuration.

  5. Run a detection test to verify that the device is properly onboarded and reporting to the service. Perform the following steps on the newly onboarded device:

    • Ensure that real-time protection is enabled (denoted by a result of 1 from running the following command):

      mdatp health --field real_time_protection_enabled
      
    • Open a Terminal window. Copy and execute the following command:

      curl -o /tmp/eicar.com.txt https://www.eicar.org/download/eicar.com.txt
      
    • The file should have been quarantined by Defender for Endpoint on Linux. Use the following command to list all the detected threats:

      mdatp threat list
      

Experience Linux endpoint detection and response (EDR) capabilities with simulated attacks

To test out the functionalities of EDR for Linux, follow the steps below to simulate a detection on your Linux server and investigate the case.

  1. Verify that the onboarded Linux server appears in Microsoft 365 Defender. If this is the first onboarding of the machine, it can take up to 20 minutes until it appears.

  2. Download and extract the script file to an onboarded Linux server and run the following command: ./mde_linux_edr_diy.sh

  3. After a few minutes, a detection should be raised in Microsoft 365 Defender.

  4. Look at the alert details, machine timeline, and perform your typical investigation steps.

Installer script

Alternatively, you can use an automated installer bash script provided in our public GitHub repository. The script identifies the distribution and version, and sets up the device to pull the latest package and install it. You can also onboard with a provided script.

❯ ./mde_installer.sh --help
usage: basename ./mde_installer.sh [OPTIONS]
Options:
-c|--channel      specify the channel from which you want to install. Default: insiders-fast
-i|--install      install the product
-r|--remove       remove the product
-u|--upgrade      upgrade the existing product
-o|--onboard      onboard/offboard the product with <onboarding_script>
-p|--passive-mode set EPP to passive mode
-t|--tag          set a tag by declaring <name> and <value>. ex: -t GROUP Coders
-m|--min_req      enforce minimum requirements
-w|--clean        remove repo from package manager for a specific channel
-v|--version      print out script version
-h|--help         display help

Read more here.

Log installation issues

See Log installation issues for more information on how to find the automatically generated log that is created by the installer when an error occurs.

Operating system upgrades

When upgrading your operating system to a new major version, you must first uninstall Defender for Endpoint on Linux, install the upgrade, and finally reconfigure Defender for Endpoint on Linux on your device.

How to migrate from Insiders-Fast to Production channel

  1. Uninstall the "Insiders-Fast channel" version of Defender for Endpoint on Linux.

    sudo yum remove mdatp
    
  2. Disable the Defender for Endpoint on Linux Insiders-Fast repo

    sudo yum repolist
    

    Note

    The output should show "packages-microsoft-com-fast-prod".

    sudo yum-config-manager --disable packages-microsoft-com-fast-prod
    
  3. Redeploy Microsoft Defender for Endpoint on Linux using the "Production channel".

Uninstallation

See Uninstall for details on how to remove Defender for Endpoint on Linux from client devices.

See also