使用 Ansible 在 Linux 上部署Microsoft Defender for Endpoint

2025-04-19

适用于：

服务器的Microsoft Defender for Endpoint
服务器计划 1 或计划 2 的Microsoft Defender

希望体验 Defender for Endpoint？注册免费试用版。

可以使用各种工具和方法在 Linux 上部署 Defender for Endpoint 。本文介绍如何使用 Ansible 在 Linux 上部署 Defender for Endpoint。若要使用其他方法，请参阅另请参阅部分。

成功的部署需要完成以下所有任务：

先决条件和系统要求
下载载入包
使用 mde_installer.sh 和 Ansible 在 Linux 上部署 Defender for Endpoint
通过手动配置存储库，使用 Ansible 在 Linux 上部署 Defender for Endpoint

重要

本文包含有关第三方工具的信息。这样做是为了帮助完成集成方案，但是，Microsoft不提供对第三方工具的故障排除支持。
请联系第三方供应商获取支持。

简介

使用 Ansible 在 Linux 服务器上部署Microsoft Defender for Endpoint，以便大规模自动执行计算机的部署过程。下面是自动化的两种方法：

使用 (建议) 的安装程序脚本。此方法大大简化了自动化过程，并且只需执行几个步骤即可安装 Defender for Endpoint 代理并将设备载入Microsoft Defender门户，而无需单独为不同的发行版进行配置。
为每个发行版手动配置存储库。使用此方法，可以通过手动配置存储库、安装代理以及为每个发行版载入设备来自动执行部署过程。此方法可更精细地控制部署过程。

适用于这两种方法的先决条件和系统要求

在开始之前，请参阅 Linux 上的 Defender for Endpoint 的先决条件，了解先决条件和系统要求。

此外，对于 Ansible 部署，需要熟悉 Ansible 管理任务，配置 Ansible，并知道如何部署 playbook 和任务。 Ansible 有许多方法可以完成相同的任务。这些说明假定支持 Ansible 模块（例如 apt 和 unarchive ）的可用性，以帮助部署包。你的组织可能使用不同的工作流。有关详细信息，请参阅 Ansible 文档。

Ansible 需要安装在至少一台计算机上， (Ansible 将此计算机称为控制节点) 。
必须为控制节点与所有托管节点之间的管理员帐户配置 SSH， (设备上安装了 Defender for Endpoint 的设备) ，建议使用公钥身份验证进行配置。
必须在所有托管节点上安装以下软件：
- 卷曲
- python-apt (如果使用 apt 作为包管理器在分发版上进行部署)
必须在或相关文件中以以下格式 /etc/ansible/hosts 列出所有托管节点：
```
[servers]
host1 ansible_ssh_host=10.171.134.39
host2 ansible_ssh_host=51.143.50.51
```
Ping 测试：
```
ansible -m ping all
```

下载适用于这两种方法的载入包

从 Microsoft Defender 门户下载载入包。

警告

不支持重新打包 Defender for Endpoint 安装包。这样做可能会对产品的完整性产生负面影响，并导致不良结果，包括但不限于触发篡改警报和无法应用的更新。

在Microsoft Defender门户中，转到“设置>终结点”“>设备管理>”“载入”。
在第一个下拉菜单中，选择“ Linux 服务器 ”作为作系统。在第二个下拉菜单中，选择“ 首选 Linux 配置管理工具 ”作为部署方法。
选择“下载载入包”。将文件另存为 WindowsDefenderATPOnboardingPackage.zip。

在命令提示符下，验证是否具有文件。提取存档的内容：

unzip WindowsDefenderATPOnboardingPackage.zip

Archive:  WindowsDefenderATPOnboardingPackage.zip
inflating: mdatp_onboard.json

使用 mde_installer.sh 和 Ansible 部署 Defender for Endpoint

在开始之前，请确保下载载入包，并满足使用安装程序 bash 脚本在 Linux 上部署 Defender for Endpoint 的先决条件。

下载安装程序 bash 脚本

