Allow or block files using the Tenant Allow/Block List
Tip
Did you know you can try the features in Microsoft Defender XDR for Office 365 Plan 2 for free? Use the 90-day Defender for Office 365 trial at the Microsoft Defender portal trials hub. Learn about who can sign up and trial terms on Try Microsoft Defender for Office 365.
In Microsoft 365 organizations with mailboxes in Exchange Online or standalone Exchange Online Protection (EOP) organizations without Exchange Online mailboxes, admins can create and manage entries for files in the Tenant Allow/Block List. For more information about the Tenant Allow/Block List, see Manage allows and blocks in the Tenant Allow/Block List.
This article describes how admins can manage entries for files in the Microsoft Defender portal and 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 Tenant Allow/Block Lists page, use https://security.microsoft.com/tenantAllowBlockList. To go directly to the Submissions page, use https://security.microsoft.com/reportsubmission.
To connect to Exchange Online PowerShell, see Connect to Exchange Online PowerShell. To connect to standalone EOP PowerShell, see Connect to Exchange Online Protection PowerShell.
You specify files by using the SHA256 hash value of the file. To find the SHA256 hash value of a file in Windows, run the following command in a Command Prompt:
certutil.exe -hashfile "<Path>\<Filename>" SHA256
An example value is
768a813668695ef2483b2bde7cf5d1b2db0423a0d3e63e498f3ab6f2eb13ea3a
. Perceptual hash (pHash) values aren't supported.Entry limits for files:
- Exchange Online Protection: The maximum number of allow entries is 500, and the maximum number of block entries is 500 (1000 file entries in total).
- Defender for Office 365 Plan 1: The maximum number of allow entries is 1000, and the maximum number of block entries is 1000 (2000 file entries in total).
- Defender for Office 365 Plan 2: The maximum number of allow entries is 5000, and the maximum number of block entries is 10000 (15000 file entries in total).
You can enter a maximum of 64 characters in a file entry.
An entry should be active within 5 minutes.
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 > Exchange Online permissions permissions is
Active. Affects the Defender portal only, not PowerShell): Authorization and settings/Security settings/Detection tuning (manage) or Authorization and settings/Security settings/Core security settings (read).
-
- Add and remove entries from the Tenant Allow/Block List: Membership in one of the following role groups:
- Organization Management or Security Administrator (Security admin role).
- Security Operator (Tenant AllowBlockList Manager).
- Read-only access to the Tenant Allow/Block List: Membership in one of the following role groups:
- Global Reader
- Security Reader
- View-Only Configuration
- View-Only Organization Management
- Add and remove entries from the Tenant Allow/Block List: Membership in one of the following role groups:
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.
A Files tab is available on the Submissions page only in organizations with Microsoft Defender XDR or Microsoft Defender for Endpoint Plan 2. For information and instructions to submit files from the Files tab, see Submit files in Microsoft Defender for Endpoint.
Create allow entries for files
You can't create allow entries for files directly in the Tenant Allow/Block List. Unnecessary allow entries expose your organization to malicious email that would have been filtered by the system.
Instead, you use the Email attachments tab on the Submissions page at https://security.microsoft.com/reportsubmission?viewid=emailAttachment. When you submit a blocked file as I've confirmed it's clean, you can select Allow this file to add an allow entry for the file on the Files tab on the Tenant Allow/Block Lists page. For instructions, see Submit good email attachments to Microsoft.
Tip
Allow entries from submissions are added during mail flow based on the filters that determined the message was malicious. For example, if the sender email address and a URL in the message are determined to be malicious, an allow entry is created for the sender (email address or domain) and the URL.
During mail flow or time of click, if messages containing the entities in the allow entries pass other checks in the filtering stack, the messages are delivered (all filters associated with the allowed entities are skipped). For example, if a message passes email authentication checks, URL filtering, and file filtering, a message from an allowed sender email address is delivered if it's also from an allowed sender.
By default, allow entries for domains and email addresses, files, and URLs are kept for 45 days after the filtering system determines that the entity is clean, and then the allow entry is removed. Or you can set allow entries to expire up to 30 days after you create them. Allow entries for spoofed senders never expire.
During time of click, the file allow entry overrides all filters associated with the file entity, which allows users to access the file.
Create block entries for files
Email messages that contain these blocked files are blocked as malware. Messages that contain the blocked files are quarantined.
To create block entries for files, use either of the following methods:
From the Email attachments tab on the Submissions page at https://security.microsoft.com/reportsubmission?viewid=emailAttachment. When you submit a file as I've confirmed it's a threat, you can select Block this file to add a block entry to the Files tab on the Tenant Allow/Block Lists page. For instructions, see Report questionable email attachments to Microsoft.
From the Files tab on the Tenant Allow/Block Lists page or in PowerShell as described in this section.
Use the Microsoft Defender portal to create block entries for files in the Tenant Allow/Block List
In the Microsoft Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block Lists page, use https://security.microsoft.com/tenantAllowBlockList.
On the Tenant Allow/Block Lists page, select the Files tab.
On the Files tab, select
Block.
In the Block files flyout that opens, configure the following settings:
Add file hashes: Enter one SHA256 hash value per line, up to a maximum of 20.
Remove block entry after: Select from the following values:
- 1 day
- 7 days
- 30 days (default)
- Never expire
- Specific date: The maximum value is 90 days from today.
Optional note: Enter descriptive text for why you're blocking the files.
When you're finished in the Block files flyout, select Add.
Back on the Files tab, the entry is listed.
Use PowerShell to create block entries for files in the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
New-TenantAllowBlockListItems -ListType FileHash -Block -Entries "HashValue1","HashValue2",..."HashValueN" <-ExpirationDate Date | -NoExpiration> [-Notes <String>]
This example adds a block entry for the specified files that never expires.
New-TenantAllowBlockListItems -ListType FileHash -Block -Entries "768a813668695ef2483b2bde7cf5d1b2db0423a0d3e63e498f3ab6f2eb13ea3","2c0a35409ff0873cfa28b70b8224e9aca2362241c1f0ed6f622fef8d4722fd9a" -NoExpiration
For detailed syntax and parameter information, see New-TenantAllowBlockListItems.
Use the Microsoft Defender portal to view entries for files in the Tenant Allow/Block List
In the Microsoft Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Tenant Allow/Block Lists in the Rules section. Or, to go directly to the Tenant Allow/Block Lists page, use https://security.microsoft.com/tenantAllowBlockList.
Select the Files tab.
On the Files tab, you can sort the entries by clicking on an available column header. The following columns are available:
- Value: The file hash.
- Action: The available values are Allow or Block.
- Modified by
- Last updated
- Last used date: The date the entry was last used in the filtering system to override the verdict.
- Remove on: The expiration date.
- Notes
To filter the entries, select
Filter. The following filters are available in the Filter flyout that opens:
- Action: The available values are Allow and Block.
- Never expire:
or
- Last updated: Select From and To dates.
- Last used date: Select From and To dates.
- Remove on: Select From and To dates.
When you're finished in the Filter flyout, select Apply. To clear the filters, select
Clear filters.
Use the
Search box and a corresponding value to find specific entries.
To group the entries, select
Group and then select Action. To ungroup the entries, select None.
Use PowerShell to view entries for files in the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
Get-TenantAllowBlockListItems -ListType FileHash [-Allow] [-Block] [-Entry <FileHashValue>] [<-ExpirationDate Date | -NoExpiration>]
This example returns all allowed and blocked files.
Get-TenantAllowBlockListItems -ListType FileHash
This example returns information for the specified file hash value.
Get-TenantAllowBlockListItems -ListType FileHash -Entry "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
This example filters the results by blocked files.
Get-TenantAllowBlockListItems -ListType FileHash -Block
For detailed syntax and parameter information, see Get-TenantAllowBlockListItems.
Use the Microsoft Defender portal to modify entries for files in the Tenant Allow/Block List
In existing file entries, you can change the expiration date and note.
In the Microsoft Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block Lists page, use https://security.microsoft.com/tenantAllowBlockList.
Select the Files tab
On the Files tab, select the entry from the list by selecting the check box next to the first column, and then select the
Edit action that appears.
In the Edit file flyout that opens, the following settings are available:
- Block entries:
- Remove block entry after: Select from the following values:
- 1 day
- 7 days
- 30 days
- Never expire
- Specific date: The maximum value is 90 days from today.
- Optional note
- Remove block entry after: Select from the following values:
- Allow entries:
- Remove allow entry after: Select from the following values:
- 1 day
- 7 days
- 30 days
- 45 days after last used date
- Specific date: The maximum value is 30 days from today.
- Optional note
- Remove allow entry after: Select from the following values:
When you're finished in the Edit file flyout, select Save.
- Block entries:
Tip
In the details flyout of an entry on the Files tab, use
View submission at the top of the flyout to go to the details of the corresponding entry on the Submissions page. This action is available if a submission was responsible for creating the entry in the Tenant Allow/Block List.
Use PowerShell to modify existing allow or block entries for files in the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
Set-TenantAllowBlockListItems -ListType FileHash <-Ids <Identity value> | -Entries <Value>> [<-ExpirationDate Date | -NoExpiration>] [-Notes <String>]
This example changes the expiration date of the specified file block entry.
Set-TenantAllowBlockListItems -ListType FileHash -Entries "27c5973b2451db9deeb01114a0f39e2cbcd2f868d08cedb3e210ab3ece102214" -ExpirationDate "9/1/2022"
For detailed syntax and parameter information, see Set-TenantAllowBlockListItems.
Use the Microsoft Defender portal to remove entries for files from the Tenant Allow/Block List
In the Microsoft Defender portal at https://security.microsoft.com, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block Lists page, use https://security.microsoft.com/tenantAllowBlockList.
Select the Files tab.
On the Files tab, do one of the following steps:
Select the entry from the list by selecting the check box next to the first column, and then select the
Delete action that appears.
Select the entry from the list by clicking anywhere in the row other than the check box. In the details flyout that opens, select
Delete at the top of the flyout.
Tip
To see details about other entries without leaving the details flyout, use
Previous item and Next item at the top of the flyout.
In the warning dialog that opens, select Delete.
Back on the Files tab, the entry is no longer listed.
Tip
You can select multiple entries by selecting each check box, or select all entries by selecting the check box next to the Value column header.
Use PowerShell to remove entries for files from the Tenant Allow/Block List
In Exchange Online PowerShell, use the following syntax:
Remove-TenantAllowBlockListItems -ListType FileHash <-Ids <Identity value> | -Entries <Value>>
This example removes the specified file block from the Tenant Allow/Block List.
Remove-TenantAllowBlockListItems -ListType FileHash -Entries "27c5973b2451db9deeb01114a0f39e2cbcd2f868d08cedb3e210ab3ece102214"
For detailed syntax and parameter information, see Remove-TenantAllowBlockListItems.
Related articles
- Use the Submissions page to submit suspected spam, phish, URLs, legitimate email getting blocked, and email attachments to Microsoft
- Report false positives and false negatives
- Manage allows and blocks in the Tenant Allow/Block List
- Allow or block emails in the Tenant Allow/Block List
- Allow or block URLs in the Tenant Allow/Block List