Set up Safe Attachments policies in Microsoft Defender for Office 365

In organizations with Microsoft Defender for Office 365, Safe Attachments is an additional layer of protection against malware in messages. After message attachments are scanned by anti-malware protection in Exchange Online Protection (EOP), Safe Attachments opens files in a virtual environment to see what happens (a process known as detonation) before the messages are delivered to recipients. For more information, see Safe Attachments in Microsoft Defender for Office 365.

Although there's no default Safe Attachments policy, the Built-in protection preset security policy provides Safe Attachments protection to all recipients by default. Recipients who are specified in the Standard or Strict preset security policies or in custom Safe Attachments policies aren't affected. For more information, see Preset security policies in EOP and Microsoft Defender for Office 365.

For greater granularity, you can also use the procedures in this article to create Safe Attachments policies that apply to specific users, group, or domains.

You configure Safe Attachments policies in the Microsoft Defender portal or in Exchange Online PowerShell.

What do you need to know before you begin?

• You open the Microsoft Defender portal at https://security.microsoft.com. To go directly to the Safe Attachments page, use https://security.microsoft.com/safeattachmentv2.

• To connect to Exchange Online PowerShell, see Connect to Exchange Online PowerShell.

• You need to be assigned permissions before you can do the procedures in this article. You have the following options:

  • Microsoft Defender XDR Unified role based access control (RBAC) (If Email & collaboration > Defender for Office 365 permissions is Active. Affects the Defender portal only, not PowerShell): Authorization and settings/Security settings/Core Security settings (manage) or Authorization and settings/Security settings/Core Security settings (read).

  • Email & collaboration permissions in the Microsoft Defender portal and Exchange Online permissions:

    • Create, modify, and delete policies: Membership in the Organization Management or Security Administrator role groups in Email & collaboration permissions and membership in the Organization Management role group in Exchange Online permissions.
    • Read-only access to policies: Membership in one of the following role groups:
      • Global Reader or Security Reader in Email & collaboration permissions.
      • View-Only Organization Management in Exchange Online permissions.

  • Microsoft Entra permissions: Membership in the Global Administrator^*, Security Administrator, Global Reader, or Security Reader roles gives users the required permissions and permissions for other features in Microsoft 365.

    Important

    ^* Microsoft recommends that you use roles with the fewest permissions. Using lower permissioned accounts helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role.

• For our recommended settings for Safe Attachments policies, see Safe Attachments settings.

  Tip

  Exceptions to Built-in protection for Safe Attachments or settings in custom Safe Attachments policies are ignored if a recipient is also included in the Standard or Strict preset security policies. For more information, see Order and precedence of email protection.

• Allow up to 30 minutes for a new or updated policy to be applied.

• For more information about licensing requirements, see Licensing terms.

Use the Microsoft Defender portal to create Safe Attachments policies

1. In the Microsoft Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Safe Attachments in the Policies section.Or, to go directly to the Safe Attachments page, use https://security.microsoft.com/safeattachmentv2.

2. On the Safe Attachments page, select Create to start the new Safe Attachments policy wizard.

3. On the Name your policy page, configure these settings:

   • Name: Enter a unique, descriptive name for the policy.
   • Description: Enter an optional description for the policy.

   When you're finished on the Name your policy page, select Next.

