Configure security settings in Microsoft Defender for Endpoint on Linux

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 other 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

You can use the command line to configure specific settings, gather diagnostics, run scans, and more. For more information, 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 at (https://security.microsoft.com) using 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 set up your profile, you can deploy it by using your management tool of choice. Preferences managed by the enterprise take precedence over preferences 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 added locally.

This article describes the structure of this profile (including a recommended profile 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 (for example, a numerical value) or complex (for example, a nested list of preferences).

Typically, you use a configuration management tool to push a file named mdatp_managed.json to 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

The following configuration profile helps you take advantage of important protection features in Defender for Endpoint on Linux. The profile includes the following configuration:

• Enable real-time protection (RTP).
• Specify 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.
• Enable automatic security intelligence updates.
• Enable cloud-delivered protection.
• Enable 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 article and can be used for more advanced scenarios where you want more control.

{
"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>",
      "offlineDefinitionUpdateFallbackToCloud":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 use 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 manages the preferences of the antivirus component of the product.

See the following subsections for a description of the dictionary contents and policy properties.

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:

  • Real-time protection is 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:

  • Real-time protection is off. Microsoft Defender Antivirus doesn't remediate threats.
  • On-demand scanning is on. Scan capabilities are still available on the device.
  • Automatic threat remediation is off. No files are moved and your security administrator is expected to take required action.
  • Security intelligence updates are on. Alerts are available in the security administrator's organization.
  • Definition updates occur only when a scan starts, even if automaticDefinitionUpdateEnabled is set to true.
  • Endpoint detection and response (EDR) is on. The output of the mdatp health command on the device shows engine not loaded for the engine_load_version property. The engine is related to antivirus, not EDR.

Enable or disable behavior monitoring (if RTP is enabled)

Specifies whether behavior monitoring and blocking capability is enabled or disabled on the device.

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 setting corresponds to the number of processor threads used by the scan. This setting affects CPU usage and the duration of on-demand scans.

Exclusion merge policy

Specifies whether to use user-defined exclusions on the device. Valid values are:

• admin_only: Use only admin-defined exclusions configured by Defender for Endpoint policy. Use this value to prevent users from defining their own exclusions.
• merge: Use a combination of admin-defined and user-defined exclusions.

Scan exclusions

Entities excluded from scans. You specify exclusions as an array of items. Admins can specify as many elements as necessary, in any order. You specify exclusions using full paths, extensions, or file names.

See the following subsections for a description of the dictionary contents.

Type of exclusion

Specifies the type of content excluded from scans.

Path to excluded content

Exclude content from the scan by full file path.

Path type (file / directory)

Specifies whether the path property refers to a file or a directory.

File extension excluded from the scan

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. You can specify the process by name (for example, cat) or full path (for example, /bin/cat).

Muting nonexec mounts

Specifies the behavior of RTP on mount points marked as noexec. Valid values are:

• Unmuted (unmute): All mount points are scanned as part of RTP. This value is the default.
• Muted (mute): Mount points marked as noexec aren't scanned as part of RTP.
  • Database servers can keep database file.
  • File servers can keep data file mount points.
  • Backup can keep data file mount points.

Unmonitor filesystems

Specifies the filesystems that aren't monitored by (are excluded from) RTP. The specified filesystems are still scanned by Quick, Full, and custom scans in Microsoft Defender Antivirus.

When you add or remove a filesystem from the unmonitored list, Microsoft validates the eligibility of the filesystem for monitoring by RTP (removed from the list) or no monitoring by RTP (added to the list).

• By default, the following filesystems are monitored by RTP:

  • btrfs
  • ecryptfs
  • ext2
  • ext3
  • ext4
  • fuseblk
  • jfs
  • overlay
  • ramfs
  • reiserfs
  • tmpfs
  • vfat
  • xfs

• By default, the following filesystems are unmonitored by RTP:

  • cifs^*
  • fuse
  • nfs
  • nfs4^*
  • smb^*

  These filesystems are also unmonitored by Quick and Full scans, but are scannable by custom scans.

  ^* Currently, RTP monitoring of this filesystem is in Preview.

For example, to remove nfs and nfs4 from the list of unmonitored filesystems (which means nfs and nfs4 are monitored by RTP after validation), update the managed config file with the following entry:

{
   "antivirusEngine":{
      "unmonitoredFilesystems": ["cifs","fuse","smb"]
  }
}

To remove all entries from the list of unmonitored filesystems, use the following entry:

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

Configure file hash computation feature

Enables or disables file hash computation for files scanned by Defender for Endpoint. Enabling this feature might affect device performance. For more information, see Create indicators for files.

Allowed threats

Specifies the names of threats that aren't blocked by Defender for Endpoint. Instead, these threats are allowed to run.

Disallowed threat actions

Restricts the allowed actions by the device user when threats are detected. The actions included in this list aren't displayed in the user interface.

Threat type settings

Control how certain threat types are handled.

See the following subsections for a description of the dictionary contents.

Threat type

Specifies the type of threat.

Action to take

Specifies the action when the previously specified threats types are detected. Valid values are:

• Audit: The device isn't protected against this type of threat, but an entry about the threat is logged. This value is the 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 whether to use user-defined threat type settings on the device. Valid values are:

• admin_only: Use only admin-defined threat type settings. Use this value to prevent users from defining their own threat type settings.
• merge: Use a combination of admin-defined and user-defined threat type settings.

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 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 and all antivirus detections.

Exclusion setting preferences

The exclusionSettings section of the configuration profile configures various exclusions for Microsoft Defender for Endpoint for Linux.

See the following sections for a description of the dictionary contents.|

Merge policy

Exclusion merge policy

Specifies whether to use user-defined exclusions on the device. Valid values are:

• admin_only: Use only admin-defined exclusions configured by Defender for Endpoint policy. Use this value to prevent users from defining their own exclusions.
• merge: Use a combination of admin-defined and user-defined exclusions.

This setting applies to exclusions of all scopes.

Exclusions

Entities excluded from scans. You specify exclusions as an array of items. Admins can specify as many elements as necessary, in any order. You specify exclusions using full paths, extensions, or file names. For each exclusion, you can specify a scope. The default scope is global.

See the following subsections for a description of the dictionary contents.

Type of exclusion

Specifies the type of content excluded from scans.

Scope of exclusion (optional)

Specifies the exclusion scope of excluded content. Valid values are:

• epp
• global

If you don't specify an exclusion scope in managed configuration, the value global is used.

Path to excluded content

Exclude content from scans by full file path.

Path type (file / directory)

Specifies whether the path property refers to a file or a directory.

File extension excluded from the scan

Exclude content from scans by file extension.

Process excluded from the scan

Exclude all file activity by a process from scans. Valid values are:

• Process name. For example, cat.
• Full path. For example, /bin/cat.

Advanced scan options

You can configure the following settings to enable certain advanced scanning features.

Configure scanning of file modify permissions events

Specifies whether Defender for Endpoint scans files when their permissions changed to set the executed bits.

Configure scanning of file modify ownership events

Specifies whether Defender for Endpoint scans files with changed ownership.

Configure scanning of raw socket events

Specifies whether Defender for Endpoint scans network socket events. For example:

• Creating raw sockets / packet sockets.
• Setting socket options.

Cloud-delivered protection preferences

The cloudService entry in the configuration profile configures the cloud-driven protection feature.

See the following subsections for a description of the dictionary contents and policy settings.

Enable or disable cloud delivered protection

Specify whether cloud-delivered protection is enabled on the device. To improve the security, we recommend keeping this feature turned on.

Diagnostic collection level

Specify the level of diagnostic information sent to Microsoft. For more information, see Privacy for Microsoft Defender for Endpoint on Linux.

Diagnostic data is used to keep Defender for Endpoint secure and up to date, detect, diagnose and fix problems, and also make product improvements.

Configure cloud block level

Specify the aggressiveness of Defender for Endpoint in blocking and scanning suspicious files. Valid values are:

• Normal (normal): The value is the default.
• Moderate (moderate): Deliver verdicts only for high confidence detections.
• High (high): Aggressively block unknown files while optimizing for performance. This value has greater chance of blocking unharmful files.
• High Plus (high_plus): Aggressively block unknown files and apply extra protection measures. This value might affect client device performance.
• Zero Tolerance (zero_tolerance): Block all unknown programs.

If this setting is on, Defender for Endpoint is more aggressive when identifying suspicious files to block and scan. Otherwise, it's less aggressive and therefore blocks and scans with less frequency.

Enable or disable automatic sample submissions

Specifies whether suspicious samples (likely to contain threats) are sent to Microsoft. Valid values are:

• None: No suspicious samples are submitted to Microsoft.
• Safe: Only suspicious samples that don't contain personal information are automatically submitted. This value is the default.
• All: All suspicious samples are submitted to Microsoft.

Enable or disable automatic security intelligence updates

Specifies 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 or On-Demand mode, updates are installed before every scan.

Advanced optional features

Use the following settings to enable certain advanced optional features.

See the following subsections for a description of the dictionary contents.

Module load feature

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

Remediate Infected File feature

Specifies whether infected processes that open or load infected files get remediated in RTP mode.

Supplementary sensor configurations

Use the following settings to configure certain advanced supplementary sensor features.

See the following sections for a description of the dictionary contents.

Configure monitoring of file modify permissions events

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

Configure monitoring of file modify ownership events

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

Configure monitoring of raw socket events

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

Configure monitoring of boot loader events

Specifies whether boot loader events are monitored and scanned.

Configure monitoring of ptrace events

Specifies whether ptrace events are monitored and scanned.

Configure monitoring of pseudofs events

Specifies whether pseudofs events are monitored and scanned.

Configure monitoring of module load events using eBPF

Specifies whether module load events are monitored by eBPF and scanned.

Configure monitoring of open events from specific filesystems using eBPF

Specifies whether open events from procfs are monitored by eBPF.

Configure source enrichment of events using eBPF

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

Enable Antivirus Engine Cache

Specifies whether metadata of events scanned by the antivirus engine are cached.

Report suspicious antivirus events to EDR

Specifies whether suspicious events from Antivirus are reported to EDR.

Network protection configurations

Use the following settings to configure advanced Network Protection inspection features that control traffic inspected by Network Protection.

See the following subsections for a description of the dictionary contents.

Enforcement Level

Configure ICMP inspection

Specifies whether ICMP events are monitored and scanned.

Add tag or group ID to the configuration profile

When you first run the mdatp health command, the tag and group ID values are blank. To add a tag or group ID to the mdatp_managed.json file, follow these steps:

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

2. In the cloudService block at the bottom of the file, add the required tag or group ID at the end of the closing curly bracket for the cloudService block as shown in the following example.

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

   Note

   • Add a comma after the closing curly bracket at the end of the cloudService block.
   • Verify there are two closing curly brackets after you add tags or groupIds blocks as shown in the example.
   • Currently, the only supported key name for tags is GROUP.

Configuration profile validation

The configuration profile must be a valid JSON-formatted file. Many tools are available for you to verify the configuration profile. For example, run the following command if you have python installed on your device:

python -m json.tool mdatp_managed.json

If the file is formatted correctly, the command returns the exit code 0. Otherwise, errors are displayed and the command returns the exit code 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

After you create the configuration profile for your organization, you can deploy it using your current management tools. Defender for Endpoint on Linux reads the managed configuration from /etc/opt/microsoft/mdatp/managed/mdatp_managed.json.