Edit

Share via

Deploy Microsoft Defender for Endpoint on Linux with Puppet

  • Article

Applies to:

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

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

Important

This article contains information about third-party tools. This is provided to help complete integration scenarios, however, Microsoft does not provide troubleshooting support for third-party tools.
Contact the third-party vendor for support.

Prerequisites and system requirements

For a description of prerequisites and system requirements, see Microsoft Defender for Endpoint on Linux.

In addition, for Puppet deployment, you need to be familiar with Puppet administration tasks, have Puppet configured, and know how to deploy packages. Puppet has many ways to complete the same task. These instructions assume availability of supported Puppet modules, such as apt to help deploy the package. Your organization might use a different workflow. Refer to the Puppet documentation for details.

Download the onboarding package

Download the onboarding package from Microsoft Defender portal.

Warning

Repackaging the Defender for Endpoint installation package is not a supported scenario. Doing so can negatively impact the integrity of the product and lead to adverse results, including but not limited to triggering tampering alerts and updates failing to apply.

  1. In the Microsoft 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 Your preferred Linux configuration management tool as the deployment method.

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

    The option to download the onboarded package.

  4. From a command prompt, verify that you have the file.

    ls -l

    total 8
-rw-r--r-- 1 test  staff  4984 Feb 18 11:22 WindowsDefenderATPOnboardingPackage.zip

  5. Extract the contents of the archive.

    unzip WindowsDefenderATPOnboardingPackage.zip

    Archive:  WindowsDefenderATPOnboardingPackage.zip
inflating: mdatp_onboard.json

Create a Puppet manifest

You need to create a Puppet manifest for deploying Defender for Endpoint on Linux to devices managed by a Puppet server. This example makes use of the apt and yumrepo modules available from puppetlabs, and assumes that the modules are installed on your Puppet server.

  1. Under the modules folder if your Puppet installation, create the folders install_mdatp/files and install_mdatp/manifests. The modules folder is typically located at /etc/puppetlabs/code/environments/production/modules on your Puppet server.

  2. Copy the mdatp_onboard.json file created earlier to the install_mdatp/files folder.

  3. Create an init.pp file that contains the deployment instructions:

    pwd

    /etc/puppetlabs/code/environments/production/modules

    tree install_mdatp

    install_mdatp
├── files
│   └── mdatp_onboard.json
└── manifests
    └── init.pp

Create a manifest file

There are two ways to create a manifest file:

  • Use an installer script; or
  • Configure your repositories manually.

Create a manifest to deploy Defender for Endpoint using an installer script

Add the following content to the install_mdatp/manifests/init.pp file. You can also download the file directly from GitHub


# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
# @param channel The release channel based on your environment, insider-fast or prod.

class install_mdatp (
  $channel = 'prod',
) {
  # Ensure that the directory /tmp/mde_install exists
  file { '/tmp/mde_install':
    ensure => directory,
    mode   => '0755',
  }

  # Copy the installation script to the destination
  file { '/tmp/mde_install/mde_installer.sh':
    ensure => file,
    source => 'puppet:///modules/install_mdatp/mde_installer.sh',
    mode   => '0777',
  }

  # Copy the onboarding script to the destination
  file { '/tmp/mde_install/mdatp_onboard.json':
    ensure => file,
    source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
    mode   => '0777',
  }

  # Install MDE on the host using an external script
  exec { 'install_mde':
    command     => "/tmp/mde_install/mde_installer.sh --install --channel ${channel} --onboard /tmp/mde_install/mdatp_onboard.json",
    path        => '/bin:/usr/bin',
    user        => 'root',
    logoutput   => true,
    require     => File['/tmp/mde_install/mde_installer.sh', '/tmp/mde_install/mdatp_onboard.json'], # Ensure the script is copied before running the installer
  }

}

Create a manifest to deploy Defender for Endpoint by configuring repositories manually

Defender for Endpoint on Linux can be deployed from one of the following channels:

Each channel corresponds to a Linux software repository.

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, we recommend 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.

Note your distribution and version and identify the closest entry for it under https://packages.microsoft.com/config/[distro]/.

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

Note

In case of RedHat, Oracle Linux, Amazon Linux 2, and CentOS 8, replace [distro] with 'rhel'.

Add the following content to the install_mdatp/manifests/init.pp file:

# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
# @param channel The release channel based on your environment, insider-fast or prod.

class install_mdatp::configure_debian_repo (
  String $channel,
  String $distro,
  String $version ) {
  # Configure the APT repository for Debian-based systems

  $release = $channel ? {
    'prod'  => $facts['os']['distro']['codename'],
    default => $channel
    }
  
  apt::source { 'microsoftpackages':
    location => "https://packages.microsoft.com/${distro}/${version}/prod",
    release  => $release,
    repos    => 'main',
    key      => {
      'id'     => 'BC528686B50D79E339D3721CEB3E94ADBE1229CF',
      'server' => 'keyserver.ubuntu.com',
    },
  }
}

class install_mdatp::configure_redhat_repo (
  String $channel,
  String $distro,
  String $version) {
  # Configure the Yum repository for RedHat-based systems
  
  yumrepo { 'microsoftpackages':
    baseurl  => "https://packages.microsoft.com/rhel/${version}/prod",
    descr    => 'packages-microsoft-com-prod',
    enabled  => 1,
    gpgcheck => 1,
    gpgkey   => 'https://packages.microsoft.com/keys/microsoft.asc',
  }
}

class install_mdatp::install {
  # Common configurations for both Debian and RedHat
  
  file { ['/etc/opt', '/etc/opt/microsoft', '/etc/opt/microsoft/mdatp']:
    ensure  => directory,
    owner   => 'root',
    group   => 'root',
    mode    => '0755',
  }

  file { '/etc/opt/microsoft/mdatp/mdatp_onboard.json':
    source  => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
    owner   => 'root',
    group   => 'root',
    mode    => '0600',
    require => File['/etc/opt/microsoft/mdatp'],
  }

  # Install mdatp package
  package { 'mdatp':
    ensure  => installed,
    require => [
      File['/etc/opt/microsoft/mdatp/mdatp_onboard.json'],
    ],
  }
}


class install_mdatp (
  $channel = 'prod'
) {
  # Include the appropriate class based on the OS family
  
  $distro = downcase($facts['os']['name'])
  $version = $facts['os']['release']['major']
  
  case $facts['os']['family'] {
    'Debian': {
      class { 'install_mdatp::configure_debian_repo':
        channel => 'prod',
        distro => $distro,
        version => $version
        } -> class { 'install_mdatp::install': }
    }
    'RedHat': {
      class { 'install_mdatp::configure_redhat_repo':
        channel => 'prod',
        distro => $distro,
        version => $version,
        } -> class { 'install_mdatp::install': }
    }
    default: { fail("${facts['os']['family']} is currently not supported.")}
  }
}

Include the manifest inside the site.pp file

Include the manifest described earlier in this article in your site.pp file:

cat /etc/puppetlabs/code/environments/production/manifests/site.pp

node "default" {
    include install_mdatp
}

Enrolled agent devices periodically poll the Puppet Server and install new configuration profiles and policies as soon as they're detected.

Monitor Puppet deployment

On the agent device, you can also check the deployment status by running the following command:

mdatp health

...
healthy                                 : true
health_issues                           : []
licensed                                : true
org_id                                  : "[your organization identifier]"
...
  • healthy: Confirm that Defender for Endpoint is successfully deployed and operational.
  • health_issues: States the issues which caused the healthy status to become false.
  • licensed: Confirms that the device is tied to your organization.
  • orgId: Your Defender for Endpoint organization identifier.

Troubleshoot installation issues

If you encounter issues during installation, try these self-troubleshooting steps:

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

  2. Refer to Installation issues for more information on commonly occurring installation issues

  3. If health of the device is false, refer to MDE agent health issues

  4. For product performance issues, refer to Troubleshoot performance issues, performance tuning

  5. For proxy and connectivity issues, refer to Troubleshoot cloud connectivity issues

To get support from Microsoft, raise a support ticket and provide log files by using the client analyzer

How to configure policies for Microsoft Defender on Linux

You can configure antivirus and EDR settings on your endpoints using following methods:

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 then reconfigure Defender for Endpoint on Linux on your device.

Uninstallation

Create a module remove_mdatp similar to install_mdatp with the following contents in init.pp file:

class remove_mdatp {
    package { 'mdatp':
        ensure => 'purged',
    }
}

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.