Create Safe Attachments policies using PowerShell
Organizations can use Exchange Online PowerShell or standalone EOP PowerShell to separately manage Safe Attachments policies and rules. A Safe Attachments policy consists of a Safe Attachments policy and a Safe Attachments rule.
When you use PowerShell cmdlets:
- A rule defines the conditions.
- A policy defines the actions to take after the organization meets the conditions within the rule.
The conditions and exceptions make up a rule that becomes part of a policy. The policy dictates the action the organization must take. It also dictates the redirect settings. Organizations can change rules independently of the policies to which they belong.
Important
When using PowerShell to create a policy, you must create the policy before the rule. You must create the policy first so that you can later assign it to the rule. If you create the rule first, you won't have a policy to assign to it.
In PowerShell, the difference between Safe Attachments policies and Safe Attachments rules is clear. You manage Safe Attachments policies by using the *-SafeAttachmentPolicy cmdlets, and you manage Safe Attachments rules by using the *-SafeAttachmentRule cmdlets.
- In PowerShell, you create the Safe Attachments policy first, then you create the Safe Attachments rule that identifies the policy that the rule applies to.
- In PowerShell, you modify the settings in the Safe Attachments policy and the Safe Attachments rule separately.
- When you remove a Safe Attachments policy from PowerShell, the system doesn't automatically remove the corresponding Safe Attachments rule, and vice versa.
The following table identifies EOP cmdlets you can use to create and manage Safe Attachments rules and policies. For more details about any of the Safe Attachments cmdlets, select the hyperlink associated with a cmdlet in the table.
| If you want to do this task: | Use this cmdlet: |
|---|---|
| View your Safe Attachments policy settings. | Get-SafeAttachmentPolicy |
| Edit an existing Safe Attachments policy. | Set-SafeAttachmentPolicy |
| Create a new custom Safe Attachments policy. | New-SafeAttachmentPolicy |
| Delete a custom Safe Attachments policy. | Remove-SafeAttachmentPolicy |
| View your Safe Attachments rule settings. | Get-SafeAttachmentRule |
| Edit an existing attachments link rule. | Set-SafeAttachmentRule |
| Create a new custom Safe Attachments rule. | New-SafeAttachmentRule |
| Delete a custom Safe Attachments rule. | Remove-SafeAttachmentRule |
Creating a Safe Attachments policy in PowerShell is a two-step process:
- Create the Safe Attachments policy.
- Create the Safe Attachments rule that specifies the Safe Attachments policy the rule applies to.
You can create a new Safe Attachments rule and assign an existing, unassociated Safe Attachments policy to it. You can't associate a Safe Attachments rule with more than one Safe Attachments policy.
You can configure the following settings on new Safe Attachments policies in PowerShell that aren't available in Microsoft Defender XDR 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).
Caution
A new Safe Attachments policy that you create in PowerShell isn't visible in Microsoft Defender XDR until you assign the policy to a Safe Attachments rule.
Step 1 - Create a Safe Attachments policy using PowerShell
You should use the following PowerShell syntax to create a Safe Attachments policy:
New-SafeAttachmentPolicy -Name "<PolicyName>" [-AdminDisplayName "<Comments>"] [-Action <Allow | Block | Replace | DynamicDelivery>] [-Redirect <$true | $false>] [-RedirectAddress <SMTPEmailAddress>] [-ActionOnError <$true | $false>]
The following example creates a Safe Attachments policy named Contoso All with the following values:
- Block messages that contain malware. Safe Documents scanning searches for malware in messages. This example doesn't use the Action parameter. Since the default value for this parameter is Block, the Safe Attachments service automatically blocks infected messages.
- Enable redirection. The system sends messages containing malware to sec-ops@contoso.com for analysis and investigation.
- Don't deliver the message if Safe Attachments scanning isn't available or an error occurs during scanning. This example doesn't use the ActionOnError parameter. Since the default value for this parameter is $true, the system doesn't deliver the message if the organization disabled Safe Attachments scanning, or an error occurs.
New-SafeAttachmentPolicy -Name "Contoso All" -Redirect $true -RedirectAddress sec-ops@contoso.com
Step 2 - Create a Safe Attachments rule using PowerShell
You should use the following PowerShell syntax to create a Safe Attachments rule:
New-SafeAttachmentRule -Name "<RuleName>" -SafeAttachmentPolicy "<PolicyName>" <Recipient filters> [<Recipient filter exceptions>] [-Comments "<OptionalComments>"] [-Enabled <$true | $false>]
The following example creates a Safe Attachments rule named Contoso All with the following conditions:
- Associate the rule with the Safe Attachments policy named Contoso All.
- Apply the rule to all recipients in the contoso.com domain.
- Apply the default priority. This example doesn't use the Priority parameter, so Safe Attachments uses the default priority instead.
- Enable the rule. This example doesn't use the Enabled parameter. Since the default value of this parameter is $true, the Safe Attachments service automatically enables the rule.
New-SafeAttachmentRule -Name "Contoso All" -SafeAttachmentPolicy "Contoso All" -RecipientDomainIs contoso.com
Use PowerShell to set the priority of Safe Attachments rules
Given the circumstance, the system might automatically increase or decrease the priority of a Safe Attachments rule. The system updates priorities in increments of 1.
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, assume you have five custom rules (priorities 0 through 4), and you change the priority of a rule to 2. What happens? The system automatically changes:
- the rule with priority 2 to priority 3.
- the rule with priority 3 to priority 4.
To set the priority of a Safe Attachments rule in PowerShell, use the following syntax:
Set-SafeAttachmentRule -Identity "<RuleName>" -Priority <Number>
The following example sets the priority of the rule named Marketing Department to 2. The system automatically decreases by 1 the priority of all existing rules that have a priority less than or equal to 2.
Set-SafeAttachmentRule -Identity "Marketing Department" -Priority 2
Tip
To set the priority of a new rule when you create it, use the Priority parameter on the New-SafeAttachmentRule cmdlet instead.