从 GitHub 存储库Microsoft拉取安装程序 bash 脚本，或使用以下命令下载它。

  wget https://raw.githubusercontent.com/microsoft/mdatp-xplat/refs/heads/master/linux/installation/mde_installer.sh

创建 Ansible YAML 文件

创建安装 YAML 文件。也可以直接从 GitHub 下载文件。

- name: Install and Onboard MDE
  hosts: servers
  tasks:
   - name: Create a directory if it does not exist
     ansible.builtin.file:
       path: /tmp/mde_install
       state: directory
       mode: '0755'

   - name: Copy Onboarding script
     ansible.builtin.copy:
       src: "{{ onboarding_json }}"
       dest: /tmp/mde_install/mdatp_onboard.json
   - name: Install MDE on host
     ansible.builtin.script: "{{ mde_installer_script }} --install --channel {{ channel | default('insiders-fast') }} --onboard /tmp/mde_install/mdatp_onboard.json"
     register: script_output
     args:
       executable: sudo

   - name: Display the installation output
     debug:
       msg: "Return code [{{ script_output.rc }}] {{ script_output.stdout }}"

   - name: Display any installation errors
     debug:
       msg: "{{ script_output.stderr }}"

注意

安装程序脚本还支持其他参数，例如通道、实时保护、版本等。若要从可用选项列表中选择，请通过以下命令检查帮助：./mde_installer.sh --help

应用 playbook

使用以下命令应用 playbook，根据要求替换相应的路径和通道：

ansible-playbook -i  /etc/ansible/hosts /etc/ansible/playbooks/install_mdatp.yml --extra-vars "onboarding_json=<path to mdatp_onboard.json > mde_installer_script=<path to mde_installer.sh> channel=<channel to deploy for: insiders-fast / insiders-slow / prod> "

验证部署是否成功

在Microsoft Defender门户中，打开设备清单。设备可能需要 5-20 分钟才能显示在门户中。
执行以下安装后检查，包括运行状况、连接性、防病毒和 EDR 检测测试等检查，以确保 Defender for Endpoint 的成功部署和工作。

- name: Run post-installation basic MDE test
  hosts: myhosts
  tasks:
    - name: Check health
      ansible.builtin.command: mdatp health --field healthy
      register: health_status

    - name: MDE health test failed
      fail: msg="MDE is not healthy. health status => \n{{ health_status.stdout       }}\nMDE deployment not complete"
      when: health_status.stdout != "true"

    - name: Run connectivity test
      ansible.builtin.command: mdatp connectivity test
      register: connectivity_status

    - name: Connectivity failed
      fail: msg="Connectivity failed. Connectivity result => \n{{ connectivity_status.stdout }}\n MDE deployment not complete"
      when: connectivity_status.rc != 0

    - name: Check RTP status
      ansible.builtin.command: mdatp health --field real_time_protection_enabled
      register: rtp_status

    - name: Enable RTP
      ansible.builtin.command: mdatp config real-time-protection --value enabled
      become: yes
      become_user: root
      when: rtp_status.stdout != "true"

    - name: Pause for 5 second to enable RTP
      ansible.builtin.pause:
        seconds: 5

    - name: Download EICAR
      ansible.builtin.get_url:
        url: https://secure.eicar.org/eicar.com.txt
        dest: /tmp/eicar.com.txt

    - name: Pause for 5 second to detect eicar 
      ansible.builtin.pause:
        seconds: 5

    - name: Check for EICAR file
      stat: path=/tmp/eicar.com.txt
      register: eicar_test

    - name: EICAR test failed
      fail: msg="EICAR file not deleted. MDE deployment not complete"
      when: eicar_test.stat.exists

    - name: MDE Deployed
      debug:
        msg: "MDE succesfully deployed"

如何在 Linux 服务器上卸载Microsoft Defender for Endpoint

首先，创建一个卸载 YAML 文件 (，例如：/etc/ansible/playbooks/uninstall_mdatp.yml) ，它使用 mde_installer.sh。还可以直接从 GitHub 下载文件

