Deploy Defender for Endpoint on Linux with Chef

Applies to:


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.

Before you begin: Install unzip if it's not already installed.

The Chef components are already installed and a Chef repository exists (chef generate repo <reponame>) to store the cookbook that will be used to deploy to Defender for Endpoint on Chef managed Linux servers.

You can create a new cookbook in your existing repository by running the following command from inside the cookbooks folder that is in your chef repository:

chef generate cookbook mdatp

This command will create a new folder structure for the new cookbook called mdatp. You can also use an existing cookbook if you already have one you'd like to use to add the MDE deployment into. After the cookbook is created, create a files folder inside the cookbook folder that just got created:

mkdir mdatp/files

Transfer the Linux Server Onboarding zip file that can be downloaded from the Microsoft 365 Defender portal to this new files folder.


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.

On the Chef Workstation, navigate to the mdatp/recipes folder. This folder is created when the cookbook was generated. Use your preferred text editor (like vi or nano) to add the following instructions to the end of the default.rb file:

  • include_recipe '::onboard_mdatp'
  • include_recipe '::install_mdatp'

Then save and close the default.rb file.

Next create a new recipe file named install_mdatp.rb in the recipes folder and add this text to the file:

#Add Microsoft Defender
case node['platform_family']
when 'debian'
 apt_repository 'MDAPRepo' do
   arch               'amd64'
   cache_rebuild      true
   cookbook           false
   deb_src            false
   key                'BC528686B50D79E339D3721CEB3E94ADBE1229CF'
   keyserver          ""
   distribution       'focal'
   repo_name          'microsoft-prod'
   components         ['main']
   trusted            true
   uri                ""
 apt_package "mdatp"
when 'rhel'
 yum_repository 'microsoft-prod' do
   baseurl            ""
   description        "Microsoft Defender for Endpoint"
   enabled            true
   gpgcheck           true
   gpgkey             ""
 if node['platform_version'] <= 8 then
    yum_package "mdatp"
    dnf_package "mdatp"

You'll need to modify the version number, distribution, and repo name to match the version you're deploying to and the channel you'd like to deploy. Next you should create an onboard_mdatp.rb file in the mdatp/recipies folder. Add the following text to that file:

#Create MDATP Directory
mdatp = "/etc/opt/microsoft/mdatp"
zip_path = "/path/to/chef-repo/cookbooks/mdatp/files/"

directory "#{mdatp}" do
  owner 'root'
  group 'root'
  mode 0755
  recursive true

#Extract into /etc/opt/microsoft/mdatp

bash 'Extract Onbaording Json MDATP' do
  code <<-EOS
  unzip #{zip_path} -d #{mdatp}
  not_if { ::File.exist?('/etc/opt/microsoft/mdatp/mdatp_onboard.json') }

Make sure to update the path name to the location of the onboarding file. To test deploy it on the Chef workstation, just run sudo chef-client -z -o mdatp. After your deployment you should consider creating and deploying a configuration file to the servers based on Set preferences for Microsoft Defender for Endpoint on Linux. After you've created and tested your configuration file, you can place it into the cookbook/mdatp/files folder where you also placed the onboarding package. Then you can create a settings_mdatp.rb file in the mdatp/recipies folder and add this text:

#Copy the configuration file
cookbook_file '/etc/opt/microsoft/mdatp/managed/mdatp_managed.json' do
  source 'mdatp_managed.json'
  owner 'root'
  group 'root'
  mode '0755'
  action :create

To include this step as part of the recipe just add include_recipe ':: settings_mdatp' to your default.rb file within the recipe folder. You can also use crontab to schedule automatic updates Schedule an update of the Microsoft Defender for Endpoint (Linux).

Uninstall MDATP cookbook:

#Uninstall the Defender package
case node['platform_family']
when 'debian'
 apt_package "mdatp" do
   action :remove
when 'rhel'
 if node['platform_version'] <= 8
    yum_package "mdatp" do
      action :remove
    dnf_package "mdatp" do
      action :remove


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