Skip to main content
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. Alert banner
  • Warning (Orange) banners: Moderate risks that require user attention. Warning banner
  • Information (Blue) banners: General insights without immediate action required. Info banner

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 FeatureThe Contextual Banners feature is optional and the configuration options are disabled by default. To enable this feature, please contact 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. Selecting General Settings
  4. Select Contextual Banners.
  5. Enable the Alert, Warning and Info banners. Enabling Contextual 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. 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. 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:
    If you lack admin privileges or are not allowed to run scripts, first run:
    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:
    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:
  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 page in the Exchange admin panel. You should see multiple rules with the prefix XorBanner: Banner rules in M365

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:
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 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)
  1. Rerun the script without the -DryRun command.
  2. Check in the Exchange Admin Center if mail flow rules were successfully added.

Removing Banners

Execute the script:

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).
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. Access to that page is restricted.