- name: Uninstall MDE
  hosts: myhosts
  tasks:
   - name: Uninstall MDE
     ansible.builtin.script: "{{ mde_installer_script }} --remove"
     register: script_output
     args:
       executable: sudo


- name: Display the installation output
  debug:
    msg: "Return code [{{ script_output.rc }}] {{ script_output.stdout }}"

- name: Display any installation errors
  debug:
    msg: "{{ script_output.stderr }}"

运行以下命令，使用 playbook 卸载 Defender for Endpoint：

ansible-playbook -i /etc/ansible/hosts /etc/ansible/playbooks/uninstall_mdatp.yml --extra-vars "mde_installer_script=<path to mde_installer.sh>"

通过手动配置存储库，使用 Ansible 部署 Defender for Endpoint

下载载入包并满足先决条件后，按照本部分中的步骤，通过手动配置每个 Linux 分发版的存储库来部署 Defender for Endpoint。

创建 Ansible YAML 文件

创建为 playbook 或任务做出贡献的子任务或角色文件。

创建载入任务 onboarding_setup.yml：

- name: Create MDATP directories
  file:
    path: /etc/opt/microsoft/mdatp/
    recurse: true
    state: directory
    mode: 0755
    owner: root
    group: root

- name: Register mdatp_onboard.json
  stat:
    path: /etc/opt/microsoft/mdatp/mdatp_onboard.json
  register: mdatp_onboard

- name: Extract WindowsDefenderATPOnboardingPackage.zip into /etc/opt/microsoft/mdatp
  unarchive:
    src: WindowsDefenderATPOnboardingPackage.zip
    dest: /etc/opt/microsoft/mdatp
    mode: 0600
    owner: root
    group: root
  when: not mdatp_onboard.stat.exists

添加 Defender for Endpoint 存储库和密钥 add_apt_repo.yml。可以从以下通道之一部署 Linux 上的 Defender for Endpoint：
- insiders-fast，表示为 [channel]insiders-slow，表示为 [channel]
- prod，表示为 [channel] 使用版本名称 (请参阅适用于Microsoft产品的 Linux 软件存储库)
每个通道对应于一个 Linux 软件存储库。

通道的选择决定了提供给设备的更新的类型和频率。 预览体验成员中的设备是第一个接收更新和新功能的设备，然后是预览体验成员慢，最后是 prod。

为了预览新功能并提供早期反馈，建议在企业中配置一些设备，以使用 预览体验成员快速 或 预览体验成员慢速。

警告

在初始安装后切换通道需要重新安装产品。若要切换产品通道：卸载现有包，重新配置设备以使用新通道，然后按照本文档中的步骤从新位置安装包。
记下分发版和版本，并在下 https://packages.microsoft.com/config/[distro]/标识其最接近的条目。

在以下命令中，将 [发行版] 和 [版本] 替换为已识别的信息。

注意

对于 Oracle Linux 和 Amazon Linux 2，请将 [发行版] 替换为“rhel”。对于 Amazon Linux 2，请将 [版本] 替换为“7”。对于 Oracle Linux，请将 [版本] 替换为 Oracle Linux 的版本。

- name: Add Microsoft APT key
  apt_key:
    url: https://packages.microsoft.com/keys/microsoft.asc
    state: present
  when: ansible_os_family == "Debian"

- name: Add Microsoft apt repository for MDATP
  apt_repository:
    repo: deb [arch=arm64,armhf,amd64] https://packages.microsoft.com/[distro]/[version]/prod [codename] main
    update_cache: yes
    state: present
    filename: microsoft-[channel]
  when: ansible_os_family == "Debian"

- name: Add Microsoft DNF/YUM key
  rpm_key:
    state: present
    key: https://packages.microsoft.com/keys/microsoft.asc
  when: ansible_os_family == "RedHat"

