Edit

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 for the current software version, see the main Defender for Endpoint on Linux page.

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 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 have been installed on your Puppet server.

Create the folders install_mdatp/files and install_mdatp/manifests under the modules folder of your Puppet installation. This folder is typically located in /etc/puppetlabs/code/environments/production/modules on your Puppet server. Copy the mdatp_onboard.json file created above to the install_mdatp/files folder. 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

Contents of install_mdatp/manifests/init.pp

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.

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.

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'.

# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
# @param channel The release channel based on your environment, insider-fast or prod.
# @param distro The Linux distribution in lowercase. In case of RedHat, Oracle Linux, Amazon Linux 2, and CentOS 8, the distro variable should be 'rhel'.
# @param version The Linux distribution release number, e.g. 7.4.

class install_mdatp (
  $channel = 'insiders-fast',
  $distro = undef,
  $version = undef
) {
  case $facts['os']['family'] {
    'Debian' : {
      $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',
        },
      }
    }
    'RedHat' : {
      yumrepo { 'microsoftpackages' :
        baseurl  => "https://packages.microsoft.com/${distro}/${version}/${channel}",
        descr    => "packages-microsoft-com-prod-${channel}",
        enabled  => 1,
        gpgcheck => 1,
        gpgkey   => 'https://packages.microsoft.com/keys/microsoft.asc',
      }
    }
    default : { fail("${facts['os']['family']} is currently not supported.") }
  }

  case $facts['os']['family'] {
    /(Debian|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'],
      }

      package { 'mdatp':
        ensure  => 'installed',
        require => File['/etc/opt/microsoft/mdatp/mdatp_onboard.json'],
      }
    }
    default : { fail("${facts['os']['family']} is currently not supported.") }
  }
}

Deployment

Include the above manifest 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 are detected.

Monitor Puppet deployment

On the agent device, you can also check the onboarding status by running:

mdatp health

...
licensed                                : true
org_id                                  : "[your organization identifier]"
...

  • licensed: This confirms that the device is tied to your organization.

  • orgId: This is your Defender for Endpoint organization identifier.

Check onboarding status

You can check that devices have been correctly onboarded by creating a script. For example, the following script checks enrolled devices for onboarding status:

mdatp health --field healthy

The above command prints 1 if the product is onboarded and functioning as expected.

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 0.

If the product is not healthy, the exit code (which can be checked through echo $?) indicates the problem:

  • 1 if the device isn't onboarded yet.
  • 3 if the connection to the daemon cannot be established.

Log installation issues

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

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.

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.