Configure and validate exclusions for Microsoft Defender for Endpoint on Linux

Applies to:

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

This article provides information on how to define antivirus and global exclusions for Microsoft Defender for Endpoint. Antivirus exclusions apply to on-demand scans, real-time protection (RTP), and behavior monitoring (BM). Global exclusions apply to real-time protection (RTP), behavior monitoring (BM), and endpoint detection and response (EDR), thus stopping all the associated antivirus detections, EDR alerts, and visibility for the excluded item.

Important

The antivirus exclusions described in this article apply to only antivirus capabilities and not to endpoint detection and response (EDR). Files that you exclude using the antivirus exclusions described in this article can still trigger EDR alerts and other detections. Global exclusions described in this section apply to antivirus and endpoint detection and response capabilities, thus stopping all associated antivirus protection, EDR alerts, and detections. Global exclusions are currently in public preview, and are available in Defender for Endpoint version 101.23092.0012 or later, in the Insiders Slow and Production rings. For EDR exclusions, contact support.

You can exclude certain files, folders, processes, and process-opened files from Defender for Endpoint on Linux.

Exclusions can be useful to avoid incorrect detections on files or software that are unique or customized to your organization. Global exclusions are useful for mitigating performance issues caused by Defender for Endpoint on Linux.

Warning

Defining exclusions lowers the protection offered by Defender for Endpoint on Linux. You should always evaluate the risks that are associated with implementing exclusions, and you should only exclude files that you're confident aren't malicious.

Supported exclusion scopes

As described in an earlier section, we support two exclusion scopes: antivirus (epp) and global (global) exclusions.

Antivirus exclusions can be used to exclude trusted files and processes from real-time protection while still having EDR visibility. Global exclusions are applied at sensor level and to mute the events that match exclusion conditions early in the flow, before any processing is done, thus stopping all EDR alerts and antivirus detections.

Note

Global (global) is a new exclusion scope that we're introducing in addition to antivirus (epp) exclusion scopes that are already supported by Microsoft.

Exclusion Category Exclusion Scope Description
Antivirus Exclusion Antivirus engine
(scope: epp)
Excludes content from antivirus scans and on-demand scans.
Global Exclusion Antivirus and endpoint detections and response engine
(scope: global)
Excludes events from real time protection and EDR visibility. Doesn't apply to on-demand scans by default.

Important

Global exclusions don't apply to network protection, so alerts generated by network protection will still be visible. To exclude processes from network protection, please use mdatp network-protection exclusion

Supported exclusion types

The following table shows the exclusion types supported by Defender for Endpoint on Linux.

Exclusion Definition Examples
File extension All files with the extension, anywhere on the device (not available for global exclusions) .test
File A specific file identified by the full path /var/log/test.log
/var/log/*.log
/var/log/install.?.log
Folder All files under the specified folder (recursively) /var/log/
/var/*/
Process A specific process (specified either by the full path or file name) and all files opened by it.
We recommend using full and trusted process launch path.
/bin/cat
cat
c?t

Important

The paths used must be hard links, not symbolic links, in order to be successfully excluded. You can check if a path is a symbolic link by running file <path-name>. When implementing global process exclusions, exclude only what is necessary to ensure system reliability and security. Verify that the process is known and trusted, specify the complete path to the process location, and confirm that the process will consistently launch from the same trusted full path.

File, folder, and process exclusions support the following wildcards:

