> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.
# Enable Contextual Banners
> Add contextual warning banners to emails. Requires a subscription; contact support to enable.
The script packages and individual scripts linked on this page are protected downloads and
require a password.
## Why Contextual Banners Matter
Contextual Banners provide users with targeted security insights based on xorlab's analysis, appearing at the top of the email body. They highlight risks such as low sender trust, potential partner impersonation, or suspicious attachments. Unlike generic warnings, these banners are selectively applied to reduce alert fatigue, ensuring that users remain attentive to truly relevant threats.
Examples of different types of banners, categorized by severity:
* **Alert (Red) banners:** Critical warnings for high-risk messages. 
* **Warning (Orange) banners:** Moderate risks that require user attention. 
* **Information (Blue) banners:** General insights without immediate action required. 
## How It Works
Contextual Banners highlight security risks based on matched detection rules:
1. xorlab adds an `x-xor-banner` header to flagged emails.
2. The header includes a banner identifier.
3. Exchange mail flow rules detect the identifier.
4. If a match is found, the banner is added to the email body.
5. Emails with a `x-xor-banner` header appear in xorlab with the `#banner` tag.
## Configuration in xorlab
**Optional Feature**
The Contextual Banners feature is optional and the configuration options are disabled by default. To enable this feature, please contact [support@xorlab.com](mailto:support@xorlab.com) to add it to your subscription.
1. Log in to the xorlab Security Platform.
2. Click the **Admin** icon in the right menu.
3. In the **Admin Panel**, click **General Settings**. 
4. Select **Contextual Banners**.
5. Enable the Alert, Warning and Info banners. 
## Configuration in Exchange Online
Before proceeding, ensure you are connected to Exchange Online via PowerShell. If you need guidance, refer to [Microsoft's official documentation](https://learn.microsoft.com/en-us/powershell/exchange/connect-to-exchange-online-powershell).
A single script, `xorlabExoContextualBanners.ps1`, manages every banner mail flow rule: creating, updating, removing, enabling and disabling them, in English, German or Spanish.
1. Download the script with the command on [Script Downloads](/latest/script-downloads#contextual-banner-scripts-for-exchange-online). Run that command in your PowerShell window or in the Azure Cloud Shell, then come back here and start the script without any parameters to open the guided menu:
```powershell theme={null}
./xorlabExoContextualBanners.ps1
```
If you lack admin privileges or are not allowed to run scripts, first run:
```powershell theme={null}
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
```
If the script reports that `ExchangeOnlineManagement` is missing, confirm the prompt to install it, or rerun with `-InstallModule`.
2. Choose `1` for **Add**, keep the default rule prefix `XorBanner`, pick a banner language, then choose `Test` for the recipient scope and enter a test address — so you can confirm the banners render correctly before applying them to everyone.
3. The script then connects to Exchange Online, and a sign-in window opens. Sign in with your Exchange administrator credentials. In the Azure Cloud Shell, the script shows a code instead:
```text theme={null}
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ABCD-EFGH to authenticate.
```
Open that page in any browser, enter the code and sign in there. The script keeps running in your terminal while you do this.
4. Review the summary and confirm with `y`. The console then lists every rule as it is created:
```text theme={null}
Add: XorBannerContentExecutable
Add complete: 43 changed, 0 previewed, 0 skipped.
```
5. From the menu, choose **Add** again, this time with recipient scope `All`, to apply the banners to every internal recipient. Rule creation can take a few minutes.
Once complete, go to the [**Transport rules**](https://admin.exchange.microsoft.com/#/transportrules) page in the Exchange admin panel. You should see multiple rules with the prefix `XorBanner`: 
### Managing Banner Rules with PowerShell
Once you know which operation you need, pass `-Action` (and, for `Add`/`Replace`, `-Language`) to skip the menu and run it directly:
```powershell theme={null}
./xorlabExoContextualBanners.ps1 -Action Replace -Language DE
```
| Action | Effect |
| - | - |
| `Add` | Creates the rules that do not exist yet for the chosen language; skips the ones that already exist. |
| `Replace` | Updates the content and language of existing rules in place. Preserves each rule’s priority, enabled/disabled state and recipient scope unless you change the scope; rules that do not exist yet are skipped — use `Add` to create them first. |
| `Remove` | Deletes every rule whose name starts with the selected prefix. |
| `Disable` | Disables matching rules without deleting them, for example while troubleshooting. |
| `Enable` | Re-enables rules that were previously disabled. |
Add `-DryRun` to any of the commands above or below to preview the rules it would change
without writing anything. `-DryRun` still needs the `ExchangeOnlineManagement` module and a
connection to read the current rules, but it never installs modules or creates, updates,
removes, enables or disables a rule.
Add `-Language EN`, `DE` or `ES` for `Add`/`Replace`. For the other options:
* `-TestRecipientEmail 'alice@example.com','bob@example.com'` restricts `Add`/`Replace` to the listed recipients. On `Replace`, omitting this keeps each rule’s existing recipient scope.
* `-ResetRecipientScope` (`Replace` only) clears a previous recipient restriction and returns the rule to all internal recipients.
* `-CreateDisabled` (`Add` only) creates the new rules disabled; by default they are created enabled.
* `-RulePrefix XorlabBanner` targets rules created by an older version of this script instead of the current `XorBanner` prefix.
* `-NonInteractive` fails instead of prompting when a required parameter is missing, for unattended runs.
* `-UseExistingConnection` reuses an already-connected Exchange Online session instead of opening a new device sign-in, and leaves it connected afterward. It fails if no connected session exists.
For the full parameter reference, run `./xorlabExoContextualBanners.ps1 -Help` or `Get-Help ./xorlabExoContextualBanners.ps1 -Full`.
If an operation stops partway through (for example, you cancel the sign-in), earlier
successful changes are not rolled back automatically. Review the rule list in the Exchange
admin panel before retrying the same command — rerunning `Add` skips the rules it already
created.
## Configuration in On-Premises Exchange
### Setup
1. Download the [xorlab contextual banner On-Prem script package](/latest/script-downloads#contextual-banner-scripts-for-on-premises-exchange) to download all scripts to manage the banner mail flow rules and place them on your Exchange Server.
2. Open “Exchange Management Shell” as administrator and go to the Download directory.
### Installing Banners
1. Run the script with the -DryRun command. (replace the email address below for that of the recipient)
```powershell theme={null}
.\xorlabOnPremAddBanners_TestRecipientEmail_DE.ps1 -TestRecipientEmail "arthur.dent@exchange.xorlab.net" -DryRun
```
2. Rerun the script without the -DryRun command.
3. Check in the Exchange Admin Center if mail flow rules were successfully added.
### Removing Banners
Execute the script:
```powershell theme={null}
./xorlabOnPremRemoveBanners.ps1
```
## Excluding Specific Senders or Recipients
To prevent banners from appearing on specific emails, use the Contextual Banners Exclusion Lists in xorlab:
* **Contextual banners recipient address exclusion**: Prevents banners from appearing on emails sent to specific internal addresses.
* **Contextual banners sender address exclusion**: Prevents banners from appearing on emails from specific external senders.
To configure these lists:
1. Go to **Settings → Lists** in XCC.
2. Search for "banners".
3. Add the email address.
## Disabling Individual Banners
You can disable one or more banners using either of the following methods:
* **In Exchange:** Disable the mail flow rule associated with the unwanted banner. You can find the rule using the banner identifier listed in the banners list.
* **In xorlab:** Go to General Settings > Contextual Banners and disable all banners of a specific severity (e.g., Alert, Warning, or Info).
## Banner Categories and Identifiers
Each banner has a unique identifier, which starts with the prefix BANNER\_`(Category)`\_`(Name)`
(e.g., BANNER\_verdict\_phishing). Use that identifier to find the associated mail flow rule in
Exchange when you want to disable an individual banner.
The full list of banner names, categories, severity levels and descriptions is documented in
[Detection Defaults → Banner categories and identifiers](/latest/detection-defaults#banner-categories-and-identifiers).
Access to that page is restricted.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.