- name: Add  Microsoft yum repository for MDATP
  yum_repository:
    name: packages-microsoft-[channel]
    description: Microsoft Defender for Endpoint
    file: microsoft-[channel]
    baseurl: https://packages.microsoft.com/[distro]/[version]/[channel]/ 
    gpgcheck: yes
    enabled: Yes
  when: ansible_os_family == "RedHat"

创建 Ansible 安装和卸载 YAML 文件。

对于基于 apt 的分发版，请使用以下 YAML 文件：

cat install_mdatp.yml

- hosts: servers
   tasks:
     - name: include onboarding tasks
       import_tasks:
         file: ../roles/onboarding_setup.yml
     - name: add apt repository
       import_tasks:
         file: ../roles/add_apt_repo.yml
     - name: Install MDATP
       apt:
         name: mdatp
         state: latest
         update_cache: yes

cat uninstall_mdatp.yml

- hosts: servers
   tasks:
     - name: Uninstall MDATP
       apt:
         name: mdatp
         state: absent

对于基于 dnf 的分发版，请使用以下 YAML 文件：

cat install_mdatp_dnf.yml

- hosts: servers
   tasks:
     - name: include onboarding tasks
       import_tasks:
         file: ../roles/onboarding_setup.yml
     - name: add apt repository
       import_tasks:
         file: ../roles/add_yum_repo.yml
     - name: Install MDATP
       dnf:
         name: mdatp
         state: latest
         enablerepo: packages-microsoft-[channel]

cat uninstall_mdatp_dnf.yml

- hosts: servers
   tasks:
     - name: Uninstall MDATP
       dnf:
         name: mdatp
         state: absent

应用 playbook

在此步骤中，将应用 playbook。运行或相关目录下 /etc/ansible/playbooks/ 的任务文件。

安装：
```
ansible-playbook /etc/ansible/playbooks/install_mdatp.yml -i /etc/ansible/hosts
```
重要

产品首次启动时，会下载最新的反恶意软件定义。这可能需要几分钟时间，具体取决于 Internet 连接。

验证/配置：

ansible -m shell -a 'mdatp connectivity test' all

ansible -m shell -a 'mdatp health' all

卸载：

ansible-playbook /etc/ansible/playbooks/uninstall_mdatp.yml -i /etc/ansible/hosts

解决安装问题

如果遇到任何安装问题，请执行以下步骤进行自我故障排除：

有关如何查找发生安装错误时自动生成的日志的信息，请参阅日志安装问题。
有关常见安装问题的信息，请参阅安装问题。
如果设备的运行状况为 false，请参阅 Defender for Endpoint 代理运行状况问题。
有关产品性能问题，请参阅排查性能问题。
有关代理和连接问题，请参阅排查云连接问题。

若要从Microsoft获取支持，请打开支持票证，并使用客户端分析器提供创建的日志文件。

如何在 Linux 上为Microsoft Defender配置策略

Defender for Endpoint 安全设置管理介绍了如何在Microsoft Defender门户中配置设置。 (建议使用此方法。)
在 Linux 上设置 Defender for Endpoint 的首选项介绍了可以配置的设置。

作系统升级

将作系统升级到新的主版本时，必须先卸载 Linux 上的 Defender for Endpoint，安装升级，最后在设备上重新配置 Linux 上的 Defender for Endpoint。

另请参阅

提示

想要了解更多信息？ Engage技术社区中的Microsoft安全社区：Microsoft Defender for Endpoint技术社区。

通过

使用 Ansible 在 Linux 上部署Microsoft Defender for Endpoint

简介

适用于这两种方法的先决条件和系统要求

下载适用于这两种方法的载入包

使用 mde_installer.sh 和 Ansible 部署 Defender for Endpoint

下载安装程序 bash 脚本

创建 Ansible YAML 文件

应用 playbook

验证部署是否成功

如何在 Linux 服务器上卸载Microsoft Defender for Endpoint

通过手动配置存储库，使用 Ansible 部署 Defender for Endpoint

创建 Ansible YAML 文件

应用 playbook

解决安装问题

如何在 Linux 上为Microsoft Defender配置策略

作系统升级

另请参阅

反馈

其他资源