Wildcard Description Examples
* Matches any number of any characters including none
(note if this wildcard isn't used at the end of the path then it substitutes only one folder)
/var/*/tmp includes any file in /var/abc/tmp and its subdirectories, and /var/def/tmp and its subdirectories. It doesn't include /var/abc/log or /var/def/log

/var/*/ only includes any files in its subdirectories such as /var/abc/, but not files directly inside /var.

? Matches any single character file?.log includes file1.log and file2.log, but notfile123.log

Note

Wildcards aren't supported while configuring global exclusions. For antivirus exclusions, when using the * wildcard at the end of the path, it matches all files and subdirectories under the parent of the wildcard. File path needs to be present before adding or removing file exclusions with scope as global.

How to configure the list of exclusions

You can configure exclusions using a management Json configuration, Defender for Endpoint security settings management, or the command line.

Using the management console

In enterprise environments, exclusions can also be managed through a configuration profile. Typically, you would use a configuration management tool like Puppet, Ansible, or another management console to push a file with the name mdatp_managed.json at the location /etc/opt/microsoft/mdatp/managed/. For more information, see Set preferences for Defender for Endpoint on Linux. Please refer to the following sample of mdatp_managed.json.

{
   "exclusionSettings":{
     "exclusions":[
        {
           "$type":"excludedPath",
           "isDirectory":true,
           "path":"/home/*/git<EXAMPLE DO NOT USE>",
           "scopes": [
              "epp"
           ]
        },
        {
           "$type":"excludedPath",
           "isDirectory":true,
           "path":"/run<EXAMPLE DO NOT USE>",
           "scopes": [
              "global"
           ]
        },
        {
           "$type":"excludedPath",
           "isDirectory":false,
           "path":"/var/log/system.log<EXAMPLE DO NOT USE><EXCLUDED IN ALL SCENARIOS>",
           "scopes": [
              "epp", "global"
           ]
        },
        {
           "$type":"excludedFileExtension",
           "extension":".pdf<EXAMPLE DO NOT USE>",
           "scopes": [
              "epp"
           ]
        },
        {
           "$type":"excludedFileName",
           "name":"/bin/cat<EXAMPLE DO NOT USE><NO SCOPE PROVIDED - GLOBAL CONSIDERED>"
        }
     ],
     "mergePolicy":"admin_only"
   }
}

Using Defender for Endpoint security settings management

Note

This method is currently in private Preview. To enable this feature, please reach out to xplatpreviewsupport@microsoft.com. Make sure to review the prerequisites: Defender for Endpoint security settings management prerequisites

You can use the Microsoft Intune admin center or the Microsoft Defender portal to manage exclusions as endpoint security policies and assign those policies to Microsoft Entra ID groups. If you're using this method for the first time, make sure to complete the following steps:

1. Configure your tenant to support security settings management

  1. In the Microsoft Defender portal, navigate to Settings > Endpoints > Configuration Management > Enforcement Scope, and then select the Linux platform.

  2. Tag devices with the MDE-Management tag. Most devices enroll and receive the policy within minutes, although some might take up to 24 hours. For more information, see Learn how to use Intune endpoint security policies to manage Microsoft Defender for Endpoint on devices that aren't enrolled with Intune.

2. Create a Microsoft Entra group

Create a dynamic Microsoft Entra group based on the operating system type to ensure that all devices onboarded to Defender for Endpoint receive the appropriate policies. This dynamic group automatically includes devices managed by Defender for Endpoint, eliminating the need for admins to manually create new policies. For more information, see the following article: Create Microsoft Entra Groups

3. Create an endpoint security policy

  1. In the Microsoft Defender portal, go to Endpoints > Configuration management > Endpoint security policies, and then select Create new Policy.

  2. For Platform, select Linux.

  3. Select the required exclusion template (Microsoft defender global exclusions (AV+EDR) for global exclusions and Microsoft defender antivirus exclusions for antivirus exclusions), and then select Create policy.

  4. On the Basics page, enter a name and description for the profile, then choose Next.

  5. On the Settings page, expand each group of settings, and configure the settings you want to manage with this profile.

  6. When you're done configuring settings, select Next.

  7. On the Assignments page, select the groups that receive this profile. Then select Next.

  8. On the Review + create page, when you're done, select Save. The new profile is displayed in the list when you select the policy type for the profile you created.

For more information refer: Manage endpoint security policies in Microsoft Defender for Endpoint.

Using the command line

Run the following command to see the available switches for managing exclusions:

mdatp exclusion

Note

--scope is an optional flag with accepted value as epp or global. It provides the same scope used while adding the exclusion to remove the same exclusion. In the command line approach, if the scope isn't mentioned, the scope value is set as epp. Exclusions added through CLI before the introduction of --scope flag remain unaffected and their scope is considered epp.

Tip

When configuring exclusions with wildcards, enclose the parameter in double-quotes to prevent globbing.

This section includes several examples.

Example 1: Add an exclusion for a file extension

You can add an exclusion for a file extension. Keep in mind that extension exclusions aren't supported for the global exclusion scope.

mdatp exclusion extension add --name .txt
Extension exclusion configured successfully
mdatp exclusion extension remove --name .txt
Extension exclusion removed successfully

Example 2: Add or remove a file exclusion

You can add or remove an exclusion for a file. The file path should already be present if you're adding or removing an exclusion with the global scope.

mdatp exclusion file add --path /var/log/dummy.log --scope epp
File exclusion configured successfully
mdatp exclusion file remove --path /var/log/dummy.log --scope epp
File exclusion removed successfully"
mdatp exclusion file add --path /var/log/dummy.log --scope global
File exclusion configured successfully
mdatp exclusion file remove --path /var/log/dummy.log --scope global
File exclusion removed successfully"

Example 3: Add or remove a folder exclusion

You can add or remove an exclusion for a folder.

mdatp exclusion folder add --path /var/log/ --scope epp
Folder exclusion configured successfully
mdatp exclusion folder remove --path /var/log/ --scope epp
Folder exclusion removed successfully
mdatp exclusion folder add --path /var/log/ --scope global
Folder exclusion configured successfully
mdatp exclusion folder remove --path /var/log/ --scope global
Folder exclusion removed successfully

Example 4: Add an exclusion for a second folder

You can add an exclusion for a second folder.

mdatp exclusion folder add --path /var/log/ --scope epp
mdatp exclusion folder add --path /other/folder  --scope global
Folder exclusion configured successfully

Example 5: Add a folder exclusion with a wildcard

You can add an exclusion for a folder with a wildcard. Keep in mind that Wildcards aren't supported while configuring global exclusions.

mdatp exclusion folder add --path "/var/*/tmp"

The previous command excludes paths under */var/*/tmp/*, but not folders that are siblings of *tmp*. For example, */var/this-subfolder/tmp* is excluded, but */var/this-subfolder/log* isn't excluded.

mdatp exclusion folder add --path "/var/" --scope epp

OR

mdatp exclusion folder add --path "/var/*/" --scope epp

The previous command excludes all paths whose parent is */var/*, such as */var/this-subfolder/and-this-subfolder-as-well*.

Folder exclusion configured successfully

Example 6: Add an exclusion for a process

You can add an exclusion for a process.

mdatp exclusion process add --path /usr/bin/cat --scope global 
Process exclusion configured successfully
mdatp exclusion process remove --path /usr/bin/cat  --scope global

Note

Only full path is supported for setting process exclusion with global scope. Use only --path flag

Process exclusion removed successfully
mdatp exclusion process add --name cat --scope epp 
Process exclusion configured successfully
mdatp exclusion process remove --name cat --scope epp
Process exclusion removed successfully

Example 7: Add an exclusion for a second process

You can add an exclusion for a second process.

mdatp exclusion process add --name cat --scope epp
mdatp exclusion process add --path /usr/bin/dog --scope global
Process exclusion configured successfully

Validate exclusions lists with the EICAR test file

You can validate that your exclusion lists are working by using curl to download a test file.

In the following Bash snippet, replace test.txt with a file that conforms to your exclusion rules. For example, if you have excluded the .testing extension, replace test.txt with test.testing. If you're testing a path, ensure that you run the command within that path.

curl -o test.txt https://secure.eicar.org/eicar.com.txt

If Defender for Endpoint on Linux reports malware, then the rule isn't working. If there's no report of malware, and the downloaded file exists, then the exclusion is working. You can open the file to confirm that the contents are the same as what is described on the EICAR test file website.

If you don't have Internet access, you can create your own EICAR test file. Write the EICAR string to a new text file with the following Bash command:

echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > test.txt

You can also copy the string into a blank text file and attempt to save it with the file name or in the folder you're attempting to exclude.

Allow a threat

In addition to excluding certain content from being scanned, you can also configure Defender for Endpoint on Linux not to detect some classes of threats, identified by the threat name.

Warning

Exercise caution when using this functionality, as it can leave your device unprotected.

To add a threat name to the allowed list, run the following command:

mdatp threat allowed add --name [threat-name]

To get the name of a detected threat, run the following command:

mdatp threat list

For example, to add EICAR-Test-File (not a virus) to the allowlist, run the following command:

mdatp threat allowed add --name "EICAR-Test-File (not a virus)"

See also

Tip

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