Configure security settings in Microsoft Defender for Endpoint on Linux

Applies to:

• Microsoft Defender for Endpoint for servers
• Microsoft Defender for Servers Plan 1 or Plan 2

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

Configure your security settings

Microsoft Defender for Endpoint on Linux includes antivirus, anti-malware protection, endpoint detection, and response capabilities. This article summarizes important security settings to configure and includes links to additional resources.

Options for configuring security settings

To configure your security settings in Defender for Endpoint on Linux, you have two main options:

• Use the Microsoft Defender portal (Defender for Endpoint Security Settings Management); or
• Use a configuration profile

If you prefer to use command line, you can use that to configure certain settings, gather diagnostics, run scans, and more. See Linux resources: Configure using command line.

Defender for Endpoint Security Settings Management

You can configure Defender for Endpoint on Linux in the Microsoft Defender portal (https://security.microsoft.com) through functionality known as Defender for Endpoint Security Settings Management. For more information, including how to create, edit, and verify security policies, see Use Microsoft Defender for Endpoint Security Settings Management to manage Microsoft Defender Antivirus.

Configuration profile

You can configure settings in Defender for Endpoint on Linux through a configuration profile that uses a .json file. After you have set up your profile, you can deploy it by using your management tool of choice. Preferences managed by the enterprise take precedence over the ones set locally on the device. In other words, users in your enterprise aren't able to change preferences that are set through this configuration profile. If exclusions were added through the managed configuration profile, they can only be removed through the managed configuration profile. The command line works for exclusions that were added locally.

This article describes the structure of this profile (including a recommended profile that you can use to get started) and instructions on how to deploy the profile.

Configuration profile structure

The configuration profile is a .json file that consists of entries identified by a key (which denotes the name of the preference), followed by a value, which depends on the nature of the preference. Values can be simple, such as a numerical value, or complex, such as a nested list of preferences.

Typically, you would use a configuration management tool to push a file with the name mdatp_managed.json at the location /etc/opt/microsoft/mdatp/managed/.

The top level of the configuration profile includes product-wide preferences and entries for subareas of the product, which are explained in more detail in the next sections.

Recommended configuration profile

This section includes two configuration profile examples:

• Sample profile to help you get started with recommended settings.
• Full configuration profile example for organizations who want more granular control over security settings.

To get started, we recommend using the first sample profile for your organization. For more granular control, you can use the full configuration profile example instead.

Sample profile

It will help you to take advantage of important protection features that Defender for Endpoint on Linux provides. The following configuration profile:

• Enables real-time protection (RTP)
• Specifies how the following threat types are handled:
  • Potentially unwanted applications (PUA) are blocked
  • Archive bombs (file with a high compression rate) are audited to the product logs
• Enables automatic security intelligence updates
• Enables cloud-delivered protection
• Enables automatic sample submission at safe level

{
   "antivirusEngine":{
      "enforcementLevel":"real_time",
      "threatTypeSettings":[
         {
            "key":"potentially_unwanted_application",
            "value":"block"
         },
         {
            "key":"archive_bomb",
            "value":"audit"
         }
      ]
   },
   "cloudService":{
      "automaticDefinitionUpdateEnabled":true,
      "automaticSampleSubmissionConsent":"safe",
      "enabled":true,
      "proxy": "<EXAMPLE DO NOT USE> http://proxy.server:port/"
   }
}

Full configuration profile example

The following configuration profile contains entries for all settings described in this document and can be used for more advanced scenarios where you want more control over the product.

{
"antivirusEngine":{
      "enforcementLevel":"passive",
      "behaviorMonitoring": "disabled",
      "scanAfterDefinitionUpdate":true,
      "scanArchives":true,
      "scanHistoryMaximumItems": 10000,
      "scanResultsRetentionDays": 90,
      "maximumOnDemandScanThreads":2,
      "exclusionsMergePolicy":"merge",
      "allowedThreats":[
         "<EXAMPLE DO NOT USE>EICAR-Test-File (not a virus)"
      ],
      "disallowedThreatActions":[
         "allow",
         "restore"
      ],
      "nonExecMountPolicy":"unmute",
      "unmonitoredFilesystems": ["nfs,fuse"],
      "enableFileHashComputation": false,
      "threatTypeSettingsMergePolicy":"merge",
      "threatTypeSettings":[
         {
            "key":"potentially_unwanted_application",
            "value":"block"
         },
         {
            "key":"archive_bomb",
            "value":"audit"
         }
      ],
      "scanFileModifyPermissions":false,
      "scanFileModifyOwnership":false,
      "scanNetworkSocketEvent":false,
      "offlineDefinitionUpdateUrl": "http://172.22.199.67:8000/linux/production/<EXAMPLE DO NOT USE>",
      "offlineDefintionUpdateFallbackToCloud":false,
      "offlineDefinitionUpdate":"disabled"
   },
   "cloudService":{
      "enabled":true,
      "diagnosticLevel":"optional",
      "automaticSampleSubmissionConsent":"safe",
      "automaticDefinitionUpdateEnabled":true,
      "proxy": "<EXAMPLE DO NOT USE> http://proxy.server:port/",
      "definitionUpdatesInterval":28800
   },
   "features":{
      "moduleLoad":"disabled",
      "supplementarySensorConfigurations":{
        "enableFilePermissionEvents":"disabled",
        "enableFileOwnershipEvents":"disabled",
        "enableRawSocketEvent":"disabled",
        "enableBootLoaderCalls":"disabled",
        "enableProcessCalls":"disabled",
        "enablePseudofsCalls":"diabled",
        "enableEbpfModuleLoadEvents":"disabled",
        "sendLowfiEvents":"disabled"
      },
      "ebpfSupplementaryEventProvider":"enabled",
      "offlineDefinitionUpdateVerifySig": "disabled"
   },
   "networkProtection":{
      "enforcementLevel":"disabled",
      "disableIcmpInspection":true
   },
   "edr":{
      "groupIds":"GroupIdExample",
      "tags": [
         {
         "key": "GROUP",
         "value": "Tag"
         }
       ]
   },
"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"
}
}