4. On the Users and domains page, identify the internal recipients that the policy applies to (recipient conditions):

   • Users: The specified mailboxes, mail users, or mail contacts.
   • Groups:
     • Members of the specified distribution groups or mail-enabled security groups (dynamic distribution groups aren't supported).
     • The specified Microsoft 365 Groups.
   • Domains: All recipients in the organization with a primary email address in the specified accepted domain.

   Click in the appropriate box, start typing a value, and select the value that you want from the results. Repeat this process as many times as necessary. To remove an existing value, select next to the value.

   For users or groups, you can use most identifiers (name, display name, alias, email address, account name, etc.), but the corresponding display name is shown in the results. For users, enter an asterisk (*) by itself to see all available values.

   You can use a condition only once, but the condition can contain multiple values:

   • Multiple values of the same condition use OR logic (for example, <recipient1> or <recipient2>). If the recipient matches any of the specified values, the policy is applied to them.

   • Different types of conditions use AND logic. The recipient must match all of the specified conditions for the policy to apply to them. For example, you configure a condition with the following values:

     • Users: [email protected]
     • Groups: Executives

     The policy is applied to [email protected] only if he's also a member of the Executives group. Otherwise, the policy isn't applied to him.

   • Exclude these users, groups, and domains: To add exceptions for the internal recipients that the policy applies to (recipient exceptions), select this option and configure the exceptions.

     You can use an exception only once, but the exception can contain multiple values:

     • Multiple values of the same exception use OR logic (for example, <recipient1> or <recipient2>). If the recipient matches any of the specified values, the policy isn't applied to them.
     • Different types of exceptions use OR logic (for example, <recipient1> or <member of group1> or <member of domain1>). If the recipient matches any of the specified exception values, the policy isn't applied to them.

   When you're finished on the Users and domains page, select Next.

5. On the Settings page, configure the following settings:

   • Safe Attachments unknown malware response: Select one of the following values:

     • Off
     • Monitor
     • Block: This is the default value, and the recommended value in Standard and Strict preset security policies.
     • Dynamic Delivery (Preview messages)

     These values are explained in Safe Attachments policy settings.

   • Quarantine policy: Select the quarantine policy that applies to messages that are quarantined by Safe Attachments (Block or Dynamic Delivery). Quarantine policies define what users are able to do to quarantined messages, and whether users receive quarantine notifications. For more information, see Anatomy of a quarantine policy.

     By default, the quarantine policy named AdminOnlyAccessPolicy is used for malware detections by Safe Attachments policies. For more information about this quarantine policy, see Anatomy of a quarantine policy.

     Note

     Quarantine notifications are disabled in the policy named AdminOnlyAccessPolicy. To notify recipients that have messages quarantined as malware by Safe Attachments, create or use an existing quarantine policy where quarantine notifications are turned on. For instructions, see Create quarantine policies in the Microsoft Defender portal.

     Users can't release their own messages that were quarantined as malware by Safe Attachments policies, regardless of how the quarantine policy is configured. If the policy allows users to release their own quarantined messages, users are instead allowed to request the release of their quarantined malware messages.

   • Redirect messages with detected attachments: If you select Enable redirect, you can specify an email address in the Send messages that contain monitored attachments to the specified email address box to send messages that contain malware attachments for analysis and investigation.

     Note

     Redirection is available only for the Monitor action. For more information, see MC424899.

   When you're finished on the Settings page, select Next.

6. On the Review page, review your settings. You can select Edit in each section to modify the settings within the section. Or you can select Back or the specific page in the wizard.

   When you're finished on the Review page, select Submit.

7. On the New Safe Attachments policy created page, you can select the links to view the policy, view Safe Attachments policies, and learn more about Safe Attachments policies.

   When you're finished on the New Safe Attachments policy created page, select Done.

   Back on the Safe Attachments page, the new policy is listed.

Use the Microsoft Defender portal to view Safe Attachments policy details

In the Microsoft Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Safe Attachments in the Policies section. To go directly to the Safe Attachments page, use https://security.microsoft.com/safeattachmentv2.

On the Safe Attachments page, the following properties are displayed in the list of policies:

• Name
• Status: Values are On or Off.
• Priority: For more information, see the Set the priority of Safe Attachments policies section.

To change the list of policies from normal to compact spacing, select Change list spacing to compact or normal, and then select Compact list.

Use the Search box and a corresponding value to find specific Safe Attachment policies.

Use Export to export the list of policies to a CSV file.

Use View reports to open the Threat protection status report.

Select a policy by clicking anywhere in the row other than the check box next to the name to open the details flyout for the policy.

Use the Microsoft Defender portal to take action on Safe Attachments policies

In the Microsoft Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Safe Attachments in the Policies section. To go directly to the Safe Attachments page, use https://security.microsoft.com/safeattachmentv2.

2. On the Safe Attachments page, select the Safe Attachments policy by using either of the following methods:

   • Select the policy from the list by selecting the check box next to the name. The following actions are available in the More actions dropdown list that appears:

     • Enable selected policies.
     • Disable selected policies.
     • Delete selected policies.

     

   • Select the policy from the list by clicking anywhere in the row other than the check box next to the name. Some or all following actions are available in the details flyout that opens:

     • Modify policy settings by clicking Edit in each section (custom policies or the default policy)
     • Turn on or Turn off (custom policies only)
     • Increase priority or Decrease priority (custom policies only)
     • Delete policy (custom policies only)

     

The actions are described in the following subsections.

Use the Microsoft Defender portal to modify custom Safe Attachments policies

After you select a custom Safe Attachments policy by clicking anywhere in the row other than the check box next to the name, the policy settings are shown in the details flyout that opens. Select Edit in each section to modify the settings within the section. For more information about the settings, see the Create Safe Attachments policies section earlier in this article.

You can't modify the Safe Attachments policies named Standard Preset Security Policy, Strict Preset Security Policy, or Built-in protection (Microsoft) that are associated with preset security policies in the policy details flyout. Instead, you select View preset security policies in the details flyout to go to the Preset security policies page at https://security.microsoft.com/presetSecurityPolicies to modify the preset security policies.

Use the Microsoft Defender portal to enable or disable custom Safe Attachments policies

You can't enable or disable the Safe Attachments policies named Standard Preset Security Policy, Strict Preset Security Policy, or Built-in protection (Microsoft) that are associated with preset security policies here. You enable or disable preset security policies on the Preset security policies page at https://security.microsoft.com/presetSecurityPolicies.

After you select an enabled custom Safe Attachments policy (the Status value is On), use either of the following methods to disable it:

• On the Safe Attachments page: Select More actions > Disable selected policies.
• In the details flyout of the policy: Select Turn off at the top of the flyout.

After you select a disabled custom Safe Attachments policy (the Status value is Off), use either of the following methods to enable it:

• On the Safe Attachments page: Select More actions > Enable selected policies.
• In the details flyout of the policy: Select Turn on at the top of the flyout.

On the Safe Attachments page, the Status value of the policy is now On or Off.

Use the Microsoft Defender portal to set the priority of custom Safe Attachments policies

Safe Attachments policies are processed in the order that they're displayed on the Safe Attachments page:

• The Safe Attachments policy named Strict Preset Security Policy that's associated with the Strict preset security policy is always applied first (if the Strict preset security policy is enabled).
• The Safe Attachments policy named Standard Preset Security Policy that's associated with the Standard preset security policy is always applied next (if the Standard preset security policy is enabled).
• Custom Safe Attachments policies are applied next in priority order (if they're enabled):
  • A lower priority value indicates a higher priority (0 is the highest).
  • By default, a new policy is created with a priority that's lower than the lowest existing custom policy (the first is 0, the next is 1, etc.).
  • No two policies can have the same priority value.
• The Safe Attachments policy named Built-in protection (Microsoft) that's associated with Built-in protection always has the priority value Lowest, and you can't change it.

Safe Attachments protection stops for a recipient after the first policy is applied (the highest priority policy for that recipient). For more information, see Order and precedence of email protection.

After you select the custom Safe Attachments policy by clicking anywhere in the row other than the check box next to the name, you can increase or decrease the priority of the policy in the details flyout that opens:

• The custom policy with the Priority value 0 on the Safe Attachments page has the Decrease priority action at the top of the details flyout.
• The custom policy with the lowest priority (highest Priority value; for example, 3) has the Increase priority action at the top of the details flyout.
• If you have three or more policies, the policies between Priority 0 and the lowest priority have both the Increase priority and the Decrease priority actions at the top of the details flyout.

When you're finished in the policy details flyout, select Close.

Back on the Safe Attachments page, the order of the policy in the list matches the updated Priority value.

Use the Microsoft Defender portal to remove custom Safe Attachments policies

You can't remove the Safe Attachments policies named Standard Preset Security Policy, Strict Preset Security Policy, or Built-in protection (Microsoft) that are associated with preset security policies.

After you select the custom Safe Attachments policy, use either of the following methods to remove it:

• On the Safe Attachments page: Select More actions > Delete selected policies.
• In the details flyout of the policy: Select Delete policy at the top of the flyout.

Select Yes in the warning dialog that opens.

Back on the Safe Attachments page, the removed policy is no longer listed.

Use Exchange Online PowerShell to configure Safe Attachments policies

In PowerShell, the basic elements of a Safe Attachments policy are:

• The safe attachment policy: Specifies the actions for unknown malware detections, whether to send messages with malware attachments to a specified email address, and whether to deliver messages if Safe Attachments scanning can't complete.
• The safe attachment rule: Specifies the priority and recipient filters (who the policy applies to).

The difference between these two elements isn't obvious when you manage Safe Attachments policies in the Microsoft Defender portal:

• When you create a Safe Attachments policy in the Defender portal, you're actually creating a safe attachment rule and the associated safe attachment policy at the same time using the same name for both.
• When you modify a Safe Attachments policy in the Defender portal, settings related to the name, priority, enabled or disabled, and recipient filters modify the safe attachment rule. All other settings modify the associated safe attachment policy.
• When you remove a Safe Attachments policy from the Defender portal, the safe attachment rule and the associated safe attachment policy are removed.

In PowerShell, the difference between safe attachment policies and safe attachment rules is apparent. You manage safe attachment policies by using the *-SafeAttachmentPolicy cmdlets, and you manage safe attachment rules by using the *-SafeAttachmentRule cmdlets.

• In PowerShell, you create the safe attachment policy first, then you create the safe attachment rule, which identifies the associated policy that the rule applies to.
• In PowerShell, you modify the settings in the safe attachment policy and the safe attachment rule separately.
• When you remove a safe attachment policy from PowerShell, the corresponding safe attachment rule isn't automatically removed, and vice versa.

Use PowerShell to create Safe Attachments policies

Creating a Safe Attachments policy in PowerShell is a two-step process:

1. Create the safe attachment policy.
2. Create the safe attachment rule that specifies the safe attachment policy that the rule applies to.

Notes:

• You can create a new safe attachment rule and assign an existing, unassociated safe attachment policy to it. A safe attachment rule can't be associated with more than one safe attachment policy.

• You can configure the following settings on new safe attachment policies in PowerShell that aren't available in the Microsoft Defender portal until after you create the policy:

  • Create the new policy as disabled (Enabled $false on the New-SafeAttachmentRule cmdlet).
  • Set the priority of the policy during creation (Priority <Number>) on the New-SafeAttachmentRule cmdlet).

• A new safe attachment policy that you create in PowerShell isn't visible in the Microsoft Defender portal until you assign the policy to a safe attachment rule.

Step 1: Use PowerShell to create a safe attachment policy

To create a safe attachment policy, use this syntax:

New-SafeAttachmentPolicy -Name "<PolicyName>" -Enable $true [-AdminDisplayName "<Comments>"] [-Action <Allow | Block | DynamicDelivery>] [-Redirect <$true | $false>] [-RedirectAddress <SMTPEmailAddress>] [-QuarantineTag <QuarantinePolicyName>]

This example creates a safe attachment policy named Contoso All with the following values:

• Block messages that are found to contain malware by Safe Documents scanning (we aren't using the Action parameter, and the default value is Block).
• The default quarantine policy is used (AdminOnlyAccessPolicy), because we aren't using the QuarantineTag parameter.

New-SafeAttachmentPolicy -Name "Contoso All" -Enable $true

For detailed syntax and parameter information, see New-SafeAttachmentPolicy.

Step 2: Use PowerShell to create a safe attachment rule

To create a safe attachment rule, use this syntax:

New-SafeAttachmentRule -Name "<RuleName>" -SafeAttachmentPolicy "<PolicyName>" <Recipient filters> [<Recipient filter exceptions>] [-Comments "<OptionalComments>"] [-Enabled <$true | $false>]

This example creates a safe attachment rule named Contoso All with the following conditions:

• The rule is associated with the safe attachment policy named Contoso All.
• The rule applies to all recipients in the contoso.com domain.
• Because we aren't using the Priority parameter, the default priority is used.
• The rule is enabled (we aren't using the Enabled parameter, and the default value is $true).

New-SafeAttachmentRule -Name "Contoso All" -SafeAttachmentPolicy "Contoso All" -RecipientDomainIs contoso.com

For detailed syntax and parameter information, see New-SafeAttachmentRule.

Use PowerShell to view safe attachment policies

To view existing safe attachment policies, use the following syntax:

Get-SafeAttachmentPolicy [-Identity "<PolicyIdentity>"] [| <Format-Table | Format-List> <Property1,Property2,...>]

This example returns a summary list of all safe attachment policies.

Get-SafeAttachmentPolicy

This example returns detailed information for the safe attachment policy named Contoso Executives.

Get-SafeAttachmentPolicy -Identity "Contoso Executives" | Format-List

For detailed syntax and parameter information, see Get-SafeAttachmentPolicy.

Use PowerShell to view safe attachment rules

To view existing safe attachment rules, use the following syntax:

Get-SafeAttachmentRule [-Identity "<RuleIdentity>"] [-State <Enabled | Disabled>] [| <Format-Table | Format-List> <Property1,Property2,...>]

This example returns a summary list of all safe attachment rules.

Get-SafeAttachmentRule

To filter the list by enabled or disabled rules, run the following commands:

Get-SafeAttachmentRule -State Disabled

Get-SafeAttachmentRule -State Enabled

This example returns detailed information for the safe attachment rule named Contoso Executives.

Get-SafeAttachmentRule -Identity "Contoso Executives" | Format-List

For detailed syntax and parameter information, see Get-SafeAttachmentRule.

Use PowerShell to modify safe attachment policies

You can't rename a safe attachment policy in PowerShell (the Set-SafeAttachmentPolicy cmdlet has no Name parameter). When you rename a Safe Attachments policy in the Microsoft Defender portal, you're only renaming the safe attachment rule.

Otherwise, the same settings are available when you create a safe attachment policy as described in the Step 1: Use PowerShell to create a safe attachment policy section earlier in this article.

To modify a safe attachment policy, use this syntax:

Set-SafeAttachmentPolicy -Identity "<PolicyName>" <Settings>

For detailed syntax and parameter information, see Set-SafeAttachmentPolicy.

Use PowerShell to modify safe attachment rules

The only setting that's not available when you modify a safe attachment rule in PowerShell is the Enabled parameter that allows you to create a disabled rule. To enable or disable existing safe attachment rules, see the next section.

Otherwise, the same settings are available when you create a rule as described in the Step 2: Use PowerShell to create a safe attachment rule section earlier in this article.

To modify a safe attachment rule, use this syntax:

Set-SafeAttachmentRule -Identity "<RuleName>" <Settings>

For detailed syntax and parameter information, see Set-SafeAttachmentRule.

Use PowerShell to enable or disable safe attachment rules

Enabling or disabling a safe attachment rule in PowerShell enables or disables the whole Safe Attachments policy (the safe attachment rule and the assigned safe attachment policy).

To enable or disable a safe attachment rule in PowerShell, use this syntax:

<Enable-SafeAttachmentRule | Disable-SafeAttachmentRule> -Identity "<RuleName>"

This example disables the safe attachment rule named Marketing Department.

Disable-SafeAttachmentRule -Identity "Marketing Department"

This example enables same rule.

Enable-SafeAttachmentRule -Identity "Marketing Department"

For detailed syntax and parameter information, see Enable-SafeAttachmentRule and Disable-SafeAttachmentRule.

Use PowerShell to set the priority of safe attachment rules

The highest priority value you can set on a rule is 0. The lowest value you can set depends on the number of rules. For example, if you have five rules, you can use the priority values 0 through 4. Changing the priority of an existing rule can have a cascading effect on other rules. For example, if you have five custom rules (priorities 0 through 4), and you change the priority of a rule to 2, the existing rule with priority 2 is changed to priority 3, and the rule with priority 3 is changed to priority 4.

To set the priority of a safe attachment rule in PowerShell, use the following syntax:

Set-SafeAttachmentRule -Identity "<RuleName>" -Priority <Number>

This example sets the priority of the rule named Marketing Department to 2. All existing rules that have a priority less than or equal to 2 are decreased by 1 (their priority numbers are increased by 1).

Set-SafeAttachmentRule -Identity "Marketing Department" -Priority 2

Note: To set the priority of a new rule when you create it, use the Priority parameter on the New-SafeAttachmentRule cmdlet instead.

For detailed syntax and parameter information, see Set-SafeAttachmentRule.

Use PowerShell to remove safe attachment policies

When you use PowerShell to remove a safe attachment policy, the corresponding safe attachment rule isn't removed.

To remove a safe attachment policy in PowerShell, use this syntax:

Remove-SafeAttachmentPolicy -Identity "<PolicyName>"

This example removes the safe attachment policy named Marketing Department.

Remove-SafeAttachmentPolicy -Identity "Marketing Department"

For detailed syntax and parameter information, see Remove-SafeAttachmentPolicy.

Use PowerShell to remove safe attachment rules

When you use PowerShell to remove a safe attachment rule, the corresponding safe attachment policy isn't removed.

To remove a safe attachment rule in PowerShell, use this syntax:

Remove-SafeAttachmentRule -Identity "<PolicyName>"

This example removes the safe attachment rule named Marketing Department.

Remove-SafeAttachmentRule -Identity "Marketing Department"

For detailed syntax and parameter information, see Remove-SafeAttachmentRule.

How do you know these procedures worked?

To verify that you've successfully created, modified, or removed Safe Attachments policies, do any of the following steps:

• On the Safe Attachments page in the Microsoft Defender portal at https://security.microsoft.com/safeattachmentv2, verify the list of policies, their Status values, and their Priority values. To view more details, select the policy from the list by clicking on the name, and view the details in the fly out.

• In Exchange Online PowerShell, replace <Name> with the name of the policy or rule, run the following command, and verify the settings:

  Get-SafeAttachmentPolicy -Identity "<Name>" | Format-List
  

  Get-SafeAttachmentRule -Identity "<Name>" | Format-List
  

• To verify that Safe Attachments is scanning messages, check the available Defender for Office 365 reports. For more information, see View reports for Defender for Office 365 and Use Explorer in the Microsoft Defender portal.