Antivirus, antimalware, and EDR settings in Defender for Endpoint on Linux

Whether you're using a configuration profile (.json file) or the Microsoft Defender portal (Security Settings Management), you can configure your antivirus, antimalware, and EDR settings in Defender for Endpoint on Linux. The following sections describe where and how to configure your settings.

Antivirus engine preferences

The antivirusEngine section of the configuration profile is used to manage the preferences of the antivirus component of the product.

Enforcement level for Microsoft Defender Antivirus

Specifies the enforcement preference of antivirus engine. There are three values for setting enforcement level:

• Real-time (real_time): Real-time protection (scan files as they're modified) is enabled.

• On-demand (on_demand): Files are scanned only on demand. In this:

  • Real-time protection is turned off.
  • Definition updates occur only when a scan starts, even if automaticDefinitionUpdateEnabled is set to true in on-demand mode.

• Passive (passive): Runs the antivirus engine in passive mode. In this case, all of the following apply:

  • Real-time protection is turned off: Threats are not remediated by Microsoft Defender Antivirus.
  • On-demand scanning is turned on: Still use the scan capabilities on the endpoint.
  • Automatic threat remediation is turned off: No files are moved and your security administrator is expected to take required action.
  • Security intelligence updates are turned on: Alerts are available in the security administrator's tenant.
  • Definition updates occur only when a scan starts, even if automaticDefinitionUpdateEnabled is set to true in passive mode.

Enable or disable behavior monitoring (if RTP is enabled)

Determines whether behavior monitoring and blocking capability is enabled on the device or not.

Run a scan after definitions are updated

Specifies whether to start a process scan after new security intelligence updates are downloaded on the device. Enabling this setting triggers an antivirus scan on the running processes of the device.

Scan archives (on-demand antivirus scans only)

Specifies whether to scan archives during on-demand antivirus scans.

Degree of parallelism for on-demand scans

Specifies the degree of parallelism for on-demand scans. This corresponds to the number of threads used to perform the scan and impacts the CPU usage, and the duration of the on-demand scan.

Exclusion merge policy

Specifies the merge policy for exclusions. It can be a combination of administrator-defined and user-defined exclusions (merge) or only administrator-defined exclusions (admin_only). Administrator-defined (admin_only) are exclusions that are configured by Defender for Endpoint policy. This setting can be used to restrict local users from defining their own exclusions.

As it is under antivirusEngine this policy is only applicable for epp exclusions unless mergePolicy under exclusionSettings is configured as (admin_only).

Scan exclusions

Entities that have been excluded from the scan. Exclusions can be specified by full paths, extensions, or file names. (Exclusions are specified as an array of items, administrator can specify as many elements as necessary, in any order.)

Type of exclusion

Specifies the type of content excluded from the scan.

Path to excluded content

Used to exclude content from the scan by full file path.

Path type (file / directory)

Indicates if the path property refers to a file or directory.

File extension excluded from the scan

Used to exclude content from the scan by file extension.

Process excluded from the scan

Specifies a process for which all file activity is excluded from scanning. The process can be specified either by its name (for example, cat) or full path (for example, /bin/cat).

Muting non-exec mounts

Specifies the behavior of RTP on mount point marked as noexec. There are two values for setting are:

• Unmuted (unmute): The default value, all mount points are scanned as part of RTP.
• Muted (mute): Mount points marked as noexec aren't scanned as part of RTP, these mount point can be created for:
  • Database files on Database servers for keeping database files.
  • File server can keep data files mountpoints with noexec option.
  • Backup can keep data files mountpoints with noexec option.

Unmonitor filesystems

Configure filesystems to be unmonitored/excluded from real-time protection (RTP). The filesystems configured are validated against Microsoft Defender's list of permitted filesystems. Filesystems can only be monitored after successful validation. These configured unmonitored filesystems are still scanned by Quick, Full, and custom scans in Microsoft Defender Antivirus.

By default, NFS and Fuse are unmonitored from RTP, Quick, and Full scans. However, they can still be scanned by a custom scan. For example, to remove NFS from the list of unmonitored filesystems list, update the managed config file as shown below. This will automatically add NFS to the list of monitored filesystems for RTP.

{
   "antivirusEngine":{
      "unmonitoredFilesystems": ["Fuse"]
  }
}

To remove both NFS and Fuse from unmonitored list of filesystems, use the following snippet:

{
   "antivirusEngine":{
      "unmonitoredFilesystems": []
  }
}

Configure file hash computation feature

Enables or disables file hash computation feature. When this feature is enabled, Defender for Endpoint computes hashes for files it scans. Note that enabling this feature might impact device performance. For more details, please refer to: Create indicators for files.

Allowed threats

List of threats (identified by their name) that aren't blocked by the product and are instead allowed to run.

Disallowed threat actions

Restricts the actions that the local user of a device can take when threats are detected. The actions included in this list aren't displayed in the user interface.

Threat type settings

The threatTypeSettings preference in the antivirus engine is used to control how certain threat types are handled by the product.

Threat type

Type of threat for which the behavior is configured.

Action to take

Action to take when coming across a threat of the type specified in the preceding section. Can be:

• Audit: The device isn't protected against this type of threat, but an entry about the threat is logged. (Default)
• Block: The device is protected against this type of threat and you're notified in the Microsoft Defender portal.
• Off: The device isn't protected against this type of threat and nothing is logged.

Threat type settings merge policy

Specifies the merge policy for threat type settings. This can be a combination of administrator-defined and user-defined settings (merge) or only administrator-defined settings (admin_only). Administrator-defined (admin_only) are threat type settings that are configured by Defender for Endpoint policy. This setting can be used to restrict local users from defining their own settings for different threat types.

Antivirus scan history retention (in days)

Specify the number of days that results are retained in the scan history on the device. Old scan results are removed from the history. Old quarantined files that are also removed from the disk.

Maximum number of items in the antivirus scan history

Specify the maximum number of entries to keep in the scan history. Entries include all on-demand scans performed in the past and all antivirus detections.

Exclusion setting preferences

Exclusion setting preferences are currently in preview.

The exclusionSettings section of the configuration profile is used to configure various exclusions for Microsoft Defender for Endpoint for Linux.

Merge policy

Specifies the merge policy for exclusions. It specifies if it can be a combination of administrator-defined and user-defined exclusions (merge) or only administrator-defined exclusions (admin_only). This setting can be used to restrict local users from defining their own exclusions. It is applicable for exclusions of all scopes.

Exclusions

Entities that need to be excluded can be specified by full paths, extensions, or file names. Each exclusion entity, i.e., either full path, extension or file name has an optional scope that can be specified. If not specified, the default value of scope in this section is global. (Exclusions are specified as an array of items, administrator can specify as many elements as necessary, in any order.)

Type of exclusion

Specifies the type of content excluded from the scan.

Scope of exclusion (optional)

Specifies the set of exclusion scopes of content excluded. Currently supported scopes are epp and global.

If nothing is specified in for an exclusion under exclusionSettings in managed configuration, then global is considered as scope.

Path to excluded content

Used to exclude content from the scan by full file path.

Path type (file / directory)

Indicates if the path property refers to a file or directory.

File extension excluded from the scan

Used to exclude content from the scan by file extension.

Process excluded from the scan

Specifies a process for which all file activity is excluded from scanning. The process can be specified either by its name (for example, cat) or full path (for example, /bin/cat).

Advanced scan options

The following settings can be configured to enable certain advanced scanning features.

Configure scanning of file modify permissions events

When this feature is enabled, Defender for Endpoint will scan files when their permissions have been changed to set the execute bit(s).

Configure scanning of file modify ownership events

When this feature is enabled, Defender for Endpoint will scan files for which ownership has changed.

Configure scanning of raw socket events

When this feature is enabled, Defender for Endpoint will scan network socket events such as creation of raw sockets / packet sockets, or setting socket option.

Cloud-delivered protection preferences

The cloudService entry in the configuration profile is used to configure the cloud-driven protection feature of the product.

Enable or disable cloud delivered protection

Determines whether cloud-delivered protection is enabled on the device or not. To improve the security of your services, we recommend keeping this feature turned on.

Diagnostic collection level

Diagnostic data is used to keep Defender for Endpoint secure and up to date, detect, diagnose and fix problems, and also make product improvements. This setting determines the level of diagnostics sent by the product to Microsoft. For more details, see Privacy for Microsoft Defender for Endpoint on Linux.

Configure cloud block level

This setting determines how aggressive Defender for Endpoint is in blocking and scanning suspicious files. If this setting is on, Defender for Endpoint is more aggressive when identifying suspicious files to block and scan; otherwise, it is less aggressive and therefore blocks and scans with less frequency.

There are five values for setting cloud block level:

• Normal (normal): The default blocking level.
• Moderate (moderate): Delivers verdict only for high confidence detections.
• High (high): Aggressively blocks unknown files while optimizing for performance (greater chance of blocking non-harmful files).
• High Plus (high_plus): Aggressively blocks unknown files and applies additional protection measures (might impact client device performance).
• Zero Tolerance (zero_tolerance): Blocks all unknown programs.

Enable or disable automatic sample submissions

Determines whether suspicious samples (that are likely to contain threats) are sent to Microsoft. There are three levels for controlling sample submission:

• None: no suspicious samples are submitted to Microsoft.
• Safe: only suspicious samples that don't contain personally identifiable information (PII) are submitted automatically. This is the default value for this setting.
• All: all suspicious samples are submitted to Microsoft.

Enable or disable automatic security intelligence updates

Determines whether security intelligence updates are installed automatically:

Depending on the enforcement level, the automatic security intelligence updates are installed differently. In RTP mode, updates are installed periodically. In Passive/ On-Demand mode updates are installed before every scan.

Advanced optional features

The following settings can be configured to enable certain advanced features.

Module load feature

Determines whether module load events (file open events on shared libraries) are monitored.

Remediate Infected File feature

Determines whether infected processes that open or load any infected file will get remediated or not.

Supplementary sensor configurations

The following settings can be used to configure certain advanced supplementary sensor features.

Configure monitoring of file modify permissions events

Determines whether file modify permissions events (chmod) are monitored.

Configure monitoring of file modify ownership events

Determines whether file modify ownership events (chown) are monitored.

Configure monitoring of raw socket events

Determines whether network socket events involving creation of raw sockets / packet sockets, or setting socket option, are monitored.

Configure monitoring of boot loader events

Determines whether boot loader events are monitored and scanned.

Configure monitoring of ptrace events

Determines whether ptrace events are monitored and scanned.

Configure monitoring of pseudofs events

Determines whether pseudofs events are monitored and scanned.

Configure monitoring of module load events using eBPF

Determines whether module load events are monitored using eBPF and scanned.

Configure monitoring of open events from specific filesystems using eBPF

Determines whether open events from procfs are monitored by eBPF.

Configure source enrichment of events using eBPF

Determines whether events are enriched with metadata at source in eBPF.

Enable Antivirus Engine Cache

Determines whether metadata of events being scanned by the antivirus engine are cached or not.

Report AV Suspicious Events to EDR

Determines whether suspicious events from Antivirus are reported to EDR.

Network protection configurations

The following settings can be used to configure advanced Network Protection inspection features to control what traffic gets inspected by Network Protection.

Enforcement Level

Configure ICMP inspection

Determines whether ICMP events are monitored and scanned.

Add tag or group ID to the configuration profile

When you run the mdatp health command for the first time, the value for the tag and group ID will be blank. To add tag or group ID to the mdatp_managed.json file, follow the below steps:

1. Open the configuration profile from the path /etc/opt/microsoft/mdatp/managed/mdatp_managed.json.

2. Go down to the bottom of the file, where the cloudService block is located.

3. Add the required tag or group ID as following example at the end of the closing curly bracket for the cloudService.

   },
   "cloudService": {
    "enabled": true,
    "diagnosticLevel": "optional",
    "automaticSampleSubmissionConsent": "safe",
    "automaticDefinitionUpdateEnabled": true,
    "proxy": "http://proxy.server:port/"
   },
   "edr": {
   "groupIds":"GroupIdExample",
   "tags": [
            {
            "key": "GROUP",
            "value": "Tag"
            }
          ]
      }
   }
   

   Note

   Add the comma after the closing curly bracket at the end of the cloudService block. Also, make sure that there are two closing curly brackets after adding Tag or Group ID block (please see the above example). At the moment, the only supported key name for tags is GROUP.

Configuration profile validation

The configuration profile must be a valid JSON-formatted file. There are many tools that can be used to verify this. For example, if you have python installed on your device:

python -m json.tool mdatp_managed.json

If the JSON is well-formed, the above command outputs it back to the Terminal and returns an exit code of 0. Otherwise, an error that describes the issue is displayed and the command returns an exit code of 1.

Verifying that the mdatp_managed.json file is working as expected

To verify that your /etc/opt/microsoft/mdatp/managed/mdatp_managed.json is working properly, you should see "[managed]" next to these settings:

• cloud_enabled
• cloud_automatic_sample_submission_consent
• passive_mode_enabled
• real_time_protection_enabled
• automatic_definition_update_enabled

Configuration profile deployment

Once you've built the configuration profile for your enterprise, you can deploy it through the management tool that your enterprise is using. Defender for Endpoint on Linux reads the managed configuration from /etc/opt/microsoft/mdatp/managed/mdatp_managed.json.