> ## 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.

# xorlab Email Security
Source: https://docs.xorlab.com/index

Defend your organization against sophisticated phishing attacks with AI-powered email security. Deploy, configure, and operate xorlab across your on-premises, hybrid, or cloud environment.

<p>Start here</p>

<p>Pick the path that matches your role.</p>

<div>
  <CardGroup>
    <Card href="/latest/setup-integration-overview">
      <img alt="Set up xorlab" />

      <img alt="Set up xorlab" />

      <p>For Admins</p>

      <p>Set up xorlab</p>

      Integrate with Microsoft 365 or on-premise, then tune detection and set up user quarantine.

      <span>Start the setup →</span>
    </Card>

    <Card href="/latest/analyst-overview">
      <img alt="Investigate and respond" />

      <img alt="Investigate and respond" />

      <p>For Analysts</p>

      <p>Investigate & respond</p>

      Get oriented in a 15-minute walkthrough, then start triaging reported email.

      <span>Get started →</span>
    </Card>
  </CardGroup>
</div>

<p>Evaluate xorlab</p>

<p>For teams that have not chosen xorlab yet.</p>

<div>
  <CardGroup>
    <Card href="/latest/evaluate-xorlab">
      <img alt="Evaluate xorlab" />

      <img alt="Evaluate xorlab" />

      <div>
        <p>See what xorlab catches before you switch anything on</p>

        <p>It runs alongside the filtering you already have and reports what it would have done — no MX record change, and nothing blocked until you decide.</p>

        <span>How a trial runs →</span>
      </div>
    </Card>
  </CardGroup>
</div>

<p>Not decided yet? <a href="/latest/analyst-benefits">What xorlab Changes for Analysts</a> and <a href="/latest/admin-essentials">What Integrating xorlab Involves</a> answer the two questions that come before a trial. Unfamiliar with a component or a term? Look it up in the <a href="/latest/terminology">Terminology</a> glossary.</p>

<p>Popular guides</p>

<div>
  <CardGroup>
    <Card href="/latest/feature-overview">
      <img alt="Feature Overview" />

      <img alt="Feature Overview" />

      <div>
        <p>Feature Overview</p>

        <p>Every feature, from detection layers to end-user self-service</p>
      </div>
    </Card>

    <Card href="/latest/ssq-overview">
      <img alt="Self-Service Quarantine" />

      <img alt="Self-Service Quarantine" />

      <div>
        <p>Self-Service Quarantine</p>

        <p>Let users manage their own quarantine</p>
      </div>
    </Card>

    <Card href="/latest/multi-tenancy-overview">
      <img alt="Multi-Tenancy" />

      <img alt="Multi-Tenancy" />

      <div>
        <p>Multi-Tenancy</p>

        <p>Manage multiple tenants in one console</p>
      </div>
    </Card>

    <Card href="/latest/upgrade-guide">
      <img alt="Upgrade Guide" />

      <img alt="Upgrade Guide" />

      <div>
        <p>Upgrade Guide</p>

        <p>Move to the latest version safely</p>
      </div>
    </Card>
  </CardGroup>
</div>

<p>Security & Compliance</p>

Which parties can process your data depends on whether you run xorlab on your own infrastructure or use it as a SaaS. [List of Data Sub-Processors](/latest/data-third-party-subprocessors) names them for each, and [Data Flow Overview](/latest/data-flow-overview) describes what each service receives while an email is analyzed.


# Handling the Abuse Mailbox
Source: https://docs.xorlab.com/latest/abuse-mailbox

Triage, analyze, and respond to employee-reported emails in the Abuse Mailbox, including automated resolution and reporter feedback.

## Manually resolve

### Review a case

1. To view open cases, click on **Abuse Mailbox** in the left menu or on the diagram in the dashboard.

   <img alt="Accessing Abuse Mailbox" />

2. Click on a message to view in detail

3. Review the email, paying attention to:
   * Message Preview
   * From and Envelope From address
   * Authentication
   * Relationship
   * Attachment Analysis (if applicable)
   * Reputation of links (if applicable)

4. Resolve the case

   <img alt="Resolve Case" />

5. The pop-up enables you to modify:
   * The verdict of the email
   * The Feedback Template for the employee
   * Add a comment to the feedback
   * Report the misclassification

### Resolve multiple cases

In the Abuse Mailbox view, you can also select multiple cases and resolve them simultaneously.

<img alt="Resolving multiple cases" />

## Auto resolve cases

xorlab Security Platform provides two mechanisms to automatically send feedback emails to reporters and close corresponding cases without manual interaction.

* **Verdict-based Automation** – determines actions based on the verdict and confidence of reported emails.
* **Campaign Automation** – enables a fine-tune approach when a reported email matches a specific campaign query.

### Verdict-based automation

The verdict-based automation of reported emails is enabled by default and can be modified via the [Actions](/latest/detection-actions) configuration screen.

1. In the dashboard, click the tiles icon next to your account name to click the **Admin** icon.

2. On the **Admin** page, click the **Actions** tile.

3. In the left menu, click **Abuse Mailbox**

4. Hover over the verdict to modify the action:

   <img alt="Selecting Abuse Mailbox Actions" />

5. Choose whether to resolve cases automatically or manually. For automatically resolved cases, select the email template to send to the employee.

   <img alt="Modifying Abuse Mailbox Actions" />

### Campaign automation

You can use [Campaigns](/latest/campaigns) to automatically resolve reported emails that match a campaign query. This option is suitable when you detect a pattern in reported emails and wish to fine-tune the system accordingly.

1. **Define the Search Query**

   * In the Abuse Mailbox view, enter a search query that captures the type of reported emails you want to handle automatically.
   * You can use tags and attributes such as sender, domain, or attachment type to make the query more specific.
   * Avoid using fields related to verdicts or actions, as they are not compatible with campaigns.

2. **Review the Results**

   * Inspect the list of matching emails to make sure your query captures only the messages you want to automate.
   * To reduce false matches, add inclusion tags like `#auth` or `#trusted` to narrow the scope.
   * Exclusion tags like `not #document` or `not #cloudstorage` can also be helpful in avoiding false matches.

3. **Create the Campaign**

   * When the search query is ready, press Enter to refresh the search results.
   * Then click on the campaign icon next to the search bar to create a new campaign.
   * If the icon is grayed out, your query contains unsupported fields — remove them and try again.

4. **Configure the Campaign**

   * Message Action: **None**
   * Resolve Action:
     * **Benign** – for legitimate, safe emails; specify which feedback message to send to the employee who reported the email.
     * **Malicious** – for unwanted or harmful emails; also choose a feedback message to inform the employee who reported the email.

### Campaign examples

The following examples show some ideas on how to automatically resolve reported cases with campaigns.

* Resolve all reported messages with young domains (sender domain or embedded URL):

  `(#365daysoldsender or #365daysold) and (#spam or #phishing)`

* Resolve all reported messages with shortened URLs (all confidences):

  `#phishing #shortened`

* Resolve all reported internal emails without attachments:

  `#internal not #nolocalreputation not #document`

* Resolve all reported partner emails without attachments or links to cloud storage:

  `#partner #auth #trusted not #nolocalreputation not #cloudstorage not #document`

* Resolve all greymail without attachments or links to cloud storage:

  ` (#marketing or #crm or #newsletter or #bulk or #external) not #nolocalreputation not(#cloudstorage or #cloudstoragesender) not #document not #spffail not #dkimfail not #subjectcvip not #bodylt75words not #lowtrusted not #internal`

Hints:

* Use `not #nolocalreputation not(#cloudstorage or #cloudstoragesender)` to avoid any phishing false negatives.
* Use `not #document` to avoid any malware false negatives.


# What Integrating xorlab Involves
Source: https://docs.xorlab.com/latest/admin-essentials

For the mail, infrastructure and security admins who have to operate it: the deployment choice, the settings an integration adds, and what stays on your plate afterward.

Putting a security product into a mail flow is normally a project. The integration of xorlab is a set of configuration changes in your own admin portal — visible to you afterward, and reversible in minutes.

<CardGroup>
  <Card title="Where it runs" icon="server" href="#where-it-runs">
    Hosted by xorlab, or on your own virtual infrastructure. Same detection either way.
  </Card>

  <Card title="What the integration involves" icon="list-check" href="#what-the-integration-involves">
    Three steps. Inline or monitoring is the one decision that shapes the rest.
  </Card>

  <Card title="What changes in your environment" icon="shuffle" href="#what-changes-in-your-environment">
    Connectors and mail flow rules. No MX change, nothing installed, no mailbox moved.
  </Card>

  <Card title="What you maintain afterward" icon="rotate" href="#what-you-maintain-afterward">
    Upgrades, certificates, backups and monitoring, split by SaaS and on-premises.
  </Card>
</CardGroup>

## Where it runs

**Two deployment options, with the same detection either way.**

* **xorlab SaaS** — hosted and operated by xorlab. There is nothing to provision, and the platform itself is kept up to date for you.
* **On-premises** — you run the xorlab Control Center (XCC) and one or more xorlab MTAs on your own virtual infrastructure, so processing and storage stay with you. Install and configure the VMs first, following the [VM Setup Guide](/latest/vm-setup-guide); the [Sizing Guide](/latest/sizing-guide) says what to provision and the [Network Guide](/latest/network-guide) says which connections to open. Only start the integration once the VMs are running.

Hybrid setups are supported in both directions. Which integration path you follow depends on where email enters and leaves your organization, not on where the mailboxes live.

If you protect several organizations from a single instance, onboard each of them as a tenant rather than repeating the integration: see [Multi-Tenancy Overview](/latest/multi-tenancy-overview).

## What the integration involves

**Three steps, in this order.**

| Step | What happens |
| :- | :- |
| [Before You Begin](/latest/before-begin-integration) | Declare the domains xorlab protects, set the data retention, and choose between inline and monitoring mode. |
| [M365 Overview](/latest/m365-integration-overview) or [On-prem Overview](/latest/on-prem-integration-overview) | Connect the mail flow, user login and reporting, plus the optional Microsoft 365 features. |
| [What to Configure Next](/latest/integration-next-steps) | Quarantine, notifications, detection and logging. |

**Inline or monitoring is the decision that shapes the rest.** In monitoring mode xorlab receives a copy of every email and drops it after the analysis, so your mail flow is untouched and nothing can be blocked. In inline mode email passes through xorlab and is forwarded on, which is what active protection requires. You can go inline in [Toothless Mode](/latest/before-begin-integration#configure-inline-mode) first, where every email is still delivered and you review what would have been quarantined. See [Switch Between Inline and Monitoring Mode](/latest/inline-and-monitoring-mode).

## What changes in your environment

The integration is made of settings in your own admin portal:

* **Microsoft 365** — two connectors with TLS enforced, two mail flow rules, and one enterprise application in Entra ID. Microsoft Graph permissions, a reporting mailbox and moving the Microsoft quarantine into xorlab are separate, optional steps.
* **On-premises** — the scope of your receive connector and a send connector on Exchange, or BCC rules for monitoring mode; firewall rules for SMTP between your mail servers and the xorlab MTAs; and your own mail servers registered inside xorlab as trusted infrastructure, which is a setting in xorlab rather than in your environment ([Add Your Trusted Infrastructure](/latest/on-prem-add-trusted-mtas)).

What stays as it is:

| Unchanged | Why |
| :- | :- |
| **Your MX records** | On Microsoft 365, email keeps arriving at Microsoft, which hands it to xorlab and takes it back for delivery. On-premises they change only if xorlab replaces your existing gateway. |
| **Your outbound sending identity** | Outgoing email still leaves through Microsoft, so your public sending IPs, your SPF record and your DKIM signatures are unchanged. On-premises it changes only if xorlab replaces your existing gateway. |
| **Exchange Online Protection and Defender** | If you use M365, Microsoft’s own filtering keeps running, and xorlab is layered on top of it. |
| **Mailboxes, addresses, licenses and clients** | Nothing is migrated and no add-in is rolled out. Reporting uses the button your users already have. |

Undoing it is the same size as doing it. Disabling the two mail flow rules puts email back on its previous path within minutes, with no DNS change and no cutover window.

<Card title="Review What Changes in Your Environment" icon="list-check" href="/latest/integration-impact">
  The full table for each path: which setting goes where, whether it is mandatory, what your users notice, and how to roll it back.
</Card>

## What your users notice

* **In monitoring mode, nothing at all.** No email is modified, delayed or blocked.
* **In inline mode, with the delivered defaults**, email with a malicious verdict is quarantined instead of delivered, and some verdicts are delivered with a subject prefix such as `[SPAM]`. Both are adjustable in [Review Default Actions](/latest/detection-actions).
* **Only if you enable them**, users get the [Self-Service Quarantine](/latest/ssq-overview) and the notifications that go with it, or [Contextual Banners](/latest/detection-contextual-banners) inside the message body. Both are off until you turn them on.

## What you maintain afterward

**How much of the platform you operate depends on where it runs.** The security configuration — guarded domains, detection tuning, lists, users and roles — stays with you in both cases.

| Task | xorlab SaaS | On-premises | Where it is documented |
| :- | :- | :- | :- |
| Platform upgrades | Handled by xorlab | You upgrade, within the support window of your major version | [Upgrading to a Patch Release](/latest/patch-upgrade), [Release Lifecycle Support](/latest/release-lifecycle-support) |
| TLS certificates | Handled by xorlab | You renew and install them on the MTAs and on XCC | [Replace MTA SMTP Certificate](/latest/tls-certificates-for-mta-smtp), [Replace MTA GUI Certificate](/latest/tls-certificates-for-mta-proxy), [Replace XCC Certificate](/latest/tls-certificates-for-xcc) |
| Backups | Handled by xorlab | Off by default, because the VM is usually covered by your hypervisor. If you switch them on, xorlab writes the backup files to a directory on the XCC and moving them somewhere durable is yours | [Backup & Recovery](/latest/backup-recovery) |
| Monitoring and alerting | Handled by xorlab | Dashboards and a set of alert rules ship with the platform. You decide where alerts are delivered — email, webhook, Slack or your own systems | [Set Up Monitoring](/latest/monitoring-guide), [Enable Alerts](/latest/monitoring-alerts) |
| Data retention values | Handled by xorlab | You configure them | [Data Retention Overview](/latest/data-retention-overview) |

Releases are rolled out to SaaS customers first and monitored before they are announced for on-premises upgrades, so an on-premises upgrade is applied to a release that has already been running elsewhere.

## Where to start

<CardGroup>
  <Card title="Integration Overview" icon="rocket-launch" href="/latest/setup-integration-overview">
    The complete integration in three steps, with the Microsoft 365 and on-premises paths side by side.
  </Card>

  <Card title="Review What Changes in Your Environment" icon="list-check" href="/latest/integration-impact">
    The questions your mail, network and security teams ask before the project starts, answered per path.
  </Card>

  <Card title="Evaluate xorlab" icon="flask" href="/latest/evaluate-xorlab">
    How a trial runs on live traffic without blocking anything, and how long each phase takes.
  </Card>

  <Card title="What xorlab Connects To" icon="hexagon-nodes" href="/latest/integrations-overview">
    Whether the rest of your stack is covered: SIEM, SOAR, identity, Microsoft Graph, threat intelligence.
  </Card>
</CardGroup>


# What xorlab Changes for Analysts
Source: https://docs.xorlab.com/latest/analyst-benefits

For analysts weighing up the platform: which work it takes over, how much of each decision it shows you, and which corrections you can make on your own.

This page summarizes some of the major benefits analysts can get out of using xorlab.

<CardGroup>
  <Card title="Less manual work" icon="filter-circle-xmark" href="#less-reaches-your-queue">
    Reported email and quarantine releases resolve themselves. What is left is what automation could not decide.
  </Card>

  <Card title="Every verdict shows its reasoning" icon="magnifying-glass-chart" href="#every-verdict-shows-its-reasoning">
    Indicators, sender relationship, authentication and file analysis on one screen, down to the individual detection rules. Read at a glance, or in depth.
  </Card>

  <Card title="You correct it yourself" icon="wrench" href="#you-correct-it-yourself">
    Activate search queries as standing policies. No configuration file, no support ticket, reversible afterward.
  </Card>

  <Card title="Capabilities you may not have today" icon="wand-magic-sparkles" href="#capabilities-you-may-not-have-today">
    Search by what a message is about, group a whole wave from one email, pull delivered mail back out.
  </Card>
</CardGroup>

## Less manual work

**Parts of the platform can take work off your desk before you see it.**

**Employee-reported email.** Reports arrive as cases, each carrying xorlab’s own analysis of the message. Cases can be closed without you in two ways: by verdict, so anything the platform has already classified confidently is resolved automatically. Or by a campaign, so a pattern you have handled once is handled the same way every time after that. The employee who reported it gets feedback either way. See [Handling the Abuse Mailbox](/latest/abuse-mailbox).

**Quarantine release.** End-users see their own quarantined email and release what they need themselves. For the quarantines you are not willing to hand over, they can only ask, and the request reaches you with the analysis already attached. See [SSQ Overview](/latest/ssq-overview) and [Handling Release Requests](/latest/handling-release-requests).

<img alt="Abuse Mailbox" />

## Every verdict shows its reasoning

**Transparent reasoning, and all relevant information at a glance.**

Each message carries a verdict and a confidence, and the detail view shows what produced them: the relationship between sender and recipient, authentication results, the indicators that were found, the analysis of every attachment and link, and so on. From there you can go further and read the individual rules that contributed. See [Understanding an Email Verdict](/latest/understand-verdict).

**It is all one screen, and it is built to be read quickly.**

<img alt="Detail View" />

This allows you tell an employee why their report was closed, a user why their email was held back, and an auditor why the platform did what it did.

The reasoning rests on models that are documented rather than described as magic: how xorlab learns who normally communicates with whom, what content is normal in your environment, and what it makes of sender authentication. See [Concepts Overview](/latest/concepts-overview).

## You correct it yourself

**Fix false positives or false negatives in a sustainable way**

Any search query can be turned into a campaign: a standing policy that overrides the default decision for exactly the messages it matches, and leaves everything else alone. A campaign can quarantine, deliver, rewrite or classify a an email, and it stays visible and reversible afterward. See [Using Campaigns](/latest/campaigns).

<img alt="Campaigns" />

Smaller corrections are quicker still. Releasing an email from quarantine is itself a signal: xorlab becomes less aggressive toward that sender each time it happens. The step-by-step measures are in [Fix a False Positive](/latest/fix-false-positives) and [Fix a False Negative](/latest/fix-false-negatives), with [Tune Detection](/latest/detection-tuning) for the cases where the overall balance needs to shift, and [Lists Overview](/latest/lists) for sender-level exceptions such as VIPs, blacklists and whitelists.

## Capabilities you may not have today

| Capability | What it gives you |
| :- | :- |
| **Search over all aspects of an email** | Query the whole corpus by what a message is about — an invoice, a credential prompt, a package delivery — as well as by link, domain, attachment property, tag, verdict and authentication result, and so on. The UI is fast, and autocomplete offers the syntax as you type. <br />[Search](/latest/search) · [Use Topics for Searches and Campaigns](/latest/topic-detection) |
| **Find the rest of a wave from one message** | Similarity search groups an email with the others that belong to it, on content rather than on sender or subject, so a wave that varies both is still one result set. The grouping can be saved as a search or promoted to a campaign.<br />[Quick Walkthrough](/latest/quick-walkthrough) |
| **Pull a delivered email back out** | Case Isolation removes a message from the mailboxes it reached, through the Microsoft Graph API.<br />[Activate Case Isolation](/latest/m365-case-isolation) |
| **Analyze email that arrived before xorlab did** | On Microsoft 365, past email is imported from the mailboxes and analyzed, so you have history to work with instead of waiting out a learning phase.<br />[Import Past M365 Emails](/latest/m365-retrospective-email-scanning) |
| **Feed the rest of your stack** | Verdicts, SMTP logs, threat intelligence extracted from your own mail and the full audit trail go out over Syslog in JSON or CEF, and lists are managed over a REST API.<br />[Connect a SIEM](/latest/integrations-siem) · [Automate with a SOAR](/latest/integrations-soar) |

## Where to start

<CardGroup>
  <Card title="Quick Walkthrough" icon="person-running" href="/latest/quick-walkthrough">
    Fifteen minutes in the web interface: search for an email, build a campaign, run a similarity search, answer a report.
  </Card>

  <Card title="Evaluate xorlab" icon="flask" href="/latest/evaluate-xorlab">
    How a trial runs on your own traffic, and what you can measure the results against before anything is blocked.
  </Card>

  <Card title="Analyst Overview" icon="compass" href="/latest/analyst-overview">
    The full analyst path: core concepts, the daily workflows, and the reference material behind them.
  </Card>

  <Card title="Video Tutorials" icon="video" href="/latest/video-tutorials">
    The same ground covered on screen, if you would rather watch than read.
  </Card>
</CardGroup>


# Analyst Overview
Source: https://docs.xorlab.com/latest/analyst-overview

The analyst's entry point, mapping the daily workflows and the order to learn them in.

This guide covers the work you do as an analyst in xorlab: understanding why an email received a particular verdict, handling reported emails and release requests, and correcting the detection when a message is classified incorrectly.

If you are new to the platform, start with the core concepts and the walkthrough below. The remaining sections describe the day-to-day workflows and the reference material you will return to.

***

## Start here

<CardGroup>
  <Card title="Core Concepts" icon="lightbulb" href="/latest/concepts-overview">
    Learn how the platform thinks: relationship, reputation and authentication.
  </Card>

  <Card title="Quick Walkthrough" icon="person-running" href="/latest/quick-walkthrough">
    A short guided tour through the web interface with hands-on introduction.
  </Card>

  <Card title="Video Tutorials" icon="video" href="/latest/video-tutorials">
    For visual learners — step-by-step description of the platform.
  </Card>
</CardGroup>

***

## Essential workflows

Your work with xorlab will typically include:

| Topic | Description |
| - | - |
| [Using Campaigns](/latest/campaigns) | Create new detection rules via campaigns. |
| [Understanding a Verdict](/latest/understand-verdict) | Understand why xorlab assigned an email a specific verdict. |
| [Handling the Abuse Mailbox](/latest/abuse-mailbox) | How to handle the reported emails and give end-users feedback. |
| [Handling Release Requests](/latest/handling-release-requests) | How to handle quarantine release requests from end-users. |
| [Reporting a Misclassification](/latest/reporting-misclassification) | Handle misclassifications and report them to xorlab. |

***

## Correcting the detection

These topics come up when a message is classified incorrectly:

* How to [Fix a False Positive](/latest/fix-false-positives)
* How to [Fix a False Negative](/latest/fix-false-negatives)
* How to [Handle Authentication Issues](/latest/authentication-issues)
* How to [Tune Detection](/latest/detection-tuning) overall
* [Using Topics](/latest/topic-detection) to improve searches and campaigns

***

## Reference

Detailed material on the concepts you will encounter across the workflows above:

* [**Tags**](/latest/tags) - what tags exist and how to use them
* [**Verdicts**](/latest/verdicts) - list of verdicts with their description and precedence
* [**Search Syntax**](/latest/search) - craft fast, accurate queries
* [**Lists**](/latest/lists) - description of all built-in lists


# Enable Auto-Login
Source: https://docs.xorlab.com/latest/authentication-auto-login-link

Passwordless quarantine access for employees, via a time-limited link embedded in notification mails.

The auto-login link grants end-users access to their quarantined emails in the SSQ, under the `xcc_quarantine_user` role, see [Roles](/latest/built-in-user-roles).

## Quickstart

The following steps will enable Auto-Login links:

1. In the Expert Editor, open `/shared/guarded_tenants.yml`.
2. Add the following configuration:

   <Accordion title="Expand to read the instructions.">
     * Include the `autoLoginLink` block for each tenant.
     * Set `enabled` to `true` to include an auto-login link in all quarantine notification emails.
     * Set `enabled` to `false` to disable the feature.
     * `expirationDays` defines the validity period of the authentication link.
     * The default of `expirationDays` is 7 days.
     * To make links permanent, set `expirationDays` to `-1`.
   </Accordion>

   ```yaml /shared/guarded_tenants.yml {7-9} theme={null}
   tenants:
     - name: example.com
       domains:
         - example.com

       autoLoginLink:
         enabled: true
         expirationDays: 7  
   ```
3. Click **Publish**. The Auto-Login configuration becomes active within about one minute.
4. Now all quarantine notifications will contain Auto-Login links.

## Create access link

For testing purposes, you can generate a link to access a specific mailbox in the SSQ.

Prerequisites:

* You need the `xcc_user_impersonate` permission, which is granted by the admin role
* `autoLoginLink` needs to be enabled, as shown above

Access this URL in your browser to get the token:

```
https://<your.xorlab.instance>/api/v2/autologin/v1/generateToken?mailbox=test@example.com
```

## Trigger a notification

You can trigger an artificial quarantine notification to a specific mailbox, helping users regain access to the SSQ:

Prerequisites:

* You need an active, signed-in xorlab administrator session in the same browser. This endpoint is not publicly accessible and cannot be called anonymously.
* `autoLoginLink` needs to be enabled, as shown above, for the notification to contain an access link.

```
https://<your.xorlab.instance>/api/v2/emailNotification/v1/sendQuarantineAccessNotification?mailbox=test@example.com
```

<Warning>
  **Use with care**

  The notification is delivered to whichever mailbox you specify, and depending on the tenant configuration it may contain a valid Auto-Login link for that mailbox. Only trigger it for mailboxes you are entitled to access.
</Warning>

## Additional information

### Compatibility with Authentication Methods

The Auto-Login Authentication method is compatible with other authentication methods, including SAML, LDAP, and password-based authentication. This allows organizations to provide seamless access to quarantined emails for end-users while preserving existing authentication mechanisms for roles with elevated permissions. No configuration changes are needed in /auth/auth/auth.yml to enable this feature.

When enabled, the auto-login token is included in all quarantine notification emails. It is not possible to restrict the Auto-Login Authentication method to specific user groups—once activated, all users receiving quarantine notifications will have access through the auto-login link.

### Access for Elevated Roles

When users with elevated roles—such as analysts or administrators—receive a quarantine notification for their own quarantined emails, they can use the auto-login link to access their Self-Service Quarantine. However, this authentication method does not grant access to the Analyst Dashboard, Admin settings, or other privileged areas of the platform.

To access these administrative features, users with elevated roles must first sign out and re-authenticate using their primary authentication method, such as SAML or LDAP. This ensures that privileged actions remain protected under stricter authentication controls, maintaining security while still allowing convenient access to quarantined emails.

## Multi-Tenancy

The `autoLoginLink` block shown above is configured per tenant, so in a multi-tenant deployment you can enable Auto-Login for some tenants and not for others, and give each tenant its own `expirationDays`.

Auto-Login is our recommended way to give the end-users of a tenant access to their SSQ, because it requires no integration with the tenant. See [Enable Tenant Login](/latest/multi-tenancy-authentication#auto-login) for a per-tenant example.


# Add Trusted CA Certificates
Source: https://docs.xorlab.com/latest/authentication-certificates

Add a custom certificate authority to the xorlab trust store so LDAP and SAML2 connections validate.

<Note>
  **Trust store**

  You must have the certificate(s) ready in a PKCS12 trust store named `truststore.p12`. The trust store must contain all certificates required for all trusted communication initiated by xorlab Authentication Service (LDAP, SAML2, etc.). For every service, only the outermost signer certificate is required to be a part of the trust store as long as the service supplies a correct certificate chain. By inserting a concrete server certificate into the trust store, that certificate is pinned explicitly.

  To create a trust store, you can use [Keytool](https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html) or [OpenSSL](https://www.ssl.com/how-to/create-a-pfx-p12-certificate-file-using-openssl/). In a nutshell, you have to add your certificate file (.pem, .crt, .cer, .p7b, or .p7c) to the trust store. You can do this with the following `keytool` command:

  `keytool -import -file certificate.pem -alias ca1 -keystore truststore.p12`

  This command will export your `certificate.pem` file to the `truststore.p12` trust store file, giving the certificate a `ca1` alias.
</Note>

1. Open the `auth/auth/auth.yml` file using the XCC [Expert Editor](/latest/expert-editor).

2. Add the following block and enter the password of your provided trust store:

   ```yaml auth.yml theme={null}
   trustStore:
     # The type of the trust store to use. Default is PKCS12 which is also the default
     # these days when using the 'keytool' shipped with the JRE.
     type: pkcs12
     # The default trust store file. Defaults to 'truststore.p12'. Relative paths are resolved
     # relative to the config directory.
     file: truststore.p12
     # The trust store password.
     password: <trust_store_password>
   ```

   <Info>
     The password of the trust store delivered with a new deployment is documented in
     [Deployment Defaults → Trust store password](/latest/deployment-defaults#trust-store-password).
     Access to that page is restricted.
   </Info>

3. Click **Publish**. The authentication configuration becomes active within about one minute.

4. Switch to the CLI of the XCC and execute the following instructions one by one:

   ```shell theme={null}
   sudo su -s /bin/bash xcc_backend
   cd /var/lib/xorlab/xcc/config/work/ag_local/auth/auth
   ```

5. Copy the `truststore.p12` file containing your certificate into the folder specified above.

6. Execute the following instructions one by one:

   ```shell theme={null}
   git add .
   git commit -m "Adding truststore file"
   exit
   ```

The Authentication service restarts automatically and applies the new configuration.


# Handle Authentication Issues
Source: https://docs.xorlab.com/latest/authentication-issues

Diagnose common email authentication problems, such as legitimate senders blocked for missing SPF or DKIM.

Most commonly:

* A legitimate email is blocked because the sender does not provide proper authentication
* SPF or DKIM is correct, but the email is not marked as authentic

| Situation | Explanation | Measures |
| - | - | - |
| **Sender has valid SPF but is not marked authentic** | Usually, the envelope from domain (used for SPF) differs from the header from domain, which breaks DMARC alignment. | Ask the sender to use the same domain for both. If that’s not possible, configure a [Trusted MTA](/latest/trusted-mtas) in xorlab to override authentication. |
| **Email has a valid DKIM signature but is not marked authentic** | Usually, the DKIM signing domain is different from the header from domain, which breaks DMARC alignment. | Ask the sender to sign with the same domain as the header from. If that’s not possible, use a [Trusted MTA](/latest/trusted-mtas) configuration. |
| **SPF/DKIM failed, but the email was not blocked** | A failing SPF or DKIM alone is not enough to block an email, as this also happens with legitimate mail. However, it is still treated as a negative signal and increases the chance of blocking. | If you want to block all such emails, create a [campaign](/latest/campaigns) based on the `#dkimfail` and `#spffail` tags. |
| **Email passes SPF/DKIM but is still blocked** | Authentication only proves that the email was actually sent from the sender domain, not that the email is safe. Attackers can still send from valid domains. | Create a [campaign](/latest/campaigns), or add the sender to the **Low trusted sender addresses** list ([Trusted Senders and Infrastructure](/latest/trusted-senders-infrastructure)) to make sure the email is not blocked. |


# Enable LDAP Login
Source: https://docs.xorlab.com/latest/authentication-ldap

Configure the LDAP backend so users sign in to xorlab with their existing directory credentials.

<Warning>
  **Prerequisites**

  * If you want to connect to an LDAP server with non-public certificates, follow [Add Trusted CA Certificates](/latest/authentication-certificates).
</Warning>

## Basic configuration

LDAP backend is defined in the `ldapAuthDataSources:` subsection of the `usernamePasswordAuthBackends:` section in the `auth/auth/auth.yml` file. First, you have to set up the basic parameters of your LDAP source, starting with its name—that can be whatever you like (`myLDAP` in this sample case)—and then configuring the connection as in the example below:

```yaml auth.yml theme={null}
    ldapAuthDataSources:
      myLDAP:
        host: ldap.example.com
        port: 10636
        useLdaps: true
        useStartTls: false
        trustAll: false
```

The following table explains the parameters:

| Parameter | Value |
| :- | :- |
| `host` | Address of your LDAP server |
| `port` | Port number of your LDAP server |
| `useLdaps` | Whether to use SSL on the socket layer (conflicts with `startTls` below) |
| `useStartTls` | Whether to use the `startTLS` command (conflicts with `useLdaps` above) |
| `trustAll` | Skip verification of the SSL server certificate (**warning**: do NOT do this on production!) |

## Authentication

The next step involves user authentication in your LDAP server. You can use a direct distinguished name (DN) of a user who is being authenticated (if you already know what the DN of a user looks like) or query LDAP for the DN. Either way, you have to specify only one method.

This is done within the `authentication:` subsection of your LDAP server configuration.

### Direct DN

If you want to use a direct DN of a user, you just set the `withUserDn.userDnPattern` attribute to a pattern which will allow to deduct a DN from a login username string, e.g., `"uid={0},ou=users,dc=company,dc=com"`, where `{0}` will be substituted with a username:

```yaml auth.yml theme={null}
        authentication:
          withUserDn:
            userDnPattern: "uid={0},ou=users,dc=example,dc=com"
```

### DN query

When a DN of a user is not known, you can search the LDAP directory for the user entry using a so-called *technical user* for authentication. Once the user entry is found, their DN is used to authenticate with the provided credentials.

A sample configuration of a DN query is as follows:

```yaml auth.yml theme={null}
        authentication:
          withQueryDn:
            bindDn: "uid=xcc-dev,ou=users,dc=example,dc=com"
            bindPassword: "LDAP_bind_pw"
            userBase: "ou=users,dc=example,dc=com"
            userSearch: "(uid={0})"
```

The table below explains the parameters:

| Parameter | Value |
| :- | :- |
| `bindDn` | The bind DN of the technical user that will be used to fetch the user information from the directory; both user and password can be omitted if the directory supports unauthenticated access |
| `bindPassword` | Password for the technical user |
| `userBase` | Specifies the subtree in the directory where user information is stored |
| `userSearch` | Template for user search query, e.g., <br />- for OpenLDAP: `"(cn={0})"`<br />- for Microsoft Active Directory: `"(sAMAccountName={0})"`<br /> where `{0}` will be replaced with the login username |

## Authorization

After a successful authentication, a user has to be authorized: their roles are read from the LDAP backend. In the `authorization.query:` subsection, you can configure the parameters of the role search using a nested search within a subtree of a directory as in the sample configuration below:

```yaml auth.yml theme={null}
        authorization:
          query:
            roleBase: "ou=groups,dc=example,dc=com"
            roleSearch: "(member={0})"
            nestedRoleDepth: 2
            groupRoleAttribute: dn
```

The parameters are explained in the table below:

| Parameter | Value |
| :- | :- |
| `roleBase` | Base of the role subtree |
| `roleSearch` | Filter to search for roles where<br />- `{0}` is substituted with the DN of the user entry found with the prior user search<br />- `{1}` is substituted with the username |
| `nestedRoleDepth` | Integer that specifies how many times to search the directory for nested roles (set to `0` to disable resolution of nested roles) |
| `groupRoleAttribute` | The role name to be used as an input for the `roleMapping` attribute; if this is not set, the DN of the role entry is used |

## Attribute mapping

In the next step you have to map (assign) attributes from the LDAP user entries to the user model in xorlab Security Platform. The mapping is described using [Spring expression language](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html) and is configured under the `attributeMapping:` subsection.

You can use these methods:

* `attr('<name>')`: retrieve the attribute with the `'<name>'` name from attributes in the source authorization system
* `replace(<string or list of strings>, '<pattern>', 'replace')`: replace every occurrence of `'<pattern>'` with `'replace'` in an input string or a list of input strings
* `azureAdEmails()`: read all email addresses from the Azure Active Directory `proxyAddresses` attribute.

Literal values have to be quoted, e.g., `key: 'literal value'`.

A sample configuration for attribute mapping, which simply retrieves attributes from the auth system, would look like this:

```yaml auth.yml theme={null}
        attributeMapping:
          userName: "attr('uid')"
          displayName: "attr('cn')"
          emails: "attr('mail')"
```

Available attributes are explained in the table below:

| Attribute | Description |
| :- | :- |
| `userName` | An attribute mapping for the username. The result of this mapping will be put into the `subject` attribute of the token issued to the consuming services |
| `displayName` | An attribute mapping for the display name of the user. It is optional and could be used by consuming services in places where a more descriptive name of the user is appreciated |
| `emails` | A mapping for the list of emails associated with the user. Consuming services might use this list to associate the user with a certain pool of email messages |
| `tenant` | **Only required for multi-tenancy deployments**: Make sure the value of the `tenant` attribute correspond to the `name` defined in the `guarded_tenants.yml`. |

## Role mapping

The last step is to configure role mapping. You must map all roles served by the LDAP directory to the corresponding xorlab roles under the `roleMapping:` subsection. Roles that are not mapped are ignored by default. Multiple xorlab roles can be mapped to the same LDAP role, e.g., `xcc_login` → `company1-group1`, `xcc_admin` → `company1-group1`.

<Note>
  The role mapping is case sensitive, therefore make sure that you specify the role names according to what is served by the LDAP directory.
</Note>

A sample role mapping configuration is shown below:

```yaml auth.yml theme={null}
        roleMapping:
          xcc_login: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_analyst: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_admin: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
          xcc_insights: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_monitor: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
```

If the LDAP directory already serves roles compatible with xorlab (see [Built-in Roles](/latest/built-in-user-roles)), you can also specify a “pass-through” role-mapping mode using `roleMappingMode: PASS_THROUGH`.

<Note>
  Please be aware that in the pass-through role-mapping mode, all roles served by the LDAP directory are added to the xorlab authorization context. If this context is becoming too large, i.e., too many irrelevant roles are added, then it might lead to errors and users being unable to access XCC. Therefore, it is advisable to only map the roles that are relevant to xorlab.
</Note>

A sample role mapping configuration using the pass-through mode:

```yaml auth.yml theme={null}
        roleMappingMode: PASS_THROUGH
        roleMapping:
          # You can still define a role mapping in pass-through mode
          xcc_monitor: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
```

## Activate the configuration

After updating `auth/auth/auth.yml`, click **Publish**. The authentication configuration becomes active within about one minute.

## Multi-Tenancy

The setup on this page applies unchanged in a multi-tenant deployment. Two things are added on top: a `tenant` entry in the [Attribute mapping](#attribute-mapping) that matches the tenant `name` in `guarded_tenants.yml`, and a [tenant-restricted user role](/latest/built-in-user-roles) in the [Role mapping](#role-mapping).

<Card title="Enable Tenant Login" icon="building" href="/latest/multi-tenancy-authentication#ldap-login">
  Complete per-tenant LDAP example, and the other login options available to tenants.
</Card>

## Example configuration

The final configuration for an LDAP backend should look like this:

```yaml auth.yml theme={null}
tokenSigningKey: "xyz"

enabledAuthBackends:
  - usernamePassword

usernamePasswordAuthBackends:
  usernamePassword:
    ldapAuthDataSources:
      myLDAP:
        host: ldap.example.com
        port: 10636
        authentication:
          withQueryDn:
            bindDn: "uid=xcc-dev,ou=users,dc=example,dc=com"
            bindPassword: "LDAP_bind_pw"
            userBase: "ou=users,dc=example,dc=com"
            userSearch: "(uid={0})"
        authorization:
          query:
            roleBase: "ou=groups,dc=example,dc=com"
            roleSearch: "(member={0})"
            nestedRoleDepth: 2
        attributeMapping:
          userName: "attr('uid')"
          displayName: "attr('cn')"
          emails: "attr('mail')"
        roleMapping:
          xcc_login: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_analyst: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_admin: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
          xcc_insights: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_monitor: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
```


# Authentication Overview
Source: https://docs.xorlab.com/latest/authentication-overview

Compare the available login methods (SAML, LDAP, auto-login, password file) and choose which to enable for admins, analysts, and end users.

We recommend to enable **SAML** login for your admin and analyst users, and **Auto-Login** for your end-users to access SSQ.

<CardGroup>
  <Card title="SAML" icon="wand-magic-sparkles" href="/latest/authentication-saml">
    Provide Single Sign-On (SSO) for your users.
  </Card>

  <Card title="LDAP" icon="user-tag" href="/latest/authentication-ldap">
    Login users via LDAP query to an Active Directory.
  </Card>

  <Card title="Auto-Login" icon="link" href="/latest/authentication-auto-login-link">
    Auto-login users via the link in a quarantine notification. Works only for end-user access to the SSQ. Not available for admin or analyst roles.
  </Card>

  <Card title="Password File" icon="file" href="/latest/authentication-with-a-password-file">
    Maintain user credentials locally on xorlab in a static file, with optional TOTP/2FA onboarding.
  </Card>
</CardGroup>

## Multi-Tenancy

All four methods above work in a multi-tenant deployment. Two things are added on top:

* The authentication backend has to map a `tenant` attribute whose value matches the `name` of a tenant in `guarded_tenants.yml`.
* Users have to be mapped to a [tenant-restricted role](/latest/built-in-user-roles), so that they only see the resources of their own tenant.

<Card title="Enable Tenant Login" icon="building" href="/latest/multi-tenancy-authentication">
  Configuration examples for SAML, Auto-Login, password file and LDAP in a multi-tenant deployment.
</Card>

## Additional information

Here we provide additional information about user authentication for reference.

### Using multiple authentication methods

xorlab supports using multiple authentication methods at the same time. For example, you can have SAML, LDAP and Password File active in parallel.

The enabled methods are specified in `auth.yml`:

```yaml auth.yml {3,4,7,10} theme={null}
# The first entry will be the default
enabledAuthBackends:
  - exampleSaml
  - examplePassword

usernamePasswordAuthBackends:
  examplePassword:  # this identifier will determine the name of the backend

saml2AuthBackends:
  exampleSaml:  # this identifier will determine the name of the backend
    ...
```

The first entry in the list will be the default authentication method. This matters if you combine for example SAML and LDAP.

<Note>
  **Access non-default auth method**

  To use a specific authentication method that is not the default, use `_agAuthBackend` in the URL, e.g., `https://xyz.activeguard.cloud/?_agAuthBackend=examplePassword`.
</Note>

### User object in xorlab

An xorlab user has the following attributes. The required ones need to be provided whenever a user logs in.

* **User name (required)** (also called "subject")
* **Display name (optional)**
* **Email addresses (optional)**: List of email addresses associated with the user. Used to determine SSQ mailbox access.
* **Roles (required)**: List of roles associated with the user.
* **Tenant (optional)**: The tenant the user belongs to. Only relevant in multi-tenant deployments, see [Multi-Tenancy](#multi-tenancy).


# Enable SAML Login
Source: https://docs.xorlab.com/latest/authentication-saml

Set up a generic SAML integration for single sign-on. For Entra ID, use the dedicated Entra ID guide instead.

<Warning>
  **SAML with M365 Entra ID**

  If you use Entra ID, please instead follow [SAML with Entra ID](/latest/m365-saml-entra-authentication).
</Warning>

In order to get a working SAML authentication setup, you have to configure three elements:

1. Identity provider (on the customer side)
2. Authentication backend in xorlab
3. [Certificate in a trust store](/latest/authentication-certificates)

Because multiple SAML identity providers can be active simultaneously in xorlab, they have to be distinguished by their names in the xorlab configuration. Here, this name will be referred to as `saml2BackendName`.

## Identity provider configuration

On the identity provider side, you have to set up a new application for xorlab with the following properties:

* SSO URL: `https://<xorlabDomain>/auth/saml2/sso/<saml2BackendName>`
* Audience URI (SP Entity ID): `https://<xorlabDomain>/auth/saml2/service-provider-metadata/<saml2BackendName>`
* The SAML response needs to be signed
* The SAML assertion needs to be signed

<Note>
  **Authentication request signing is now supported**

  If your IdP requires authentication request signing, this optional feature is supported in xorlab. For more information, please refer to [Authentication request signing](/latest/authentication-saml-request-signing).
</Note>

In addition, the SAML assertion must have attributes to transport the:

* username (required; a list of one element)
* roles (required; a list of many elements)
* display name (optional; a list of one element)
* emails (optional; a list of many elements)
* `nameID` claim (required)

Mapping these assertion attributes to xorlab user attributes can be specified in the configuration.

<Note>
  Before you start configuring this backend in xorlab, please read the [Authentication](/latest/authentication-overview) article, if you haven’t already.
</Note>

## xorlab configuration

The configuration on the xorlab side is in the `auth.yml` file under the `saml2AuthBackends:` section. It is important that you use the same name for the SAML backend within xorlab as it is named on the identity provider side.

Also, the identity provider needs to provide the metadata for the application configuration either via an URL or in a file.

### Basic configuration

All basic settings are configured under the `idp:` subsection of the SAML backend section—in the example below we used `mySamlProvider` as the backend name:

```yaml auth.yml theme={null}
saml2AuthBackends:
  mySamlProvider:
    idp:
      metadataFile: example-saml-provider-metadata.xml
      # metadataUrl: https://example-idp.com/metadata
```

If the IdP (Relying Party) metadata is stored in a file, specify its location and name as a value for the `metadataFile` attribute. Otherwise, point to this metadata available over a HTTP(S) endpoint by providing its URL address as a value for the `metadataUrl` attribute. Note that only one metadata location can be specified so, in the above example, the `metadataUrl` key is commented out and xorlab will use the metadata file.

### Attribute mapping

In the next step, you have to map (assign) attributes from the SAML assertion to the user model in xorlab. The mapping is described using [Spring expression language](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html) and is configured under the `attributeMapping:` subsection.

You can use these methods:

* `attr('<name>')`: retrieve the attribute with the `'<name>'` name from attributes in the source authorization system.
* `replace(<string or list of strings>, '<pattern>', 'replace')`: replace every occurrence of `'<pattern>'` with `'replace'` in an input string or a list of input strings.
* `azureAdEmails()`: read all email addresses from the Azure Active Directory `proxyAddresses` attribute.

Literal values have to be quoted, e.g., `key: 'literal value'`.

A sample configuration for attribute mapping which simply retrieves attributes from the auth system (Entra ID in this case) would look like this:

```yaml auth.yml theme={null}
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
```

Available attributes are explained in the table below:

| Attribute | Description |
| :- | :- |
| `userName` | An attribute mapping for the username. The result of this mapping will be put into the `subject` attribute of the token issued to the consuming services<br />**Note:** The default is to use the assertion subject as a username. If you want to change this behavior, then specify a mapping for the username. However, in most setups, this should not be the case |
| `displayName` | An attribute mapping for the display name of the user. It is optional and could be used by consuming services in places where a more descriptive name of the user is appreciated |
| `emails` | Mapping for the list of emails associated with the user. Consuming services might use this list to associate the user with a certain pool of email messages |
| `roles` | Mapping for the list of roles assigned to the user. This mapping can only be set for authentication backends which do not do their own authorization |
| `tenant` | **Only required for multi-tenancy deployments**: Make sure the value of the `tenant` attribute correspond to the `name` defined in the `guarded_tenants.yml`. |

### Role mapping

The last step is to configure role mapping. You must map all roles served by the SAML identity provider to the corresponding xorlab roles under the `roleMapping:` subsection. Roles that are not mapped are ignored by default. Multiple xorlab roles can be mapped to the same identity provider role, e.g., `xcc_login` → `company1-group1`, `xcc_admin` → `company1-group1`.

If the SAML identity provider already serves roles compatible with xorlab (see [*Built-in Roles*](/latest/built-in-user-roles)), you can also specify a “pass-through” role-mapping mode using `roleMappingMode: PASS_THROUGH`.

<Note>
  Please be aware that in the pass-through role-mapping mode, all roles served by the SAML identity provider are added to the xorlab authorization context. If this context is becoming too large, i.e., too many irrelevant roles are added, then it might lead to errors and users being unable to access XCC. Therefore, it is advisable to only map the roles that are relevant to xorlab.
</Note>

A sample role mapping configuration is shown below:

```yaml auth.yml theme={null}
    roleMapping:
      xcc_admin:
      - xcc_admin
      xcc_monitor:
      - xcc_monitor
      xcc_insights:
      - xcc_insights
      xcc_quarantine_user:
      - xcc_quarantine_user
```

A sample role mapping configuration using the pass-through mode:

```yaml auth.yml theme={null}
    roleMappingMode: PASS_THROUGH
    roleMapping:
      # You can still define a role mapping in pass-through mode
      xcc_monitor: [ xcc_admin ]
```

### Activate the configuration

After updating `auth/auth/auth.yml`, click **Publish**. The authentication configuration becomes active within about one minute.

### Multi-Tenancy

The setup on this page applies unchanged in a multi-tenant deployment. Two things are added on top: a `tenant` entry in the [Attribute mapping](#attribute-mapping) that matches the tenant `name` in `guarded_tenants.yml`, and a [tenant-restricted user role](/latest/built-in-user-roles) in the [Role mapping](#role-mapping).

<Card title="Enable Tenant Login" icon="building" href="/latest/multi-tenancy-authentication#saml-login">
  Complete per-tenant SAML example, and the other login options available to tenants.
</Card>

### Example configuration

The final configuration for a SAML backend—Azure in this example—should look like this:

```yaml auth.yml theme={null}
tokenSigningKey: "xyz"

enabledAuthBackends:
  - azureSaml

saml2AuthBackends:
  azureSaml:
    idp:
      metadataUrl: https://login.microsoftonline.com/<tenant_id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app_id>
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
    roleMapping:
      xcc_admin:
      - xcc_admin
      xcc_monitor:
      - xcc_monitor
      xcc_insights:
      - xcc_insights
      xcc_quarantine_user:
      - xcc_quarantine_user
```

<Note>
  **Shared mailboxes and aliases**

  The configuration from the above example will not support shared mailboxes or aliases obtained with the `proxyAddresses` attribute.
</Note>


# Enable Request Signing for SAML
Source: https://docs.xorlab.com/latest/authentication-saml-request-signing

Sign SAML authentication requests with a key store when your identity provider requires it.

This optional feature requires creating a key store containing the certificate of a custom certificate authority and a private key that is used to sign the authentication request.

1. Run this command in your shell to create a `keystore.p12` key store file using the certificate in the `certificate.crt` file and a corresponding private key in the `privateKey.key` file:

   ```shell theme={null}
   openssl pkcs12 -export -in certificate.crt -inkey privateKey.key -out keystore.p12
   ```

   After entering the command, you will be prompted to enter and verify an export password to protect the key store file. Remember this password as you will need it in step #6.

2. Switch to the CLI of the XCC and execute the following instructions one by one:

   ```shell theme={null}
   sudo su -s /bin/bash xcc_backend
   cd /var/lib/xorlab/xcc/config/work/ag_local/auth/auth
   ```

3. Copy the `keystore.p12` file into the folder specified above.

4. Execute the following instructions one by one:

   ```shell theme={null}
   git add .
   git commit -m "Adding keystore file"
   exit
   ```

5. Open the `auth/auth/auth.yml` file using the XCC [Expert Editor](/latest/expert-editor).

6. In the `saml2AuthBackends` section, under your IdP config (here as `mySaml`), add the following block and enter your key store password as the `password` parameter:

   ```yaml auth.yml theme={null}
   saml2AuthBackends:
     mySaml:
       idp:
         signingKeyStore:
           file: keystore.p12
           password: the-key-store-password
   ```

7. Click **Publish**. The authentication configuration becomes active within about one minute.

The Authentication service restarts automatically and applies the new configuration.


# Enable Login via Password File
Source: https://docs.xorlab.com/latest/authentication-with-a-password-file

Define local xorlab users in a static password file, with password and account recommendations.

To get an overview over all available login mechanisms, have a look at [Authentication](/latest/authentication-overview).

When using local users, we recommend to:

* Use secure passwords or passphrases. Make them unique, random, and long; preferably create them in a password generator of your favorite password manager.
* Don't share accounts.
* Enable 2FA.

## Quickstart

1. In the [Expert Editor](/latest/expert-editor), open `auth.yml` in `auth/auth/`. Make sure the following configuration is present. Normally it is pre-configured. Rename `examplePassword` to a more meaningful name.

   ```yaml auth.yml theme={null}
   enabledAuthBackends:
     - examplePassword

   usernamePasswordAuthBackends:
     examplePassword:
   ```

2. Open `passwordFile.yml` in the same folder and add the local users. Below you find the available attributes that you can configure. We recommend to always require 2FA via `totpRequired`.

```yaml passwordFile.yml theme={null}
  users:
  - username: admin
      tenant: customerA
      displayName: The Admin
      passwordHash: "<ADD PWD HASH HERE>"
      emails: ["email1@example.com", "email2@example.com"]
      totpRequired: true
      roles:
      - xcc_admin
  - username: user1
      tenant: customerA
      passwordHash: "{bcrypt}$2y$10$.4If2RFwcvHRrxlR98m9ju/mCRYCHLAYULByGXvJY.jBuK2/bckZu"
      totpRequired: true
      roles:
      - xcc_analyst
```

3. Click **Publish**. The users become available within about one minute.

The following `users` attributes are available:

| Attribute | Value |
| :- | :- |
| `username` | Unique user name |
| `tenant` | The `tenant` attribute should reference `name`, defined in `guarded_tenants.yml` |
| `displayName` | More descriptive user name |
| `passwordHash` | Hash value of a password (see [Password hash generator](#password-hash-generator) below) |
| `emails` | List of emails associated with the user |
| `roles` | Role in AG assigned to the user |
| `totpRequired` | Optional flag. If set to `true`, the user must complete TOTP onboarding at the next login |
| `totpSeedBase32` | Base32-encoded TOTP seed that will be set automatically be xorlab after the user completes the TOTP onboarding |

## 2FA/MFA onboarding

Password file users can be forced to set up TOTP during their next login by adding `totpRequired: true` to the user entry in `passwordFile.yml`.

```yaml passwordFile.yml {5} theme={null}
users:
  - username: adminMfa
    # password: test
    passwordHash: "{bcrypt}$2a$10$HVcQJ4zCw1B0AKPz2Mx8FO4HjtbP46FZNaVJDsosYrMeZXTHTs5ti"
    totpRequired: true
    roles:
      - xcc_admin
      - xcc_insights
      - xcc_monitor
```

Afterward, click **Publish**. The authentication configuration becomes active within about one minute, and the user will then be forced into a TOTP onboarding flow during the next login.

<img alt="2FA Login" />

If the onboarding is successful, the following changes will be automatically made by xorlab:

* `totpSeedBase32` is stored on the user object
* `totpRequired` is removed again (in this way, a new TOTP onboarding can be triggered by setting it to true again)

After onboarding, the user must provide a valid TOTP code when logging in.

<Accordion title="`totpSeedBase32`">
  By default, xorlab generates the seed automatically and updates the `passwordFile.yml`. However, if necessary, you can manually set the seed yourself. One can be created with `openssl rand 20 | base32`.
</Accordion>

## Password hash generator

1. Run the `docker exec -it auth_auth create_hash` command on the **XCC** terminal to generate a password hash from the password you enter and re-type when prompted. You should get the output similar to the one below:
   ```shell theme={null}
   $ docker exec -it auth_auth create_hash
   ActiveGuard password hash generator
   Password to hash: 1234
   Hashed password:
   {bcrypt}$2a$10$YOmSE8jp9fSBlVP3P3KEh.UnezedRVSnBZL7x5xWQvYfiBF0z49Uy
   ```
2. Copy the generated hash, open Expert Editor and paste it into `auth/auth/passwordFile.yml` as a value for the `passwordHash` key of a particular user.
3. Once you finish adding password hashes for all users, click **Publish**. After about one minute, the changes are hot-reloaded and active.

In case you don't have access to the XCC terminal, run `htpasswd -nBC 10 ignore | sed 's/ignore:/{bcrypt}/'` on a Linux terminal to generate a password hash as alternative to step 1 above.

## Enable Logging

With this authorization method, it's good to know whether there were any unsuccessful login attempts. You can use the logging system for that:

1. Follow the instructions for logging [audit trail events](/latest/logging-events#audit-trail-events) to create a log for the `audit.access.denied` event.

2. Your `auth/auth/logback-audit.xml` config file should look like the one below:

   ```xml theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <included>
    <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
      <syslogHost>syslog.example.com</syslogHost>
      <port>514</port>
      <protocol>UDP</protocol>
      <facility>LOCAL0</facility>
      <encoder>
      <pattern>%jsonMsg%n</pattern>
      </encoder>
    </appender>

    <!-- Log all unsuccessful login attempts -->
    <logger name="audit.access.denied">
      <appender-ref ref="syslogAppender"/>
    </logger>
   </included>
   ```

If you want to log all login attempts, both unsuccessful and successful, just change the `logger name` value to `"audit.access"`.

## Multi-Tenancy

The setup on this page applies unchanged in a multi-tenant deployment. Two things are added on top: a `tenant` entry per user that matches the tenant `name` in `guarded_tenants.yml`, and a [tenant-restricted user role](/latest/built-in-user-roles) in `roles`.

<Card title="Enable Tenant Login" icon="building" href="/latest/multi-tenancy-authentication#password-file-login">
  Complete per-tenant password file example, and the other login options available to tenants.
</Card>


# Before You Begin
Source: https://docs.xorlab.com/latest/before-begin-integration

Complete before any integration: configure guarded domains, set data retention, and choose inline or monitoring mode.

## Configure your guarded domains

Open the Expert Editor and add all domains that should be protected by xorlab to `shared/guarded_tenants.yml`.

```yaml shared/guarded_tenants.yml theme={null}
tenants:
- name: xorlab
  # Add all domains that should be protected
  domains:
  - xorlab.com
  - "**.xorlab.com" # To include subdomains; note the required quotes
```

## Define data retention

Review the default data retention parameters below. If you want to change a parameter, specify it in the same file `shared/guarded_tenants.yml`. Otherwise, no action is required.

<Note>
  **SaaS**

  For xorlab SaaS, these values are managed by xorlab. Please contact [support@xorlab.com](mailto:support@xorlab.com) if you want to change it.
</Note>

```yaml shared/guarded_tenants.yml theme={null}
tenants:
- name: xorlab
  ## Default data retention
  dataRetention:
    ## Duration after which benign mails are deleted.
    deliveredTtlDays: 90
    ## Duration after which reported messages are deleted.
    reportedTtlDays: 730
    ## Duration after which quarantind emails are deleted.
    quarantinedDefaultTtlDays: 30
```

For all available retention and storage configurations, see [Data Retention Overview](/latest/data-retention-overview).

When you finish editing `shared/guarded_tenants.yml`, click **Publish**. The new configuration becomes active within about one minute.

## Choose between Inline and Monitoring mode

**Choose and configure either of those two modes.** This choice will also be required later in the setup.

For new xorlab instances, the mode is normally already preconfigured.

<CardGroup>
  <Card title="Inline" icon="shield" href="/latest/before-begin-integration#configure-inline-mode">
    Active protection. Emails pass through xorlab and are forwarded to the next system. This mode is required for productive integrations. Supports *toothless* operation.
  </Card>

  <Card title="Monitoring" icon="envelope-open-text" href="/latest/before-begin-integration#configure-monitoring-mode">
    xorlab receives only a copy of every email, and discards it after processing. This mode is used for temporary evaluations.
  </Card>
</CardGroup>

### Configure Inline mode

For more information and explanations, see [Inline and Monitoring Mode](/latest/inline-and-monitoring-mode).

1. In `activeguard/core/active_guard.yml`, configure the SMTP handlers and the sender/recipient extraction settings:
   ```yaml active_guard.yml theme={null}
   scanSources:
     smtp:
       port: 10025
       handler:
       # Inline mode - filter and forward processed emails
         smtpInline: {}
         smtpReport: {}
   ```
2. Open `activeguard/mta/startup_cfg/postfix_custom/master.cf` and set the following lines to `bounce`.
   ```ini master.cf theme={null}
   # Enable all delivery status notifications
   bounce    unix  -       -       n       -       0       bounce
   defer     unix  -       -       n       -       0       bounce
   trace     unix  -       -       n       -       0       bounce
   ```
3. Open `activeguard/mta/startup_cfg/postfix_custom/main.cf` and configure it like this.
   ```ini main.cf highlight={2-3,6} theme={null}
   # Enable delay warnings
   delay_warning_time = 1h
   confirm_delay_cleared = yes
   # Ativate DSNs
   smtpd_discard_ehlo_keywords = silent-discard
   ```
4. **Optional:** Enable *toothless* mode during learning phase. This will force xorlab to deliver all emails, even malicious ones.
   <Accordion title="Toothless mode">
     In toothless mode, xorlab will not take any actions on emails and always deliver them. This is only used for the first few weeks to avoid false positives during the learning phase. Afterward, this profile needs to be removed again. In toothless mode, you can search for `#quarantine` to find the emails that xorlab would have quarantined.
   </Accordion>
   ```yaml guarded_tenants.yml theme={null}
   tenants:
   - name: xorlab
     ruleProfiles:
     - default_dana.properties
     - default_actions.properties
     # Add this line to enable toothless mode
     - no_subject_rewrite_no_quarantine.properties
   ```
5. Click **Publish**. The new configuration becomes active within about one minute.

### Configure Monitoring mode

For more information and explanations, see [Inline and Monitoring Mode](/latest/inline-and-monitoring-mode).

1. In `activeguard/core/active_guard.yml`, configure the SMTP handlers and the sender/recipient extraction settings:

   ```yaml active_guard.yml theme={null}
   scanSources:
     smtp:
       port: 10025
       handler:
       # Activate Monitoring mode - all emails will be dropped after processing.
         smtpOffline:
           senderRecipientExtraction:
             # Get the recipients from the TO and CC headers
             recipientExtraction: MAIL_HEADER
             # Get the envelope sender from email headers
             senderExtraction: HEADER
         smtpReport: {}
   ```

   <Warning>
     For M365 integrations, set `senderRecipientExtraction.senderExtraction` to `MAIL_ENVELOPE` instead of `HEADER`.
   </Warning>

2. Open `activeguard/mta/startup_cfg/postfix_custom/master.cf` and set the following lines to `discard`.
   ```ini master.cf theme={null}
   # Disable all delivery status notifications
   bounce    unix  -       -       n       -       0       discard
   defer     unix  -       -       n       -       0       discard
   trace     unix  -       -       n       -       0       discard
   ```

3. Open `activeguard/mta/startup_cfg/postfix_custom/main.cf` and configure it like this.
   ```ini main.cf highlight={2-3,6} theme={null}
   # Comment out the following two lines. This will deactivate delay notifications.
   #delay_warning_time = 1h
   #confirm_delay_cleared = yes
   # Disable Delivery Status Notification (DSN) extension
   smtpd_discard_ehlo_keywords = silent-discard, dsn
   ```

4. Click **Publish**. The new configuration becomes active within about one minute.


# Blacklists
Source: https://docs.xorlab.com/latest/blacklists

Block email delivery by sender address, domain, IP, or other indicators, including how subdomain matching behaves.

Blacklists are accessible by selecting **Settings → Lists → Blacklists** in XCC.

<Warning>
  **Subdomains**

  When you add a root (top-level) domain, e.g., `example.com`, to the list, all its subdomains will also be blacklisted. When you add a particular subdomain, e.g., `site.example.com`, only this subdomain will be blocked; any lower-level ones such as `other.site.example.com` won’t be affected.
</Warning>

## Blocked senders

Customize any of the lists below to block emails from individuals, organizations, or top-level domains.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Sender TLD blacklist** | Use this list to block emails from entire top-level domains | TLD as `String`, e.g., `cloud` |
| **Sender domain blacklist** | Use this list to block emails from certain domains | Domain name as `String` |
| **Sender address blacklist** | Use this list to block emails from certain sender addresses | Email address as `String` |
| **Exposed accounts local sender domains** | Use this list to protect your exposed accounts from receiving emails from certain domains | Domain name as `String` |

## Blocked links

Customize any of the lists below to block emails that contain links matching specific criteria.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Link domain blacklist** | Use this list to block emails that contain a link from certain domains (or root domains) by the domain name | Domain name as `String` |
| **Link IP blacklist** | Use this list to block emails that contain a link from certain domains (or root domains) by the domain IP | Domain IP as `String` |

## Blocked files

Customize any of the lists below to block emails that contain files matching specific criteria.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **File extension blacklist (regex)** | Use this list to block emails that contain files with certain extensions | File extension as `Regex`, e.g., `(?i)\.bat$` for case-insensitive matches. |
| **File hash blacklist** | Use this list to block emails that contain files matching certain SHA256 hash values | Hash value as `String`, e.g., `9db4 4391 dbfa 43bc 9b13 4440 00f6 9c77 a395 95c9 bac5 710e 0a78 a638 60b0 69a2` |
| **File output blacklist (regex)** | Use this list to block emails that contain files for which the `file` command matches certain patterns | Pattern as `Regex`, e.g., `Java archive data` |

## Blocked recipients

These are only usable with the `DROP_recipient_address_droplist` rule enabled.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Recipient address droplist** | All incoming emails to these recipient addresses will be dropped immediately, except when there is another guarded recipient not listed here. | Email address as `String`, e.g., `formeremployee@company.com` |


# List of Built-in Roles
Source: https://docs.xorlab.com/latest/built-in-user-roles

Reference table of the built-in xorlab roles and the capabilities each one grants.

To create a new custom role, see [Create a Custom Role](/latest/create-custom-user-role).

| xorlab role | Identifier | Capabilities |
| - | - | - |
| User | `xcc_analyst` | - Release emails from quarantine<br />- Reanalyze/Unlock emails<br />- Send feedback for reported incidents<br />- Submit misclassification reports<br />- Create, delete, or modify search queries and campaigns<br />- Update custom tags for messages, reported incidents, and uploaded files<br />- Upload a file for analysis |
| User (Tenant-Restricted) | `xcc_tenant_analyst` | This user can only access resources on their own tenant and can:<br />- Release emails from quarantine<br />- Reanalyze/Unlock emails<br />- Send feedback for reported incidents<br />- Submit misclassification reports<br />- View campaigns and saved searches (no modifications)<br />- Update custom tags for messages, reported incidents, and uploaded files<br />- Upload a file for analysis |
| Auditing User | `xcc_analyst_audit` | - View messages, reported cases, and analyzed files<br />- View campaigns and saved searches<br />- View the custom tags of messages<br />- View items from black- and whitelists in the web interface<br />- View configuration lists in Expert Editor |
| Auditing User (Tenant-Restricted) | `xcc_tenant_analyst_audit` | This user can only access resources on their own tenant and can: <br />- View messages, reported cases, and analyzed files<br />- View campaigns and saved searches<br />- View the custom tags of messages<br />- View items from black- and whitelists in the web interface<br />- View configuration lists in Expert Editor |
| Admin | `xcc_admin` | - Isolate messages from user mailboxes<br />- Modify black- and whitelists in the web interface<br />- Edit configuration lists in Expert Editor<br />- Start a new backup and check the status of the running process<br />- Edit system configurations<br />- Other power user capabilities |
| Auditing Admin | `xcc_admin_audit` | - Everything that an `Auditing User` can view<br />- View system configurations and backup status |
| Self-Service Quarantine User | `xcc_quarantine_user` | - Authenticate and log in via the web interface<br />- Change basic settings such as white/black theme<br />- View emails in the `Malware`, `Extortion`, `Policy` and `Impersonation` quarantine<br />- View and release emails from the `Phishing` and `Spam` quarantine. |
| Insights User | `xcc_insights` | Access to the statistics dashboards in the **Insights** section |
| Monitoring User | `xcc_monitor` | Access to `/monitoring` (Grafana) |

## Multi-Tenancy

The two tenant-restricted roles, `xcc_tenant_analyst` and `xcc_tenant_analyst_audit`, exist for multi-tenant deployments. A user with one of these roles only sees the resources of the tenant they are assigned to.

The tenant assignment does not come from the role itself: it comes from the `tenant` attribute your authentication backend maps for the user, which must match the `name` of a tenant in `guarded_tenants.yml`. See [Enable Tenant Login](/latest/multi-tenancy-authentication) for the mapping in SAML, LDAP and password file backends.


# Using Campaigns
Source: https://docs.xorlab.com/latest/campaigns

Turn a search query into a standing rule, so analysts can close a detection gap without editing configuration files.

Campaigns enable analysts to adjust the built-in detection. They allow the creation of new security policies in response to undetected threats or recurring false positives.

## Create a campaign

### 1. Search

Every campaign starts with a search query in the All Messages view. Use the predefined search filters to specify email attributes, or write your own query directly in the search bar. For a syntax description of the search functionality, checkout [Search](/latest/search).

<img alt="Search functionality in All Messages" />

The table below lists useful search parameters that can be used to define a campaign. Keep in mind that campaigns cannot include attributes related to verdicts or actions.

| Search | Example |
| :- | :- |
| `From`, `To`, `CC` email address and display name<br />Envelope `from` and envelope recipient email address. | `from:search@xorlab.com`, `from.displayname:search`, `envfrom:search@xorlab.com`, `sender:search@xorlab.com`, `recipient:search@xorlab.com`, `involves:search@xorlab.com`<br />Supports wildcards |
| Tags (note that the `#quarantine` and `#subjectrewrite` tags can’t be used in campaigns) | `#untrusted #newdomain` |
| Domains in the email (incl. sender domains as well as URL domains in the email body) | `domain:test.xorlab.com`<br />Supports wildcards |
| Attachment name and hash | `file.name:text.exe`, `file.hash:abcdefg`<br />Supports wildcards |
| Spam score | `spam:gt:4` |
| Rspamd score | `rsd:gt:2` |
| Subject | `subject:"hi there"`<br />Supports wildcards |
| Content similarity | N/A<br />The similarity search query is automatically generated in the similarity detail view |
| Links URL and display text | `link:"https://www.test.com"`, `link.displaytext:"click here!"`<br />Supports wildcards |
| Headers | `header.name:x-xor-example`, `header.value:abcdefg`, `header:{ name:x-xor-example value:abcdefg }`<br />Supports wildcards |

### 2. Evaluate

After entering your search query, carefully review the results it returns. Because campaigns override all default detection rules, it’s crucial to design a query that matches only the intended emails — no more, no less.

[Tags](/latest/tags) are a powerful way to narrow the campaign’s scope. Start by examining two or three emails that should match your campaign and identify which tags they have in common. Add these tags to your search query to make it more precise. For example, adding `#auth` ensures that the campaign only applies to senders that can be authenticated by SPF or DKIM.

You can also use a NOT clause to exclude certain emails based on missing attributes. For example, adding `NOT #file` ensures the campaign doesn’t apply to emails that contain attachments.

<Note>
  Press Enter after modifying your search query to refresh the results.
</Note>

### 3. Create

Once you are satisfied with your search query, click the campaign icon on the right side of the search bar to create a campaign.

If the icon is not clickable, the current search query includes one or more attributes that are not compatible with campaigns. Review your query and remove unsupported fields before proceeding.

<img alt="Save the campaign" />

### 4. Save

A pop-up window appears that lets you turn your search query into an active campaign. In addition to adding a name and short description, review the following fields carefully:

* **Message Action**: Determines what xorlab should do with incoming, outgoing or internal emails that match the campaign query - quarantine, deliver, or none?
  * **Quarantine** - Assign a verdict and specify the quarantine where matching emails should be placed.
  * **Deliver** -  Assign a verdict and optionally deliver the email with a rewritten subject.
  * **None** - Use this option if you want the campaign to only match reported emails with a **Resolve Action**.
* **Resolve Action**: Controls how reported emails that match the campaign query are automatically resolved. See [Abuse Mailbox](/latest/abuse-mailbox) for examples.
  * **Benign** – Select for legitimate, safe emails. You can specify which feedback message is sent to the reporting employee.
  * **Malicious** – Select for emails that should not have been delivered. You can also specify the feedback message sent to the reporter.
  * **None** – Select if you do not want the campaign query to automatically resolve reported emails.

<img alt="Define campaign actions" />

### 5. Review

Click the campaign icon in the left menu bar to open the Campaign Overview. This view lists all active campaigns and shows how many emails have matched each campaign — both in total and today.

Use these statistics to verify that your campaign works as intended. If you notice an unexpectedly high number of matches, review the campaign query and adjust its filters or tags to narrow the scope.

<img alt="Overview of campaigns" />

## Modify a campaign

From the Campaign Overview (see image above), click on a campaign to open its details page. Here, you can review the campaign’s query, search attributes, and the list of all emails that matched the campaign.

<img alt="Edit an existing campaign" />

**How to edit a campaign:**

* Modify the search query or filters
* Press **Enter** to refresh the search results
* Press on the three dots on the right
* Select **Edit** from the menu
* Make sure **Update with the current search** is checked
* Click **Save**

<Note>
  Press **Enter** after changing the search query and before opening the edit menu, otherwise the updated results won’t be applied.
</Note>

## Campaign examples

### Blocking greymail

* CFO Anthony Kovacs reports receiving a high volume of unwanted marketing and newsletter emails
* Goal is to reduce inbox noise by quarantining messages that match greymail characteristics

**Campaign Query:**

```sql theme={null}
to:anthony.kovacs@futuretek-inc.com 
#domainonlyinbound #inc #untrusted (#crm or #marketing or #newsletter) 
not(#reputable or #senderwhitelisted or #attachedinvoice or #phishing or #malware or #vipfraud or #extortion or #impersonation)
```

### Unauthenticated alerts

* Technical systems send alert emails to the operations team when a critical threshold is reached
* These alerts lack SPF and DKIM authentication, and the sender display name contains the company name
* Default policies quarantine the messages as impersonation
* Whitelisting the entire sending domain would pose a security risk

**Campaign Query:**

```sql theme={null}
from:alert@exmample.com 
from.displayname:"Futuretek-inc" 
to:operations@futuretek-inc.com 
subject:"Critical Alert" 
url:"https://monitoring.futuretek-inc.com/details?id=*" 
```

### Deliver reply-to's

* The accounting team uses a third-party billing platform (billing-system.io) to send invoices
* The platform routes customer replies to `accounting@futuretek-inc.com` using the header `X-Billing-System: invoice-reply`
* These replies are often quarantined because xorlab sees no prior relationship with the sender
* Goal is to deliver legitimate invoice replies while still scanning them for malware and static policy violations

**Campaign Query:**

```sql theme={null}
to:accounting@futuretek-inc.com 
#auth 
header:{name:"X-Billing-System" AND value:"invoice-reply"} 
not(#malware or #policy)
```


# Local Reputation
Source: https://docs.xorlab.com/latest/concepts-local-reputation

How xorlab learns which domains, file types, and content are normal for your organization, and uses that to spot anomalies.

**Local Reputation** is the indicator this produces, and it helps distinguish relevant emails from potentially malicious ones.

<Note>
  **Key Takeaways**

  * Use the local reputation to assess the relevance of certain domains and file types in your organization.
  * The detection engine filters content without local reputation more aggressively.
  * The local reputation is built up continuously, and shown for domains and file types. The local reputation for additional objects like root domains, top-level domains, file extensions, etc. can be queried via custom rules.
  * The local reputation decays over time if the corresponding content is not seen anymore.
  * The local reputation is only built up based on legitimate traffic with a high [Relationship](/latest/concepts-relationship).
</Note>

The local reputation is specific to your organization. It is distinct from the **Global Reputation** provided by xorlab, which is identical across all xorlab customers and reflects a global relevance scoring.

## Learning phase

As with the [Relationship](/latest/concepts-relationship), the local reputation system relies on the initial learning phase to build up the reputation values. During this time, the values are expected to be inaccurate. Afterward, it stabilizes but the system keeps updating the local reputation values based on the email traffic it sees.

## Understanding reputation values

The local reputation is a value between 0 and 100. 0 means it has not yet been seen in emails with a high relationship. The local reputation is a strong indicator to distinguish legitimate links from malicious ones, as it is difficult for an attacker to obtain local reputation for a domain.

xorlab exposes the local reputation for the following objects. All can be found in the detail view:

<CardGroup>
  <Card title="URL Domain">
    <img alt="URL Domain" />
  </Card>

  <Card title="File Type">
    <img alt="File Type" />
  </Card>

  <Card title="Sender Domain">
    <img alt="Sender Domain" />
  </Card>
</CardGroup>

Subdomains normally inherit the local reputation of the root domain.

<Note>
  **Reputation and Relationship**

  It is possible (but rare) that a sender domain has local reputation, but no [Relationship](/latest/concepts-relationship). This happens when your organization did not exchange emails with that domain itself, but the domain was mentioned in communication with another domain that has a relationship. In such a case, the local reputation weights similarly strong as a normal relationship value.
</Note>

### Special cases

There are some special cases where the local reputation behaves differently:

* Domains from **Subdomain-Providers** do not inherit the local reputation of the root domain.
* The local reputation is not used for domains from **Cloudstorage-Providers**. While it is shown in the platform, the detection engine does not use it as indicator.

In general, all cases are exempted from local reputation where an attacker could easily obtain access to that domain.

### Using reputation tags

To search and filter emails based on local reputation, you can use these built-in tags:

| Tag | Description |
| :- | :- |
| `#nolocalreputation` | Email contains a link with a domain with no local reputation |
| `#tldnoreputation` | Email contains a top-level domain with no local reputation |
| `#filetypenoreputation` | Email contains a file type with no local reputation |
| `#nonreputable` | Sender domain has no local reputation |

For more tags about reputation, have a look at [Tags](/latest/tags).


# Concepts Overview
Source: https://docs.xorlab.com/latest/concepts-overview

The core detection concepts behind xorlab's proactive model. Read these before the hands-on analyst guides.

<Card title="Relationship" icon="hexagon-nodes" href="/latest/concepts-relationship">
  Learning who communicates with whom.
</Card>

<Card title="Local Reputation" icon="file-check" href="/latest/concepts-local-reputation">
  Understanding what kind of content is exchanged in legitimate communications.
</Card>

<Card title="Sender Authentication" icon="user-check" href="/latest/concepts-sender-auth">
  Verifying the authenticity of email senders.
</Card>


# Relationship
Source: https://docs.xorlab.com/latest/concepts-relationship

The relationship (trust) model of who communicates with whom in your organization, built and maintained automatically.

The relationship is a key indicator for the detection engine.

<Note>
  **Key Takeaways**

  * Use the relationship to assess how frequently your organization communicates with a sender.
  * The relationship is learned on domains and mailboxes separately. The more back and forth emails are seen, the higher its value. It will decay over time if no communication is seen.
  * The detection engine filters emails with a lower relationship more aggressively.
  * In xorlab, instead of whitelisting a sender, you can manually increase its relationship to make the detection more permissive.
  * Relationship requires a successful authentication of the sender.
</Note>

## Learning phase

The relationship model needs an initial learning phase before it is ready to be used. Normally, detection is disabled during learning phase (*Toothless* mode, in which xorlab delivers all emails and only records the actions it would have taken) and manually enabled afterward.

It is possible to enable partial protection already during learning phase. If this is required, contact [support@xorlab.com](mailto:support@xorlab.com).

To get an indication of the learning, have a look at the *Business Relevant* percentage in the dashboard.

<Info>
  The duration of the learning phase and the expected *Business Relevant* range are documented in
  [Detection Defaults → Learning phase](/latest/detection-defaults#learning-phase). Access to that page is restricted.
</Info>

<img alt="Business Relevant" />

The relationship model is designed such that it is not affected by special cases like out-of-office messages, subdomain providers, freemail providers, etc.

## Understanding relationship values

A relationship value is between 0 and 100. 0 means there was no back and forth communication yet. Each email is assigned three values:

* **Personal**: Relationship between sender and recipient mailbox
* **Person - Organization**: Relationship between sender mailbox and recipient domain
* **Organization**: Relationship between sender domain and recipient domain

The overall relationship of an email is the maximum of those three. However, the detection engine may use these values individually. For example, it weights the Personal value higher than the Organization one.

The relationship value only increases if emails were seen in both directions.

<Note>
  **Relationship value and trust score**

  The relationship value is also referred to as the **trust score**. They are the same number, and the terms are used interchangeably across xorlab.

  In [Search](/latest/search#scores), it is the `trust` score: `trust:gte:15` matches every email whose relationship value is 15 or higher.
</Note>

<img alt="Relationship Overview" />

To see how much each side contributed to the current relationship, hover over one of the values to see the one-sided relationship:

<img alt="Relationship Details" />

## Using relationship tags

To search and filter for emails based on their relationship, you can use these built-in tags:

| Tag | Description |
| :- | :- |
| `#untrusted` | No or negligible relationship. Sender has not been seen or communicated with |
| `#lowtrusted` | Small back and forth communication seen |
| `#mediumtrusted` | Consistent back and forth communication seen |
| `#hightrusted` | Frequent back and forth communication seen |
| `#business` | The *Organization* relationship is at least `#lowtrusted` |
| `#partner` | The domains with the highest relationship |

<Note>
  **Detection**

  The biggest difference in detection happens between `#untrusted` and `#lowtrusted`. In general, xorlab allows only very little attack surface in `#untrusted` emails.
</Note>

The actual threshold values for the different tags are only indicative and subject to change; they are documented in [Detection Defaults → Relationship trust tiers](/latest/detection-defaults#relationship-trust-tiers) (password required). For more tags about relationship, have a look at [Tags](/latest/tags#relationship-tags).


# Sender Authentication
Source: https://docs.xorlab.com/latest/concepts-sender-auth

How xorlab authenticates email senders with SPF, DKIM, and DMARC, a prerequisite for building the relationship model.

Sender authentication is a mandatory requirement for using and building up [Relationship](/latest/concepts-relationship).

<Note>
  **Key Takeaways**

  * xorlab relies on SPF, DKIM, DMARC and several built-in checks to verify the sender of an email.
  * xorlab treats the *Header From* address as email sender, not the *Envelope From*. An email is marked authentic only if the Header From is successfully authenticated.
  * More information about the sender authentication is found in the detail view.

  <Frame>
    <img alt="Sender Auth Overview" />
  </Frame>
</Note>

## Understanding authentication

Each email shows a summary of authentication checks in the **Authentication** box of the detail view. A checkmark next to the header from address indicates whether the email is considered authentic overall.

<img alt="Authentication of the sender" />

**Legend**

* **Blue** — Check passed
* **Red** — Check failed and flagged as suspicious
* **Gray** — Check unavailable (e.g., missing SPF/DKIM) or failed but not considered suspicious

Each check contributes to the email authentication in the following way:

| Check | Description | Authentication Impact | Colors |
| - | - | - | - |
| **SPF** | Validates the envelope from domain using SPF. | Authenticates the sender **only when combined with a valid DMARC check**. | **Blue** — SPF pass<br />**Gray** — Neutral or no SPF<br />**Red** — SPF fail or softfail |
| **DKIM** | Verifies all available DKIM signatures. | Authenticates the sender **only when combined with a valid DMARC check**. | **Blue** — At least one valid signature<br />**Gray** — No signature<br />**Red** — All signatures invalid |
| **DMARC** | Checks SPF and DKIM alignment. | A passing DMARC check authenticates the sender (requires SPF or DKIM success). | **Blue** — SPF aligned or DKIM aligned<br />**Gray** — Both SPF and DKIM unavailable<br />**Red** — All other cases |
| **Network** | Custom DNS checks (see details below). | A passing Network check authenticates the sender. | **Blue** — At least one check passed<br />**Gray** — No checks passed |

### SPF

SPF checks if the **envelope from** domain allows the sending server to send emails for it.

On its own, SPF doesn’t stop attackers from faking the **header from** address (the one which is seen in the inbox).

That’s why SPF only counts when it also passes **DMARC alignment** — meaning the envelope from and header from domains match. You can see both in the email detail view.

<img alt="Header from and envelope from" />

### DKIM

DKIM makes sure the email hasn’t been changed on the way by checking its digital signatures.

But an attacker could still create a fake email and sign it with their own DKIM key. That’s why DKIM only counts with **DMARC alignment** — the **signing domain** has to match the **header from** domain you see as the sender. You’ll find the signing domain in the `dkim-signature` header (`d=` value).

<img alt="Header from and envelope from" />

### DMARC

DMARC ties everything together. It works only if at least SPF or DKIM is valid, and makes sure they match the visible sender. Specifically:

* With SPF, the envelope from and header from must match
* With DKIM, the signing domain and header from must match

By default, xorlab uses relaxed alignment. That means the main domain has to match, but subdomains don’t need to.

### Network

The Network check consists of several individual checks. Passing any one of them is enough for the overall Network check to pass and to authenticate the sender.

Results are either **pass** or **neutral** — there is no negative outcome.

| Check | Description |
| - | - |
| **DNS MX check** | Passes if the sending IP is listed in the MX records of the sender domain. |
| **DNS check** | Passes if (1) the EHLO domain matches the sender domain, and (2) its A record matches the sending IP. |
| **Reverse DNS check** | Passes if (1) the PTR record of the sending IP matches the sender domain, and (2) its A record points back to the same IP. |
| **Header from SPF check** | Passes if the SPF check succeeds for the header from domain. |
| **Private IP check** | Passes if the sending IP is a private address. |

As with DMARC, xorlab only requires the root domains to match in these checks.

## Handling authentication issues

For instructions on how to handle common authentication issues, have a look at [Handling Authentication Issues](/latest/authentication-issues).


# Change Misclassification Reporting
Source: https://docs.xorlab.com/latest/configure-misclassification-reporting

Override the default misclassification reporting parameters in xcc.yml.

Configure the relevant parameters in the `xcc.yml` file using the Expert Editor. The values shown below are the defaults. You only need to override the parameters you want to modify, the others can be left out.

```yaml xcc.yml theme={null}
misclassificationSubmission:
  ## Global switch to turn the feature on/off.
  enabled: true
  ## Pre-selected values in the web interface
  uiPreselection:
    ## Pre-selected Privacy Profile. Choose one of the following options:
    ##   - SHARE_EVERYTHING
    ##   - SHARE_EVERYTHING_EXCEPT_RAW_EML
    ##   - DO_NOT_SHARE_SENSITIVE_INFORMATION
    privacyProfile: "SHARE_EVERYTHING"
    ## Pre-selected value of the Share Misclassification checkbox in the web interface
    shareMisclassification: true
```

## Disable misclassification reporting

To fully disable the misclassification reporting feature, add the following to `xcc.yml`:

```yaml xcc.yml theme={null}
misclassificationSubmission:
  enabled: false
```

## Turn off auto-selected misclassification checkbox

Per default, the "Report misclassification" checkbox is always selected. To turn the auto-selection off, add the following to `xcc.yml`:

```yaml xcc.yml theme={null}
misclassificationSubmission:
  uiPreselection:
    shareMisclassification: false
```

When you finish editing `xcc.yml`, click **Publish**. This setting is activated automatically within about one minute.


# Create a Custom Role
Source: https://docs.xorlab.com/latest/create-custom-user-role

Define a custom role from permissions and scopes when the built-in roles do not fit.

For the list of built-in roles, see [Built-in User Roles](/latest/built-in-user-roles).

xorlab defines the concepts of *Roles*, *Permissions* and *Scopes*:

* A *Permission* denotes a specific action bound to a specific *Scope*. Example: Releasing an email from the quarantine.
* A *Scope* limits a permission to a specific context. Example: Releasing an email is only allowed for a specific tenant.
* A *Role* is a set of *Scopes* with *Permissions*. If needed, *Roles* can be arbitrarily composed and assigned to users.

Only roles can be assigned to users.

## Create a new role

1. Open the file `xcc.yml` in the Expert Editor.

2. Add the name and permissions of the new role to `roleToPermissionMappings`. You can find all permissions below at [Permissions-role matrix](#permissions-role-matrix) or [Start from a built-in role](#start-from-a-built-in-role).

   ```yaml xcc.yml theme={null}
   roleToPermissionMappings:
   # We advise to use lower snake case for custom role names.
   # Notice, that you must not use built-in role names like xcc_admin, etc.
     custom_role1:
         # The set of granted permissions associated to the role
         - xcc_asset_fetch|tenant:primary
         - xcc_rule_list_fetch
     custom_role2:
         - xcc_analyst_portal|tenant:primary
   ```

**Hint:** You can query your current permissions as described [here](/latest/troubleshooting#how-to-view-the-current-permissions-of-a-user).

<Info>
  A custom role for SSQ users is not supported. It is required to use the built-in role `xcc_quarantine_user`. If you need to adjust the available permissions for your SSQ users, contact [support@xorlab.com](mailto:support@xorlab.com).
</Info>

## Start from a built-in role

Rather than assembling a role permission by permission, copy the full set of a built-in role and remove what you do not need. Each block below is the complete permission list of one built-in role, ready to paste into `roleToPermissionMappings`. Rename `my_custom_role` first — a custom role must not reuse a built-in role name.

<AccordionGroup>
  <Accordion title="xcc_admin" description="56 permissions">
    ```yaml xcc.yml theme={null}
    # Admin
    roleToPermissionMappings:
      my_custom_role:
          - config_service_read
          - config_service_write
          - xcc_analyst_portal
          - xcc_api_key_create
          - xcc_api_key_delete
          - xcc_api_key_fetch
          - xcc_asset_fetch
          - xcc_backup_info_fetch
          - xcc_backup_trigger
          - xcc_campaign_add
          - xcc_campaign_archive
          - xcc_campaign_fetch
          - xcc_campaign_remove
          - xcc_campaign_update
          - xcc_config_m365_credentials
          - xcc_core_result_delete
          - xcc_file_upload
          - xcc_incident_isolate
          - xcc_incident_resolve
          - xcc_login
          - xcc_mail_import_read
          - xcc_mail_import_update
          - xcc_quarantine_archive
          - xcc_quarantine_release
          - xcc_quarantine_release_request_create
          - xcc_quarantine_release_request_resolve
          - xcc_result_detail_dana_screenshots
          - xcc_result_detail_fetch
          - xcc_result_detail_preview
          - xcc_result_detail_unlock
          - xcc_result_list_fetch
          - xcc_result_query_check
          - xcc_result_report_log_add
          - xcc_result_report_log_fetch
          - xcc_rule_list_add
          - xcc_rule_list_fetch
          - xcc_rule_list_remove
          - xcc_rule_list_update
          - xcc_search_add
          - xcc_search_fetch
          - xcc_search_remove
          - xcc_search_update
          - xcc_share_misclassification
          - xcc_sidebar_file_upload
          - xcc_sidebar_messages
          - xcc_sidebar_quarantines
          - xcc_sidebar_reported
          - xcc_ssq_portal
          - xcc_topics_fetch
          - xcc_user_impersonate
          - xcc_user_settings_change_language
          - xcc_user_settings_change_quarantine_notification
          - xcc_user_settings_change_theme
          - xcc_user_tags_add
          - xcc_user_tags_fetch
          - xcc_user_tags_remove
    ```
  </Accordion>

  <Accordion title="xcc_admin_audit" description="24 permissions">
    ```yaml xcc.yml theme={null}
    # Admin audit
    roleToPermissionMappings:
      my_custom_role:
          - config_service_read
          - xcc_analyst_portal
          - xcc_asset_fetch
          - xcc_backup_info_fetch
          - xcc_campaign_fetch
          - xcc_login
          - xcc_result_detail_dana_screenshots
          - xcc_result_detail_fetch
          - xcc_result_detail_preview
          - xcc_result_list_fetch
          - xcc_result_query_check
          - xcc_result_report_log_fetch
          - xcc_rule_list_fetch
          - xcc_search_fetch
          - xcc_sidebar_file_upload
          - xcc_sidebar_messages
          - xcc_sidebar_quarantines
          - xcc_sidebar_reported
          - xcc_ssq_portal
          - xcc_topics_fetch
          - xcc_user_settings_change_language
          - xcc_user_settings_change_quarantine_notification
          - xcc_user_settings_change_theme
          - xcc_user_tags_fetch
    ```
  </Accordion>

  <Accordion title="xcc_analyst" description="45 permissions">
    ```yaml xcc.yml theme={null}
    # Analyst
    roleToPermissionMappings:
      my_custom_role:
          - xcc_analyst_portal
          - xcc_asset_fetch
          - xcc_campaign_add
          - xcc_campaign_archive
          - xcc_campaign_fetch
          - xcc_campaign_remove
          - xcc_campaign_update
          - xcc_file_upload
          - xcc_incident_isolate
          - xcc_incident_resolve
          - xcc_login
          - xcc_mail_import_read
          - xcc_quarantine_archive
          - xcc_quarantine_release
          - xcc_quarantine_release_request_create
          - xcc_quarantine_release_request_resolve
          - xcc_result_detail_dana_screenshots
          - xcc_result_detail_fetch
          - xcc_result_detail_preview
          - xcc_result_detail_unlock
          - xcc_result_list_fetch
          - xcc_result_query_check
          - xcc_result_report_log_add
          - xcc_result_report_log_fetch
          - xcc_rule_list_add
          - xcc_rule_list_fetch
          - xcc_rule_list_remove
          - xcc_rule_list_update
          - xcc_search_add
          - xcc_search_fetch
          - xcc_search_remove
          - xcc_search_update
          - xcc_share_misclassification
          - xcc_sidebar_file_upload
          - xcc_sidebar_messages
          - xcc_sidebar_quarantines
          - xcc_sidebar_reported
          - xcc_ssq_portal
          - xcc_topics_fetch
          - xcc_user_settings_change_language
          - xcc_user_settings_change_quarantine_notification
          - xcc_user_settings_change_theme
          - xcc_user_tags_add
          - xcc_user_tags_fetch
          - xcc_user_tags_remove
    ```
  </Accordion>

  <Accordion title="xcc_analyst_audit" description="22 permissions">
    ```yaml xcc.yml theme={null}
    # Analyst audit
    roleToPermissionMappings:
      my_custom_role:
          - xcc_analyst_portal
          - xcc_asset_fetch
          - xcc_campaign_fetch
          - xcc_login
          - xcc_result_detail_dana_screenshots
          - xcc_result_detail_fetch
          - xcc_result_detail_preview
          - xcc_result_list_fetch
          - xcc_result_query_check
          - xcc_result_report_log_fetch
          - xcc_rule_list_fetch
          - xcc_search_fetch
          - xcc_sidebar_file_upload
          - xcc_sidebar_messages
          - xcc_sidebar_quarantines
          - xcc_sidebar_reported
          - xcc_ssq_portal
          - xcc_topics_fetch
          - xcc_user_settings_change_language
          - xcc_user_settings_change_quarantine_notification
          - xcc_user_settings_change_theme
          - xcc_user_tags_fetch
    ```
  </Accordion>

  <Accordion title="xcc_tenant_analyst" description="45 permissions">
    ```yaml xcc.yml theme={null}
    # Tenant analyst
    roleToPermissionMappings:
      my_custom_role:
          - xcc_analyst_portal
          - xcc_asset_fetch|tenant:primary
          - xcc_campaign_add|tenant:primary
          - xcc_campaign_archive|tenant:primary
          - xcc_campaign_fetch|tenant:primary
          - xcc_campaign_remove|tenant:primary
          - xcc_campaign_update|tenant:primary
          - xcc_file_upload
          - xcc_incident_isolate|tenant:primary
          - xcc_incident_resolve|tenant:primary
          - xcc_login
          - xcc_mail_import_read|tenant:primary
          - xcc_quarantine_archive|tenant:primary
          - xcc_quarantine_release|tenant:primary
          - xcc_quarantine_release_request_create|tenant:primary
          - xcc_quarantine_release_request_resolve|tenant:primary
          - xcc_result_detail_dana_screenshots|tenant:primary
          - xcc_result_detail_fetch|tenant:primary
          - xcc_result_detail_preview|tenant:primary
          - xcc_result_detail_unlock|tenant:primary
          - xcc_result_list_fetch|tenant:primary
          - xcc_result_query_check
          - xcc_result_report_log_add|tenant:primary
          - xcc_result_report_log_fetch|tenant:primary
          - xcc_rule_list_add|tenant:primary
          - xcc_rule_list_fetch|tenant:primary
          - xcc_rule_list_remove|tenant:primary
          - xcc_rule_list_update|tenant:primary
          - xcc_search_add|tenant:primary
          - xcc_search_fetch|tenant:primary
          - xcc_search_remove|tenant:primary
          - xcc_search_update|tenant:primary
          - xcc_share_misclassification|tenant:primary
          - xcc_sidebar_file_upload
          - xcc_sidebar_messages
          - xcc_sidebar_quarantines
          - xcc_sidebar_reported
          - xcc_ssq_portal
          - xcc_topics_fetch|tenant:primary
          - xcc_user_settings_change_language
          - xcc_user_settings_change_quarantine_notification
          - xcc_user_settings_change_theme
          - xcc_user_tags_add|tenant:primary
          - xcc_user_tags_fetch
          - xcc_user_tags_remove|tenant:primary
    ```
  </Accordion>

  <Accordion title="xcc_tenant_analyst_audit" description="22 permissions">
    ```yaml xcc.yml theme={null}
    # Tenant analyst audit
    roleToPermissionMappings:
      my_custom_role:
          - xcc_analyst_portal
          - xcc_asset_fetch|tenant:primary
          - xcc_campaign_fetch|tenant:primary
          - xcc_login
          - xcc_result_detail_dana_screenshots|tenant:primary
          - xcc_result_detail_fetch|tenant:primary
          - xcc_result_detail_preview|tenant:primary
          - xcc_result_list_fetch|tenant:primary
          - xcc_result_query_check
          - xcc_result_report_log_fetch|tenant:primary
          - xcc_rule_list_fetch|tenant:primary
          - xcc_search_fetch|tenant:primary
          - xcc_sidebar_file_upload
          - xcc_sidebar_messages
          - xcc_sidebar_quarantines
          - xcc_sidebar_reported
          - xcc_ssq_portal
          - xcc_topics_fetch|tenant:primary
          - xcc_user_settings_change_language
          - xcc_user_settings_change_quarantine_notification
          - xcc_user_settings_change_theme
          - xcc_user_tags_fetch
    ```
  </Accordion>

  <Accordion title="xcc_insights" description="2 permissions">
    ```yaml xcc.yml theme={null}
    # Insights
    roleToPermissionMappings:
      my_custom_role:
          - xcc_sidebar_insights
          - xcc_sidebar_threat_intelligence
    ```
  </Accordion>

  <Accordion title="xcc_monitor" description="1 permission">
    ```yaml xcc.yml theme={null}
    # Monitor
    roleToPermissionMappings:
      my_custom_role:
          - xcc_sidebar_monitor
    ```
  </Accordion>
</AccordionGroup>

## Set the permission scope

Optional: you can restrict the permission scope with the following syntax. If you omit the scope, the permission will have global scope.

```
<grantDefinition>           := <permissionName>(|<scopeDefinition>)*
<scopeDefinition>           := <mailScopeDefinition>|<verdictScopeDefinition>|<quarantineScopeDefinition>|<perTenantScope>
<mailScopeDefinition>       := email:|sender:|recipient:(primary|all|(specific:<emailAddress>))
<quarantineScopeDefinition> := quarantine:(Airlock|BEC|Extortion|Filter|Impersonation|Malware|Phishing|Spam)
<perTenantScope>            := tenant:(primary|<tenantUid>)
<permissionName>            := See Permissions-Role Matrix
```

Examples:

| Definition | Explanation |
| - | - |
| `xcc_quarantine_release` | Allows releasing any quarantined email. |
| `xcc_quarantine_release\|email:primary\|tenant:11111111-1111-1111-1111-111111111111` | Allows releasing emails quarantined for the user's primary email address. |
| `xcc_quarantine_release\|recipient:all\|quarantine:Spam` | Allows releasing only spam emails quarantined for all of the user's addresses. |
| `xcc_quarantine_release\|tenant:primary\|quarantine:Spam` | Allows releasing only spam emails quarantined for the user's primary tenant. |
| `xcc_quarantine_release\|sender:primary\|quarantine:Phishing` | Allows releasing only sent phishing emails for the user's primary email address. |

When you finish editing `roleToPermissionMappings` in `xcc.yml`, click **Publish**. The role mapping becomes active within about one minute.

## Permissions-role matrix

This table shows whether a specific built-in role has a `Permission` or not and if so with what `Scope`.

* Table entry `global` means that the role has unrestricted access for a specific permission.
* Table entry `tenant:primary` means that the role has access for a specific permission but only within the bounds of the current user's tenant.
* Table entry `based on <flag>` means that the role has access only within the user's own tenant, to the quarantined emails of their own addresses, and only where that flag is enabled for the quarantine in `guarded_tenants.yml`.
* A missing table entry indicates that the role does not have that permission at all.

<div>
  <div>
    <span>Show roles</span>
    <label><input type="checkbox" /><code>xcc\_admin</code></label>
    <label><input type="checkbox" /><code>xcc\_admin\_audit</code></label>
    <label><input type="checkbox" /><code>xcc\_analyst</code></label>
    <label><input type="checkbox" /><code>xcc\_analyst\_audit</code></label>
    <label><input type="checkbox" /><code>xcc\_tenant\_analyst</code></label>
    <label><input type="checkbox" /><code>xcc\_tenant\_analyst\_audit</code></label>
    <label><input type="checkbox" /><code>xcc\_insights</code></label>
    <label><input type="checkbox" /><code>xcc\_monitor</code></label>
    <label><input type="checkbox" /><code>xcc\_quarantine\_user</code></label>
  </div>

  <div>
    <table>
      <thead>
        <tr>
          <th>Permission</th>
          <th><code>xcc\_admin</code></th>
          <th><code>xcc\_admin\_audit</code></th>
          <th><code>xcc\_analyst</code></th>
          <th><code>xcc\_analyst\_audit</code></th>
          <th><code>xcc\_tenant\_analyst</code></th>
          <th><code>xcc\_tenant\_analyst\_audit</code></th>
          <th><code>xcc\_insights</code></th>
          <th><code>xcc\_monitor</code></th>
          <th><code>xcc\_quarantine\_user</code></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <th><code>config\_service\_read</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows reading of configuration file from the config service in Expert Editor</div></td>
        </tr>

        <tr>
          <th><code>config\_service\_write</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows editing of a configuration file in the config service in Expert Editor</div></td>
        </tr>

        <tr>
          <th><code>xcc\_analyst\_portal</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows general access to the main analyst UI</div></td>
        </tr>

        <tr>
          <th><code>xcc\_api\_key\_create</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows creation of new API keys.</div></td>
        </tr>

        <tr>
          <th><code>xcc\_api\_key\_delete</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows deletion of API keys.</div></td>
        </tr>

        <tr>
          <th><code>xcc\_api\_key\_fetch</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows listing API keys.</div></td>
        </tr>

        <tr>
          <th><code>xcc\_asset\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td><span>based on <code>canView</code></span></td>
        </tr>

        <tr>
          <td><div>Allows retrieving analysis artifacts of messages, reported emails, and uploaded files</div></td>
        </tr>

        <tr>
          <th><code>xcc\_backup\_info\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows access to information about the current backup status</div></td>
        </tr>

        <tr>
          <th><code>xcc\_backup\_trigger</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows manually triggering of a backup</div></td>
        </tr>

        <tr>
          <th><code>xcc\_campaign\_add</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows creation of a new campaign</div></td>
        </tr>

        <tr>
          <th><code>xcc\_campaign\_archive</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows archiving of a campaign</div></td>
        </tr>

        <tr>
          <th><code>xcc\_campaign\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows retrieval of the campaigns</div></td>
        </tr>

        <tr>
          <th><code>xcc\_campaign\_remove</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows removal of a campaign</div></td>
        </tr>

        <tr>
          <th><code>xcc\_campaign\_update</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows update of existing campaigns</div></td>
        </tr>

        <tr>
          <th><code>xcc\_config\_m365\_credentials</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows managing (setting or clearing) stored credentials for Microsoft 365 integrations</div></td>
        </tr>

        <tr>
          <th><code>xcc\_core\_result\_delete</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows to delete a result from xcc</div></td>
        </tr>

        <tr>
          <th><code>xcc\_file\_upload</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows uploading files for analysis</div></td>
        </tr>

        <tr>
          <th><code>xcc\_incident\_isolate</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows isolation of one or multiple messages</div></td>
        </tr>

        <tr>
          <th><code>xcc\_incident\_resolve</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows resolving one or multiple incidents</div></td>
        </tr>

        <tr>
          <th><code>xcc\_login</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td><span>global</span></td>
        </tr>

        <tr>
          <td><div>Allows performing a login from the UI</div></td>
        </tr>

        <tr>
          <th><code>xcc\_mail\_import\_read</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows reading of mail imports</div></td>
        </tr>

        <tr>
          <th><code>xcc\_mail\_import\_update</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows updating/managing of mail imports</div></td>
        </tr>

        <tr>
          <th><code>xcc\_quarantine\_archive</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td><span>based on <code>canView</code></span></td>
        </tr>

        <tr>
          <td><div>Allows archiving of a quarantined message.</div></td>
        </tr>

        <tr>
          <th><code>xcc\_quarantine\_release</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td><span>based on <code>canRelease</code></span></td>
        </tr>

        <tr>
          <td><div>Allows the release of one or more quarantined messages</div></td>
        </tr>

        <tr>
          <th><code>xcc\_quarantine\_release\_request\_create</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td><span>based on <code>canRequestRelease</code></span></td>
        </tr>

        <tr>
          <td><div>Allows creating a release request for one or more quarantined messages</div></td>
        </tr>

        <tr>
          <th><code>xcc\_quarantine\_release\_request\_resolve</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows resolving a message which has been requested to be released either by approving or denying the request.</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_detail\_dana\_screenshots</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td><span>based on <code>canView</code></span></td>
        </tr>

        <tr>
          <td><div>Allows viewing of screenshots and videos from the dynamic analysis (if available)</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_detail\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td><span>based on <code>canView</code></span></td>
        </tr>

        <tr>
          <td><div>Allows view of the email details</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_detail\_preview</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td><span>based on <code>canView</code></span></td>
        </tr>

        <tr>
          <td><div>Allows viewing of email previews (if available)</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_detail\_unlock</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td><span>based on <code>canUnlock</code></span></td>
        </tr>

        <tr>
          <td><div>Allows unlocking of emails with encrypted attachments (Attachment Airlock)</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_list\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td><span>based on <code>canView</code></span></td>
        </tr>

        <tr>
          <td><div>Allows view of search query results (e.g., the <b>Messages</b> overview)</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_query\_check</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td><span>global</span></td>
        </tr>

        <tr>
          <td><div>Internal permission required for all roles</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_report\_log\_add</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows to add a new message to the report log</div></td>
        </tr>

        <tr>
          <th><code>xcc\_result\_report\_log\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows viewing of the case log</div></td>
        </tr>

        <tr>
          <th><code>xcc\_rule\_list\_add</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows addition of entries on black- and whitelists</div></td>
        </tr>

        <tr>
          <th><code>xcc\_rule\_list\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows retrieval of black- and whitelists</div></td>
        </tr>

        <tr>
          <th><code>xcc\_rule\_list\_remove</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows removal of entries of rule lists</div></td>
        </tr>

        <tr>
          <th><code>xcc\_rule\_list\_update</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows editing of black- and whitelists</div></td>
        </tr>

        <tr>
          <th><code>xcc\_search\_add</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows creation of a new saved query</div></td>
        </tr>

        <tr>
          <th><code>xcc\_search\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows retrieval of the saved queries</div></td>
        </tr>

        <tr>
          <th><code>xcc\_search\_remove</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows removal of existing saved queries</div></td>
        </tr>

        <tr>
          <th><code>xcc\_search\_update</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows update of existing saved queries</div></td>
        </tr>

        <tr>
          <th><code>xcc\_share\_misclassification</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows submission of misclassification reports</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_file\_upload</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows access to the list of files uploaded using the `File Upload` menu item</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_insights</code></th>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td><span>global</span></td>

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows access to the `Insights` menu item<br /><b>Note: </b>To access the actual dashboards, the user must also have role `xcc_insights`</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_messages</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows display of the <b>Messages</b> menu item</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_monitor</code></th>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td><span>global</span></td>

          <td />
        </tr>

        <tr>
          <td><div>Allows access to `Monitoring` menu item<br /><b>Note: </b>To access the actual dashboards, the user must also have role `xcc_monitor`</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_quarantines</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows display of the <b>Quarantines</b> menu item</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_reported</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows display of the <b>Reported</b> menu item</div></td>
        </tr>

        <tr>
          <th><code>xcc\_sidebar\_threat\_intelligence</code></th>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td><span>global</span></td>

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows access to the `Threat Intelligence` menu item<br /><b>Note: </b>To access the actual dashboards, the user must also have role `xcc_insights`</div></td>
        </tr>

        <tr>
          <th><code>xcc\_ssq\_portal</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td><span>global</span></td>
        </tr>

        <tr>
          <td><div>Allows access to the self-service user quarantine UI</div></td>
        </tr>

        <tr>
          <th><code>xcc\_topics\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>tenant:primary</span></td>
          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows viewing of the extracted topics from email (if available)</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_impersonate</code></th>
          <td><span>global</span></td>

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows impersonation of another user</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_settings\_change\_language</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td><span>global</span></td>
        </tr>

        <tr>
          <td><div>Allows the user to change their language</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_settings\_change\_quarantine\_notification</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td><span>global</span></td>
        </tr>

        <tr>
          <td><div>Allows the user to change their quarantine notification settings</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_settings\_change\_theme</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td><span>global</span></td>
        </tr>

        <tr>
          <td><div>Allows the user to change their settings (e.g., the theme)</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_tags\_add</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows adding of one or multiple tags for an analyzed message, reported incident, and uploaded file</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_tags\_fetch</code></th>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>
          <td><span>global</span></td>

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows retrieval of user tags attached to an analyzed message, reported incident, and uploaded file</div></td>
        </tr>

        <tr>
          <th><code>xcc\_user\_tags\_remove</code></th>
          <td><span>global</span></td>

          <td />

          <td><span>global</span></td>

          <td />

          <td><span>tenant:primary</span></td>

          <td />

          <td />

          <td />

          <td />
        </tr>

        <tr>
          <td><div>Allows removal of one or multiple tags for an analyzed message, reported incident, and uploaded file</div></td>
        </tr>
      </tbody>
    </table>
  </div>
</div>


# Custom Alerts
Source: https://docs.xorlab.com/latest/custom-alerts

Tag emails with alert hashtags based on domain, address, and keyword lists under Settings, Lists, Alerts.

Emails matching one of these lists get tagged `#alert`. The lists are accessible by selecting **Settings → Lists → Alerts** in XCC. Modify any of the lists below:

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Domain alerts** | Use this list to flag emails that contain link domains in the email body or any of its attachments | Domain name as `String`, e.g., `cloudservice.com` |
| **Email address alerts** | Use this list to flag emails sent from certain email addresses | Email address as `String`, e.g., `user@suspicious.com` |
| **File extension alerts (regex)** | Use this list to flag emails that contain file attachments with a given file extension | File extension as `Regex`, e.g., `(?i)\.exe$` for case-insensitive matching |
| **File hash alerts** | Use this list to flag emails that contain file attachments with a given SHA256 hash value | File hash value as `String`, e.g., `9db4 4391 dbfa 43bc 9b13 4440 00f6 9c77 a395 95c9 bac5 710e 0a78 a638 60b0 69a2` |
| **Keyword alerts** | Use this list to flag emails that contain any given keyword | Keyword as `String` |


# Dashboard and Messages
Source: https://docs.xorlab.com/latest/dashboard-messages

The dashboard and message list views: traffic statistics, filters, and how to navigate processed emails.

## Dashboard

Dashboard is the first page you will see after you login to xorlab. It gives you a summary of the platform activities in a concise and comprehensible way. You can see the statistics of email traffic, the status of the defense system, and the results of its activity.

<img alt="Dashboard" />

In the left pane, there is a navigation menu that allows you to quickly access particular sets of messages and other tools.

The navigation menu includes:

* **Messages**: A list of **All Messages** processed by xorlab.
* **Quarantines**: A list of quarantined messages grouped by a type of threat (malware, phishing, etc).
* **Abuse Mailbox**: A list of messages reported as suspicious by users and grouped into cases by priority or status, see [Abuse Mailbox](/latest/abuse-mailbox).
* **Saved Searches**: A list of your saved custom searches.
* **Campaigns**: The panel for managing your [Campaigns](/latest/campaigns).
* **Insights**: The panel for accessing statistic information presented as Elastic-powered graphs.
* **Threat Intelligence**: The panel for accessing more detailed information on main five areas in Elastic-powered dashboards.
* **Monitoring**: Directs to the Grafana, a centralized access where you can access logs and dashboards, see also [Monitoring Guide](/latest/monitoring-guide).
* **File Upload**: A tool that allows you to manually upload a file to the Sandbox, see [File Analysis](/latest/file-analysis).

## All messages

This page shows an overview of all messages that have been processed by xorlab.

<img alt="All Messages View" />

The search bar on top of the page enables you to filter the list view for messages. It includes user-friendly features such as autocomplete, filters, and time range selection. Please refer to the [Search Documentation](/latest/search) for more information.

For each email in the list view, you find the following information:

* **Type**: IN (incoming email), OUT (outgoing email), INT (internal email)
* **Received**: The timestamp on which xorlab received the email
* **Reputation/Trust**: A color-coded and numeric indicator. Reflects either trust or reputation, depending on which is more relevant and available.
* **Authentication**: The blue or gray check symbol. A blue checkmark shows that the sender is authenticated, a gray checkmark indicates broken authentication.
* **From**: The sender address of the message and the display name of the sender.
* **Attachment**: A paperclip symbol appears if the email includes one or multiple attachments.
* **Subject**: The subject of the email.
* **To**: The recipient address of the message and the display name of the recipient.
* **Verdict**: Classification of the email, ranging from malicious (red) to benign (blue). Exceptions are spam (orange) and simulation (blue).
* **Status**: Explains the action that xorlab took with the email. Most frequent actions are either quarantined (yellow) or delivered (green).
* **Contextual Banners**: If enabled, the **Status** field might also include a symbol to indicate which [contextual banner](/latest/detection-contextual-banners) was applied.


# Review Default Actions
Source: https://docs.xorlab.com/latest/detection-actions

Decide which verdicts are quarantined and which are delivered with a rewritten subject, and set that per tenant.

The **Actions** configuration screen defines what xorlab does with an email once it has been classified: deliver it, rewrite its subject, or quarantine it. Actions are chosen from the email's verdict and confidence — see [List of Verdicts](/latest/verdicts) for how the final verdict is resolved, and [Understanding an Email Verdict](/latest/understand-verdict) for how a message gets one.

## Review the default actions

Review the default protection settings of xorlab:

1. Open **Admin → Actions** in XCC. Review the configured actions per confidence and verdict.

   1. For a more aggressive detection, set the **Medium Confidence** of the verdicts to quarantine.
   2. Change the default **Subject Rewrite** of *\[SPAM]* if required.
   3. Setting **Low Confidence** to quarantine is not recommended as it will create false positives.

   <img alt="Default actions" />

2. In addition to the configured **Actions**, xorlab can quarantine an email due to a static policy. Go through [Review Static Policies](/latest/detection-static-policies).

For changes this screen cannot express, see [Tune Detection](/latest/detection-tuning) and [Rule Parameters](/latest/rule-parameters).

## Multi-Tenancy

Actions are configured per tenant. Select the tenant in the dropdown, then review its **Actions**. To give a tenant a different detection strength altogether, reference a different [rule profile](/latest/rule-profiles) for it.


# Add Result Header to Email
Source: https://docs.xorlab.com/latest/detection-analysis-result-header

Add headers carrying xorlab's analysis results to every email so downstream systems can act on them.

The headers contain only the most important analysis results, not the full analysis output.

To activate this:

1. In the Expert Editor, open `shared/guarded_tenants.yml`.

2. Find `messageProcessing.pipelines.default`, and add this line:

```yaml guarded_tenants.yml {6} theme={null}
tenants:
  - name: example
    messageProcessing:
      pipelines:
        emails:
          # Supported values: Enabled|EnabledInbound|Disabled
          analysisResultInMimeHeader: EnabledInbound
```

Click **Publish**. The new setting becomes active within about one minute.

With this feature enabled, the header of an analyzed email will look like the one below:

```
x-xor-id: 111111111111-1111-1111-1111-111111111111
x-xor-decision: DELIVER
x-xor-verdict: spam
x-xor-verdict-confidence: high
x-xor-tags: #spam, #highrisk, #hsrisk, #domainonlyinbound, #mprisk, #noreputation, #rsdmediumscore, #senderonlyinbound, #tldnoreputation, #untrusted, #auth, #lowscore, #spfpass, #banner, #deliver, #dkimfromsigned, #eachlinkmfrom, #htmlmessage, #inc
```

The `x-xor-verdict-confidence` header is only included when the verdict is either Phishing, Spam, VIP Fraud, Impersonation, or Policy. The other verdicts do not have a confidence.


# Enable Attachment Removal
Source: https://docs.xorlab.com/latest/detection-attachment-removal

Strip suspicious attachments and deliver the remaining email. The Self-Service Quarantine is generally the better option.

Removed attachments can be replaced with a text file.

<Note>
  **Use SSQ instead**

  In general, we recommend to enable the [SSQ](/latest/ssq-overview) instead of attachment removal. It provides a safer environment and no attachments are lost.
</Note>

Attachment removal can be activated in different ways:

* **Verdict based**: Remove all attachments from emails classified as Malware or Filter/Policy.
* **File based**: Remove attachments that match certain file criteria (e.g. extension)
* **Custom rule based**: Remove attachments based on arbitrary custom rules - contact [support@xorlab.com](mailto:support@xorlab.com) for this

<Warning>
  After an attachment was replaced or removed, the original attachment is deleted and cannot be recovered anymore.
</Warning>

To enable attachment removal or replacement:

1. Open the `activeguard/core/rule_sets/90_local/params/local.properties` file in Expert Editor and add:
   ```ini local.properties theme={null}
   # Global switch for enabling attachment removal/replacement
   POLICY_attachment_transform_state=ACTIVE
   # Control the file name of the text file which replaces the attachment. Use %s to include the original file name
   POLICY_attachment_replace_filename_formatstring=removed-%s.txt
   ```

2. Specify the email direction on which attachment removal is activated:
   ```ini local.properties theme={null}
   # Supported values: ALL, INCOMING (default) and OUTGOING
   POLICY_attachment_transform_direction=INCOMING
   ```

3. For **verdict based** attachment removal, use the following configuration:
   ```ini local.properties theme={null}
   # Supported values: keep(default)/remove/replace
   # Add only the verdicts where you want to enable attachment removal
   POLICY_malware_dynamic=replace
   POLICY_malware_static=replace
   # Use attachment removal/replacement on filter verdicts with care.
   POLICY_attachment_filter=
   ```

4. For **file based** attachment removal, use the following configuration:
   ```ini local.properties theme={null}
   # Supported values: keep(default)/remove/replace
   POLICY_encrypted_archive_file=
   POLICY_excessive_nesting=
   # Replace/remove all executable files
   POLICY_executable_file=
   # Replace/remove all files with blacklisted extensions/hashes/file outputs 
   POLICY_file_extension_is_blacklisted= # (1)
   POLICY_file_hash_is_blacklisted=
   POLICY_file_output_is_blacklisted=
   # Replace/remove all flash files
   POLICY_flash=
   POLICY_legacy_archive_file=
   POLICY_html_file=
   POLICY_iso_file=
   POLICY_office_encrypted=
   # Replace/remove all files with VBA script
   POLICY_office_vbascript=
   # Replace/remove all files with dangerous VBA script (executable, file, network or registry directives)
   POLICY_office_dangerous_vbascript=
   POLICY_shortcut_file=
   ```
   1. Attachment removal based on blacklists only works if the quarantine action for blacklist matches is disabled. If you need help adjusting this setting, contact [support@xorlab.com](mailto:support@xorlab.com).

5. For every use case above, you can specify the text in the replacement file with the following properties:
   ```ini local.properties theme={null}
   # If attachment replacement is enabled, this is the generic fallback text which goes into the text file replacing the file.
   POLICY_attachment_replace_text=This attachment got removed as it violated our security policy.
   # Specific replacement tests:
   POLICY_attachment_replace_text_executable_file=This attachment got removed as it was an executable file and thus violated our security policy.
   POLICY_attachment_replace_text_legacy_archive_file=This attachment got removed as it was an archive and thus considered dangerous.
   POLICY_attachment_replace_text_excessive_nesting=This attachment got removed because of excessive nesting of files.
   POLICY_attachment_replace_text_encrypted_archive_file=This attachment got removed as it was an encrypted archive and thus violated our security policy.
   POLICY_attachment_replace_text_file_extension_is_blacklisted=This attachment got removed as it had a blacklisted file extension.
   POLICY_attachment_replace_text_file_hash_is_blacklisted=This attachment got removed as it was blacklisted.
   POLICY_attachment_replace_text_file_output_is_blacklisted=This attachment got removed as it had a blacklisted file extension.
   POLICY_attachment_replace_text_flash=This attachment got removed as it was a flash file and thus violated our security policy.
   POLICY_attachment_replace_text_html_file=This attachment got removed as it was a html file and thus violated our security policy.
   POLICY_attachment_replace_text_iso_file=This attachment got removed as it was an iso file and thus violated our security policy.
   POLICY_attachment_replace_text_office_encrypted=This attachment got removed as it was an office file with encrypted content and thus violated our security policy.
   POLICY_attachment_replace_text_office_vbascript=This attachment got removed as it was an office file with active content and thus violated our security policy.
   POLICY_attachment_replace_text_shortcut_file=This attachment got removed as it was a shortcut file and thus violated our security policy.
   POLICY_attachment_replace_text_office_dangerous_vbascript=This attachment got removed as it contained suspicious scripts and thus violated our security policy.
   POLICY_attachment_replace_text_malware_dynamic=This attachment got removed as it contained suspicious scripts and thus violated our security policy.
   POLICY_attachment_replace_text_malware_static=This attachment got removed as it contained suspicious scripts and thus violated our security policy.
   POLICY_attachment_replace_text_filter=This attachment got removed as it violated our security policy.
   ```

6. Click **Publish**. The rule-set configuration becomes active within about one minute.


# Enable Contextual Banners
Source: https://docs.xorlab.com/latest/detection-contextual-banners

Add contextual warning banners to emails. Requires a subscription; contact support to enable.

<Note>
  The script packages and individual scripts linked on this page are protected downloads and
  require a password.
</Note>

## 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. <img alt="Alert banner" />
* **Warning (Orange) banners:** Moderate risks that require user attention. <img alt="Warning banner" />
* **Information (Blue) banners:** General insights without immediate action required. <img alt="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

<Note>
  **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.
</Note>

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**. <img alt="Selecting General Settings" />
4. Select **Contextual Banners**.
5. Enable the Alert, Warning and Info banners. <img alt="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](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
   ```

   <Accordion title="Troubleshooting">
     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`.
   </Accordion>
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`: <img alt="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:

```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. |

<Info>
  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.
</Info>

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`.

<Note>
  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.
</Note>

## 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.

<Info>
  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.
</Info>


# Detection Overview
Source: https://docs.xorlab.com/latest/detection-overview

The detection features you can enable on top of xorlab's preconfigured protection, in recommended order.

xorlab's preconfigured protection settings deliver strong security from the start.

| Step | Description |
| :- | :- |
| [Configure built-in lists](#configure-built-in-lists) | **Mandatory**. Populate built-in lists for optimal protection. |
| [Review Default Actions](/latest/detection-actions) | **Optional**. Review the default actions of xorlab. |
| [Additional features](#activate-additional-detection-features) | **Optional**. Activate additional detection-related features to get the most out of xorlab. |

## Configure built-in lists

To optimize protection, it is required to manually populate some of the built-in lists

1. Go to *Admin* and open *Lists*

2. Select **VIP names** and add the names of your C-level. These names will be used to detect VIP Fraud in incoming emails.

   <img alt="VIP names" />

3. Select **High value targets** and add the email addresses of recipients that will be likely targeted by advanced attacks. Usually this is C-level as well. They will receive a more strict and thorough filtering.

4. Optional: Add mailboxes to **Exposed accounts** that should be filtered more aggressively. You can add mailboxes here that are publicly known and receive a lot of spam.

5. Optional: Add mailboxes to **Exposed public contacts** that should be filtered less aggressively to avoid false positives.

## Review default actions

Review what xorlab does with an email per verdict and confidence level, and adjust it where it does not match your policy: [Review Default Actions](/latest/detection-actions).

## Activate additional detection features

The following detection related features can be activated to get the most out of xorlab:

<CardGroup>
  <Card title="SSQ" icon="user" href="/latest/ssq-overview">
    Enable the Self-Service Quarantine (SSQ) for your end-users so that they can release harmless emails themselves.
  </Card>

  <Card title="Banners" icon="triangle-exclamation" href="/latest/detection-contextual-banners">
    Enable targeted contextual banners that will be added to suspicious emails.

    Note: Banners are a paid feature.
  </Card>

  <Card title="VirusTotal" icon="virus" href="/latest/detection-virustotal">
    Extend the XCC web interface with threat intelligence from Virustotal. This enhances the analyst experience, but does not affect detection.

    The VirusTotal license needs to be provided by the customer.
  </Card>

  <Card title="DNS Blocklists" icon="network-wired">
    To further improve spam detection, you can integrate third party DNS blocklists. This is only recommended when using xorlab as standalone filter. We recommend to use either:

    * [Spamhaus Integration](/latest/detection-spamhaus-dqs)
    * Abusix - contact [support@xorlab.com](mailto:support@xorlab.com)
  </Card>
</CardGroup>

## Multi-Tenancy

In a multi-tenant deployment, the steps above are done per tenant:

| Step | In a multi-tenant deployment |
| :- | :- |
| [Configure built-in lists](#configure-built-in-lists) | Same screens as above. Open the **Admin** view and select the tenant in the dropdown on top, then populate the lists for that tenant. Repeat for each tenant. |
| [Review Default Actions](/latest/detection-actions) | Same screens as above. Select the tenant in the dropdown, then review its **Actions**. To give a tenant a different detection strength altogether, reference a different [rule profile](/latest/rule-profiles) for it. |
| [Additional features](#activate-additional-detection-features) | **SSQ** is enabled per tenant, see [Add a Tenant](/latest/multi-tenancy-new-tenant#optional-enable-ssq). **Banners** and **VirusTotal** are instance-wide and cannot be configured per tenant. |

Detection changes you make for a single tenant are stored in that tenant's rule set. See [Manage Tenant Rules](/latest/multi-tenancy-rules) for the underlying folder structure and for setting rule parameters per tenant.


# Enable Spamhaus Integration
Source: https://docs.xorlab.com/latest/detection-spamhaus-dqs

Integrate Spamhaus DQS through the SpamAssassin plugin by supplying a valid key.

Providing a valid key will trigger an automated process to configure this plugin.

## Configuring Spamhaus DQS

First, ensure the tenant’s `local.cf` file is correctly configured. Using [Expert Editor](/latest/expert-editor), in the `activeguard/core/startup_cfg/spamass/local.cf` file, make sure that:

* `skip_uribl_checks` is set to `0` to enable the [`URIDNSBL` plugin](https://spamassassin.apache.org/full/3.2.x/doc/Mail_SpamAssassin_Plugin_URIDNSBL.html)
* `skip_rbl_checks` is set to `0` to enable the `Realtime Blackhole List` checks
* the `dns_query_restriction` list does not contain the value `spamhaus.net` but it does contain `spamhaus.org`

Please also make sure that the trusted MTAs in Spamassassin are configured correctly in `local.cf`.

Some keys are Hash Blocklist (HBL) enabled, some are not. Where to write the key depends on whether the key is HBL enabled and whether you want to use this feature. Therefore, configure Spamhaus either with or without HBL as described below.

### Using Spamhaus DQS with HBL

1. Using Expert Editor, create a new file at `activeguard/core/startup_cfg/spamass/spamhaus_hbl_license.txt`.
2. Populate it with your key and only your key.

### Using Spamhaus DQS without HBL

1. Using Expert Editor, create a new file at `activeguard/core/startup_cfg/spamass/spamhaus_license.txt`.
2. Populate it with your key and only your key.

## Triggering the configuration script

After you have completed the steps above, click **Publish**. Then [**restart the `ag_core` container**](/latest/activate-configuration#configuration-files), because the Spamhaus files under `activeguard/core/startup_cfg/` require an MTA restart:

```shell theme={null}
cd /etc/xorlab/activeguard/
docker compose down && docker compose up -d
```

and check the `stdout` log of `core` (either use Loki or the command line `docker compose logs core`) for the line containing the message `Spamassassin DQS config successfully linted`. This indicates that the configuration files have been successfully written to the Spamassassin configuration directory and are valid.

The communication runs via DNS, therefore you don’t have to change your firewall config.

## Testing

1. Run the [Spamhaus Blocklist Tester (BLT)](https://blt.spamhaus.com).

2. Under `Data Query Service Test`, enter your DQS key, and for the `Test Type` select `Both`, then enter a guarded email address for your tenant to which you have access and permission to use.

   The tests will display as failed in the BLT itself, as they are successfully delivered to the tenant’s mailserver, but are filtered out later by xorlab Security Platform. The BLT cannot know this.

3. The mailbox will receive several emails from `test@unlisted.blt.spamhaus.net`:

   * If the key supplied is HBL-enabled, these should all be quarantined and tagged as `#blacklistedexternal`.
   * If the key is not HBL-enabled, these should all be quarantined and tagged as `#blacklistedexternal` except those with `hbl` in the subject; for example, `BLT DQS Content Test Email (19843:248226:hbl-dqs-body-cc-wallet)`.

## Disabling Spamhaus

You should disable Spamhaus when its license expires to avoid any issues:

1. Remove the license file—either `spamhaus_hbl_license.txt` or `spamhaus_license.txt`—from `activeguard/core/startup_cfg/spamass/` in Expert Editor.

2. While in Expert Editor, open `activeguard/core/startup_cfg/spamass/local.cf` and set `skip_rbl_checks` and `skip_uribl_checks` to `1`.

3. Click **Publish**, then [restart the container](/latest/activate-configuration#configuration-files):

   ```shell theme={null}
   cd /etc/xorlab/activeguard/
   docker compose stop core && docker compose down && sleep 2 && docker compose up -d
   ```


# Review Static Policies
Source: https://docs.xorlab.com/latest/detection-static-policies

The static policies enforced on every email regardless of relationship or context, and the Filter quarantine they trigger.

Below you find the static policies that are active by default. Normally, they do not need to be changed.

<Accordion title="Disabling a static policy">
  To disable one of the static policies below, add a corresponding line to `local.properties`:

  ```ini local.properties theme={null}
  # Syntax: <Rule name>_state=PASSIVE
  FILTER_iso_state=PASSIVE
  ```
</Accordion>

| Static policy (`FILTER` rule) | Description |
| :- | :- |
| `FILTER_executable` | Quarantine all emails with executable files |
| `FILTER_flash` | Quarantine all emails with flash files |
| `FILTER_iso` | Quarantine all emails with ISO files |
| `FILTER_legacy_archive` | Quarantine all emails with archive files that are considered legacy |
| `FILTER_shortcut` | Quarantine all emails with shortcut files |
| `FILTER_windows_script` | Quarantine all emails with windows scripts |
| `FILTER_office_dde` | Quarantine all emails with Office documents containing Dynamic Data Exchange (DDE) fields |
| `FILTER_office_external_frame` | Quarantine all emails with Office documents containing external frame(s) |
| `FILTER_office_external_webvideo` | Quarantine all emails with Office documents containing external videos |
| `FILTER_wwwdata_sender` | Quarantine all emails where the sender’s FROM address is matched by this regex: `.*www-data.*` |
| `FILTER_UNTRUSTED_new_file_type_from_unknown_sender` | Quarantine all emails from unknown senders that contain new file types. A new file type means that it has not been seen yet in trusted communication |

<Info>
  The file extensions blocked by each static policy are documented in
  [Detection Defaults → Static policy file extensions](/latest/detection-defaults#static-policy-file-extensions).
  Access to that page is restricted.
</Info>

**Malware rules still apply**: Even if the above static policies (filters) are disabled, xorlab will still block the majority of their associated file types because of the built-in malware rules. Malware rules depend on the relationship, for example they might block a script file from an untrusted sender, but allow it from a partner. With the static policy, you can enforce blocking it independently of the relationship.


# Tune Detection
Source: https://docs.xorlab.com/latest/detection-tuning

Fine-tune detection to reduce false positives and false negatives. Intended for analysts.

xorlab detection works out of the box, but you can adjust it to address specific issues or align it with your organization's policies.

## Step-by-step guide

<Note>
  We recommend adding the tag `#tuned` to emails that you performed some tuning actions on. This will help you avoid looking at the same issue twice. You can also supplement every search query with `not #tuned` to exclude these cases from the results.
</Note>

### 1️⃣ Authentication

| Step | Query | Measures |
| - | - | - |
| Check if some guarded domains are not configured. | `#ext #auth` | Add missing domains to the list of [guarded domains](/latest/before-begin-integration#configure-your-guarded-domains). |
| Check if emails from your organization are not authentic. | `#impersonation or (#senderstguarded #noauth)` | Check [Authentication](/latest/authentication-issues) and [Trusted MTAs](/latest/trusted-mtas) to fix these issues. |
| Check that there are no emails marked as external. | `#ext` | Usually, there should be no external emails left. Clarify if these emails are expected in the organization. |

### 2️⃣ False positive tuning

| Step | Query | Measures |
| - | - | - |
| Find all false positives. | `#quarantine` | Follow the steps below depending on the verdict. |
| Review false positives with phishing or spam verdicts. | `verdict:phishing or verdict:spam` | <ul><li>Will this sender gain trust during the learning phase? → No actions required.</li><li>Will this sender never gain trust because they are only inbound? → Add sender to the **Low trusted sender addresses** list (see [Trusted Senders and Infrastructure](/latest/trusted-senders-infrastructure)).</li><li>Is this a specific recipient that frequently needs to receive emails from new senders? → Add recipient to "Exposed public contacts" list.</li><li>Is there a more complex pattern? → Go to [Advanced Tuning](#4️⃣-advanced-tuning).</li></ul> |
| Check VIP fraud verdicts (often VIPs sending from personal addresses). | `verdict:vipfraud` | Add them to the **VIP sender email whitelist**. |
| Check impersonation verdicts. | `verdict:impersonation` | Fix [missing Authentication](/latest/authentication-issues). |
| Investigate malware verdicts to understand the root cause. | `verdict:malware` | Look at the [Classifiers & Rules](/latest/understand-verdict#get-an-in-depth-understanding) tab. <br />Common issues are network requests made in the Sandbox. If they have benign reasons like loading a logo from SharePoint, you can add them to **Dynamic DNS request whitelist**. |
| Identify the responsible `FILTER` rule. | `verdict:filter` | Use [Understand Verdicts](/latest/understand-verdict#understanding-verdict-rules) and follow [Advanced Tuning](#4️⃣-advanced-tuning) to decide whether to disable the specific filter rule. |

### 3️⃣ False negative tuning

Use `#inc #untrusted not verdict:reputable not verdict:popular #domainonlyinbound not #quarantine not #dmarcreport` or parts of it to find suspicious emails.

* [Report false negative](/latest/reporting-misclassification) to xorlab.
* Add sender or link to blacklists.
* [Create a campaign](/latest/campaigns).
* Follow [Advanced Tuning](#4️⃣-advanced-tuning) to evaluate if you want to enable or disable specific rules.

### 4️⃣ Advanced tuning

This section explains how to tune individual detection rules for false positives and false negatives by checking impact and changing rule states when needed.

#### False positive tuning

1. Read [Understanding Verdicts](/latest/understand-verdict) to learn what *verdict rules* are and how you can use the *Classifiers & Rules* tab to identify them.
2. Check if multiple false positives in your quarantine are caused by the same verdict rule.
   1. To check the impact of this rule, search for `rule:rule-name #quarantine` (see [*Search*](/latest/search#queries-using-rules)).
   2. Go through the results to assess the legitimacy of every email. For every true positive that you find, check if any other verdict rules (e.g., `PHISHING_...`) triggered on this email. If so, this email would still be blocked by the other rules. To only see emails that would be delivered after disabling the rule in question, exclude all other occurring verdict rules from the query like this: `rule:verdict_rule-name not rule:verdict_other-rule-name #quarantine`.
   3. If you do this and only end up with false positives, you can disable this rule by adding its name appended with `_state=PASSIVE` to `local.properties`, for example `PHISHING_risk_based_one_suspicious_state=PASSIVE`
3. Check if a *passive* **ADAPT\_** rule would match the false positives in your quarantine.
   1. To check the impact of this rule, search for `passiverule:ADAPT_rule-name #quarantine` (see [*Search*](/latest/search#queries-using-rules)).
   2. Examine the search results to see if the other emails that matched this **ADAPT\_** rule are also false positives that should have been delivered.
   3. If the *passive rule* mostly matched false positives, you can activate the rule by adding its name appended with `_state=ACTIVE` to `local.properties`, for example `ADAPT_phishing_confidence_low_based_on_link_with_from_domain_state=ACTIVE`

#### False negative tuning

1. Check if your false negatives are caused by a specific **ADAPT\_** rule.
   1. To check the impact of this rule, search for `rule:rule-name #deliver` (see [*Search*](/latest/search#queries-using-rules)).
   2. Go through the results to assess the legitimacy of every email. For every true negative that you find, exclude any other active **ADAPT\_** rules that also trigger on the same email from the query like this: `rule:ADAPT_rule-name not rule:ADAPT_other-rule-name #deliver`.
   3. If you do this and only end up with false negatives, you can disable this rule by adding its name appended with `_state=PASSIVE` to `local.properties`, for example: `ADAPT_phishing_confidence_high_state=PASSIVE`
2. Check if a *passive* verdict- or **FILTER\_** rule would match your false negatives.
   1. To check the impact of this rule, search for `passiverule:VERDICT_rule-name #deliver` (see [*Search*](/latest/search#queries-using-rules)).
   2. Examine the search results to see if the other emails that matched this passive rule are also false negatives that should have been quarantined.
   3. If the passive rule mostly matched false negatives, you can activate the rule by adding its name appended with `_state=ACTIVE` to `/activeguard/core/rule_sets/90_local/params/local.properties`, for example `PHISHING_risk_based_one_suspicious_state=ACTIVE`


# Enable VirusTotal
Source: https://docs.xorlab.com/latest/detection-virustotal

Enable VirusTotal threat intelligence in the email detail view. Informational only, not used for detection.

To enable VirusTotal:

1. Open the file `xcc.yml` in the Expert Editor and add the following with your key:

   ```yaml xcc.yml {2} theme={null}
   virusTotal:
     apiKey: "add_your_key_here"
     ## Optional proxy configuration
     # http:
        # host: https://www.virustotal.com # Mandatory in case you provide settings for http
        # proxy:
         #  host: proxy.xorlab.com
         #  port: 8080
           ## Optional credentials:
           # credentials:
             # user: "proxy-user"
             # password: "pwd"
     ## Enables the TLS/SSL support with no certificate validation
     # trustAll: false
   ```

2. Click **Publish**, then [restart the XCC](/latest/activate-configuration#configuration-files). The `virusTotal` setting is a general `xcc.yml` setting and requires the XCC restart to take effect.

## Information about the integration

xorlab sends only the SHA256 hash of an attachment to VirusTotal, not the entire attachment. URLs are submitted as-is without prior hashing. By adding your VirusTotal key you agree that this information will be sent to VirusTotal. Please visit [VirusTotal website](https://www.virustotal.com) for their Terms and Services and their Privacy Policy as by submitting data those will apply.

xorlab only uses the VirusTotal API for items that are manually opened in xorlab, e.g., when opening a message in the detail view. No VirusTotal API requests are performed when an email is not viewed.

The following VirusTotal API endpoints are used:

* [https://developers.virustotal.com/reference#file-info](https://developers.virustotal.com/reference#file-info)
* [https://developers.virustotal.com/reference#url-info](https://developers.virustotal.com/reference#url-info)
* [https://developers.virustotal.com/reference#domain-info](https://developers.virustotal.com/reference#domain-info)
* [https://developers.virustotal.com/reference#ip-info](https://developers.virustotal.com/reference#ip-info)


# Email Bombing Recipient Addresses
Source: https://docs.xorlab.com/latest/email-bombing-list

Tighten filtering for a mailbox under a subscription-flood attack, where mass sign-up confirmations bury real mail.

Email bombing (also known as “list linking” or “email cluster bombing”) floods a user’s inbox with thousands of legitimate subscription or notification emails within a short time. These attacks are typically short but high in volume and can hide important security alerts in the noise.

The **Email bombing recipient addresses** list is accessible by selecting **Settings → Lists → Other** in XCC.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Email bombing recipient addresses** | Recipients whose auto-generated emails receive more aggressive filtering | Email address as `String` |

## What this list does

When you add a recipient address to this list:

* More aggressive filtering of auto-generated emails is applied.
* The volume of newsletter and notification emails is reduced.
* The impact of an ongoing attack is limited.

<Warning>
  **Risk of false positives**

  Aggressive filtering increases the risk of false positives.\
  Legitimate password resets, account notifications, or newsletters may be quarantined.
</Warning>

## When to use it

Use this list only if:

* A user is actively experiencing an email bombing attack.
* The inbox is flooded with high volumes of auto-generated emails from many unknown domains.
* Manual sender blocking is no longer effective.

This is a **temporary containment measure**.

## Operational guidance

1. Add the affected address as soon as the attack is confirmed.
2. Monitor the mailbox for false positives.
3. Remove the address once the attack subsides.
4. Report unique incidents to [support@xorlab.com](mailto:support@xorlab.com).
5. Contact support for help with bulk isolation or unsubscribing affected users.


# Email Direction
Source: https://docs.xorlab.com/latest/email-direction

How xorlab assigns each email a direction (incoming, outgoing, internal, or external) based on your guarded domains.

Every email will be assigned one of the following four directions:

* **Incoming:** The domain of the recipient is guarded, but the domain of the sender is not.
* **Outgoing:** The domain of the sender is guarded, but the domain of the recipient is not.
* **Internal:** The domain of the sender and recipient are both guarded.
* **External:** Neither sender nor recipient domain is guarded.

The direction is important because by default, only **Incoming** emails are filtered. The direction assignment is done based on sender and recipient, and not based on IP address or a dedicated listener.

<img alt="Mail direction" />

A sender that can’t be authenticated is always considered as **not guarded**.

<Warning>
  **External direction**

  The direction **External** is in almost all cases caused by a configuration issue: Either a domain is missing from `guarded_tenants.yml`, or xorlab is accidentally receiving emails for a domain that it should not receive any. For a properly configured xorlab, there should be no **External** emails. You can check this with the search `direction:external`.
</Warning>

<Note>
  **External verdict vs. External direction**

  In addition to the External direction, there is also a verdict External. The latter has nothing to do with the direction, and is the fallback verdict for benign emails that cannot be categorized further.
</Note>


# Customize Templates
Source: https://docs.xorlab.com/latest/email-template-modifications

Add, remove, and customize end-user notification templates, including logo, colors, fonts, and text.

## Change the logo

To change the logo in the notifications:

1. Open `shared/email_templates/style/default.yml`.

2. Uncomment the configuration about logo, choose either via embedded **File** or via **URL**:

   <CardGroup>
     <Card title="File (preferred)" icon="file">
       PNG Logo is uploaded to xorlab.

       ```yaml default.yml theme={null}
       logo:
           # Path is relative to email_templates folder, not to the root directory
           location: "shared/logo.txt"
           type: "PNG_BASE_64"
       ```
     </Card>

     <Card title="URL" icon="link">
       Logo is referenced via a URL.

       ```yaml default.yml theme={null}
       logo:
           location: "https://your.site/logo.png"
           type: "LINK"
       ```
     </Card>
   </CardGroup>

3. In case of **URL**, click **Publish** and finish. The template configuration becomes active within about one minute.

4. In case of **File**, add a new folder called `shared` under `shared/email_templates`.

5. Create a new file inside `shared/email_templates/shared` and name it `logo.txt` (as configured above).

6. Enter the logo Base64 encoded into this file. For Base64 encoding, you can use e.g. [Base64.guru](https://base64.guru/converter/encode/file) or [CyberChef](https://gchq.github.io/CyberChef/).

7. Click **Publish**. The template configuration becomes active within about one minute.

## Change the colors

In the same **Branding & Colors** section of the `default.yml` file, you can change the colors used in the mail notification templates to match your company’s brand identity.

1. Click the `style` folder to expand it and click the `default.yml` file.
2. The second part in the section titled **Branding & Colors** is marked as `#colors:`.
3. Using the <kbd>Ctrl</kbd>+<kbd>Slash</kbd> (<kbd>Cmd</kbd>+<kbd>Slash</kbd> on macOS) keyboard shortcut, uncomment the `colors` line and the required lines that follow. Enter new values for color properties that can be changed:
   * `error`, `alert`, `warning`, `ok`, `neutral`—the color of the text label for the findings (aka the “kicker”, e.g., `ALERT`, `WARN`, `GREEN LIGHT` or `UNDECIDED`)
   * `background`—self-explanatory: the color of the background
   * `light` and `dark`—reserved (unused)
   * `info`
   * `subscript` (message info: from, date, etc.)
4. Click **Publish**. The template configuration becomes active within about one minute.

## Change the font

1. Click the `style` folder to expand it and click the `default.yml` file.
2. Go to the section titled **Typography**.
3. Using the <kbd>Ctrl</kbd>+<kbd>Slash</kbd> (<kbd>Cmd</kbd>+<kbd>Slash</kbd> on macOS) keyboard shortcut, uncomment the `font` line and the required lines that follow. Enter new values for font properties that can be changed:
   * `size`—if you want to specify a new size
   * `family`—if you want to use another font family
   * `color`—for specifying a new font color

The resulting Typography section can look like the one below:

```yaml theme={null}
font:
  size: "12"
  family: "Lato, 'Helvetica Neue', Helvetica, Arial, sans-serif"
  color: "#0e0e0e"
```

When you are done, click **Publish**. The template configuration becomes active within about one minute.

## Change the footer information

All company information appearing as an email footer is configurable in the `default.yml` file located in the `info` folder.

1. Click the `info` folder to expand it and click the `default.yml` file.
2. Using the <kbd>Ctrl</kbd>+<kbd>Slash</kbd> (<kbd>Cmd</kbd>+<kbd>Slash</kbd> on macOS) keyboard shortcut, uncomment the required lines. Enter new values for company info properties that can be changed:
   * `name`—your company name
   * `details`—additional info, e.g., the department name such as `"Security Operations Center"`
   * `email`—contact email address
   * `url`—the URL address for a Self-Service Quarantine link in notification mails, e.g., `"https://customer.activeguard.cloud"`
   * `provider`—the name of the service provider

The resulting company information file can look like the one below:

```yaml theme={null}
name: "MyCompany, Inc."
details: "Security Operations Center"
email: "secops@mycompany.com"
url: "https://mycompany.activeguard.cloud"
provider: "xorlab AG"
```

When you are done, click **Publish**. The template configuration becomes active within about one minute.

## Localization

In order to support localization for a particular language (`lang`) of a given country (`COUNTRY`), follow the steps below:

1. Click the `locale` folder to expand it and click the `default.yml` file.
2. In the right pane, select and copy the whole content of the file.
3. Use the context menu for the `locale` folder to add a new file.
4. Enter the name for the file in the dialog box that appears. Use the convention of `default_lang_COUNTRY.yml`, e.g., `default_pt_BR.yml` for the Brazilian Portuguese version of a file. Click **Create**.
5. Scroll down to the file you have just created, click it, and in the right pane paste the content of the previously copied content of the `default.yml` file. For each template entry in the new localization file, replace the default text with its translation. Click **Publish**. The new localization file becomes active within about one minute.

### Change the default language

The default language for notifications is defined in the `default.yml` file located in the `config` folder.

1. Click the `config` folder to expand it and click the `default.yml` file.
2. You will see only one entry: `defaultLocale`. Set it to your country code (currently, only `EN` and `DE` values are supported).
3. Click **Publish**. The new default language becomes active within about one minute.

### Using language headers

If you want to use another language in notifications for a particular report email, set the `x-ag-locale` email header in the report email to the locale desired for the template (this header must be set in the “outer” email that carries the reported email as attachment). For example, if you want to set the template for Swiss German, set the value to `de-CH`. For this reported email, xorlab Security Platform will then use the `default_de_CH.yml` instead of the `default.yml` template to pick the translation.

To read the language from a custom header, for example `my-custom-language-header` instead of `x-ag-locale`, you would need to edit `activeguard/core/active_guard.yml` the following way:

```yaml theme={null}
emailReporting:
  ## Header name for specifying locale (default = x-ag-locale)
  localeIdentifyingMailHeaderName: my-custom-language-header
```

Afterward, click **Publish**, then restart all MTAs. The `emailReporting` setting is in `active_guard.yml` and requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

## Managing Templates

### Disable a template

1. In the main `shared/email_templates` folder, click a `.yml` file for the notification template you want to disable.
2. In the right pane, go to the `category` keyword and change its value from `ANALYST_FEEDBACK` to `DEFAULT`.
3. Repeat these actions for every unwanted template and click **Publish**. The template configuration becomes active within about one minute.

### Create a new template

To create a new email notification titled `NOTIFICATION_NAME` for the `default` tenant:

1. Use the context menu for the `email_templates` folder to create a new file inside of it.
2. Enter `NOTIFICATION_NAME.yml` as the name for the file in the dialog box that appears. Click **Create**.
3. Scroll down to the file you just created, click it, and in the right pane paste the following content:
   ```yaml theme={null}
   # Note: The `id` must be the same template identifier as the file name.
   id: NOTIFICATION_NAME
   # The type of notification for the template (default: DEFAULT)
   # Supports: DEFAULT, ALERT, ERROR, WARN, CLEAR, ACK
   type: DEFAULT
   # The notification category for the template. Use ANALYST_FEEDBACK for feedback to reported emails.
   # Supports: DEFAULT, ANALYST_FEEDBACK, QUARANTINE_NOTIFICATION
   category: ANALYST_FEEDBACK
   # The following block is only supported for category ANALYST_FEEDBACK
   analystFeedbackConfig:
     displayText: "Template display text"
     # Choose any of the predefined verdicts
     verdict: "phishing"
     defaultSelection: true
   ```
4. Enter values that match the template usage—please refer to the [Template configuration](#template-configuration) section.
5. Go to the `locale` folder and, in each localization file of the `default` tenant, add a new entry for the new `NOTIFICATION_NAME` template using the YAML structure given below. For example, to localize the email notification into US English, add the following lines to `default.yml`:
   ```yaml theme={null}
   ################################################################################
   ## NOTIFICATION NAME                                                          ##
   ################################################################################
   NOTIFICATION_NAME:
     subject: "This is a subject example for a new template"
     preview: "This is a preview example for a new template"
     disclaimer: "This is a disclaimer example for a new template"
     kicker: "This is a kicker example for a new template"
     title: "This is a title example for a new template"
     summary: "This is a summary example for a new template"
     details:
       title: "This is a detailed info title example for a new template"
       paragraphs:
         - "This is the first paragraph example for a new template"
         - "This is the second paragraph example for a new template"
     providerNotice: "This is a provider notice example for a new template"
   ```
6. Click **Publish**. The new template becomes active within about one minute.

The table below explains the purpose of each key:

| Key | Content |
| :- | :- |
| `subject` | The subject of the email notification |
| `preview` | The notification email text content to be used as a preview text displayed in some email clients |
| `disclaimer` | “*You are receiving this email as a response…*” |
| `kicker` | The notification email text label to describe the response type, e.g., `ALERT` |
| `title` | The notification email title |
| `summary` | The notification email brief summary of the findings |
| `details:title` | The notification email title for the paragraphs providing further details of the findings |
| `details:paragraphs` | The notification email paragraphs providing further analysis details of the findings |
| `provider_notice` | “*This service is operated by…*” |

<Note>
  **Untranslated sections**

  Any template sections that are not translated will be rendered as empty in the final email notification.
</Note>

### Template configuration

The table below lists template parameters and their allowed values:

| Parameter | Values | Description |
| - | - | - |
| `type` | `DEFAULT` (green)<br />`ALERT` (red)<br />`ERROR` (red)<br />`WARN` (yellow)<br />`CLEAR` (green)<br />`ACK` (gray) | Used for color-coding the kicker (see the table above). You can [change the default colors](#change-the-colors) |
| `category` | `DEFAULT`: template is not used. The main usage of this value is to deactivate a built-in template<br />`ANALYST_FEEDBACK`: template can be sent to the reporter of a reported email (as a part of resolving a case)<br /> `QUARANTINE_NOTIFICATION`: used for an SSQ quarantine notification<br />`LEGACY_QUARANTINE_NOTIFICATION`: used for the legacy quarantine notifications via the `notifyUser` rule [context variable](/latest/context-vars) | Category of the template |
| `displayText` | "string" | Text to be displayed to the notification recipient |
| `verdict` | Name of a [verdict](/latest/verdicts) | Verdict that will be used for this template |
| `defaultSelection` | `true` or `false` | Determines if this template should be shown in the resolve dialog if there are multiple per verdict |

### Using variables in templates

It is possible to use some variables in notification templates so that notifications contain more details about the email messages they refer to. The table below lists all available variables. In order to use them, type `$email.<variable_name>`, e.g., `$email.subject` or `$email.senderAddress`, where you want the desired value to appear in the notification email.

| Variable | Description |
| - | - |
| `ggrid` | GGRID of the email |
| `sender` | Displayed sender’s name |
| `sentFrom` | Sender’s non-clickable address |
| `subject` | Email subject |
| `verdict` | Verdict given by xorlab after email analysis |
| `contextFields` | Indicators given by xorlab after email analysis |
| `comment` | Comment added by the case resolver (for feedback on reported emails only) |
| `mailbox` | Recipient’s mailbox |
| `tenant` | Recipient’s tenant (for feedback on reported emails only) |
| `locale` | Locale set for the notification email |
| `receivedTimeFormatted` | Time when the reported message was received |

<Note>
  **contextFields**

  The `contextFields` variable is an exception in the usage. Since it’s a map, you have to use the following pattern: `$email.contextFields.get("<indicator>")`, e.g., `$email.contextFields.get("dce.indicator.shortened")`.
</Note>

## Multi-Tenancy

Everything on this page edits the `default` files, which apply to all tenants.

To give a single tenant its own logo, colors, texts or footer, assign it an `emailTemplateStyle` in `guarded_tenants.yml` and create the matching files next to the `default` ones, instead of editing `default` itself. The customization steps are the same as above.

<Card title="Customize Tenant Notifications" icon="building" href="/latest/multi-tenancy-email-templates">
  Step-by-step guide for per-tenant text, style, logo and footer.
</Card>


# Notifications Overview
Source: https://docs.xorlab.com/latest/email-template-overview

When xorlab sends end-user notifications: report feedback, quarantine digests, and custom notifications.

xorlab can send email notifications to your end-users in the following situations:

* The user reports an email and will then get a feedback email from xorlab
* Quarantine notifications - for example daily digests
* When configured via custom rules

This page provides an overview over the existing templates that are used for the above purposes. To change or extend the built-in templates, have a look at [Template Customizations](/latest/email-template-modifications).

## Available Templates

The table below lists the built-in notification templates.

| Email notification | Description |
| - | - |
| `BEC` | For reports of business email compromise attacks |
| `BENIGN` | For reports of emails that do not contain anything suspicious |
| `CLOUD_STORAGE` | For reports of emails that contain a link to a cloud storage service |
| `EXTORTION` | For reports of extortion emails |
| `IMPERSONATION` | For reports of impersonation attacks |
| `POLICY_VIOLATION` | For reports of emails that violate company policies |
| `MALICIOUS` | For reports of emails that are suspicious |
| `MALWARE` | For reports of emails with an attachment that contains malware |
| `MARKETING` | For reports of emails of marketing newsletters |
| `PHISHING` | For reports of phishing emails |
| `REPORT_NOTIFICATION_ACKNOWLEDGEMENT` | To notify the user that xorlab received their report |
| `REPORT_NOTIFICATION_ERROR` | To notify the user that their report is missing a message to analyze |
| `SIMULATION` | For reports that are part of awareness campaigns |
| `SPAM` | For reports of spam emails |
| `USER_QUARANTINE_DIGEST` | To notify the user that xorlab quarantined multiple emails and put them into the SSQ |
| `USER_QUARANTINE_NOTIFICATION` | To notify the user that xorlab quarantined an email and put it into the SSQ |
| `VIP_FRAUD` | For reports of email attacks that impersonate people of your organization |
| `QUARANTINE_NOTIFICATION_IN` | Used for verdict-based quarantine notifications. Deprecated feature. |

## Example Emails

While all templates share the same structure, they differ in text and color depending on the type of notification. Below are a few examples:

### BENIGN

<img alt="Benign email" />

### PHISHING

<img alt="Phishing email" />

### REPORT\_NOTIFICATION\_ACKNOWLEDGEMENT

<img alt="Report Notification Acknowledgement" />

### USER\_QUARANTINE\_DIGEST

<img alt="SSQ Daily Digest" />

## Directory structure

Email notification templates are stored in the `shared/email_templates` directory, accessible via the [Expert Editor](/latest/expert-editor).

## Folder Structure

```text theme={null}
  shared/email_templates
  ├── BEC.yml                              # Template configuration files.
  ├── [... other templates ...]
  ├── config
  │   └── default.yml                # Default language settings
  |                                        
  ├── info
  │   └── default.yml                # Company information for footers
  |                                        
  ├── locale
  |   └── default_it.yml             # Italian localization file.
  |   └── default_fr.yml             # French localization file.
  │   └── default_de.yml             # German localization file.
  |   └── default_en.yml             # English localization file.
  |                                        
  ├── style
  │   └── default.yml                # Branding and styling
  |                                        
  ├── [... other templates ...]
  └── VIP_FRAUD.yml
```

## Folder Descriptions

* `config`  – Defines the default language for notifications.
* `locale` – Contains localized strings for different languages.
* `style` – Controls visual elements such as colors, fonts, and logos.
* `info` – Stores organization details like name, contact email, and links, used in the footers.
* Template files – Each template (e.g., `BEC.yml`, `PHISHING.yml`) contains its configuration.

## Multi-Tenancy Support

If your organization uses multiple tenants, you can customize templates per tenant. Tenant-specific customizations are controlled by the `emailTemplateStyle` attribute. By default, templates apply as `default` to all tenants, but you can introduce unique identifiers to manage styles, localization, and branding for other tenants.

For more information, have a look at [Customize Tenant Notifications](/latest/multi-tenancy-email-templates).


# Trigger Test Notifications
Source: https://docs.xorlab.com/latest/email-template-preview-notification

Send a test notification to a mailbox to verify auto-login, template layout, and localization.

The notification contains a dummy message and, depending on the selected template, may include an AutoLogin link.

## Prerequisites

* You need an active, signed-in xorlab administrator session in the same browser. This endpoint is not publicly accessible and cannot be called anonymously.
* To include an AutoLogin link in the test notification, [Auto-Login](/latest/authentication-auto-login-link) must be enabled for the tenant.

<Warning>
  **Use with care**

  The test notification is delivered to whichever mailbox you specify in the `mailbox` parameter, and depending on the selected template and tenant configuration it may contain a valid AutoLogin link for that mailbox. Only trigger it for mailboxes you are entitled to access.
</Warning>

## Endpoint URL

```
https://<your.xorlab.instance>/api/v2/emailNotification/v1/sendQuarantineNotification
```

## Supported Request Parameters

* **mailbox** (string, required): The recipient mailbox.
* **template** (string, optional): Defaults to `USER_QUARANTINE_NOTIFICATION`. Other possible values include:
  * `VIP_FRAUD`
  * `SPAM`
  * `POLICY_VIOLATION`
* **locale** (string, optional): The language of the notification. Defaults to the system's default language.

## Example Requests

### Basic request

Sends a notification using the default template and system language:

```
https://<your.xorlab.instance>/api/v2/emailNotification/v1/sendQuarantineNotification?mailbox=info@example.com
```

### Request with all parameters

Sends a localized notification using a specific template:

```
https://<your.xorlab.instance>/api/v2/emailNotification/v1/sendQuarantineNotification?mailbox=info@example.com&locale=de&template=POLICY_VIOLATION
```


# Change Sender Address
Source: https://docs.xorlab.com/latest/email-template-sender-addresses

Set a per-tenant sender address for feedback emails, quarantine notifications and digests, and rule-triggered notification messages.

<Accordion title="Sender address defaults">
  In the following code blocks, `<sender-address>` can be a full email address, or just a mailbox such as `notification` or `notification@` — in that case, it is completed using the tenant's primary [guarded domain](/latest/terminology#guarded-domains), the first entry under `domains` for that tenant in `guarded_tenants.yml`. If you leave the setting out entirely, the default shown in each section below applies.
</Accordion>

## Feedback emails

Feedback emails are sent after a user reports a suspicious email. They can be manually triggered by an analyst through resolving a case as well as automatically generated through a campaign or an auto-close rule. By default, these emails are sent from `notification@<domain>`, with `<domain>` referring to the tenant's primary domain.

If you like to customize the sender address, add the following block (if it does not already exist) to the corresponding tenant or config set in `shared/guarded_tenants.yml`:

```yaml guarded_tenants.yml theme={null}
emailReporting:
  notificationAddress: <sender-address>
```

Afterward, click **Publish**. The new configuration becomes active within about one minute.

### SMTP auth for feedback emails

If you want the feedback emails to be sent to an SMTP server requiring authentication, please follow the steps outlined in [SMTP auth for specific email addresses](/latest/smtp-configuration#smtp-auth-for-specific-email-addresses).

## Quarantine notifications

Quarantine notifications are sent to the end-user when an email addressed to them has been put in quarantine, and this is also the sender address used for quarantine digests. By default, these emails are sent from `quarantine@<domain>`, with `<domain>` referring to the tenant's primary domain.

If you like to customize the sender address, add the following block (if it does not already exist) to the corresponding tenant or config set in `shared/guarded_tenants.yml`:

```yaml guarded_tenants.yml theme={null}
quarantine:
  notifications:
    notificationAddress: <sender-address>
```

Afterward, click **Publish**. The new configuration becomes active within about one minute.

## Custom bounce and notification messages

The xorlab Security Platform rule language allows configuring custom bounce or notification messages that are triggered for certain events (for example, when using the rule context keys `SenderNotification.Template` or `ReceiverNotification.Template`). These emails share the sender address configured for [feedback emails](#feedback-emails): by default `notification@<domain>`, and customizable through the same `emailReporting.notificationAddress` property in `shared/guarded_tenants.yml`.


# Evaluate xorlab
Source: https://docs.xorlab.com/latest/evaluate-xorlab

For teams who have not decided yet: how a trial is set up, how long each phase takes, and what you can measure the results against before anything is blocked.

You can find out what xorlab catches without committing to it. The platform runs alongside the filtering you already have, analyzes your real email traffic, and reports what it would have done — no MX record change, no software on your servers, and no email blocked until you decide it should be.

The setup is short. Most of the trial is you reading results.

## How a trial runs

<div>
  <div>
    <p>Day 0</p>

    <p>Decide where xorlab runs</p>

    Two deployment options, you get the same results for both:

    * **xorlab SaaS** — hosted and operated by xorlab. Nothing to provision, so it is the quickest way into a trial.
    * **On-premises** — you run the xorlab Control Center (XCC) and one or more xorlab MTAs on your own virtual infrastructure.
  </div>

  <div>
    <p>Day 0</p>

    <p>Ask for an instance</p>

    Write to [sales@xorlab.com](mailto:sales@xorlab.com). Your own trial instance can be ready as early as the next working day.
  </div>

  <div>
    <p>Day 1</p>

    <p>Connect your email flow</p>

    You choose how far into the mail flow xorlab goes. Both options are reversible in minutes, and neither touches your MX records:

    * **Monitoring Mode** — xorlab receives a copy of every email as an additional BCC recipient and drops it after the analysis.
    * **Inline Mode** — xorlab sits in the mail flow but delivers every email anyway, including the ones it would have quarantined.

    On Microsoft 365, run [Retrospective Email Scanning](/latest/m365-retrospective-email-scanning) before you connect the mail flow: xorlab imports the past months of email from the mailboxes and analyzes them, so the trial starts with history behind it.
  </div>

  <div>
    <p>Some days</p>

    <p>Finish the learning phase</p>

    The [Relationship](/latest/concepts-relationship) model and [Local Reputation](/latest/concepts-local-reputation) have to observe your traffic before detection can rely on them. Live traffic alone gets them there in a matter of days, on any deployment. If you imported past M365 email in the previous step, they are ready from the moment the mail flow is connected.
  </div>

  <div>
    <p>Once it has learned</p>

    <p>See what is getting through</p>

    xorlab assigns a [verdict](/latest/verdicts) and a confidence to every email, and assigns categories to the malicious ones: Phishing, Malware, BEC, VIP Fraud, Impersonation, Extortion, Spam, etc. are separate verdicts you can filter and count. Because nothing is blocked yet, each one is a message that reached the mailbox regardless of what you run today.

    For any of them, xorlab shows the indicators and reasoning behind the decision — see [Understanding an Email Verdict](/latest/understand-verdict).
  </div>

  <div>
    <p>Two weeks</p>

    <p>Compare it with what you run today</p>

    We recommend two weeks of side-by-side traffic: long enough to cover the weekly rhythm of your mail, short enough that the trial does not stall. Compare it either way:

    * **In xorlab** — search the traffic, save what you are tracking as a saved search, and export it to work through outside the platform.
    * **In your SIEM** — stream the verdicts and the analysis results extracted over Syslog, then put them next to what your existing controls reported.

    Write to [support@xorlab.com](mailto:support@xorlab.com) and we will go through the evaluation with you.
  </div>

  <div>
    <p>Along the way</p>

    <p>Tune it to your own risk appetite</p>

    You can shift the balance between catching more and flagging less, and correct individual decisions as they come up — see [Fix a False Positive](/latest/fix-false-positives) and [Fix a False Negative](/latest/fix-false-negatives).
  </div>

  <div>
    <p>Go live</p>

    <p>Switch protection on</p>

    When the results convince you, protection is a configuration change rather than a new project. If you ran in Inline Mode, enabling a switch is all it takes, and quarantining is active about a minute later. From Monitoring Mode, you switch to Inline Mode first. Nothing else about the integration changes.
  </div>
</div>

## Two ways to connect your mail flow

Both let you evaluate on live traffic without blocking anything. The difference is how much of the final setup you have already built by the end of the trial.

| | Monitoring Mode | Inline Mode |
| :- | :- | :- |
| Where xorlab sits | Out of band. It receives a BCC copy and drops it after the analysis | In the mail flow. Every email passes through and is forwarded on |
| Your mail flow | Untouched | Carries one more hop |
| MX records | Unchanged | Unchanged, unless xorlab replaces your gateway on premises |
| What users notice | Nothing at all | Nothing at all |
| Import of past M365 email | Available | Available |
| Going live afterward | Requires switching to Inline Mode | Just activate a parameter |
| Pick it when | Any change to the mail flow needs its own approval | You want the trial to end in one configuration change |

## What the trial does not touch

* **Your MX records.** On M365, email keeps arriving at Microsoft, which hands it to xorlab and takes it back for delivery.
* **Your current filtering.** Your existing filters keep running. xorlab is layered on top, which is what makes the comparison possible.
* **Your servers, clients and mailboxes.** Nothing is installed and nothing is migrated. Reporting uses the button your users already have.
* **Your outbound sending identity.** On M365, outgoing email still leaves through Microsoft, so SPF and DKIM stay as they are. Same for on-premises.

Ready to see it on your own traffic? Write to [sales@xorlab.com](mailto:sales@xorlab.com).


# Feature Overview
Source: https://docs.xorlab.com/latest/feature-overview

A map of what the platform does, from detection layers through analyst tooling to end-user self-service.

xorlab is designed as a unified workflow, where multiple detection layers — relationship modeling, local reputation, sandboxing, campaigns, Abuse Mailbox automation, SSQ, and contextual banners — reinforce each other to provide strong, context-driven protection.

While the platform works best when all components are combined, each feature can be activated individually, giving you full flexibility to match your security needs, infrastructure, and rollout strategy.

***

## Feature overview

<CardGroup>
  <Card title="Inbound Email Security" icon="shield-check" href="#inbound-email-security">
    Protects your organization with a contextual detection engine that catches advanced e-mail-based threats with a very low false positive rate.
  </Card>

  <Card title="Campaigns" icon="filter" href="#campaigns">
    Campaigns let analysts turn any search query into a precise detection rule that overrides default behavior for exactly the emails they choose.
  </Card>

  <Card title="Full Transparency" icon="magnifying-glass-chart" href="#full-transparency">
    Shows the reasoning behind every verdict in a single detail view, from the sender relationship down to the individual rules.
  </Card>

  <Card title="Sandbox" icon="bug" href="#sandbox">
    Analyzes suspicious files in a secure, isolated environment to detect hidden or unknown malware.
  </Card>

  <Card title="Self-Service Quarantine" icon="user" href="#self-service-quarantine-ssq">
    Lets users safely manage their quarantined emails — including encrypted attachments and request-release workflows.
  </Card>

  <Card title="Case Isolation" icon="envelope" href="#case-isolation">
    Allows analysts to remove harmful emails directly from a user’s mailbox via the Microsoft Graph API.
  </Card>

  <Card title="Abuse Mailbox" icon="bell" href="#abuse-mailbox">
    Enables automated analysis and triaging of user-reported emails and can provide instant feedback.
  </Card>

  <Card title="Contextual Banners" icon="triangle-exclamation" href="#contextual-banners">
    Displays intelligent, context-driven email warnings that reduce user mistakes without creating alert fatigue.
  </Card>

  <Card title="Open Integrations" icon="hexagon-nodes" href="#open-integrations">
    Connects to the rest of your stack over standard protocols — SMTP, Syslog, REST, SAML, and Microsoft Graph.
  </Card>
</CardGroup>

***

## Inbound Email Security

xorlab stops the full range of email attacks, with a strong focus on sophisticated targeted attacks and zero-day exploitation.

Inbound Email Security is the core of xorlab’s platform. It protects your organization from phishing, spoofing, and malware by understanding how your organization normally communicates and using that context to detect anomalies.

Instead of relying on static indicators or threat feeds, xorlab builds a dynamic model of trusted communication (Relationship), learns what content is common in your environment (Local Reputation), and verifies every sender using authentication standards such as SPF, DKIM, and DMARC.

With this information xorlab is able to reliably detect:

* Executive and employee impersonation
* Credential phishing and brand spoofing
* Ransomware, sabotage, and industrial espionage
* Email Account Compromise

Learn more about how the xorlab detection works: [Concepts Overview](/latest/concepts-overview)

How to: [Integrate xorlab into your mail flow](/latest/setup-integration-overview)

<img alt="inbound-security" />

## Campaigns

Campaigns allow analysts to transform any search query into a targeted policy that adapts xorlab’s detection to specific business needs. Because campaigns are built directly from the search engine, anything you can search for — sender patterns, domains, tags, file behavior, topics, authentication signals, and more — can be enforced as a rule. This makes campaigns a precise tool for handling edge cases, reducing false positives, blocking recurring threats, and automating responses without affecting global detection logic.

Campaigns evaluate emails in real time and override default behavior only when the defined conditions match. Each campaign specifies exactly what should happen: quarantine, deliver, rewrite, or classify a reported message. They bring structure, auditability, and repeatability to analyst decisions, especially when dealing with greymail, unauthenticated system alerts, third-party workflows, or post-incident cleanups.

How to: [Using Campaigns](/latest/campaigns)

## Full Transparency

Every email xorlab processes gets a verdict and a confidence, and the detail view shows what produced them. Analysts do not have to trust a score: the sender relationship, the authentication results, the indicators that were found, and the analysis of every attachment and link are on one screen, and from there each individual rule that contributed to the decision can be read.

That transparency is what makes the decision defensible outside the SOC. It lets you tell an employee why their report was closed, a user why their email was held back, and an auditor why the platform did what it did — and it is the same view from which an analyst isolates a case or builds a campaign.

Learn more: [Understanding an Email Verdict](/latest/understand-verdict)

How to: [Fix a False Positive](/latest/fix-false-positives)

<img alt="Detail View" />

## Sandbox

The Sandbox detects malicious behavior in email attachments that can’t be reliably identified through static analysis alone. It complements xorlab’s static analysis by executing suspicious files in a secure, isolated environment and observing how they behave. This helps uncover hidden malware, zero-days, and evasive techniques that would otherwise go unnoticed.

<img alt="Sandbox" />

## Self-Service Quarantine (SSQ)

Self-Service Quarantine gives end-users a safe and controlled way to see, review, and release their own quarantined emails without relying on the security team. It reduces unnecessary IT tickets, speeds up legitimate mail delivery, and provides transparency so users understand why messages were held.

SSQ integrates tightly with xorlab’s detection logic, ensuring that risky messages stay blocked while low-risk cases can be handled by users directly. Analysts remain in full control through configurable permissions and optional “Request Release” workflows for sensitive quarantines. SSQ also supports encrypted attachments, shared mailboxes, customizable notifications, and seamless access via auto-login or SSO.

Learn more: [SSQ Overview](/latest/ssq-overview)

How to: [Handle Release Requests](/latest/handling-release-requests)

<img alt="ssq" />

## Abuse Mailbox

The Abuse Mailbox helps security teams handle user-reported emails quickly and consistently by combining automated triage with analyst review. Reported messages are grouped into clear cases, enriched with xorlab’s analysis, and prioritized so analysts can focus on the few that truly require attention.

Reports can be resolved automatically using verdict-based rules or campaigns, which apply precise logic to classify and respond to common patterns. Automated feedback keeps employees informed and reduces repetitive work for the SOC.

When manual review is needed, analysts get all relevant context — authentication, relationship signals, file analysis, link reputation, and more — in a single view. The result is faster investigations, consistent decisions, and a scalable way to handle large volumes of reports.

How to: [Handle the Abuse Mailbox](/latest/abuse-mailbox)

Integrate [Abuse Mailbox with M365](/latest/m365-reporting-integration)

Integrate [Abuse Mailbox On-Premises](/latest/on-prem-reporting-integration)

<img alt="Abuse Mailbox" />

## Case Isolation

Case Isolation allows analysts to remotely remove harmful emails from a user’s mailbox through the Microsoft Graph API. Once enabled, an “Isolate” button appears in every message detail view, making it easy to take immediate action whenever a threat is confirmed. Isolation is performed directly against the user’s mailbox

How to: [Activate Case Isolation](/latest/m365-case-isolation)

## Contextual Banners

Contextual Banners add targeted security insights directly inside the email body, giving users clear and actionable warnings without overwhelming them. Instead of generic “be careful” labels, banners highlight specific risks detected by xorlab — such as low sender trust, suspicious attachments, or potential impersonation. They appear only when relevant, reducing alert fatigue while increasing user awareness.

Each banner is tied to a precise detection rule and surfaced through mail flow rules in Exchange. Analysts stay in full control by enabling, disabling, or excluding banners per sender, recipient, or severity level. Banners integrate seamlessly with xorlab’s trust, reputation, and content analysis engines to surface context users normally don’t see.

How to: [Enable Contextual Banners](/latest/detection-contextual-banners)

<img alt="Abuse Mailbox" />

## Open Integrations

xorlab is not a closed appliance. Every part of the platform is reachable through interfaces your existing tools already speak, which means it fits into the stack you have rather than requiring one built around it.

* **Mail flow over SMTP**, in front of, behind, or alongside Microsoft 365, Exchange, or any standards-compliant gateway — inline or purely observing.
* **The full event stream over Syslog** in JSON or CEF: verdicts, SMTP transactions, extracted threat intelligence, and a complete analyst and admin audit trail. Any SIEM can ingest it without a vendor-built connector.
* **A REST API** so SOAR playbooks and scripts can manage blocklists, whitelists, and VIP lists without a human in the web interface.
* **SAML 2.0 and LDAP** for single sign-on, with role and tenant mapping from your identity provider.
* **Microsoft Graph** for case isolation, retrospective scanning, and quarantine handling, through a single app registration in your own tenant.
* **Threat intelligence in both directions** — VirusTotal and Spamhaus DQS enrich analysis, while indicators observed in your own mail are exported for use elsewhere.

Learn more: [What xorlab Connects To](/latest/integrations-overview)


# File Analysis
Source: https://docs.xorlab.com/latest/file-analysis

Upload files to xorlab for static analysis and Sandbox analysis using the same engine that scans email attachments.

The file analysis that is also used to analyze email attachments supports many static and dynamic analysis techniques. From the cracking of encrypted file formats to the detection of different static file properties, xorlab performs a thorough analysis of the files provided. Archives and file formats that support embedded objects are extracted and iteratively analyzed. Sandbox analysis for PDF, Word, and Excel file formats is performed and the runtime behavior is assessed.

One of the unique features of the Sandbox in xorlab is the detection of exploits without giving the attacker the opportunity to execute an evasive native code payload.

To use the file analysis, just click the **File Upload** item in the left pane of the main XCC page, and click the **Upload Files** frame to select a file to be uploaded. You can also drag and drop the file to this area:

<img alt="File Upload tool" />

After uploading the file (multiple uploads are possible), the file will appear in the lower part of the screen in the “pending” state until the entire scan is completed. Then, the file will receive a VERDICT and a RISK score. Furthermore, the analyzed files are also tagged with informative and classification tags (you will find the full list of tags at the end of this article).

When you click the file in the file list, its detailed view appears:

<img alt="Analyzed file details" />

The most important information—verdict and risk—is displayed at the top. The goal of the detail view is to show all the relevant information in a condensed manner but to allow the analyst to further dig down to the relevant details. The `archive.zip` file contains the artifacts of the scan (logs, pcap file, screenshots, etc.).

By clicking the row of the file, the view will expand and show all the details related to the file (including video and screenshots and all the system events of the Sandbox scan):

<img alt="Nested file details" />

## File analysis verdicts

Besides the risk score, the VERDICT of file analysis indicates what xorlab Security Platform has found and how the file is classified:

| VERDICT | Description |
| :- | :- |
| `MALWARE (D)` | Malware found based on dynamic runtime behavior |
| `MALWARE (S)` | Malware found based on static analysis (e.g., YARA rule) |
| `EXECUTABLE` | Executable file format found |
| `SCRIPT` | Script file format found |
| `SHORTCUT` | Shortcut file format found |
| `VBA SCRIPT`  (in red) | Dangerous VBA script found (starts a new process, initiates network connection, or performs other potentially malicious operation) |
| `VBA SCRIPT`  (in orange) | VBA script found |
| `EXT. OBJECT` | Office format referencing remote object (e.g., remote video) |
| `DDE` | Office format using DDE |
| `EMB. OBJECT` | Office format with an embedded object |
| `ACTIVEX` | ActiveX object found |
| `FLASH` | Flash object or file format found |
| `ENCRYPTED` | Encrypted file format found |
| `ARCHIVE` | Archive file format (e.g., `.zip`, .`7z`, etc.) |
| `LEGACY ARCHIVE` | Legacy archive file format (e.g., `.rar`) |
| `DOCUMENT` | Document file format found |
| `FILE` | No specific classification |


# Fix a False Negative
Source: https://docs.xorlab.com/latest/fix-false-negatives

React to a missed threat so that xorlab quarantines similar emails in future.

If you are looking for a more general approach to tune the overall detection, have a look at [Tune Detection](/latest/detection-tuning).

Below we list the most common measures for a false negative and when they should be applied.

<Note>
  **Report Misclassification**

  We recommend to report all false negatives to xorlab via [Reporting a Misclassification](/latest/reporting-misclassification). This helps improving the detection in a sustainable way.
</Note>

## Add sender to blacklist

If you expect more false negatives from the same sender, add its address to the sender blacklist.

**Requirements**:

1. The sender does not send legitimate or wanted emails.

**Action**:

1. Open the email in the detail view.
2. Press <kbd>B</kbd>, or click on the three dots in the upper right and choose **Blacklist**.
3. Select **Sender address blacklist** and save. For the accepted entry formats and how subdomain matching behaves, see [Blacklists](/latest/blacklists).

## Add link to blacklist

If you expect more false negatives with the same phishing link, add the link to the link domain blacklist.

**Requirements**:

1. The link domain is not used in legitimate emails.

**Action**:

1. Open the email in the detail view.
2. Click on the **LINKS** tab.
3. Select the corresponding links and click on **Blacklist**. This adds them to the **Link domain blacklist**, see [Blacklists](/latest/blacklists).

## Create a campaign

Create a campaign when the false negatives cannot be tied to a specific sender, or if a sender might send both legitimate and unwanted emails.

The full guide about campaigns can be found here: [Campaigns](/latest/campaigns).

**Requirements**:

1. None. Campaigns can always be used, but they require a bit more effort for creation and life-cycling.

**Action**:

1. Create a search query that matches all the required false negatives. This can differ a lot from case to case. Some examples:
   1. Use the built-in **content similarity**. This is the go-to method for all false negatives that vary in sender, display name, subject, etc. For this, open the email in the detail view and click on **SIMILAR**.
   2. Often the display name or parts of the subject stays the same through a wave of similar emails. This can be used in a search query like this: `from.displayname:Abc AND subject:"*Password Reset*"`.
   3. Sometimes the attackers re-use some URL patterns in the same wave. This can be leveraged with a query like this: `link:"*/special/url-path/*"`.
2. Create a campaign based on the search and set the action to **Quarantine**. If you use the SSQ, choose the quarantine name such that the end-users can or cannot release the email.


# Fix a False Positive
Source: https://docs.xorlab.com/latest/fix-false-positives

React to a wrongly quarantined email so that xorlab stops quarantining that kind of message.

If you are looking for a more general approach to tune the overall detection, have a look at [Tune Detection](/latest/detection-tuning).

Most false positives can be resolved by following the primary measures below in order. However, in certain special cases (described in the second part), you may need to use a special approach.

<Note>
  **Report Misclassification**

  We recommend to report all false positives to xorlab via [Reporting a Misclassification](/latest/reporting-misclassification), where possible. This helps improving the detection in a sustainable way.
</Note>

## Primary measures

### 1️⃣Let the system handle it

xorlab learns whenever an email is released from the quarantine. It will reduce the chance that the next email from the same sender will be quarantined again.

<Note>
  **Auto-learning**

  For a specific sender: The more emails are released, the less aggressive the detection is for that sender. However, it will never fully disable all checks.
</Note>

Therefore the first step is to just release the email from the quarantine, and this might fix the false positive.

**Requirements**:

1. The sender needs to have authentication (`#auth`).
2. The false positives must come from the same sender address.

**Action**:

1. Release the email from quarantine.

### 2️⃣Add sender to the low trusted sender list

This is the go-to action for most situations that do not resolve on its own. It will reduce the phishing and spam detection for that sender to a minimum, but keeps malware and BEC rules still active. For the full list of trust levels and what each one changes, see [Trusted Senders and Infrastructure](/latest/trusted-senders-infrastructure).

**Requirements**:

1. The sender needs to have authentication (`#auth`).
2. You do not expect to receive malicious emails from there.
3. It is not a BEC or malware false positive. (1)
4. Some of the more aggressive malware rules will also be deactivated by the *Low trusted sender* list. Therefore in some cases the list also works for malware verdicts.

**Action**:

1. Open the email in the detail view.
2. Press <kbd>W</kbd>, or click on the three dots in the upper right and choose **Whitelist**.
3. Select **Low trusted sender addresses** and save.

### 3️⃣ Create a campaign

Campaign are used when the requirements for the *Low trusted sender* list are not fulfilled. It allows you to let through very specific emails by creating a search that matches only the desired emails. The full guide about campaigns can be found here: [Campaigns](/latest/campaigns).

<Warning>
  **Campaigns overwrite built-in detection**

  A campaign overwrites all built-in detections, therefore be careful with campaigns that set the action to **Deliver**. They should  be as narrow as possible to only match the desired emails.
</Warning>

**Requirements**:

1. None. Campaigns can always be used, but they require a bit more effort for creation and life-cycling.

**Action**:

1. Find aspects of the email that are present in all of the false positives. Examples are: subject keywords, display name, sender address, etc.
2. Create a search query that is as specific as possible and only matches the false positives. Examples: `from:sender@example.com AND subject:*Notification*`.
3. Create a campaign for that search query and set the action to **Deliver**.
   1. Tip: You can still exclude certain verdicts from the Deliver campaign, for example to exclude malware: `from:sender@example.com AND subject:*Notification* AND NOT #malware`.

## Special cases

### Malware false positives with #networkactivity

If an attachment makes suspicious DNS requests in the Sandbox, the email might be quarantined even though it is legitimate. In such cases, you can allow specific domains for DNS requests.

**Requirements**:

1. The malware false positive needs to have the tag `#networkactivity`.

**Action**:

1. For the affected email, open the **Attachments** tab and click on the attachment with the red Sandbox symbol.
2. In the new dialog, copy the domain marked as `SUSPICIOUS` in the **Network** tab.
3. Go to **Settings → Lists → Whitelists** and add the domain to the **Dynamic DNS request whitelist**, see [Whitelists](/latest/whitelists).


# Fraud Keywords
Source: https://docs.xorlab.com/latest/fraud-keywords

Customize the keyword list that marks user-reported incidents as potential fraud.

Mark user incidents as fraud if they contain certain keywords. These keywords can be customized in **Settings → Lists → Reported**.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Potential fraud keywords** | User-reported emails are marked as `Fraud` if they contain any of the keywords in this list | Keyword as `String`, e.g., `monorail` |


# Handling Release Requests
Source: https://docs.xorlab.com/latest/handling-release-requests

Review end-user requests to release quarantined emails, and decide whether to release or deny them.

If enabled, end-users can request the release of quarantined emails via the SSQ portal. This functionality can be enabled separately for each verdict, and works only for emails the user cannot release themselves.

## End-user view

For emails in an eligible quarantine, the end-user sees a Request Release button in the upper-right corner.

* After clicking the button, the email status changes to: `RELEASE REQUESTED`
* Once an analyst reviews the request, the status updates to:

  * `RELEASE APPROVED` – if the analyst releases the email
  * `RELEASE DENIED` – if the analyst denies the request (the email stays in quarantine)

<img alt="Request Release" />

## Analyst workflow

The summarized workflow for an analyst looks like this:

1. You get notified about the newly requested release. There are a few different options:

   * Via email, triggered by each release request. This can be enabled by an admin user as described in [Enable request notifications](/latest/ssq-request-release#enable-request-notifications).
   * By manually searching for `status:releaserequested`.
   * By creating and using a saved search for `status:releaserequested`.

2. You analyze the email to see if it is not harmful. The page [Understand an Email Verdict](/latest/understand-verdict) provides more details to understand why a certain verdict was set.

3. If it is benign, you release the email via the **Release** button.

   <img alt="Request Release" />

4. If it is malicious, you deny the request via the **Deny Release** button.

Below you can find all status related to the release request feature, such that you can use them in the search:

| Status | Description |
| - | - |
| `RELEASE REQUESTED` | An end-user requested the release for this email, but no action has been taken yet. |
| `RELEASE APPROVED` | An analyst approved the request. The email has been released. |
| `RELEASE DENIED` | An analyst denied the request. The email is still quarantined. |

<Tip>
  **Saved Search**

  Create a saved search for the status `RELEASE REQUESTED` to quickly access all pending requests.
</Tip>


# Switch Between Inline and Monitoring Mode
Source: https://docs.xorlab.com/latest/inline-and-monitoring-mode

Switch between monitoring mode, which observes a copy out of band, and inline mode, which acts on the email your recipients receive.

xorlab can run in either of the following modes:

* **Monitoring**: xorlab is located out-of-band of the mail flow and is only used to monitor the traffic (it cannot intervene in your mail flow). Usually, it receives the email traffic as an additional BCC recipient and the copies are dropped after processing. This mode allows email traffic monitoring with low impact on the infrastructure. Detection and the configured actions still run in full, so emails do get the `QUARANTINED` decision — see [Decisions and quarantine in Monitoring mode](#decisions-and-quarantine-in-monitoring-mode).
* **Inline**: xorlab is inline in the mail flow and actively filters emails. This mode is configured whenever xorlab is used for inbound email security. Emails are forwarded after they have been processed.

## Monitoring mode

The following changes are necessary to run xorlab in Monitoring mode:

1. Open [Expert Editor](/latest/expert-editor) and navigate to the `activeguard/core/active_guard.yml` file.

2. Under the relevant SMTP handler, set `senderRecipientExtraction.recipientExtraction: MAIL_HEADER` and `senderRecipientExtraction.senderExtraction: HEADER`:

   <Warning>
     For M365 integrations, the value for `senderRecipientExtraction.senderExtraction` should be `MAIL_ENVELOPE`.
   </Warning>

   ```yaml active_guard.yml theme={null}
   scanSources:
     smtp:
       port: 10025
       handler:
         smtpReport: {}
       # The following line activates Monitoring mode.
       # All emails will be dropped after processing.
         smtpOffline:
           senderRecipientExtraction:
             # Get the recipients from the TO and CC headers
             recipientExtraction: MAIL_HEADER
             # Get the envelope `FROM` from email headers
             senderExtraction: HEADER
   ```

3. Set up SMTP routing for Monitoring mode: see *Set Up Email Routing in xorlab* for [on-premises](/latest/on-prem-smtp#configure-for-monitoring) or [Microsoft 365](/latest/m365-smtp).

4. [Disable delivery status notifications](#disable-delivery-status-notifications).

5. Click **Publish**. The monitoring mode configuration becomes active within about one minute.

This configuration sets xorlab Security Platform into Monitoring mode. For more information about sender and recipient extraction, please see the [next section](#sender-and-recipient-extraction).

It is possible to omit the `handler` block as it is set to `smtpOffline {}` by default:

```yaml active_guard.yml theme={null}
scanSources:
  smtp:
    port: 10025
    ## Default handler configuration - applied if nothing else specified
    #handler:
    #- smtpReport
    #- smtpOffline
```

<Warning>
  **Envelope-from**

  It is important to provide xorlab Security Platform the original envelope `FROM` in Monitoring mode. With the above configuration, xorlab tries to derive it from email headers. Further possibilities are described in the next chapter.
</Warning>

### Sender and recipient extraction

In Monitoring mode, emails are often forwarded as copies (BCC) to xorlab. In this case, it is possible that the SMTP envelope `FROM` and recipient information have been overwritten as a part of the BCC forward.

The envelope `FROM` might be something like `MAILER-DAEMON@gateway.internal` and the envelope recipient is xorlab itself like, for example, `emails@xorlab.internal` when the email arrives at xorlab. Therefore, you need to configure xorlab to get the envelope `FROM` and recipients from the correct location:

```yaml active_guard.yml theme={null}
scanSources:
  smtp:
    port: 10025
    handler:
      smtpOffline:
        senderRecipientExtraction:
          recipientExtraction: MAIL_HEADER
          senderExtraction: HEADER
```

<Warning>
  For M365 integrations, set `senderRecipientExtraction.senderExtraction` to `MAIL_ENVELOPE` instead of `HEADER`.
</Warning>

<Note>
  **Wrong configuration**

  The usual symptom of a wrong envelope `FROM` configuration is a missing or wrong envelope `FROM` shown in the detail view of an email in XCC. Consequently, xorlab cannot do various checks like, for example, SPF verification.
</Note>

The following values are supported for `senderRecipientExtraction.senderExtraction`:

| Value | Default | Description |
| :- | :- | :- |
| `HEADER` | Default for `smtpOffline` (Monitoring mode) | Try to get the original envelope `FROM` from email headers |
| `MAIL_ENVELOPE` | Default for `smtpInline` (Inline mode) | Take the envelope `FROM` from the SMTP `MAIL FROM` command |

The following values are supported for `senderRecipientExtraction.recipientExtraction`:

| Value | Default | Description |
| :- | :- | :- |
| `MAIL_HEADER` | Default for `smtpOffline` (Monitoring mode) | Use the `TO` and `CC` headers to get all recipients |
| `MAIL_ENVELOPE` | Default for `smtpInline` (Inline mode) | Take the recipients from the SMTP `RCPT TO` command |

For reported email handlers, `senderRecipientExtraction.reporterExtraction` controls how the sender of the report itself is extracted. Supported values are `MAIL_ENVELOPE` and `FROM_HEADER`.

You can also provide the original envelope `FROM` through specific headers by matching them with `senderHeaderNamePattern`:

```yaml active_guard.yml theme={null}
scanSources:
  smtp:
    port: 10025
    handler:
      smtpOffline:
        senderRecipientExtraction:
          recipientExtraction: MAIL_HEADER
          senderExtraction: CUSTOM_HEADER
          # Specify a custom header that contains the original envelope `FROM`
          senderHeaderNamePattern: "x-original-envelope-from"
```

It is also possible to use a regex when you have multiple custom headers to check; provide that regex as the value for `senderHeaderNamePattern`:

```yaml active_guard.yml theme={null}
          senderHeaderNamePattern: x-one-envelope-from|x-other-envelope-from
```

The above expression matches either first or second header.

### Disable delivery status notifications

For Monitoring mode, we recommend to generally disable delivery status notifications. This includes bounce emails. This will make sure that xorlab will never send delivery status notifications back to the sender when being in Monitoring mode.

1. Open the Expert Editor and navigate to the  `activeguard/mta/startup_cfg/postfix_custom/master.cf` file.
2. Find the three lines starting with `bounce unix`, `defer unix`, and `trace unix`, and set the last word on all three lines to `discard`:
   ```shell theme={null}
   # Disable all delivery status notifications
   bounce    unix  -       -       n       -       0       discard
   defer     unix  -       -       n       -       0       discard
   trace     unix  -       -       n       -       0       discard
   ```
3. Open the `activeguard/mta/startup_cfg/postfix_custom/main.cf` file and comment out (e.g., using the **Ctrl+/** or **Cmd+/** keyboard shortcut) the `delay_warning_time` property (if you have multiple `main.cf` files, do it in each of them):
   ```shell theme={null}
   ## Deactivate delivery delay notifications through commenting it out
   #delay_warning_time = 1h
   #confirm_delay_cleared = yes
   ```
4. Disable Delivery Status Notification (DSN) for bcc deployments in each `main.cf` file.
   ```
   ## xorlab bcc deployment specific settings
   # Disable Delivery Status Notification (DSN) for bcc deployments
   smtpd_discard_ehlo_keywords = silent-discard, dsn
   ```
5. Click **Publish**. The new Postfix settings become active within about one minute.

### Decisions and quarantine in Monitoring mode

Detection and the [Actions](/latest/detection-actions) configuration screen apply exactly as they do in Inline mode:

* An email whose verdict and confidence lead to a quarantine action gets the `QUARANTINED` decision, and its copy is kept in the matching quarantine instead of being dropped. Search for `status:quarantined` to list them.
* Every other email is dropped after processing.

None of this reaches your mail flow. xorlab only ever holds back its own copy, and the email the recipient received was delivered by your existing mail flow, untouched. A quarantine that fills up in Monitoring mode is therefore expected.

## Inline mode

In Inline mode, xorlab Security Platform is part of the email traffic and forwards emails accordingly. In order to activate it:

1. Open [Expert Editor](/latest/expert-editor) and navigate to the `activeguard/core/active_guard.yml` file.
2. Under the relevant SMTP handler, set `smtpInline: {}` instead of `smtpOffline`. `senderExtraction` and `recipientExtraction` can be omitted as they default to `MAIL_ENVELOPE`:
   ```yaml active_guard.yml theme={null}
   scanSources:
     smtp:
       port: 10025
       handler:
         smtpReport: {}
       # The following line activates the Inline mode.
         smtpInline: {}
   ```
3. Make sure that bounce messages are enabled in `activeguard/mta/startup_cfg/postfix_custom/master.cf`:
   ```shell theme={null}
   # bounce, defer and trace must be set to "bounce"
   bounce    unix  -       -       n       -       0       bounce
   defer     unix  -       -       n       -       0       bounce
   trace     unix  -       -       n       -       0       bounce
   ```
4. Activate delivery delay notifications in `activeguard/mta/startup_cfg/postfix_custom/main.cf`:
   ```shell theme={null}
   ## Enable delivery delay notifications
   delay_warning_time = 1h
   confirm_delay_cleared = yes
   ```
5. Set up SMTP routing for Inline mode: see *Set Up Email Routing in xorlab* for [on-premises](/latest/on-prem-smtp) or [Microsoft 365](/latest/m365-smtp).
6. Click **Publish**. The inline mode configuration becomes active within about one minute.


# Review What Changes in Your Environment
Source: https://docs.xorlab.com/latest/integration-impact

See which settings an integration adds to Microsoft 365 or to your on-premises mail flow, what it leaves untouched — including your MX records — and how to undo it.

xorlab integrates through configuration only. Every step in the integration guides is a setting you make in your own admin portal, every setting is visible to you afterward, and every setting can be switched off again. No software is installed on your servers, your clients or your endpoints, and no mailbox is moved.

Use this page to answer the questions your mail, network and security teams ask before the project starts.

## Quick answers

| Question | Answer |
| :- | :- |
| Do our MX records change? | With M365, **no** — they keep pointing at Microsoft. On premises, only if xorlab replaces your existing gateway. |
| Do we install software anywhere? | No. The integration consists of connectors, mail flow rules and an app registration in your own tenant, plus configuration inside xorlab. |
| Do users need an add-in or a new button? | No. Reporting uses the button your users already have — the built-in M365 one, or your existing third-party button. |
| Does Microsoft's own filtering stop working? | No. Exchange Online Protection and Defender keep running, and xorlab is layered on top of them. |
| Do our outgoing emails get new sending IPs? | With M365, no — outgoing email still leaves through Microsoft, so SPF and DKIM stay as they are. On premises, only if xorlab becomes your outbound gateway. |
| Do we need a DNS change or a cutover window? | Not for M365. The change is made by enabling two mail flow rules, it takes effect within minutes, and it is undone the same way. |
| Can we start without blocking anything? | Yes. Run in [Monitoring mode](/latest/inline-and-monitoring-mode), which never touches the mail flow, or go inline in [Toothless Mode](/latest/before-begin-integration#configure-inline-mode), where every email is still delivered. |

## Microsoft 365

### What the integration adds

| Change | Where you make it | Required? |
| :- | :- | :- |
| Two connectors, `Microsoft365Toxorlab` and `xorlabToMicrosoft365`, both with TLS enforced | Exchange admin center → **Connectors** | Mandatory — [Enable M365 Inline Mode](/latest/m365-inline-mode). [Enable M365 Monitoring Mode](/latest/m365-monitoring-mode) needs only the first one. |
| Two mail flow rules that redirect incoming and outgoing email to xorlab, or blind-copy it in Monitoring mode | Exchange admin center → **Mail flow** → **Rules** | Mandatory — [Enable M365 Inline Mode](/latest/m365-inline-mode) or [Enable M365 Monitoring Mode](/latest/m365-monitoring-mode) |
| One enterprise application named `xorlab`, with app roles, and the users or groups who sign in to XCC assigned to it | Entra ID | Mandatory — [Create Entra ID App](/latest/m365-entra-id-app) and [Enable Entra ID SAML Login](/latest/m365-saml-entra-authentication) |
| Microsoft Graph application permissions (`Mail.ReadWrite` or `Mail.Read`, and `User.Read.All`) with admin consent, and a client secret | Entra ID → the `xorlab` app | Optional — only for [Activate Case Isolation](/latest/m365-case-isolation) and [Import Past M365 Emails](/latest/m365-retrospective-email-scanning) |
| The spam actions of the default inbound anti-spam policy set to **Add X-header** | Microsoft Defender portal | Optional — [Move M365 Quarantine to xorlab](/latest/m365-move-quarantine) |
| A reporting mailbox and one more mail flow rule, `xorlabReportingIntegration` | Microsoft Defender portal → **User reported settings**, and Exchange admin center | Optional — [Integrate M365 Abuse Mailbox](/latest/m365-reporting-integration) |

### What stays as it is

* **Your MX records.** Email keeps arriving at M365 first. A mail flow rule hands it to xorlab over the connector, and xorlab hands it back to M365 for delivery. There is nothing to change at your DNS provider, no TTL to plan around and no cutover moment.
* **Your outbound sending identity.** Outgoing email also returns to M365 for final delivery, so your public sending IPs, your SPF record and your DKIM signatures are unchanged.
* **Exchange Online Protection and Defender.** Microsoft's own filtering keeps running. The only policy xorlab touches is optional: [Move M365 Quarantine to xorlab](/latest/m365-move-quarantine) changes the spam actions so that users have a single quarantine instead of two.
* **Mailboxes, addresses and licenses.** Nothing is migrated and no mailbox is created for your users. The only new mailbox is the optional reporting mailbox.
* **Accepted domains, SPF and the connection filter.** A standard integration does not touch them. The three adjustments under [troubleshooting](/latest/m365-inline-mode#troubleshooting) are needed only if you run into deliverability issues.
* **Your clients.** No add-in is rolled out. Users report suspicious email with the button M365 already provides.

<Note>
  **Hybrid setups**

  Follow the M365 path whenever you receive and send email through M365, even if mailboxes also exist on premises. If email enters and leaves through your own infrastructure, follow [On-premises](#on-premises) instead.
</Note>

### How to undo it

Disable the two mail flow rules in the Exchange admin center. Email returns to its previous path within minutes, without a DNS change. The connectors and the Entra ID app can then be removed at your own pace.

## On-premises

How much changes depends on where xorlab sits in your mail flow. You choose that in [Set Up Email Routing in xorlab](/latest/on-prem-smtp).

| Target setup | Mail path | MX records |
| :- | :- | :- |
| **Inline add-on** (default) | Your gateway forwards incoming email to xorlab instead of directly to Exchange, and xorlab delivers it to Exchange. Outgoing email goes Exchange → xorlab → gateway. | Unchanged. Your existing gateway keeps the MX. |
| **Inline gateway** | xorlab receives email from the internet and delivers it to Exchange. It also delivers outgoing email to the external recipient. | Changed. They point at the xorlab MTAs. Also open inbound SMTP to the MTAs, add them to your SPF record, and set up [DKIM signing](/latest/dkim-and-dmarc-setup) on xorlab. |
| **Monitoring** | Unchanged. xorlab receives a copy of every email and discards it after the analysis. | Unchanged. |

### What the integration adds

| Change | Where you make it | Required? |
| :- | :- | :- |
| The scope of the default receive connector extended with the IP addresses of the xorlab MTAs | Exchange admin center → **Mail Flow** → **receive connectors** | Inline — [Enable Exchange Inline](/latest/on-prem-exchange-inline) |
| A send connector that routes outgoing email through the xorlab MTAs as smart hosts | Exchange admin center → **Mail Flow** → **send connectors** | Inline — [Enable Exchange Inline](/latest/on-prem-exchange-inline) |
| Two mail flow rules that blind-copy email to xorlab, or a message filter, bounce profile and destination control on a Cisco ESA | Exchange admin center, or the ESA | Monitoring — [Enable Exchange Monitoring with BCC](/latest/on-prem-exchange-monitoring-mode) or [Enable ESA Monitoring with BCC](/latest/on-prem-esa-monitoring-mode) |
| Firewall rules for SMTP between your email servers and the xorlab MTAs, and for the outbound connections of the platform | Your firewall | Mandatory — [Network Guide](/latest/network-guide) |
| Your own email servers registered as trusted infrastructure. This is a setting inside xorlab, not in your environment | Expert Editor | Mandatory — [Add Your Trusted Infrastructure](/latest/on-prem-add-trusted-mtas) |
| A SAML application or an LDAP service account for signing in to XCC | Your identity provider | Optional — [Enable SAML or LDAP Login](/latest/on-prem-saml-ldap-authentication) |
| Forwarding of reported email to `suspicious@<templateDomain>` on xorlab | Exchange, or your reporting button | Optional — [Integrate On-prem Abuse Mailbox](/latest/on-prem-reporting-integration) |

### What stays as it is

* **Your existing gateway or filter**, unless you deliberately replace it. In the default inline add-on setup, xorlab is added next to what you already run.
* **Mailboxes, addresses and clients.** Nothing is migrated and nothing is installed on Exchange or on the endpoints.
* **The mail flow itself, in Monitoring mode.** xorlab only receives a copy and never modifies, delays or blocks an email.

<Note>
  **Monitoring mode and availability**

  The copies are ordinary emails, so if all xorlab MTAs are unreachable, they can queue up on the system that sends them. If that happens, disable the BCC rules temporarily.
</Note>

### How to undo it

In Monitoring mode, disable the BCC mail flow rules or the ESA message filter. In Inline mode, set the next hop of the system in front of xorlab back to its previous destination and disable the send connector that points at xorlab.

## What your users notice

* **In Monitoring mode, nothing.** No email is modified, delayed or blocked.
* **In Inline mode, with the delivered defaults:**
  * Emails with a malicious verdict are quarantined instead of delivered. Which verdict and confidence leads to which action is visible, and adjustable, in [Review Default Actions](/latest/detection-actions).
  * Some verdicts are delivered with a subject prefix such as `[SPAM]`, configured on the same screen.
  * Nothing else is added to the message. [Enable Contextual Banners](/latest/detection-contextual-banners) and [Add Result Header to Email](/latest/detection-analysis-result-header) are separate, optional steps and are off by default.
* **Only if you enable it:** the [Self-Service Quarantine (SSQ)](/latest/ssq-overview) lets users see and release their own quarantined emails, and quarantine notifications are sent to them.

During the first weeks you can go inline in [Toothless Mode](/latest/before-begin-integration#configure-inline-mode). xorlab then delivers every email, including the ones it would have quarantined, and you review those in XCC by searching for `#quarantine` before switching protection on.

## Next steps

<Card title="Before You Begin" icon="rocket-launch" href="/latest/before-begin-integration">
  Configure your guarded domains, set the data retention, and choose between Inline and Monitoring mode.
</Card>


# What to Configure Next
Source: https://docs.xorlab.com/latest/integration-next-steps

What to configure once the integration is complete: user login, quarantine, notifications, detection, and logging.

Now that you finished the [xorlab integration](/latest/setup-integration-overview), have a look at the following topics:

| Step | Description |
| :- | :- |
| [Enable User Login](/latest/authentication-overview) | In case you haven't done it yet, simplify user login to xorlab via SAML, LDAP or Auto-Login |
| [Customize detection](/latest/detection-overview) | Review the built-in detection and activate additional features |
| [Enable SSQ](/latest/ssq-overview) | Enable Self-Service Quarantine (SSQ) for your end-users |
| [Connect a SIEM](/latest/integrations-siem) | Forward verdicts, threat intelligence, and the audit trail to your SIEM or log management platform |
| [Automate with a SOAR](/latest/integrations-soar) | Trigger playbooks from xorlab events, and let them manage list entries over the API |

For everything else xorlab connects to — identity providers, Microsoft Graph, threat intelligence, and awareness training tools — see [What xorlab Connects To](/latest/integrations-overview).


# What xorlab Connects To
Source: https://docs.xorlab.com/latest/integrations-overview

Which systems xorlab integrates with and over which interface: SMTP mail flow, Syslog to SIEM, REST APIs for SOAR and automation, SAML and LDAP identity, Microsoft Graph, and threat intelligence.

xorlab is built on open, standardized interfaces. You install no proprietary agent and you wait for no vendor-specific connector: if your platform speaks **SMTP**, **Syslog**, **HTTPS/REST**, **SAML**, or **LDAP**, it can be integrated with xorlab today.

Use this page to check whether a system in your stack is covered, and to find the guide that covers it. Each section links into the step-by-step instructions under [Admin Configuration](/latest/setup-integration-overview).

<Note>
  Ready to start the integration? Go to [Integration Overview](/latest/setup-integration-overview) — the ordered guide through the standard xorlab integration. Come back here when you want to connect a further system.
</Note>

<CardGroup>
  <Card title="Mail Flow" icon="envelope" href="#mail-flow-smtp">
    Route or mirror email through xorlab in Microsoft 365, on-premises, or hybrid environments.
  </Card>

  <Card title="Connect a SIEM" icon="scroll" href="#siem-and-log-management">
    Stream verdicts, threat intelligence, and the full audit trail to Splunk, Sentinel, QRadar, Elastic, and others.
  </Card>

  <Card title="Automate with a SOAR" icon="hexagon-nodes" href="#soar-and-automation">
    Drive xorlab from your playbooks over REST, and trigger playbooks from xorlab events.
  </Card>

  <Card title="Identity & SSO" icon="user-check" href="#identity-and-single-sign-on">
    SAML 2.0 and LDAP against Entra ID, Active Directory, or any standards-compliant IdP.
  </Card>

  <Card title="Microsoft 365 & Graph" icon="microsoft" href="#microsoft-365-and-microsoft-graph">
    Case isolation, retrospective scanning, the built-in Report button, and contextual banners.
  </Card>

  <Card title="Threat Intelligence" icon="virus" href="#threat-intelligence">
    Enrich analysis and investigation with VirusTotal and Spamhaus DQS.
  </Card>

  <Card title="Awareness Training" icon="person-running" href="#security-awareness-and-phishing-simulation">
    Let any phishing simulation service through to the inbox without weakening detection.
  </Card>

  <Card title="Operational Monitoring" icon="sensor-alert" href="#operational-monitoring-and-alerting">
    On-premises only: ship platform health alerts to email, Slack, webhooks, or any Alertmanager receiver.
  </Card>
</CardGroup>

## Interfaces at a glance

| Interface | Direction | Used for |
| :- | :- | :- |
| SMTP (with TLS) | Inbound and outbound | Mail flow, notifications, reported email, log delivery by email |
| Syslog (UDP, TCP, TLS — RFC 3164 or RFC 5424) | xorlab → your system | SIEM, log management, SOAR event triggers |
| HTTPS / REST | Your system → xorlab | [List API](/latest/api-rule-list-management) for automated list management, [Email Scanning API](/latest/abby) for on-demand analysis |
| Log files (on-premises only) | xorlab → your collector | Log shippers and agents that tail files |
| SAML 2.0 | xorlab → your IdP | Single sign-on for admins, analysts, and end users |
| LDAP | xorlab → your directory | Login against Active Directory |
| Microsoft Graph | xorlab → M365 | Case isolation, retrospective scanning, move to quarantine |
| DNS | xorlab → resolver | Sender authentication and DNS-based blocklists such as Spamhaus DQS |

## Mail flow (SMTP)

xorlab sits in your mail flow over SMTP, which is what makes it deployable in front of, behind, or alongside almost any mail infrastructure — Microsoft 365, Exchange, or any standards-compliant MTA or gateway.

Two modes are supported, and both are available in all deployment variants (on-premises, hybrid, and SaaS):

* **Inline mode**: all email is routed through xorlab, which can block, quarantine, and rewrite.
* **Monitoring mode**: xorlab receives a copy of every email and discards it after analysis. Nothing is blocked.

Each path guide below ends with architecture diagrams of every supported topology for that path, so you can match your environment before you start.

<CardGroup>
  <Card title="Microsoft 365" icon="microsoft" href="/latest/m365-integration-overview">
    Connectors, inline or monitoring mode, and the optional Graph-based features. Includes the [mail flow diagrams](/latest/m365-integration-overview#inline-mode-diagrams).
  </Card>

  <Card title="On-premises" icon="server" href="/latest/on-prem-integration-overview">
    Exchange, Cisco ESA, and other gateways, as a gateway or as an add-on. Includes the [mail flow diagrams](/latest/on-prem-integration-overview#inline-mode-diagrams).
  </Card>

  <Card title="Inline vs. Monitoring" icon="network-wired" href="/latest/inline-and-monitoring-mode">
    What each mode can and cannot do, and how to switch between them later.
  </Card>

  <Card title="Advanced SMTP" icon="share-nodes" href="/latest/smtp-configuration">
    Multiple next hops, per-domain routing, TLS enforcement, and trusted MTAs.
  </Card>
</CardGroup>

The documented on-premises guides cover Exchange and Cisco ESA, but the interface is plain SMTP: any other MTA or secure email gateway can take their place. If yours is not covered by a guide, contact [support@xorlab.com](mailto:support@xorlab.com) and we will walk you through it.

## SIEM and log management

Every relevant thing that happens in xorlab is a log event: the verdict for each message, each SMTP transaction, threat intelligence indicators extracted from malicious mail, and the complete analyst and admin audit trail. Events are emitted over Syslog in JSON or CEF, so any SIEM can consume them without a dedicated connector.

<Card title="Connect a SIEM" icon="scroll" href="/latest/integrations-siem">
  Which events to send, which format to choose, and where to look in the documentation of Splunk, Microsoft Sentinel, QRadar, Elastic, Graylog, and others.
</Card>

## SOAR and automation

Automation works in both directions. xorlab pushes events out over Syslog, and your playbooks call back into xorlab over a REST API. Use that, for example, to add a confirmed phishing sender to a Blacklist without anyone logging into the web interface.

<Card title="Automate with a SOAR" icon="hexagon-nodes" href="/latest/integrations-soar">
  Event triggers, the List API as the action surface, worked playbook patterns, and the API key model.
</Card>

<CardGroup>
  <Card title="List API" icon="list-check" href="/latest/api-rule-list-management">
    Read, add, and remove entries on any list, including custom lists. Scoped API keys, multi-tenant aware.
  </Card>

  <Card title="Email Scanning API" icon="code" href="/latest/abby">
    Submit a message over HTTP and get the analysis result back synchronously.
  </Card>
</CardGroup>

## Identity and single sign-on

xorlab does not maintain its own user directory unless you want it to. Admins, analysts, and end users authenticate against your identity provider, and roles are mapped from the attributes it returns, including tenant-restricted roles in multi-tenant deployments.

| Integration | Notes |
| :- | :- |
| [SAML 2.0](/latest/authentication-saml) | Recommended for admins and analysts. Works with any standards-compliant IdP; see [Entra ID](/latest/m365-saml-entra-authentication) for a worked Microsoft 365 example. Supports [request signing](/latest/authentication-saml-request-signing) and [certificate handling](/latest/authentication-certificates). |
| [LDAP](/latest/authentication-ldap) | Login against Active Directory or another LDAP directory. |
| [Auto-Login](/latest/authentication-auto-login-link) | Passwordless access for end users to the Self-Service Quarantine from the quarantine notification. |
| [Password file](/latest/authentication-with-a-password-file) | Local credentials with optional TOTP, for break-glass access or environments without an IdP. |

Several methods can be active at the same time — for example SAML for the SOC and Auto-Login for end users. See [Authentication Overview](/latest/authentication-overview).

## Microsoft 365 and Microsoft Graph

Beyond mail flow, xorlab integrates with Microsoft 365 through a single [Entra ID app registration](/latest/m365-entra-id-app) and Exchange Online mail flow rules.

| Integration | What it does |
| :- | :- |
| [Case Isolation](/latest/m365-case-isolation) | Analysts remove a confirmed malicious email from recipients' mailboxes through Microsoft Graph. |
| [Retrospective Email Scanning](/latest/m365-retrospective-email-scanning) | Import and analyze mail that was already delivered, before the tenant goes inline. |
| [Move to Quarantine](/latest/m365-move-quarantine) | Move the M365 quarantine to xorlab for a centralized experience. |
| [Abuse Mailbox via the Report button](/latest/m365-reporting-integration) | The built-in Microsoft 365 reporting button feeds reported email into xorlab, with automated feedback to the reporter. |
| [Contextual Banners](/latest/detection-contextual-banners) | Exchange Online (and on-premises Exchange) mail flow rules insert risk-specific banners. Ready-made PowerShell scripts are provided. |
| [Shared mailboxes](/latest/ssq-shared-mailboxes) | Resolve shared mailbox membership so delegates can use the Self-Service Quarantine. |

## Threat intelligence

| Integration | Role in the platform |
| :- | :- |
| [VirusTotal](/latest/detection-virustotal) | On-demand enrichment in the message detail view. Informational only — it does not influence the verdict. Bring your own API key. |
| [Spamhaus DQS](/latest/detection-spamhaus-dqs) | DNS-based blocklist and Hash Blocklist checks through the SpamAssassin plugin. Bring your own key. |
| xorlab xCloud and xorlab ML | Built in, no configuration required. See [Data Sent to External Services](/latest/data-to-external-services) for exactly what leaves your environment. |

xorlab also **exports** threat intelligence: the `ti.*` [log events](/latest/logging-events#threat-analysis-events) emit malicious sender addresses, sending IPs, attachment hashes, domains, and URLs observed in your own mail, ready to be consumed by your SIEM or fed into other controls. See [Connect a SIEM](/latest/integrations-siem#export-threat-intelligence).

## Security awareness and phishing simulation

Any awareness training or phishing simulation service can be allowed through, regardless of vendor. Add its distinctive mark to the Simulation lists, ideally the sending IP range, and simulated attacks reach the inbox and are tagged `verdict:simulation`.

<Card title="Phishing Simulation" icon="person-running" href="/latest/phishing-simulation-tools">
  Which identifiers to use, and why matching on the connecting IP is safer than matching on a header.
</Card>

## Operational monitoring and alerting

<Info>
  **On-premises deployments only**

  If you run xorlab as SaaS, xorlab operates and monitors the platform for you. Subscribe to the [status page](/latest/important-resources#status-page) for scheduled maintenance and incidents.
</Info>

If you run xorlab on-premises, platform health monitoring is built on Prometheus and Alertmanager, so alerts about the platform itself can go anywhere Alertmanager can send them: email, Slack, a generic webhook, and every other receiver Alertmanager supports.

<Card title="Enable Alerts" icon="sensor-alert" href="/latest/monitoring-alerts">
  Configure receivers and route alerts by severity.
</Card>

<Note>
  Operational alerting is for platform health. To get email security events into another system, use [Syslog](/latest/integrations-siem) instead.
</Note>

## Don’t see your product?

That is usually not a problem. xorlab integrates through standard protocols rather than per-vendor connectors, so the question is which interface your product speaks:

* It can receive Syslog, or an agent of yours can read a log file → see [Connect a SIEM](/latest/integrations-siem).
* It can make an HTTP request → see [Automate with a SOAR](/latest/integrations-soar).
* It is a mail gateway or mail server → see [Mail flow (SMTP)](#mail-flow-smtp).
* It is an identity provider that supports SAML 2.0 or LDAP → see [Authentication Overview](/latest/authentication-overview).

If you are unsure, contact [support@xorlab.com](mailto:support@xorlab.com).


# Connect a SIEM
Source: https://docs.xorlab.com/latest/integrations-siem

Stream xorlab verdicts, threat intelligence, and audit events to any SIEM over Syslog in JSON or CEF, with pointers into the ingestion documentation of the common platforms.

<Info>
  **Optional**

  This is a next step after the [standard integration](/latest/setup-integration-overview). xorlab protects email without a SIEM connected.
</Info>

xorlab integrates with SIEM and log management platforms over **Syslog**, using either **JSON** or **CEF** as the message payload. Because both sides of that are standards, you need no xorlab-specific app, add-on, or connector. Any platform that can accept Syslog can ingest xorlab events.

<Card title="Go straight to the setup steps" icon="scroll" href="/latest/logging-via-syslog">
  Forward Events over Syslog — the appender configuration, TCP/TLS, and all available parameters.
</Card>

## What you can send

Logging is event-based: you choose which events to forward, so you can start with verdicts only and expand from there. The categories most relevant to a SIEM:

| What | Events | Why you want it |
| :- | :- | :- |
| Email verdicts | `trace.msg_verdict`, `trace.msg_analysis.complete` | One record per email with the decision, direction, sender, and recipients — and with the extended JSON format also tags, risk and trust scores, attachment hashes, and extracted URLs. The backbone of email dashboards and correlation. |
| SMTP transactions | `trace.mta.received`, `trace.mta.send`, `trace.msg_delivered` | Accept/relay records with queue IDs, for mail flow tracing and delivery troubleshooting. |
| Threat intelligence | `ti.email`, `ti.ip`, `ti.file`, `ti.domain`, `ti.url` | Indicators extracted from malicious mail in *your* environment. See [Export threat intelligence](#export-threat-intelligence). |
| Analyst and admin audit trail | `audit.*` | Logins, message views and downloads, quarantine releases, list changes, campaign changes, config changes. Needed for compliance evidence and insider-risk monitoring. |
| Quarantine and release workflow | `audit.user.quarantine_release`, `audit.quarantine.release.request.*` | Who requested, approved, or denied a release, and when. |
| Case isolation | `audit.isolate.removed` | Records every email evicted from a mailbox. |
| Platform events | `sys.*` | Startup, shutdown, configuration commits, backup success and failure. |

The full list, with event IDs, severities, and the component each one is emitted by, is in [Log Events](/latest/logging-events).

## Choose a payload format

| Format | Pattern | Use it when |
| :- | :- | :- |
| JSON | `%jsonMsg%n` | Default choice. Works for all events. Best when your SIEM parses JSON natively. |
| JSON extended | `%coreJsonMsg%n` | You want the complete email analysis result — attachments with hashes, extracted URLs, threat intel hits, headers — as a single record. Only valid for `trace.*` events. |
| CEF | `%cef%n` | Your platform expects ArcSight-style CEF, or you use a CEF-based data connector (for example CEF via AMA in Microsoft Sentinel). |
| Single attributes | `%logArg{key}` | You only need a few fields, for example to feed a lookup table. |

Details and worked examples: [Format Converters](/latest/logging-formats).

<Tip>
  **Start with the extended JSON verdict event**

  For most SIEM projects, forward `trace.msg_analysis.complete` with the `%coreJsonMsg%n` pattern. That gives you the highest value per event: exactly one rich record per email. A copy-ready configuration is in [Configuration Examples](/latest/logging-examples#log-detailed-email-results).
</Tip>

## Transport and reliability

| Option | Notes |
| :- | :- |
| UDP | Default. Simplest, but lossy, and messages are truncated to 1500 bytes unless you raise `messageSizeLimit`. Fine for low-volume audit events, not for extended JSON. |
| TCP | Recommended. Requires wrapping the Syslog appender in an `AsyncAppender`. |
| TLS (`SSL`) | Recommended when logs leave your network, for example to a cloud-hosted SIEM. Also requires an `AsyncAppender`. |

Both `RFC3164` (default) and `RFC5424` framing are supported through the `format` parameter, and `hostName` sets the log source identifier your SIEM keys on. See [Available attributes](/latest/logging-via-syslog#available-attributes).

<Warning>
  For TCP and TLS, adding an `AsyncAppender` is mandatory. Without it, a slow or unreachable SIEM can affect xorlab. See [Use Syslog with TCP or TLS](/latest/logging-via-syslog#use-syslog-with-tcp-or-tls).
</Warning>

## Where to configure it in your SIEM

xorlab appears to your SIEM as a generic Syslog source, so the work on the SIEM side is the platform’s standard “add a Syslog source” procedure. We do not ship per-vendor apps. Use the vendor’s own documentation below, and point the source at the `syslogHost` and `port` you configured in xorlab.

| Platform | Receive xorlab events by | Vendor documentation |
| :- | :- | :- |
| Splunk Enterprise / Splunk Cloud | Splunk Connect for Syslog (SC4S), which Splunk recommends over a raw network input | [Splunk Connect for Syslog](https://splunk.github.io/splunk-connect-for-syslog/main/) |
| Microsoft Sentinel | Syslog via AMA connector, requires you to run a host with AMA | [Ingest syslog and CEF messages to Microsoft Sentinel](https://learn.microsoft.com/en-us/azure/sentinel/connect-cef-syslog-ama) |
| IBM QRadar | A log source with the Syslog protocol type, parsed by a universal DSM or a log source extension | [Adding a log source](https://www.ibm.com/docs/en/dsm?topic=management-adding-log-source) |
| Elastic Security | Elastic Agent with the Custom UDP Logs or Custom TCP Logs integration | [Custom UDP Logs integration](https://www.elastic.co/docs/reference/integrations/udp) |
| Graylog | Syslog TCP input (with optional TLS) or Syslog UDP input | [Syslog Inputs](https://go2docs.graylog.org/current/getting_in_log_data/syslog_inputs.html) |
| Sumo Logic | Syslog source on an installed collector | [Syslog Source](https://www.sumologic.com/help/docs/send-data/installed-collectors/sources/syslog-source/) |
| Cribl Stream | Syslog source, then route to any downstream destination | [Syslog Source](https://docs.cribl.io/stream/sources-syslog/) |
| Wazuh | Remote syslog on the Wazuh server | [Configuring syslog on the Wazuh server](https://documentation.wazuh.com/current/user-manual/capabilities/log-data-collection/syslog.html) |
| Datadog | Syslog source in Observability Pipelines | [Syslog Source](https://docs.datadoghq.com/observability_pipelines/sources/syslog/) |

<Note>
  Not listed here does not mean unsupported. Any platform with a Syslog listener works the same way — look for “syslog input”, “syslog source”, or “log source” in its documentation.
</Note>

### If your collector prefers files

For on-premises deployments you can also write events to a rolling log file and let an existing agent or log shipper pick them up. This is often the path of least resistance when you already run a forwarder on every host.

<Card title="Write Events to a Log File" icon="file" href="/latest/logging-via-file">
  Rolling file appender with size and retention policies.
</Card>

## Export threat intelligence

The `ti.*` events are worth calling out separately. Whenever xorlab identifies a malicious element in an email, it emits the indicator as its own event:

| Event | Indicator |
| :- | :- |
| `ti.email` | Malicious sender email address |
| `ti.ip` | Malicious sending MTA IP address |
| `ti.file` | Malicious attachment |
| `ti.domain` | Malicious embedded domain |
| `ti.url` | Malicious embedded URL |

Because xorlab derives these from attacks against your own organization, they are usually higher-signal than a generic feed. Common uses are populating a SIEM threat intelligence index, blocking indicators on the proxy or firewall, or hunting retroactively across other log sources.

## Verify the integration

1. Configure the appender and logger as described in [Forward Events over Syslog](/latest/logging-via-syslog).
2. Generate the event you subscribed to — for verdict events, send a test email through xorlab.
3. Confirm the event arrives in your SIEM. If nothing appears, check in this order:
   * Is the event emitted by the component whose `logback-audit.xml` you edited? Each component has its own configuration directory, listed in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component).
   * Is the chosen pattern valid for the chosen event? `%coreJsonMsg` only works for `trace.*` events.
   * Is UDP truncating the payload? Extended JSON records easily exceed 1500 bytes — switch to TCP.
   * Is the port reachable from the xorlab MTA and XCC? See the [Network Guide](/latest/network-guide).

The full list of symptoms and causes, including duplicated and truncated records, is in [Verify and Troubleshoot Logging](/latest/logging-verify).


# SIEM & SOAR Overview
Source: https://docs.xorlab.com/latest/integrations-siem-soar-overview

The two ways xorlab connects to a SIEM or SOAR: an outbound event stream over Syslog, and an inbound REST API for automation.

Both integrations are **optional**. xorlab protects email without either of them, and analysts can do everything described here by hand in the web interface.

They rest on two interfaces:

* **Outbound**, over Syslog: verdicts, extracted threat intelligence, and the full analyst and admin audit trail. This is what a SIEM ingests, and what a SOAR uses as a playbook trigger.
* **Inbound**, over HTTPS: the [List API](/latest/api-rule-list-management), which lets a playbook or script change list entries without a human in the web interface.

| Step | Description |
| :- | :- |
| [Connect a SIEM](/latest/integrations-siem) | **Optional**. Forward the events you care about to Splunk, Microsoft Sentinel, QRadar, Elastic, or any other platform with a Syslog listener. |
| [Automate with a SOAR](/latest/integrations-soar) | **Optional**. Turn those same events into playbook triggers, and let playbooks manage Blacklists, Whitelists, and VIP lists over the API. |

<Warning>
  **Prerequisites**

  * Complete the [integration](/latest/setup-integration-overview)
</Warning>


# Automate with a SOAR
Source: https://docs.xorlab.com/latest/integrations-soar

Drive xorlab from your SOAR or automation platform: Syslog events as playbook triggers, the List API as the action surface, and worked playbook patterns.

<Info>
  **Optional**

  This is a next step after the [standard integration](/latest/setup-integration-overview). Analysts can do everything described here by hand in the web interface.
</Info>

You can operate xorlab by machine as well as by hand. Automation runs in two directions:

<CardGroup>
  <Card title="xorlab → your platform" icon="share-nodes" href="#trigger-playbooks-from-xorlab-events">
    Events are pushed out over Syslog and become playbook triggers: verdicts, extracted indicators, and the full audit trail.
  </Card>

  <Card title="Your platform → xorlab" icon="code" href="#act-on-xorlab-from-a-playbook">
    Your playbooks call a REST API to change xorlab configuration, most importantly list entries.
  </Card>
</CardGroup>

Both use interfaces most SOAR and automation platform already supports, so integrating xorlab is a matter of configuring a Syslog source and an HTTP action.

<Card title="Go straight to the setup steps" icon="list-check" href="/latest/api-rule-list-management">
  List API — create an API key, then call the endpoints from your playbook.
</Card>

## Trigger playbooks from xorlab events

Send the relevant [log events](/latest/logging-events) over Syslog to your SOAR, or to the SIEM your SOAR is already connected to. The events most often used as triggers:

| Trigger | Event | Typical playbook |
| :- | :- | :- |
| An email was quarantined or blocked | `trace.msg_verdict`, `trace.msg_analysis.complete` | Open or enrich a case, notify the recipient’s manager, check whether the same sender reached other systems. |
| A malicious indicator was observed | `ti.email`, `ti.ip`, `ti.file`, `ti.domain`, `ti.url` | Push the indicator to the proxy, firewall, or EDR blocklist, and hunt for it across other log sources. |
| A user released a message from quarantine | `audit.user.quarantine_release` | Post-hoc review of the release, and follow-up if the message was high risk. |
| A release request was created | `audit.quarantine.release.request.created` | Route the approval into your ticketing or chat workflow. |
| An analyst isolated an email | `audit.isolate.removed` | Record the containment action in the incident record. |
| A list or configuration changed | `audit.user.lists.item_added`, `audit.user.lists.item_removed`, `audit.user.config.file_modified` | Change-management evidence, and alerting on unexpected changes. |

Setup is the standard Syslog path — see [Connect a SIEM](/latest/integrations-siem) for format and transport guidance, and [Forward Events over Syslog](/latest/logging-via-syslog) for the configuration itself.

## Act on xorlab from a playbook

The [List API](/latest/api-rule-list-management) is the primary automation surface. It reaches every list that is visible in the web interface, including custom lists. That covers most of what a playbook needs to change: [Blacklists](/latest/blacklists), [Whitelists](/latest/whitelists), [VIP Names](/latest/vips) and high-value targets, fraud keywords, simulation senders, trusted infrastructure, and reporting addresses.

| Endpoint | Use |
| :- | :- |
| `getLists` | Discover the available lists, their internal names, and their `maxSize`. Always start here. |
| `listEntries` | Read the current entries of a list, as NDJSON. |
| `addEntries` | Add or update entries, each with a free-text comment. |
| `deleteEntries` | Remove entries. Missing entries are ignored, so calls are safe to repeat. |

Use this minimal action step to add a sender domain your playbook has confirmed as malicious to a Blacklist:

```bash theme={null}
curl -sS -X POST \
  '<xorlab-url>/api/public/lists/v1/addEntries' \
  -H 'Authorization: apikey <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantUid": null,
    "listName": "BLACKLIST_local_sender_addresses",
    "entries": [
      {
        "entry": "bad-domain.example",
        "comment": "Blocked by playbook PB-114, case INC-4821"
      }
    ]
  }'
```

Use the `comment` field deliberately. Analysts see it on the **Lists** page, so it is the fastest way for them to understand why an automated entry exists. Put the playbook name and the case ID in it.

For the API key, the endpoint reference, and multi-tenant scoping, see the [List API](/latest/api-rule-list-management). For the narrower case of submitting a message for analysis over HTTP instead of SMTP, see the [Email Scanning API](/latest/abby).

<Warning>
  Every list has a maximum size, and adding to a full list removes its oldest entry. An unbounded automation that keeps adding entries will therefore evict older ones. Read `maxSize` from `getLists` and have your playbook clean up its own entries with `deleteEntries`, for example when a case is closed. See [Understanding list behavior](/latest/api-rule-list-management#understanding-list-behavior).
</Warning>

## Playbook patterns

Common patterns:

| Pattern | How it works |
| :- | :- |
| **Close the loop on a confirmed phishing case** | An analyst or a playbook confirms a reported email is malicious → `addEntries` puts the sender address or domain on a Blacklist → the indicator also goes to the proxy and EDR. |
| **Sync an external feed or deny list** | A scheduled playbook reads your authoritative source (threat feed, MISP, an internal deny list) and reconciles it into a xorlab list with `listEntries`, `addEntries`, and `deleteEntries`. |
| **Keep VIP data in step with HR** | On a change in the HR system or an Entra ID group, update the VIP names and high-value-target lists so impersonation protection follows the org chart automatically. |
| **Onboard a phishing simulation campaign** | Before a campaign starts, a playbook adds the simulation provider’s sending IP range to the [Simulation lists](/latest/phishing-simulation-tools), and removes it when the campaign ends. |
| **Time-boxed exceptions** | A playbook adds a Whitelist entry with a case ID in the comment and schedules its own `deleteEntries` call, so temporary exceptions do not become permanent ones. |
| **Enrich tickets with the xorlab verdict** | The verdict event forwarded over Syslog carries the decision, tags, sender authentication result, and attachment hashes. That can be used to populate a ticket automatically. |

## Platform notes

The xorlab side is identical for every platform: a Syslog destination for events, and an authenticated HTTP POST for actions. The table below names the building block to use on the other side, and where the vendor documents it.

| Platform | Building block | Vendor documentation |
| :- | :- | :- |
| Palo Alto Cortex XSOAR / XSIAM | The *GenericAPICall* integration, which makes authenticated HTTP calls to endpoints without a dedicated integration | [GenericAPICall](https://xsoar.pan.dev/docs/reference/integrations/generic-api-call) |
| Splunk SOAR | The Splunk-built **HTTP** app, configured as an asset. Its `post data` action makes the REST call | [HTTP app on Splunkbase](https://splunkbase.splunk.com/app/5904) |
| Microsoft Sentinel | An automation rule invoking a Logic App, whose built-in HTTP action calls the endpoint | [Call external HTTPS endpoints from workflows](https://learn.microsoft.com/en-us/azure/connectors/connectors-native-http) |
| Tines | The HTTP Request action | [HTTP Request](https://www.tines.com/docs/actions/types/http-request/) |
| Anything else | Any HTTP request step that lets you set a custom header for authentication | — |


# Keyboard Shortcuts
Source: https://docs.xorlab.com/latest/keyboard-shortcuts

All keyboard shortcuts available in XCC, grouped by screen area.

| Area | Shortcut | Function |
| - | - | - |
| Media & preview dialogs | <kbd>Left</kbd>, <kbd>Right</kbd> | Previous/next image |
| Message list view | <kbd>Slash</kbd><br /><kbd>Esc</kbd><br /><kbd>S</kbd><br /><kbd>Shift</kbd>+<kbd>S</kbd><br /><kbd>T</kbd><br /><kbd>X</kbd><br /><kbd>A</kbd><br /><kbd>E</kbd><br /><kbd>Del</kbd> | Set focus to the search bar<br />Clear search<br />Save search<br />Save campaign<br />Add a tag<br />Export campaign<br />Archive campaign<br />Edit search or campaign<br />Delete search or campaign |
| Message detail view | <kbd>P</kbd><br /><kbd>N</kbd><br /><kbd>B</kbd><br /><kbd>W</kbd><br /><kbd>I</kbd><br /><kbd>R</kbd><br /><kbd>S</kbd><br /><kbd>E</kbd><br /><kbd>T</kbd><br /><kbd>O</kbd><br /><kbd>D</kbd><br /><kbd>Shift</kbd>+<kbd>D</kbd><br /><kbd>M</kbd><br /><kbd>Del</kbd><br /><kbd>1</kbd><br /><kbd>2</kbd><br /><kbd>3</kbd><br /><kbd>4</kbd><br /><kbd>5</kbd><br /><kbd>6</kbd><br /><kbd>7</kbd> | Previous message<br />Next message<br />Blacklist message<br />Whitelist message<br />Isolate message<br />Release message<br />Resolve message as benign<br />Resolve message<br />Add a tag<br />Show original email<br />Download email<br />Download archive<br />Download metadata<br />Delete message<br />Select **Summary** tab<br />Select **Attachments** tab<br />Select **Links** tab<br />Select **Similar** tab<br />Select **Headers** tab<br />Select **Classifiers & Rules** tab<br />Select **Context variables** tab |
| Message detail view (reported messages) | <kbd>1</kbd><br /><kbd>2</kbd><br /><kbd>3</kbd><br /><kbd>4</kbd><br /><kbd>5</kbd><br /><kbd>6</kbd><br /><kbd>7</kbd><br /><kbd>8</kbd> | Select **Summary** tab<br />Select **Report log** tab<br />Select **Attachments** tab<br />Select **Links** tab<br />Select **Similar** tab<br />Select **Headers** tab<br />Select **Classifiers & Rules** tab<br />Select **Context variables** tab |
| Message list view (SSQ) | <kbd>A</kbd><br /><kbd>T</kbd><br /><kbd>W</kbd><br /><kbd>M</kbd> | Select all<br />Select today<br />Select since one week<br />Select since one month |
| Message detail view (SSQ) | <kbd>R</kbd> | Release message |
| File detail view | <kbd>D</kbd><br /><kbd>Del</kbd><br /><kbd>1</kbd><br /><kbd>2</kbd><br /><kbd>3</kbd><br /><kbd>4</kbd> | Download<br />Delete<br />Select **Summary** tab<br />Select **Links** tab<br />Select **Classifiers & Rules** tab<br />Select **Context variables** tab |
| Release dialog | <kbd>Enter</kbd> | Release |


# Lists Overview
Source: https://docs.xorlab.com/latest/lists

Overview of the built-in lists that adjust platform behavior on the fly, and where to find them in XCC.

Throughout this documentation, a list is referenced as **Settings → Lists → \<Category>**. To get there in XCC:

1. On the main screen, click the tiles icon next to your account name and click the **Admin** icon in the displayed menu.
2. On the resulting **Admin** page, click the **Lists** tile:
   <img alt="Selecting Lists" />

Lists include [Blacklists](/latest/blacklists) and [Whitelists](/latest/whitelists), but also more sophisticated lists like [Trusted Senders and Infrastructure](/latest/trusted-senders-infrastructure) to manually overwrite trust scores, or the [Phishing Simulation Tools](/latest/phishing-simulation-tools) to define which emails are treated as phishing simulations.

<Note>
  **A note on terminology**

  This documentation uses **Blacklist** and **Whitelist** because that is how these lists are named in xorlab Security Platform. They are also commonly known as blocklist and allowlist.

  The terms *blocklist* and *allowlist* are used only where they refer to something outside xorlab, such as third-party [DNS blocklists](/latest/detection-overview).
</Note>

If you want to automate list maintenance, use the [Rule List API](/latest/api-rule-list-management). It allows you to read and update list entries directly, without editing config files.

<img alt="Built-in lists" />

<Note>
  **Custom lists**

  It is possible to add additional lists to this overview that can then be used in custom rules for specific use cases. Contact [support@xorlab.com](mailto:support@xorlab.com) for detailed instructions.
</Note>


# Reporting Addresses
Source: https://docs.xorlab.com/latest/lists-reporting-addresses

Configure the addresses used to report suspicious emails to services other than xorlab.

xorlab Security Platform provides an email address for reporting potentially malicious messages. Additionally, your organization may report malicious emails to other services than xorlab Security Platform. If this is the case, it is important that xorlab Security Platform knows about external reporting addresses. Emails sent to or from such addresses may contain malicious content, which xorlab Security Platform should ignore. Otherwise, malicious URLs in reported emails may start to build up a local reputation.

To let xorlab Security Platform know about these other reporting addresses, add them to the list under **Settings → Lists → Reported**.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **External reporting addresses (regex)** | List of external spam-reporting addresses | Regular expressions to match email addresses, e.g., `^(?i)spam@company\.com$` |


# Activate Case Isolation
Source: https://docs.xorlab.com/latest/m365-case-isolation

Remove delivered emails from Microsoft 365 mailboxes through the Graph API using the Isolate action.

As soon as you activate this feature, the **Isolate** button appears in the detail view of every email.

<Warning>
  **Prerequisites**

  * Complete [Create Entra ID App](/latest/m365-entra-id-app)
  * Have access to [Entra ID Portal](https://entra.microsoft.com) with an Administrator role
  * Know your customer ID `xyz`, e.g. `xyz.activeguard.cloud`
</Warning>

## Configure Entra ID

1. Go to [Entra ID Portal](https://entra.microsoft.com/) → **Overview** → copy the **Tenant ID** and keep it for future use.

   <img alt="Your AAD Tenant ID" />

2. In the menu left, go to **App registrations** → select **All applications** → copy the **Application (client) ID** and keep it for future use.

   <img alt="Application (client) ID" />

3. Open the `xorlab` app → **Certificates & secrets** → **Add a certificate or secret** in the list in the main view:

   <img alt="Application certificates and secrets" />

4. Click **New client secret**:

   <img alt="New client secret" />

5. Enter a description for the client secret and set the expiration time in the **Add a client secret** pane that shows up on the right. Click **Add**.

   <Note>
     **Expiration reminder**

     Please make sure to set a reminder for the secret expiration date, since there is no warning message or other information from M365 on the expiring secret.
   </Note>

6. Copy the **Value** of the secret and keep it for future use. This value is displayed only once. If you forget to copy the value or lose it, just delete this secret and create a new one.

   <img alt="Secret value" />

7. Select **API permissions** from the left pane and click **Add a permission**:

   <img alt="Adding an API permission for your app" />

   <Note>
     **Default permission**

     There can be a default `User.Read` permission already added to your app. It can be left there.
   </Note>

8. Choose **Microsoft Graph**:

   <img alt="Selecting Microsoft Graph API" />

9. Click **Application permissions**:

   <img alt="Application permissions" />

10. Available permissions grouped in categories are displayed. Use the search field to filter the permissions:

    * Filter for `mail` and check the box next to `Mail.ReadWrite`

      <img alt="Selecting mail permissions" />

    * Filter for `user.read` and check the box next to `User.Read.All`

      <img alt="Selecting user permissions" />

11. Click **Add permissions**. On the main **API Permissions** page, you should see the three new permissions granted. Click the **Grant admin consent for…** button above the list to apply the permissions change.

    <img alt="New permissions for your app" />

## Configure xorlab

1. In xorlab, open the **Admin** view in the upper right. If you have more than one tenant, select the one you want to activate case isolation for in the dropdown.

2. Open **Integrations**, and add the *Tenant ID*, *Application (client) ID* and *Client Secret* value from before to the **Credentials** section and save it.

   <img alt="M365 credentials" />

3. Go back to the Expert Editor and open the file `shared/guarded_tenants.yml`.

4. Enable case isolation for the corresponding tenant by adding these two lines:

   ```yaml shared/guarded_tenants.yml {5-6} theme={null}
   tenants:
     - name: <tenant-name>
       domains:
         - <tenant-domain>
       caseIsolation:
         enabled: true
   ```

5. Click **Publish**. Within about one minute, case isolation will be active for that tenant.

## Next steps

* [Move M365 Quarantine to xorlab](/latest/m365-move-quarantine)


# Create Entra ID App
Source: https://docs.xorlab.com/latest/m365-entra-id-app

Register the mandatory xorlab app in Entra ID for M365 SAML login and optional case isolation or retrospective scanning.

Create a basic app for xorlab in Entra ID before enabling the required [SAML Login](/latest/m365-saml-entra-authentication). The same app is also used for optional [Case Isolation](/latest/m365-case-isolation) and [Retrospective Email Scanning](/latest/m365-retrospective-email-scanning).

1. Log in to the [Entra ID Portal](https://entra.microsoft.com).

2. Go to *Enterprise Application* via the search:

   <img alt="Selecting an enterprise application" />

3. Click **New application**:

   <img alt="New application" />

4. Click **Create your own application**. Enter `xorlab` as name. Select **Integrate any other application you don’t find in the gallery**:

   <img alt="Create your own application" />

5. Click **Create**. The application is now available under **App registrations** → **All applications**.

## Next steps

Continue with the mandatory SAML login first:

* [SAML Login](/latest/m365-saml-entra-authentication)

Then enable the protection mode for your tenant, which is also mandatory:

* Either [M365 Monitoring Mode](/latest/m365-monitoring-mode) or [M365 Inline Mode](/latest/m365-inline-mode)

The app created here is also used by these optional steps:

* [Retrospective Email Scanning](/latest/m365-retrospective-email-scanning) — run this *before* the tenant goes inline, as it is not supported for inline tenants
* [Case Isolation](/latest/m365-case-isolation)


# Enable M365 Inline Mode
Source: https://docs.xorlab.com/latest/m365-inline-mode

Put xorlab in the Microsoft 365 delivery path so it can block and quarantine. Your MX records stay untouched.

The integration is done via mail flow rules and connectors.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration)  and [Set Up Email Routing in xorlab](/latest/m365-smtp)
  * Have access to [Exchange Admin Center](https://admin.exchange.microsoft.com/)
  * Know your xorlab smart host and the domain name on the xorlab MTA certificate, e.g. `mx.xyz.activeguard.cloud` and `*.xyz.activeguard.cloud`
  * Have the value for the `x-xor-tenant-token` header, which both mail flow rules set
</Warning>

## Choose how to configure it

Both paths create the same two connectors and the same two mail flow rules. Pick one.

<CardGroup>
  <Card title="Quick integration with PowerShell" icon="terminal" href="#quick-integration-with-powershell">
    Run one script that asks for your values. Mail flow rules need to be activated manually.
  </Card>

  <Card title="Manual integration in the Exchange Admin Center" icon="hand-pointer" href="#manual-integration-in-the-exchange-admin-center">
    The same configuration manually in the web interface. Use it if you prefer to see each setting before you apply it.
  </Card>
</CardGroup>

## Quick integration with PowerShell

One script creates both connectors and both mail flow rules. It asks for your values, shows a summary and changes nothing until you confirm. You need the **Exchange Administrator** role and the `ExchangeOnlineManagement` module. Run it either in a PowerShell window on your own machine or in the Azure Cloud Shell.

<Accordion title="Installing ExchangeOnlineManagement module locally">
  Run these once, in a PowerShell window on your own machine. Everything installs for your user account only, so you do not need local administrator rights:

  ```powershell wrap theme={null}
  Install-PackageProvider -Name NuGet -Force -Scope CurrentUser
  Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force -AllowClobber
  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  Import-Module ExchangeOnlineManagement -Force
  ```
</Accordion>

1. Download the script with the command on [Script Downloads](/latest/script-downloads#exchange-online-setup-script), which requires you to log in. Run that command in your PowerShell window, then come back here and start the script. If you are not signed in to Exchange Online yet, a sign-in window opens first. In the Azure Cloud Shell, the script shows a code instead: open [microsoft.com/devicelogin](https://microsoft.com/devicelogin) in any browser tab and enter it there:

   ```powershell wrap theme={null}
   ./xorlabExoSetup.ps1 -Mode Inline
   ```

   If one of the connectors or rules already exists in your tenant, the script stops without changing anything.

2. Answer the prompts:

   | Prompt | What to enter |
   | :- | :- |
   | Smart host | The full MX domain of your xorlab MTAs, for example `mx.xyz.activeguard.cloud`. The script looks up the xorlab MTA IPs from it. |
   | Certificate domain | The domain name on the xorlab MTA certificate, which M365 verifies, for example `*.xyz.activeguard.cloud`. |
   | Header value | The value both mail flow rules write into the `x-xor-tenant-token` header. |
   | Scope | `org` applies the rules to the whole organization. `test` limits them to one mailbox; see [Test with one mailbox first](#test-with-one-mailbox-first). |
   | Test mailbox | Only for `test`: the mailbox you test with. |
   | Validation mailbox | A company mailbox that receives the connector validation email. Defaults to the test mailbox. |

3. Check the summary and confirm with `y`. The script then:

   * creates the `xorlabToMicrosoft365` and `Microsoft365Toxorlab` connectors
   * validates `Microsoft365Toxorlab` and summarizes the result
   * creates the `IncomingToxorlab` and `OutgoingToxorlab` mail flow rules, **disabled**

   In the validation summary, the connectivity check should succeed. The test email can fail at this point; if it does, validate the connector again in the Exchange Admin Center once the mail flow rules are enabled. The Exchange Admin Center shows the connector as not validated until you validate it there.

4. Enable both rules:

   ```powershell wrap theme={null}
   Enable-TransportRule -Identity "IncomingToxorlab"
   Enable-TransportRule -Identity "OutgoingToxorlab"
   ```

   This is the step that puts xorlab in the delivery path. It can take several minutes until the rules are active. Test them by sending an incoming and an outgoing email.

If M365 rejects emails from xorlab afterward, or files them as junk, see [Troubleshooting](#troubleshooting).

To remove the connectors and mail flow rules again, run `./xorlabExoSetup.ps1 -Mode Inline -Remove`.

### Test with one mailbox first

With the `test` scope, each rule gets one extra condition on top of its organization-wide ones: `IncomingToxorlab` matches only email **to** the test mailbox, and `OutgoingToxorlab` only email **from** it. All other email keeps its normal mail flow.

When you are done testing, remove that condition and the same rules apply to the whole organization. Either delete it in the Exchange Admin Center under **Mail flow** → **Rules** — **The recipient** → **is this person** on the incoming rule, **The sender** → **is this person** on the outgoing one — or run:

```powershell wrap theme={null}
Set-TransportRule -Identity "IncomingToxorlab" -SentTo $null
Set-TransportRule -Identity "OutgoingToxorlab" -From $null
```

## Manual integration in the Exchange Admin Center

### Create xorlab to M365 connector

This connector makes sure that M365 will accept emails from xorlab.

1. Go to [Exchange Admin Center](https://admin.exchange.microsoft.com/) → **Connectors** → add a connector:

   <img alt="Add a connector" />

2. **Connection from** → **Your organization’s email server**:

   <img alt="New connector" />

3. Set the name to `xorlabToMicrosoft365` and enable **Retain internal Exchange email headers**:

   <img alt="Connector name" />

4. Choose **By verifying that the subject name…** and add `*.xyz.activeguard.cloud` where `xyz` is your customer ID:

   <img alt="Authenticating sent email" />

5. **Create connector**.

### Create M365 to xorlab connector

This connector makes sure that all emails are routed through xorlab.

1. Create a new connector.

2. **Connection from** → **Office 365**, and **Connection to** → **Your organization’s email server**:

   <img alt="New connector from M365" />

3. Set the name to `Microsoft365Toxorlab` and enable **Retain internal Exchange email headers**:

   <img alt="Connector name from M365" />

4. Select **Only when I have a transport rule set up…**:

   <img alt="Use of connector" />

5. Add a new smart host with the value `mx.xyz.activeguard.cloud`, where `xyz` is your customer ID:

   <img alt="Routing" />

6. Activate **Always use Transport Layer Security…** and select **Issued by a trusted certificate authority (CA)**:

   <img alt="Security restrictions" />

7. Enter a company mailbox where a validation email should be sent to:

   <img alt="Validation email" />

   <Note>
     **Unsuccessful validation**

     The connector validation might fail at this point. If this happens, save the connector without validation, create the mail flow rule in the next section and then validate the connector again.
   </Note>

8. Review the connector and click **Create** when it’s OK.

### Create mail flow rules

Here we create mail flow rules that use the connector from above. The mail flow rules make sure that there is no loop between xorlab and M365.

1. Go to [Exchange Admin Center](https://admin.exchange.microsoft.com/) → **Mail flow** → **Rules** and create a new rule:

   <img alt="Creating a new rule" />

2. Configure the rule like this:

   * **Name:** `IncomingToxorlab`
   * **Apply this rule if** → **The sender** → **is external/internal** → **Outside the organization**
   * Click the plus icon (`+`) to add another condition
   * **And** → **The recipient** → **is external/internal** → **Inside the organization**
   * **Do the following** → **Redirect the message to** → **the following connector** → choose **Microsoft365Toxorlab**
   * Click the plus icon (`+`) to add another action
   * **And** → **Modify the message properties** → **set a message header** → set `x-xor-tenant-token` to your header value
   * **Except if** → **The sender** → **IP address is in any of these ranges...** → add all IPs of the xorlab MTAs (find them in the DNS A records of `mx.xyz.activeguard.cloud`)

   <img alt="New rule" />

3. Click through **Next** → **Finish** and leave all settings at their defaults.

4. Repeat steps #2-3 to add another rule but this time set:

   * **Name:** `OutgoingToxorlab`
   * **The sender** → **Inside the organization**
   * **The recipient** → **Outside the organization**
   * **Except if** → **The sender** → **IP address is in any of these ranges...** → the same xorlab MTA IPs as in step #2
   * Click the plus icon (`+`) to add another exception
   * **The message properties** → **Automatic Reply**

   <img alt="Outgoing rule" />

5. Enable both rules in the **Rules** page.

6. It can take several minutes until the rule is active. Test it by sending an incoming and outgoing email.

## Troubleshooting

Apply the following measures only if you experience deliverability issues between M365 and xorlab. Normally, they are not necessary.

### M365 rejects emails from xorlab

If M365 rejects some legitimate emails from xorlab, there are multiple measures. Apply them in order written below until the problem is fixed.

First, add your xorlab domain as an “[accepted domain](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/manage-accepted-domains/manage-accepted-domains)”.

<Accordion title="Add xorlab as accepted domain">
  1. Go to [Microsoft 365 Admin Center](https://admin.microsoft.com/) → **Settings** → **Domains** and add a domain:

     <img alt="add-domain" />

  2. Enter `xyz.activeguard.cloud`, where `xyz` is your customer ID:

     <img alt="Add a domain name" />

  3. Select the first option **Add a text record…**:

     <img alt="Domain verification method" />

  4. Send the TXT value to [support@xorlab.com](mailto:support@xorlab.com) so that we can add it to the DNS record of your domain. After this has been done, **verify**:

     <img alt="Domain verification data" />

  5. After a successful verification, click **More options** and select **Skip and do this later**:

     <img alt="Domain skip and do this later" />
</Accordion>

If that does not help, you can add xorlab to your SPF records.

<Accordion title="Add xorlab to your SPF records">
  You can add the xorlab MTAs to your SPF records. For this, include `a:mx.xyz.activeguard.cloud` to all your domains that route emails via xorlab:

  ```shell theme={null}
  dig +short TXT customer.tld
  "v=spf1 a:mx.xyz.activeguard.cloud include:spf.protection.outlook.com -all"
  ```

  Afterward, check that your SPF records are still valid, for example with  DMARCanalyzer’s [SPF checker](https://www.dmarcanalyzer.com/spf/checker/).
</Accordion>

If adding xorlab to your SPF record did also not help, you can add xorlab to the anti-spam policy of M365.

<Accordion title="Add xorlab to the M365 anti-spam policy">
  1. Go to [**Anti-spam policies**](https://security.microsoft.com/antispam) and select **Connection filter policy (Default)**:

     <img alt="Anti-spam policies" />

  2. Click **Edit connection filter policy**:

     <img alt="Connection filter policy" />

  3. Enter the xorlab MTA IPs to the first field:

     <img alt="Allowed IPS for connection cilter" />

  4. Check if the addresses are correct under **IP Allow list** and click **Close**.
</Accordion>

### M365 puts emails from xorlab into Junk

The following mail flow rule will bypass the M365 spam filtering for emails coming from xorlab. Note that this will mostly disable the Junk folder mechanism for your mailboxes.

<Accordion title="Bypass spam filtering">
  1. Go to [Exchange Admin Center](https://admin.exchange.microsoft.com/) → **Mail flow** → **Rules** and create a new rule:

     <img alt="Creating a new rule" />

  2. Configure the rule like this:

     * **Name:** `SpamBypassxorlab`.
     * **Apply this rule if** →  **The sender** → **IP address is in any of these ranges...** → add all IPs of the xorlab MTAs
     * Click the plus icon (`+`) to add another condition
     * **And** → **The message properties** → **include an SCL greater than or equal to** → **Bypass spam filtering**
     * **Do the following** → **Modify the message properties** → **set the spam confidence level (SCL)** → **Bypass spam filtering**

       <img alt="Bypass spam filtering actions" />

  3. Click through **Next** → **Finish** and leave all settings at their defaults.

  4. Enable the rule in the **Rules** page.
</Accordion>

## Next steps

Optionally continue with:

* [Activate Case Isolation](/latest/m365-case-isolation)
* [Move M365 Quarantine to xorlab](/latest/m365-move-quarantine)
* [Integrate M365 Reported Emails](/latest/m365-reporting-integration)

Once the integration is complete, continue with [What to Configure Next](/latest/integration-next-steps).


# M365 Overview
Source: https://docs.xorlab.com/latest/m365-integration-overview

The complete ordered step list for integrating xorlab with Microsoft 365.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration)
</Warning>

Your MX records stay with Microsoft: every step below is a connector, a mail flow rule or an app registration inside your own tenant. See [Review What Changes in Your Environment](/latest/integration-impact#microsoft-365) for the full list, including what stays untouched and how to undo it.

| Step | Description |
| :- | :- |
| [Set Up Email Routing in xorlab](/latest/m365-smtp) | **Mandatory**. Configure xorlab to accept and forward emails with your M365 tenant. |
| [Create Entra ID App](/latest/m365-entra-id-app) | **Mandatory**. Create the xorlab app in Entra ID. This is required for the mandatory Entra ID SAML login and is also used by Case Isolation and Retrospective Email Scanning. |
| [Enable SAML Login](/latest/m365-saml-entra-authentication) | **Mandatory**. Allow single sign-on (SSO) via Entra ID. |
| [Import Past M365 Emails](/latest/m365-retrospective-email-scanning) | **Optional**. Import historical emails during onboarding to speed up the learning phase. |
| Enable either M365 [Monitoring](/latest/m365-monitoring-mode) or [Inline](/latest/m365-inline-mode) mode | **Mandatory**. In Monitoring mode, M365 sends just copies of emails to xorlab. In Inline mode, M365 routes emails via xorlab for active protection. See [Before you begin](/latest/before-begin-integration#choose-between-inline-and-monitoring-mode) and below for more information. |
| [Activate Case Isolation](/latest/m365-case-isolation) | **Optional**. Allow removing emails from mailboxes after they have been delivered. |
| [Move M365 Quarantine to xorlab](/latest/m365-move-quarantine) | **Optional**. Make sure that users only need to use the xorlab quarantine. This instructs M365 to send malicious emails to xorlab instead of quarantining them itself. |
| [Integrate M365 Reported Emails](/latest/m365-reporting-integration) | **Optional**. Integrate the Abuse Mailbox with xorlab such that reported emails are handled by xorlab. |

## Inline mode diagrams

In Inline mode, xorlab filters all emails and sends the benign ones back to M365 for final delivery.

<Card title="M365 Inline mode">
  <img alt="M365 Inline mode" />

  [Open the M365 Inline mode guide](/latest/m365-inline-mode)
</Card>

## Monitoring mode diagrams

In Monitoring mode, xorlab receives only a copy of every email and discards it after processing.

<Card title="M365 Monitoring mode">
  <img alt="M365 Monitoring mode" />

  [Open the M365 Monitoring mode guide](/latest/m365-monitoring-mode)
</Card>

## Multi-Tenancy

If you integrate more than one M365 tenant with the same xorlab instance, follow [Add a Tenant](/latest/multi-tenancy-new-tenant) instead of the table above. It uses the same guides, but adds the per-tenant configuration around them:

* Configure the domains and routing of the tenant with the [M365 topology](/latest/multi-tenancy-domain-and-routing#m365-topology).
* Set up SAML per tenant, see [Enable Tenant Login](/latest/multi-tenancy-authentication).
* Assign reported emails to the right tenant, see [Assign Reported Emails to Tenants](/latest/multi-tenancy-reported-emails).


# Enable M365 Monitoring Mode
Source: https://docs.xorlab.com/latest/m365-monitoring-mode

Set up out-of-band observation in Microsoft 365. In this mode xorlab analyzes traffic and still decides on it, but cannot intervene in your mail flow.

M365 sends a copy of every incoming and outgoing email to xorlab.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/m365-smtp)
  * Have access to [Exchange Admin Center](https://admin.exchange.microsoft.com/)
  * Know your xorlab smart host and monitoring address, e.g. `mx.xyz.activeguard.cloud` and `monitor@mx.xyz.activeguard.cloud`
  * Have the value for the `x-xor-tenant-token` header, which both mail flow rules set
</Warning>

<Info>
  * Using BCC monitoring sends an additional copy of each email to xorlab, which can lead to hitting the external recipients rate limit (tenant ERRL) of Microsoft Exchange.
  * You can monitor how close you are to the limit under: **Reports → Mail flow → Outbound external recipients**
</Info>

## Choose how to configure it

Both paths create the same connector and the same two mail flow rules. Pick one.

<CardGroup>
  <Card title="Quick integration with PowerShell" icon="terminal" href="#quick-integration-with-powershell">
    Run one script that asks for your values. Mail flow rules need to be activated manually.
  </Card>

  <Card title="Manual integration in the Exchange Admin Center" icon="hand-pointer" href="#manual-integration-in-the-exchange-admin-center">
    The same configuration manually in the web interface. Use it if you prefer to see each setting before you apply it.
  </Card>
</CardGroup>

## Quick integration with PowerShell

One script creates the connector and both mail flow rules. It asks for your values, shows a summary and changes nothing until you confirm. You need the **Exchange Administrator** role and the `ExchangeOnlineManagement` module. Run it either in a PowerShell window on your own machine or in the Azure Cloud Shell.

<Accordion title="Installing ExchangeOnlineManagement module locally">
  Run these once, in a PowerShell window on your own machine. Everything installs for your user account only, so you do not need local administrator rights:

  ```powershell wrap theme={null}
  Install-PackageProvider -Name NuGet -Force -Scope CurrentUser
  Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force -AllowClobber
  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  Import-Module ExchangeOnlineManagement -Force
  ```
</Accordion>

1. Download the script with the command on [Script Downloads](/latest/script-downloads#exchange-online-setup-script), which requires you to log in. Run that command in your PowerShell window, then come back here and start the script. If you are not signed in to Exchange Online yet, a sign-in window opens first. In the Azure Cloud Shell, the script shows a code instead: open [microsoft.com/devicelogin](https://microsoft.com/devicelogin) in any browser tab and enter it there:

   ```powershell wrap theme={null}
   ./xorlabExoSetup.ps1 -Mode Monitoring
   ```

   If the connector or one of the rules already exists in your tenant, the script stops without changing anything.

2. Answer the prompts:

   | Prompt | What to enter |
   | :- | :- |
   | Smart host | The full MX domain of your xorlab MTAs, for example `mx.xyz.activeguard.cloud`. |
   | Monitoring address | The address that receives the copies. Defaults to `monitor@` followed by the smart host. The connector only carries mail to this address’s domain. |
   | Header value | The value both mail flow rules write into the `x-xor-tenant-token` header. |
   | Scope | `org` applies the rules to the whole organization. `test` limits them to one mailbox; see [Test with one mailbox first](#test-with-one-mailbox-first). |
   | Test mailbox | Only for `test`: the mailbox you test with. |

3. Check the summary and confirm with `y`. The script then:

   * creates the `Microsoft365Toxorlab` connector
   * validates it with a test email to the monitoring address and summarizes the result
   * creates the `IncomingBCCxorlab` and `OutgoingBCCxorlab` mail flow rules, **disabled**

   In the validation summary, both the connectivity check and the test email should succeed. If one fails, the script continues anyway; validate the connector again later in the Exchange Admin Center. It shows as not validated there until you do, because `Validate-OutboundConnector` does not record its result on the connector.

4. Enable both rules:

   ```powershell wrap theme={null}
   Enable-TransportRule -Identity "IncomingBCCxorlab"
   Enable-TransportRule -Identity "OutgoingBCCxorlab"
   ```

   From then on, M365 sends a copy of every incoming and outgoing email to xorlab. It can take several minutes until the rules are active.

To remove the connector and mail flow rules again, run `./xorlabExoSetup.ps1 -Mode Monitoring -Remove`.

### Test with one mailbox first

With the `test` scope, each rule gets one extra condition on top of its organization-wide ones: `IncomingBCCxorlab` matches only email **to** the test mailbox, and `OutgoingBCCxorlab` only email **from** it. No copies are sent for any other email.

When you are done testing, remove that condition and the same rules apply to the whole organization. Either delete it in the Exchange Admin Center under **Mail flow** → **Rules** — **The recipient** → **is this person** on the incoming rule, **The sender** → **is this person** on the outgoing one — or run:

```powershell wrap theme={null}
Set-TransportRule -Identity "IncomingBCCxorlab" -SentTo $null
Set-TransportRule -Identity "OutgoingBCCxorlab" -From $null
```

## Manual integration in the Exchange Admin Center

### Create mail flow rule

1. Go to [Exchange Admin Center](https://admin.exchange.microsoft.com/) → **Mail flow** → **Rules** and create a new rule:

   <img alt="Creating a new rule" />

2. Configure the rule like this:

   * **Name:** `IncomingBCCxorlab`
   * **Apply this rule if** → **The sender** → **is external/internal** → **Outside the organization**
   * Click the plus icon (`+`) to add another condition
   * **And** → **The recipient** → **is external/internal** → **Inside the organization**
   * **Do the following** → **Add Recipients** → **to the Bcc box** → enter `monitor@mx.xyz.activeguard.cloud`, where `xyz` is your customer ID
   * Click the plus icon (`+`) to add another action
   * **And** → **Modify the message properties** → **set a message header** → set `x-xor-tenant-token` to your header value

   <img alt="Rule settings for incoming emails" />

3. Click through **Next** → **Finish** and leave all settings at their defaults.

4. Repeat steps #2-3 to add another rule but this time set:

   * **Name:** `OutgoingBCCxorlab`
   * **The sender** → **Inside the organization**
   * **The recipient** → **Outside the organization**

   <img alt="Rule settings for outgoing emails" />

5. Enable both rules in the **Rules** page.

Now, a copy of every incoming and outgoing email will be sent to xorlab.

### Create a connector

In addition to the mail flow rule above, we need to create a connector to make sure the emails are sent directly to xorlab.

<Accordion title="Additional information">
  We recommend to always create a connector to ensure proper email delivery. However, you can omit the connector if the following two conditions are met:

  * You do not have any other connectors that might interfere with the BCC emails sent to xorlab.
  * You do not have a hybrid MS setup with an on-prem-only email delivery (*Centralized Mail Transport*).
</Accordion>

1. Go to [Exchange Admin Center](https://admin.exchange.microsoft.com/) → **Connectors** → add a connector:

   <img alt="Add a connector" />

2. **Connection from** → **Office 365**, and **Connection to** → **Your organization’s email server**:

   <img alt="New connector from O365" />

3. Set the name to `Microsoft365Toxorlab` and enable **Retain internal Exchange email headers**:

   <img alt="Connector name from M365" />

4. Choose the third option and enter `mx.xyz.activeguard.cloud`, where `xyz` is your customer ID. Click the plus (`+`) icon:

   <img alt="Use of connector" />

5. Add a new smart host with the value `mx.xyz.activeguard.cloud`, where `xyz` is your customer ID:

   <img alt="Routing" />

6. Activate **Always use Transport Layer Security…** and select **Issued by a trusted certificate authority (CA)**:

   <img alt="Security restrictions" />

   *Security restrictions*

7. Enter a company mailbox where a validation email should be sent to:

   <img alt="Validation email" />

   <Note>
     **Unsuccessful validation**

     The connector validation might fail at this point. If this happens, save the connector without validation, and then validate the connector again.
   </Note>

8. Review the connector and click **Create** when it’s OK.

## Optional: Include internal emails

Per default, xorlab only processes incoming and outgoing emails. However, if you want to include also internal emails, do the following:

* Remove one of the two mail flow rules from above
* Rename the existing one to `BCCxorlab`
* Change **Apply this rule if** to **Apply to all messages** and remove the **And** condition

<img alt="Configuring the monitor rule" />

Now, a copy of every email will be sent to xorlab.

## Next steps

Optionally continue with:

* [Activate Case Isolation](/latest/m365-case-isolation)
* [Move M365 Quarantine to xorlab](/latest/m365-move-quarantine)
* [Integrate M365 Reported Emails](/latest/m365-reporting-integration)

Once the integration is complete, continue with [What to Configure Next](/latest/integration-next-steps).


# Move M365 Quarantine to xorlab
Source: https://docs.xorlab.com/latest/m365-move-quarantine

Move the Microsoft 365 quarantine to xorlab so end users have a single quarantine, including the known limitations.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/m365-smtp)
  * Have either [M365 Monitoring Mode](/latest/m365-monitoring-mode) or [M365 Inline Mode](/latest/m365-inline-mode) enabled
  * Have access to the [Microsoft Defender portal](https://security.microsoft.com) with permission to edit anti-spam policies
</Warning>

<Note>
  **Limitation**

  Although you can force M365 to pass quarantined emails to xorlab, the ones recognized as malware or high-confidence phishing cannot be moved out of M365 quarantine.
</Note>

1. Go to [the Anti-spam settings page](https://security.microsoft.com/antispam) → open **Anti-spam Inbound policy (Default)**:

   <img alt="Anti-spam policies" />

2. Scroll down the pane until you see the **Edit actions** link:

   <img alt="Edit anti-spam actions" />

3. Select **Add X-header** from the drop-down list for:

   * **Spam**
   * **High-confidence spam**
   * **Phishing**
   * **Bulk complaint level (BCL) met or exceeded**

   In the **Add this X-header text**, enter `x-eopmarkedspam` (this value is required by xorlab):

   <img alt="Anti-spam actions" />

4. Click **Save**.

By default, xorlab recognizes the EOP header and assigns the `#eopmarkedspam` tag to the email. This tag increases the likelihood that the email will be classified as spam. To reduce false positives, these emails are not automatically quarantined. If desired, you can create a campaign that automatically quarantines all emails tagged with `#eopmarkedspam`.

## Next steps

* [Integrate M365 Reported Emails](/latest/m365-reporting-integration)


# Integrate M365 Abuse Mailbox
Source: https://docs.xorlab.com/latest/m365-reporting-integration

Connect the built-in Microsoft 365 reporting button to xorlab so reported emails appear in xorlab and reporters receive feedback.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/m365-smtp)
</Warning>

## Prepare xorlab

1. Open `shared/guarded_tenants.yml` and add all email address patterns that are allowed to report emails.

   ```yaml guarded_tenants.yml {4-6} theme={null}
   tenants:
     - name: example
       emailReporting:
         authorizedEmailReportRecipients:
           - .*@xorlab\.com
           - .*@xorlab\.net
   ```

2. Choose if you want to enable or disable automatic feedback. If enabled, every reporter will get an immediate feedback email.

   <CardGroup>
     <Card title="Automatic feedback" icon="shield">
       ```yaml guarded_tenants.yml {4,5} theme={null}
       tenants:
         - name: example
           ruleProfiles:
             # REMOVE this line
             - no_auto_feedback.properties
       ```
     </Card>

     <Card title="Disabled feedback" icon="xmark">
       ```yaml guarded_tenants.yml {4,5} theme={null}
       tenants:
         - name: example
           ruleProfiles:
             # ADD this line
             - no_auto_feedback.properties
       ```
     </Card>
   </CardGroup>

3. Optional: Change the sender address used for feedback emails: [Change Sender Address](/latest/email-template-sender-addresses#feedback-emails).

4. Click **Publish**. The new configuration becomes active within about one minute.

## Forward M365 reported emails to xorlab

You need a dedicated mailbox in M365 that receives reported emails. If you don't have one, create one like `reporting@example.com` first. Both paths below require it.

Both paths configure the same user reported settings and the same mail flow rule. Pick one.

<CardGroup>
  <Card title="Quick integration with PowerShell" icon="terminal" href="#quick-integration-with-powershell">
    Run one script that asks for your values. The mail flow rule needs to be activated manually.
  </Card>

  <Card title="Manual integration in the admin portals" icon="hand-pointer" href="#manual-integration-in-the-admin-portals">
    The same configuration manually in the Microsoft Defender portal and the Exchange Admin Center. Use it if you prefer to see each setting before you apply it.
  </Card>
</CardGroup>

### Quick integration with PowerShell

The script configures the user reported settings and creates the mail flow rule. Run it either in a PowerShell window on your own machine or in the Azure Cloud Shell. You need **Exchange Administrator** role for the mail flow rule, **Security Administrator** role for the user reported settings and the `ExchangeOnlineManagement` Powershell module.

<Accordion title="Installing ExchangeOnlineManagement module locally">
  Run these once, in a PowerShell window on your own machine. Everything installs for your user account only, so you do not need local administrator rights:

  ```powershell wrap theme={null}
  Install-PackageProvider -Name NuGet -Force -Scope CurrentUser
  Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force -AllowClobber
  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  Import-Module ExchangeOnlineManagement -Force
  ```
</Accordion>

1. Download the script with the command on [Script Downloads](/latest/script-downloads#exchange-online-setup-script). Run that command in your PowerShell window, then come back here and start the script. If you are not signed in to Exchange Online yet, a sign-in window opens first. In the Azure Cloud Shell, the script shows a code instead: open [microsoft.com/devicelogin](https://microsoft.com/devicelogin) in any browser tab and enter it there:

   ```powershell wrap theme={null}
   ./xorlabExoSetup.ps1 -Mode Reporting
   ```

   If the `xorlabReportingIntegration` rule already exists in your tenant, the script stops without changing anything.

2. Answer the prompts:

   | Prompt | What to enter |
   | :- | :- |
   | Internal mailbox | Your internal mailbox where you can receive reported emails, for example `reporting@example.com`. It must already exist. |
   | Destination | `mailbox` sends reported emails to your reporting mailbox only. `both` sends them to Microsoft as well. |
   | xorlab reporting address | The address xorlab receives reported emails on, for example `suspicious@mx.xyz.activeguard.cloud`. |

3. Check the summary and confirm with `y`. The summary also shows the reporting mailbox that is configured now, which the script replaces. The script then:

   * turns on **Monitor reported messages in Outlook** and sends reported emails to your reporting mailbox, and to Microsoft if you chose `both`
   * creates the `xorlabReportingIntegration` mail flow rule, **disabled**

4. Enable the rule, then [test the integration](#test-the-integration):

   ```powershell wrap theme={null}
   Enable-TransportRule -Identity "xorlabReportingIntegration"
   ```

To remove the mail flow rule again, run `./xorlabExoSetup.ps1 -Mode Reporting -Remove`. The user reported settings stay as they are.

### Manual integration in the admin portals

1. In the [M365 Defender portal](https://security.microsoft.com/)  go to **Settings** → **Email & collaboration** → **User reported settings**. Or directly via [User submissions](https://security.microsoft.com/securitysettings/userSubmission).

2. Activate **Monitor reported messages in Outlook**.

3. Scroll down to **Reported message destinations** and add your reporting mailbox to the mailbox field. Choose either **My reporting mailbox only** or **Microsoft and my reporting mailbox** in the dropdown.

   <img alt="Email address for reported messages" />

4. Click **Save**.

5. Go to [Exchange Mail Flow](https://admin.exchange.microsoft.com/#/transportrules) and create a new rule with the name `xorlabReportingIntegration`:

   * **Apply this rule if** → **The recipient** → **is this person** and select your reporting mailbox.
   * **Do the following** → **Redirect the message to** → enter the xorlab reporting address `suspicious@mx.xyz.activeguard.cloud`, where `xyz` is your customer ID.

   <img alt="Reporting rule conditions" />

6. Click **Next** until **Finish**, then **Done**.

7. Enable the new rule.

## Test the integration

1. Report an email via the M365 built-in button. It is available in the web interface as well as in Outlook.
2. In xorlab, go to **Abuse Mailbox** → **All Cases** and there you should see the reported email. It can take up to 30 seconds to appear.
3. If you enabled **automatic feedback** in the beginning, you should receive a feedback email within 30 seconds.

## How to change the reporting address

The default address under which xorlab will listen for reported emails is `suspicious@<templateDomain>`, with `templateDomain` referring to the parameter that's set in `active_guard.yml`.

If you like to customize the sender address, add the following block (if it does not already exist) to the `active_guard.yml` file:

```yaml active_guard.yml {7} theme={null}
scanSources:
  smtp:
    port: 10025
    handler:
      smtpReport:
        # Default. <templateDomain> corresponds to the parameter templateDomain in active_guard.yml
        emailAddress: suspicious@<templateDomain>
```

Afterward, click **Publish**. The `scanSources` handler settings become active within about one minute.

## How to automate reported email handling

For further information about automation, have a look at [Abuse Mailbox](/latest/abuse-mailbox#auto-resolve-cases).

## How "Not Junk" reports are handled

When you integrate M365 reporting, xorlab adds one of the following tags to each reported email:

* `#reportedasnotjunk` for messages reported as **Not Junk**
* `#reportedasjunk` for messages reported as **Junk**
* `#reportedasphishing` for messages reported as **Phishing**

Default behavior:

* **Not Junk**: the case is automatically resolved as `benign` by `REPORTED_NOT_JUNK_decision`, no acknowledgment email is sent, and the `#reportedasnotjunk` tag is added.
* **Junk/Phishing**: the corresponding tag is added, acknowledgment is sent (if enabled), and the case is handled by normal reported-email analysis.

`REPORTED_NOT_JUNK_decision` is evaluated before campaigns, so these cases are auto-resolved before campaign rules are applied.

To disable this auto-resolve behavior and return to normal reported-email handling, set the rule state to `PASSIVE` in `/activeguard/core/rule_sets/90_local/params/local.properties`:

```shell local.properties theme={null}
# Disable auto-resolve for M365 "Not Junk" reports
REPORTED_NOT_JUNK_decision_state=PASSIVE
```

Then click **Publish**. The rule-set configuration becomes active within about one minute.

## Multi-Tenancy

Repeat this integration for each M365 tenant. In addition, xorlab needs to know which tenant a reported email belongs to, which is decided by a header on the carrier email:

<Card title="Assign Reported Emails to Tenants" icon="building" href="/latest/multi-tenancy-reported-emails">
  Add the `x-ag-tenant` header so that reported emails end up in the right tenant.
</Card>

Note that `local.properties` above applies to all tenants. To change this behavior for a single tenant only, see [Manage Tenant Rules](/latest/multi-tenancy-rules#tenant-specific-parameters).

## Next steps

The M365 integration is complete:

* [What to Configure Next](/latest/integration-next-steps)


# Import Past M365 Emails
Source: https://docs.xorlab.com/latest/m365-retrospective-email-scanning

Backfill the relationship and reputation models from mailbox history, so protection is effective sooner after go-live.

Import past emails from M365 and pushes them through xorlab for analysis (Retrospective Email Scanning).

This is intended as a one-time onboarding step for a new tenant or customer. It can only be used for domains that are not already inline with xorlab.

## What you achieve

With Retrospective Email Scanning, you can:

* Import past emails from M365 for one tenant
* Speed up the initial learning phase
* Observe imported emails in the normal xorlab message view

Imported emails are processed similarly to live emails. In the message list, the **Received** date remains the original date of the message, not the import date.

## Before you start

1. Add your tenant to `shared/guarded_tenants.yml`. An example can be found [here](/latest/before-begin-integration#configure-your-guarded-domains).
2. Customize detection for that tenant. For standard onboardings, this only includes adding list entries: [Configure built-in lists](/latest/detection-overview#configure-built-in-lists).
3. Complete [Create Entra ID App](/latest/m365-entra-id-app).

## Configure Microsoft Graph permissions

Set up Microsoft permissions:

1. Follow exactly as described in [Configure Entra ID for Case Isolation](/latest/m365-case-isolation#configure-entra-id). If you have done that already for case isolation, then this step is not necessary anymore.
   <Note>
     **Same credentials as case isolation**
     Retrospective Email Scanning uses the same Graph credentials as [Case Isolation](/latest/m365-case-isolation).
   </Note>

The application must include these permissions:

* `Mail.Read`
* `User.Read.All`

The Graph credential is currently shared between the Retrospective Email Scanning and Case Isolation. If you also use Case Isolation, `Mail.Read` must be replaced with `Mail.ReadWrite`.

## Add the Graph credentials in xorlab

1. Open the **Admin** view in xorlab.
2. Select the tenant for which you want to run the import.
3. Open **Microsoft 365**.
4. Add the *Tenant ID*, *Application (client) ID*, and *Client Secret* in the **Credentials** section.
5. Save the credentials.

<img alt="M365 credentials" />

## Start a new import

1. Open **Admin → Microsoft 365** for the tenant.
   <Note>
     **Choose a tenant**
     If you have more than one tenant, you need to select one of them in the dropdown on top.
   </Note>
2. Click on **New Import**.
   <img alt="M365 import" />
3. Enter a name for the import.
4. Set the time range to **3 months**. Depending on the situation, this can be increased or decreased. However, for proper learning at least one month is required. For a quick test, you can choose a short time range of 1 hour.
5. Start the import.
   <Warning>
     **Tenant data reset**
     Starting a new import job removes all past email data of that tenant.
   </Warning>
6. After the import is through, you can continue with the normal M365 onboarding by either activating [Inline](/latest/m365-inline-mode) or [Monitoring](/latest/m365-monitoring-mode).

## Additional information

The below chapters provide more information about the Retrospective Email Scanning itself.

### Important behavior

<Warning>
  **Tenant data reset**

  Starting an import job wipes the tenant data before the import begins. This includes result publication, trust values, reputation values, and related learned state. xorlab then starts from a clean slate for that tenant.
</Warning>

Only emails from the tenant domains defined in `shared/guarded_tenants.yml` are imported.

If a guarded domain contains a pattern, xorlab strips the pattern and uses the base domain instead. Example:

* `*.xorlab.com` becomes `xorlab.com`

### Watch the import progress

An import job can have the following active states:

* `INDEXING`: xorlab is indexing the messages to be imported
* `IMPORTING`: xorlab is importing and processing the messages

An import job can finish in the following states:

* `COMPLETED`
* `FAILED`
* `CANCELED`

While a job is in the `IMPORTING` state, xorlab shows a progress bar in percent.

### Pause, resume, or cancel a job

* Jobs in the `IMPORTING` phase can be paused and resumed
* Jobs in the `INDEXING` phase cannot be paused
* If you want to stop a job during `INDEXING`, cancel it

### Restrictions

* Retrospective Email Scanning is not supported for tenants with active mail flow. In multi-tenant environments, tenants
  not affected by the import may still have mail flow activated
* The Sandbox is always disabled for imported messages, even if it is enabled elsewhere

### Required permissions

The following xorlab user permissions are required for Retrospective Email Scanning. The built-in `xcc_admin` role contains those already:

* `xcc_mail_import_update`: create, pause, resume, and cancel import jobs
* `xcc_mail_import_read`: view the status of import jobs

For details on custom roles and permissions, see [Create a Custom Role](/latest/create-custom-user-role).

### Related log events

The log events for Retrospective Email Scanning are the `mail_import` ones in [Log Events](/latest/logging-events). To forward them, start at [Logging Overview](/latest/logging-overview).

## Next steps

* Either [M365 Monitoring Mode](/latest/m365-monitoring-mode) or [M365 Inline Mode](/latest/m365-inline-mode)


# Enable Entra ID SAML Login
Source: https://docs.xorlab.com/latest/m365-saml-entra-authentication

Wire Entra ID to xorlab as a SAML identity provider, so analysts, admins or end-users sign in with their Microsoft account.

<Warning>
  **Prerequisites**

  * Complete [Create Entra ID App](/latest/m365-entra-id-app)
  * Have access to [Entra ID Portal](https://entra.microsoft.com) with one of these roles: Cloud Application Administrator, Application Administrator, or owner of the service principal.
  * Know your customer ID `xyz`, e.g. `xyz.activeguard.cloud`
</Warning>

If you want to enable a different login mechanism like for example LDAP, have a look at [Authentication Overview](/latest/authentication-overview).

## Activate SAML in Entra ID

1. Go to [Entra ID Portal](https://entra.microsoft.com) → **Enterprise apps** → click on the `xorlab` app.

2. Open **Single sign-on**:

   <img alt="Set up single sign-on" />

3. Choose **SAML**.

4. Edit the **Basic SAML Configuration**:

   <img alt="Edit the basic SAML configuration" />

5. Add an **Identifier** and a **Reply URL** entry, where `xyz` is your customer ID.

   <img alt="SAML configuration" />

   | Input field name | URL |
   | :- | :- |
   | Identifier (Entity ID) | `https://xyz.activeguard.cloud/auth/saml2/service-provider-metadata/entraSaml` |
   | Reply URL (Assertion Consumer Service URL) | `https://xyz.activeguard.cloud/auth/saml2/sso/entraSaml` |

   <Warning>
     The `entraSaml` part of both URLs is the **SAML backend name**. You will need to use **exactly the same name** later when configuring the SAML authentication in xorlab. Each SAML backend must have a unique name. If you are configuring multiple SAML providers in a multi-tenant deployment, use unique names that identify the tenant (e.g `nameSAML`).
   </Warning>

6. **Save** and click **No, I’ll test it later**.

7. Copy and save the App Federation Metadata URL from **SAML Certificates**, you will need it later.

   <img alt="App Federation Metadata" />

## Configure users and roles in Entra ID

1. Go to [Entra ID Portal](https://entra.microsoft.com) → **App registrations** → **All applications** → click on the `xorlab` app.

   <img alt="App registrations" />

2. Click on **App roles** and then **Create app role**:

   <img alt="Create app role" />

3. Create three new app roles via **Create app role**. The optional ones can be omitted if they are not needed.

   | Display Name | Value | Required? |
   | :- | :- | :- |
   | Administrator | `entra_xor_admin` | Mandatory |
   | Analyst | `entra_xor_analyst` | Optional |
   | Quarantine user | `entra_xor_quarantine_user` | Optional |

   <img alt="App role configuration panel" />

4. Open the **Enterprise apps** menu on the left side, choose again the `xorlab` app and click on **Assign users and groups**:

   <img alt="Assign users and groups" />

5. Click on **Add user/group**:

   <img alt="Add user/group" />

6. Add the users or groups who need access to xorlab and assign them one of the three created roles Administrator, Analyst or Quarantine user.

   <Note>
     **Group assigning is only available in the Microsoft Entra ID P1+ license.**
   </Note>

## Activate SAML on xorlab

Now that you have the Entra ID configured, we will set up xorlab accordingly.

1. Open the file `auth/auth/auth.yml` and add a SAML backend.

   ```yaml auth.yml theme={null}
   enabledAuthBackends:
     # Add this to the list of enabled backends. If you put it as first entry, it will be the new default.
     - entraSaml

   saml2AuthBackends:
     entraSaml:
       idp:
         # Enter the App Federation Metadata URL from Entra ID
         metadataUrl: https://login.microsoftonline.com/*****************************
       attributeMapping:
         displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
         emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
         roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
   ```

   <Warning>
     **If you rename `entraSaml`, make sure to update the Identifier and Reply URL in Entra ID SAML configuration above.**
   </Warning>

2. Enter the **App Federation Metadata Url** you copied before for the `metadataUrl` key.

3. Map your Entra ID roles to xorlab roles by adding a `roleMapping`. More information about xorlab roles can be found at [Built-in User Roles](/latest/built-in-user-roles)

   ```yaml auth.yml {14-27} theme={null}
   enabledAuthBackends:
     - entraSaml

   saml2AuthBackends:
     entraSaml:
       idp:
         # Enter the App Federation Metadata Url from M365
         metadataUrl: https://login.microsoftonline.com/*****************************
       attributeMapping:
         displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
         emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
         roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
       # Add your Entra ID roles to every xorlab role that is required.
       roleMapping:
         xcc_admin:
         - entra_xor_admin
         xcc_monitor:
         - entra_xor_admin
         xcc_analyst:
         - entra_xor_analyst
         xcc_insights:
         - entra_xor_admin
         - entra_xor_analyst
         xcc_quarantine_user:
         - entra_xor_admin
         - entra_xor_analyst
         - entra_xor_quarantine_user
   ```

   <Accordion title="Role pass-through without role mapping">
     The following example shows how to do a role pass-through without role mapping. In general this is not recommended because it is more error prone. However if you do it, make sure to:

     * Specify all xorlab roles in Entra ID (including `xcc_insights` and `xcc_monitor`) and assign them to your users
     * Provide only xorlab related roles in the SAML token to avoid an excessive token size

     ```yaml auth.yml {14} theme={null}
     enabledAuthBackends:
       - entraSaml

     saml2AuthBackends:
       entraSaml:
         idp:
           # Enter the App Federation Metadata Url from M365
           metadataUrl: https://login.microsoftonline.com/*****************************
         attributeMapping:
           displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
           emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
           roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
         # Specify PASS_THROUGH, otherwise xorlab will only consider roles that match the role mapping
         roleMappingMode: PASS_THROUGH
     ```
   </Accordion>

4. Click **Publish**. The authentication configuration becomes active within about one minute.

5. Now the SAML integration is done and you can test the login with the link `https://xyz.activeguard.cloud/?_agAuthBackend=entraSaml`. Replace `xyz` with your customer ID.

<Note>
  **Custom trust store**

  In case your xorlab configuration uses a custom trust store, you will also have to add the [DigiCert Global Root CA certificate](https://cacerts.digicert.com/DigiCertGlobalRootCA.crt.pem) when integrating SAML with Azure Active Directory. Please follow the steps described in [Certificate configuration](/latest/authentication-certificates).
</Note>

## Next steps

Enable the protection mode for your tenant:

* Either [M365 Monitoring Mode](/latest/m365-monitoring-mode) or [M365 Inline Mode](/latest/m365-inline-mode)

Optionally, before going inline, import your existing emails:

* [Import Past M365 Emails](/latest/m365-retrospective-email-scanning)


# Enable Shared Mailbox Script for M365
Source: https://docs.xorlab.com/latest/m365-shared-mailbox-script

Set the Entra ID attribute that tells xorlab which shared mailboxes each Self-Service Quarantine user may access.

When shared mailboxes are being used, xorlab needs to know, which mailboxes to include for
which [Self-Service Quarantine](/latest/ssq-overview) users. This can be accomplished by setting an attribute in Entra ID,
which is read by xorlab via the SAML integration.
For on-premises setups the process will differ.

## Pre-requisites

* **Global Administrator Role on Entra ID**

  Performing the following operations will require administrator privilege on your Microsoft Entra ID and Exchange Admin portal.

* **xorlab Entra ID Application**

  Ensure that an xorlab enterprise application and application registration has been created, which should have been done during the [Create Entra ID App](/latest/m365-entra-id-app).

* **Postman or access to Graph Explorer**

  To create the extension property, necessary to store the shared mailboxes, you will need the Postman software with an account (free) or an access to the Graph Explorer.

  <Warning>
    **Using API tools with admin credentials**

    It is strongly recommended that sensitive credentials are stored only locally and not uploaded to cloud accounts, such as Postman.
  </Warning>

## Configure your xorlab App Registration

Open the [Azure Portal](https://portal.azure.com/), search for the xorlab *App Registration* created during the [Create Entra ID App](/latest/m365-entra-id-app).

1. From the left hand sidebar navigate to **Manage → Certificates & secrets → Client Secrets** and create a temporary client secret. You will need it later for creating a custom extension property.

2. Create a PKCS#12 certificate (.pfx) by following the official Microsoft guide below. As a result, you should have two certificate files: `.cer` and `.pfx`. Make sure to take note of the certificate password.

   <Tip>
     **Certificate creation on Windows**

     Follow the steps from [Create a self-signed public certificate to authenticate your application](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate) including the optional "Export your public certificate with its private key" section.
   </Tip>

3. Upload the public certificate `.cer` into **Certificates** in *App Registration* section.

4. Once the certificate is uploaded, navigate to the **API permissions**, and add the following application permissions:

   ```txt API permissions theme={null}
   Microsoft APIs → Microsoft Graph:
       User.Read.All
       User.ReadWrite.All 
       Group.ReadWrite.All
       Application.Read.All
       Application.ReadWrite.All
       Application.ReadWrite.OwnedBy

   API my organization uses -> Office 365 Exchange Online:
       Exchange.ManageAsApp
   ```

5. Make sure that the permissions are granted admin consent (**Grant admin consent for ...**).

6. Assign the **Exchange Administrator** role to the xorlab App Registration:

   1. Navigate to **Microsoft Entra ID → Roles and administrators**.
   2. Search for the **Exchange Administrator** administrative role in the search bar and open it.
   3. Use the **Add assignments** button.

   <img alt="Exchange Administrator Role" />

## Create the custom extension property

To create this property, you will have to use the Graph API. We prepared a Postman collection containing the requests needed.

<Accordion title="Postman collection for the extension property">
  Copy the collection below, save it as `ExtensionProperty_cheatsheet.postman_collection.json`, and import it into Postman with **Import**.

  The IDs are collection variables, not values: set `tenantID`, `clientID`, `appID`, `objectID` and `userID` on the collection's **Variables** tab before you run a request.

  ```json ExtensionProperty_cheatsheet.postman_collection.json theme={null}
  {
  	"info": {
  		"_postman_id": "6f9a433f-92a5-49c7-8774-beb231bab7ca",
  		"name": "ExtensionProperty cheatsheet",
  		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
  		"_exporter_id": "4674986"
  	},
  	"item": [
  		{
  			"name": "Optional",
  			"item": [
  				{
  					"name": "Delete custom property",
  					"request": {
  						"auth": {
  							"type": "bearer",
  							"bearer": [
  								{
  									"key": "token",
  									"value": "{{GraphAPIToken}}",
  									"type": "string"
  								}
  							]
  						},
  						"method": "DELETE",
  						"header": [],
  						"body": {
  							"mode": "raw",
  							"raw": "",
  							"options": {
  								"raw": {
  									"language": "json"
  								}
  							}
  						},
  						"url": {
  							"raw": "https://graph.microsoft.com/v1.0/applications/{{appID}}/extensionProperties/{{objectID}}",
  							"protocol": "https",
  							"host": [
  								"graph",
  								"microsoft",
  								"com"
  							],
  							"path": [
  								"v1.0",
  								"applications",
  								"{{appID}}",
  								"extensionProperties",
  								"{{objectID}}"
  							]
  						}
  					},
  					"response": []
  				},
  				{
  					"name": "Set mailboxes for a user",
  					"request": {
  						"auth": {
  							"type": "bearer",
  							"bearer": [
  								{
  									"key": "token",
  									"value": "{{GraphAPIToken}}",
  									"type": "string"
  								}
  							]
  						},
  						"method": "PATCH",
  						"header": [],
  						"body": {
  							"mode": "raw",
  							"raw": "{\n  \"extension_4f24edfca6384790ae9e4eea5a0363d7_xorlab\": [\"test@yourdomain.ch\", \"test2@yourdomain.ch\"]\n}\n",
  							"options": {
  								"raw": {
  									"language": "json"
  								}
  							}
  						},
  						"url": {
  							"raw": "https://graph.microsoft.com/v1.0/users/{{userID}}",
  							"protocol": "https",
  							"host": [
  								"graph",
  								"microsoft",
  								"com"
  							],
  							"path": [
  								"v1.0",
  								"users",
  								"{{userID}}"
  							]
  						}
  					},
  					"response": []
  				}
  			]
  		},
  		{
  			"name": "Get a token",
  			"request": {
  				"method": "POST",
  				"header": [],
  				"body": {
  					"mode": "formdata",
  					"formdata": [
  						{
  							"key": "client_id",
  							"value": "{{clientID}}",
  							"type": "text"
  						},
  						{
  							"key": "client_secret",
  							"value": "{{clientSecret}}",
  							"type": "text"
  						},
  						{
  							"key": "redirect_uri",
  							"value": "localhost",
  							"type": "text"
  						},
  						{
  							"key": "grant_type",
  							"value": "client_credentials",
  							"type": "text"
  						},
  						{
  							"key": "scope",
  							"value": "https://graph.microsoft.com/.default",
  							"type": "text"
  						}
  					]
  				},
  				"url": {
  					"raw": "https://login.microsoftonline.com/{{tenantID}}/oauth2/v2.0/token",
  					"protocol": "https",
  					"host": [
  						"login",
  						"microsoftonline",
  						"com"
  					],
  					"path": [
  						"{{tenantID}}",
  						"oauth2",
  						"v2.0",
  						"token"
  					]
  				}
  			},
  			"response": []
  		},
  		{
  			"name": "Create custom property",
  			"request": {
  				"auth": {
  					"type": "bearer",
  					"bearer": [
  						{
  							"key": "token",
  							"value": "{{GraphAPIToken}}",
  							"type": "string"
  						}
  					]
  				},
  				"method": "POST",
  				"header": [],
  				"body": {
  					"mode": "raw",
  					"raw": " {\n     \"name\": \"xorlab\",\n     \"isMultiValued\": \"true\",\n     \"targetObjects\": [\n         \"User\"\n     ]\n }",
  					"options": {
  						"raw": {
  							"language": "json"
  						}
  					}
  				},
  				"url": {
  					"raw": "https://graph.microsoft.com/v1.0/applications/{{objectID}}/extensionProperties",
  					"protocol": "https",
  					"host": [
  						"graph",
  						"microsoft",
  						"com"
  					],
  					"path": [
  						"v1.0",
  						"applications",
  						"{{objectID}}",
  						"extensionProperties"
  					]
  				}
  			},
  			"response": []
  		}
  	],
  	"variable": [
  		{
  			"key": "tenantID",
  			"value": "tenantID"
  		},
  		{
  			"key": "clientID",
  			"value": "clientID"
  		},
  		{
  			"key": "appID",
  			"value": "appID"
  		},
  		{
  			"key": "objectID",
  			"value": "objectID"
  		},
  		{
  			"key": "userID",
  			"value": "userID"
  		},
  		{
  			"key": "GraphAPIToken",
  			"value": "GraphAPIToken"
  		}
  	]
  }
  ```
</Accordion>

<Tip>
  **In case you can't download Postman**

  In case you can’t have access to Postman, you can also use the Graph Explorer. Make sure to have the necessary Application rights and run a POST query on this endpoint: `https://graph.microsoft.com/v1.0/applications/**REPLACE WITH OBJECT ID**/extensionProperties`

  In the body section, you will have to insert this:

  ```json theme={null}
  {
      "name": "xorlab",
      "isMultiValued": "true",
      "targetObjects": [
          "User"
      ]
  }
  ```
</Tip>

1. Import the collection into your Postman software.

2. In the **Collection > Variables** section, ensure that you are not syncing or sharing any sensitive variables — especially `GraphAPIToken` and `clientSecret`. The recommended approach is to store the token and any secrets as a secret variable in your local Postman Vault and reference it directly using `{{vault:secret-name}}` in your requests. This ensures the token remains secure and is not accidentally uploaded or shared.

3. In **Get a token** request, replace the different variables and use the request to get a token from Graph API.

4. In **Create custom property**, replace **GraphAPIToken** variable with the token returned by the previous request.
   You should now be able to run the Create custom property request, as a response you will get the property name, it should be: `extension_**clientID**_xorlab`.

## Run and automate the script in Azure Automation

Azure provides the possibility to run PowerShell scripts directly in their system for a cheap price. We recommend using this option which save resources and implementation time.

You will first need to create an Automation Account, you can do so by searching for **Automation Account** in the Azure Portal.

<Note>
  During the creation, make sure the Managed Identities are *System Assigned* and that the networking is *Public Access*
</Note>

After the creation of the Automation Account, you have to activate *Try Runtime Environment Experience* by clicking the according button.

Then, navigate into **Runtime environment** and create a new **PowerShell 7.2** environment.

In this new runtime environment, add the following modules from the PowerShell Gallery:

```
    - ExchangeOnlineManagement
    - Microsoft.Graph.Authentication
    - Microsoft.Graph.Users
```

Go back to your Automation Account and navigate in **Certificates**, here you will have to upload the `.pfx` certificate file created previously. The name of the certificate must be ‘cert’.
You will be asked to enter the password of the certificate and select **Exportable** as **Yes**.

<Tip>
  **Wrong password**

  If Azure tells you that the password is incorrect, it can be due to a wrong certificate created. Double check that it is **PKCS#12** compliant.
</Tip>

Once this is done, you will need to navigate to **Variables** and create some of them, based on the data you saved before:

| Name | Type | Encrypted | Description |
| - | - | - | - |
| certificateThumb | string | No | The hexadecimal thumb of your certificate without '-' |
| clientID | string | No | The client ID of your xorlab App Registration |
| organization | string | No | The tenant domain of your organization (e.g contoso.corp) |
| tenantID | string | No | The Azure tenant ID |
| unifiedGroupsType | string | No | Define who will have access to the M365 unified groups, can be: ‘Members’ or ‘Owners’ |
| extensionProperty | string | No | The extension property name created previously |

Navigate to Runbooks and create a new runbook. Then, import the [shared mailboxes script](/latest/script-downloads#shared-mailboxes-script).

Make sure your runbook is using your custom Runtime Environment previously created.

Try to run your runbook, the final output should let you know some of the mailboxes updated. **There shouldn’t be any errors.**

If you’re happy with the result, publish the runbook and schedule it on a regular basis (e.g each night) via the **Schedules** functionality.

## Use the new extension property in xorlab

1. In the Azure portal, search for the xorlab Enterprise Application

2. Navigate to **Single Sign On**

3. Edit **Attributes & Claims**

4. Add a new claim named `xorlabAddresses` (Namespace can be left empty)

5. Select **Directory Schema Extension** and find your xorlab App Registration

6. Select it and find the `user.xorlab` attribute

7. Save the changes and open your xorlab instance

8. In the Expert Editor, open the `auth.yml` file and search for your SAML configuration

9. Set the `emails:` property to

   ```yaml theme={null}
   emails: sortPrefixedList(attr('xorlabAddresses'), ":")
   ```

10. Click **Publish**. The authentication configuration becomes active within about one minute.

## Maintenance Task – Updating an Expired Certificate

Depending on the parameters used in the [Configure your xorlab App Registration](#configure-your-xorlab-app-registration), the certificate (both .pfx and .cer files) may expire after some time. When this happens, you’ll need to renew the certificate and upload the updated files to both App Registration and Azure Automation.

### Steps to Renew the Certificate

#### App Registration

* Repeat steps 2 and 3 from the [Configure your xorlab App Registration](#configure-your-xorlab-app-registration) section.
* This will update the certificate at the App Registration level.

#### Azure Automation

* Go to your Automation Account>Shared Resources.
* Navigate to Certificates.
* Remove the existing certificate named `cert`.
* Upload the newly created `.pfx` certificate file.
  * Ensure the certificate name is exactly cert.
  * Enter the certificate password.
  * Set Exportable to Yes.

Once these steps are completed, your automation should resume functioning correctly.


# Set Up Email Routing in xorlab
Source: https://docs.xorlab.com/latest/m365-smtp

Configure email routing and TLS enforcement on xorlab in preparation for the Microsoft 365 integration.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration)
</Warning>

## Enforce TLS

In `activeguard/mta/startup_cfg/postfix_custom/main.cf`, set the following parameters to enforce TLS on all connections. In SaaS, they are normally already configured like this.

```ini main.cf theme={null}
smtpd_tls_cert_file = /etc/ssl/my_certs/my_cert.crt
smtpd_tls_key_file = /etc/ssl/my_certs/my_cert.key
smtp_tls_security_level = verify
smtpd_tls_security_level = encrypt
```

If you had to change anything, click **Publish**. The new Postfix settings become active within about one minute.

## Route all emails to M365

1. Open `main.cf` in `activeguard/mta/startup_cfg/postfix_custom/`.
2. Set `relayhost` to `<GUID>.mail.protection.outlook.com`. You find your `<GUID>` in the M365 Exchange Admin Center under **Mail flow** → **Accepted domains**.
   ```ini main.cf theme={null}
   relayhost = <GUID>.mail.protection.outlook.com
   ```

<Accordion title="Advanced routing">
  If for any reason you need to route your emails to different M365 regions, configure the following in addition:

  1. For every domain that should be routed separately, add a corresponding entry in the `transport` and `sender_dependent_transport` file.
     ```text transport theme={null}
     xorlab.com          smtp:xorlab-com.mail.protection.outlook.com
     xorlab.net          smtp:xorlab-net.mail.protection.outlook.com
     ```
     ```text sender_dependent_transport theme={null}
     @xorlab.com         xorlab-com.mail.protection.outlook.com
     @xorlab.net         xorlab-net.mail.protection.outlook.com
     ```
     By default, subdomains need to be added separately. Please see [Subdomain matching](/latest/smtp-configuration#subdomain-matching) to change the default.
  2. In `main.cf`, configure the following two lines:
     ```ini main.cf theme={null}
     # Activate recipient transport maps
     transport_maps = lmdb:/etc/postfix/transport
     # Activate sender transport maps
     sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport
     ```
</Accordion>

When you finish editing the Postfix files, click **Publish**. The routing configuration becomes active within about one minute.

## Next steps

* [Create Entra ID App](/latest/m365-entra-id-app)


# Add Your Trusted Infrastructure
Source: https://docs.xorlab.com/latest/on-prem-add-trusted-mtas

Register your own email infrastructure as trusted so xorlab can trace the true origin of an email.

More information and explanations about trusted infrastructure can be found under [Trusted MTAs](/latest/trusted-mtas).

## Add email servers

1. Open `shared/guarded_tenants.yml`.
2. Under `trustedMTAs`, add an entry for each email server that is part of your email infrastructure. You only need to add servers that do not use a private IP.
   ```yaml guarded_tenants.yml theme={null}
   tenants:
     - name: example
       # Add your servers either via IP OR via hostname. Servers with private IPs do not need to be added
       trustedMTAs:
         # Via IP in CIDR notation
         - hostCidrBlock: 1.2.3.4/32
         - hostCidrBlock: 5.6.7.0/24
         # Via hostname regex (matching the EHLO)
         - hostNamePattern: exchange\.example\.com
         - hostNamePattern: .*\.example\.com
   ```
3. This step is only required if outgoing email sent to xorlab are not DKIM signed. For all of your Exchange servers, add an `authenticDomains` parameter that contains all your guarded domains.
   <Warning>
     **Use `authenticDomains` only for servers that do not forward malicious emails. Do not use it for your gateway.**
   </Warning>
   ```yaml guarded_tenants.yml highlight={6-8} theme={null}
   tenants:
     - name: example
       trustedMTAs:
         - hostNamePattern: exchange\.example\.com
           # Add all your guarded domains as regex
           authenticDomains:
             - example\.com
             - example\.net
   ```
   <Accordion title="Information">
     `authenticDomains` will set all emails coming from that corresponding server as authentic. This is used to tell xorlab from which infrastructure you send outgoing emails. When you sign emails with DKIM, this is not required anymore.
   </Accordion>
4. Open the `activeguard/core/startup_cfg/spamass/local.cf` file and add the IP address of each of your email server that receives incoming emails before xorlab. This is only required for email servers that do not use a private IP address (RFC1918).
   ```shell local.cf theme={null}
   # Set which networks or MTAs are considered trusted
   trusted_networks 1.2/16 5/8                 # all in 1.2.*.* and 5.*.*.*
   trusted_networks 212.17.35.15               # specific address
   trusted_networks 1.                         # all in 1.*.*.*
   ```
5. Click **Publish**. The `guarded_tenants.yml` changes become active within about one minute. If you edited `local.cf` in step #4, [restart all MTAs](/latest/activate-configuration#configuration-files) as well, because files under `activeguard/core/startup_cfg/` require an MTA restart:
   ```shell theme={null}
   cd /etc/xorlab/activeguard
   docker compose down && docker compose up -d
   ```

## Verify

1. Check that outgoing emails are marked as outgoing. For this, search for `from:*@guarded.com` and see if the direction is correct. Replace `guarded.com` with your primary guarded domain.
2. Open an incoming email in the detail view and check that the `IP` and `EHLO` are correct. They should contain the external sender, not your infrastructure.

## Next steps

Optionally continue with:

* [Enable SAML or LDAP Login](/latest/on-prem-saml-ldap-authentication)
* [Integrate Reported Emails](/latest/on-prem-reporting-integration)

Once the integration is complete, continue with [What to Configure Next](/latest/integration-next-steps).


# Enable ESA Monitoring with BCC
Source: https://docs.xorlab.com/latest/on-prem-esa-monitoring-mode

Configure Cisco ESA message filters to BCC a copy of every email to xorlab for out-of-band monitoring.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/on-prem-smtp)
</Warning>

## Message Filter

The first step is to create a message filter that sends a BCC copy of all incoming and outgoing emails to xorlab. The following snippet shows such a message filter, assuming the ESA has different receive listeners for incoming and outgoing emails:

```text theme={null}
ActiveGuardBCCEmails:
if recv-listener == "<incoming Listener>" {
    insert-header("X-Original-Envelope-From","$EnvelopeFrom");
    bcc-scan("<xorlab Security Platform Email>");
} else {
    if recv-listener == "<outgoing Listener>" {
        bcc-scan("<xorlab Security Platform Email>");
    }
}
```

“xorlab Security Platform Email” corresponds to any email address with a domain that resolves to the xorlab MTAs. You can set it to `monitor@mx.xyz.activeguard.cloud`, for example. See the [DNS registration](/latest/vm-setup-guide#register-required-dns-records) section for details on how to set and configure your DNS records.

Note that this rule adds the original envelope `FROM` to the BCC email, which is required by xorlab.

If the BCC emails should be sent through a specific network interface, add an additional content filter like this (where `<NIC>` corresponds to the desired network interface):

<img alt="ESA Content Filter" />

*Content Filter to specify a network interface for the BCC emails*

## Bounce Profile

Now, we need to create a bounce profile so that no bounce or warning messages are sent to the sender if a BCC email could not be delivered to xorlab:

<img alt="Bounce Profile" />

*Bounce profile to disable bounce and warning messages*

This bounce profile should be applied whenever an email is sent to xorlab. To this end, add a Destination Control for the domain used above in the xorlab Security Platform email address:

<img alt="Destination Controls" />

*Apply the new Bounce Profile only to emails sent to xorlab Security Platform*

## Next steps

* [Add Your Trusted Infrastructure](/latest/on-prem-add-trusted-mtas)


# Enable Exchange Inline
Source: https://docs.xorlab.com/latest/on-prem-exchange-inline

Place xorlab in the Exchange delivery path using receive and send connectors, so it can block and quarantine.

This applies to on-premises Microsoft Exchange 2016 or 2019.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/on-prem-smtp)
</Warning>

* For incoming emails, you must extend the receive connectors to accept emails from xorlab Security Platform.
* For outgoing emails, you must add a new send connector pointing to xorlab Security Platform.

## Setting up the receive connector

To extend the default receive connector to accept emails from xorlab:

1. Open Exchange Admin Center.

2. Under **Mail Flow** → **receive connectors**, select your Exchange server and edit the connector starting with **Default Frontend…**.

3. In the dialog, go to **Scoping** and, for each xorlab MTA in your setup, add its IP address as a new entry to **Remote network settings**.

   <img alt="Scope of IP addresses" />

4. Click **Save**.

## Adding a new send connector

To route all outgoing emails through xorlab Security Platform:

1. Go to Exchange Admin Center.

2. Under **Mail Flow** → **send connectors**, add a new connector.

3. Enter a name and choose **Custom**.

   <img alt="Custom send connector" />

4. Click **Next**.

5. Choose the **Route email through smart hosts** option and add the domain names of all xorlab MTAs in your setup (the domain names—with DNS A records—corresponding to the IPs that you configured in **Setting up the receive connector**) as smart hosts.

6. Tick the checkbox to use external DNS lookup settings.

   <img alt="Smart hosts for send connector" />

7. Click **Next**.

8. Leave the smart host authentication to **None**. TLS between xorlab and the Exchange server is enforced by xorlab (for incoming and outgoing emails).

9. Click **Next**.

10. Under **Address space**, add a new space and enter `*` as a domain. Click **Next**.

    <img alt="Address space for email routing" />

11. Add your Exchange server as a source. Click **Finish**.

## Next steps

* [Add Your Trusted Infrastructure](/latest/on-prem-add-trusted-mtas)


# Enable Exchange Monitoring with BCC
Source: https://docs.xorlab.com/latest/on-prem-exchange-monitoring-mode

Configure Exchange to blind-copy traffic to xorlab, letting it analyze without sitting in the delivery path.

This applies to on-premises Microsoft Exchange 2016 or 2019. xorlab will receive a copy of every incoming and outgoing email.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/on-prem-smtp)
</Warning>

## Creating the mail flow rules

### Incoming emails

First, we need to create a mail-flow rule that sends a copy of all incoming emails to xorlab Security Platform.

1. In the Exchange Control Panel, under **Mail Flow → Rules**, create a new rule.

2. After you enter the name for the rule, click the drop-down list under **Apply this rule if…** to expand it and choose **The sender is located…** and then **is external/internal**:

   <img alt="Selecting the sender for the rule" />

3. In the **select sender location** input box that appears (if it doesn’t, click **Select one…** next to the list), select **Outside the organization** and click **OK**:

   <img alt="Sender from outside of the organization" />

4. Click the drop-down list under **Do the following…** to expand it and choose **BCC the message to…**

5. A new browser tab/window opens where you can enter the xorlab Security Platform monitoring mailbox address, e.g., `monitor@mx.xyz.activeguard.cloud`. Your new rule should look like the one depicted below:

   <img alt="Exchange rule for incoming emails" />

6. Click **Save**.

### Outgoing emails

Now we need to create another mail-flow rule that sends a copy of all outgoing emails to xorlab Security Platform.

Repeat the same steps as for incoming mails but, in step #2, select **The recipient is located…** in the first list. Now the rule should look like this:

<img alt="Exchange rule for outgoing emails" />

After creating those two rules, a copy of all incoming and outgoing emails will be sent to xorlab.

## Internal emails

In order to also send a copy of internal emails to xorlab Security Platform, the two mail-flow rules from above can be replaced with one single mail-flow rule that is applied to **all messages** (select this item from the list in step #2) as shown below. This step can be ignored if internal emails should not be forwarded to xorlab:

<img alt="Exchange rule for internal emails" />

## Considerations

As mentioned above, in monitoring mode, xorlab Security Platform will not change the mail traffic in any way. However, if all xorlab MTAs are down or do not accept emails, it can lead to a growing email queue on the Exchange Server. If this happens, you should temporarily disable the BCC mail flow rules.

## Next steps

* [Add Your Trusted Infrastructure](/latest/on-prem-add-trusted-mtas)


# On-prem Overview
Source: https://docs.xorlab.com/latest/on-prem-integration-overview

The complete ordered step list for integrating xorlab with on-premises email infrastructure.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration)
</Warning>

Your MX records only change if xorlab replaces your existing gateway. See [Review What Changes in Your Environment](/latest/integration-impact#on-premises) for what each topology changes in your mail flow, what stays untouched and how to undo it.

| Step | Description |
| :- | :- |
| [Set Up Email Routing in xorlab](/latest/on-prem-smtp) | **Mandatory**. Configure xorlab to accept and forward emails properly in your environment. |
| Forward emails in **Monitoring** or **Inline** mode | **Mandatory**. In Monitoring mode, you send just copies of emails to xorlab. In Inline mode, you route emails via xorlab for active protection. See [Before you begin](/latest/before-begin-integration#choose-between-inline-and-monitoring-mode) and below for more information. Here we provide instructions for common systems. <br /><br /> *Monitoring*: [Cisco ESA](/latest/on-prem-esa-monitoring-mode) or [Exchange](/latest/on-prem-exchange-monitoring-mode) <br /> *Inline*: [Exchange](/latest/on-prem-exchange-inline) <br /><br /> If your system is not listed—for example Cisco ESA in Inline mode, or any other MTA—contact [support@xorlab.com](mailto:support@xorlab.com) and we will guide you through the setup. |
| [Add Your Trusted Infrastructure](/latest/on-prem-add-trusted-mtas) | **Mandatory**. Configure your trusted email infrastructure in xorlab to allow proper detection. |
| [Enable SAML or LDAP Login](/latest/on-prem-saml-ldap-authentication) | **Optional**. Allow SAML-based or LDAP-based user login to xorlab. |
| [Integrate Reported Emails](/latest/on-prem-reporting-integration) | **Optional**. Integrate the Abuse Mailbox such that reported emails are handled by xorlab. |

## Inline mode diagrams

In Inline mode, xorlab filters all emails and sends the benign ones to the next hop. Depending on if xorlab is the gateway or an add-on, the integration looks different.

<CardGroup>
  <Card title="Gateway simple">
    <img alt="Simple on-premises gateway integration" />

    [Gateway setup guide](/latest/on-prem-smtp#configure-as-inline-gateway)
  </Card>

  <Card title="Gateway advanced">
    <img alt="Advanced on-premises gateway integration" />

    [Gateway setup guide](/latest/on-prem-smtp#configure-as-inline-gateway)
  </Card>

  <Card title="Add-on">
    <img alt="On-premises Exchange add-on integration" />

    [Add-on setup guide](/latest/on-prem-smtp#configure-as-inline-add-on)
  </Card>
</CardGroup>

## Monitoring mode diagrams

In Monitoring mode, xorlab receives only a copy of every email and discards it after processing. The copy can be setup either on the gateway or on the Exchange server.

<Note>
  **Evaluation**

  If you plan to evaluate xorlab as an add-on to an existing solution, setup the BCC on the Exchange server. In this way you can quickly evaluate the additional security that xorlab provides on top.
</Note>

<CardGroup>
  <Card title="BCC from gateway">
    <img alt="BCC monitoring from a gateway" />

    [Monitoring setup guide](/latest/on-prem-smtp#configure-for-monitoring)
  </Card>

  <Card title="BCC from Exchange">
    <img alt="BCC monitoring from Exchange" />

    [Monitoring setup guide](/latest/on-prem-smtp#configure-for-monitoring)
  </Card>
</CardGroup>

The diagrams show Exchange and a generic gateway, but the interface is plain SMTP: any other MTA or secure email gateway can take the place of the gateway shown. See [Advanced SMTP Configurations](/latest/smtp-configuration) for multiple next hops, per-domain routing, and TLS enforcement.

## Multi-Tenancy

If you protect more than one organization with the same xorlab instance, follow [Add a Tenant](/latest/multi-tenancy-new-tenant) instead of the table above. It uses the same guides, but adds the per-tenant configuration around them:

* Configure the domains and routing of the tenant with the topology that matches your setup, see [Configure Tenant Domains and Routing](/latest/multi-tenancy-domain-and-routing).
* Set up SAML or LDAP per tenant, see [Enable Tenant Login](/latest/multi-tenancy-authentication).
* Configure the trusted infrastructure per tenant or in a shared config template, see [Trusted MTAs In-Depth](/latest/trusted-mtas).
* Assign reported emails to the right tenant, see [Assign Reported Emails to Tenants](/latest/multi-tenancy-reported-emails).


# Integrate On-prem Abuse Mailbox
Source: https://docs.xorlab.com/latest/on-prem-reporting-integration

Route user-reported suspicious mail from a self-hosted mail system into the Abuse Mailbox, with automated replies.

You will be able to view all reported emails in xorlab and send feedback to the reporters.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration) and [Set Up Email Routing in xorlab](/latest/on-prem-smtp)
</Warning>

If you have a hybrid M365 setup and all your mailboxes are hosted in M365, follow [Integrate M365 Reported Emails](/latest/m365-reporting-integration) instead.

## Prepare xorlab

1. Open `shared/guarded_tenants.yml` and add all email address patterns that are allowed to report emails.

   ```yaml guarded_tenants.yml {4-6} theme={null}
   tenants:
     - name: example
       emailReporting:
         authorizedEmailReportRecipients:
           - .*@xorlab\.com
           - .*@xorlab\.net
   ```

2. Choose if you want to enable or disable automatic feedback. If enabled, every reporter will get an immediate feedback email.

   <CardGroup>
     <Card title="Automatic feedback" icon="shield">
       ```yaml guarded_tenants.yml {4,5} theme={null}
       tenants:
         - name: example
           ruleProfiles:
             # REMOVE this line
             - no_auto_feedback.properties
       ```
     </Card>

     <Card title="Disabled feedback" icon="xmark">
       ```yaml guarded_tenants.yml {4,5} theme={null}
       tenants:
         - name: example
           ruleProfiles:
             # ADD this line
             - no_auto_feedback.properties
       ```
     </Card>
   </CardGroup>

3. Optional: Change the sender address used for feedback emails: [Change Sender Address](/latest/email-template-sender-addresses#feedback-emails).

4. Click **Publish**. The new configuration becomes active within about one minute.

## Forward reported emails to xorlab

Reported emails need to be forwarded as **EML** attachment to a dedicated email address on xorlab: `suspicious@<templateDomain>`. The `templateDomain` property can be found in `activeguard/core/active_guard.yml`.

The actual implementation of the forwarding depends on your setup. Choose the one that fits your environment.

<Tabs>
  <Tab title="Manual reporting mailbox">
    You have a dedicated mailbox where users in your organization can report emails to. They need to manually forward the reported email as attachment to that mailbox.

    <Note>
      **Forwarding:** In your Exchange, create a mail flow rule that forwards all email from that mailbox to xorlab at `suspicious@<templateDomain>`. If you need the emails still in that mailbox, you can send xorlab just a BCC copy of the emails instead.
    </Note>
  </Tab>

  <Tab title="Third party button">
    You have a third party button in place that your users use for reporting emails.

    <Note>
      **Forwarding:** Most buttons allow you to add an additional recipient to the reported emails. Add `suspicious@<templateDomain>`. If that is not possible, create a mail flow rule on Exchange as described under "Manual reporting mailbox".
    </Note>
  </Tab>

  <Tab title="No reporting mailbox">
    There is no reporting button and no dedicated reporting mailbox available.

    <Note>
      **Forwarding:** We recommend that you acquire a third party reporting button that allows your users to report emails. xorlab partners with multiple reporting button providers. Contact [support@xorlab.com](mailto:support@xorlab.com) for more information.
    </Note>
  </Tab>
</Tabs>

## How to change the reporting address

The default address under which xorlab will listen for reported emails is `suspicious@<templateDomain>`, with `templateDomain` referring to the parameter that's set in `active_guard.yml`.

If you like to customize the sender address, add the following block (if it does not already exist) to the `active_guard.yml` file:

```yaml active_guard.yml {7} theme={null}
scanSources:
  smtp:
    port: 10025
    handler:
      smtpReport:
        # Default. <templateDomain> corresponds to the parameter templateDomain in active_guard.yml
        emailAddress: suspicious@<templateDomain>
```

Afterward, click **Publish**. The `scanSources` handler settings become active within about one minute.

## How to automate reported email handling

For further information about automation, have a look at [Abuse Mailbox](/latest/abuse-mailbox#auto-resolve-cases).

## Multi-Tenancy

Repeat this integration for each tenant. In addition, xorlab needs to know which tenant a reported email belongs to, which is decided by a header on the carrier email and not by the reporting address:

<Card title="Assign Reported Emails to Tenants" icon="building" href="/latest/multi-tenancy-reported-emails">
  Add the `x-ag-tenant` header so that reported emails end up in the right tenant.
</Card>

## Next steps

The on-premises integration is complete:

* [What to Configure Next](/latest/integration-next-steps)


# Enable On-prem SAML/LDAP Login
Source: https://docs.xorlab.com/latest/on-prem-saml-ldap-authentication

Enable SAML or LDAP login for on-premises deployments. SAML is recommended for a smoother single sign-on experience.

For an overview over all supported authentication methods, have a look at [Authentication Overview](/latest/authentication-overview).

## Enable SAML login

If you have Entra ID from Microsoft, follow that guide. Otherwise have a look at the generic SAML integration.

<CardGroup>
  <Card title="Microsoft Entra ID" icon="microsoft" href="/latest/m365-saml-entra-authentication">
    Follow this guide to authenticate your users via Entra ID.

    Replace any occurrences of `xyz.activeguard.cloud` with the domain of your XCC.
  </Card>

  <Card title="Generic SAML Integration" icon="user-tag" href="/latest/authentication-saml">
    This guide provides general instructions on how to enable SAML-based user login for xorlab.
  </Card>
</CardGroup>

## Enable LDAP login

See [Enable LDAP Login](/latest/authentication-ldap) for generic instructions on how to enable LDAP-based user login for xorlab.

## Next steps

* [Integrate Reported Emails](/latest/on-prem-reporting-integration)


# Set Up Email Routing in xorlab
Source: https://docs.xorlab.com/latest/on-prem-smtp

Set up email routing on xorlab for on-premises integration, with a guide for each target architecture.

<Warning>
  **Prerequisites**

  * Complete [Before You Begin](/latest/before-begin-integration)
</Warning>

Follow one guide of the following that fits your target architecture:

<CardGroup>
  <Card title="Inline (Add-on)" icon="shield" href="#configure-as-inline-add-on">
    Default. xorlab is located between your gateway and exchange server.
  </Card>

  <Card title="Inline (Gateway)" icon="key" href="#configure-as-inline-gateway">
    xorlab is the gateway and receives/sends emails from/to the internet.
  </Card>

  <Card title="Monitoring" icon="envelope-open-text" href="#configure-for-monitoring">
    xorlab receives only a copy of every email, and discards it after processing.
  </Card>
</CardGroup>

## Configure as Inline add-on

As Inline add-on, xorlab will:

* Deliver incoming emails to `<inbound-next-hop>` (usually an Exchange server)
* Deliver outgoing emails to `<outbound-next-hop>` (the Gateway)

Follow these steps:

1. Go to `activeguard/mta/startup_cfg/postfix_custom/` in the Expert Editor.

2. Open `main.cf` and enable `transport_maps`:

   ```ini main.cf theme={null}
   transport_maps = lmdb:/etc/postfix/transport
   ```

3. Open `transport`. Create it if it does not exist. Add a line for every guarded domain with `<inbound-next-hop>` and one line for all outgoing emails with `<outbound-next-hop`:

   ```ini transport theme={null}
   # Inbound emails
   xorlab.com  smtp:<inbound-next-hop>
   xorlab.net  smtp:<inbound-next-hop>
   # Outbound emails
   *           smtp:<outbound-next-hop>
   ```

   <Accordion title="Subdomains">
     By default, subdomains need to be added separately. Please see [Subdomain matching](/latest/smtp-configuration#subdomain-matching) to change the default.
   </Accordion>

   <Accordion title="Fallback">
     You can specify fallbacks if the first destination is not reachable: `smtp:[1.2.3.4],[2.2.2.2]`.
   </Accordion>

4. Open `client_access` and add the IP of every email server that will send emails to xorlab:

   ```ini client_access theme={null}
   # Permit this IP to send emails to xorlab
   <ip-address1>   permit
   <ip-address2>   permit

   # You can also permit domains. The domain name is determined by means of a reverse DNS lookup and automatically extends to subdomains. 
   example.com   permit
   ```

5. Click **Publish**. The inline add-on configuration becomes active within about one minute.

## Configure as Inline gateway

As Inline gateway, xorlab will:

* Deliver incoming emails to `<inbound-next-hop>` (usually an Exchange server)
* Deliver outgoing emails directly to the external recipient

Follow these steps:

1. Go to `activeguard/mta/startup_cfg/postfix_custom/` in the Expert Editor.

2. Open `main.cf` and enable `transport_maps`:

   ```ini main.cf theme={null}
   transport_maps = lmdb:/etc/postfix/transport
   ```

3. In `main.cf`, add all guarded domains as `relay_domains`:

   ```ini main.cf theme={null}
   # Only add domains to the relay_domains, this will automatically include subdomains as well
   # xorlab will accept emails to these domains from every IP
   relay_domains = xorlab.com, xorlab.net
   ```

4. Open `transport`. Create it if it does not exist. Add a line for every guarded domain with `<inbound-next-hop>`:

   ```ini transport theme={null}
   # Inbound emails
   xorlab.com  smtp:<inbound-next-hop>
   xorlab.net  smtp:<inbound-next-hop>
   ```

   <Accordion title="Subdomains">
     By default, subdomains need to be added separately. Please see [Subdomain matching](/latest/smtp-configuration#subdomain-matching) to change the default.
   </Accordion>

   <Accordion title="Fallback">
     You can specify fallbacks if the first destination is not reachable: `smtp:[1.2.3.4],[2.2.2.2]`.
   </Accordion>

5. Open `client_access` and add the IP of every email server that will send emails to xorlab:

   ```ini client_access theme={null}
   # Permit this IP to send emails to xorlab
   <ip-address1>   permit
   <ip-address2>   permit

   # You can also permit domains. The domain name is determined by means of a reverse DNS lookup and automatically extends to subdomains. 
   example.com   permit
   ```

6. Click **Publish**. The inline gateway configuration becomes active within about one minute.

## Configure for Monitoring

In Monitoring Mode, xorlab discards all received emails. Here we configure the routing for emails that are generated by xorlab itself (for example feedback notifications).

1. Go to `activeguard/mta/startup_cfg/postfix_custom/` in the Expert Editor.

2. Specify the relay destination in the `main.cf` file:

   ```ini main.cf theme={null}
   ## Route all emails to this host
   relayhost = relay.host.com
   ```

3. Open `client_access` and add the IP of every email server that will send emails to xorlab:

   ```ini client_access theme={null}
   # Permit this IP to send emails to xorlab
   <ip-address1>   permit
   <ip-address2>   permit

   # You can also permit domains. The domain name is determined by means of a reverse DNS lookup and automatically extends to subdomains. 
   example.com   permit
   ```

4. Click **Publish**. The monitoring configuration becomes active within about one minute.

## Next steps

Forward emails to xorlab in the mode you chose:

* *Monitoring*: [Cisco ESA](/latest/on-prem-esa-monitoring-mode) or [Exchange](/latest/on-prem-exchange-monitoring-mode)
* *Inline*: [Exchange](/latest/on-prem-exchange-inline)


# Phishing Simulation
Source: https://docs.xorlab.com/latest/phishing-simulation-tools

Allow simulated phishing emails from awareness training services to reach inboxes unfiltered.

There’s a myriad of services allowing you to launch simulated cyber attacks against your organization and measure its awareness of email-borne threats. To make sure that simulated emails reach the inbox of your staff, consult the documentation of a respective service and include its infrastructure, sender address, or sender domain in the Simulation lists.

xorlab Security Platform will mark simulated attacks with `verdict:simulation` if the distinctive mark of a service is known. Log in to xorlab, navigate to **Settings → Lists → Simulation**, and add the distinctive mark of your simulation service to the appropriate list.

<Warning>
  Emails matching a Simulation list entry are treated as benign, bypassing all other threat analysis. Sender address, sender domain, MTA EHLO, and x-mailer header are all values an attacker can forge, so configuring simulation matching on these increases your attack surface to impersonation. **We recommend using MTA IP (regex) wherever your simulation service supports it**, since the connecting IP is much harder for an attacker to spoof than a header value.
</Warning>

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Sender address** | Use this list if your simulation service uses designated sender addresses.<br />No authentication is required | Email address as `String`, e.g., `awareness@myfakedomain.com`<br />Matches Header FROM and Envelope FROM |
| **Sender domain** | Use this list if your simulation service uses a designated sender domain.<br />No authentication is required | Sender domain as `String`, e.g., `myfakedomain.com`<br />Matches Header FROM and Envelope FROM |
| **MTA EHLO (regex)** | Use this list if your simulation service sends simulated attacks from designated host names | Host names as `Regex`, e.g., `*.\.awarenesstool\.com`<br />Please be aware that the email needs to contain EHLO or EHLO IP for this verification to work |
| **MTA IP (regex)** | Use this list if your simulation service sends simulated attacks from designated IPs | IP records as `Regex`, e.g., `192\.168\.1\..`<br />Please be aware that the email needs to contain EHLO or EHLO IP for this verification to work |
| **x-mailer header (regex)** | Use this list if your simulation service adds a designated x-mailer header to simulated attack emails.<br />Note that all emails matching any entries in this list will be marked as simulation | Header content as `Regex`, e.g., `Tool v5\..` |


# Quick Walkthrough
Source: https://docs.xorlab.com/latest/quick-walkthrough

A hands-on tour of the most important xorlab features. Read the core concepts first.

If you prefer to watch a video instead, have a look at [Video Tutorials ](/latest/video-tutorials).

We recommend to have read the [Core Concepts](/latest/concepts-overview) before starting with the walkthrough here.

In 15 minutes, you will cover the basics of using xorlab:

* How to search for emails
* Create your first campaign
* Using the similarity search
* Give feedback to a reported email

## Search an email

The search is very powerful and one of the key tools in xorlab. The full search syntax can be found under [Search](/latest/search).

1. Open the **Messages** menu on the left.

2. Search for all sender addresses that contain the word `notification`: Open the **Sender** filter, switch the dropdown to **contains** and add `notification`. If you don't get any results, you can choose any other word.

   <img alt="Sender search" />

3. Refine the search further by adding some [Tags](/latest/tags) to only match incoming emails from untrusted senders: `#untrusted #inc`. You can add as many tags as you want. By default, they are ANDed.

   <img alt="Sender search tags" />

4. All filters can be replaced by text search. The following gives the same results as above:

   <img alt="Sender search tags text" />

5. You can further play around using for example:

   * `(topic:invoice OR topic:accountissue) #newsender`: Unknown senders that send emails about invoices or account issues
   * `#untrusted #vbascript`: Emails from untrusted senders with VBA script
   * `#partner #encryptedarchive`: Emails from partners that contain an encrypted archive

6. Save your search for later use with the button on the right side. You can find all your saved searches in the **Saved Searches** menu.

   <img alt="Saved searches" />

## Create a campaign

Campaigns allow you to define an action for all emails that match a search query. It is an easy tool to react to missed threats or false positives.

Campaigns work only forward-looking, and do not affect past emails. For an in-depth guide about Campaigns, check out [Using Campaigns](/latest/campaigns).

1. Create a new search query that will be the basis of the campaign: `#youngsender #newsender topic:packagedelivery`. This will find all emails from recently registered domains that talk about package delivery.

2. Click on the campaign button on the right side in the search.

   <img alt="Create campaign" />

3. Enter a descriptive campaign name.

4. Under **Message Action**, you can choose the action that should be applied to all emails that will match this search from now on. Choose **None** for now, in this way the campaign will be passive and not have any impact. The **Resolve Action** can also be left as **None** as it affects only [Reported Emails](/latest/abuse-mailbox).

   <img alt="Create campaign dialog" />

   <Note>
     **Deliver**

     Be careful when using the Deliver action. It will overwrite all built-in detection mechanisms. It is normally only used in a very narrow scope to address false positives.
   </Note>

5. After saving, you can find your new campaign in the **Campaign** menu on the left. The switch in the upper right provides different views for convenience.

   <img alt="Campaign overview" />

6. If you want to activate the campaign, you can set the **Message Action** any time later to **Quarantine**.

## Using the similarity search

The similarity search allows to group emails based on different parameters. For example, a phishing wave might use different sender addresses and subjects, but you can still group them based on content similarity.

1. In the **Messages** menu, click on any email in the list to open the [Detail View](/latest/understand-verdict).

2. Open the **SIMILAR** tab. This will show you all emails with a similar content. The first email highlighted in blue is the one that you opened in the detail view.

   <img alt="Similar view" />

   <Note>
     **Content similarity**

     The content similarity uses fuzzy hashing of the email body to group emails. It is robust such that one can change several words of an email and even re-arrange paragraphs and it will still group them together. The false positive rate is generally very low for emails with enough text (above 30-40 words).
   </Note>

3. If your email does not have any results based on content similarity, you can use one of the other built-in groupings like **Same Sender**. The number in brackets shows the amount of matches.

   * When choosing another grouping, you need to disable the **Content similar** search, otherwise they will be ANDed.

   <img alt="Similar view 2" />

4. When you found a grouping that works for you, you can create again a saved search or even a campaign with the two icons on the right side in the search bar.

5. The search bar here supports the same searches as the default one in the **Messages** menu. For example, you can refine the built-in groupings with normal search queries. In this example we grouped the emails based on display name and restricted it via search `verdict:phishing` to only phishing emails.

   <img alt="Similar view 3" />

## Give feedback to a reported email

<Warning>
  **Prerequisites**

  * This chapter is only applicable if you use the [Abuse Mailbox](/latest/abuse-mailbox) feature of xorlab.
  * You need at least one already reported email in xorlab.
</Warning>

Here we show how you find the user reported emails and give feedback to the reporter.

1. Open the **Abuse Mailbox** menu on the left and choose **All Cases**. This will show all reported emails xorlab received.

   <img alt="Abuse Mailbox" />

2. The search bar on top works in the same way as the ones we've seen in the previous chapters. Optional: You can additionally use the `reporter:` keyword to search for specific internal reporters.

3. Click on an email where the **STATUS** on the right side is `OPEN`.

4. You will see the same detail view as before, but additionally you have **Resolve** buttons in the upper right. Click on **Resolve as Spam**.

   <img alt="Abuse Mailbox detail view" />

5. Under **Feedback Template** you can select what feedback the reporter should get. Keep it as *Spam*. Add a custom **Comment**, and click on **Resolve**.

   <img alt="Abuse Mailbox dialog" />

   <Note>
     **Attaching the reported email**

     When you select a benign verdict (shown as green in the search), xorlab will attach the reported email as EML to the feedack email. For malicious emails, this is not the case.
   </Note>

6. A few seconds later, the reporter will now get a feedback email like this. The comment is added in the lower half of the email:

   <img alt="Abuse Mailbox feedback" />


# Reporting a Misclassification
Source: https://docs.xorlab.com/latest/reporting-misclassification

Report a false positive or false negative to xorlab so that the detection can be corrected.

Suppose a message was mistakenly quarantined but is benign (false positive) or was delivered although it shouldn’t have been (false negative).

You can report a misclassification in various locations:

We show here how to report the misclassification of an arbitrary email:

1. Open the email in the detail view

2. Click the three dots in the upper right and choose **Report Misclassification**:

   <img alt="Report misclassification from menu" />

3. In the new dialog, choose the **Expected verdict** and select the severity of the issue with the slider (see the [guide below](#severity-levels) to pick the right level)

   <img alt="Report misclassification" />

4. Optional: Add a comment clarifying the reason for this misclassification report.

<Note>
  **Report locations**

  Besides the above shown way, you can also report a misclassification whenever you:

  * Release an email from the quarantine
  * Isolate an email
  * Resolve a reported email

  The corresponding dialogs offer a **Report misclassification** checkbox.
</Note>

## Severity levels

Please follow these guides to find the severity level that fits your case best:

### Reporting a misclassified malicious email

| Level | Description |
| :- | :- |
| **Low** | Unwanted mail with no security impact (e.g., newsletters & marketing, graymail). |
| **Moderate** | Pure spam with no/little security impact (e.g., shady promotions, obvious spam, high-volume spam). |
| **Major** | Harmful spam or threat with potential security impact (e.g., adult/drug spam, phishing, extortion, fraud, impersonation). |
| **Critical** | High-severity threat with clear harm potential that requires immediate attention (e.g., malware or a high-quantity phishing wave). Please include a comment with critical issues to help us assess them quickly. |

### Reporting a misclassified benign email

| Level | Description |
| :- | :- |
| **Low** | Wanted informational mail (e.g., newsletters & marketing). |
| **Moderate** | Wanted non-business-relevant or personal email (e.g., notifications from services, emails for private purposes). |
| **Major** | Business-relevant or critical emails (e.g., business communication, password-reset emails, invoices, travel tickets). |
| **Critical** | Business-critical email that required immediate attention (e.g., a quarantined email that required an immediate response, causing potential for business damage). Please include a comment with critical issues to help us assess them quickly. |

## Report a misclassified topic

To report a misclassified topic, please see [Report misclassified topics](/latest/topic-detection#report-misclassified-topics).

## Configuration

The Admin guide to configure the behavior of the reporting can be found here: [Configure Misclassification Reporting](/latest/configure-misclassification-reporting).


# Restrict Access to Expert Editor
Source: https://docs.xorlab.com/latest/restrict-admin-access

Restrict which IP addresses can reach the Expert Editor, on top of role-based access control.

1. In the Expert Editor, create the file `xcc/web/access.d/web_admin.conf`
2. Add the following content and adjust the `deny` and `allow` commands accordingly:

```
# Define Nginx access restrictions here.
# For details, see: https://nginx.org/en/docs/http/ngx_http_access_module.html

# Allow only specific IPs to access the Expert Editor
allow 1.2.3.0/24;
allow 2.3.4.5;
deny all;
```

3. Click **Publish**, then restart the `xcc_web` container. Files under `xcc/web/` require an XCC restart; see [How to Activate the Configuration](/latest/activate-configuration).


# Search
Source: https://docs.xorlab.com/latest/search

Locate messages with autocomplete-assisted queries, then reuse a query as a saved view or promote it to a campaign.

Search in xorlab helps you find any message in seconds using intuitive filters, tags, time ranges, and wildcards, and keeps track of your recent queries.

<Accordion title="▶ Watch the Video Tutorial: How to Use Search in xorlab">
  <div>
    <iframe title="xorlab Search tutorial" />
  </div>
</Accordion>

## Key features

* **Autocomplete Suggestions:** As you type, the search bar provides real-time suggestions, reducing the need to memorize search syntax.
* **Filter Options:** You can easily filter your results by sender, recipient, subject, or other key attributes by selecting options from a dropdown menu.
* **Time Range Selection:** The search bar includes a built-in time range selector to refine your searches by date without manually entering date strings.
* **Wildcard Characters:** Wildcards are automatically supported with `?` matching a single character and `*` matching zero or more characters.
* **Tag-based Search:** Easily search and aggregate emails using case-insensitive tags (e.g., #phishing, #highrisk) to filter or group emails. For the complete list, please see [*Tags*](/latest/tags).
* **Recent Searches:** Access the four last searches by clicking the search bar, allowing easy recall of previous queries for ongoing investigations or repetitive tasks.
* **Campaign Creation:** If a search query is [Campaign](/latest/campaigns) compatible, you can click the icon in the search bar to directly turn the query into an adaptive policy.
* **Save Searches:** There's also an icon in the search bar that enables you to save the search query for later use.

## All search attributes

Every attribute the search understands is listed below, with the section that documents
its accepted values. Anything not in this table is not a valid search attribute: a query
that uses one returns no results rather than an error, so it is worth checking the name
here before assuming a search found nothing.

| Attribute | What it matches | Details |
| :- | :- | :- |
| `sender:` `recipient:` | The header or the SMTP address, whichever matches | [Senders and recipients](#senders-and-recipients) |
| `from:` `to:` `cc:` | The corresponding header only | [Senders and recipients](#senders-and-recipients) |
| `envfrom:` `envrecipient:` | The SMTP envelope address only | [Senders and recipients](#senders-and-recipients) |
| `involves:` | Any of `from`, `to`, `cc`, `envfrom`, `envrecipient` | [Senders and recipients](#senders-and-recipients) |
| `reporter:` | Who reported an incident | [Senders and recipients](#senders-and-recipients) |
| `<Address>.displayname:` | The display name, where `<Address>` is `sender`, `recipient`, `from`, `to`, `cc`, or `involves` | [Senders and recipients](#senders-and-recipients) |
| `tenant:` `tenant.uid:` | The assigned tenant. No wildcards | [Multi-tenant](#multi-tenant) |
| `direction:` | Incoming, outgoing, internal, or external | [Direction](#direction) |
| `received:` | When the email was received, as a point or a range | [Date and time](#date-and-time) |
| `#<tag>` | A tag the platform assigned | [Tags](#tags) |
| `trust:` `reputation:` `risk:` `threat:` | A score, as a comparison, an interval, or a level | [Scores](#scores) |
| `spam:` `rsd:` | A score, as a comparison or an interval. These two have no level form | [Scores](#scores) |
| `verdict:` | A verdict class, an email verdict, or a file analysis verdict | [Verdicts](#verdicts), [Email attachments](#email-attachments) |
| `status:` | The state of an email, a reported email, or an uploaded file | [Processing status](#processing-status) |
| `topic:` | A detected topic anywhere in the email | [Topics](#topics) |
| `subject.topic:` `body.topic:` `file.topic:` | A detected topic in one part of the email | [Subject](#subject), [Body](#body), [Email attachments](#email-attachments) |
| `subject:` | The subject line | [Subject](#subject) |
| `link:` `link.displaytext:` `link.location:` | An extracted link, its display text, or where it was found | [Embedded links](#embedded-links) |
| `domain:` `domain.ip:` `domain.date:` | An extracted domain, its IP, or its registration date | [Embedded domains](#embedded-domains) |
| `domain.local:` `domain.global:` | The local or global reputation of a domain | [Embedded domains](#embedded-domains) |
| `file.name:` `file.hash:` `file.type:` | An attachment by name, SHA256 hash, or extracted type | [Email attachments](#email-attachments) |
| `header.name:` `header.value:` `header:{…}` | A message header, by name, by value, or by both at once | [Email headers](#email-headers) |
| `messages` `reported` `files` `quarantine:` | A predefined set of emails or files | [Predefined filters](#predefined-filters) |
| `rule:` `passiverule:` | A rule that ran during processing, or one that ran passively without affecting the outcome | [Queries using rules](#queries-using-rules) |

Verdict confidence has no attribute of its own and is matched through `rule:`, see
[Verdict confidences](#verdict-confidences).

## Search query basics

You can build powerful search queries using a combination of **filters**, **verdicts** and **tags**, and simple **logic** like `and`, `or`, and `not`.

### How the logic works

Search queries are made up of **statements** — simple conditions like filters (`status:open`) or tags (`#quarantine`) — connected using logical operators:

* `and`: both conditions must match
* `or`: at least one condition must match
* `not`: exclude anything that matches the expression

#### For example:

`#domainonlyinbound #inc #untrusted not(#crm or #marketing or #newsletter)`

The strongest operator is `not` followed by `and` and then by `or`. Multiple statements without any operator are always treated as `and`. Group statements with parentheses whenever you mix operators: `#inc and #phishing or #spam` also returns outgoing spam, while `#inc and (#phishing or #spam)` does not.

### Special characters

| Syntax | Meaning | Example |
| :- | :- | :- |
| `( )` | Groups statements | `#inc and (#phishing or #spam)` |
| `[a, b]` | Matches any of the listed values, like `or` | `status:[delivered,quarantined]` |
| `[a TO b]` | Matches an inclusive range, for [scores](#scores) and dates | `threat:[50 TO 100]` |
| `{ }` | Applies every condition inside to the same object, such as one header | `header:{name:"x-spam-result" AND value:"*MIME_HTML_ONLY*"}` |
| `*` `?` | Matches any number of characters, or exactly one | `subject:"*invoice*"` |
| `" "` | Treats the value as one string. Required when it contains a space or one of `:` `#` `(` `)` `[` `]`; escape a quote inside it with `\"` | `subject:"Password Reset"` |

## Email attributes

Every email has base attributes automatically set by xorlab, such as the sender, recipient, and timestamp. You can search using these attributes with the syntax `attribute:value`.

### Senders and recipients

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `sender:<Match>` | Returns emails where the header `from:` or the SMTP `from` address matches `<Match>` |
    | `recipient:<Match>` | Returns emails where the header `to:` or `cc:` or the SMTP `to` address match `<Match>` |
    | `from:<Match>` | Returns emails where the header `from:` (a.k.a. `mail-from` or `5322.From`) matches `<Match>` |
    | `to:<Match>` | Returns emails where the header `to:` matches `<Match>` |
    | `cc:<Match>` | Returns emails where the header `cc:` matches `<Match>` |
    | `involves:<Match>` | Returns emails where either `from`, `to`, `cc`, `envfrom`, or `envrecipient` match `<Match>` |
    | `reporter:<Match>` | Returns incidents reported by `<Match>` |
    | `envfrom:<Match>` | Returns emails where the SMTP `from` address (a.k.a. `envelope-from` or `5321.From`) matches `<Match>` |
    | `envrecipient:<Match>` | Returns emails where the SMTP `to` address (a.k.a. `envelope-to` or `5321.To`) matches `<Match>` |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | ` <Match>` | Accepts fully qualified email addresses and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `from:albert@timespace.com` | Returns all emails where the header `from:` field contains `albert@timespace.com` |
    | `to:*.net` | Returns all emails that contain a .net domain in the header `to:` field |
    | `from:[marie@radio.org,isaac@gravity.net]` | Returns all emails with `mail-from = from:marie@radio.org` OR `mail-from = from:isaac@gravity.net` |
    | `cc:[marie*,*isaac]` | Returns all emails whose header `cc:` field starts with the token `marie` or ends with the token `isaac` |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `<Address>.displayname:<Match>` | Returns all emails for the specified address type that have the given display name |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `<Address>` | Accepts `sender`, `recipient`, `from`, `to`, `cc`, `involves` |
    | `<Match>` | Accepts strings and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`.  If the display name to be matched contains spaces, then you must enclose it in double quotes. Use `\` to escape quotes |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `from.displayname:"Albert E."` | Returns all emails where a sender display name contains `Albert E.` |
    | `from.displayname:"R* Fey*"` | Returns all emails where the sender display name starts with the character `R` and ends with the string `Fey` separated by a space |
    | `to.displayname:[Albert, Richard]` | Returns all emails where the recipient display name is either `Albert` or `Richard` |
    | `cc:[marie*,*isaac]` | Returns all emails where a cc address starts with `marie` or ends with `isaac` |
  </Tab>
</Tabs>

### Multi-tenant

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `tenant:<name>` | Returns emails where the assigned tenant matches the `<name>` defined in guarded\_tenants.yml |
    | `tenant.uid:<uid>` | Returns emails where the tenant's unique `uid` identifier matches `<uid>` |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `<uid>` | Accepts the value of the `uid` attribute defined in `/shared/guarded_tenants.yml` |
    | `<name>` | Accepts the value of the `<name>` attribute defined in `/shared/guarded_tenants.yml` |
    | These search attributes do not support use of wildcard characters `?` and `*`. | |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `tenant:timespace.com` | Returns all emails of the tenant `timespace.com` |
    | `tenant.uid:db3953f5-2aba-42b1-b038-115d55c56f422` | Returns emails of the tenant whose `uid` matches `db3953f5-2aba-42b1-b038-115d55c56f422` |
    | `tenant:[radio.org,gravity.net]` | Returns all emails of the tenant `radio.org` OR the tenant `gravity.net` |
  </Tab>
</Tabs>

### Direction

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `direction:<Direction>` | Returns emails that were sent, received, exchanged internally, or processed on behalf of a third party |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `<Direction>` | Accepts `incoming`, `outgoing`, `internal`, `external`. Multiple direction matches can be combined with `[<Direction>, ...]` which translates to `<Direction> OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `direction:incoming` | Returns emails sent from external parties to recipients inside the protected organization |
    | `direction:outgoing` | Returns emails sent from the members of the protected organization to external parties |
    | `direction:internal` | Returns emails sent between members of the protected organization |
    | `direction:external` | Returns emails sent from external parties to external parties (as it typically happens if an MTA forwards external emails) |
  </Tab>
</Tabs>

### Date and time

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `received:since:<Keyword> \|<DateString> \|<RelativeDateString>` | Returns emails that were received since the specified date and time |
    | `received:before:<Keyword> \|<DateString> \|<RelativeDateString>` | Returns emails that were received before the specified date and time |
    | `received:[<DateString> TO <DateString>]` | Returns emails that were received in the specified date and time interval (inclusive) |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `Keyword` | Accepts `today`, `noon`, `midnight`, `yesterday` |
    | `DateString` | Accepts a date time string in the following formats:<br />- `dd.mm[.yyyy][,hh:mm]` where `yyyy` and `hh:mm` are optional<br />- `[yyyy-]mm-dd[,hh:mm]` where `yyyy` and `hh:mm` are optional<br />- `[yyyy-]mmm-dd[,hh:mm]` where `mmm = {jan, feb, mar, apr, jun, jul, aug, sep, oct, nov, dec}` and `yyyy` and `hh:mm` are optional |
    | `RelativeDateString` | Accepts a string in the following format `<Number><d \| w \| m>` that indicates the current date minus `<Number>` number of `<d>` days, of `<w>` weeks, or of `<m>` months |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `received:since:noon` or `received:since:today,noon` | Returns all emails received since today 12:00 |
    | `received:since:today,midnight` | Returns all emails received since today 00:00 |
    | `received:since:sep-20,12:30` | Returns all emails received since 12:30, September 20 of the current year |
    | `received:since:2020-09-20` or `received:since:20.09.2020` | Returns all emails received since September 20, 2020 |
    | `received:since:3d` | Returns all emails received within the past three days (current time—72h) |
  </Tab>
</Tabs>

### Tags

xorlab Security Platform enriches processed emails with tags to simplify correlation and retrieval.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `#<String>` | Returns all emails that were tagged with `<String>` |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `String` | Accept any string. String values are parsed as described in the [*Tags*](/latest/tags) reference. Multiple tags are combined with logical `AND` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `#inc` | Returns all incoming emails |
    | `#inc AND #trusted AND #word` | Returns all incoming emails from trusted senders that have a Word file attached |
    | `#out AND #encryptedarchive` | Returns all outgoing emails that have an encrypted archive attached |
    | `#inc AND #highrisk AND #newsender AND #exposedhvt AND #file` | Returns all incoming emails from senders never-before-seen to a high-value target that have a high-risk score and at least one file attached |
    | `#untrusted AND #newdomain AND #exposedhvt` | Returns all emails from untrusted senders to high-value targets that contain at least one link with a domain never-before-seen |
    | `#inc AND #highrisk AND #untrusted AND #newsender AND #cloudstorage` | Returns all incoming emails with a high-risk score from untrusted and unknown senders that contain at least one link to a cloud storage platform |
    | `#inc AND #highrisk AND #newsender AND #shortenednolocalreputation` | Returns all incoming emails with a high-risk score from senders never-before-seen that contain a shortened link which points to a URL that has no local reputation (meaning it is not relevant to the organization) |
    | `#inc AND #trusted AND #dangerousvbascript` | Returns all incoming emails from trusted senders that contain at least one Office file with a VBA script that makes use of potentially dangerous functions |
    | `#inc AND #trusted AND #cracked AND #executable` | Returns all incoming emails from trusted senders with a cracked, encrypted attachment and an executable file attached |
    | `#inc AND #runtime` | Returns all incoming emails with an attachment that triggered a suspicious runtime event (as observed in the Sandbox) |
    | `#pdf AND #cfiviolation` | Returns all emails with a PDF document attached that triggered a CFI violation in the Sandbox (most likely an exploit) |
  </Tab>
</Tabs>

### Scores

xorlab Security Platform generates several scores for each processed email. Each score is a function of the organization’s email history and the email being processed.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `<Score>:<Relation>:<Number>` | Returns all emails with the specified score in a given range |
    | `<Score>:[<Number> TO <Number>]` | Returns all emails with a `<Score>` in the specified interval (inclusive) |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `Score` | Accepts `trust`, `reputation`, `risk`, `threat`, `spam`, and `rsd`:<br />- `trust` denotes the overall trust score — the [relationship](/latest/concepts-relationship) value — and assumes a value between 0 and 100<br />- `reputation` denotes the reputation of the sending domain and assumes a value between 0 and 100<br />- `risk` quantifies the attack surface of an email and assumes a value between 0 and infinity<br />- `threat` is a function of `risk`, `trust`, `reputation` and classification, and quantifies the threat that an email poses to the organization; the score assumes a value between 0 and 100<br />- `spam` quantifies the likelihood of an email being spam; the score assumes a value between negative and positive infinity<br />- `rsd` is the rspamd score of the email; the score assumes a value between negative and positive infinity |
    | `Relation` | Accepts `eq` (equal), `gt` (greater than), `gte` (greater than or equal), `lt` (less than) and `lte` (less than or equal) |
    | `Number` | Accepts integers (for scores `trust`, `reputation`, `risk`, `threat`) and floating point values (for `spam`) |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `reputation:gt:50` | Returns all emails where the reputation score is greater than 50. The reputation is a score associated with authenticated senders based on the global and local reputation of the domain |
    | `spam:lt:0` | Returns all emails with a negative spam score |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `<Score>:<Level>` | Returns all emails with a `<Score>` at least `<Level>` |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `Score` | Accepts `trust`, `reputation`, `risk`, and `threat` (see previous table) |
    | `Level` | Accepts `low`, `medium`, `high` and additionally `noauth` and `trusted` if `Score = reputation`:<br />- `noauth` indicates that the sender of an email could not be authenticated<br />- `trusted` indicates that the email sender could be authenticated and that sender `trust` is greater than 0<br />- `low` captures values between 0 and 50 if `Score = risk` and values between 0 and 34 otherwise<br />-  `medium` captures values between 51 and 75 if `Score = risk` and values between 35 and 67 otherwise<br />- `high` captures values greater 75 if `Score = risk` and values between 68 and 100 otherwise |
  </Tab>
</Tabs>

### Verdicts

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `verdict:<Class> \|<Malicious Verdict> \|<Benign Verdict>` | Returns all emails from a given verdict class or with a specific verdict. For more information about verdicts, please see [*Verdicts*](/latest/verdicts) |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | - |
    | `Class` | Accepts `benign`, `malicious`, and `undecided`. Note that `benign` does not include `simulation` |
    | `Malicious Verdict` | Accepts `bec`, `blacklist`, `extortion`, `filter`, `impersonation`, `malware`, `malware_static`, `malware_dynamic`, `phishing`, `policy`, and `vipfraud`. Multiple verdict matches can be combined with a comma-separated list (which is similar to logical `OR`) using the special syntax `:[<Verdict>, ...]` |
    | `Benign Verdict` | Accepts `bulk`, `business`, `cloudstorage`, `crm`, `external`, `forwarded`, `freemail`, `internal`, `marketing`, `newsletter`, `partner`, `personal`, `poll`, `popular`, `reputable`, `simulation`, `socialnetwork`, `survey`, and `trusted`.  Multiple verdict matches can be combined with a comma-separated list (which is similar to logical `OR`) using the special syntax `:[<Verdict>, ...]` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `verdict:malware` | Returns all emails containing malware, detected either statically or in the Sandbox |
    | `verdict:malware_dynamic` | Returns only emails whose malware was detected in the [Sandbox](/latest/xorlab-sandbox). Use `verdict:malware_static` for statically detected malware |
    | `verdict:policy` | Returns all emails with a Policy **or** Blacklist verdict. Use `verdict:filter` to match only Policy |
    | `verdict:simulation` | Returns all emails that are part of some simulated awareness campaign |
    | `verdict:bulk` | Returns all emails that are part of a bulk campaign |
  </Tab>
</Tabs>

### Verdict confidences

To search for emails with a certain verdict confidence, you need to make use of the `rule:` search feature described [further in this article](#predefined-filters). The verdicts that are not listed in the following table do not have different confidences.

| Verdict | Description |
| :- | :- |
| Phishing | **High:** `rule:PHISHING_high_confidence_decision`<br />**Med:** `rule:PHISHING_medium_confidence_decision`<br />**Low:** `rule:PHISHING_low_confidence_decision` |
| Spam | **High:** `rule:SPAM_high_confidence_decision`<br />**Med:** `rule:SPAM_medium_confidence_decision`<br />**Low:** `rule:SPAM_low_confidence_decision` |
| VIP Fraud | **High:** `rule:VIP_FRAUD_high_confidence_decision`<br />**Med:** `rule:VIP_FRAUD_medium_confidence_decision` |
| Impersonation | **High:** `rule:IMPERSONATION_high_confidence_decision`<br />**Med:** `rule:IMPERSONATION_medium_confidence_decision` |
| Policy (Filter) | **High:** `rule:FILTER_high_confidence_decision`<br />**Med:** `rule:FILTER_medium_confidence_decision` |

### Processing status

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `status:<ProcessingStatus>` | Returns emails that are in the specified processing status. The value of `<ProcessingStatus>` depends on the type of email, whether it was quarantined or whether somebody reported it as suspicious |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `ProcessingStatus` | - Accepts `delivered`, `quarantined`,` released`, `dropped`, `bounced`, `pending`, `smtperror` for emails from the normal mail flow<br />- Accepts `open`, `resolved`, and `pending` for emails reported as suspicious<br />- Accepts `completed` and `pending` for reported and uploaded suspicious files<br />- Emails with `status:pending` can be in the state of `processing:ongoing` or `processing:error`<br />- Multiple matches can be combined with `[<ProcessingStatus>, ...]` which translates to `<ProcessingStatus > OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `status:delivered` | Returns all emails from normal mail flow that were delivered either to the recipient’s mailbox (incoming emails) or to the Internet (outgoing emails) |
    | `status:quarantined` | Returns all emails from normal mail flow that were quarantined. Emails in this state can be [filtered](#predefined-filters) with `quarantine:<QuarantineLabel>` |
    | `status:released` | Returns all emails that were released from quarantine |
    | `status:dropped` | Returns all emails from normal mail flow that were dropped (i.e., deleted and not delivered) |
    | `status:pending` | Returns all emails that are currently being processed or caused an error while processing. Emails in this status can be filtered with `processing:ongoing` or `processing:error` |
    | `status:smtperror` | Returns all emails that have failed in delivery |
    | `status:open` | Returns all reported emails that require further analysis |
    | `status:resolved` | Returns all reported emails that were resolved, either automatically by the platform or manually by an analyst |
  </Tab>
</Tabs>

## Email content

### Topics

The `topic` keyword allows searching for topics found in any part (body, subject and attachment) of the email.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `topic:<Match>` | Returns all emails with a given topic |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings (case-insensitive). Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`. See [topic detection](/latest/topic-detection) for possible values |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `topic:sexualcontent` | Returns all emails with the topic `sexualcontent` |
    | `topic:[sexualcontent,invoice]` | Returns all emails with one of the topics `sexualcontent` or `invoice` |
  </Tab>
</Tabs>

### Body

The `body` keyword allows searching topics in the email's plaintext or HTML body parts.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `body.topic:<Match>` | Returns all emails with a given topic in the email body (HTML or plaintext part) |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings (case-insensitive). Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`. See [topic detection](/latest/topic-detection) for possible values |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `body.topic:sexualcontent` | Returns all emails with the topic `sexualcontent` in the email body |
    | `body.topic:[sexualcontent,invoice]` | Returns all emails with one of the topics `sexualcontent` or `invoice` in the email body |
  </Tab>
</Tabs>

### Subject

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `subject:<Match>` | Returns all emails with a given subject |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings (case-insensitive) and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`.  If the subject to be matched contains spaces, then you must enclose the subject string in double quotes. Use `\` to escape quotes |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `subject:"How the world works"` | Returns all emails with a subject equal to `How the world works` |
    | `subject:"This is \"a laser\""` | Returns all emails with a subject equal to `This is "a laser"` |
    | `subject:[The*,*world*]` | Returns all emails with a subject that begins with `The` or contains `world`, e.g., `The world works like this` |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `subject.topic:<Match>` | Returns all emails with a given topic in the subject |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings (case-insensitive). Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`. See [topic detection](/latest/topic-detection) for possible values |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `subject.topic:sexualcontent` | Returns all emails with the topic `sexualcontent` in the subject |
    | `subject.topic:[sexualcontent,invoice]` | Returns all emails with one of the topics `sexualcontent` or `invoice` in the subject |
  </Tab>
</Tabs>

### Embedded links

xorlab Security Platform extracts links from the email body and attached documents.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `link:<Match>` | Returns all emails that contain the matching link |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`.  If the link to be matched contains the reserved characters (i.e., `:`, `#`, `(`, `)`, `[`, `]` ),  then you must enclose the link in double quotes. Use `\` to escape quotes |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `link:"http://www.xorlab.com"` | Returns all emails that contain at least one link to [xorlab.com](http://www.xorlab.com/) |
    | `link:"http://www.xorlab.*"` | Returns all emails that contain at least one link that starts with [*http://www.xorlab*](http://www.xorlab) |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `link.displaytext:<Match>` | Returns all emails that contain a link matching the given display text |
  </Tab>

  <Tab title="Arguments">
    | | Description |
    | :- | :- |
    | `Match` | Accepts strings and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`.  If the display text of a link to be matched contains spaces, then you must enclose the display text string in double quotes. Use `\` to escape quotes |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `link.displaytext:"Click me!"` | Returns all emails that contain at least one link with the display text `Click me!` |
    | `link.displaytext:"Click *!"` | Returns all emails that contain at least one link with the display text that starts with `Click ` and that ends with `!` |
    | `link.displaytext:["Click me!", "Click here!"]` | Returns all emails that contain at least one link with the display text `Click me!` or `Click here!` |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `link.location:<Location>` | Returns all emails that contain a link in the given location (e.g., message body or a message attachment) |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Location` | Accepts `body` and `attachment` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `link.location:body` | Returns all emails that contain at least one link within their body |
  </Tab>
</Tabs>

### Embedded domains

xorlab Security Platform extracts domains from the links it finds in the email body and attachments. This includes domains that surface in network activity during dynamic file analysis.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `domain:<Match>` | Returns all emails that contain a given domain |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `domain:xorlab.com` | Returns all emails that contain at least one link to the [xorlab.com](http://www.xorlab.com/) domain |
    | `domain:[*xorlab.com,*xorlab.ch]` | Returns all emails that contain at least one link to the subdomains of [xorlab.com](http://www.xorlab.com/) and [xorlab.ch](http://www.xorlab.ch/) |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `domain.date:since:<Keyword> \| <DateString> \| <RelativeDateString>` | Returns emails that contain a domain registered since the specified [date and time](#date-and-time) |
    | `domain.date:before:<Keyword> \| <DateString> \| <RelativeDateString>` | Returns emails that contain a domain registered before the specified [date and time](#date-and-time) |
    | `domain.date:[<DateString> TO <DateString>]` | Returns emails that contain a domain registered in the specified date and time interval (inclusive) |
    | `domain.ip:<IpValue>` | Returns emails that contain a domain with the specified IP |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `IpValue` | Accepts a valid IP version 4. Multiple IP matches can be combined with `[<IpValue>, ...]` which translates to `<IpValue> OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `domain.ip:172.217.10.78` | Returns all emails that contain at least one domain with the IP matching `172.217.10.78` |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `domain.(local \| global):<Relation>:<Number>` | Returns emails that contains a domain with the local or global reputation system score within [a given range](#scores) |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Relation` | Accepts `eq` (equal), `gt` (greater than), `gte` (greater than or equal), `lt` (less than) and `lte` (less than or equal) |
    | `Number` | Accepts integers (for scores `trust`, `reputation`, `risk`, `threat`) and floating point values (for `spam`) |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `domain.global:gt:5` | Returns all emails that contain a domain with a global reputation greater than 5 |
    | `domain.local:lt:5` | Returns all emails that contain a domain with a local reputation lower than 5 |
  </Tab>
</Tabs>

## Email attachments

xorlab Security Platform supports file name and file hash filters as well as specific file analysis verdicts.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `file.name:<Match>` | Returns all emails that contain a file matching the given term |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`.  If the link display text to be matched contains spaces, then you must enclose the link display text string in double quotes. Use `\` to escape quotes |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `file.name:"Please open.exe"` | Returns all emails with an attachment named `Please open.exe` |
    | `file.name:*.exe` | Returns all emails with an attachment  that ends with `.exe` |
    | `file.name:[*exe, *hta, *bat]` | Returns all emails with attachments name ending with the tokens `exe`, `hta` or `bat` |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `file.hash:<SHA256>` | Returns all emails that contain a file matching the given SHA256 hash value |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | - | - |
    | `SHA256` | Accepts hash values computed with the SHA256 algorithm. Multiple hash value matches can be combined with `[<SHA256>, ...]` which translates to `<SHA256> OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `file.hash:275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f` | Returns all emails with an attachment whose SHA256 hash value equals `275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f` |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `file.type:<Match>` | Returns all emails that contain a file matching the xorlab Security Platform extracted file type |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | - | - |
    | `Match` | Accepts strings and wildcards (using `matches:`). Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`. |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `file.type:document` | Returns all emails with attachments of the `document` type |
    | `file.type:[exe, document]` | Returns all emails with attachments of the `exe` or `document` type |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `file.topic:<Match>` | Returns all emails with a given topic in an attachment |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Match` | Accepts strings (case-insensitive). Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...`. See [topic detection](/latest/topic-detection) for possible values |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `file.topic:sexualcontent` | Returns all emails with the topic `sexualcontent` in an attachment |
    | `file.topic:[sexualcontent,invoice]` | Returns all emails with one of the topics `sexualcontent` or `invoice` in an attachment |
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `verdict: <Verdict>` | Returns all emails that contain a file with a given verdict class or with a specific verdict |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | - | - |
    | `Verdict` | Accepts `activex`, `archive`, `data`, `dde`, `document`, `embobject`, `encrypted`, `executable`, `extobject`, `flash`, `image`, `iso`, `legacy`, `script`, `shortcut`, and `vbascript`.  Multiple verdict matches can be combined with a comma-separated list (which is similar to logical `OR`) using the special syntax `:[<Verdict>, ...]` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `verdict:activex` | Returns all emails containing an attachment with ActiveX content |
  </Tab>
</Tabs>

## Email headers

xorlab Security Platform supports searching across the message header name and values.

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `header.<Part>:<Match>` | Returns all emails that contain a header matching the given name or value |
    | `header:{name:<Match> AND value:<Match>}` | Returns all emails that contain one header matching both the name and the value |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | :- | :- |
    | `Part` | Accepts `name` or `value` |
    | `Match` | Accepts strings and wildcards. Multiple matches can be combined with `[<Match>, ...]` which translates to `<Match> OR ...` |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `header.name:"x-spam-score"` | Returns all emails that contain a header with the  `x-spam-score` name |
    | `header.name:"*malicious"` | Returns all emails that contain a header name that ends with `malicious` |
    | `header:{name:"x-spam-result" AND value:"*MIME_HTML_ONLY*"}` | Returns all emails with `MIME_HTML_ONLY` in the `x-spam-result` header |
  </Tab>
</Tabs>

## Predefined filters

| Filter | Description |
| - | - |
| `messages` | Returns all processed emails from regular mail traffic |
| `reported` | Returns all emails that were reported as suspicious |
| `quarantine:<QuarantineLabel>` | Returns all emails from a given quarantine, where `<QuarantineLabel>` accepts `malware`, `phishing`, `extortion`, `impersonation`, `fraud` (deprecated), `filter`, and `spam`<br />**Examples:**<br />- `quarantine:malware` returns all emails that contained malware<br />- `quarantine:impersonation quarantine:phishing` returns all emails that impersonated somebody to deliver a phishing link |
| `files` | Returns all uploaded files |

### Queries using rules

<Tabs>
  <Tab title="Query syntax">
    | Query | Description |
    | - | - |
    | `rule:<Rule>` | Returns all emails for which the specified rule has been executed during the processing of the email |
    | `passiverule:<Rule>` | Returns all emails for which the specified rule has been executed, but was configured as passive, so it did not influence the decision or tags |
  </Tab>

  <Tab title="Arguments">
    | Argument | Description |
    | - | - |
    | `Rule` | Accepts any rule name.  A rule name must contain only lower and upper-case letters and no other character except underscore |
  </Tab>

  <Tab title="Examples">
    | Query | Result |
    | - | - |
    | `rule:TAG_link_no_reputation` | Returns all emails for which the rule `TAG_link_no_reputation` was applied. The rule adds the `#noreputation` hashtag to an email, as the name of the rule suggests |
  </Tab>
</Tabs>


# Integration Overview
Source: https://docs.xorlab.com/latest/setup-integration-overview

Where to start integrating xorlab, including the choice between the Microsoft 365 and on-premises paths.

**Start here.** These three steps are the complete, standard xorlab integration — mail flow, user login, reporting, and the optional Microsoft 365 features. Follow them in order.

1. Follow [Before You Begin](/latest/before-begin-integration).
2. Choose your integration:

   <CardGroup>
     <Card title="M365" icon="microsoft" href="/latest/m365-integration-overview">
       Integrate xorlab with your M365. Use this also for hybrid setups where you receive and send emails via M365.
     </Card>

     <Card title="On-premises" icon="server" href="/latest/on-prem-integration-overview">
       Integrate xorlab with your on-premises infrastructure. Use this also for hybrid setups where you receive and send emails on-premises.
     </Card>
   </CardGroup>
3. After you completed the integration above, follow [Next Steps](/latest/integration-next-steps).

## What changes in your environment

The integration is made of settings in your own admin portal — connectors, mail flow rules and an app registration. Nothing is installed on your servers, clients or endpoints, no mailbox is moved, and with M365 your MX records keep pointing at Microsoft.

<Card title="Review What Changes in Your Environment" icon="list-check" href="/latest/integration-impact">
  Which settings each path adds, what it leaves untouched, what your users notice, and how to undo it.
</Card>

<Card title="What Integrating xorlab Involves" icon="server" href="/latest/admin-essentials">
  The wider picture around these steps: choosing between SaaS and on-premises, what your users notice, and what you maintain once the integration is live.
</Card>

## Multi-Tenancy

If you protect multiple organizations with a single xorlab instance, do not follow the steps above one by one. Instead, onboard each organization as a tenant:

<Card title="Add a Tenant" icon="rocket-launch" href="/latest/multi-tenancy-new-tenant">
  Step-by-step guide that walks you through domains, routing, mail flow activation and the optional per-tenant features.
</Card>

See [Multi-Tenancy Overview](/latest/multi-tenancy-overview) for the full picture.


# Advanced SMTP Configurations
Source: https://docs.xorlab.com/latest/smtp-configuration

Advanced Postfix SMTP settings in the postfix-custom folder, including next-hop syntax.

All configuration files mentioned here are in the folder `activeguard/mta/startup_cfg/postfix_custom/`.

## Next hop syntax

The following syntax can be used to set the next hop in routing-related configuration, for example in `transport` maps or in the `relayhost` parameter.

| Format | Example | Description |
| :- | :- | :- |
| `Domain` | `gateway.xorlab.com` | Look up the destination through DNS MX records of the domain. This provides the most flexibility and automatic fallback if there are multiple MX records specified |
| `[Domain]` | `[gateway.xorlab.com]` | Look up the destination through DNS A records of the domain |
| `[IP]` | `[1.2.3.4]` | Use the IP address directly as the next destination |

## Sender-based routing

In sender-based routing, the next hop (referred to as `<next-hop>`) for the email is chosen based on the sender’s address (`MAIL FROM`). This configuration is usually only used in conjunction with recipient-based routing to address special cases.

First, we need to enable the sender-dependent transport in the `main.cf` file:

```shell theme={null}
sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport
```

If the `sender_dependent_transport` file does not exist, you have to create it.

<Note>
  **Routing precedence**

  Please be aware that recipient-based routing has **precedence** over sender-based routing. If a recipient address matches an entry in `transport`, it will overrule any next-hop configurations from a match in `sender_dependent_transport`.
</Note>

Afterward, for every sender that you would like to configure, add one line to the `sender_dependent_transport` file. You can specify sender email addresses as well as sender domains:

```shell theme={null}
# Example for sender domain-based routing
@xorlab.com         <next-hop>
# Example for sender email address-based routing
test1@xorlab.com    <next-hop>
test2@xorlab.com    <next-hop>
```

Afterward, click **Publish**. The new Postfix settings become active within about one minute.

## Subdomain matching

### Subdomains in transport maps

When configuring email routing in `transport`, subdomains are not matched by default. This means that if you want to route emails for both a domain (e.g., xorlab.com) and its subdomains (e.g., sub.xorlab.com), you must either specify them explicitly or use the dot-prefix (.) syntax to apply a wildcard rule.

```shell theme={null}
# Routing for xorlab.com
xorlab.com      smtp:<next-hop>

# Routing for xorlab.com and all subdomains
xorlab.com      smtp:<next-hop>
.xorlab.com     smtp:<next-hop>
```

If you want subdomain matching to be applied automatically for all entries in your transport file, you can enable it globally. To do this, add the following line to `main.cf`:

```shell theme={null}
# Enable subdomain matching for all transport entries
parent_domain_matches_subdomains = transport_maps
```

Afterward, click **Publish**. The new Postfix settings become active within about one minute.

### Subdomains in client access

In contrast, subdomain matching behaves differently for `client_access` and `relay_domains` configurations. For these settings, subdomains are automatically matched without requiring explicit entries. This is because Postfix performs a reverse DNS lookup on the EHLO IP address, which allows it to match both the domain and its subdomains seamlessly.

For example:

* In `client_access`, you only need to list the top-level domain (xorlab.com), and subdomains will be matched automatically.
* Similarly, listing the main domains as `relay_domains` in `main.cf` is sufficient for subdomain matching.

## Sender and recipient restrictions

This section explains how to impose generic restrictions on either a sending MTA or on a recipient address or domain.

<Note>
  **SMTP restrictions**

  The restrictions described in this section refer to the SMTP connection only. Emails rejected during the SMTP connection will not appear in the XCC web interface.
</Note>

### Reject clients

To reject emails from certain sender IPs or hostnames during the SMTP connection, list them in the `client_access` file with `reject`:

```shell theme={null}
# Reject SMTP connection based on IP or hostname (EHLO)
1.2.3.4           reject
1.3               reject
ehlo.example.com  reject
```

Afterward, click **Publish**. The new Postfix settings become active within about one minute.

### Reject recipients

To reject all emails to certain recipients, add these recipients to the file `recipient_access`:

```shell theme={null}
# Reject certain recipients or recipient domains
recipient@xorlab.com    reject
xorlab.net              reject
```

Afterward, click **Publish**. The new Postfix settings become active within about one minute.

## TLS configuration

TLS policies can be defined for xorlab Security Platform when acting as a client as well as when acting as a server. The policies are set in `main.cf`:

```shell theme={null}
# TLS policy as client
smtp_tls_security_level = may
# TLS policy as server
smtpd_tls_security_level = may
```

Supported values include:

* `none`: Disable TLS.
* `may` (default): Opportunistic TLS. Use TLS if the client, respectively the server, supports TLS.
* `encrypt`: Enforce TLS. Do not send or receive emails without TLS. No valid certificate required.
* `verify`: Enforce TLS and successful certificate verification. Only supported for `smtp_tls_security_level`.

All values and additional information can be found in the Postfix documentation for the [`smtp_tls_security_level`](http://www.postfix.org/postconf.5.html#smtp_tls_security_level) as well as [`smtpd_tls_security_level`](http://www.postfix.org/postconf.5.html#smtpd_tls_security_level).

After changing the TLS policy, click **Publish**. The new Postfix settings become active within about one minute.

## SMTP auth for specific email addresses

If you want emails sent from specific addresses to be routed through an SMTP server requiring authentication, you can follow this configuration. For example, you can authenticate xorlab Security Platform when sending reported email feedback from the `threatanalyst@example.com` address:

1. Set the desired sender address for feedback emails as described in [Feedback emails](/latest/email-template-sender-addresses#feedback-emails). We will use `threatanalyst@example.com` here. For any other email addresses, just skip this step.

2. Configure [sender-dependent transport](#sender-based-routing) in the `main.cf` file by enabling (uncommenting) this line:

   ```
   sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport
   ```

3. If the `sender_dependent_transport` file does not exist, create it and add this entry:

   ```
   threatanalyst@example.com [smtp.example.com]:2525
   ```

4. In the same folder, create two files: `sasl_passwd.lmdb` and an `sasl_passwd` file. Leave the former empty, while in the latter add this line:

   ```
   [smtp.example.com]:2525 username:password
   ```

5. Finally, go back to the `main.cf`file and add the following block under the line you enabled in step #2:

   ```
   sender_dependent_relayhost_maps = lmdb:/etc/postfix/sender_dependent_transport
   # Auth for sender_dependent
   smtp_sasl_password_maps = lmdb:/etc/postfix/sasl_passwd
   smtp_sender_dependent_authentication = yes
   smtp_sasl_auth_enable = yes
   smtp_sasl_mechanism_filter = plain
   smtp_sasl_security_options = noanonymous
   ```

6. Click **Publish**. The new Postfix settings become active within about one minute.

## Message size limit

The maximum message size that xorlab Security Platform will accept during an SMTP connection can be defined in `main.cf` and `postfix_custom/master.cf`:

```shell main.cf theme={null}
# Max accepted mail size in bytes, the limit can be increased if absolutely necessary
message_size_limit = 52428800
```

```shell master.cf theme={null}
mta.activeguard.xor:10026 inet  n       -       n       -       20      smtpd
  -o message_size_limit=57671680
```

<Tip>
  Note that the value of the `message_size_limit` setting in `master.cf` has to be 1.1x higher than in `main.cf`.
</Tip>

The default message size is 50 MB. This limit can be increased if necessary. However, consider the following points:

* Many major email providers don’t accept message sizes over 35 MB.
* The xorlab Security Platform file size limit for attachments sent to the Sandbox is 50 MB.
* Aggressively increasing the message size limit can slow down email processing times.

After changing the message size limit, click **Publish**. The new Postfix settings become active within about one minute.

## Additional configuration

xorlab Security Platform exposes the internal Postfix configuration files and thereby allows you to use the entire SMTP configuration that Postfix offers. This includes, for example:

* Address rewrites
* Header rewrites
* SMTP connection configuration (limit, rate, delay, etc.)

Please refer to the [Postfix documentation](http://www.postfix.org/documentation.html) if you want to configure one of those things.

Afterward, you can configure it directly in the Postfix configuration files that are exposed in XCC. Below you can find all built-in Postfix files. You can also add additional files in [Expert Editor](/latest/expert-editor).

<Note>
  **Postfix lookup tables**

  xorlab supports [Postmap](http://www.postfix.org/postmap.1.html) lookup tables in `lmdb:` format ([Lookup tables](http://www.postfix.org/DATABASE_README.html)).

  The following files are automatically postmapped: `client_access`,`client_access_tenant`,`recipient_access`,`sender_access`,`transport`,`sender_dependent_transport` and `postmap_*`.

  If you use a different file name, you need to either:

  a) Prefix your file `postmap_`.

  b) Create an empty file with the same name and `.lmbd` suffix. E.g., for `custom_transport`, you need to create an empty file called `custom_transport.lmdb` in the same folder.
</Note>

| Name | Postfix Resource | Description |
| :- | :- | :- |
| `client_access` | [http://www.postfix.org/postconf.5.html#check\_client\_access](http://www.postfix.org/postconf.5.html#check_client_access) | Restrictions based on the client hostname or IP during SMTP connection |
| `header_checks` | [http://www.postfix.org/header\_checks.5.html](http://www.postfix.org/header_checks.5.html) | Is not active by default. You have to configure it first in `main.cf` |
| `main.cf` (or `main.cf.vmx.<id>`) | [http://www.postfix.org/postconf.5.html](http://www.postfix.org/postconf.5.html) | Main configuration |
| `master.cf` | [http://www.postfix.org/master.5.html](http://www.postfix.org/master.5.html) | Normally, it should not be changed. Can break email routing easily |
| `recipient_access` | [http://www.postfix.org/postconf.5.html#check\_recipient\_access](http://www.postfix.org/postconf.5.html#check_recipient_access) | Restrictions based on the RCPT TO during SMTP connection |
| `sender_access` | [http://www.postfix.org/postconf.5.html#check\_sender\_access](http://www.postfix.org/postconf.5.html#check_sender_access) | Restrictions during SMTP connection based on the sender |
| `sender_access_add_header` | N/A | Used only internally. Adds the `envelope from` into a new header `x-xor-envelope-from` |

## Reserved configuration

The following Postfix features are reserved for internal use and must not be configured:

* [`mynetworks`](http://www.postfix.org/postconf.5.html#mynetworks): Use the `client_access` file instead to allow certain IPs to relay emails through xorlab Security Platform
* [`content_filter`](http://www.postfix.org/postconf.5.html#content_filter)

## Multi-Tenancy

In a multi-tenant deployment, routing is configured with the same Postfix files described on this page, but they have to line up with the tenants declared in `shared/guarded_tenants.yml`:

* `transport` needs a next hop per guarded domain.
* `client_access` needs to permit the SMTP clients of every tenant.
* `client_access_tenant` prepends the header that xorlab uses to identify the tenant, matching the `tenantSelector` of that tenant.

Do not assemble this by hand from this page. [Configure Tenant Domains and Routing](/latest/multi-tenancy-domain-and-routing) contains the complete, consistent configuration for each supported topology (Default Chain, M365, Star, Front MTA and Full Chain).


# Enable Attachment Airlock
Source: https://docs.xorlab.com/latest/ssq-attachment-airlock

Hold emails with encrypted attachments in the Self-Service Quarantine until the user supplies a password, then re-analyze them.

Only attachments that cannot be decrypted through other means are affected.

<Warning>
  **Prerequisites**

  * Complete [Set Up the SSQ](/latest/ssq-setup)
</Warning>

Follow the steps below to activate this feature:

1. In [Expert Editor](/latest/expert-editor), navigate to `activeguard/core/rule_sets/90_local/params/local.properties`.

2. Edit the file by inserting the following lines:
   ```text theme={null}
   # Enable Attachment Airlock
   ATTACHMENT_AIRLOCK_decision_state=ACTIVE
   ```
   This parameter activates the Attachment Airlock feature. If, for any reason, you wish to deactivate this feature in the future, simply change the parameter from `ACTIVE` to `DISABLED`.

3. Click **Publish**. The rule-set configuration becomes active within about one minute.

## Password Compatibility

Attachment Airlock expects passwords to be UTF-8 encoded. If a file is encrypted with a password containing special characters (e.g., ç, ü, ñ) using older tools or systems that use legacy encodings like CP437 or ISO-8859-1, unlocking may fail due to encoding mismatches.

## Using Attachment Airlock

With Attachment Airlock enabled, users can unlock password-protected attachments in a secure environment and have them analyzed by xorlab. When an email with a password-protected attachment is sent to an xorlab user, and the password protection can’t be automatically cracked by xorlab, the user receives the following notification email:

<img alt="Airlock notification" />

By clicking the **Unlock safely** link, you are redirected to the [SSQ portal](/latest/ssq-overview) with the preview of the quarantined message (if the main SSQ page is opened instead, just click the **Attachments** tab and click the message):

<Info>
  The **Attachments** tab in the SSQ shows the contents of the `Airlock` quarantine — the quarantine you configure under that name in `guarded_tenants.yml`, see [List of Quarantines](/latest/ssq-list-of-quarantines).
</Info>

<img alt="Airlock message preview" />

To unlock the message, click **Unlock** and enter the password for the attachment:

<img alt="Enter the attachment password" />

With the provided password, xorlab starts analyzing the attachment and informs you about it:

<img alt="Unlocking the attachment" />

After a successful analysis, if the attachment is safe, the message is unlocked and delivered to your mailbox:

<img alt="Unlocked message" />


# List of Quarantines
Source: https://docs.xorlab.com/latest/ssq-list-of-quarantines

Which quarantine each verdict lands in, and who is allowed to release from it.

The quarantines can be adjusted and extended in the `shared/guarded_tenants.yml`. You only need to add the quarantines that you want to adjust.

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    domains:
      - example.com
    quarantine:
      quarantines:
        - name: Malware
          canView: true
          canRelease: false
          canRequestRelease: false
        - name: Extortion
          canView: true
          canRelease: false
          canRequestRelease: false
        - name: Impersonation
          canView: true
          canRelease: false
          canRequestRelease: false
        - name: Filter
          canView: true
          canRelease: false
          canRequestRelease: false
        - name: Phishing
          canView: true
          canRelease: true
          canRequestRelease: false
        - name: Spam
          canView: true
          canRelease: true
          canRequestRelease: false
        - name: BEC
          canView: true
          canRelease: true
          canRequestRelease: false
        - name: Airlock
          canView: true
          canRelease: false
          canRequestRelease: false
          # Special case - do not use canUnlock on any other quarantine
          canUnlock: true
```


# SSQ Overview
Source: https://docs.xorlab.com/latest/ssq-overview

Let end users view and release their own quarantined emails through the Self-Service Quarantine.

The Self-Service Quarantine (SSQ) gives each user access only to their own emails.

For a basic setup follow:

<Card title="Set Up the SSQ" icon="rocket-launch" href="/latest/ssq-setup" />

Afterward you can further customize it as shown below.

| Step | Description |
| :- | :- |
| [Set Up the SSQ](/latest/ssq-setup) | **Mandatory**. Basic configuration of the SSQ. |
| [Enable Release Requests](/latest/ssq-request-release) | **Optional**. Allow your users to request the release of dangerous emails in the SSQ. |
| [Enable Attachment Airlock](/latest/ssq-attachment-airlock) | **Optional**. Quarantine all encrypted attachments that cannot be decrypted. The user can enter the password in the SSQ to release it. |
| [Support Shared Mailboxes](/latest/ssq-shared-mailboxes) | **Optional**. Allow users to access shared mailboxes in the SSQ. |

## Multi-Tenancy

All SSQ configuration lives in `guarded_tenants.yml` and is therefore already tenant-aware. Follow the same steps as above, once per tenant.

There is one exception: for [Support Shared Mailboxes](/latest/ssq-shared-mailboxes), use [Auto-Login](/latest/authentication-auto-login-link). The M365 shared mailbox script is not recommended in a multi-tenant deployment.

You can also give each tenant its own logo and texts in the quarantine notifications, see [Customize Tenant Notifications](/latest/multi-tenancy-email-templates).


# Enable Release Requests
Source: https://docs.xorlab.com/latest/ssq-request-release

Let end users request release of emails they cannot release themselves, for analyst review.

End-users request release from their Self-Service Quarantine (SSQ); analysts then decide whether to release or deny each request.

<Warning>
  **Prerequisites**

  * Complete [Set Up the SSQ](/latest/ssq-setup)
</Warning>

Follow the steps below to activate this feature:

1. In Expert Editor, open `shared/guarded_tenants.yml`.

2. Set `canRequestRelease: true` and `canRelease: false`for every quarantine where you want to enable the request release. See [List of Quarantines](/latest/ssq-list-of-quarantines).

   ```yaml {7,8} theme={null}
   tenants:
     - name: xorlab.com
       quarantine:
         quarantines:
           - name: Phishing
             canView: true
             canRelease: false
             canRequestRelease: true
   ```

   The feature must be enabled **separately for each quarantine**. It only applies to quarantines where **end-users do not already have release permissions**.

3. Click **Publish**. The new configuration becomes active within about one minute. The SSQ will then show a **Request Release** button for emails in the corresponding quarantines.

   <img alt="Request Release" />

## Enable request notifications

You can configure notifications to be triggered when specific release request events occur.

* `audit.quarantine.release.request.created` – A user has submitted a release request
* `audit.quarantine.release.request.approved` – An analyst has approved and released the email
* `audit.quarantine.release.request.denied` – An analyst has denied the release request

These notifications can be sent via Email or via Syslog:

* For **email notification**, there is a working example in the **XCC (Backend container)** tab of [Send an Email When an Event Occurs](/latest/logging-via-email).
* To forward the events to your **SIEM**, see [Forward Events over Syslog](/latest/logging-via-syslog).

## Workflow

If you want to know more about the workflow from analyst and end-user perspective, have a look at [Handling Release Requests](/latest/handling-release-requests).


# Set Up the SSQ
Source: https://docs.xorlab.com/latest/ssq-setup

Choose how employees reach the Self-Service Quarantine (SSQ) and what they may do there. It is always on; only access needs configuring.

## Quickstart

1. Choose how end-users should access the SSQ.

   <CardGroup>
     <Card title="Preferred: Auto-Login" icon="link">
       Via Auto-Login, users can access their SSQ by just clicking on the link in the quarantine notifications.
       Follow [Auto-Login Setup Guide](/latest/authentication-auto-login-link#quickstart) to set it up
     </Card>

     <Card title="SAML or LDAP" icon="user-tag">
       End-users authenticate via SAML or LDAP to access the SSQ. If this has not yet been setup:

       * **SaaS**: Follow [M365 SAML Login](/latest/m365-saml-entra-authentication)
       * **On-prem**: Follow [On-prem SAML or LDAP Login](/latest/on-prem-saml-ldap-authentication)
     </Card>
   </CardGroup>
2. If you use [Auto-login](/latest/authentication-auto-login-link), this step can be skipped. Otherwise: Assign the `xcc_quarantine_user` role to the users that should be able to access the SSQ. Depending on the user login, this looks different:

   <Accordion title="SAML">
     1. Assign the users a dedicated SSQ role in your IDP. We name it here `saml_xor_quarantine_user`.
     2. Add the role mapping to `auth.yml` under your SAML backend in `saml2AuthBackends`:
        ```yaml auth.yml highlight={2-3} theme={null}
        roleMapping:
          xcc_quarantine_user:
          - saml_xor_quarantine_user
        ```
   </Accordion>

   <Accordion title="LDAP">
     1. Assign the users a dedicated SSQ role in your Active Directory. We name it here `ldap_xor_quarantine_user`.
     2. Add the role mapping to `auth.yml` under your LDAP configuration in `ldapAuthDataSources`:
        ```yaml auth.yml highlight={2-3} theme={null}
        roleMapping:
          xcc_quarantine_user:
          - ldap_xor_quarantine_user
        ```
   </Accordion>

   <Accordion title="Local user">
     1. Open the file `auth/auth/passwordFile.yml`
     2. Add the role to the user that should access the SSQ:

     ```yaml passwordFile.yml highlight={4} theme={null}
     users:
       - username: admin
         roles:
           - xcc_quarantine_user
     ```
   </Accordion>

   Click **Publish**. The authentication configuration becomes active within about one minute, and the users should then be able to access the SSQ in xorlab.
3. Review the default quarantine permissions. No action is required if the default works for you.
   | Permission | Description | Default |
   | :- | :- | :- |
   | `canView` | Users can view emails in their SSQ | `true` for all quarantines |
   | `canRelease` | Users can release emails in their SSQ | `true` for *Phishing* and *Spam*, `false` for all other quarantines |
   | `canRequestRelease` | Users can request the release of emails, and an Analyst/Admin needs to confirm it. Works only when `canRelease` is disabled | `false` for all quarantines |
   | To see all quarantines and their defaults: [List of Quarantines](/latest/ssq-list-of-quarantines). | | |
   | To overwrite the permission of a quarantine, add the following to `guarded_tenants.yml`: | | |
   ```yaml shared/guarded_tenants.yml highlight={6-9} theme={null}
   tenants:
     - name: xorlab
       quarantine:
         quarantines:
             ## Add the quarantines here where you want to overwrite the default configuration
             - name: Malware
               canView: true
               canRelease: false
               canRequestRelease: true
   ```
4. Open the file `shared/email_templates/info/default.yml` and set the following parameters. They will be shown in the footer of the quarantine notifications.
   <Warning>
     **The `url` parameter must be set to the URL of your xorlab**
   </Warning>
   ```yaml default.yml theme={null}
   name: "Example, Inc."
   details: "Security Operations Center"
   email: "secops@example.com"
   url: "https://xyz.activeguard.cloud"
   provider: "xorlab AG"
   ```
5. Customize the quarantine notifications such that they match your organization brand. All customizations are described under [Customize Templates](/latest/email-template-modifications). We recommend to at least change the [Logo](/latest/email-template-modifications#change-the-logo).
6. Optional: Adjust the sender address that is used for quarantine notifications: [Change Sender Address](/latest/email-template-sender-addresses#quarantine-notifications). The default is `quarantine@<domain>`, with `<domain>` referring to the tenant's primary domain.
7. Enable quarantine notifications and choose their frequency. The frequency can be overwritten by each user individually in their SSQ. Notifications are only sent for quarantines with `canView: true`.

   ```yaml shared/guarded_tenants.yml highlight={4-6} theme={null}
   tenants:
     - name: xorlab
       quarantine:
         notifications:
           enabled: true
           frequency: DAILY
           ## - NEVER: Sending of a quarantine notification is disabled for the user.
           ## - IMMEDIATELY: Sending of a quarantine notification happens immediately if a message for the user is quarantined.
           ## - DAILY: Sending the quarantine notification every day at the time specified in the dailyCron option.
           ## - WEEKLY: Sending the quarantine notification once a week at the time specified in the weeklyCron option.
   ```

   <Accordion title="Daily/Weekly notifications">
     You can adjust the frequency and timing of daily and weekly digest notifications like this:

     ```yaml shared/guarded_tenants.yml theme={null}
     tenants:
       - name: xorlab
         quarantine:
           notifications:
             enabled: true
             frequency: DAILY
           digest:
              ## The maximum number of recent quarantined messages mentioned in the daily/weekly digest email.
              mentionedEntries: 10
              ## Daily digest frequency. It must be written in the following format (default: send daily digest at the beginning of each workday):
              ## .------------------ second (0 - 59)
              ## | .---------------- minute (0 - 59)
              ## | | .-------------- hour (0 - 23)
              ## | | | .------------ day of month (must be a *)
              ## | | | | .---------- month (must be a *)
              ## | | | | | .-------- period of week (e.g., MON-FRI)
              ## * * * * * *
              ## Note that sending daily digest emails is not instantaneous and takes at least `shippingTimespanMinutes`
              dailyCron: "0 0 0 * * MON-FRI"
              ## Weekly digest frequency. It must be written in the following format (default: send weekly digest at the beginning of each work weak):
              ## .------------------ second (0 - 59)
              ## | .---------------- minute (0 - 59)
              ## | | .-------------- hour (0 - 23)
              ## | | | .------------ day of month (must be a *)
              ## | | | | .---------- month (must be a *)
              ## | | | | | .-------- day of week (MON, TUE, WED, THU, FRI, SAT, or SUN)
              ## * * * * * *
              ## Note that sending weekly digest emails is not instantaneous and takes at least `shippingTimespanMinutes`
              weeklyCron: "0 0 0 * * MON"
              ## Default time zone of this tenant.
              zoneId: "Europe/Zurich"
     ```
   </Accordion>

   <Accordion title="More information">
     The frequency above is the global default. Users can change it in their own SSQ.
     **Shared mailboxes**: Every user with access to a mailbox can configure the notification settings for that specific mailbox. The notification setting per mailbox is global, so for shared mailboxes the setting is changeable by every user that has SSQ access to that mailbox.
     **Reset frequency**: As soon as a user logged in to their SSQ the first time, they will not be affected anymore when you change the `frequency`. Therefore, to reset the notification frequency of all users, you can use these database queries:

     ```sql theme={null}
     SELECT * FROM xcc.user_settings_quarantine_notification;
     UPDATE xcc.user_settings_quarantine_notification SET frequency='IMMEDIATELY' WHERE frequency='NEVER';
     ```
   </Accordion>
8. Click **Publish**. The new configuration becomes active within about one minute.

Now the SSQ is setup and ready to be used.

## Configure additional SSQ features

We recommend to additionally configure the following features to provide the best SSQ experience.

<CardGroup>
  <Card title="Attachment Airlock" icon="lock" href="/latest/ssq-attachment-airlock">
    Quarantine all encrypted attachments that cannot be decrypted. The user can enter the password in the SSQ to release it.
  </Card>

  <Card title="Request Release" icon="envelope-open-text" href="/latest/ssq-request-release">
    Allow users to request the release of emails in the SSQ.
  </Card>

  <Card title="Shared Mailboxes" icon="share-nodes" href="/latest/ssq-shared-mailboxes">
    Allow users to access shared mailboxes in the SSQ.
  </Card>
</CardGroup>

## Multi-Tenancy

Every `guarded_tenants.yml` block on this page is set on a single tenant, so the setup above already works per tenant. Repeat it for each tenant, or share it via [Using Tenant Config Templates](/latest/multi-tenancy-configsets).


# Shared Mailboxes Overview
Source: https://docs.xorlab.com/latest/ssq-shared-mailboxes

Give Self-Service Quarantine users access to shared mailboxes, with auto-login as the recommended approach.

[Auto-Login](/latest/authentication-auto-login-link) provides a seamless experience and requires no further integration.

<Warning>
  **Prerequisites**

  * Complete [Set Up the SSQ](/latest/ssq-setup)
</Warning>

Below you can find an overview over all supported implementations:

<CardGroup>
  <Card title="Preferred: Auto-Login" icon="link" href="/latest/authentication-auto-login-link">
    By enabling the Auto-Login feature, users can access their SSQ by just clicking on the link in the quarantine notifications. This includes shared mailboxes. No SAML, LDAP or similar authentication is required.
  </Card>

  <Card title="Shared Mailbox Script for M365" icon="envelope-open-text" href="/latest/m365-shared-mailbox-script">
    If the Auto-Login feature cannot be used and you have M365, you can rely on a M365 powershell script to gather the shared mailbox access information and provide them to xorlab.
  </Card>

  <Card title="Manual Assignment" icon="vial">
    For testing purposes, you can give a user temporarily access to some shared mailboxes.

    <Accordion title="Instructions">
      1. Find out how the user test user logs into xorlab (either SAML, LDAP or via local password file)
      2. For [SAML](/latest/authentication-saml) and [LDAP](/latest/authentication-ldap), configure the `emails` attribute inside `auth.yml` such that it contains all accessible mailboxes. Provide that information via the IDP respectively Active Directory.
      3. For [Password File](/latest/authentication-with-a-password-file), configure the `emails` attribute in `passwordFile.yml` to contain the accessible shared mailboxes.
    </Accordion>
  </Card>
</CardGroup>


# Tags
Source: https://docs.xorlab.com/latest/tags

The hashtags xorlab adds to processed emails from content, metadata, and email history, and where to find them.

xorlab Security Platform enriches records of a processed email with information it extracts from the email content, metadata, and existing email history. Enrichment happens in the form of *hashtags*. You can access the tag information in the record details or, if integrated, in your Security Information and Event Management (SIEM). Use [Search](/latest/search) to find emails tagged with certain keywords or to aggregate similar emails (e.g., belonging to the same marketing or phishing campaign).

You can make xorlab Security Platform add custom tags (please see [Custom Alerts](/latest/custom-alerts)) to the processed email records.

## Aggregation examples

`#inc #highrisk #untrusted #newsender #newdomain #exposedhvt`<br />
Aggregates all incoming emails from untrusted senders, from which we have not yet received any email, to a high-value target and which have a high-risk score and contain a link to a domain not yet observed in email communication.

`#inc #highrisk #untrusted #newsender #cloudstorage`<br />
Aggregates all incoming emails from untrusted senders, from which we have not yet received any email, which have a high-risk score and contain a link to a cloud storage service.

`#inc #highrisk #untrusted #newsender #shortenednolocalreputation`<br />
Aggregates all incoming emails from untrusted senders, from which we have not yet received any email, which have a high-risk score and contain a shortened link to a URL that has no significance to your organization.

`#inc #untrusted #newfiletype #exposedhvt`<br />
Aggregates all incoming emails from untrusted senders to a high-value target, which contain an attachment whose file type has never been observed in your organization’s email communication.

`#out #encryptedfile #untrusted`<br />
Aggregates all outgoing emails to untrusted recipients which contain an encrypted attachment.

`#inc #trusted #dangerousvbascript`<br />
Aggregates all incoming emails from trusted senders that contain a Microsoft Office document that contains a VBA script with high-risk functions.

`#pdf #cfiviolation`<br />
Aggregates all emails with a PDF attachment that triggered a control flow integrity violation in the Sandbox.

## Tag reference

Here is a list of all keyword tags that are used to enrich email records.

### General classification tags

Use caution when using verdict classification tags in campaigns, as some of the tags are applied after the campaigns are evaluated (e.g. `#internal` and `#benign`). This can result in discrepancies between search queries that match emails and campaigns that modify email verdicts.

| Tag | Description |
| - | - |
| `#banner` | The email was delivered with a contextual banner |
| `#bec` | The email is classified as business email compromise (BEC) |
| `#benign` | The email is classified as benign |
| `#bulk` | The email was sent from a bulk email sender |
| `#crm` | The email was sent from a CRM service, e.g., Salesforce |
| `#eopmarkedspam` | The email was marked as spam by Microsoft Exchange Online Protection |
| `#external` | The email was sent by someone who is not a member of your organization. No other classification matches. Not to be confused with `#ext` |
| `#extortion` | The email is classified as extortion |
| `#filter` | The email or one of its attachments violates either one of the built-in or custom security policies |
| `#impersonation` | The sender of the email impersonates a known party. This could be an employee, a business partner, or a popular service |
| `#internal` | The email was sent by a member of your organization to one or more members of your organization. No other classification matches. Not to be confused with `#int` |
| `#marketing` | The email is classified as email marketing |
| `#malware` | The email contains malware. |
| `#newsletter` | The email is classified as a newsletter |
| `#phishing` or `#potentialphishing` | The email is classified as phishing. With lower confidence, `#potentialphishing` is used |
| `#poll` | The email was sent from a poll service, e.g., Doodle |
| `#popular` | The sending organization is a popular brand, e.g., Amazon |
| `#potentialextortion` | The email could be an attempt of extortion |
| `#potentialfraud` | The reported email could be an attempt to defraud the recipient |
| `#simulation` | The email belongs to a simulated employee awareness campaign. Please refer to [Phishing Simulation Tools](/latest/phishing-simulation-tools) to learn how to configure xorlab Security Platform to support your campaign tool |
| `#socialnetwork` | The email was sent from a social network service, e.g., LinkedIn |
| `#spam` | The email is classified as spam |
| `#survey` | The email was sent from a survey service, e.g., SurveyMonkey |
| `#suspectedintphishing` | The email could be an internal phishing attempt |
| `#suspectedintextortion` | The email looks like an internal extortion attempt |
| `#vipfraud` | The email is classified as a fraud attempt that appears to originate from the CEO or any other VIP in your organization. Please refer to [VIP Names](/latest/vips) for instructions on how to configure xorlab Security Platform to identify VIPs |

### Content classification tags

| Tag | Description |
| - | - |
| `#ahv` | A Swiss AHV (social security) number was found in the email or in one of the documents |
| `#alert` | Email alert (can have different reasons) |
| `#blacklisted` | A blacklisted object was found. This can be the sender, a file type, domain, or any other object that can be blacklisted |
| `#blacklistedexternal` | A blacklisted object based on an external blacklist was found |
| `#bodylt25words` | The email body contains less than 25 words |
| `#bodylt50words` | The email body contains less than 50 words |
| `#bodylt5words` | The email body contains less than 5 words |
| `#bodylt75words` | The email body contains less than 75 words |
| `#bodymadult` | The email body exactly matches at least one adult (erotic) keyword |
| `#bodymextortion` | The email body exactly matches at least one extortion keyword |
| `#bodymguardedemail` | The email body matches (by regex) at least one guarded email address |
| `#bodymkeyword` | The email body exactly matches at least one phishing keyword |
| `#bodymkeywords` | The email body exactly matches multiple phishing keywords |
| `#bodympartner` | The email body exactly matches at least one partner organization’s name |
| `#bodympopular` | The email body exactly matches at least one popular service |
| `#bodymspam` | The email body exactly matches at least one spam keyword |
| `#bodymurgency` | The email body exactly matches at least one urgency keyword |
| `#bodymvipfraud` | The email body exactly matches at least one VIP fraud keyword |
| `#bodystadult` | The email body is similar to an adult (erotic) keyword |
| `#bodystspam` | The email body consists of at least one word that is similar to (Levenstein match) a spam keyword |
| `#bouncemessage` | Looks like a bounce message |
| `#bulkahv` | A list of Swiss AHV (social security) numbers was found in the email or in one of the documents |
| `#bulkccnumber` | A list of credit card numbers was found in the email or in one of the documents |
| `#bulkiban` | A list of IBAN numbers was found in the email or in one of the documents |
| `#bulksensitivedata` | A list of sensitive data was found in the email or in one of the documents |
| `#bulkswissaddress` | A list of Swiss addresses was found in the email or in one of the documents |
| `#bulkswissphone` | A list of Swiss phone numbers was found in the email or in one of the documents |
| `#ccnumber` | A credit card number was found in the email or in one of the documents |
| `#compliance` | A compliance issue was found |
| `#confidential` | A document with classification confidential was found |
| `#cryptobitcoin` | A potential bitcoin address was found |
| `#cryptocurrency` | A potential cryptocurrency address was found |
| `#cryptodash` | A potential dash address was found |
| `#cryptoethereum` | A potential ethereum address was found |
| `#cryptomonero` | A potential monero address was found |
| `#cryptoripple` | A potential ripple address was found |
| `#cryptozcash` | A potential zcash address was found |
| `#cve_2017_0199` | A malware signature matched (specific CVE number) |
| `#cve_2017_8570` | A malware signature matched (specific CVE number) |
| `#cve_2017_8759` | A malware signature matched (specific CVE number) |
| `#cve_2018_0802` | A malware signature matched (specific CVE number) |
| `#cve_2018_4878` | A malware signature matched (specific CVE number) |
| `#cve_2023_23397` | A malware signature matched (specific CVE number) |
| `#cve_2024_4367` | A malware signature matched (specific CVE number) |
| `#cve_2025_8088` | A malware signature matched (specific CVE number) |
| `#cve_2026_21509` | A malware signature matched (specific CVE number) |
| `#dataloss` | A potential data loss issue was found (e.g., an encrypted file sent to a person not known to the organization) |
| `#emptymessage` | The message body is empty |
| `#emptysubject` | The email subject looks empty |
| `#encrypted` | The message looks encrypted |
| `#htmlinvisiblefont` | HTML email uses invisible font |
| `#htmlmessage` | HTML message |
| `#htmlmostlyimage` | HTML email consists of mostly an image |
| `#htmlobfuscated` | HTML message is obfuscated |
| `#htmlshortlinkimg` | HTML message is short with an image link |
| `#iban` | IBAN number found |
| `#largenumberindisplayname` | Display name contains a large number |
| `#largenumberinsubject` | Subject contains a large number |
| `#lookslikespam` | The email looks like spam (keywords) |
| `#lotsofmoney` | The email talks about lots of money |
| `#nosubject` | Email does not have a subject |
| `#onionlink` | Email contains link to the `.onion` domain (Tor) |
| `#privatekey` | Email contains a private key |
| `#pyzor` | Email hash matches Pyzor database |
| `#qrcode` | Email contains a QR code |
| `#qrcodelink` | Email contains a link extracted from a QR code |
| `#razor` | Email hash matches Razor database |
| `#sensitivedata` | Potentially sensitive data was found in the email body or within a file |
| `#subjectobfuscated` | Subject contains lots of punctuation characters. This hints at an attempt to bypass keyword detection |
| `#subjectcemoji` | Subject contains an emoji |
| `#subjectcguarded` | Subject contains (fuzzy matches) a guarded name, i.e., the organization’s name |
| `#subjectminvoice` | Subject exactly matches at least one of the invoice keywords |
| `#subjectckeyword` | Subject contains (fuzzy matches) a phishing keyword |
| `#subjectcpartner` | Subject contains (fuzzy matches) a partner organization’s name |
| `#subjectmpopular` | Subject exactly matches at least one popular service |
| `#subjectmrecipient` | Subject matches the local part of the recipient’s address |
| `#subjectmvipfraud` | Subject exactly matches at least one VIP fraud keyword |
| `#subjectstkeyword` | Subject is similar to a phishing keyword |
| `#svgembeddingtag` | SVG attachment contains embedded content, e.g. `<foreignObject>`, which may be used for obfuscation |
| `#svgscript` | SVG attachment that uses JavaScript |
| `#swissaddress` | A Swiss address was found in the email body or a file |
| `#swissphone` | A Swiss phone number was found in the email body or a file |
| `#txtext` | Text extraction was performed on a file |
| `#uppercase` | Email content consists mostly of uppercase letters |
| `#whitelisted` | A whitelisted object was found. This can be the sender, a file type or the file itself, domain, or any other object that can be whitelisted |
| `#zerowidthspace` | A zerowidth whitespace character was found. This is used in malicious emails to bypass text analysis |

### Attachment classification tags

| Tag | Description |
| - | - |
| `#activex` | ActiveX object in an Office document found |
| `#android` | Android file type found |
| `#archive` | Archive file type found |
| `#attachedinvoice` | The email has a PDF invoice attached |
| `#audio` | Audio file type found |
| `#cracked` | An encrypted file format was cracked |
| `#dangerousfiletype` | A potentially dangerous file type was found |
| `#dangerousvbascript` | A potentially dangerous VBA script was found. This tag is placed when an office document contains a macro that can execute code, write to the filesystem and/or start a network activity like opening a link. Examples could be creating a new file or modifying the registry. Note that the tag is not set when the file type is whitelisted in xorlab Security Platform |
| `#dangerousxlmscript` | A potentially dangerous XLM (Excel 4.0) script was found |
| `#dde` | An Office document using DDE was found |
| `#dmarcreport` | A DMARC report was found |
| `#document` | A document file format was found |
| `#eicar` | EICAR file signature matched |
| `#encryptedarchive` | An encrypted archive was found |
| `#encryptedfile` | An encrypted file format was found |
| `#encryptedoffice` | An encrypted Office file was found |
| `#excel` | An Excel file was found |
| `#excessivenesting` | An archive with excessive nesting was found |
| `#excessivenrofentries` | An archive with excessive number of entries was found |
| `#excessivesize` | An archive with excessive file size was found |
| `#executable` | An executable file format was found |
| `#extensionblacklisted` | File extension is blacklisted |
| `#extensionmismatch` | File extension mismatch |
| `#externalole` | An external OLE reference was found in an Office document |
| `#extractioncountexceeded` | Number of files extracted exceeded maximum threshold |
| `#file` | The email has a file attached |
| `#fileblacklisted` | File hash is blacklisted |
| `#filecontentmpopular` | The content of the attached file exactly matches at least one popular service |
| `#fileoutblacklisted` | File format output is blacklisted |
| `#filetypenoreputation` | File type has no reputation (never seen in trusted communication) |
| `#flash` | Flash object or file found |
| `#html` | HTML attachment found |
| `#htmldataurl` | HTML attachment contains data URL, which can be used to embed content |
| `#htmldownload` | HTML attachment contains a downloadable file |
| `#htmlembeddingtag` | HTML attachment contains embedded content, e.g., iframes, which may be used for obfuscation |
| `#htmlredirect` | HTML attachment contains a redirect to another page, which may be used for obfuscation |
| `#htmlscriptcharacterescapes` | HTML attachment contains JavaScript that uses a suspicious number of escape characters, which may be used for obfuscation |
| `#htmlscriptdocrewrite` | HTML attachment contains JavaScript that rewrites itself, which can be used for obfuscation |
| `#htmlscriptdownload` | HTML attachment contains JavaScript with a download attribute to get a payload |
| `#htmlscriptdecode` | HTML attachment contains JavaScript that uses decoding functions, which can be used for obfuscation |
| `#htmlscriptencodeddata` | HTML attachment contains JavaScript with encoded data, which can be used for obfuscation |
| `#htmlscriptpayload` | HTML attachment contains JavaScript that constructs a downloadable payload |
| `#htmlwithform` | HTML attachment contains a form tag |
| `#htmlwithscript` | HTML attachment contains a script tag |
| `#image` | Image file format found |
| `#ios` | iOS file format found |
| `#iso` | ISO file format found |
| `#largeimage` | An image larger than 1 MB was found |
| `#legacyarchive` | A legacy archive format was found (rar, ace, etc.) |
| `#macos` | A macOS file type was found |
| `#macrofilewhitelisted` | A whitelisted Office macro file was found |
| `#media` | Media file type found |
| `#newfiletype` | Never seen before file type found |
| `#office` | Office file format found |
| `#officeframe` | Office file uses external frames |
| `#officewebvideo` | Office file uses external web video |
| `#onlymediafiles` | All attachments are media files |
| `#ole` | OLE object in office file found |
| `#pdf` | PDF file format found |
| `#pdfanalysiserror` | Error during PDF static analysis occurred |
| `#powerpoint` | Powerpoint file format found |
| `#rtf` | RTF file format was found |
| `#rtfwithembeddedobject` | The RTF file contains an embedded object |
| `#script` | A script file format was found |
| `#shortcut` | Shortcut file format was found |
| `#unix` | Unix file type found |
| `#vbascript` | VBA script found |
| `#video` | Video file type found |
| `#xlmscript` | XLM (Excel 4.0) script found |
| `#whitelisted` | A whitelisted object was found. This can be the sender, a file type or file itself, domain, or any other object that can be whitelisted |
| `#windows` | Windows file type found |
| `#word` | Word file found |

### URL classification tags

| Tag | Description |
| - | - |
| `#15daysold` | A 15-day-old domain was found |
| `#180daysold` | A 180-day-old domain was found |
| `#1dayold` | A 1-day-old domain was found |
| `#30daysold` | A 30-day-old domain was found |
| `#365daysold` | A 365-day-old domain was found |
| `#5daysold` | A 5-day-old domain was found |
| `#90daysold` | A 90-day-old domain was found |
| `#badreputation` | A link with bad reputation was found |
| `#blacklisted` | A blacklisted object was found. This can be the sender, a file type, domain, or any other object that can be blacklisted |
| `#cloudstorage` | A cloud storage link was found |
| `#cmslink` | Link points to a CMS resource |
| `#contains` | One or more XcY tags (*X contains Y*) are present, e.g., `#displaynamecguarded` |
| `#dangerousfiletypeinpath` | The path of a link contains a potentially dangerous file type |
| `#displaytextmkeyword` | The display text of a link contains a phishing keyword |
| `#displaytextmspam` | The display text of a link contains a spam keyword |
| `#doclink` | A document contains links |
| `#domaincguarded` | Domain contains (fuzzy matches) a guarded name, i.e., the organization’s name |
| `#domainckeyword` | Domain contains (fuzzy matches) a phishing keyword |
| `#domaincpartner` | Domain contains (fuzzy matches) a partner organization’s name |
| `#domainstguarded` | Domain is similar to the organization’s name |
| `#domainstpartner` | Domain is similar to a partner’s name |
| `#doubleshortened` | Double shortened link found (shortener pointing to another shortener) |
| `#eachlinkmfrom` | All link domains match sender’s email domain |
| `#eachlinknonreputable` | All link domains have neither a local nor global reputation |
| `#eachlinkreputable` | All link domains have a global or local reputation |
| `#embeddedlink` | A potential embedded URL was found (in another URL) |
| `#emotet` | Typical Emotet structured link was found (possibly hosting malicious content) |
| `#guardeddomaininurl` | Guarded domain in URL found |
| `#guardednameinurl` | Guarded tenant name in URL found |
| `#idn` | A domain with a suspicious IDN character was found |
| `#iphost` | A link with an IP as host was found |
| `#link` | A link was found in the email |
| `#linkblacklisted` | A blacklisted link was found |
| `#linkblacklistedexternal` | A blacklisted link based on an external blacklist was found |
| `#linkckeyword` | Email contains a link which has a `PATH` or `QUERY` part containing (fuzzy matching) a phishing keyword |
| `#linkmfrom` | Email contains a link with a domain matching the sender’s email domain |
| `#linkmismatch` | A link display name mismatch was found |
| `#linkwithpathnolocalrep` | Email contains a link with no local reputation and having a `PATH` or `QUERY` part |
| `#matches` | One of the XmY rules matched, i.e., the organization’s name or a keyword, etc., matched a relevant string |
| `#mismatchnolocalreputation` | Link display name mismatches actual link and the actual link has no local reputation |
| `#mismatchnoreputation` | Link display name mismatches actual link and the actual link has no global reputation |
| `#newdomain` | Never seen before domain found |
| `#newtld` | Never seen before TLD found |
| `#noimgsrcreputation` | Email contains remote image sources and none of these have global or local reputation |
| `#nolocalreputation` | Email contains a link with a domain with no local reputation |
| `#noreputation` | Email contains a link with a domain with no global and no local reputation |
| `#onecommonphishinglink` | Email contains exactly one common phishing link |
| `#oneembeddedlink` | Email contains exactly one embedded link |
| `#onesuspiciouslink` | Email contains exactly one suspicious link |
| `#shortened` | Shortened link was found |
| `#shortenednolocalreputation` | Shortened link resolves to domain with no local reputation |
| `#shortenednoreputation` | Shortened link resolves to domain with no local and no global reputation |
| `#similar` | One of the XsY (*X is similar to Y*) similarity tags matched |
| `#subdomainproviderwithnolrep` | Found a link without local reputation that is below a subdomain provider |
| `#suspiciousidn` | A domain with a suspicious IDN character was found |
| `#tldnoreputation` | TLD has no reputation |
| `#veryyoungdomain` | A very young domain was found (younger than 30 days) |
| `#youngdomain` | A young domain was found (younger than 365 days) |

### Sandbox

| Tag | Description |
| - | - |
| `#cfiviolation` | Control-flow integrity violation in the Sandbox encountered |
| `#dana` | Sandbox analysis of a file performed |
| `#inline` | Sandbox analysis is performed inline **(deprecated since 6.21)** |
| `#ipaddress` | Sandbox observed a direct IP connection |
| `#networkactivity` | Suspicious network activity observed in the Sandbox |
| `#offline` | Sandbox analysis is performed offline **(deprecated since 6.21)** |
| `#runtime` | A suspicious activity in the Sandbox was observed |
| `#spawnsprocess` | A suspicious process is spawned in the Sandbox (from the client application) |
| `#systemfileio` | Suspicious file IO operation observed in the Sandbox |
| `#systemprocess` | A suspicious system process is spawned in the Sandbox |
| `#systemregistryio` | Suspicious registry IO operation observed in the Sandbox |

### Relationship tags

Relationship tags describe the quality of the relationship between your organization and the sending organization (or the receiving organization for outgoing emails). Tag assignment can be influenced by configuring the corresponding thresholds.

| Tag | Description |
| - | - |
| `#business` | The sender-recipient relationship has some significance but is yet too shallow to be considered trusted |
| `#hightrusted` | The sender-recipient relationship is considered highly trusted |
| `#lowtrusted` | The sender-recipient relationship is considered slightly trusted |
| `#mediumtrusted` | The sender-recipient relationship is considered medium trusted |
| `#nonreputable` | The domain the email was sent from has no significance in your organization. See also `#reputable` |
| `#partner` | The organization, which the sender is a member of, is considered a partner of your organization. Relationships with partner organizations score high on trust |
| `#personal` | The sender-recipient relationship is personal |
| `#recipientpartner` | The organization, which the recipient is a member of, is considered a partner of your organization. Relationships with partner organizations score high on trust |
| `#reputable` | The sending domain has a certain significance in your organization. See also `#nonreputable` |
| `#trusted` | The sender-recipient relationship is considered trusted |
| `#untrusted` | The sender-recipient relationship is not considered trusted |

### Sender-specific tags

| Tag | Description |
| - | - |
| `#15daysoldsender` | The sender domain was registered in the last 15 days |
| `#180daysoldsender` | The sender domain was registered in the last 180 days |
| `#1dayoldsender` | The sender domain was registered today |
| `#30daysoldsender` | The sender domain was registered in the last 30 days |
| `#365daysoldsender` | The sender domain was registered in the last 365 days |
| `#3rdpartycloudmailer` | The mail is sent via a 3rd party cloud mailer |
| `#5daysoldsender` | The sender domain was registered in the last 5 days |
| `#90daysoldsender` | The sender domain was registered in the last 90 days |
| `#addressindisplayname` | The display name of the email contains an email address |
| `#addressparsingerror` | An error occurred during address parsing. Indicates an uncommon address format |
| `#airlockwhitelisted` | The sender is on the Attachment Airlock whitelist |
| `#arcreject` | Authenticated Received Chain (ARC) checks failed |
| `#auth` | Email sender is authenticated |
| `#autogenerated` | The email is auto generated, e.g., by a script |
| `#bcconly` | No guarded email recipients in `TO/CC` |
| `#blacklisted` | A blacklisted object was found. This can be the sender, a file type, domain or any other object that can be blacklisted |
| `#bulk` | Sender seems to be a bulk email sender or we have seen a lot of incoming and no outgoing emails to that sender for some time now |
| `#business` | The sender and recipient have a business relationship |
| `#cloudmailer` | The sender is a known cloud service for sending emails |
| `#cloudmailerrcvdonly` | The sender is a known cloud service for sending emails, based on information found in the `received` headers |
| `#cloudstoragesender` | Sender is a cloud storage service |
| `#contactform` | Sender is a contact form |
| `#contains` | One or more XcY tags (*X contains Y*) are present like `#displaynamecguarded` |
| `#displaynamecemoji` | Displayname contains an emoji |
| `#displaynamecguarded` | Displayname contains (fuzzy matches) a guarded name, i.e., the organization’s name |
| `#displaynameckeyword` | Displayname contains (fuzzy matches) a phishing keyword |
| `#displaynamecpartner` | Displayname contains (fuzzy matches) a partner organization’s name |
| `#displaynamecpopular` | Displayname contains (fuzzy matches) a popular service name |
| `#displaynamecvip` | Displayname contains (fuzzy matches) a VIP's name |
| `#displaynamemguarded` | Displayname exactly matches the organization’s name |
| `#displaynamemkeyword` | Displayname exactly matches at least one phishing keyword |
| `#displaynamempartner` | Displayname exactly matches at least one partner name |
| `#displaynamempopular` | Displayname exactly matches at least one popular service |
| `#displaynamestguarded` | Displayname is similar to the organization’s name |
| `#displaynamestkeyword` | Displayname is similar to a phishing keyword |
| `#displaynamestpartner` | Displayname is similar to a partner’s name |
| `#displaynamestpopular` | Displayname is similar to a popular service |
| `#displaynamestvip` | Displayname is similar to a VIP’s name |
| `#domainfirstcontact` | Sending domain first time seen |
| `#domainnodeliver` | No email was ever delivered from the sending domain |
| `#domainonlyinbound` | Domain only sends inbound emails |
| `#dkimfromsigned` | The `from` field is DKIM signed |
| `#dkiminvalid` | No DKIM verification succeeded and the found DKIM signature is invalid |
| `#dkimfail`, `#dkimneutral`, `#dkimpolicy`, `#dkimpermerror`, `#dkimtemperror` | No DKIM verification succeeded and one of the results `fail`, `neutral`, `policy`, `permerror`, or `temperror` was found |
| `#dynamicrelay` | One of the MTAs in the headers has a dynamic IP address |
| `#educationsender` | The sender’s email address is from an education domain |
| `#etrust` | Sender is in extended trust circle. The extended trust circle contains all domains which locally have a high reputation. xorlab Security Platform learns this based on the observed mail flow |
| `#fake` | Email address seems fake (in `displayname`) |
| `#fakeguarded` | Guarded email is faked |
| `#fakepartner` | Partner email is faked |
| `#fakepopular` | Popular email is faked |
| `#fakereply` | Email is a faked reply |
| `#forged` | Email sender is forged |
| `#forgedfreemail` | Forged freemail |
| `#forgedguarded` | Forged guarded email |
| `#forgedpartner` | Forged partner email |
| `#forgedpopular` | Forged popular email |
| `#freemail` | Freemail sender |
| `#freemailforgedreplyto` | Freemail address in `reply to` found (but not in `from`) |
| `#fromsdiffer` | Envelope `from` and header `from` differ |
| `#mailerdaemon` | Email comes from a mailer daemon address |
| `#mailinglist` | Sender seems a mailing list |
| `#marketing` | Marketing email |
| `#matches` | One of the XmY (*X matches Y*) rules matched, i.e., the organization’s name or a keyword, etc., matched a relevant string |
| `#mtaauth` | MTA is whitelisted |
| `#mtawlhigh` | Sending MTA is on highly reputable whitelist (high) |
| `#mtawlmedium` | Sending MTA is on reputable whitelist (medium) |
| `#newsender` | Never seen before sender (same as `#senderfirstcontact`) |
| `#newsendertld` | Never seen before sender TLD found |
| `#newsletter` | Email seems to be a newsletter |
| `#noauth` | Email sender is not authentic |
| `#nonreputable` | Email sender domain is non-reputable |
| `#otrust` | Sender has organizational trust |
| `#partner` | Sender is a partner (at least the domain) |
| `#partnerwithoutauth` | Sender is a partner but has no authentication (might be forged or the email setup does not allow for authentication) |
| `#personal` | Email seems to be a personal email |
| `#phpsender` | Sender seems a PHP script |
| `#poll` | Email comes from an online poll service (e.g., Doodle) |
| `#popular` | Sender seems to be a popular service |
| `#postmaster` | Email comes from a postmaster address |
| `#predatorypublisher` | Sender is a predatory publishing/journal sender; usually indicating academic scam |
| `#ptrust` | Sender has personal trust |
| `#replytonotfrom` | `Reply-To` domain does not match `From` domain |
| `#reputable` | Sender domain is reputable |
| `#senderblacklisted` | Sender is blacklisted |
| `#senderblacklistedexternal` | Sender is blacklisted based on an external blacklist |
| `#sendercguarded` | Sender mail address contains the organization’s name |
| `#senderckeyword` | Sender mail address exactly matches at least one phishing keyword |
| `#sendercpartner` | Sender mail address contains a partner’s name |
| `#sendercpopular` | Sender mail address contains a popular service’s name |
| `#senderfirstcontact` | Sender first time seen |
| `#senderhascctld` | Sender’s TLD is a country code TLD |
| `#senderisolated` | A message from the same email address has previously been isolated |
| `#sendernodeliver` | No email from the sender was delivered before |
| `#senderneverbenign` | Sender’s domain was never seen as sender or recipient in a delivered email—except for freemail, where the sender email address was never seen as a sender or recipient |
| `#senderonlyinbound` | Sender only seen in inbound emails |
| `#senderreleased` | A message from the same email address has previously been released from quarantine |
| `#senderseenasrecipient` | Sender’s email address was previously seen as a recipient |
| `#senderseenbefore` | Sender’s email address was previously seen as a sender |
| `#senderstguarded` | Sender’s mail address is similar to the organization’s name |
| `#senderstpartner` | Sender’s mail address is similar to a partner’s name |
| `#senderstpopular` | Sender’s mail address is similar to a popular service’s name |
| `#sendersuspicious` | Sender’s MTA is suspicious due to its reputation and past behavior |
| `#sendertldnoreputation` | Sender’s TLD has no reputation |
| `#senderwhitelisted` | Sender is whitelisted |
| `#similar` | One of the XsY (*X is similar to Y*) similarity tags matched |
| `#socialnetwork` | Email comes from a social network (e.g., Facebook, LinkedIn, etc.) |
| `#spfehlofail` | SPF EHLO fail |
| `#spfehlosoftfail` | SPF EHLO soft fail |
| `#spffail` | SPF fail |
| `#spfneutral` | SPF result neutral |
| `#spfnone` | No SPF record found |
| `#spfpass` | SPF check passed |
| `#spfpermerror` | SPF permanent error |
| `#spfsoftfail` | SPF soft fail |
| `#spftemperror` | SPF temp error |
| `#trusted` | Sender is trusted |
| `#trustedmta` | MTA is trusted |
| `#trustednoauth` | Sender domain would be trusted but this mail is not authenticated. Either a trusted sender’s email setup is wrong or the sender is impersonating a trusted party |
| `#trustoverride` | The trust relationship was overwritten on purpose. This has to be done by configuration and allows to lower e.g., the trust level of a partner manually |
| `#untrusted` | Sender is not trusted (or trust score is very low) |
| `#veryyoungsender` | Sender is very young (younger than 30 days) |
| `#whitelisted` | A whitelisted object was found. This can be the sender, a file type or file itself, domain, or any other object that can be whitelisted |
| `#wwwdata` | Sender is a webserver |
| `#xorlab` | This mail is part of a breach simulation by xorlab |
| `#youngsender` | Sender domain is young (younger than 365 days) |

### Recipient-specific tags

| Tag | Description |
| - | - |
| `#educationrcpt` | The recipient’s email address is from an education domain |
| `#exposedaccount` | The recipient is listed as an exposed account. Examples for exposed accounts are `contact@yourcompany.com`, `media@yourcompany.com`, or any other email address listed on your website or public sources |
| `#exposedhvt` | The recipient is considered a high-value target. Examples for high-value targets are members of the finance department or the Executive Assistant of your CEO |
| `#exposedpubliccontact` | The recipient is listed as an exposed public contact and should be subject to less aggressive filtering. This can be useful for certain public mailboxes where you expect a lot of suspicious or malformed emails |
| `#freemailrcpt` | Freemail recipient |
| `#recipientdisplaynamecvip` | A recipient’s displayname contains (fuzzy matches) a VIP’s name. |
| `#recipientdropped` | Email dropped because all guarded recipients are on a drop list |
| `#recipientpartner` | Recipient is a partner organization |
| `#recipientwhitelisted` | Recipient is whitelisted |

<Note>
  The following tags are only available on outgoing emails.
</Note>

| Tag | Description |
| - | - |
| `#rcptunknown` | The recipient of an outgoing email is unknown to the organization (meaning that the recipient does not appear in the organization’s email history) |
| `#rcptunknowntosender` | The recipient of an outgoing email is unknown to the sender (meaning that the recipient does not appear in the sender’s email history) |

### Mail flow tags

Mail flow tags indicate if an email was sent or received by your organization, exchanged internally, or processed on behalf of a third party. Please see [Search](/latest/search#direction).

| Tag | Description |
| - | - |
| `#ext` | Neither the sender nor the recipient is a member of your organization. This can happen if you process emails on behalf of a third party, e.g., by hosting a third-party service. Not to be confused with `#external` |
| `#inc` | The email was sent by an external party to your organization |
| `#int` | The email was sent by a member of your organization to one or more members of your organization. Not to be confused with `#internal` |
| `#out` | The email was sent by a member of your organization to an external party |
| `#forwarded` | The email was forwarded internally by a member of your organization |
| `#unknowntenant` | The email could not be assigned to a tenant. |

### Decision tags

Decision tags indicate if an email was delivered, sanitized, or quarantined after processing.

| Tag | Description |
| - | - |
| `#attachmenttransformed` | An attachment was removed or replaced before delivery |
| `#deliver` | The email was delivered to its recipients |
| `#quarantine` | The email was quarantined<br />**Note that this tag can’t be used in campaigns** |
| `#subjectrewrite` | The email was delivered with a subject prefix, e.g., `[SPAM]`<br />**Note that this tag can’t be used in campaigns** |

## Risk scores

### Overall risk

| Tag | Description |
| - | - |
| `#highrisk` | The email has a high overall risk score |
| `#mediumrisk` | The email has a medium overall risk score |
| `#lowrisk` | The email has a low overall risk score |
| `#verylowrisk` | Overall risk score is very low |

### Phishing risk

| Tag | Description |
| - | - |
| `#vhprisk` | The phishing risk score is very high |
| `#hprisk` | The email has a high phishing risk score |
| `#mprisk` | The email has a medium phishing risk score |
| `#lprisk` | The email has a low phishing risk score |

### Spam risk

| Tag | Description |
| - | - |
| `#hsrisk` | The email has a high spam risk score |
| `#msrisk` | The email has a medium spam risk score |
| `#lsrisk` | The email has a low spam risk score |

The spam risk of an email is influenced by a variety of factors. Two of them are the scores calculated by *SpamAssassin* and *Rspamd*. The following tags describe them:

| Tag | Description |
| - | - |
| `#highscore` | SpamAssassin calculated a high spam score. The higher the score, the more likely the email is spam |
| `#mediumscore` | SpamAssassin calculated a medium spam score |
| `#lowscore` | SpamAssassin calculated a low overall spam score. The lower the score, the less likely the email is spam |
| `#negscore` | SpamAssassin calculated a negative spam score. The lower the score, the less likely the email is spam |
| `#missingscore` | The spam score is missing. This indicates a problem with spam analysis |
| `#hbayes` | Bayes spam probability is high |
| `#mbayes` | Bayes spam probability is medium |
| `#lbayes` | Bayes spam probability is low |
| `#rspamd` | Rspamd classified the email as spam |
| `#rsdhighscore` | Rspamd calculated a high spam score. The higher the score, the more likely the email is spam |
| `#rsdmediumscore` | Rspamd calculated a medium spam score |
| `#rsdlowscore` | Rspamd calculated a low spam score. The lower the score, the less likely the email is spam |
| `#rsdnegscore` | Rspamd calculated a negative spam score |

## User reports

| Tag | Description |
| - | - |
| `#acksent` | The reporting user received an acknowledgment |
| `#analystfeedback` | The analyst is required to provide the user with a feedback |
| `#autofeedback` | The reporting user received an automatically generated feedback |
| `#feedback` | The email is an automatically generated email originating from xorlab Security Platform |
| `#highpriority` | The reported email is a high priority incident |
| `#lowpriority` | The reported email is a low priority incident |
| `#mediumpriority` | The reported email is a medium priority incident |
| `#reported` | The email was reported by a user |
| `#reportedasjunk` | The email was reported as **Junk** by a user |
| `#reportedasnotjunk` | The email was reported as **Not Junk** by a user |
| `#reportedasphishing` | The email was reported as **Phishing**  by a user |
| `#fileanalysis` | The file was submitted for analysis with the File Upload tool |
| `#simulation` | The email is part of a simulated security awareness campaign |

## Reporting misclassification

| Tag | Description |
| - | - |
| `#misclassified` | The message or case was reported as misclassification |


# Terminology
Source: https://docs.xorlab.com/latest/terminology

Glossary of every xorlab product, component, and concept name, with the alternative names each one is also known by.

This page is the canonical source for xorlab vocabulary.

Terms are listed alphabetically.

## Abuse Mailbox Automation (AMA)

The service of xorlab Security Platform that analyzes, handles, and automates the processing of user-reported emails. Reported emails are grouped into cases, enriched with xorlab's analysis, and can be resolved automatically. See [Handle the Abuse Mailbox](/latest/abuse-mailbox).

**Also known as:** Abuse Mailbox.

## Attachment Airlock

A feature that holds back emails with encrypted attachments in the Self-Service Quarantine until the user supplies the password. The email is then re-analyzed. Only attachments that cannot be decrypted by other means are affected. Emails held this way receive the `encrypted` verdict. See [Enable Attachment Airlock](/latest/ssq-attachment-airlock).

## Blacklist

A list of senders, domains, links, or file properties that you maintain to force emails matching them to be treated as malicious. Emails matched by a blacklist receive the Blacklist verdict. See [Blacklists](/latest/blacklists).

**Also known as:** blocklist. xorlab Security Platform uses the term Blacklist, so this documentation does too.

**Not to be confused with:** third-party DNS blocklists such as Spamhaus, which are an unrelated external service.

## Campaign

An analyst-defined policy that turns a search query into a detection rule, overriding the built-in detection for exactly the emails that match. Campaigns are used to respond to undetected threats, recurring false positives, and greymail. See [Using Campaigns](/latest/campaigns).

## Case

A user-reported email as it appears in the Abuse Mailbox, together with its analysis, status, and resolution. Analysts resolve a case by assigning a verdict. See [Handle the Abuse Mailbox](/latest/abuse-mailbox).

**Not to be confused with:** Case Isolation, which is a separate feature.

## Case Isolation

A feature that removes already-delivered emails from a user's mailbox through the Microsoft Graph API. Once enabled, an **Isolate** button appears in the detail view of every email. See [Activate Case Isolation](/latest/m365-case-isolation).

## Confidence

The certainty level attached to a verdict: high, medium, or low. Confidence takes precedence over specificity when xorlab determines the final verdict of an email, and it controls which action is taken. See [Verdict precedence](/latest/verdicts#verdict-precedence).

## Config Set

A reusable configuration template defined in `guarded_tenants.yml` that can be applied to any number of tenants, so shared settings do not have to be repeated per tenant. See [Using Tenant Config Templates](/latest/multi-tenancy-configsets).

## Contextual Banners

Warnings inserted into the body of an email to highlight a specific risk that xorlab detected, such as low sender trust or a suspicious attachment. They are surfaced through mail flow rules in Exchange. See [Enable Contextual Banners](/latest/detection-contextual-banners).

## Email Direction

The relationship of an email to your guarded domains. Every email is assigned exactly one of four directions: **Incoming**, **Outgoing**, **Internal**, or **External**, see [Email Direction](/latest/email-direction).

**Not to be confused with:** the External verdict, which is unrelated to the External direction.

## Expert Editor

The administration tool inside XCC that gives full access to all xorlab configuration files. See [Expert Editor](/latest/expert-editor).

## External Service

A service that the xorlab MTAs or the XCC call over the network while analyzing an email, rather than doing the work locally. External means external to those two components, not outside xorlab: the Sandbox, Tika, xorlab ML, NLU, and xorlab xCloud are all operated by xorlab. See [Data Flow Overview](/latest/data-flow-overview).

## Global Reputation

xorlab's relevance scoring for email content that is identical across all xorlab customers, rather than learned from a single organization's traffic. See [Local Reputation](/latest/concepts-local-reputation).

**Not to be confused with:** Local Reputation, which xorlab learns from your own email traffic and which is specific to your organization.

## Guarded Domains

List of domains and subdomains which belong to your organization or the tenants you mention. Email filtering will only be applied to recipients in these domains. For example, the guarded domains for xorlab are `xorlab.com` and `xorlab.ch`. See [Before You Begin](/latest/before-begin-integration#configure-your-guarded-domains).

**Not to be confused with:** Guarded Tenants, which names the tenants themselves rather than their domains.

## Guarded Tenants

The tenants configured in `guarded_tenants.yml`, each with its own domains, routing, and settings. See [Configure Domains and Routing](/latest/multi-tenancy-domain-and-routing).

## Inbound Email Security

The service of xorlab Security Platform that protects your organization from malicious incoming emails. It is the core of the platform. See [Feature Overview](/latest/feature-overview#inbound-email-security).

## Inline Mode

The operating mode in which xorlab sits in the mail flow and actively filters emails, forwarding them after processing. This is the mode used whenever xorlab provides Inbound Email Security. See [Inline and Monitoring Mode](/latest/inline-and-monitoring-mode).

## Learning Phase

The initial period during which the relationship model builds up before it can be relied on. Detection is normally disabled during this phase, and enabled manually afterward. See [Learning phase](/latest/concepts-relationship#learning-phase).

## Lists

The built-in lists in XCC that adjust platform behavior on the fly, covering blacklists, whitelists, VIPs, trusted senders, fraud keywords, and more. See [Lists](/latest/lists).

## Local Reputation

xorlab's continuously learned model of which email content — domains, file types, and similar — is common in your organization. It is used to distinguish relevant emails from potentially malicious ones. See [Local Reputation](/latest/concepts-local-reputation).

## Misclassification

An email that xorlab classified incorrectly: a benign email that was quarantined (false positive) or a malicious email that was delivered (false negative). Misclassifications can be reported to xorlab to improve detection. See [Report a Misclassification](/latest/reporting-misclassification).

## Monitoring Mode

The operating mode in which xorlab sits out-of-band of the mail flow and cannot intervene in it. Emails usually arrive as an additional BCC recipient and are dropped after processing, but detection and the configured actions still run, so an email can still all different decisions like for example `QUARANTINED` — what is held back is xorlab's own copy. See [Decisions and quarantine in Monitoring mode](/latest/inline-and-monitoring-mode#decisions-and-quarantine-in-monitoring-mode).

## MTA GUI

The technical management interface of an xorlab MTA, reachable on port 8443. This is only available for on-premises deployments. See [How to connect to MTA GUI](/latest/troubleshooting#how-to-connect-to-mta-gui).

**Not to be confused with:** the XCC web interface, which is the main interface for analysts and administrators and is a different application.

## Quarantine

A holding area for emails that xorlab did not deliver. Quarantines are named by category — for example Filter, Malware, Phishing, or Spam — and each has its own retention and release permissions. See [Change Quarantine Retention](/latest/data-retention-quarantine).

## Relationship

xorlab's model of the email communication patterns in your organization, built up continuously and automatically. Each email is assigned a relationship value between 0 and 100, derived from how much back-and-forth communication has been seen with the sender. It is a key indicator for the detection engine. See [Relationship](/latest/concepts-relationship).

**Also known as:** trust model. The relationship value is also called the trust score, and is what the `trust` score matches in [Search](/latest/search#scores).

## Reported Email

An email that an employee submitted to the security team as suspicious, using the reporting button or the abuse mailbox address. Reported emails appear in the Abuse Mailbox as cases. See [Handle the Abuse Mailbox](/latest/abuse-mailbox).

## Retrospective Email Scanning

A one-time onboarding feature that imports past emails from M365 and pushes them through xorlab for analysis, so trust and reputation build up without waiting for live traffic. See [Retrospective Email Scanning](/latest/m365-retrospective-email-scanning).

## Rule Profile

A named set of rule parameters that switches xorlab between operating modes — Inline or Monitoring, Toothless or active protection — without editing individual rules. Profiles are assigned per tenant in `guarded_tenants.yml`. See [Rule Profiles](/latest/rule-profiles).

## Self-Service Quarantine (SSQ)

The service of xorlab Security Platform that lets end-users view, release, and manage their own quarantined emails without involving the security team. It is abbreviated as SSQ, which is the form used throughout this documentation after the first mention on a page. See [SSQ Overview](/latest/ssq-overview).

## Tags

Hashtags that xorlab attaches to every processed email, describing what it extracted from the content, metadata, and communication history — for example `#untrusted` or `#newsender`. Tags are the main building block for searches and campaigns. See [Tags](/latest/tags).

## Tenant

An organizational unit within one xorlab Security Platform instance, with its own guarded domains, routing, quarantines, and settings. A deployment serving several tenants is a multi-tenant deployment. See [Multi-Tenancy Overview](/latest/multi-tenancy-overview).

## Toothless Mode

An operating mode in which xorlab delivers all emails and only records the actions it would have taken. It is used for evaluation and during the learning phase. See [Toothless](/latest/rule-profiles#toothless).

## Topic Detection

The classification of what an email is about — for example an invoice or an account issue — based on its subject, body, and attachments. It is powered by xorlab NLU and the results are searchable. See [Topic Detection](/latest/topic-detection).

## Trusted MTA

An internal mail server whose `Received` headers xorlab treats as authentic. Declaring trusted MTAs is required for correct SPF evaluation when xorlab is not the border gateway. See [Trusted MTAs](/latest/trusted-mtas).

## Verdict

The single final classification xorlab assigns to every email, ranging from benign to malicious. Together with its confidence, the verdict determines the action taken on the email. Verdicts are also used by analysts to resolve reported emails. See [List of Verdicts](/latest/verdicts).

## VIP

A member of senior management, the board, or another well-known person registered in xorlab so that impersonation attempts against them are detected more aggressively. See [VIP Names](/latest/vips).

## Whitelist

A list of senders, domains, or infrastructure that you maintain to exempt matching emails from filtering. See [Whitelists](/latest/whitelists).

**Also known as:** allowlist. xorlab Security Platform uses the term Whitelist, so this documentation does too.

## xorlab Control Center (XCC)

The component of xorlab Security Platform that provides the web interface for analysts and administrators. It maintains the configuration as well as the shared state for the xorlab MTAs (for example, the quarantines). It is referred to as XCC everywhere else in this documentation. There is only one instance per xorlab Security Platform.

**Not to be confused with:** the MTA GUI, which is a separate interface on the MTAs.

## xorlab ML

The external machine learning service that xorlab queries to improve message classification. It receives only non-identifying indicators, never message bodies, and is active by default. See [Data Flow Overview](/latest/data-flow-overview#xorlab-ml).

## xorlab MTA

The component of xorlab Security Platform that is responsible for processing and forwarding emails. It is lightweight and stateless. Usually, multiple xorlab MTAs are set up to guarantee zero-downtime and fail-safe operations.

## xorlab Natural Language Understanding (NLU)

Denotes a set of services in xorlab Security Platform that are responsible for understanding of email content, such as what topics are discussed in an email. See [xorlab NLU](/latest/xorlab-nlu).

## xorlab SaaS

The deployment option in which xorlab hosts and operates xorlab Security Platform, as opposed to an on-premises deployment on the customer’s own virtual infrastructure. It determines who is responsible for upgrades, restarts, and data retention settings. See [What Integrating xorlab Involves](/latest/admin-essentials).

**Also known as:** xorlab Security Platform (SaaS).

**Not to be confused with:** xorlab xCloud, which is an external service both deployment options use.

## xorlab Sandbox (DANA)

The component of xorlab Security Platform that is responsible for the sandbox analysis of email attachments. In on-premises deployments it is also referred to as DANA, which is the name used for the appliance, its containers, and its configuration files. See [xorlab Sandbox (DANA)](/latest/xorlab-sandbox).

**Also known as:** Dynamic Analysis, DANA.

## xorlab Security Platform

The complete email defense platform by xorlab. It is the name of the product. It is also abbreviated by just "xorlab".

## xorlab Tika

The external service that extracts text and URLs from attachments, including OCR, to improve classification. It should not be disabled, as it is critical for email classification. See [xorlab Tika](/latest/xorlab-tika).

## xorlab xCloud

The external service that xorlab queries for global information about domains, URLs, and IP addresses. It is active by default and cannot be disabled. See [Data Flow Overview](/latest/data-flow-overview#xorlab-xcloud).


# Use Topics for Searches and Campaigns
Source: https://docs.xorlab.com/latest/topic-detection

Filter on what a message is about, such as invoices, credentials, or package delivery, rather than on its sender or headers.

xorlab leverages Natural Language Understanding (NLU) to analyze email content and identify specific topics within the subject, body, and attachments. These topics can be accessed directly via the search.

The set of detectable topics will continue to expand over time as xorlab refines its models and introduces new capabilities.

The following topics are currently supported:

| Topic | Description |
| - | - |
| `accountissue` | Identifies text related to user account issues, such as password resets, password expirations, and account (de-)activations. |
| `sexualcontent` | Detects sexual content, including explicit language, pornographic material, and marketing of adult products such as Viagra. |
| `invoice` | Recognizes content related to invoices, receipts, and billing documents, helping detect fraudulent or impersonated requests. |
| `packagedelivery` | Identifies text related to package deliveries, including shipping confirmations, customs notifications, and tracking updates. |

## Using topics

You can filter and search for emails based on detected topics using the topic attributes, as described in the [Search Documentation](/latest/search). Some examples for threat hunting:

* `topic:accountissue AND #nonreputable`: All emails that talk about account problems (like a password reset) sent from addresses that are not relevant to your organization.
* `topic:packagedelivery AND #senderfirstcontact`: All package delivery emails where xorlab sees the sender for the first time.

You can then create a campaign based on this search to address false negatives.

## How it helps

By understanding the meaning and intent behind email content, xorlab can:

* **Increase detection accuracy:** Helps distinguish between legitimate and suspicious emails by considering their topics in combination with other security signals.
* **Improve prioritization:** Automatically assigns higher risk scores to emails that match attack patterns, such as fraudulent invoices or fake account recovery requests.
* **Reduce manual effort:** Security teams don’t need to manually inspect emails for suspicious patterns—the platform detects and flags threats automatically.
* **Enhance correlation with other indicators:** Works alongside behavioral analysis and sender reputation checks to improve decision-making without analyst intervention.

## Report misclassified topics

If you come across a misclassified topic, please report it — your feedback helps us continuously improve our product and its accuracy.

To report a misclassified topic, follow these steps:

1. Report the email normally as described in [Reporting a Misclassification](/latest/reporting-misclassification).

2. Keep the default settings, but add a comment mentioning that it's a misclassified topic, and where the misclassified text is found. E.g. `Misclassified topic: subject`.

   <img alt="Report misclassified topic 2" />


# Trusted MTAs In-Depth
Source: https://docs.xorlab.com/latest/trusted-mtas

How Received headers and trusted MTA configuration let xorlab verify the true path an email traveled.

Email `Received` headers play an important role when verifying the authenticity of email senders. In setups where xorlab is not the border gateway and receives emails from other internal MTAs, the platform needs to know which `Received` headers it can trust (i.e., were added by your organization).

This configuration is required for xorlab to be able to properly authenticate emails. It allows to get the right sender IP address for SPF checks for incoming emails. It is also required to know which emails are legitimate (authentic) outgoing emails if your email server does not DKIM sign outgoing emails.

By default, xorlab trusts every `Received` header originating from a private IP (RFC1918) up until the first one originating from a public IP. This works fine in most setups but fails if your internal MTAs also use public IPs. In that case, you need to declare these MTAs as trusted.

Common symptoms of a wrong trusted MTA configuration are:

* Increased number of emails without authentication, incoming as well as outgoing (SPF checks fail because the IP is taken from the `Received` header).
* Outgoing emails are marked as incoming.
* Inaccurate spam scores.

## Configuration

Trusted MTAs can be configured in `shared/guarded_tenants.yml`. Open the [Expert Editor](/latest/expert-editor) in XCC and add them to the `trustedMTAs` list of the corresponding tenant or config set.

After making the change, click **Publish**. The trusted MTAs become active within about one minute.

Here is an example of two trusted MTAs, one identified through the host name and one through an IP range:

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    trustedMTAs:
      # Host name pattern to identify a trusted MTA. E.g., "^mxin.*\.mail\.example\.net"
      # This match must occur at the end of the host name. So one.mxin.mail.example.net
      # is a match, but mxin.mail.example.net.example.org is not.
      # It is recommended to prefix the pattern with the line start character, `^`, to avoid
      # unintended matching of different domains.
      - hostNamePattern: ^border\.xorlab\.com
        # Enable IP check, trust this header only if the EHLO domain resolves to its IP.
        ipCheckEnabled: true
        # Enable reverse DNS lookup check, trust this header if the root domain of the IP reverse lookup matches the root EHLO domain.
        # reverseDNSCheckEnabled: true
      # Identify through IP range
      - hostCidrBlock: 1.2.3.4/28
        # No need to specify additional checks when defining a trusted MTA via a hostCidrBlock entry
```

The `ipCheckEnabled` and `reverseDNSCheckEnabled` options apply only to `hostNamePattern` entries and are enabled by default. We recommend keeping both enabled, so the header is verified if either check passes. If a trusted MTA is defined using `hostCidrBlock`, no additional validation checks are performed because the IP cannot easily be spoofed.

The following picture shows another example of received headers of an incoming email in an M365 setup with xorlab Security Platform. M365 is the border MTA, and the email is sent by a `google.com` server. The colorful boxes highlight the inputs used for the `hostNamePattern` and `hostCidrBlock` matching. Every received header that is matched by one of the trusted MTA entries is shown in blue.

<img alt="Email headers for xorlab integrated with M365" />

*Received headers of an incoming email where xorlab Security Platform is integrated with M365.*

<Warning>
  Adding an MTA to the trusted MTA list does not mean that emails coming through this server are seen as legitimate. It only helps xorlab Security Platform to trace back the last hops the email took to find out the IP of the external sender. This can then be used for SPF and other checks.
</Warning>

### Authentication whitelist

The trusted MTA configuration also allows you to mark emails as authentic when they pass through a certain trusted MTA. This can be a handy feature if normal authentication of certain senders is not possible. As a reminder, email authentication is important as xorlab Security Platform applies the trust/relationship model only to emails that are marked as authentic (i.e., that have an authenticated `header from`).

This can be implemented with the `authenticDomains` list attribute:

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    trustedMTAs:
      # Whitelist through IP range
      - hostCidrBlock: 1.2.3.4/32
        # Regex - applied to the HEADER FROM domain of an email. The regex is required to match the complete domain.
        authenticDomains:
          - xorlab\.com
```

This configuration example tells xorlab that all emails with an **xorlab.com** `header from` address (e.g., `test@xorlab.com`) that pass through the server `1.2.3.4` should be treated as authentic.

Note that `authenticDomains` expects regular expressions, therefore dots must be escaped. Another example would be: `.*\.xorlab\.com`, which only whitelists subdomains of **xorlab.com**.

**The regular expression is matched against the `header from` domain of the email and it must match the complete domain**. For example, the regex `xorlab\.com` would not match the domain `test.xorlab.com`.

<Warning>
  **Authentic vs. legitimate**

  Note that `authenticDomains` will only mark corresponding emails as authentic. This does not mean that xorlab Security Platform also classifies the emails as legitimate. `authenticDomains` is usually only needed to mark emails from your organization as authentic if other mechanisms like SPF and DKIM fail or are not present.
</Warning>

#### External

The trusted MTA configuration can be enhanced using the `external: true` parameter in combination with the `authenticDomains` parameter. This setup is useful when you trust an external source to send emails on behalf of your domain, even if the external server is not mentioned in your SPF records. By applying this configuration, xorlab will still mark the sender as authenticated, regardless of SPF or DMARC lookup failures.

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    trustedMTAs:
      # Mark emails with a "header from" xorlab.com sent by google.com as authentic
      - hostNamePattern: google\.com
        # With external: true, this entry will not be used to extend the trusted received header list
        # This entry will be matched only with the EHLO received by the border MTA.
        external: true
        authenticDomains:
          - xorlab\.com
```

This example will mark emails from `google.com` MTAs as authentic, without trusting the received header that the `google.com` MTA wrote itself:

<img alt="Emails from google.com" />

## Multi-Tenancy

`trustedMTAs` is a per-tenant setting, so in a multi-tenant deployment every tenant can declare its own trusted infrastructure and its own `authenticDomains`.

If tenants share the same infrastructure, for example because they all sit behind the same front MTA, define `trustedMTAs` once in a config template rather than repeating it on every tenant: [Using Tenant Config Templates](/latest/multi-tenancy-configsets).

A wrong trusted MTA configuration shows up per tenant, so check the symptoms listed at the top of this page for the affected tenant. The routing that determines which MTAs a tenant receives emails from is described in [Configure Tenant Domains and Routing](/latest/multi-tenancy-domain-and-routing).


# Trusted Senders and Infrastructure
Source: https://docs.xorlab.com/latest/trusted-senders-infrastructure

Raise or lower the detection for certain senders and their sending infrastructure, independently of learned reputation.

With the **Trust** lists, you can manually override trust levels of communication partners.

## Trusted senders

xorlab Security Platform lets you adjust the trust level of individual senders and entire domains. This can be helpful to maintain a higher risk profile for certain senders while lowering the guard on others.

To adjust trust levels, log in to xorlab and navigate to **Settings → Lists → Trust**. Then add email addresses or individual email domains to one of the following lists:

| Trust level | List name | Accepted entries |
| :- | :- | :- |
| High | 1. **High trusted sender addresses**<br />2. **High trusted sender domains** | 1. Email addresses as `String`<br />2. Email domain as `String` |
| Medium | 1. **Medium trusted sender addresses**<br />2. **Medium trusted sender domains** | 1. Email addresses as `String`<br />2. Email domain as `String` |
| Low | 1. **Low trusted sender addresses**<br />2. **Low trusted sender domains** | 1. Email addresses as `String`<br />2. Email domain as `String` |
| Untrusted | 1. **Untrusted sender addresses**<br />2. **Untrusted sender domains** | 1. Email addresses as `String`<br />2. Email domain as `String` |

<Warning>
  **Subdomains**

  When you specify a root (top-level) domain, e.g., `example.com`, all its subdomains will also be affected. When you enter a particular subdomain, e.g., `site.example.com`, only this subdomain will be affected, not any lower-level ones such as `other.site.example.com`.
</Warning>

<Info>
  How much filtering each trust level still applies is documented in
  [Detection Defaults → Trust level filtering impact](/latest/detection-defaults#trust-level-filtering-impact).
  Access to that page is restricted.
</Info>

Please note that adding a sender to a trusted list overrides xorlab mechanisms which decrease or increase the sender’s trust level with time based on communications.

## Trusted infrastructure

Similar to adjusting the trust level for [senders and/or their organizations](#trusted-senders) above, you can let xorlab Security Platform know of trusted email infrastructure components. This can be helpful to mitigate the impact of misconfigurations in a sender’s SPF configuration.

Use the lists below to add host names of trusted but non-verifiable mail transfer agents:

| List name | Description | Accepted entries |
| :- | :- | :- |
| 1. **MTA EHLO trust list (regex)**<br />2. **MTA RDNS trust list (regex)** | Use these lists for known senders whose email infrastructure cannot be authenticated | Host names as `Regex`, e.g., `mta\.trusted\.org` |


# Understanding an Email Verdict
Source: https://docs.xorlab.com/latest/understand-verdict

Trace a classification back to the signals that produced it, using the detail view and the analysis breakdown.

## Get a high-level understanding

To get a first understanding on how and why an email was classified in a certain way, open it in the detail view and follow the steps below.

### Verdict and confidence

On top left, you find the classification and action:

* Verdict: **Spam**
* Confidence: **High**
* Action: **Quarantine**

<img alt="Verdict Confidence" />

<Note>
  The [Verdict](/latest/verdicts) and Confidence combination defines the action.
</Note>

For example, a high-confidence phishing email is put into quarantine, while a low-confidence phishing email is delivered with a subject rewrite. You can find your configured actions under **Admin → Actions**, see [Actions](/latest/detection-actions).

If an email is delivered even though it is classified as malicious, it is usually because it has a `low` or `medium` Confidence that is set to the Deliver action.

### Sender and relationship

Scroll down and check in the [Authentication Box](/latest/concepts-sender-auth) if the sender is authenticated:

* No authentication leads more often to a Quarantine action, because the relationship data can not be used.
* However successful authentication by itself is not a positive indicator, as many malicious emails have it.

Below Authentication, have a look at the [Relationship Box](/latest/concepts-relationship):

* Emails with no relationship are filtered more aggressively.
* On the other hand, existing relationship can be a reason for a false negative.
* Hover over the individual values to see if there was one-sided communication.

<img alt="Auth Relationship" />

### Indicators

On the bottom, the list of indicators shows you the most important reasons why the email was blocked.

* 🔴 - Counts strongly for a malicious verdict
* 🟠 - Counts slightly for a malicious verdict
* 🟢 - Benign indicator, some are just informational (like SPF/DKIM tags) and some count for a benign verdict (like having a relationship)

#### Phishing and Spam

For Pishing and Spam verdicts, the **Sender**, **Links** and **Content** boxes contain the responsible indicators:

<img alt="Spam Phishing Verdict" />

#### Malware

For Malware verdicts (dynamic and static), the **Attachment** and **Dynamic Analysis** boxes give more insights on why it was classified as Malware:

<img alt="Spam Phishing Verdict" />

## Get an in-depth understanding

Here we explain how you can go even further and understand in-depth why a verdict was set. This can be helpful in cases like false positives to find out why an email was blocked. For this we need to have a look at the xorlab rules.

> The verdict and confidence is always set by rules, and rules rely on indicators.

All applied rules are visible in the **CLASSIFIERS & RULES** tab. The most important facts about rule application:

* Rules are applied sequentially according to a priority. In the **CLASSIFIERS & RULES** tab, you see the last applied rule on top.
* Every rule can set a decision: `UNDECIDED`, `DELIVER` and `QUARANTINE`. As soon as the first rule sets either `DELIVER` or `QUARANTINE`, no further rules are applied and the action is carried out.
* The rules implement the actions that you configured in the **Actions** configuration screen.

To interpret the rules, you need to know the most important rule types:

<CardGroup>
  <Card title="Tag Rules">
    `TAG_*`: TAG\_spf\_pass

    They set the tags and indicators that you see for each email. They are always set to `UNDECIDED`.
  </Card>

  <Card title="Verdict Rules">
    `<verdict>_*`: MALWARE\_office\_activex

    They propose a verdict and confidence for the email. They are always set to `UNDECIDED`.

    For one verdict, multiple verdict rules can apply. If they have different confidences, the highest one will be taken.

    Multiple different verdicts can be proposed for a single email.
  </Card>

  <Card title="Adapt Rules">
    `ADAPT_*`: ADAPT\_phishing\_ml\_verdict

    They avoid false positives by applying various heuristics.

    They can lower the confidence or remove proposed verdicts completely.

    Can sometimes be the reason for a false negative.
  </Card>

  <Card title="Decision Rules">
    `*_decision`: MALWARE\_dynamic\_decision

    They apply the final action `DELIVER` or `QUARANTINE` for the email.

    They decide which of the proposed verdicts is set as final verdict based on the [Verdict Precedence](/latest/verdicts).
  </Card>
</CardGroup>

The order is Tag → Verdict → Adapt (Optional) → Decision. Here is an example:

<img alt="Applied Rules" />

On top you can see the **Decision** rule carrying out the high-confidence phishing action. Below are several **Verdict** rules from the verdicts *Phishing* and *Filter*.

* The final verdict is Phishing as it has precedence over Filter.
* One Phishing verdict is rule is enough to classify the email as Phishing. In this case even multiple applied.

Now we need to dig into the verdict rules to understand why they were applied.

### Understanding verdict rules

In most cases the name of the verdict rule gives already enough information why it triggered. Some examples:

* `PHISHING_risk_based`: The overall risk of the email was above a certain threshold.
* `MALWARE_office_dangerous_vbascript`: Suspicious VBA Script was found in an office attachment.
* `SPAM_score_high`: The email has a high spam score.
* `SPAM_sa_freemail_forged_replyto`: The Reply-To header is set to a freemail address but the email was not sent from a freemailer.

To go further, you can expand a rule to see which conditions were fulfilled that this rule triggered:

<img alt="Applied Verdict Rule" />

This Phishing verdict rule required four indicators to be present:

| Indicator | Description |
| - | - |
| `indicator.very_young_sender=true` | The sender domain has been recently registered |
| `indicator.sender_is_untrusted=true` | The sender is untrusted, see [Relationship](/latest/concepts-relationship) |
| `indicator.displayname_matches_popular_service=true` | The displayname of the sender matches a popular service |
| `verdict.phishing.do_not_adapt=true` | This rule should not be *adapted* via an Adapt rule |

The web interface shows only indicators that matched and were relevant. It is possible that a rule also checks other indicators via an OR condition, which are not shown.

### Passive rules

xorlab has some built-in passive rules that are indicated via a **gray** UNDECIDED decision. Rules are usually set as passive due to the following reasons:

* Some rules do not work in every environment
* For evaluation purposes - to see how well a rule performs

<img alt="Passive Rule" />

You can generally ignore them as they do not influence the decision. To check at which emails a passive rule was applied, you can use `passiveRule:` in the search.


# List of Verdicts
Source: https://docs.xorlab.com/latest/verdicts

The full classification scale and the action each level triggers, including how confidence modifies the outcome.

xorlab classifies every email with a final verdict. Verdicts range from benign to malicious and—along with their confidence—are the basis of the actions taken as a part of filtering out malicious emails. Verdicts are also used by analysts to classify reported emails as a part of the [Abuse Mailbox](/latest/abuse-mailbox).

<Note>
  You can search for the verdicts listed here with the `verdict:` keyword as described in [*Search*](/latest/search).

  Some search keywords are **aliases** that match several verdicts at once — for example `verdict:policy` matches both Policy and Blacklist. See [Search aliases](#search-aliases).
</Note>

## Malicious verdicts

The following table shows all malicious verdicts.

| Verdict | Search keyword | Description |
| - | - | - |
| Malware | `malware` | Email containing malware |
| Spam | `spam` | Spam email |
| Phishing | `phishing` | Phishing email |
| Policy | `filter` | Email that violates a built-in or custom security policy. For example, a file type is not allowed<br />xorlab Security Platform has many built-in policies that can be activated if needed. Policies are usually not trust-based and hold for all emails |
| Blacklist | `blacklist` | Sender, domain, link, or file is on one of your maintained [blacklists](/latest/blacklists) |
| Impersonation | `impersonation` | General impersonation emails. For example, the attacker uses your organization’s domain as sender domain |
| VIP Fraud | `vipfraud` | Special case of impersonation where the attacker impersonates a VIP (e.g., a CEO) |
| Extortion | `extortion` | Extortion emails, for example, monetary claims based on cryptocurrencies |
| BEC | `bec` | Business Email Compromise. For example, the sender being a compromised partner |
| Encrypted | `encrypted` | Email with an encrypted attachment that was held by [Attachment Airlock](/latest/ssq-attachment-airlock). Only assigned when Attachment Airlock is enabled |

<Note>
  **Policy and Blacklist**

  Policy and Blacklist are two separate verdicts, but they are closely related and both are quarantined into the **Filter** quarantine.

  * `verdict:policy` matches **both** Policy and Blacklist.
  * `verdict:filter` matches **only** Policy.
</Note>

### Additional verdicts for reported emails

The following additional verdicts can be used when resolving reported emails:

| Verdict | Search keyword | Description |
| - | - | - |
| Malicious | `malicious` | Generic malicious email |

## Benign verdicts

A benign verdict does not necessarily mean that the email is 100% benign. Benign verdicts are applied when no malicious verdict could be derived. Based on the positive indicators in the email (e.g., trust), a more significant (trustworthy) benign verdict is chosen.

### Reputation and trust-based verdicts

Verdicts that are based on reputation or trust are usually the most trustworthy benign verdicts.

| Verdict | Description |
| - | - |
| `reputable` | Sender has no trust but a reputable domain |
| `trusted` | Sender has a little trust |
| `business` | Sender has a good trust on organization level |
| `partner` | Sender has the highest trust on organization level |
| `personal` | Sender has a good trust on personal level |

### Others

All other benign verdicts are based on certain indicators found in the email, but do not necessarily mean that the email is benign.

| Verdict | Description |
| - | - |
| `external` | Most generic verdict. No other verdict could be applied |
| `popular` | Sender is a popular service |
| `cloudstorage` | Sender is a cloud storage service |
| `crm` | Sender is a CRM service |
| `bulk` | Sender is a bulk email service |
| `freemail` | Sender is a freemail service |
| `internal` | Internal email |
| `marketing` | Sender is a marketing service |
| `newsletter` | Email is a newsletter |
| `poll` | Sender is a poll service |
| `simulation` | Email from a phishing simulation service, as configured in [Phishing Simulation Tools](/latest/phishing-simulation-tools) |
| `socialnetwork` | Sender is a social network |
| `survey` | Email is a survey |

### Additional verdicts for reported emails

The following additional verdicts can be used when resolving reported emails:

| Verdict | Description |
| - | - |
| `benign` | Generic benign email |
| `forwarded` | Used when a reported email has been inline forwarded, and therefore header information has been lost |

## Attachment verdicts

Attachments are classified separately from the email that carries them. These verdicts appear on the analyzed file, and are also what [File Analysis](/latest/file-analysis) reports.

| Verdict | Description |
| - | - |
| `malware` | Malware detected in the attachment |
| `office_activex` | Office document containing an ActiveX control |
| `office_dangerous_vbascript` | Office document containing a VBA script with high-risk functions |
| `office_vbascript` | Office document containing a VBA script |
| `office_dde` | Office document using Dynamic Data Exchange |
| `office_external_object` | Office document referencing an external object |
| `rtf_embedded_object` | RTF document with an embedded object |
| `executable` | Executable file |
| `script` | Script file |
| `shortcut` | Shortcut file |
| `flash` | Flash file |
| `encrypted` | Encrypted file whose contents could not be inspected |
| `archive` | Archive file |
| `legacy_archive` | Archive in a legacy format |
| `document` | Document file |
| `file` | Generic file. No other verdict could be applied |

## Search aliases

In addition to the verdict names above, the `verdict:` keyword accepts the following aliases. Each alias matches every verdict listed next to it.

| Alias | Matches |
| - | - |
| `malicious` | all malicious verdicts |
| `benign` | all benign verdicts **except** Simulation — search for that with `verdict:simulation` |
| `policy` | Policy **and** Blacklist |
| `vbascript` | `office_vbascript`, `office_dangerous_vbascript` |
| `activex` | `office_activex` |
| `dde` | `office_dde` |
| `extobject` | `office_external_object` |
| `embobject` | `rtf_embedded_object` |
| `legacy` | `legacy_archive` |

## Verdict precedence

After analysis, xorlab assigns a single final verdict to each email. This verdict is determined first based on its confidence (high, medium, or low), and then on its specificity. The final verdict controls which action (e.g., deliver with a subject rewrite or quarantine the email) is taken on the email.

**Confidence**: All high-confidence verdicts and verdicts without confidence have priority over all medium-confidence verdicts. And all medium-confidence verdicts have priority over all low-confidence verdicts.

**Specificity**: More specific verdicts have priority over more generic verdicts. The decision rules are evaluated in this order:

Simulation > Whitelist > Blacklist > Policy > Encrypted > Malware > BEC > Extortion > VIP Fraud > Impersonation > Phishing > Spam

<Note>
  **Whitelist** is a step in this order but is not a verdict. It assigns no verdict at all: it stops further evaluation, so the email keeps the benign verdict it would otherwise have received.
</Note>

For example, if an email is determined to be Spam with high confidence, but also as Phishing with high confidence, the final verdict will be high-confidence Phishing. This is due to Phishing being a more specific verdict than Spam. If instead the email is only considered Phishing with medium confidence, then the final verdict would be high-confidence Spam because higher-confidence verdicts have precedence over lower-confidence verdicts.

### Rule priorities

The rules that determine the final verdict and decision are evaluated in a fixed priority order.
The order applies to emails and reported emails, as well as for all email directions.

<Info>
  The priority values of the built-in decision rules are documented in
  [Detection Defaults → Rule priorities](/latest/detection-defaults#rule-priorities).
  Access to that page is restricted.
</Info>


# Video Tutorials
Source: https://docs.xorlab.com/latest/video-tutorials

Recorded walkthroughs, as an alternative to reading the analyst guide.

## Web interface introduction & concepts

Watch this tutorial for an introduction into xorlab. It discusses the core detection concepts and explains how xorlab is using proactive detection, reputation, and trust models to classify and block threats.

The video also explains analysts how to navigate the web interface of xorlab. You'll learn about the available insights of the **Messages** page and how to analyze the information of the detail view page. Other topics that are discussed in the video are verdicts, actions, confidence levels, tags, attachment and link analysis, and tools to investigate similar messages.

<div>
  <iframe title="Detection Concepts & Introduction to the UI" />
</div>

## Search

Learn how to get the most out of xorlab: from powerful search filters and tags to creating campaigns, using quarantines, and applying the right actions. This video walks you through the essentials with tips and tricks along the way.

<div>
  <iframe title="xorlab Search tutorial" />
</div>


# VIP Names
Source: https://docs.xorlab.com/latest/vips

Flag high-risk identities so that lookalike senders are caught before they reach an inbox.

Attackers impersonate senior management, board members, and other well-known people to launch multi-step targeted attacks against your organization. Register these VIPs to increase protection and improve visibility. To do so, log in to xorlab Security Platform and navigate to **Settings → Lists** and then:

1. Register the first and last name of each of your VIP in the **Basic / VIP names** list by clicking the **Add entry** button below the search input box. This helps to identify Display Name Impersonation Attacks.

Note: For best detection accuracy, add names with umlauts (ä, ö, ü) in both forms (e.g. Müller and Mueller).

<img alt="Registering VIPs" />

2. Make sure to add the corporate email addresses of your VIPs to the **Basic / High value targets** list the same way as with VIPs names. This allows the platform to perform more rigorous filtering while maintaining a risk-based, resource-efficient approach for the rest of your organization.
   <img alt="Registering VIPs’ corporate email addresses" />

3. If your organization allows the use of private email accounts for basic information exchange, then make sure to whitelist private email addresses of registered VIPs in the **Whitelist / VIP sender email whitelist**:
   <img alt="Registering VIPs’ private email addresses" />

## Exposed accounts

Some people inside your organization might be more affected by malicious email than others (for instance, because they receive emails sent to `contact@yourcompany.com` or because their email is publicly available). To increase spam and phishing protection for them, register their email addresses in the **Basic / Exposed accounts** list:

<img alt="Registering exposed email accounts" />

## Exposed public contacts

To this list, you can the add the email addresses of your organization that should be subject to less aggressive filtering. This will decrease spam and phishing protection for them, but can be useful for certain public mailboxes where you expect a lot of suspicious or malformed emails that should be let through.

There is also a related `regex` list called **Exposed public contacts (regex)**, which makes it handy to assign a group of addresses to be considered as exposed public contacts.


# Web Form Senders
Source: https://docs.xorlab.com/latest/web-form-senders

Keep automated submissions from your public site out of the trust model without whitelisting the whole domain.

Emails sent by website contact forms often should be treated differently. We provide two lists to account for this. Log in to xorlab Security Platform, navigate to **Settings → Lists → Basic**, and modify them according to your requirements.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Contact form recipient address** | Use this list to identify contact form email based on its recipients.<br />Threat analysis of such emails is restricted to content, ignoring the metadata | Email address as `String`, e.g., `contact@springfield-nuclear.com` |
| **Contact form sender address** | Use this list to identify contact form email based on its sender address.<br />Threat analysis of such emails is restricted to content, ignoring the metadata | Email address as `String`, e.g., `webform@springfield-nuclear.com` |


# Whitelists
Source: https://docs.xorlab.com/latest/whitelists

Accept email based on sender address, domain, IP, or other indicators, including how subdomain matching behaves.

Whitelists are accessible by selecting **Settings → Lists → Whitelists** in XCC.

<Warning>
  **Subdomains**

  When you add a root (top-level) domain, e.g., `example.com`, to the list, all its subdomains will also be whitelisted. When you add a particular subdomain, e.g., `site.example.com`, only this subdomain will be allowed; any lower-level ones such as `other.site.example.com` won’t be affected.
</Warning>

## Safe senders

Customize any of the lists below to ensure that emails of certain individuals, organizations, or top-level domains are delivered even if your applied risk policy would indicate otherwise.

<Note>
  The **Whitelist** dialog in the message detail view also offers the **Low trusted sender addresses** and **Low trusted sender domains** lists. Those are trust levels rather than whitelists and are documented in [Trusted Senders and Infrastructure](/latest/trusted-senders-infrastructure).
</Note>

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Registered domains** | Any domain names that are controlled by your organization and sound similar to the domains of guarded tenants | Domain name as `String`, e.g., `springfield-nuclear-newsletter.com` |
| **Sender address whitelist (requires auth)** | Use this list to whitelist senders if their [5322.From](https://tools.ietf.org/html/rfc5322) identity can be verified | `mail-from` address as `String` |
| **Sender address whitelist (no auth)** | Use this list to whitelist senders for which you don’t require authentication.<br /> **Use with care.** Emails from senders in this list bypass threat analysis. This increases your attack surface to sender impersonation | Email address as `String` |
| **Sender address airlock whitelist (requires auth)** | Use this list to whitelist senders whose emails will never be put into the airlock quarantine | Email address as `String` |
| **Sender domain whitelist (requires auth)** | Use this list to whitelist organizations if their [5322.From](https://tools.ietf.org/html/rfc5322) identity can be verified | `mail-from` domain as `String` |
| **Sender domain whitelist (no auth)** | Use this list to whitelist entire organizations for which you don’t require sender authentication.<br /> **Use with care.** Emails from senders in this list bypass threat analysis. This increases your attack surface to sender impersonation | Domain name as `String` |

### Safe SMTP senders

| List name | Description | Accepted entries |
| :- | :- | :- |
| **1. Envelope FROM sender whitelist (requires auth)<br />2. Envelope FROM sender whitelist (requires auth) (regex)** | Use this list to whitelist SMTP senders if their [5321.From](https://tools.ietf.org/html/rfc5321) identity can be verified. | 1. `envelope-from` address as `String`<br />2. `envelope-from` address as `Regex`, e.g., `bob\d*@whitelisted\.org` |
| **Envelope FROM sender whitelist (no SPF)** | Use this list to whitelist SMTP senders for which you don’t require authentication.<br /> **Use with care.** Emails from senders in this list bypass threat analysis | SMTP sender address as `String` |
| **Envelope FROM domain whitelist (requires auth)** | Use this list to whitelist organizations if their [5321.From](https://tools.ietf.org/html/rfc5321) identity can be verified | `envelope-from` domain as `String` |
| **Envelope FROM domain whitelist (no SPF)** | Use this list to whitelist entire organizations for which you don’t require SMTP sender authentication.<br /> **Use with care.** Emails from senders in this list bypass threat analysis. This increases your attack surface to sender impersonation | SMTP domain name as `String` |

### Safe infrastructure

| List name | Description | Accepted entries |
| :- | :- | :- |
| **1. MTA EHLO whitelist (regex)<br />2. MTA RDNS whitelist (regex)** | Use this list to whitelist SMTP sender domains | Domain name as `Regex`, e.g., `mta\.partner\.org` |
| **MTA IP whitelist (regex)** | Use this list to whitelist SMTP sender IPs | IP address as `Regex`, e.g., `192\.168\.1\..` |

## Safe recipients

Customize any of the lists below to ensure that emails to certain email addresses are delivered even if your applied risk policy would indicate otherwise. Note that emails that also go to other recipients in your organization are not affected by these whitelists.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Recipient address whitelist (regex)** | Use this list to whitelist emails to these (guarded) recipients. Emails addressed to these and no other guarded recipients not on this list will always get through | Email addresses as `Regex`, e.g. `dmarc-reports.*@guarded.com$` |

## Accepted links

Customize any of the lists below to exclude certain links from risk analysis.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Link domain whitelist** | Use this list to whitelist accepted link domains. Accepted links will not increase the risk score | Domain name as `Regex`, e.g., `businesscritical.com` |

## Accepted files

Customize any of the lists below to exclude certain files from risk analysis.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **File extension whitelist (regex)** | Use this list to exclude files with a given extension from risk analysis | File extension as `Regex`, e.g., `\.txt$` |
| **File output whitelist (regex)** | Use this list to exclude files with a given type from risk analysis. <br />The file type is based on the output of the `file` command | Pattern as `Regex`, e.g., `ASCII text` |
| **File extension expected (regex)** | Use this list to indicate files with a given extension which are considered as expected in communication and shouldn’t increase risk when present | File extension as `Regex`, e.g., `\.txt$` |
| **File output expected (regex)** | Use this list to indicate files with a given extension which are considered as expected in communication and shouldn’t increase risk when present. <br />The file type is based on the output of the `file` command | Pattern as `Regex`, e.g., `ASCII text` |
| **Macro file whitelist (hash)** | Use this list to not consider as dangerous files with Microsoft Office macros.<br />To whitelist a macro file within an Office document, add its file hash to this list. <br />You can either whitelist the whole file or all the dangerous OLE-nested subfiles inside.<br />In order to understand which nested files should be whitelisted, you can check the drop-down list under **Attachments** in XCC (if there is no email message with a file as attachment, it could be uploaded directly with the **File upload** feature).<br />For the nested files that have some macro keywords under their **Office analysis** tab, whitelist them by adding their `sha256` hashes to the list | `sha256` hash of the file |

## Accepted file behavior

Customize any of the lists below to exclude files from risk analysis that exhibit a specific behavior in the Sandbox.

| List name | Description | Accepted entries |
| :- | :- | :- |
| **Dynamic DNS request whitelist** | Use this list to whitelist domains in the context of the Sandbox | Domain name as `String`, e.g., `backend.com` |

## Spam blacklist exclusion

If some senders your organization communicates with have landed on a spam blacklist, you can circumvent this here.

| List name | Description | Accepted Entries |
| :- | :- | :- |
| **SPAM sender exclusion from external blacklist** | Emails with sender's domain (`From` and `EnvFrom`) found in this list will not be affected by the external SPAM blacklists. This helps when certain free webmail provider MTAs land on SPAM blacklists and you want to ignore this. | Domain name as `String`, e.g., `bluewin.ch` |
| **SPAM recipient exclusion from external blacklist** | Emails with recipient's address (`To`, `ReceivedFor`, `CC`, `EnvelopeRecipient`) found in this list will not be affected by the external SPAM blacklists. This helps when certain free webmail provider MTAs land on SPAM blacklists and you want to ignore this. | Email address as `String`, e.g., `user@xorlab.ch` |

## Contextual banners

Configure which senders or recipients should not get a [contextual banner](/latest/detection-contextual-banners) on their emails.

| List name | Description | Accepted Entries |
| :- | :- | :- |
| **Contextual banners recipient address exclusion** | Use this list to exclude recipient email addresses within your organization from displaying banners. | Email address as `String`, e.g., `user@xorlab.ch` |
| **Contextual banners sender address exclusion** | Use this list to exclude sender email addresses from displaying banners. | Email address as `String`, e.g., `user@xorlab.ch` |


# Changelog
Source: https://docs.xorlab.com/changelog

See what changed in every xorlab Security Platform release, filtered by major version, with the fixes rolled out via xCloud and those that need an upgrade.

**See [Release Lifecycle Support](/latest/release-lifecycle-support) to know how long each release is supported.**

Fixes with an increased impact are **bolded**.

Subscribe to the [RSS feed](https://docs-resources.xorlab.com/rss.xml) to be notified of every release.

<Accordion title="About patch releases">
  * *Rolled out via xCloud* - These updates are applied automatically and become available in your xorlab environment without any action required.
  * *Available via upgrade* - For SaaS customers, updates are deployed gradually during scheduled maintenance windows. For on-premise customers, a manual upgrade is required.
</Accordion>

<Update label="Release 11.0.10" description="September 29, 2026">
  ### Rolled out via xCloud

  * \[SA-16205] Rules: Add new high-confidence rule `SPAM_topic_package_delivery_nonreputable_1dayold_link_domain_mismatches_from_domain` (`ACTIVE` by default). This rule improves detection for emails with links to new domains from non-reputable senders.
  * \[SA-16343] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_nonreputable_cloudmailer_only_inbound` (`ACTIVE` by default). This rule improves detection for invoice phishing from nonreputable cloudmailers.
  * \[SA-16449] Rules: Add new high-confidence rule `BEC_bcc_only_html_short_link_img_files_all_media` (`ACTIVE` by default). This rule improves detection for document-sharing-related phishing typically seen in BEC cases.
  * \[SA-16461] Rules: Add new high-confidence rule `SPAM_untrusted_noauth_sender_is_non_personal_address` (`ACTIVE` by default). This rule improves spam detection for certain kinds of medication-related spam.

  ### Available via upgrade

  * \[SA-16467] MTA: Fix problem with lingering temp-files when parsing certain ical files.
  * \[SA-5227] XCC: Allow configuring per-tenant quarantine digest and email notification sender address via config `guarded_tenants.yml` property `tenants[].quarantine.notifications.notificationAddress` and `tenants[].quarantine.emailReporting.notificationAddress`.
  * \[SA-16090] XCC: The email notifications are now also localized in Spanish.
  * \[SA-16090] UI: The SSQ web interface now supports the Spanish language.
  * \[SA-16355] UI: Fix text alignment in attachment table.
  * \[SA-16356] UI: Fix an issue where the shortcuts stopped working after the first use.
  * \[SA-16271] UI: Show campaign validation errors and warnings in the detail view.
  * \[SA-16363] UI: Added a copy button after the breadcrumbs in the list editor to copy the list identifier (listName).
  * \[SA-16421] UI: Fix a bug that prevented copying the file size in the attachments table.
</Update>

<Update label="Release 10.0.18" description="September 29, 2026">
  ### Rolled out via xCloud

  * \[SA-16205] Rules: Add new high-confidence rule `SPAM_topic_package_delivery_nonreputable_1dayold_link_domain_mismatches_from_domain` (`ACTIVE` by default). This rule improves detection for emails with links to new domains from non-reputable senders.
  * \[SA-16209] Rules: Add a new high-confidence rule `PHISHING_bcc_only_sender_global_reputation_low_cloud_storage_link` (`ACTIVE` by default). This rule catches phishing that claims to share an important document via a cloud storage link.
  * \[SA-16261] Rules: Add a new rule `BEC_bcc_only_html_short_link_image_small_body` (`ACTIVE` by default). This rule catches BEC cases claiming to share a document.
  * \[SA-16297] Rules: Improve `PHISHING_sender_unknown_never_delivered_cloud_mailer_displayname_popular` and `PHISHING_unknown_never_delivered_cloudmailer_autogenerated_keywords` to avoid FPs.
  * \[SA-16334] MTA: Fixed a resource leak that could exhaust available ports and cause emails to queue up.
  * \[SA-16343] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_nonreputable_cloudmailer_only_inbound` (`ACTIVE` by default). This rule improves detection for invoice phishing from nonreputable cloudmailers.
  * \[SA-16362] Rules: Add new high-confidence rule `SPAM_freemail_forged_reply_to_bcc_only_lots_of_money` (`ACTIVE` by default). This rule improves detection for spam promising victims huge sums of money.
  * \[SA-16449] Rules: Add new high-confidence rule `BEC_bcc_only_html_short_link_img_files_all_media` (`ACTIVE` by default). This rule improves detection for document-sharing-related phishing typically seen in BEC cases.
  * \[SA-16461] Rules: Add new high-confidence rule `SPAM_untrusted_noauth_sender_is_non_personal_address` (`ACTIVE` by default). This rule improves spam detection for certain kinds of medication-related spam.

  ### Available via upgrade

  * \[SA-16271] UI: Show campaign validation errors and warnings in the detail view.
  * \[SA-16421] UI: Fix a bug that prevented copying the file size in the attachments table.
  * \[SA-16422] UI: Fix a bug where the the subject rewrite was not displayed correctly for actions with no confidence.
</Update>

<Update label="Release 11.0.9" description="September 1, 2026">
  ### Rolled out via xCloud

  * \[SA-16184] Fix detection of the `#reportedasjunk`, `#reportedasnotjunk`, and `#reportedasphishing` tags in setups where a required mail header is missing.
  * \[SA-16209] Rules: Add a new high-confidence rule `PHISHING_bcc_only_sender_global_reputation_low_cloud_storage_link` (`ACTIVE` by default). This rule catches phishing that claims to share an important document via a cloud storage link.
  * \[SA-16261] Rules: Add a new rule `BEC_bcc_only_html_short_link_image_small_body` (`ACTIVE` by default). This rule catches BEC cases claiming to share a document.
  * \[SA-16297] Rules: Improve `PHISHING_sender_unknown_never_delivered_cloud_mailer_displayname_popular` and `PHISHING_unknown_never_delivered_cloudmailer_autogenerated_keywords` to avoid FPs.
  * \[SA-16362] Rules: Add new high-confidence rule `SPAM_freemail_forged_reply_to_bcc_only_lots_of_money` (`ACTIVE` by default). This rule improves detection for spam promising victims huge sums of money.

  ### Available via upgrade

  * \[SA-16187] MTA: Email processing API service should immediately return a http status code 429 if overloaded.
  * \[SA-16321] MTA: Add `trustedMTA` type `Border` allowing more versatile email routing configurations.
  * **\[SA-16334] MTA:** Fixed a resource leak that could exhaust available ports and cause emails to queue up.
  * \[SA-16410] UI: Prevent skipping messages when using the previous/next message shortcuts in the detail view.
  * \[SA-16345] XCC: Fix regression where updating a rule list comment would show an error even though changes were persisted.
  * \[SA-16422] UI: Fix a bug where the the subject rewrite was not displayed correctly for actions with no confidence.
  * \[SA-16473] XCC: Fix issue leading to a timeout during database backup recovery on large instances.
  * \[SA-16480] XCC: Fix issue causing errors when searching for messages after a database recovery.
</Update>

<Update label="Release 11.0.8" description="August 10, 2026">
  ### Rolled out via xCloud

  * \[SA-16173] Rules: Add new high-confidence rule `SPAM_untrusted_domain_only_inbound_matches_popular_service_not_popular_auth` (`ACTIVE` by default). This rule catches more phishy spam, e.g., where the spammer impersonates Galaxus.
  * \[SA-16305] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_domain_only_inbound_sender_global_reputation_low` (`ACTIVE` by default). This rule catches more invoice-based phishing.
  * \[SA-16348] Rules: Improve our internal scores for certain payment providers to reduce FP.

  ### Available via upgrade

  * \[SA-16126] MTA, XCC, Dana: Address issue which causes host upgrades to fail if not enough space is available on the `/boot` partition.
  * \[SA-16349] MTA: The ConfigClient is now more resilient against corrupted or otherwise incomplete meta-info files.
  * \[SA-16268] XCC: Expert config editor prevents invalid `roleMapping` in `auth.yml`.
</Update>

<Update label="Release 10.0.17" description="August 10, 2026">
  ### Rolled out via xCloud

  * \[SA-16173] Rules: Add new high-confidence rule `SPAM_untrusted_domain_only_inbound_matches_popular_service_not_popular_auth` (`ACTIVE` by default). This rule catches more phishy spam, e.g., where the spammer impersonates Galaxus.
  * \[SA-16236] Rules: Improve `PHISHING_untrusted_domain_only_inbound_sender_global_reputation_low_matches_keyword` to catch more phishing.
  * \[SA-16291] Rules: Add new high-confidence rule `PHISHING_topic_package_delivery_untrusted_only_inbound_forged_replyto_non_configured_ccsend` (`ACTIVE` by default). This rule improves detection for package delivery phishing.
  * \[SA-16305] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_domain_only_inbound_sender_global_reputation_low` (`ACTIVE` by default). This rule catches more invoice-based phishing.
  * \[SA-16348] Rules: Improve our internal scores for certain payment providers to reduce FP.

  ### Available via upgrade
</Update>

<Update label="Release 11.0.7" description="August 3, 2026">
  ### Rolled out via xCloud

  * \[SA-16236] Rules: Improve `PHISHING_untrusted_domain_only_inbound_sender_global_reputation_low_matches_keyword` to catch more phishing.

  ### Available via upgrade

  * \[SA-16321] Core: Fixed a regression introduced in 11.0.6 that could cause sender authenticity to be evaluated incorrectly, resulting in legitimate senders being marked as unauthentic.
  * \[SA-16288] UI: Fixed the Abuse Mailbox chart tooltip so it stays above the legend and updates its value correctly when hovering between priority segments.
</Update>

<Update label="Release 11.0.6" description="July 28, 2026">
  ### Rolled out via xCloud

  * \[SA-10215] MTA: Introduce trustedMta config option `type` to better control how and when to trust received-headers.
  * \[SA-16291] Rules: Add new high-confidence rule `PHISHING_topic_package_delivery_untrusted_only_inbound_forged_replyto_non_configured_ccsend` (`ACTIVE` by default). This rule improves detection for package delivery phishing.

  ### Available via upgrade

  * **\[SA-16289] MTA: Address CVE-2026-14266 in `7zip`**.
  * \[SA-16170] XCC: Fixed an issue where the sender could appear as unauthenticated in the UI due to inconsistent letter casing.
</Update>

<Update label="Release 11.0.5" description="July 20, 2026">
  ### Rolled out via xCloud

  * \[SA-16043] Rules: Add new high-confidence rule `PHISHING_untrusted_domain_only_inbound_matches_multiple_delivery_keywords_short_body` (`ACTIVE` by default). This rule enables us to catch more package delivery phishing.
  * \[SA-16093] Rules: Add new rule `BEC_bcc_only_only_media_files_link_subdomain_provider_cloud_storage` (`ACTIVE` by default). This rule improves our ability to catch BEC cases, where the attacker host the payload on a cloud storage provider.
  * \[SA-16203] Rules: Add new high-confidence rule `PHISHING_untrusted_domain_only_inbound_sender_global_reputation_low_matches_keyword` (`ACTIVE` by default). This rule catches more invoice phishing.

  ### Available via upgrade

  * \[SA-5450] MTA: Add a `mta-down-graceful` shell utility which first blocks new traffic, drains the queues and then shuts-down the MTA.
  * \[SA-16094] MTA: Enforced a stricter input size limit for URL extraction to improve resource utilization and prevent timeouts.
  * \[SA-16106] MTA: Fixed an issue that could cause attachments to be skipped during analysis under certain conditions.
  * \[SA-16197] UI: Fix a bug where long images were displayed in full size without the ability to scroll them.
</Update>

<Update label="Release 10.0.16" description="July 20, 2026">
  ### Rolled out via xCloud

  * \[SA-16043] Rules: Add new high-confidence rule `PHISHING_untrusted_domain_only_inbound_matches_multiple_delivery_keywords_short_body` (`ACTIVE` by default). This rule enables us to catch more package delivery phishing.
  * \[SA-16093] Rules: Add new rule `BEC_bcc_only_only_media_files_link_subdomain_provider_cloud_storage` (`ACTIVE` by default). This rule improves our ability to catch BEC cases, where the attacker host the payload on a cloud storage provider.
  * \[SA-16203] Rules: Add new high-confidence rule `PHISHING_untrusted_domain_only_inbound_sender_global_reputation_low_matches_keyword` (`ACTIVE` by default). This rule catches more invoice phishing.

  ### Available via upgrade
</Update>

<Update label="Release 11.0.4" description="June 30, 2026">
  ### Rolled out via xCloud

  ### Available via upgrade

  * \[SA-16111] MTA, XCC, Dana: Fix issues with background package management commands interfering with ones running in the foreground.
  * \[SA-16143] MTA, XCC: Trust "DigiCert Global Root CA", which was recently removed from Mozilla's list of trusted roots. M365 services, notably MTAs require us to still trust this root.
  * \[SA-16142] MTA: Fix an issue that caused analysis results to be too large to be published to XCC.
</Update>

<Update label="Release 10.0.15" description="June 30, 2026">
  ### Rolled out via xCloud

  ### Available via upgrade

  * \[SA-16142] MTA: Fix an issue that caused analysis results to be too large to be published to XCC.
  * \[SA-16143] MTA, XCC: Trust "DigiCert Global Root CA", which was recently removed from Mozilla's list of trusted roots. M365 services, notably MTAs require us to still trust this root.
</Update>

<Update label="Release 11.0.3" description="June 26, 2026">
  ### Rolled out via xCloud

  * \[SA-15996] Rules: Add new high-confidence rule `SPAM_ml_only_inbound_non_reputable_link_with_path_no_local_reputation` (`ACTIVE` by default). This rule catches various kinds of spam messages from only-inbound senders.
  * \[SA-16029] Rules: Add new high-confidence rule `SPAM_only_inbound_low_reputation_one_shortened_link` (`ACTIVE` by default). This rule targets mass online pharmacy spam.
  * \[SA-16086] Rules: Add new high-confidence rule `PHISHING_ml_topic_invoice_account_issue_package_delivery_displayname_similar_to_popular` (`ACTIVE` by default). This rule catches phishing attempts where the sender tries to appear to be a renowned service.

  ### Available via upgrade

  * \[SA-16074] XCC: Fix a mismatch where we had the tag `#noauth` but the UI showed the sender as authenticated.
  * \[SA-16087] XCC: Fixed duplication issue that caused three malware entries to display when resolving a case via the dropdown menu.
  * \[SA-16096] XCC: Resolve an issue where the UI would show a sender as not authenticated, even though the tag `#auth` is also present.
  * \[SA-16109] XCC: Fixed bug that prevented users with role `xcc_tenant_analyst` to use the user interface.
  * \[SA-16118] XCC: Fixed issue that caused email templates to not to be hot-reloaded.
  * \[SA-16077] UI: Fixed a bug where, in some cases, both the current message and the empty state were shown in the similar list if the search had no matches.
  * \[SA-16078] UI: Fixed a regression where clicking on a folders would not collaps/espand it.
  * \[SA-16119] UI: Fixed issue that prevented the saved search time range to be shown.
  * \[SA-16052] UI: Fixed a bug that could cause one image to be skipped when using the arrow keys to navigate to the next/previous image.
  * \[SA-16079] UI: Fixed a layout issue where the reported icon was displayed wrongly in similar list.
  * \[SA-16095] UI: Fixed an issue causing images to flicker in Firefox in some instances.
</Update>

<Update label="Release 10.0.14" description="June 26, 2026">
  ### Rolled out via xCloud

  * \[SA-15996] Rules: Add new high-confidence rule `SPAM_ml_only_inbound_non_reputable_link_with_path_no_local_reputation` (`ACTIVE` by default). This rule catches various kinds of spam messages from only-inbound senders.
  * \[SA-16029] Rules: Add new high-confidence rule `SPAM_only_inbound_low_reputation_one_shortened_link` (`ACTIVE` by default). This rule targets mass online pharmacy spam.
  * \[SA-16086] Rules: Add new high-confidence rule `PHISHING_ml_topic_invoice_account_issue_package_delivery_displayname_similar_to_popular` (`ACTIVE` by default). This rule catches phishing attempts where the sender tries to appear to be a renowned service.

  ### Available via upgrade

  * \[SA-16008] XCC: Restored `Europe/Zurich` as the default time zone for quarantine digests. Due to a regression, new schedules were incorrectly created in UTC.
  * \[SA-16064] XCC: Fixed DMARC alignment computation in the UI. Some emails with authenticated senders were incorrectly displayed as failing authentication.
  * \[SA-16074] XCC: Fix a mismatch where we had the tag `#noauth` but the UI showed the sender as authenticated.
  * \[SA-16096] XCC: Resolve an issue where the UI would show a sender as not authenticated, even though the tag `#auth` is also present.
</Update>

<Update label="Release 11.0.2" description="June 16, 2026">
  ### Rolled out via xCloud

  ### Available via upgrade

  * \[SA-15913] Dana: Reduced exposure of potentially sensitive information by no longer logging certain HTTP request headers.
  * \[SA-16008] XCC: Restored `Europe/Zurich` as the default time zone for quarantine digests. Due to a regression, new schedules were incorrectly created in UTC.
  * \[SA-16061] XCC: Fixed an issue introduced with the release 11 upgrade where the first counter lookup always returned 0, causing tags such as `#domainfirstcontact` to be applied to emails from known senders.
  * \[SA-16064] XCC: Fixed DMARC alignment computation in the UI. Some emails with authenticated senders were incorrectly displayed as failing authentication.
</Update>

<Update label="Release 11.0.1" description="June 12, 2026">
  ### Rolled out via xCloud

  * \[SA-15960] Rules: Disabled spam classifier training during mail imports, as classifiers are shared across tenants.
  * \[SA-15970] Rules: Improved IBAN detection (see `#iban` tag).

  ### Available via upgrade

  * \[SA-16013] Dana: Ensure packages are properly upgraded to prevent startup failures caused by outdated AppArmor profiles.
  * \[SA-15885] XCC: Ensure proper sanitization of attacker-controlled content in quarantine digests.
  * \[SA-16017] XCC: Fixed intermittent counter update failures caused by a database constraint violation.
</Update>

<Update label="Release 11.0.0" description="June 12, 2026">
  ### Highlights

  * \[SA-5068] UI: Users with self-service quarantine access can now archive quarantined emails to keep their view clean. The archived messages are hidden from the main view but remain accessible at any time.
  * \[SA-14132] UI: Onboarding a new Microsoft 365 tenant can now start immediately using retrospective email scanning. This feature allows xorlab to scan historical email traffic to initialize relationship scores and reputations right away, reducing the learning period and false positives in early deployment.
  * \[SA-6123] XCC: Allow lists, block lists, and VIP lists can now be managed programmatically via REST API. All changes done via APIs are scoped, token-authenticated, and audit-logged.

  ### UX improvements and fixes

  * \[SA-14961] UI: Improved error reporting for case isolation, showing a specific error message when isolation fails because the target mailbox is on-premises, disabled, or deleted.
  * \[SA-15191] UI: Removed double scrollbars appearing in message lists.
  * \[SA-15353] UI: Fixed a bug where loading more results after entering an invalid query displayed a page error.
  * \[SA-15384] UI: Removed the label from the actions column header in the self-service quarantine attachment list.
  * \[SA-15385] UI: Fixed an inconsistency where two different delete icons were used across the UI.
  * \[SA-15438] UI: Removed an unnecessary data reload that occurred after closing the unlock message dialog.
  * \[SA-15755] UI: Improved the attachments table to expand and better fill the available space.
  * \[SA-15787] UI: Add the ability to open a link on a new tab on sidebar submenus by using the middle button (or Ctrl+Click).
  * \[SA-15788] UI: Fixed a bug where clicking a dashboard link would reset the selected tenant.
  * \[SA-15794] UI: Removed the tooltip animation for the open case priorities chart.
  * \[SA-15840] UI: Fixed a bug where a long mail subject could break the layout.
  * \[SA-15875] UI: Added missing column padding in blocklist/allowlist dialogs.

  ### Multi-Tenancy improvements

  * \[SA-12705] XCC: Case isolation can now be configured for multiple tenants.
  * \[SA-14149] Core: Added per-tenant tuning of several message processing parameters.
  * \[SA-15237] Core: Added native support for tenant-specific rules and rule profiles.

  ### Detection improvements

  * \[SA-11086] Core: Improved detection for resource-intensive archives like zip bombs.
  * \[SA-15131] Rules: Ensure `#deliver` and `#benign` tags are set properly on emails with direction `external`.

  ### Breaking changes

  * \[SA-14193] MTA: This release removes the internal `unbound` DNS resolver. This breaking change affects on-prem customers only; SaaS customers are not affected. All DNS requests are now resolved via the DNS server configured on the host. In standard on-prem configurations, no action is required. To verify whether your setup is affected:

    * Open `activeguard/core/startup_cfg/unbound.conf` in the Expert Editor.
    * If the file does not contain an active `forward-zone` entry, no action is required.
    * If such an entry exists, compare the configured `forward-addr` with the host DNS server by running `resolvectl status` on any MTA and checking `Current DNS Server`. If it is not the same, contact [support@xorlab.com](mailto:support@xorlab.com).

  * \[SA-6123] XCC: Lists exceeding 10'000 entries will now be automatically truncated. If any of your lists is affected, please contact [support@xorlab.com](mailto:support@xorlab.com) to have the maximum limit adjusted and the previous content restored.

  * \[SA-12205] XCC: When using the [M365 Abuse Mailbox](/latest/m365-reporting-integration), emails reported by users as "Not Junk" will now be auto-resolved as benign (with precedence over campaigns). No report acknowledgment or feedback will be sent to the user for these cases. To revert to the previous behavior, follow the [instructions](/latest/m365-reporting-integration).

    Reported phishing simulation emails are unaffected: they are still auto-resolved and feedback is still sent.

    In addition, xorlab now sets these tags for M365 Abuse Mailbox reports: `#reportedasnotjunk`, `#reportedasjunk`, `#reportedasphishing`.

  * \[SA-12205] XCC: The tags `#simulation` and `#recipientdropped` cannot be used anymore in campaigns. Existing campaigns with those tags will still work as before, but marked as deprecated in the GUI.

  * \[SA-15254] XCC: Simplification of Auth configuration (`auth.yml`). Support for multiple file-based data sources in a username-password auth backend has been dropped. With this release, only one file-based data source is supported. By default, the file-based data source is enabled with the users specified in the `passwordFile.yml` file. No action is required. Existing configuration will be migrated into a conforming state.

  * \[SA-15293] XCC: The `xcc.yml` setting `frontend.triageDefaultSelection.classification` has been removed. No action is required.

  * \[SA-15119] Rules: The `exploit` verdict has been merged into `malware`. As of this release, the `exploit` verdict and the `#exploit` tag have been removed. For any cases where the `exploit` verdict was assigned, xorlab will now fall back to the `malware` verdict. Similarly, any attachment transformation policies that are configured for `exploit` will fall back to the configured `malware` policy.

  * \[SA-15207] Rules: Removal of the `monitoring_mode.properties` [rule profile](https://docs.xorlab.com/11.0/rule-profiles)

    For setups that are configured to run in Monitoring mode and the `monitoring_mode.properties` profile is configured in
    `active_guard.yml` (under `rules` → `params`), the automatic migration will replace it with `default_actions.properties`.
    This changes some default decision actions as follows:

    * The medium confidence filter/policy action changes from `DELIVER` to `QUARANTINE`
    * The medium confidence impersonation action changes from `DELIVER` to `QUARANTINE`
    * The medium confidence VIP fraud action changes from `DELIVER` to `QUARANTINE`

  ### Bugfixes and improvements

  * \[SA-14836] MTA: Prevent Postfix from performing SMTP requests using IPv6 leading to error logs.
  * \[SA-15003] MTA: Fix "Postfix down" alerts, postfix\_exporter now restarts unhealthy log sources.
  * \[SA-15006] MTA: Address a changed metric label affecting the Postfix queue size alert and the MTA monitoring dashboard.
  * \[SA-15025] MTA: Improve Postfix SMTP security defaults.
  * \[SA-15105] MTA: In this release, we disabled additional authentication methods that were not following the DMARC RFC. By default, these methods are now disabled because they caused senders to be authenticated when sent via certain cloud mailer services, even though they should not be considered authenticated under DMARC.
  * \[SA-15338] MTA: Fix problem where tenant assignment would fail in monitoring mode in certain cases.
  * \[SA-15458] MTA: Overhauled envelope extraction configuration to switch between inline and monitoring mode.
  * \[SA-15556] MTA: Adjust rspamd default configuration. Reduce number of retries when querying 3rd party DNS lists.
  * \[SA-15945] MTA: Fix issue where rspamd would not fully recover after a start or config update if the backend was temporarily unavailable.
  * \[SA-11966] XCC: Auth now supports TOTP-based multi-factor authentication for users specified in the password file.
  * \[SA-15284] XCC: Fix redacted subject being visible during PENDING state.
  * \[SA-15395] XCC: Users with an unknown or no tenant assignment are now able to store some user settings (e.g. the UI theme).
  * \[SA-15545] XCC: Introduce a new audit trail event `audit.xcc_instance_metrics.submitted`, which is triggered when the metrics are submitted to xorlab.
  * \[SA-15717] XCC: Fix issue where pending release requests where not marked as approved if approval was bypassed by an release action.
</Update>

<Update label="Release 10.0.13" description="June 5, 2026">
  ### Rolled out via xCloud

  * \[SA-14440] Rules: Add new high-confidence rule `PHISHING_topic_account_issue_untrusted_nonreputable_body_matches_multiple_urgency_keywords_popular_service` (`ACTIVE` by default). This rule catches more account issue phishing.

  * \[SA-15328] Rules: Add a new high-confidence rule `PHISHING_unknown_never_delivered_cloudmailer_autogenerated_keywords` (`ACTIVE` by default) to catch phishing sent via abused cloud mailing services.

  * \[SA-15544] Rules: Add new high confidence rule `PHISHING_domain_only_inbound_html_short_link_image_short_body` (`ACTIVE` by default). This rule improves our ability to catch more "account problem" phishing.

  * \[SA-15754] Rules: Add a new high-confidence rule `PHISHING_non_reputable_only_inbound_popular_displayname_guarded_subject` (`ACTIVE` by default). This rule targets phishing disguised as notifications from popular services.

  * \[SA-15754] Rules: Add a new high-confidence rule `SPAM_only_inbound_phishing_keywords_video` (`ACTIVE` by default). This rule targets video-based spam messages.

  * \[SA-15822] Rules: Add a new high-confidence rule `MALWARE_only_inbound_noauth_ole` (`ACTIVE` by default) to catch malware embedded in Office documents.

  * \[SA-15833] Rules: Add two new high-confidence rules (`ACTIVE` by default):

    * `SPAM_untrusted_very_young_domain_link_count_is_exactly_one`: Blocks spam coming from very young sender domains
    * `PHISHING_untrusted_freemail_very_young_domain`: Blocks phishing coming from very young sender domains

  * \[SA-15835] Rules: Add a new high-confidence rule `PHISHING_untrusted_only_inbound_body_displaytext_document_signature_keyword_link_with_no_reputation` (`ACTIVE` by default). This rule targets document-signing phishing.

  * \[SA-15835] Rules: Add a new high-confidence rule `SPAM_untrusted_noreputation_popular_displayname_link_mismatches_from_domain` (`ACTIVE` by default). This rule targets spam where the sender attempts to impersonate a popular service.

  * \[SA-15903] Rules: Treat VHD and VHDX disk images as malware.

  * \[SA-15905] Rules: Add a new high-confidence rule `SPAM_only_inbound_obfuscated_text` (`ACTIVE` by default) to catch malicious emails applying various obfuscation techniques.

  * \[SA-15921] Rules: Update and improve the existing rule `EXTORTION_nonreputable_untrusted_match_multiple_keywords`. With this change, it catches even more extortion cases.

  * \[SA-16004] Rules: Add a new high-confidence rule `PHISHING_only_inbound_freemail_file_scheme` (`ACTIVE` by default) to catch a wave of credential stealing phishing using the `file:` URI scheme.

  ### Available via upgrade

  * \[SA-15556] MTA: Adjust rspamd default configuration. Reduce number of retries when querying 3rd party DNS lists.
  * \[SA-15945] MTA: Fix issue where rspamd would not fully recover after a start or config update if the backend was temporarily unavailable.
  * \[SA-15840] UI: Fixed a bug where a long mail subject could break the layout.
  * \[SA-15871] UI: Fixed tree view item highlighting in Expert Editor.
  * \[SA-15934] UI: Fixed the formula displayed in the time saved panel.
</Update>

<Update label="Release 9.0.16" description="June 5, 2026">
  ### Rolled out via xCloud

  * \[SA-14440] Rules: Add new high-confidence rule `PHISHING_topic_account_issue_untrusted_nonreputable_body_matches_multiple_urgency_keywords_popular_service` (`ACTIVE` by default). This rule catches more account issue phishing.

  * \[SA-15328] Rules: Add a new high-confidence rule `PHISHING_unknown_never_delivered_cloudmailer_autogenerated_keywords` (`ACTIVE` by default) to catch phishing sent via abused cloud mailing services.

  * \[SA-15544] Rules: Add new high confidence rule `PHISHING_domain_only_inbound_html_short_link_image_short_body` (`ACTIVE` by default). This rule improves our ability to catch more "account problem" phishing.

  * \[SA-15754] Rules: Add a new high-confidence rule `PHISHING_non_reputable_only_inbound_popular_displayname_guarded_subject` (`ACTIVE` by default). This rule targets phishing disguised as notifications from popular services.

  * \[SA-15754] Rules: Add a new high-confidence rule `SPAM_only_inbound_phishing_keywords_video` (`ACTIVE` by default). This rule targets video-based spam messages.

  * \[SA-15822] Rules: Add a new high-confidence rule `MALWARE_only_inbound_noauth_ole` (`ACTIVE` by default) to catch malware embedded in Office documents.

  * \[SA-15833] Rules: Add two new high-confidence rules (`ACTIVE` by default):

    * `SPAM_untrusted_very_young_domain_link_count_is_exactly_one`: Blocks spam coming from very young sender domains
    * `PHISHING_untrusted_freemail_very_young_domain`: Blocks phishing coming from very young sender domains

  * \[SA-15835] Rules: Add a new high-confidence rule `PHISHING_untrusted_only_inbound_body_displaytext_document_signature_keyword_link_with_no_reputation` (`ACTIVE` by default). This rule targets document-signing phishing.

  * \[SA-15835] Rules: Add a new high-confidence rule `SPAM_untrusted_noreputation_popular_displayname_link_mismatches_from_domain` (`ACTIVE` by default). This rule targets spam where the sender attempts to impersonate a popular service.

  * \[SA-15903] Rules: Treat VHD and VHDX disk images as malware.

  * \[SA-15905] Rules: Add a new high-confidence rule `SPAM_only_inbound_obfuscated_text` (`ACTIVE` by default) to catch malicious emails applying various obfuscation techniques.

  * \[SA-15921] Rules: Update and improve the existing rule `EXTORTION_nonreputable_untrusted_match_multiple_keywords`. With this change, it catches even more extortion cases.

  * \[SA-16004] Rules: Add a new high-confidence rule `PHISHING_only_inbound_freemail_file_scheme` (`ACTIVE` by default) to catch a wave of credential stealing phishing using the `file:` URI scheme.

  ### Available via upgrade
</Update>

<Update label="Release 10.0.12" description="May 18, 2026">
  ### Rolled out via xCloud

  * \[SA-15491] Rules: Add new high-confidence rule `SPAM_untrusted_sender_only_inbound_shortened_short_body` (`ACTIVE` by default). This rules improves our ability to catch spam using shortened links.

  * \[SA-15687] Rules: Add new high-confidence rule `SPAM_untrusted_recipient_is_non_personal_address_address_type_count_high` (`ACTIVE` by default). This rule target mass spam where the spammer has a ton of recipients as TO or CC.

  * \[SA-15691] Rules: Add two new rules (`ACTIVE` by default):

    * `PHISHING_ml_untrusted_matches_popular_service_link_domain_mismatch`: The rule improves our ability to detect phishing attacks impersonating popular services.
    * `SPAM_untrusted_sender_only_inbound_body_matches_popular_service_urgency_keyword`: The rule improves our ability to detect phishy spam mentioning popular services.

  * \[SA-15709] Rules: Add new rule `MALWARE_cracked_new_domain_doc_link` (`ACTIVE` by default). This rule improves our ability to block malware attacks, where the attacker tries to hide the malware behind an encrypted attachment.

  * \[SA-15816] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_domain_only_inbound_displaytext_contains_only_caps` (`ACTIVE` by default). This rule enables us to block more invoice phishing attacks.

  ### Available via upgrade

  * \[SA-15732] MTA: Improved the detection of auto-generated emails.

  * \[SA-15615] UI: Fixed time range picker issues:

    * Dashboard no longer scrolls to the bottom after selecting a new time range.
    * Picker no longer appears offscreen in the Similar tab.

  * \[SA-15696] UI: Fixed an issue that caused a text field's background to turn white after selecting an option in the browser autocomplete popup.

  * \[SA-15717] XCC: Fixed an issue where pending release requests were not marked as approved if approval was bypassed by a release action.
</Update>

<Update label="Release 9.0.15" description="May 18, 2026">
  ### Rolled out via xCloud

  * \[SA-15491] Rules: Add new high-confidence rule `SPAM_untrusted_sender_only_inbound_shortened_short_body` (`ACTIVE` by default). This rules improves our ability to catch spam using shortened links.
  * \[SA-15687] Rules: Add new high-confidence rule `SPAM_untrusted_recipient_is_non_personal_address_address_type_count_high` (`ACTIVE` by default). This rule target mass spam where the spammer has a ton of recipients as TO or CC.
  * \[SA-15691] Rules: Add two new rules (`ACTIVE` by default):
    * `PHISHING_ml_untrusted_matches_popular_service_link_domain_mismatch`: The rule improves our ability to detect phishing attacks impersonating popular services.
    * `SPAM_untrusted_sender_only_inbound_body_matches_popular_service_urgency_keyword`: The rule improves our ability to detect phishy spam mentioning popular services.
  * \[SA-15709] Rules: Add new rule `MALWARE_cracked_new_domain_doc_link` (`ACTIVE` by default). This rule improves our ability to block malware attacks, where the attacker tries to hide the malware behind an encrypted attachment.
  * \[SA-15816] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_domain_only_inbound_displaytext_contains_only_caps` (`ACTIVE` by default). This rule enables us to block more invoice phishing attacks.

  ### Available via upgrade

  * \[SA-15732] MTA: Improve the detection of auto-generated emails.
</Update>

<Update label="Release 10.0.11" description="April 28, 2026">
  ### Rolled out via xCloud

  * \[SA-15333] Rules: Add new high-confidence rules (`ACTIVE` by default):

    * `PHISHING_only_inbound_displayname_matches_keyword_subject_urgent` addresses phishing cases that create a sense of urgency.
    * `PHISHING_only_inbound_non_reputable_displayname_matches_partner_link_mismatch` catches phishing cases with mismatched links in the name of a partner organization.
    * `PHISHING_topic_invoice_only_inbound_non_reputable_displayname_popular_or_partner_or_guarded` addresses invoice phishing in the name of partner organizations.

  * \[SA-15393] Rules: Add new high-confidence rule `SPAM_nonreputable_young_domain_new_link_dangerous_file_type_subject_phishing_keyword` (`ACTIVE` by default). This rule improves spam detection for emails from non-reputable senders with dubious links.

  * \[SA-15444] Rules: Add new high-confidence rules `PHISHING_topic_invoice_only_inbound_display_text_phishing_keywords` and `SPAM_freemail_only_inbound_calendar_file_suspicious_link` (`ACTIVE` by default). The rules catch cases of invoice phishing and calendar invite spam.

  * \[SA-15526] Rules: Add a new high-confidence rule `SPAM_topic_invoice_only_inbound_non_reputable_public_suffix_no_reputation` (`ACTIVE` by default). This rule targets unwanted mails inquiring about the status of an invoice.

  * \[SA-15569] Rules: Add a set of new rules (all `ACTIVE` by default)

    * `PHISHING_ml_matches_guarded_name_file`: Targets phishing attacks impersonating a guarded sender.
    * `SPAM_topic_invoice_untrusted_sender_only_inbound_link_count_suspicious_is_exactly_one`: Targets link-based phishy spam talking about invoices.
    * `PHISHING_body_matches_popular_service_urgency_invoice`: Targets invoice phishing attacks impersonating a popular service.
    * `EXTORTION_untrusted_sender_only_inbound_multiple_extortion_keywords_not_file_not_link`: Targets extortion attacks where there's no link or attachment.

  * \[SA-15702] Rules: Add new high-confidence rule `SPAM_untrusted_only_inbound_replyto_not_from_displayname_matches_popular_service_non_configured_ccsend` (`ACTIVE` by default). This rule improves spam detection for ccsend abusers.

  ### Available via upgrade

  * \[SA-15445] UI: Fix a bug that prevented to perform bulk actions to the current message in the similar tab.
  * \[SA-15550] MTA, XCC: Fix issue where mails would be stuck in publishing because of excessively large `message-id` mail headers.
  * \[SA-15554] XCC: Remove the non-functional auto completion suggestion `file.type:mail`.
  * \[SA-15647] UI: Fix the search in the Actions page.
</Update>

<Update label="Release 9.0.14" description="April 28, 2026">
  ### Rolled out via xCloud

  * \[SA-13856] Rules: Improved newsletter detection heuristics.

  * \[SA-15333] Rules: Add new high-confidence rules (`ACTIVE` by default):

    * `PHISHING_only_inbound_displayname_matches_keyword_subject_urgent` addresses phishing cases that create a sense of urgency.
    * `PHISHING_only_inbound_non_reputable_displayname_matches_partner_link_mismatch` catches phishing cases with mismatched links in the name of a partner organization.
    * `PHISHING_topic_invoice_only_inbound_non_reputable_displayname_popular_or_partner_or_guarded` addresses invoice phishing in the name of partner organizations.

  * \[SA-15393] Rules: Add new high-confidence rule `SPAM_nonreputable_young_domain_new_link_dangerous_file_type_subject_phishing_keyword` (`ACTIVE` by default). This rule improves spam detection for emails from non-reputable senders with dubious links.

  * \[SA-15444] Rules: Add new high-confidence rules `PHISHING_topic_invoice_only_inbound_display_text_phishing_keywords` and `SPAM_freemail_only_inbound_calendar_file_suspicious_link` (`ACTIVE` by default). The rules catch cases of invoice phishing and calendar invite spam.

  * \[SA-15462] Rules: Add new high-confidence rule `SPAM_cloudmailer_only_inbound_non_reputable_reply_to_not_from` (`ACTIVE` by default). This rule addresses spam emails attachments of forged catalogs for used cars and machines.

  * \[SA-15508] Rules: Add new high-confidence rule `PHISHING_topic_account_issue_invoice_marketing_non_reputable_reply_to_not_from` (`ACTIVE` by default). This rule addresses phishing cases that are sent through marketing cloud mailers.

  * \[SA-15526] Rules: Add a new high-confidence rule `SPAM_topic_invoice_only_inbound_non_reputable_public_suffix_no_reputation` (`ACTIVE` by default). This rule targets unwanted mails inquiring about the status of an invoice.

  * \[SA-15569] Rules: Add a set of new rules (all `ACTIVE` by default)

    * `PHISHING_ml_matches_guarded_name_file`: Targets phishing attacks impersonating a guarded sender.
    * `SPAM_topic_invoice_untrusted_sender_only_inbound_link_count_suspicious_is_exactly_one`: Targets link-based phishy spam talking about invoices.
    * `PHISHING_body_matches_popular_service_urgency_invoice`: Targets invoice phishing attacks impersonating a popular service.
    * `EXTORTION_untrusted_sender_only_inbound_multiple_extortion_keywords_not_file_not_link`: Targets extortion attacks where there's no link or attachment.

  * \[SA-15702] Rules: Add new high-confidence rule `SPAM_untrusted_only_inbound_replyto_not_from_displayname_matches_popular_service_non_configured_ccsend` (`ACTIVE` by default). This rule improves spam detection for ccsend abusers.

  ### Available via upgrade
</Update>

<Update label="Release 10.0.10" description="March 24, 2026">
  ### Rolled out via xCloud

  * \[SA-13856] Rules: Improved newsletter detection heuristics.
  * \[SA-15462] Rules: Add new high-confidence rule `SPAM_cloudmailer_only_inbound_non_reputable_reply_to_not_from` (`ACTIVE` by default). This rule addresses spam emails attachments of forged catalogs for used cars and machines.
  * \[SA-15508] Rules: Add new high-confidence rule `PHISHING_topic_account_issue_invoice_marketing_non_reputable_reply_to_not_from` (`ACTIVE` by default). This rule addresses phishing cases that are sent through marketing cloud mailers.

  ### Available via upgrade

  \[SA-15506] XCC: Fix permission issue during auto host migration which prevented the upgrade from versions prior to 10.0.8.
</Update>

<Update label="Release 10.0.9" description="March 23, 2026">
  ### Rolled out via xCloud

  * \[SA-14856] Rules: Improved newsletter detection heuristics.
  * \[SA-15107] Rules: Add new high-confidence rule `SPAM_ml_popular_displayname` (`ACTIVE` by default). This rule catches spam sent in the name of popular brands.
  * \[SA-15258] Rules: Add new high-confidence rule `PHISHING_untrusted_only_inbound_non_reputable_sender_contains_guarded_doc_link` (`ACTIVE` by default). This rule improves our ability to block phishing emails, where the attachment contains a document phishing link.
  * \[SA-15340] Rules: Detect MS Office vulnerability CVE-2026-21509 with a new YARA rule `YARA_cve_2026_21509` (`ACTIVE` by default). Matches can be found by searching for the tag `#cve_2026_21509` after the upgrade. This rule catches documents that might exploit [CVE-2026-21509](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2026-21509).
  * \[SA-15364] Rules: Add new high-confidence rule `PHISHING_topic_package_delivery_only_inbound_non_reputable_reply_to_not_from` (`ACTIVE` by default). This rule catches package-delivery phishing with reply-to address mismatches.
  * \[SA-15456] Rules: Add new high-confidence rule `PHISHING_cloud_mailer_non_reputable_only_inbound_display_text_signature_keyword` (`ACTIVE` by default). This rule catches document review and document signing phishing.
  * \[SA-15475] Rules: Mark the rule `BEC_html_with_script_small_phishy_body_and_subject` as `PASSIVE` to avoid false positives.

  ### Available via upgrade

  * \[SA-15408] MTA: Lower log level when email address parsing fails in specific cases when running in monitoring mode.
  * \[SA-15409] XCC: Fix issue causing the upgrade script to fail attempting to commit configuration changes.
  * \[SA-15353] UI: Fix a bug where a page error is displayed when trying to load more results and an invalid query was typed.
</Update>

<Update label="Release 9.0.13" description="March 23, 2026">
  ### Rolled out via xCloud

  * \[SA-14856] Rules: Improved newsletter detection heuristics.
  * \[SA-15107] Rules: Add new high-confidence rule `SPAM_ml_popular_displayname` (`ACTIVE` by default). This rule catches spam sent in the name of popular brands.
  * \[SA-15258] Rules: Add new high-confidence rule `PHISHING_untrusted_only_inbound_non_reputable_sender_contains_guarded_doc_link` (`ACTIVE` by default). This rule improves our ability to block phishing emails, where the attachment contains a document phishing link.
  * \[SA-15340] Rules: Detect MS Office vulnerability CVE-2026-21509 with a new YARA rule `YARA_cve_2026_21509` (`ACTIVE` by default). Matches can be found by searching for the tag `#cve_2026_21509` after the upgrade. This rule catches documents that might exploit [CVE-2026-21509](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2026-21509).
  * \[SA-15364] Rules: Add new high-confidence rule `PHISHING_topic_package_delivery_only_inbound_non_reputable_reply_to_not_from` (`ACTIVE` by default). This rule catches package-delivery phishing with reply-to address mismatches.
  * \[SA-15456] Rules: Add new high-confidence rule `PHISHING_cloud_mailer_non_reputable_only_inbound_display_text_signature_keyword` (`ACTIVE` by default). This rule catches document review and document signing phishing.
  * \[SA-15475] Rules: Mark the rule `BEC_html_with_script_small_phishy_body_and_subject` as `PASSIVE` to avoid false positives.

  ### Available via upgrade

  * \[SA-15353] UI: Fix a bug where a page error is displayed when trying to load more results and an invalid query was typed.
</Update>

<Update label="Release 10.0.8" description="March 3, 2026">
  ### Rolled out via xCloud

  * \[SA-15251] Rules: Add new high confidence rules (`ACTIVE` by default):

    * `SPAM_ml_calendar_file` for catching attacks based on calendar invites.
    * `PHISHING_only_inbound_non_reputable_qr_code_link_and_keywords_html_body_with_data_url` for catching QR code phishing attacks.
    * `PHISHING_only_inbound_non_reputable_voicemail_keywords` for catching voicemail phishing attacks.
    * `PHISHING_topic_account_issue_only_inbound_non_reputable_in_file` for catching account issue phishing attacks.

  ### Available via upgrade

  * \[SA-15338] MTA: Fix issue where recipient-based tenant assignment would not honor the `recipientRetrievalStrategy` configuration.
  * \[SA-15293] UI: Fixed issue causing setting wrong classification and template selection data when resolving cases and creating campaigns.
  * \[SA-15372] UI: Fixed issue which caused wrong number formatting on Firefox.
  * \[SA-15356] XCC: Standardized timezone handling. The `xcc_backend` container now uses UTC by default, which may affect log timestamps.
</Update>

<Update label="Release 9.0.12" description="March 3, 2026">
  ### Rolled out via xCloud

  * \[SA-15251] Rules: Add new high confidence rules (`ACTIVE` by default):

    * `SPAM_ml_calendar_file` for catching attacks based on calendar invites.
    * `PHISHING_only_inbound_non_reputable_qr_code_link_and_keywords_html_body_with_data_url` for catching QR code phishing attacks.
    * `PHISHING_only_inbound_non_reputable_voicemail_keywords` for catching voicemail phishing attacks.
    * `PHISHING_topic_account_issue_only_inbound_non_reputable_in_file` for catching account issue phishing attacks.

  ### Available via upgrade
</Update>

<Update label="Release 10.0.7" description="February 24, 2026">
  ### Rolled out via xCloud

  * \[SA-14255] Rules: Fixed a bug where senders added to the medium/high trust list while using a cloud mailer were still incorrectly treated as low-trusted.
  * \[SA-15161] Rules: Add new high-confidence rule `PHISHING_topic_account_issue_package_delivery_cloudmailer_replyto_freemail` (`ACTIVE` by default). This rule catches phishing attempts claiming an issue with the target's account.
  * \[SA-15209] Rules: Add two new high-confidence rules (`ACTIVE` by default). The rules block popular service impersonations and document signing phishing:

    * `SPAM_untrusted_only_inbound_displayname_popular_suspicious_link_with_path_part`
    * `PHISHING_untrusted_non_reputable_document_signature_keywords_with_data_url`

  ### Available via upgrade

  * \[SA-15007] MTA: Fix Postfix exporter label format in alerts for monitored\_mta:

    * The values for the metrics label `le` were changed from integral to decimal numbers. For example, the value `10` was changed to `10.0`. This prevents previous value selectors, such as `le="10"` from matching any value. It has to be migrated to `le="10.0"`.
    * An automatic migration will update these values in the file `/monitored_mta/prometheus/alert/activeguard_alerts.yml`.
    * However, if your instance has manual modifications in this file, then manual updates might be required. The migration only modifies values that were shipped with the original installation.

  * \[SA-15204] MTA: Fix issue where yaml files in expert editor path `/shared/email_templates/style/` where not properly validated.

  * \[SA-15255] MTA: Fix issue where a software module was initialized too late. This would lead to unexpected problem when recovering unfinished messages from before a shutdown.

  * \[SA-15241] UI: Fix a bug where a saved search could not show the checkboxes in some cases.

  * \[SA-15282] UI: Fix issue that prevented to show current set action for a campaign and that accidentally sent feedbacks even if set otherwise.

  * \[SA-15284] XCC: Fix an issue which led to errors, when an analyst tried to bulk release a message for which user already requested a release.
</Update>

<Update label="Release 9.0.11" description="February 24, 2026">
  ### Rolled out via xCloud

  * \[SA-14255] Rules: Fixed a bug where senders added to the medium/high trust list while using a cloud mailer were still incorrectly treated as low-trusted.
  * \[SA-15161] Rules: Add new high-confidence rule `PHISHING_topic_account_issue_package_delivery_cloudmailer_replyto_freemail` (`ACTIVE` by default). This rule catches phishing attempts claiming an issue with the target's account.
  * \[SA-15209] Rules: Add two new high-confidence rules (`ACTIVE` by default). The rules block popular service impersonations and document signing phishing:

    * `SPAM_untrusted_only_inbound_displayname_popular_suspicious_link_with_path_part`
    * `PHISHING_untrusted_non_reputable_document_signature_keywords_with_data_url`

  ### Available via upgrade

  * \[SA-15241] UI: Fix a bug where a saved search could not show the checkboxes in some cases.
</Update>

<Update label="Release 10.0.6" description="February 4, 2026">
  ### Rolled out via xCloud

  * \[SA-14745] Rules: Add new high-confidence rules `PHISHING_topic_account_issue_invoice_only_inbound_displayname_popular` and `PHISHING_only_inbound_non_reputable_links_popular_displayname` (`ACTIVE` by default) to catch new phishing waves using forged notification emails in the name of popular services.
  * \[SA-15159] Rules: Add new high-confidence rule `SPAM_only_inbound_bcc_only_forwarded_reply_to` (`ACTIVE` by default). This rule blocks spam mails forwarded through another service, such as Gmail.
  * \[SA-15227] Rules: Add new high-confidence rule `PHISHING_popular_auth_bcc_only_env_from_non_configured_m365_domain` (`ACTIVE` by default). This rule blocks phishing mails forwarded through Microsoft infrastructure.

  ### Available via upgrade

  * \[SA-15116] MTA, XCC: Fix issue where a configuration change in monitoring would not cause a hot-reload of the configuration.
  * \[SA-15180] MTA: Fix problem where results are not properly published in case a tenant was deleted while processing a message.
  * \[SA-15250] MTA, XCC: Address multiple CVEs in OpenSSL, such as CVE-2025-15467.
  * \[SA-15144] UI: Change the Release icon in the Quarantine portal, which was the old icon used for Releasing a message.
</Update>

<Update label="Release 9.0.10" description="February 4, 2026">
  ### Rolled out via xCloud

  * \[SA-14745] Rules: Add new high-confidence rules `PHISHING_topic_account_issue_invoice_only_inbound_displayname_popular` and `PHISHING_only_inbound_non_reputable_links_popular_displayname` (`ACTIVE` by default) to catch new phishing waves using forged notification emails in the name of popular services.
  * \[SA-15159] Rules: Add new high-confidence rule `SPAM_only_inbound_bcc_only_forwarded_reply_to` (`ACTIVE` by default). This rule blocks spam mails forwarded through another service, such as Gmail.
  * \[SA-15227] Rules: Add new high-confidence rule `PHISHING_popular_auth_bcc_only_env_from_non_configured_m365_domain` (`ACTIVE` by default). This rule blocks phishing mails forwarded through Microsoft infrastructure.

  ### Available via upgrade

  * \[SA-15250] MTA, XCC: Address multiple CVEs in OpenSSL, such as CVE-2025-15467.
</Update>

<Update label="Release 10.0.5" description="January 19, 2026">
  ### Rolled out via xCloud

  * \[SA-15055] Rules: Add a new high-confidence rule `PHISHING_only_inbound_cloudmailer_high_to_address_count_replyto_not_from` (`ACTIVE` by default). This rule addresses a wave of phishing delivered through reputable cloud mailers.

  * \[SA-15068] Rules: Add 2 new high confidence rules (`ACTIVE` by default). Both rules target phishing, where the attacker misused cloud mailer infrastructure:

    * `PHISHING_topic_account_issue_package_delivery_replyto_domain_not_equal_from_domain_cloudmailer`
    * `PHISHING_untrusted_replyto_domain_not_equal_from_domain_sender_account_name_character_count_gt_25`

  * \[SA-15022]\[SA-15108] Rules: Add new high-confidence BEC rules `BEC_cloudstorage_new_domain_multiple_document_signature_keywords` and `BEC_bcc_only_document_signature_keywords_all_caps_displaytext` (`ACTIVE` by default). Both rules address attacks sent from compromised accounts.

  * \[SA-15134] Rules: Add a new high-confidence rule `PHISHING_no_auth_no_reputable_link_displayname_or_subject_popular_or_guarded_urgency_keywords` (`ACTIVE` by default). This rule addresses phishing from unauthenticated senders that try to appear as a popular service or an organization-internal sender.

  * \[SA-15155]\[SA-14991] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_domain_only_inbound_to_address_type_count_large` (`ACTIVE` by default). This rule improves our ability to detect and block invoice phishing.

  ### Available via upgrade

  * \[SA-14916] MTA: Do not send encrypted attachments to the text extraction service.
  * \[SA-15003] MTA: Fix "Postfix down" alerts, postfix\_exporter now restarts unhealthy log sources.
  * \[SA-15074] UI: Fixed wrong update of the URL parameters when removing the last active search filter.
  * \[SA-14906] XCC: Fix issue which prevented the proxy configuration from being applied in `m365GraphApi`.
  * \[SA-15071] XCC: Fix for missing updates to counters and models when a quarantine release request gets approved.
</Update>

<Update label="Release 9.0.9" description="January 19, 2026">
  ### Rolled out via xCloud

  * \[SA-15055] Rules: Add a new high-confidence rule `PHISHING_only_inbound_cloudmailer_high_to_address_count_replyto_not_from` (`ACTIVE` by default). This rule addresses a wave of phishing delivered through reputable cloud mailers.

  * \[SA-15068] Rules: Add 2 new high confidence rules (`ACTIVE` by default). Both rules target phishing, where the attacker misused cloud mailer infrastructure:

    * `PHISHING_topic_account_issue_package_delivery_replyto_domain_not_equal_from_domain_cloudmailer`
    * `PHISHING_untrusted_replyto_domain_not_equal_from_domain_sender_account_name_character_count_gt_25`

  * \[SA-15022]\[SA-15108] Rules: Add new high-confidence BEC rules `BEC_cloudstorage_new_domain_multiple_document_signature_keywords` and `BEC_bcc_only_document_signature_keywords_all_caps_displaytext` (`ACTIVE` by default). Both rules address attacks sent from compromised accounts.

  * \[SA-15134] Rules: Add a new high-confidence rule `PHISHING_no_auth_no_reputable_link_displayname_or_subject_popular_or_guarded_urgency_keywords` (`ACTIVE` by default). This rule addresses phishing from unauthenticated senders that try to appear as a popular service or an organization-internal sender.

  * \[SA-15155]\[SA-14991] Rules: Add new high-confidence rule `PHISHING_topic_invoice_untrusted_domain_only_inbound_to_address_type_count_large` (`ACTIVE` by default). This rule improves our ability to detect and block invoice phishing.

  ### Available via upgrade

  * \[SA-14916] MTA: Do not send encrypted attachments to the text extraction service.
  * \[SA-14906] XCC: Fix issue which prevented the proxy configuration from being applied in `m365GraphApi`.
  * \[SA-15071] XCC: Fix for missing updates to counters and models when a quarantine release request gets approved.
</Update>

<Update label="Release 10.0.4" description="December 19, 2025">
  ### Rolled out via xCloud

  * \[SA-14993] Rules: Add new high-confidence rule `PHISHING_untrusted_only_inbound_cloud_mailer_subject_guarded_document_signature_keywords` (`ACTIVE` by default) to catch phishing attempts claiming to share an internal document.
  * \[SA-14997] Rules: Add new high-confidence rule `PHISHING_no_auth_new_domain_phishy_displayname` (`ACTIVE` by default) to catch more phishing sent by unauthenticated senders.
  * \[SA-15018] Rules: Add new high-confidence rule `PHISHING_untrusted_common_phishing_link_displayname_popular_phishing_keywords` (`ACTIVE` by default) to block emails that promise a free gift in the name of a popular brand.
  * \[SA-15026] Rules: Add new high-confidence rule `PHISHING_untrusted_only_inbound_subject_guarded_multiple_keywords` (`ACTIVE` by default) to address more phishing cases that claim to share an internal document.
  * \[SA-15056] Rules: Add new high-confidence rule `PHISHING_google_application_integration` (`ACTIVE` by default). This rule blocks a new attack, coming from an authenticated Google Application Integration service.
  * \[SA-15064] Rules: Add new high-confidence rule `PHISHING_only_inbound_html_mostly_image_test_subject` (`ACTIVE` by default). This rule blocks a wave of AI-translated Swiss German phishing cases.
  * \[SA-15070] Rules: Require an untrusted sender for the rule `PHISHING_nonreputable_sender_unknown_never_delivered_urgency_keywords_suspicious_link` to trigger. Adding a specific sender to the low-trusted sender list now prevents this rule from triggering.

  ### Available via upgrade

  * \[SA-14782] UI: Fix a bug where the filters could change position when adding a new filter.
  * \[SA-14878] UI: Fix an issue where the selected tenant resets when navigating to specific configuration in the admin section.
  * \[SA-14971] UI: Improve the Expert Editor dialogs by avoiding scrollbars for long filenames.
  * \[SA-14926] UI: Disable similar content filter menu item when the suggested filter is present.
  * \[SA-14998] UI: The verdicts and status search fields are now auto-focused when opening the filter.
  * \[SA-15029] UI: Fix a bug where the comment was sent even if "No Feedback" option was selected in resolve dialog.
  * \[SA-14746] XCC: Prevent error log in case of insufficient permissions while using auto-login links.
  * \[SA-14795] XCC: Improvements around the DB queries for messages scheduled for deletion.
  * \[SA-15003] MTA: Fix mail log rotation to avoid postfix down alerts.
  * \[SA-15091] MTA: Fix out of bounds access when processing sudomain provider lists.
</Update>

<Update label="Release 9.0.8" description="December 19, 2025">
  ### Rolled out via xCloud

  * \[SA-14993] Rules: Add new high-confidence rule `PHISHING_untrusted_only_inbound_cloud_mailer_subject_guarded_document_signature_keywords` (`ACTIVE` by default) to catch phishing attempts claiming to share an internal document.
  * \[SA-14997] Rules: Add new high-confidence rule `PHISHING_no_auth_new_domain_phishy_displayname` (`ACTIVE` by default) to catch more phishing sent by unauthenticated senders.
  * \[SA-15018] Rules: Add new high-confidence rule `PHISHING_untrusted_common_phishing_link_displayname_popular_phishing_keywords` (`ACTIVE` by default) to block emails that promise a free gift in the name of a popular brand.
  * \[SA-15026] Rules: Add new high-confidence rule `PHISHING_untrusted_only_inbound_subject_guarded_multiple_keywords` (`ACTIVE` by default) to address more phishing cases that claim to share an internal document.
  * \[SA-15056] Rules: Add new high-confidence rule `PHISHING_google_application_integration` (`ACTIVE` by default). This rule blocks a new attack, coming from an authenticated Google Application Integration service.
  * \[SA-15064] Rules: Add new high-confidence rule `PHISHING_only_inbound_html_mostly_image_test_subject` (`ACTIVE` by default). This rule blocks a wave of AI-translated Swiss German phishing cases.
  * \[SA-15070] Rules: Require an untrusted sender for the rule `PHISHING_nonreputable_sender_unknown_never_delivered_urgency_keywords_suspicious_link` to trigger. Adding a specific sender to the low-trusted sender list now prevents this rule from triggering.

  ### Available via upgrade

  * \[SA-14746] XCC: Prevent error log in case of insufficient permissions while using auto-login links.
  * \[SA-14795] XCC: Improvements around the DB queries for messages scheduled for deletion.
  * \[SA-15091] MTA: Fix out of bounds access when processing sudomain provider lists.
</Update>

<Update label="Release 9.0.7" description="December 10, 2025">
  <Warning>
    **Update recommended**

    We recommend to update to 9.0.7 (or any 10.0.X version) as soon as possible due to SA-15030. This fixes a critical vulnerability in a third party library (Tika) that is used on the MTA.
  </Warning>

  ### Rolled out via xCloud

  * \[SA-14399] Rules: Add new `PHISHING_untrusted_only_inbound_document_signature_keywords_link_with_no_reputation` (`ACTIVE` by default). This rule will catch more document signature phishing.
  * \[SA-14855] Rules: Add new high-confidence rule `SPAM_ml_untrusted_only_inbound_non_reputable_link` (`ACTIVE` by default) to block more spam.
  * \[SA-14932] Rules: Add high confidence rule `PHISHING_topic_invoice_matches_office_interaction_document_signature_keyword` (`ACTIVE` by default). This rule blocks more invoice phishing, where the attack is attached as an office document.
  * \[SA-14944] Rules: Add new high-confidence rule `PHISHING_sender_unknown_never_delivered_cloud_mailer_displayname_popular` (`ACTIVE` by default) to block phishing mails sent through reputable cloud services.
  * \[SA-14959] Rules: Add new high-confidence rule `PHISHING_sender_unknown_never_delivered_cloud_mailer_displayname_popular` (`ACTIVE` by default) to block phishing mails disguised as bounce messages.
  * \[SA-15005] Rules: Add new high-confidence rule `PHISHING_untrusted_nonreputable_body_matches_voicemail_password_popular_guarded_email` (`ACTIVE` by default). The rule catches more voice mail phishing impersonating popular services.
  * \[SA-15024] Rules: Fix for a missing space in default subject rewrites. An earlier update introduced a bug where subject rewrites were missing the space between the prefix and the subject. E.g., the subject would become `[SPAM]Subject` instead of `[SPAM] Subject`.

  ### Available via upgrade

  * \[SA-15006] MTA: Address changed metric label, affecting the Postfix queue size alert and the MTA monitoring dashboard.
  * **\[SA-15030] MTA: Address critical CVEs (CVE-2025-54988, CVE-2025-66516) in Tika.**
  * \[SA-13868] XCC: Avoid updating the relationship score when a campaign is set up to deliver the message with a malicious verdict. This avoids the build-up of trust for campaigns that, e.g., only do a subject rewrite instead of quarantining the messages.
  * \[SA-14864] XCC: Prevent error log on case isolation when repeatedly trying to isolate a message.
</Update>

<Update label="Release 10.0.3" description="December 5, 2025">
  ### Rolled out via xCloud

  * \[SA-14399] Rules: Add new `PHISHING_untrusted_only_inbound_document_signature_keywords_link_with_no_reputation` (`ACTIVE` by default). This rule will catch more document signature phishing.
  * \[SA-14855] Rules: Add new high-confidence rule `SPAM_ml_untrusted_only_inbound_non_reputable_link` (`ACTIVE` by default) to block more spam.
  * \[SA-14932] Rules: Add high confidence rule `PHISHING_topic_invoice_matches_office_interaction_document_signature_keyword` (`ACTIVE` by default). This rule blocks more invoice phishing, where the attack is attached as an office document.
  * \[SA-14944] Rules: Add new high-confidence rule `PHISHING_sender_unknown_never_delivered_cloud_mailer_displayname_popular` (`ACTIVE` by default) to block phishing mails sent through reputable cloud services.
  * \[SA-14959] Rules: Add new high-confidence rule `PHISHING_sender_unknown_never_delivered_cloud_mailer_displayname_popular` (`ACTIVE` by default) to block phishing mails disguised as bounce messages.
  * \[SA-15005] Rules: Add new high-confidence rule `PHISHING_untrusted_nonreputable_body_matches_voicemail_password_popular_guarded_email` (`ACTIVE` by default). The rule catches more voice mail phishing impersonating popular services.
  * \[SA-15024] Rules: Fix for a missing space in default subject rewrites. An earlier update introduced a bug where subject rewrites were missing the space between the prefix and the subject. E.g., the subject would become `[SPAM]Subject` instead of `[SPAM] Subject`.

  ### Available via upgrade

  * \[SA-14999] MTA: Prepare MTAs for the upcoming release-11 trust model changes.
  * \[SA-15006] MTA: Address changed metric label, affecting the Postfix queue size alert and the MTA monitoring dashboard.
  * \[SA-12808] XCC: Mail header additions triggered via rules are now mentioned in the detail view in tab `Classifiers & Rules`.
  * \[SA-14864] XCC: Prevent error log on case isolation when repeatedly trying to isolate a message.
  * \[SA-13868] XCC: Avoid updating the relationship score when a campaign is set up to deliver the message with a malicious verdict. This avoids the build-up of trust for campaigns that, e.g., only do a subject rewrite instead of quarantining the messages.
  * \[SA-14864] XCC: Improve error message when quarantine release fails in SSQ portal.
</Update>

<Update label="Release 10.0.2" description="November 24, 2025">
  ### Rolled out via xCloud

  * \[SA-12158] Rules: Add new high-confidence rules `SPAM_topic_sexual_content_package_delivery_non_reputable_links` and `SPAM_ml_adult_keywords_non_reputable_links_state` (`ACTIVE` by default). Additionally, broaden the existing `SPAM_ml_topic_sexual_content` rule and improve `ADAPT_spam_confidence_low_image_only`. These changes help with catching ongoing spam waves that promote adult products.
  * \[SA-14155] Rules: Add new high-confidence rule `PHISHING_reputable_freemail_forged_reply_to_shortened_embedded_link` (`ACTIVE` by default) to catch more phishing sent via reputable services.
  * \[SA-14443] Rules: Add new high-confidence rule `SPAM_untrusted_non_reputable_only_inbound_very_young_sender` (`ACTIVE` by default) to block spam from newly registered domains.
  * \[SA-14443] Rules: Disable `PHISHING_common_domains` as it is redundant with other rules.
  * \[SA-14778] Rules: Add new high-confidence rule `PHISHING_topic_package_delivery_untrusted_sender_only_inbound_one_suspicious_link` (`ACTIVE` by default). This rule improves our ability to block package delivery phishing.
  * \[SA-14847] Rules: Add new high-confidence rule `PHISHING_address_parsing_error_matches_phishing_keyword_no_auth` (`ACTIVE` by default). The rule blocks more unauthenticated phishing.
  * \[SA-14868] Rules: Add new high-confidence rule `PHISHING_sender_is_social_network_subject_matches_urgency_multiple_phishing_keywords` (`ACTIVE` by default). This rule improves our ability to block phishing attacks sent from legit Meta infrastructure.
  * \[SA-14903] Rules: Add new high-confidence rule `SPAM_untrusted_non_reputable_domain_only_inbound_link_without_dns` (`ACTIVE` by default). The rule catches spam waves that attempt to evade detection by making the link domain resolve only after delivery.

  ### Available via upgrade

  * \[SA-14850] XCC: Intermediate validation errors in `auth.yml` triggered via expert configuration editor should not be logged as ERROR.
  * \[SA-14852] MTA: Extract a few more relevant properties from iCalendar files. With the additional properties, we can better detect calendar invite impersonation.
  * \[SA-14904] MTA: Add attribute `pipeline` to audit log message types: `trace.msg_analysis.start`, `trace.msg_analysis.resume`, `trace.msg_analysis.complete`, `trace.msg_verdict`.
  * \[SA-14907] MTA, XCC: Upgrade `containerd` to address `runC` vulnerability CVE-2025-31133, CVE-2025-52565, and CVE-2025-52881.
  * \[SA-14561] UI: In the authentication status next to the `FROM` address, avoid showing failed or passed checks that did not directly contribute to the authentication status of the `FROM` address. The previous behavior lead to confusion about the exact reason why the `FROM` is considered authenticated or not.
  * \[SA-14885] UI: Fix an issue that automatically unticked the Rerpot Misclassification checkbox when writing a comment in the resolve dialog.
  * \[SA-14913] UI: Fix issue that made the time range selection date-picker to be mis-placed when choosing a custom date.
  * \[SA-14946] UI: Fix an issue where the empty state in Abuse mailbox card was not centered.
</Update>

<Update label="Release 9.0.6" description="November 24, 2025">
  ### Rolled out via xCloud

  * \[SA-12158] Rules: Add new high-confidence rules `SPAM_topic_sexual_content_package_delivery_non_reputable_links` and `SPAM_ml_adult_keywords_non_reputable_links_state` (`ACTIVE` by default). Additionally, broaden the existing `SPAM_ml_topic_sexual_content` rule and improve `ADAPT_spam_confidence_low_image_only`. These changes help with catching ongoing spam waves that promote adult products.
  * \[SA-14155] Rules: Add new high-confidence rule `PHISHING_reputable_freemail_forged_reply_to_shortened_embedded_link` (`ACTIVE` by default) to catch more phishing sent via reputable services.
  * \[SA-14443] Rules: Add new high-confidence rule `SPAM_untrusted_non_reputable_only_inbound_very_young_sender` (`ACTIVE` by default) to block spam from newly registered domains.
  * \[SA-14443] Rules: Disable `PHISHING_common_domains` as it is redundant with other rules.
  * \[SA-14778] Rules: Add new high-confidence rule `PHISHING_topic_package_delivery_untrusted_sender_only_inbound_one_suspicious_link` (`ACTIVE` by default). This rule improves our ability to block package delivery phishing.
  * \[SA-14847] Rules: Add new high-confidence rule `PHISHING_address_parsing_error_matches_phishing_keyword_no_auth` (`ACTIVE` by default). The rule blocks more unauthenticated phishing.
  * \[SA-14868] Rules: Add new high-confidence rule `PHISHING_sender_is_social_network_subject_matches_urgency_multiple_phishing_keywords` (`ACTIVE` by default). This rule improves our ability to block phishing attacks sent from legit Meta infrastructure.
  * \[SA-14903] Rules: Add new high-confidence rule `SPAM_untrusted_non_reputable_domain_only_inbound_link_without_dns` (`ACTIVE` by default). The rule catches spam waves that attempt to evade detection by making the link domain resolve only after delivery.

  ### Available via upgrade

  * \[SA-14850] XCC: Intermediate validation errors in `auth.yml` triggered via expert configuration editor should not be logged as ERROR.
  * \[SA-14561] UI: In the authentication status next to the `FROM` address, avoid showing failed or passed checks that did not directly contribute to the authentication status of the `FROM` address. The previous behavior lead to confusion about the exact reason why the `FROM` is considered authenticated or not.
  * \[SA-14907] MTA, XCC: Upgrade `containerd` to address `runC` vulnerability CVE-2025-31133, CVE-2025-52565, and CVE-2025-52881.
</Update>

<Update label="Release 10.0.1" description="November 10, 2025">
  ### Rolled out via xCloud

  * \[SA-11326] Rules: Add new `PHISHING_ml_sender_account_name_character_count_large_document_signature_keyword` (`ACTIVE` by default). This rule will catch more document signature phishing.
  * \[SA-11326] Rules: Update `SPAM_ml_young_sender` to catch even more spam from young senders.
  * \[SA-14839] Rules: Re-enable `#malware` and `#exploit` for use in campaigns.

  ### Available via upgrade

  * \[SA-14800] XCC: Fix issue where messages with recipients containing `=` characters would end up in state `SMTP ERROR` even though they were delivered successfully.
  * \[SA-14802] XCC: Fix issue which prevented users with global analyst permissions to see quarantines specified outside of the tenant they are belonging to.
  * \[SA-14813] XCC: Fixed issue that moved signed received headers at the top of the headers list.
  * \[SA-14786] MTA: Fix issue when calculating `result_publish_latency` while changing the time zone offset (daylight saving time). **When applied, this bugfix may cause the metric to temporarily spike.**.
  * \[SA-14792] MTA, XCC: Fix issue preventing us from displaying rDNS information when it would be available.
  * \[SA-14820] MTA: Fix issue where a special payload could trigger an out of memory situation, forcing Core to restart.
  * \[SA-14832] MTA, XCC: Upgrade Docker Compose to address CVE-2025-62725.
  * \[SA-14835] MTA: Fix issue where lengthy pipeline repository init fails leaving the system with no working scan pipelines.
  * \[SA-14827] MTA: Improve error handling fo results in case of an abrupt shutdown.
  * \[SA-14843] MTA: Improve error handling for results which can not be published to xcc.
</Update>

<Update label="Release 9.0.5" description="November 10, 2025">
  ### Rolled out via xCloud

  * \[SA-11326] Rules: Add new `PHISHING_ml_sender_account_name_character_count_large_document_signature_keyword` (`ACTIVE` by default). This rule will catch more document signature phishing.
  * \[SA-11326] Rules: Update `SPAM_ml_young_sender` to catch even more spam from young senders.
  * \[SA-14765] Rules: A set of new and improved rules to address various phishing and spam cases (all high-confidence and `ACTIVE` by default):

    * `PHISHING_untrusted_non_reputable_subject_guarded_or_popular_suspicious_link`
    * `PHISHING_untrusted_only_inbound_displayname_and_subject_popular`
    * `SPAM_untrusted_only_inbound_displayname_popular_each_link_nonreputable`
    * `SPAM_untrusted_only_inbound_qr_code_link_similar_to_popular`

  ### Available via upgrade

  * \[SA-14720] MTA: Fix problem where mta would report an error about delayed log messages after restart even though this was not the case.
  * \[SA-14786] MTA: Fix problem when calculating `result_publish_latency` while changing the time zone offset (daylight saving time). **When applied, this bugfix may cause the metric to temporarily spike.**.
  * \[SA-14792] MTA, XCC: Fix issue preventing us from displaying rDNS information when it would be available.
  * \[SA-14820] MTA: Fix issue where a special payload could trigger an out of memory situation, forcing Core to restart.
  * \[SA-14827] MTA: Improve error handling fo results in case of an abrupt shutdown.
  * \[SA-14832] MTA, XCC: Upgrade Docker Compose to address CVE-2025-62725.
  * \[SA-14835] MTA: Fix issue where lengthy pipeline repository init fails leaving the system with no working scan pipelines.
  * \[SA-14843] MTA: Improve error handling for results which can not be published to xcc.
  * \[SA-14727] UI: Fix issue where the wrong tooltip was shown for headers marked as possibly forged.
  * \[SA-14766] UI: Fix issue that prevented the correct automation rate from being shown in the dashboard.
  * \[SA-14800] XCC: Fix issue where messages with recipients containing `=` characters would end up in state `SMTP ERROR` even though they were delivered successfully.
  * \[SA-14804] XCC: Fix bug in permission check for case isolation.
  * \[SA-14802] XCC: Fix issue which prevented users with global analyst permissions to see quarantines specified outside of the tenant they are belonging to.
  * \[SA-14813] XCC: Fixed issue that moved signed received headers at the top of the headers list.
</Update>

<Update label="Release 10.0.0" description="October 31, 2025">
  ### Highlights

  * \[SA-9095] Core: Support iCalendar file analysis: URL extraction, content matching, and attachment extraction. This change addresses the uptick in phishing attacks using `.ics` files.
  * \[SA-5498] UI: The resolve case dialog has a new layout. Benign/malicious toggles were removed, replaced with a searchable template and verdict selector.
  * \[SA-9843] XCC: On campaign creation, the query will be checked for any tags that are not supported. E.g., if the query contains the tag `#quarantine`, it is now not possible to create a campaign. This additional validation ensures that only tags that are set before campaign rules can be used in campaign queries.

  ### UX improvements and fixes

  * \[SA-9843] XCC: Adding a user tag to a message is now prevented if that tag has the same name as a built-in tag. This prevents confusion between user tags and tags that are assigned by xorlab rules.
  * \[SA-12566] UI: Report misclassification is only auto-selected when resolving a case where the chosen verdict is different from the one initially assigned.
  * \[SA-13944] UI: A new column in the main list view shows the overall relationship score between sender and recipient.
  * \[SA-13991] UI: The dashboard "Email Security" box tooltips and counts now only reflect blocked, subject-rewritten, or bannered messages.
  * \[SA-14368] UI: The dashboard header side panels with explanation details have been redesigned. They now contain detail explanations and breakdowns for the model computations, the explanations are accessible via blue-highlighted rows.
  * \[SA-14454] UI: The similarity tab now uses the "same sender" default filter if no similar content is found.
  * \[SA-14456] UI: The similarity tab now suggests predefined filters with counts, they can be clicked to activate immediately.
  * \[SA-14449]\[SA-14450]\[SA-14468] UI: Blacklist/whitelist dialogs were refreshed with a cleaner, more intuitive structure.
  * \[SA-14580] UI: Fix a bug where the browser back button was not working while showing the error page.
  * \[SA-14595] UI: Fix a bug where the relationship tooltip was flickering in certain cases.
  * \[SA-14631] UI: Improve error message when trying to adding reserverd tags.
  * \[SA-14665] UI: Only one empty filter of the same type can be added to the search bar. When trying to add a filter which is already part of the searchbar but it is empty, the previous filter will be moved to the end and reopened.
  * \[SA-14666] UI: Fix a bug where in certain cases the search history remained open.
  * \[SA-14686] UI: Encrypted files no longer have orange background.
  * \[SA-14669] UI: Improve the search in the list configurator.
  * \[SA-14671] UI: Show the table header for the relationship score column in the message lists.
  * \[SA-14690] UI: Fix Abuse Mailbox chart layout for small screens.
  * \[SA-14692] UI: Clicking outside the image or video, while the preview dialog is open, will close it.
  * \[SA-14707] UI: Fix a bug where the Abuse Mailbox was displaying a really tiny in some cases.
  * \[SA-14708] UI: Fix a bug where the url params were not cleared in some conditions.
  * \[SA-14710] UI: Fix a bug where dragging multiple files into the dropzone caused infinite loading.
  * \[SA-14711] UI: Fix a bug where the table action buttons would disappear from the attachemnts table.
  * \[SA-14712] UI: Fix damages prevented calculations.
  * \[SA-14713] UI: A wrong page was displayed after fixing a deprecated campaign.
  * \[SA-14716] UI: Fix a bug where the autocomplete glitched when the pointer was over the list and arrow down was pressed.
  * \[SA-14728] UI: Fix a bug where long email addresses were not displayed correctly in the relationship tooltip.

  ### Multi-Tenancy improvements

  * The parameter `authTenantId` inside `guarded_tenants.yml` is now considered deprecated. While it is still supported, we recommend to use `name` instead. All features that rely on `authTenantId` will use `name` if no `authTenantId` is specified.

  ### Detection improvements

  * \[SA-6528]\[SA-9095] Core: Support URL extraction, content matching, and attachment extraction for iCalendar files. This change addresses the uptick in phishing attacks using `.ics` files.
  * \[SA-14563] Rules: Added two new tags that will empower SOCs to use previous actions (isolaton and release) in e.g. campaigns:

    * `#senderisolated`: Set if a message from the same email address (FROM) has previously been isolated.
    * `#senderreleased`: Set if a message from the same email address (FROM) has previously been released from quarantine.

  ### Breaking changes

  * \[SA-9843] XCC: The tag `#quarantine` and `#deliver` cannot be used anymore in campaigns. Existing campaigns with those tags will still work, but marked as deprecated in the GUI.

  * \[SA-14395] XCC: This concerns only xorlab M365 integrations. The file `client_access_cidr` containing M365 IPs has been cleaned up:

    * All M365 IPs have been moved into a hidden `client_access_m365_cidr` file that is managed now by xorlab (via `ag_global`).
    * `client_access_cidr` is now empty and can be used on-demand like `client_access`.
    * If you added custom entries in `client_access_cidr`, save them before the upgrade to apply them afterward again.

  * \[SA-14398] Rules: This change updates the behavior of `fp_low.properties`, by **removing** the following entries:

    * `FILTER_executable_state=PASSIVE`
    * `FILTER_flash_state=PASSIVE`
    * `FILTER_iso_state=PASSIVE`
    * `FILTER_legacy_archive_state=PASSIVE`
    * `FILTER_shortcut_state=PASSIVE`
    * `FILTER_windows_script_state=PASSIVE`

    This means that the above mentioned `FILTER-rules` will now be `ACTIVE` by default, even if `fp_low.properties` is activated. To continue with the old behavior, please add the above state-entries to `local.properties`.

  * \[SA-14420] XCC: The property `bccFallbackDomain` in `guarded_tenants.yml` has been removed and is now replaced implicitly by the first guarded domain entry. This only affects the domain shown in the tenant selection dialog in multi-tenant environments.

  * \[SA-14541] Rules: This release removes the verdict `UNTRUSTED`, which was only applied to outgoing messages.

  * \[SA-14541] Rules: The verdict `TRUSTED` is now only applied when there is a high enough level of trust between the sender and the recipient. In previous releases, messages would also get the verdict `TRUSTED` if the sender domain had enough local reputation.

  ### Bugfixes and improvements

  * \[SA-14170] MTA: Bugfix problem where password cracking would fail for zip files with unusual names. This could have lead to situations where mails could not be released via Attachment Unlock.
  * \[SA-14423] MTA: Fix issue where results could not be published properly to xcc after a processing timeout.
  * \[SA-14402] XCC: Upgrade Elastic stack from major version 7 to major version 8.
  * \[SA-14598] XCC: Improve performance of message and quarantine cleanup.
  * \[SA-14606] MTA: Silence processing error when analzying excessively large image files.
  * \[SA-14609] XCC: Bugfix problem where config was reloaded even tough the authentication service was still starting up.
  * \[SA-14651] MTA: Bugfix problem where pdf files with excessive numbers of embedded objects would cause delays.
  * \[SA-14660] XCC: Upgrade redis dependency to mitigate `CVE-2025-49844`.
  * \[SA-14720] MTA: Fix problem where mta would report an error about delayed log messages after restart even though this was not the case.
</Update>

<Update label="Release 9.0.4" description="October 24, 2025">
  ### Rolled out via xCloud

  * \[SA-14601] Rules: Add new high-confidence rule `PHISHING_untrusted_embedded_shortened_cloud_storage_is_exactly_one` (`ACTIVE` by default). This rule targets phishing emails where the attacker uses a combination of embedded and shortened links.

  * \[SA-14613] Rules: Add new high-confidence rule `PHISHING_untrusted_nonreputable_voicemail_keywords` (`ACTIVE` by default). This rule addresses phishing emails claiming that the target has a recorded voicemail.

  * \[SA-14616] Rules: A set of new and improved rules to address various phishing and spam cases (all high-confidence and `ACTIVE` by default):

    * `PHISHING_topic_package_delivery_untrusted_only_inbound_links_non_reputable`
    * `PHISHING_untrusted_non_reputable_only_inbound_cloudstorage_link`
    * `PHISHING_untrusted_only_inbound_body_and_subject_multiple_keywords_popular_displayname_and_links`
    * `PHISHING_untrusted_only_inbound_common_phishing_link_without_reputation`
    * `PHISHING_untrusted_only_inbound_matches_keywords_body_contains_unicode_block_elements`
    * `SPAM_untrusted_only_inbound_html_mostly_image_data_url`

  * \[SA-14619] Rules: Add new high-confidence rule `PHISHING_untrusted_non_reputable_only_inbound_cloudstorage_with_document_signature_keywords` (`ACTIVE` by default). This rule addresses phishing emails asking to sign a document.

  * \[SA-14739] Rules: Add new rules `BEC_bcc_only_html_short_link_display_text_matches_keyword` and `BEC_bcc_only_cloud_storage_link_embedded_link` (`ACTIVE` by default). These rules block attacks from compromised accounts claiming to share an important document.

  * \[SA-14756] Rules: Add new high-confidence rule `SPAM_ml_topic_sexual_content` (`ACTIVE` by default). This rule ensures that explicit sexual content is blocked.

  * \[SA-14776] Rules: Update `SPAM_nonreputable_multiple_adult_keywords_all_links_negligible_reputation` to block more spam.

  ### Available via upgrade

  * \[SA-14701] UI: Fixed issue that triggered an error 500 when accessing a tenant-specific saved search.
  * \[SA-14423] MTA: Fix issue where results could not be published properly to xcc after a processing timeout.
  * \[SA-14606] MTA: Silence processing error when analzying excessively large image files.
</Update>

<Update label="Release 9.0.3" description="October 14, 2025">
  <Note>
    **SA-14660: CVE-2025-49844**

    This patch fixes CVE-2025-49844. It is a vulnerability in the Redis database used on the XCC. There is no immediate risk of exploitation as the Redis access is restricted to authenticated users. Additionally, for on-premise customers, Redis is normally not exposed to an external network. However, we still recommend to update to 9.0.3 as this is a publicly known Redis vulnerability.
  </Note>

  ### Rolled out via xCloud

  * \[SA-14425] Rules: Add new high-confidence rule `SPAM_untrusted_non_configured_firebase_sender_not_released` (`ACTIVE` by default) to block spam sent through `firebaseapp.com`.

  * \[SA-14513] Rules: Add 7 new high confidence rules (all `ACTIVE` by default). These rules will improve our general detection in multiple areas:

    * `PHISHING_sender_unknown_never_delivered_link_negligible_local_global_reputation_matches_popular`
    * `PHISHING_untrusted_sender_only_inbound_body_matches_guarded_email`
    * `PHISHING_untrusted_sender_domain_only_inbound_matches_document_signature_keyword`
    * `SPAM_untrusted_sender_domain_only_inbound_matches_popular_service_and_urgency`
    * `PHISHING_untrusted_matches_multiple_phishing_keywords_and_urgency`
    * `PHISHING_topic_invoice_untrusted_nonreputable_shortened_no_local_reputation`
    * `PHISHING_untrusted_cracked_office_interaction_keywords`

  * \[SA-14557] Rules: Add a new high-confidence rule `PHISHING_sender_unknown_never_delivered_subject_and_body_multiple_document_signature_keywords` (`ACTIVE` by default) to improve our detection of document signature phishing.

  * \[SA-14618] Rules: Fix `ADAPT_phishing_override_based_on_risk_score` such that less benign emails from popular senders get blocked.

  * \[SA-14627] Rules: Add a new high-confidence rule `SPAM_sender_unknown_never_delivered_subject_matches_urgency_and_phishing_replyto_not_from` (`ACTIVE` by default) to address spam mails that are urging the target to claim a large amount of money.

  * \[SA-14679] Rules: Update the rule `BEC_bcc_only_html_short_link_image_file_body_matches_popular_service` to block a broader variety of BEC cases.

  ### Available via upgrade

  * \[SA-14170] MTA: Bugfix problem where password cracking would fail for zip files with unusual names. This could have lead to situations where mails could not be released via Attachment Unlock.
  * \[SA-14598] XCC: Improve performance of message and quarantine cleanup. Notice that next xcc start may take a bit longer than usual.
  * \[SA-14609] XCC: Bugfix problem where config was reloaded even tough the authentication service was still starting up.
  * \[SA-14651] MTA: Bugfix problem where pdf files with excessive numbers of embedded objects would cause delays.
  * **\[SA-14660]** XCC: Upgrade redis dependency to mitigate `CVE-2025-49844`.
</Update>

<Update label="Release 9.0.2" description="September 29, 2025">
  ### Rolled out via xCloud

  * \[SA-14497] Rules: New rules to address various phishing cases (high-confidence and `ACTIVE` by default)

    * `PHISHING_topic_account_untrusted_displayname_guarded_no_or_suspicious_link`
    * `PHISHING_untrusted_displayname_guarded_or_phishy_mostly_image_subject_phishy`
    * `PHISHING_untrusted_domain_only_inbound_one_cloud_storage_link_from_outbound_address`
    * `PHISHING_untrusted_only_inbound_document_subject_phishy_qr_code_keywords`
    * `PHISHING_untrusted_only_inbound_non_reputable_only_media_files_phishing_keywords`

  * \[SA-14497] Rules: Improved rules to address various malware cases (high-confidence and `ACTIVE` by default)

    * `MALWARE_encrypted_archive`: Now enabled in more rule profiles.
    * `MALWARE_office_encrypted`: Now enabled in more rule profiles.

    If the improved malware detection causes benign emails to be quarantined, consider adding the sender addresses to the `Low trusted sender addresses` list.

  ### Available via upgrade

  * \[SA-14566] MTA: Silence error log in case of duplicate DKIM signatures.
  * \[SA-14590] MTA: Fix bug where attachment unlock would fail for message that were analyzed before upgrading to release 9.0.
  * \[SA-14577] UI: Fix a bug where the previous query was saved in the history instead of the current one.
  * \[SA-14600] XCC: Sync major version of PostgreSQL client tools in XCC containers.
</Update>

<Update label="Release 9.0.1" description="September 24, 2025">
  ### Rolled out via xCloud

  * \[SA-14261] Rules: Add new high-confidence rule `PHISHING_untrusted_sender_only_inbound_displayname_matches_popular_service` (`ACTIVE` by default). This rule will block more phishing where the attacker imitates a popular sender.
  * \[SA-14469] Rules: Add new high-confidence rule `PHISHING_untrusted_body_matches_multiple_document_signature_keywords_subject_matches_guarded_name` (`ACTIVE` by default). This rule will improve our ability to block document signature phishing, where the attacker impersonates a guarded name.
  * \[SA-14484] Rules: Add new high-confidence rule `PHISHING_untrusted_freemail_body_matches_qr_code_keyword_matches_guarded` (`ACTIVE` by default). This new phishing rule blocks QR-code phishing, where the attacker impersonates a guarded name.

  ### Available via upgrade

  * \[SA-14230] XCC: Fix issue where a released mail could be unlocked and potentially be delivered twice.
  * \[SA-14464] XCC: When isolating a message on M365, the result is still marked as `ISOLATED` even if the message has been deleted by the end-user and could not be found in the mailbox any more.
  * \[SA-14517] UI: Revert event click behavior on the message list rows.
  * \[SA-14521] XCC: Fix issue where errors would be logged due to invalid email addresses.
  * \[SA-14530] XCC: Fix issue where SQL errors would be logged right after XCC startup.
  * \[SA-14531] UI: Fix regression where the SSQ list view would show a disabled release-button even tough releasing was not possible.
  * \[SA-14534] MTA: Fix bug where we would not fully recover from decrypting a corrupted MS Office file.
  * \[SA-14536] UI: Add search trigger when pressing the Enter key on the numeric pad.
  * \[SA-14537] XCC: Fix issue where M365 message isolation health check would fail when testing API capabilities for on-premise accounts.
  * \[SA-14562] MTA: Limit number of postfix log messages being processed to prevent `ag_mta` going OutOfMemory.
  * \[SA-14564] MTA: Fix problem where results for mails which had their attachments removed were stuck in publishing.
</Update>

<Update label="Release 9.0.0" description="September 12, 2025">
  ### Highlights

  * \[SA-12649] XCC: New SSQ release feature: End-users can now request the release of quarantined emails directly via their SSQ. The feature can be enabled individually per quarantine.
  * \[SA-13771] XCC: Hot-reload for authentication settings: Configuration changes to LDAP, SAML, and other authentication integrations no longer require a service restart. Manual restarts also no longer terminate active user sessions.
  * \[SA-13765] UI: Enhanced message authentication insights: SPF, DKIM, and DMARC alignment results are now summarized in the message detail view. Analysts can also drill down into detailed results for each method. With this release, all DNS-based authentication checks are consistently executed for every email, ensuring complete and reliable visibility.
  * \[SA-14284] XCC: Improved multi-tenant support: SSQ configuration and data retention settings are now fully multi-tenant capable and can be managed separately for each domain.

  ### UX improvements and fixes

  * \[SA-6187] UI: Allow the middle mouse button to open links in a new tab.
  * \[SA-13356] UI: The Open Case Priorities widget in the dashboard now displays cases that do not have a priority assigned.
  * \[SA-13636] UI: The trends section in the dashboard now displays the threats blocked according to the selected time range.
  * \[SA-13935] UI: The `Home`, `End`, `Page Up`, and `Page Down` keys no longer interact with the search bar drop down. These keys now always move the cursor.
  * \[SA-14006] UI: The insights section in the dashboard has been revised, with additional items now included in the Graymail breakdown section.
  * \[SA-14015] UI: The dashboard header items are now clickable and include an explanation of how the value is computed, including the formulas and a breakdown of the computation.
  * \[SA-14407] UI: Fix the campaign header information alignment, such as Message Action or Resolve Action, in the campaign page.

  ### Multi-Tenancy improvements

  * \[SA-13920] MTA: A tenant can now have more than one `tenantSelector` configured. A `tenantSelector`'s value can now match based on a regex pattern.
    See /9.0/guarded\_tenants\_yml

  ### Detection improvements

  This section lists only the detection improvements that require a version upgrade. Most other detection enhancements are rolled out gradually and do not require an update.

  * \[SA-14163] XCC: Update counters also for `To` and `Cc` addresses. With this change, seeing an address in the `To/Cc` position of an outgoing or internal email counts as having seen & delivered an email to that address. As a result, the next email from that address will not have the `#senderfirstcontact` tag.

  ### Breaking changes

  * \[SA-14037] Rules: The following MTA trust lists were removed:

    * `MTA EHLO trust list for guarded (regex)`
    * `MTA EHLO trust list for partner (regex)`
    * `MTA RDNS trust list for guarded (regex)`
    * `MTA RDNS trust list for partner (regex)`

    If you're using any of these lists and want to keep these MTA entries trusted, make sure to manually migrate them to the `trustedMTAProfiles` in `active_guard.yml`. See more information here: [https://docs.xorlab.com/9.0/trusted-mtas/](https://docs.xorlab.com/9.0/trusted-mtas/).

    Also removed are the following rule templates: `sender_is_trusted_ehlo_for_guarded.xml`, `sender_is_trusted_ehlo_for_partner.xml`, `sender_is_trusted_reverse_dns_for_guarded.xml` and `sender_is_trusted_reverse_dns_for_partner.xml`.

    If any custom rule exists that relies on these templates (e.g., if it uses `<template name="sender_is_trusted_ehlo_for_guarded"/>` anywhere), the rule will stop working.

  * \[SA-14284] XCC: All configuration parameters related to data retention were moved from `xcc.yml` to `guarded_tenants.yml`, see [Data Retention](https://docs.xorlab.com/9.0/data-retention/?h=reten#configuration). Additionally, all SSQ related configuration parameters were also moved from `xcc.yml` to `guarded_tenants.yml`, see [SSQ](https://docs.xorlab.com/9.0/ssq-self-service-quarantine/). No action is required from your side.

  * \[SA-14354] MTA: Only consider `TXT` DNS records when verifying SPF, ignore `SPF` DNS records. **Please ensure all your guarded domains have valid SPF entries in their `TXT` DNS records.**

  ### Deprecations

  * \[SA-13855] UI: Removed access to the Explore view in the sidebar. The data remain accessible in Kibana via the Insights sidebar menu and under the "Messages Overview" dashboard. The permission `xcc_sidebar_explore` is removed from all roles.
  * \[SA-13855] XCC: Removed the configuration options `elasticSearch.exploreGlobalTimeoutS` that affected the maximum waiting time for the result in the Explore view.
    This configuration is not necessary because the feature has been removed in this release.
  * \[SA-13855] XCC: Remove the following configuration options `elasticSearch.exportScrollMaxDurationS`, `elasticSearch.exportGlobalTimeoutS`, `elasticSearch.exportMaxNumberOfResults`, `elasticSearch.taggingScrollMaxDurationS`, and `elasticSearch.taggingGlobalTimeoutS` as they were unused.
    This configuration is not necessary because it was used by previously removed features.

  ### Bugfixes and improvements

  * \[SA-7483] MTA, XCC: Loki and Promtail configuration is now hot-reloaded.

  * \[SA-9755] MTA: Fix a bug where subject-rewrites were not applied to quarantine-released messages.

  * \[SA-13212] MTA: Fix postfix warning: `support for parameter "smtp_use_tls" will be removed; instead, specify "smtp_tls_security_level"`.

  * \[SA-13672] MTA: xorlab now performs a reverse DNS lookup locally if the border MTA does not provide this information.

  * \[SA-13758] MTA: Refactored `audit` module of `ag_mta` to achieve more reliable email delivery status updates.

  * \[SA-13788] Rules: Rename rule profiles to be consistent and easier to understand:

    * `global_only_spam_rewrites_and_no_user_notifications.properties` -> `default_actions.properties`
    * `profile_no_subject_rewrite_no_quarantine.properties` -> `no_subject_rewrite_no_quarantine.properties`
    * `profile_no_auto_feedback.properties` -> `no_auto_feedback.properties`
    * `profile_default_dana.properties` -> `default_dana.properties`
    * `profile_default_dana_monitoring.properties` -> `monitoring_dana_offline_only.properties`
    * `profile_no_dana_except_for_specific_recipients.properties` -> `no_dana_except_for_specific_recipients.properties`
    * `profile_fp_sensitive.properties` -> `fp_sensitive.properties` (this profile will be deprecated and fully replaced with `fp_low.properties` in future releases)
    * `profile_fp_low.properties` -> `fp_low.properties`
    * `global_initialization.properties` -> `learning_mode.properties`
    * `global_bcc_threat_analyst.properties` -> `monitoring_mode.properties`
    * `global_default.properties` -> `default.properties`

  * \[SA-13880] MTA: Fix a bug where SMTP envelope information is lost in certain cases when unlocking an attachment.

  * \[SA-13897] UI: Improved data loading animations in the Self-Serviced Quarantine.

  * \[SA-13906] MTA: Fix a bug where an email would be marked as erroneous after exceeding the processing time limit.

  * \[SA-13908] XCC: Remember active user sessions during Auth restarts caused by config changes or manual restarts. User sessions are still terminated during an Auth version upgrade.

  * \[SA-13921] UI: The root domain information is always shown for URLs in the message detail view.

  * \[SA-13966] MTA: Fix a `NullPointerException` triggered in test quarantine digest email notification.

  * \[SA-14012] XCC: Fix bug where XCC would log `sys.ready` twice on startup.

  * \[SA-14066] XCC: Reverse proxy does not offer the following weak SSL ciphers anymore: `ECDHE-RSA-AES256-GCM-SHA512`, `DHE-RSA-AES256-GCM-SHA512`, `ECDHE-RSA-AES256-SHA384`.
    This change follows latest recommendations of Mozilla ([https://wiki.mozilla.org/Security/Server\_Side\_TLS](https://wiki.mozilla.org/Security/Server_Side_TLS)).

  * \[SA-14106] MTA: Fix an issue where `.pub` files were mistakenly analyzed for the presence of VBA macros.

  * \[SA-14146] XCC: Fix problem where an underscore in a custom quarantine would trigger an error. Allowed quarantine names must match this regular expression: `[0-9A-Za-z_-]+`.

  * \[SA-14148] MTA: Move Postfix `client_access_tenant` check such that mail header `PREPEND` actions are only applied once per mail and not once per recipient.

  * \[SA-14168] MTA: Email transformations (like adding a header or a subject rewrite) are now also applied to emails released from quarantine.

  * \[SA-14238] Monitoring: Grafana update to apply fixes for [CVE-2025-6197 and CVE-2025-6023](https://grafana.com/blog/2025/07/17/grafana-security-release-medium-and-high-severity-fixes-for-cve-2025-6197-and-cve-2025-6023/).

  * \[SA-14336] XCC: Fix problem where release-8 upgrade would fail because of an improper git configuration.

  * \[SA-14403] XCC: Upgrade PostgreSQL to mitigate CVE-2025-8713, CVE-2025-8714 and CVE-2025-8715.

  * \[SA-14433] MTA: Audit log `trace.msg_verdict` will also report mail envelope information `sender` and `recipients`.

  * \[SA-12695] XCC: xorlab now collects usage metrics such as guarded domains and number of seats. This data is sent to xCloud.
</Update>


# Email Scanning API
Source: https://docs.xorlab.com/latest/abby

Submit a message over HTTP and get its analysis result back synchronously, instead of routing it via SMTP. An advanced integration for narrow cases.

For most automation use cases, use the [Rule List API](/latest/api-rule-list-management), which is the primary public API for xorlab.

<Note>
  **Before you start**

  Please contact our support for the latest changes in xorlab API setup before you start configuring the API.
</Note>

## Enable the API

1. First, activate the API as the source for receiving emails by xorlab. Open the `activeguard/core/active_guard.yml` file in [Expert Editor](/latest/expert-editor) and add the following line to `scanSources`:
   ```yaml theme={null}
   scanSources:
     restApi {}
   ```
2. Add these two lines and set their values to the same value as `mainWorkerCount`. If `mainWorkerCount` is not set, use the default value of `20`:
   ```yaml theme={null}
   ## Guard Request Processing Configuration
   ## Maximum number of guard requests in processing. After that, we (soft)reject with SMTP error 451.
   maxGuardRequestsInProcessing: 20
   ## Threshold for GuardRequests in progress, before we start with linear throttling
   guardRequestThrottleThreshold: 20
   ```
3. Now, configure the Email Scanning API in Expert Editor by navigating to the `abby/abby/abby.yml` file. When you open it, the following content appears:
   ```yaml theme={null}
   # (Required) A map of service provider definitions.
   # The following map entries are supported and mandatory:
   #  - core
   serviceProviders:
    core:
      # Service provider definition, see documentation of active_guard.yml for details.
      hosts:
        - https://mx1.xyz.activeguard.cloud:9785
        - https://mx2.xyz.activeguard.cloud:9785
      # longRequestTimeout is used for synchronously enqueuing messages
      longRequestTimeout: 3600000  # 1h
   ## (Optional) A list of static API token definitions.
   #staticApiTokens:
   #  #(Mandatory) The name of the token user.
   #  - name: <client/customer name>
   #    # (Mandatory) The token used for authentication. Generate a random string with for example: openssl rand -base64 64.
   #    token: <a secure token>
   #    # (Optional) A list of permissions associated with this token.
   #    permissions: []
   staticApiTokens:
    - name: demo
      token: <32-byte word>
   ```
4. Under `hosts`, adjust the addresses of the xorlab MTAs such that they match your deployment:
   ```yaml theme={null}
     hosts:
        - https://mx1.xyz.activeguard.cloud:9785
        - https://mx2.xyz.activeguard.cloud:9785
   ```
5. Under `staticApiTokens`, enter the name of your bearer authentication token and its value. For SaaS instances, the token will be preconfigured and provided by xorlab; for on-prem instances, we recommend using the `openssl rand -hex 32` command to generate the token (32 bytes or 64 hex digits). Unlike the [Rule List API](/latest/api-rule-list-management), this API does not use API keys created in the web interface. The token must still be configured statically in `abby.yml`. The value below is a placeholder showing the expected shape — always use one you generated yourself:
   ```yaml theme={null}
   staticApiTokens:
    - name: api_test
      token: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
   ```
6. Click **Publish**, then restart all MTAs. The `scanSources` and processing settings in `activeguard/core/active_guard.yml` require an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

## API reference

### Request

Requests are served by two endpoints:

* `/v1/messageQueue/submitEmail`
* `/v1/admin/status`

In order to process a message, our API requires the following arguments:

| Arguments | Value | Description |
| - | - | - |
| `email` | Path to the .eml file | Path to the .eml file you wish to send to xorlab |
| `parameters` | `borderMtaData` key:value pairs | Data retrieved at the border MTA receiving the email (see below); you must explicitly set its content type of `application/json` |
| `Authorization: Bearer` | Auth token | Bearer authorization token provided by xorlab or generated by a customer (see step #5 in the previous section) |

The `parameters` argument accepts only one parameter, `borderMtaData`, which includes the following key:value pairs:

| Key | Value | Description |
| - | - | - |
| `envelopeFrom` | string | Envelope `FROM` address (required) |
| `envelopeRecipients` | array | Envelope `TO` address(es) (required) |
| `remoteAddress` | string | The IP address of the sending MTA, received at the border MTA |
| `senderHelo` | string | HELO or EHLO (host or IP) of the sending mail client, received at the border MTA |

<Note>
  **Maximum payload**

  The maximum accepted payload size is 50 MiB. Payloads above this will result in a 413 error code.
</Note>

### Response

In response to your API request, you will receive either a message analysis result or an error. In the former case, the response will contain the following parameters:

| Parameter | Value (format) | Description |
| - | - | - |
| `ggrid` | string (UUID) | The unique ID associated with the message analysis |
| `created` | string (date-time) | The time when the analysis result was created |
| `completed` | string (date-time) | The time when the analysis was concluded |
| `decision` | string | The decision xorlab took with regards to this message: `undecided`,  `deliver`, `quarantine`, `bounce`, or `drop` |
| `verdict` | string | The [verdict](/latest/verdicts) xorlab applied to the message |
| `tags` | array | All [tags](/latest/tags) associated with the message |

## Examples

### cURL

This is a sample cURL command for sending an email to xorlab for analysis:

```curl theme={null}
curl -sS -X POST -F email=@<path to your eml file> -F parameters='{"borderMtaData": {"envelopeFrom": "s@example.com", "envelopeRecipients": ["r@example.com"]}};type=application/json' -H 'Authorization: Bearer <auth token>' https://<your xorlab instance>:9081/v1/messageQueue/submitEmail
```

where

* `<path to your eml file>` is the path to the .eml file you wish to send, e.g., `fileName.eml`
* `<auth token>` is the bearer auth token (see step #5 in the [Enable the API](#enable-the-api) section above)
* `<your xorlab instance>` is the domain of your xorlab instance, e.g., for `xyz.activeguard.cloud`, the full link would read `https://xyz.activeguard.cloud:9081/v1/messageQueue/submitEmail`

### Python

The following Python script makes use of the [cURL command](#curl) described above:

```python theme={null}
#!/usr/bin/env python3
import json

import click
import subprocess


@click.group()
def cli():
    pass


@cli.group()
def mail():
    pass


@mail.command()
@click.option("--file", required=True, help="Path to the email file")
@click.option("--env-ip", required=True, help="IP address of the sending MTA")
@click.option("--env-from", required=True, help="Envelope FROM address")
@click.option("--env-sender-helo", required=True, help="HELO or EHLO (host or IP) of the sending mail client")
@click.option("--env-to", required=True, help="Envelope TO address")
def submit(file, env_ip, env_from, env_sender_helo, env_to):
    parameters = {
        "borderMtaData": {
            "envelopeFrom": env_from,
            "senderHelo": env_sender_helo,
            "remoteAddress": env_ip,
            "envelopeRecipients": [env_to],
        }
    }

    command = [
        "curl", "-sS", "-X", "POST",
        "-F", f"email=@{file}",
        "-F", f'parameters={json.dumps(parameters)};type=application/json',
        "-H", "Authorization: Bearer <auth token>",
        "https://<your xorlab instance>:9081/v1/messageQueue/submitEmail"
    ]

    subprocess.run(command, check=True)


if __name__ == "__main__":
    cli()
```

The placeholders here—`<auth token>` and `<your xorlab instance>`—are the same as for the cURL example.

## Full API specifications

```yaml theme={null}
openapi: 3.0.0
info:
  title: xorlab API
  version: 1.1.0

servers:
  - url: /v1

security:
  - bearerAuth: []

paths:
  /messageQueue/submitEmail:
    post:
      description: Submit a new message into the analysis queue and wait for the analysis to complete.
      requestBody:
        $ref: "#/components/requestBodies/MailScanRequest"
      responses:
        "200":
          $ref: "#/components/responses/MessageAnalysisResult"
        default:
          $ref: "#/components/responses/GenericError"

  /admin/status:
    post:
      description: A request for system status
      responses:
        "200":
          description: A system status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStatus'
        default:
          $ref: "#/components/responses/GenericError"


components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  requestBodies:
    MailScanRequest:
      description: Request body to provide an email to ActiveGuard
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              parameters:
                $ref: "#/components/schemas/MessageAnalysisRequest"
              email:
                description: The raw email as it was transported over the wire.
                type: string
                format: binary
            required:
              - parameters
              - email

  responses:
    GenericError:
      description: Typical error response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    MessageAnalysisResult:
      description: A message analysis result.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MessageAnalysisResult"

  schemas:
    Error:
      description: A common error.
      type: object
      properties:
        error:
          description: Machine readable error description
          type: string
        message:
          description: Human readable error description
          type: string
      required:
        - error

    SystemStatus:
      description: System status.
      type: object
      properties:
        messageQueueStatus:
          description: Flag which indicates the status of the message queue.
          type: string
          enum:
            - GREEN
            - YELLOW
            - RED
      required:
        - messageQueueStatus

    MessageAnalysisRequest:
      description: A request to process a message
      type: object
      properties:
        borderMtaData:
          description: Data retrieved at border MTA receiving the email.
          type: object
          properties:
            envelopeFrom:
              type: string
            envelopeRecipients:
              type: array
              items:
                type: string
              minItems: 1
            remoteAddress:
              description: The IP address of the sending MTA, received at the border MTA
              type: string
            senderHelo:
              description: HELO or EHLO (host or IP) of the sending mail client, received at the border MTA.
              type: string
          required:
            - envelopeFrom
            - envelopeRecipients
        tenantUid:
          description: The tenant to which the resulting GuardRequest will be assigned
          type: string
          format: uuid
      required:
        - borderMtaData

    MessageAnalysisResult:
      description: A result of a message analysis.
      type: object
      properties:
        ggrid:
          description: The unique ID associated with the message analysis.
          type: string
          format: uuid
        created:
          description: The time when the analysis result was created.
          type: string
          format: date-time
        completed:
          description: The time when the analysis was concluded.
          type: string
          format: date-time
        decision:
          description: The decision ActiveGuard took with regards to this message.
          type: string
          enum:
            - undecided
            - deliver
            - quarantine
            - bounce
            - drop
        verdict:
          description: The verdict ActiveGuard applied to the message. https://docs.xorlab.com/latest/verdicts
          type: string
        tags:
          description: All tags associaceted with the message. See https://docs.xorlab.com/latest/tags.
          type: array
          items:
            type: string
```


# How to Activate the Configuration
Source: https://docs.xorlab.com/latest/activate-configuration

Which Expert Editor changes require a component restart to take effect, and which activate automatically within a minute.

All changes outside of the Expert Editor do not require a restart and will get automatically active after one minute.

After making changes in the Expert Editor, click **Publish** to deploy them. Then either wait for automatic activation or restart the component listed below.

## Configuration files

The following table lists all xorlab configuration files from the Expert Editor and how changes to them will get active. More specific entries overwrite the “required action” for wildcard (`*`) entries.

| File | Required action |
| :- | :- |
| `activeguard/core/active_guard.yml`: <br />-  `ruleListUpdateCron`<br />- `ruleListUpdateOnStartup`<br />- `ruleListUpdateDisabled`<br />- `scanSources/smtp/handler/*`<br />- `smtpConfiguration`<br /><br />`activeguard/core/logback-audit.xml`<br />`activeguard/core/logback.properties`<br />`activeguard/core/rule_sets/*`<br /><br />`activeguard/rspamd/*`<br /><br />`activeguard/mta/audit/logback-audit.xml`<br />`activeguard/mta/startup_cfg/postfix_custom/*`<br /><br />`auth/auth/*`<br /><br />`shared/*` <br /><br />`xcc/backend/logback-audit.xml`<br />`xcc/backend/logback.properties`<br />`xcc/backend/xcc.yml`:<br />- `misclassificationSubmission`<br />- `roleToPermissionMappings`<br />- `deliveryStatus`<br /><br />`monitored_mta/*`<br />`monitoring/* except grafana.ini` | None, automatically activated after one minute |
| `activeguard/core/active_guard.yml`: <br />`all properties not mentioned above, including:`<br /> - `serviceProviders`<br /> - `scanSources`<br /><br />`activeguard/core/startup_cfg/*`<br /><br />`activeguard/db/*`<br />`activeguard/mta/audit/audit.yml`<br /><br />`activeguard/core/startup_cfg/spamhaus_[hbl_]license.txt` | Restart MTAs. For all MTAs:<br />1. SSH connect to the MTA<br />2. `cd /etc/xorlab/activeguard`<br />3. `docker compose down && docker compose up -d` |
| `xcc/backend/xcc.yml`: all properties not mentioned before<br /><br />`xcc/web/*` | Restart XCC:<br />1. SSH connect to the XCC<br />2. `cd /etc/xorlab/xcc`<br />3. `docker compose down && docker compose up -d` |
| `monitoring/grafana/grafana.ini` | Restart Monitoring on MTAs. For all MTAs:<br />1. SSH connect to the MTA<br />2. `cd /etc/xorlab/monitored`<br />3. `docker compose down && sleep 2 && docker compose up -d` |

<Warning>
  **xorlab Security Platform (SaaS)**

  Restarting components is only possible for on-premises deployments. If you are using xorlab Security Platform (SaaS), please contact [support@xorlab.com](mailto:support@xorlab.com).
</Warning>


# Adding a Custom Rule
Source: https://docs.xorlab.com/latest/adding-custom-rule

Create a custom classification rule as an XML file under rule_sets/90_local/ in the Expert Editor, and add a custom list.

Follow these instructions to add a custom rule:

1. Open Expert Editor and go to the folder `activeguard/core/rule_sets/90_local/`.

2. Create a new file within `rules` via the three dots context menu. Name it `<rule_name>.xml` (e.g. `CUSTOM_spam_keyword_match.xml`).

   <img alt="Hamburger icon for the context menu" />

3. Open the file you just created and paste the content of the custom rule.

4. Inside `params` folder, open `local.properties`.

5. Add the parameter to activate the rule. Usually the format is `<rule_name>_state=ACTIVE` (e.g. `CUSTOM_spam_keyword_match_state=ACTIVE`).

6. Click **Publish**. The rule-set changes become active within about one minute.

## Adding a custom list

In case your custom rule references a new custom list, you will also need to add this new custom list.

1. Open Expert Editor and go to the folder `activeguard/core/rule_sets/90_local/`.

2. Create a new file within `lists` folder via the three dots context menu. If there is no `lists` folder inside `90_local`, create one manually.

3. Enter `<list_name>.list.info.json` as file name. For example, `CUSTOM_spam_domains.list.info.json`.

4. Open the file you just created and add:

   ```json theme={null}
   {"displayName":"Incoming subject rewrite recipients","category":"custom","description":"Internal recipients for which incoming emails will be subject prefixed."}
   ```

   where

   * `displayName` is the title/name of the list (*no.1 on the screenshot below*)

   * `category` is the name of the category the list belongs to (existing or a new one; *no.2 on the screenshot below*)

   * `description` is the description of the list displayed in the right pane after selecting a list in the left pane of the [Lists](/latest/lists) view (*no.3 on the screenshot below*).

   <img alt="List elements in the Lists view" />

5. Click **Publish**. The custom list becomes active within about one minute.

## Adding a YARA rule

You can block emails using a [YARA](https://virustotal.github.io/yara/) rule by adding it to a custom rule. This YARA-based rule consists of 3 main elements:

1. Condition to specify when the YARA rule is applied
2. Actual YARA rule.
3. Decision that tags or quarantines the matched email.

We start with this example rule and modify it to contain a YARA rule that finds [CVE-2018-0802](https://nvd.nist.gov/vuln/detail/CVE-2018-0802) exploits in Word and RTF files:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Change DISABLED to ACTIVE to activate the rule. -->
<rule name="example_rule" state="DISABLED" priority="390" applyTo="INCOMING">
  <pipeline>Emails</pipeline>
  <if>
    <and>
      <!-- Add conditions for decision here -->
      <hasTag name="#trusted"/>
    </and>
    <then>
      <decision decision="UNDECIDED">
        <tag>#mytag</tag>
      </decision>
    </then>
  </if>
</rule>
```

1. Set the name to `YARA_cve_2018_0802`, set the `state` property to `ACTIVE`, and select the email direction it should be applied to in `applyTo`:

   ```xml theme={null}
   <rule name="YARA_cve_2018_0802" state="ACTIVE" priority="20" applyTo="ALL">
   ```

   The allowed values for `applyTo` are: `ALL`, `INCOMING`, `OUTGOING`, `INTERNAL`.

   <Accordion title="Priority">
     The `priority` values are within the range of 0-2000. We recommend setting the priority to at least above 20 to ensure the built-in tag rules still apply. Then, either set it between 300 and 400 to ensure the rule has precedence over the built-in quarantine rules, or set it above 1000 to ensure that it does not have precedence over the built-in quarantine rules, i.e., is applied afterward.
   </Accordion>

2. Write a condition that would match all Word and RTF attachments during the file scan:

   ```xml theme={null}
   <if>
     <ForEachFileScanRequest match="ANY">
       <and>
         <or>
           <fileType equals="word"/>
           <fileType equals="rtf"/>
         </or>
   ```

3. Now, add the actual YARA rule and close the condition block:

   ```xml theme={null}
         <yaraMatch>
           <yaraRule>rule rtf_CVE_2018_0802 { strings: $header_rtf = "\\rt" ascii nocase $equation = { 45 71 75 61 74 69 6F 6E 2E 33 }
             $header_and_shellcode = /03010[0-1]([0-9a-fA-F]){4}([0-9a-fA-F]+08)([0-9a-fA-F]{4})([0-9a-fA-F]{296})2500/ ascii nocase condition:
             uint32be(0) == 0x7B5C7274 and all of them }
           </yaraRule>
         </yaraMatch>
       </and>
     </ForEachFileScanRequest>
   ```

4. Define the action. Here we just add a Tag that can be later used in a [campaign](/latest/campaigns):

   ```xml theme={null}
     <then>
       <decision decision="UNDECIDED">
         <tag>#cve_2018_0802</tag>
       </decision>
     </then>
   ```

5. The whole rule should look like this:

   ```xml theme={null}
   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <rule name="YARA_cve_2018_0802" state="ACTIVE" priority="20" applyTo="ALL">

     <if>
       <ForEachFileScanRequest match="ANY">
         <and>
           <or>
             <fileType equals="word"/>
             <fileType equals="rtf"/>
           </or>
           <yaraMatch>
             <yaraRule>rule rtf_CVE_2018_0802 { strings: $header_rtf = "\\rt" ascii nocase $equation = { 45 71 75 61 74 69 6F 6E 2E 33 }
               $header_and_shellcode = /03010[0-1]([0-9a-fA-F]){4}([0-9a-fA-F]+08)([0-9a-fA-F]{4})([0-9a-fA-F]{296})2500/ ascii nocase condition:
               uint32be(0) == 0x7B5C7274 and all of them }
             </yaraRule>
           </yaraMatch>
         </and>
       </ForEachFileScanRequest>
       <then>
         <decision decision="UNDECIDED">
           <tag>#cve_2018_0802</tag>
         </decision>
       </then>
     </if>
   </rule>
   ```

### Multiple YARA rules

It is possible to use multiple YARA rules in one custom rule. All you have to do is to put them in the `<or>…</or>` block, just like you did with the `fileType` selector:

```xml theme={null}
        <yaraMatch>
          <or>
            <yaraRule>rule 1 {
              … }
            </yaraRule>
            <yaraRule>rule 2 {
              … }
            </yaraRule>
          </or>  
        </yaraMatch>
```

## Multi-Tenancy

A rule placed in `90_local` as described above is the default for **all** tenants.

To add a rule that applies to a single tenant only, put the rule file in `activeguard/core/rule_sets/_tenantX/rules/custom/` instead, and activate it in the `params` folder of that same tenant. See [Manage Tenant Rules](/latest/multi-tenancy-rules#tenant-specific-rules) for the folder structure and for overriding parameters per tenant.


# Add list entries in bulk
Source: https://docs.xorlab.com/latest/api-reference/add-list-entries-in-bulk

/latest/assets/lists-api-v1.yaml post /public/lists/v1/addEntries
Adds entries to one tenant-scoped or deployment-global list. Requests can contain at most 500 entries. Existing entries are updated and counted as modifications.




# Delete list entries in bulk
Source: https://docs.xorlab.com/latest/api-reference/delete-list-entries-in-bulk

/latest/assets/lists-api-v1.yaml post /public/lists/v1/deleteEntries
Deletes entries from one tenant-scoped or deployment-global list. Requests can contain at most 500 entries. Missing entries are ignored and not counted as modifications.




# List all entries from one list
Source: https://docs.xorlab.com/latest/api-reference/list-all-entries-from-one-list

/latest/assets/lists-api-v1.yaml post /public/lists/v1/listEntries
Streams all entries from one list scope as NDJSON. Each line is one `PublicListsEntry`.




# List available lists
Source: https://docs.xorlab.com/latest/api-reference/list-available-lists

/latest/assets/lists-api-v1.yaml post /public/lists/v1/getLists
Returns metadata for all lists in one tenant-scoped or deployment-global scope.




# List API
Source: https://docs.xorlab.com/latest/api-rule-list-management

Automate list entries with the List API: getLists, listEntries, addEntries, and deleteEntries, with API key authentication and tenant scopes.

The List API lets you programmatically add, update, and remove entries on all lists that are visible in the web interface, including custom lists. The following endpoints are supported:

* `getLists`
* `listEntries`
* `addEntries`
* `deleteEntries`

<Tip>
  For playbook patterns that use these endpoints — and for getting xorlab events into your SOAR in the first place — see [Automate with a SOAR](/latest/integrations-soar).
</Tip>

## Quickstart

1. Go to the Admin view in xorlab, and open the **API keys** configuration.

   <img alt="API keys" />

2. Create a new API key and store it in a secure location. The key comes with a fixed permission set that only allows manipulating list entries, and nothing else.

3. Now you can use the key to change lists via the API. Below are some examples.

<Tabs>
  <Tab title="Get lists">
    Use this first to discover which lists are available. For the global scope, set `tenantUid` to `null`:

    ```bash theme={null}
    curl -sS -X POST \
      '<xorlab-url>/api/public/lists/v1/getLists' \
      -H 'Authorization: apikey <api-key>' \
      -H 'Content-Type: application/json' \
      -d '{
        "tenantUid": null
      }'
    ```

    Use this to get the available lists for a specific tenant:

    ```bash theme={null}
    curl -sS -X POST \
      '<xorlab-url>/api/public/lists/v1/getLists' \
      -H 'Authorization: apikey <api-key>' \
      -H 'Content-Type: application/json' \
      -d '{
        "tenantUid": "<tenant-uid>"
      }'
    ```
  </Tab>

  <Tab title="Read all entries">
    This returns all entries of one list as NDJSON, that is, one JSON object per line.

    ```bash theme={null}
    curl -sS -X POST \
      '<xorlab-url>/api/public/lists/v1/listEntries' \
      -H 'Authorization: apikey <api-key>' \
      -H 'Content-Type: application/json' \
      -d '{
        "tenantUid": null,
        "listName": "BLACKLIST_local_sender_addresses"
      }'
    ```
  </Tab>

  <Tab title="Add">
    Use this to add new entries or update existing ones. Existing entries are updated and counted as modifications.

    ```bash theme={null}
    curl -sS -X POST \
      '<xorlab-url>/api/public/lists/v1/addEntries' \
      -H 'Authorization: apikey <api-key>' \
      -H 'Content-Type: application/json' \
      -d '{
        "tenantUid": null,
        "listName": "BLACKLIST_local_sender_addresses",
        "entries": [
          {
            "entry": "bad-domain.example",
            "comment": "Added by automation after incident review"
          },
          {
            "entry": "another-bad-domain.example",
            "comment": "Confirmed phishing sender domain"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Delete">
    Use this to remove entries that are no longer needed. Missing entries are ignored.

    ```bash theme={null}
    curl -sS -X POST \
      '<xorlab-url>/api/public/lists/v1/deleteEntries' \
      -H 'Authorization: apikey <api-key>' \
      -H 'Content-Type: application/json' \
      -d '{
        "tenantUid": null,
        "listName": "BLACKLIST_local_sender_addresses",
        "entries": [
          "bad-domain.example",
          "another-bad-domain.example"
        ]
      }'
    ```
  </Tab>
</Tabs>

Used placeholders:

| Placeholder | Description |
| :- | :- |
| `<xorlab-url>` | Base URL of your xorlab instance, for example `https://xyz.activeguard.cloud`. |
| `<api-key>` | API key created in the XCC web interface. |
| `<tenant-uid>` | Use `null` for the global scope. If you want to access a tenant-scoped list, set it to the `uid` parameter of that tenant as found in the `guarded_tenants.yml`. |
| `<list-name>` | Internal list name, for example `BLACKLIST_local_sender_addresses`. |

## Understanding list behavior

Each list has a maximum size. The exact limit depends on the list type and is returned by the `getLists` endpoint as `maxSize`.

The most important behavior to understand is what happens when a list is already full:

<Warning>
  **Automatic cleanup of full lists**

  If a list has reached its maximum size and you add a new entry, xorlab automatically removes the oldest existing entry from that list.
</Warning>

This means:

* New entries can still always be added
* The list size never grows beyond its configured maximum
* Older entries may disappear automatically if the list is already full

If needed, you can still manage list entries manually either through the **Lists** page or through configuration files in the Expert Editor. However the same automatic cleanup applies.

## Accessing custom lists

Custom lists can be accessed via the API in the same way as all built-in lists. The only requirement is:

* Custom lists needs to have a corresponding `.info.json` file in the Expert Editor, as described in [Adding a custom list](/latest/adding-custom-rule#adding-a-custom-list).

## Support for multi-tenancy

API keys can be created on:

* the global scope (**All** tenant selected)
* a tenant scope (specific tenant selected)

The scope where a key is created determines what it can access.

* A tenant-scoped key can manipulate list entries only within that tenant
* A globally scoped key can manipulate list entries for all tenants and for the global scope of the instance

<img alt="API key for tenant" />

The scope cannot be changed afterward, so create a separate key per automation with the narrowest scope that works. Together with the fixed permission set, this keeps the impact of a leaked key limited to the list entries of one tenant.

## Endpoint reference

Each endpoint has its own reference page in the sidebar below this one, generated
from the OpenAPI specification: request and response schemas, error codes, and a
playground you can call your own instance from.

The specification itself is on [List API OpenAPI Spec](/latest/lists-api-spec), in one
block you can copy into your API tooling or hand to a client generator.


# Backup & Recovery
Source: https://docs.xorlab.com/latest/backup-recovery

Configure manual and scheduled full or incremental backups, and restore xorlab after a failure.

## Overview

xorlab supports [manual](#manual-backup) as well as [scheduled automatic](#backup) backups that can be used to restore the system after a failure. Backups are either **full** or **incremental**:

* **Full** backups are self-contained and do not depend on previous backups, which makes them more robust than incremental backups.

* An **incremental** backup only saves changes made since the last backup (full or incremental) hence it is faster, but it depends on earlier full/incremental backups. XCC will always trigger a full backup if no full backup can be found.

* A sequence that begins with a **full** backup and may include any number of **incremental** backups is called a **backup chain**.

Backups are **disabled** by default on on-premises VMs, as the host VM itself is typically backed up via the hypervisor. Should you choose to use xorlab's backup functionality, it is recommended to schedule *weekly* full backups over the weekend and *daily* incremental backups.

Backup (and [recovery](#recovery)) are done only on the XCC VM, as MTAs do not store data. Host configuration files, e.g. files in `/etc/xorlab/` are also not covered by the backups. Hence, it is recommended to regularly take snapshots of all VMs, at least after every update of xorlab.

## Quick setup

1. Open the [Expert Editor](/latest/expert-editor) and navigate to the `/xcc/backend/xcc.yml`.

2. Enable the backup service, and if needed, adjust the [schedule](#backup-schedule) for **full** and **incremental** backups, and the retention policy.

   ```shell {2} theme={null}
   backup:
     enabled: true
     incrementalBackupCron: 0 0 12,21 * * SUN-FRI
     fullBackupCron: 0 0 1 * * SAT
     deletion:
       enabled: true
       keepAdditional: 0
       deleteDanglingChain: true
   ```

   > In this example, incremental backups occur daily from Sunday to Friday at 12:00 and 21:00. A full backup is taken on Saturday at 01:00. Incomplete chains, e.g. incremental backups without a full backup, will be removed. Long running backups get aborted after 72 hours, which should be sufficient for typical email load and data retention settings. See [Backup Settings](#backup-settings) for more details.

3. SSH to the XCC, open `/etc/xorlab/xcc/.env` and adjust the location of `BKP_BASE_DIR`, the directory where backups will be saved:

   ```shell theme={null}
   BKP_BASE_DIR=/backups
   ```

4. Click **Publish**, then restart the `xcc_backend` container to apply the changes. The general backup settings in `xcc/backend/xcc.yml` require an XCC restart; see [How to Activate the Configuration](/latest/activate-configuration):

   ```shell theme={null}
   cd /etc/xorlab/xcc && docker compose stop backend && docker compose up -d
   ```

5. Optionally, we recommend integrating/sending the backup events [`sys.backup.*`](/latest/logging-events#system-events) to your SIEM or centralized monitoring system, if available. This will allow you to be notified if a backup fails.

## Backup

<Warning>
  **Software versions compatibility**

  The compatibility of backups between major/minor versions (e.g. 9.1.0 and 9.0.0) is not guaranteed. Hence, when the XCC runs on a new version, the next scheduled backup will always be a full backup automatically.

  It is recommended to perform an **incremental** backup before a software upgrade and a **full** backup immediately afterward.
</Warning>

<Warning>
  **Backup Service does not back up any host related configuration, e.g. firewall, `/etc/xorlab` directory, etc.**
</Warning>

Each backup (full or incremental) consists of the `info.json` metadata file and four **module** files:

* **Assets** - contains the assets required by the XCC web interface and the quarantined messages.
* **ConfigRepos** - contains the xorlab configuration for each platform component.
* **Redis** - contains the metadata used for similarity matching.
* **Database** - contains the database contents with the metadata of each message analyzed by xorlab.

An example of all files for a full and two incremental backups:

```
backup-2025-09-23T14-42-50.738330283Z-full-Assets
backup-2025-09-23T14-42-50.738330283Z-full-ConfigRepos
backup-2025-09-23T14-42-50.738330283Z-full-Database
backup-2025-09-23T14-42-50.738330283Z-full-Redis
backup-2025-09-23T14-42-50.738330283Z-full-info.json
backup-2025-09-23T14-47-02.611662359Z-incremental-Assets
backup-2025-09-23T14-47-02.611662359Z-incremental-ConfigRepos
backup-2025-09-23T14-47-02.611662359Z-incremental-Database
backup-2025-09-23T14-47-02.611662359Z-incremental-Redis
backup-2025-09-23T14-47-02.611662359Z-incremental-info.json
backup-2025-09-23T14-47-19.942717733Z-incremental-Assets
backup-2025-09-23T14-47-19.942717733Z-incremental-ConfigRepos
backup-2025-09-23T14-47-19.942717733Z-incremental-Database
backup-2025-09-23T14-47-19.942717733Z-incremental-Redis
backup-2025-09-23T14-47-19.942717733Z-incremental-info.json
```

Each file follows the naming schema:

```
backup-timestamp-type-module
```

It starts with the `backup-` prefix followed by the UTC timestamp, which corresponds to the time when the backup was scheduled/triggered. The name further contains the type of the backup and the name of the module that created it. The file ending in `info.json` contains meta-data about the backup.

If the backup service is enabled, XCC saves backups to the chosen [backup directory](#backup-directory) according to the [backup schedules](#backup-schedule).

### Backup directory

Backups will take up a significant amount of disk space. In order to not interfere with normal operations, e.g. by using up all available disk space, it is strongly recommended to keep the backup directory on a different mount point than the other production data.
By default, the backup directory is set to `/backups`. You can change it in `/etc/xorlab/xcc/.env`:

```shell theme={null}
BKP_BASE_DIR=/backups
```

This backup directory (`BKP_BASE_DIR`) is mapped to `/var/lib/xorlab/xcc/backup/backups` in the `backend` container, as configured in `/etc/xorlab/xcc/docker-compose.yml`:

```yaml theme={null}
- ${BKP_BASE_DIR}:/var/lib/xorlab/xcc/backup/backups               # Backup dir
```

### Backup schedule

The backup schedule syntax uses the Quartz cron format, and can be edited in `/xcc/backend/xcc.yml` via the [Expert Editor](/latest/expert-editor).

The pattern represents: second, minute, hour, day, month, weekday. Month and weekday names can be given as the first three letters of the English names. Here are a few examples:

* `0 0 6,19 * * *`: at 6:00 and 19:00, every day.
* `0 0 9-17 * * MON-FRI`: every hour from 09:00 to 17:00, on weekdays.
* `0 0 0 * * SUN`: every Sunday at midnight.
* `"-"`: Never/disabled.

The default configuration schedules incremental backups daily from Sunday to Friday at 12:00 and 21:00, and a full backup on Saturday at 01:00. Note that the cron schedules are mutually exclusive (no incremental backup scheduled for Saturday):

```yaml theme={null}
backup:
  enabled: false
  incrementalBackupCron: 0 0 12,21 * * SUN-FRI
  fullBackupCron: 0 0 1 * * SAT
  deletion:
    enabled: true
    keepAdditional: 0
    deleteDanglingChain: true
```

After editing the backup schedule in the Expert Editor, click **Publish** and restart the XCC. These general `xcc/backend/xcc.yml` settings require an XCC restart; see [How to Activate the Configuration](/latest/activate-configuration).

You can use online tools, such as [Cron Expression Generator & Explainer](https://www.freeformatter.com/cron-expression-generator-quartz.html) or [crontab guru](https://crontab.guru/), to verify that your cron schedule. Be mindful, that crontab guru follows the standard cron syntax (no seconds field).

<Note>
  **Incremental backup schedule**

  Even if an incremental backup is scheduled, XCC will do a **full** backup if one of the following conditions apply:

  * XCC runs on a more recent minor version (after an update full backup is scheduled automatically).
  * There is an incomplete full backup that can be resumed.
  * No previous backup is found in the backup directory.
</Note>

### Backup settings

By default, automatic backup deletion is enabled. Only the current backup chain is kept (and one additional one related to the last minor release), and the dangling incremental backups (without associated full backup as their base) will be deleted. Here's the list of all backup configuration options that can be set in `/xcc/backend/xcc.yml`.

```yaml theme={null}
backup:
  enabled: false
  # Cron pattern for incremental backup. May still trigger a full backup if
  # a new minor version is detected after an update, which necessitates a full
  # backup. "-" means disabled.
  incrementalBackupCron: 0 0 12,21 * * SUN-FRI
  # Cron pattern for full backup, "-" means disabled.
  fullBackupCron: 0 0 1 * * SAT
  # Maximum backup time in hours after which the backup gets aborted.
  maxBackupTimeH: 72
  # Time in seconds to wait to acquire shared table locks at the beginning of the dump.
  dbTableLockTimeoutS: 3600
  # Time in hours to wait for a database dump.
  dbDumpTimeoutH: 24
  # Whether to check if the last backup is complete on startup and immediately resume
  # incomplete backup.
  resumeLastBackupOnStartup: true
  # Number of concurrent threads during backup.
  maxBackupModuleThreads: 20
  # Comma-separated list of module names to skip for full backups.
  # Can be one of Database, ConfigRepos, Assets, Redis
  skipModuleFull: ""
  # Comma-separated list of module names to skip for incremental backups:
  # Can be one of Database, ConfigRepos, Assets, Redis
  skipModuleIncremental: ""
  # Backup chains retention policy. Scanning for old backups gets triggered on startup and
  # after each scheduled backup.
  deletion:
     ## If backups should be deleted at all.
     enabled: true
     # Keep backup chain if it is no older than this number of days.
     keepForDays: 0
     # Keep X additional backup chains. The current chain will never be deleted.
     keepAdditional: 0
     # Keep last backup chain of previous (minor) release. Recommended for rolling
     # back an update in the worst case.
     keepLastPreviousRelease: true
     # If a backup chain without a full backup can be deleted.
     deleteDanglingChain: true
```

### Manual backup

When you need to create backups manually—for example, when the automatic backup was performed a couple of days ago and you want to make some substantial changes such as upgrading to a new xorlab version—you can can trigger a backup manually from the XCC web interface.

1. Log in to the XCC web interface.

2. On the main screen, click the tiles icon next to your account name and click the **Admin** icon in the displayed menu:

3. Open the **Backup** page:

   <img alt="Backup tile" />

4. Press the **New Incremental Backup** button, or choose **New Full Backup**:

   <img alt="Backup page" />

## Recovery

<Warning>
  **xorlab will automatically start a recovery procedure during startup, if the recovery folder contains a valid backup. This recovery will overwrite the current data. Make sure to only populate the recovery folder if you want to recover from a backup.**
</Warning>

<Note>
  **If you require assistance, or are in doubt, do not hesitate to contact us via [support@xorlab.com](mailto:support@xorlab.com).**
</Note>

The recovery process starts automatically if the `backend` service finds backup files in the recovery directory during startup. It will commence with the most recent full backup and proceed to apply all subsequent incremental backups. It replaces the database with the one from the backup, so the existing database does not have to be deleted beforehand.

Here are the steps needed to perform a recovery:

1. [Restore host configuration](#restore-host-configuration)

2. [Populate recovery directory](#populate-recovery-directory)

3. [Start recovery process](#start-recovery-process)

4. [Clear recovery directory](#clear-recovery-directory)

5. [Remove outdated search results](#remove-outdated-search-results)

6. [Re-start XCC stack](#re-start-xcc-stack)

### Restore host configuration

Host configuration, that was changed during an update, is backed up to `/etc/xorlab/backup/`.

### Populate recovery directory

The recovery directory is `${WRK_BASE_DIR}/backup/recovery` on the XCC, which is `/var/lib/xorlab/xcc/backup/recovery` with default settings. The default `/etc/xorlab/xcc/docker-compose.yml` already mounts it into the `backend` container, so it needs no setup.

Move the backup chain you would like to recover from the [backup directory](#backup-directory) to the recovery directory: its full backup, and the incremental backups after it up to the point in time you want to restore. Assuming `/backups` is used as the backup directory:

```shell theme={null}
sudo mv /backups/backup-2025-10-10* /var/lib/xorlab/xcc/backup/recovery/
```

If the backup directory is on a different mount point than `/var/lib/xorlab/xcc`, as recommended, moving the files copies them, so make sure there is enough free disk space for the backup chain.

### Start recovery process

1. Make sure all containers from the xcc stack are stopped:

   ```shell theme={null}
   cd /etc/xorlab/xcc && docker compose down
   ```

2. Start PostgreSQL—the database has to be running to recover its data:

   ```shell theme={null}
   docker compose up -d db
   ```

3. Start the backend service:

   ```shell theme={null}
   docker compose up backend
   ```

   and observe the logs. After a few seconds status reports similar to the following will be shown:

   ```java theme={null}
   xcc_backend  | INFO  [RecoveryServiceThread-6]: c.x.j.b.m.ModuleRunner - ### Status Report:
   xcc_backend  | Assets [30s ago]: Extracting to /var/lib/xorlab/xcc/backend/assets (no progress will be reported until done.)
   xcc_backend  | Database [18s ago]: pg_restore: finished item 3439 INDEX uq_asset_ggrid_name
   xcc_backend  | RecoveryService [30s ago]: Starting recovery modules [com.xorlab.jxcc.backup.module.recovery.AssetsRecoveryModule@ac91282, com.xorlab.jxcc.backup.module.recovery.DatabaseRecoveryModule@7f79edee] for backup Backup(2025-10-29T04:00:00.016296214Z, full, /var/lib/xorlab/xcc/backup/recovery)
   ```

4. Once the recovery is complete, the JVM in the `xcc_backend` container will shut down with exit code 3, and you will see this line:

   ```shell theme={null}
   INFO exited: xcc (exit status 3; expected)
   ```

5. <kbd>Ctrl</kbd>+<kbd>C</kbd> to close the logs and stop the container.

<Note>
  **Errors from `pg_restore`**

  xorlab uses `pg_restore` to restore backups. All log lines containing `Found expected (non-)error from pg_restore` can be safely ignored as they do not influence the recovery.
</Note>

### Clear recovery directory

Move the backup chain back to the backup directory. The recovery directory must be empty before the `backend` service starts again, otherwise it starts a second recovery. xorlab also only cleans up old backup chains in the backup directory.

```shell theme={null}
sudo mv /var/lib/xorlab/xcc/backup/recovery/backup-* /backups/
```

### Remove outdated search results

The recovery marks all emails for re-synchronization with Elasticsearch, and the `backend` service re-synchronizes them from the database once it starts. Until then, the search index still holds the emails from before the recovery, and the XCC web interface shows them in the search overview. Delete the index while the `backend` service is still stopped; it creates the index again when it starts.

1. List the index and note its version number, `xcc_result_publish_version_<N>`:

   ```shell theme={null}
   docker exec es_0 curl -s "localhost:9200/_cat/indices/xcc_result_publish_*?v"
   ```

2. Delete the index, replacing `<N>` with the version number from the previous step:

   ```shell theme={null}
   docker exec es_0 curl -s -X DELETE "localhost:9200/xcc_result_publish_version_<N>"
   ```

### Re-start XCC stack

```shell theme={null}
cd /etc/xorlab/xcc && docker compose down && docker compose up -d
```

<Note>
  **The analyst dashboard will appear empty or incomplete while data is being re-synchronized. Depending on the amount of emails, it may take minutes to hours until this process is completed.**
</Note>

## Patch rollback

If the patch upgrade was not successful, it’s possible to revert the changes.

All components can be restored to the **previous** patch version (unless stated otherwise in the [release notes](/latest/upgrade-guide#reading-the-changelog)) by performing the following steps:

1. Set the version variables (`*_VERSION`) to the **previous** patch version in the `/etc/xorlab/<component>/.env` file.

2. Restart the component:

   ```shell theme={null}
   cd /etc/xorlab/<component> && docker compose up -d
   ```

For example, to roll back the xcc component from `11.0.1` to the `11.0.0`:

1. Set the version variables to the `11.0.0`:

   ```shell /etc/xorlab/xcc/.env theme={null}
   (...)
   XCCWEB_VERSION=11.0.0        # was 11.0.1
   XCC_VERSION=11.0.0           # was 11.0.1
   XCC_DB_VERSION=11.0.0        # was 11.0.1
   XCC_REDIS_VERSION=11.0.0     # was 11.0.1
   (...)
   ```

2. Restart the xcc component:

   ```shell theme={null}
   cd /etc/xorlab/xcc && docker compose up -d
   ```

In case the patch rollback fails, please refer to the [Recovery](#recovery) section, to perform a restore from the backup chain created before the update.


# Configuration Files
Source: https://docs.xorlab.com/latest/configuration-files

The xorlab YAML configuration files — guarded_tenants.yml, active_guard.yml, xcc.yml and auth.yml — with links to the full reference for each.

You edit these files through the
[Expert Editor](/latest/expert-editor) and deploy your changes as described in
[Activate a Configuration](/latest/activate-configuration).

Each file is described below, with a link to its complete annotated reference: every supported
attribute, together with the values a new deployment ships with.

## guarded\_tenants.yml

**Expert Editor location:** `/shared/guarded_tenants.yml`

Tenants and config sets: applied [rule profiles](/latest/rule-profiles), transport and routing, and per-tenant detection and quarantine settings. See [Multi-Tenancy Overview](/latest/multi-tenancy-overview).

<Info>
  The complete annotated reference is documented in
  [guarded\_tenants.yml](/latest/guarded_tenants_yml). Access to that page is restricted.
</Info>

## active\_guard.yml

**Expert Editor location:** `activeguard/core/active_guard.yml`

Core email processing: service providers, scan sources, email reporting, and the optional analysis services such as the [Sandbox](/latest/xorlab-sandbox), [NLU](/latest/xorlab-nlu) and [QR code analysis](/latest/qr-code-extraction).

<Info>
  The complete annotated reference is documented in
  [active\_guard.yml](/latest/active_guard_yml). Access to that page is restricted.
</Info>

## xcc.yml

**Expert Editor location:** `xcc/backend/xcc.yml`

XCC: authentication wiring, [custom role permission mappings](/latest/create-custom-user-role) and [auto-login links](/latest/authentication-auto-login-link).

<Info>
  The complete annotated reference is documented in
  [xcc.yml](/latest/xcc_yml). Access to that page is restricted.
</Info>

## auth.yml

**Expert Editor location:** `auth/auth/auth.yml`

Authentication service: enabled backends ([LDAP](/latest/authentication-ldap), [SAML](/latest/authentication-saml), [password file](/latest/authentication-with-a-password-file)), session lifetimes and the [trust store](/latest/authentication-certificates).

<Info>
  The complete annotated reference is documented in
  [auth.yml](/latest/auth_yml). Access to that page is restricted.
</Info>


# Context Variables
Source: https://docs.xorlab.com/latest/context-vars

Reference of the context variables you can set in rules to trigger actions or override global settings.

| Variable | Accepted values (case sensitive) | Description |
| - | - | - |
| `DynamicScanMode` | `AlwaysInline`<br />`NoDynamicScan`<br />`Inline`<br />`Offline` | Controls when and how to apply a dynamic email analysis. See [Sandbox Configuration](/latest/xorlab-sandbox) |
| `QuarantineName` | text | Sets the assigned [quarantine](/latest/data-retention-quarantine) for a quarantined message |
| `ReportAcknowledgment.Template` | template name | Sets the template for the acknowledgment email of a reported incident (if applicable). Default: [`REPORT_NOTIFICATION_ACKNOWLEDGEMENT`](/latest/email-template-overview#report_notification_acknowledgement) |
| `ReportFeedback.Template` | template name | Sets the template for a reported email |
| `ReportFeedback.AttachIncidentEml` | `DELIVER \| DROP` | Specifies whether to attach the reported email to the report feedback template that can be set with `ReportFeedback.Template`; by default, the email is attached for the `DELIVER` decision |
| `EmailScreenshot` | `true`<br />`false` | If set to `true`, the .eml files will be rendered to .png images |
| `KeepDanaAssets` | `true`<br />`false` | If set to `true`, Sandbox assets will be preserved. See [Screenshots for Benign Emails](/latest/xorlab-sandbox#show-screenshots-for-benign-attachments) |
| `NotifyUser` | `true`<br />`false` | If set to true, the guarded recipient gets a notification mail about the quarantined message instead of the actual mail (you can set the template with `ReceiverNotification.Template`); the guarded sender gets a notification mail about their message not being delivered (you can set the template with `SenderNotification.Template`).<br />This feature is independent of SSQ notifications, and we recommend using the latter—just make sure you don’t use both as it might result in two notifications for the same quarantined message |
| `SenderNotification.Template` | template name | When `NotifyUser` is set to `false`, this variable sends a notification email to the sender using the selected template |
| `SenderNotification.GuardedOnly` | `true`<br />`false` | When `NotifyUser` is set to `false`, and this variable is set to `true` (default), a notification is sent to a guarded email sender only |
| `ReceiverNotification.Template` | template name | When `NotifyUser` is set to `false`, this variable sends a notification email to the recipient using the selected template |
| `ReceiverNotification.GuardedOnly` | `true`<br />`false` | When `NotifyUser` is set to `false`, and this variable is set to the default `true`, a notification is sent to a guarded email recipient only |
| `Delivery.SubjectPrefix` | text | Adds a prefix to the rewritten email subject. Works in inline mode only |
| `Delivery.Attachment.Remove` | `true`<br />`false` | Completely remove the attachment which contains a specifically marked ScanRequest |
| `Delivery.Attachment.Replace.Enable` | `true`<br />`false` | If enabled, the attachment which contains a specifically marked ScanRequest will be replaced with a text file (set with the optional `Delivery.Attachment.Replace.Text` and `Delivery.Attachment.Replace.NameFormatString` parameters) |
| `Delivery.Attachment.Replace.Text` | text | Content of a text file that will be displayed to the reader of the email instead of an attachment (default: `Attachment removed by policy`) |
| `Delivery.Attachment.Replace.NameFormatString` | text | Filename of a text file that will replace the attachment (default: `replaced-%s.txt`) |
| `PublishThreatIntel` | `true`<br />`false` | Selectively decide if threat intel should be published for this particular email (default: publish it only for malicious emails) |
| `KeepRawMail` | `true`<br />`false` | If set to true, the source .eml file will be published to XCC and available for download in the **Detail** view. The email will be kept until the global time-to-live is reached |
| `verdict.value` | text | Sets a [verdict](/latest/verdicts) that will be displayed in the XCC, quarantine notification emails and a report |

## Rule example

Below is a rule example that sets seven context variables for an incoming email with a spam score equal to or higher than 8. This email will be put in the Spam quarantine with a `spam` verdict, and the following actions will be performed:

* The .eml file will be rendered as a .png image.
* All Sandbox assets will be kept.
* The subject won’t be changed.
* No notification will be sent to the recipient.
* Threat intel info will be published.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rule name="CUSTOM_SPAM_high_score" state="ACTIVE" priority="550" applyTo="INCOMING">
    <pipeline>Emails</pipeline>
    <if>
        <spamScore cmp="GREATER_OR_EQUAL" threshold="8"/>
        <then>
            <decision decision="QUARANTINE">
                <tag>#quarantine</tag>
                <contextSetString contextKey="QuarantineName" value="Spam"/>
                <contextSetString contextKey="verdict.value" value="spam"/>
                <contextSetString contextKey="EmailScreenshot" value="true"/>
                <contextSetString contextKey="KeepDanaAssets" value="true"/>
                <!-- As the email is put into quarantine, leave SubjectPrefix empty. -->
                <contextSetString contextKey="Delivery.SubjectPrefix" value=""/>
                <!-- Do not send a quarantine notification. Normally, notifications are triggered through SSQ which is a completely separate mechanism -->
                <contextSetString contextKey="NotifyUser" value="false"/>
                <contextSetBool contextKey="PublishThreatIntel" value="true"/>
            </decision>
        </then>
    </if>
</rule>
```


# Data Flow Overview
Source: https://docs.xorlab.com/latest/data-flow-overview

Which components handle your email, which services they call while analyzing it, and what each of those services receives. Applies to on-premises and SaaS alike.

Three components make up the xorlab Security Platform, and this page describes the data that moves between them:

* **xorlab MTA** — the mail transfer agents that receive and forward email, analyze it, and decide the classification of each message. A deployment usually runs several of them.
* **xorlab Control Center (XCC)** — the web interface analysts and administrators work in. It also holds the configuration and the shared state, such as the quarantines. There is one XCC per deployment.
* **External services** — services that the MTAs and the XCC call over the network during analysis instead of doing the work locally. They are described one by one below.

<Note>
  **External** means external to the MTAs and the XCC, not outside xorlab. Every service
  listed below is operated by xorlab, apart from the DNS blocklists. Where a xorlab
  service in turn contacts a third party — a URL shortener, for example — the section
  below says so. Which company hosts each service, and in which country, is listed in
  [List of Data Sub-Processors](/latest/data-third-party-subprocessors).
</Note>

## Who operates which component

| Deployment | MTAs and XCC | External services |
| :- | :- | :- |
| On-premises | You run them on your own infrastructure | Operated by xorlab, except the Sandbox — and Tika, which runs alongside it — which you can also run yourself |
| SaaS | Operated by xorlab | Operated by xorlab |

<Note>
  **In a SaaS deployment there is normally nothing here for you to change.** xorlab
  operates these services and defines their configuration. The options below for turning
  a service on or off describe on-premises deployments. What each service receives, and
  how long it keeps it, is the same either way.
</Note>

<Info>
  The data flow diagram and the order in which an email passes through the processing stages are
  documented in
  [Data Flow Details → Email processing pipeline](/latest/data-flow-details#email-processing-pipeline).
  Access to that page is restricted.
</Info>

## Description of External Services

If any of the external services is not reachable, the message is analyzed with the information that is still available and delivered as usual, detection accuracy is reduced for as long as the
disruption lasts, and xorlab resumes using the service automatically once it is reachable again.

### xorlab Sandbox

The xorlab Sandbox scans selected email attachments for malicious behavior in a secure, isolated environment. Supported file types include:

* MS Office files: Word (including RTF), Excel (including CSV), PowerPoint, OneNote
* PDF files

These files are transmitted over HTTPS and are only stored temporarily—typically for a few minutes—during the analysis process. After analysis, they are automatically deleted.

You can [configure](/latest/xorlab-sandbox) which file types are submitted for analysis.

Disabling file submission effectively turns off the Sandbox. You may also [disable the xorlab Sandbox entirely](/latest/xorlab-sandbox#disable-the-sandbox-completely), if required.

**If the xorlab Sandbox cannot be reached,** attachments are not scanned dynamically. Static malware detection is unaffected and keeps running, so malware detection is only partially degraded: what is missing is the behavior that becomes visible when a file is opened. The affected emails also have no attachment previews.

### xorlab Tika

The [Tika](/latest/xorlab-tika) service is used to improve the URL extraction and text extraction from attachments (for example, through OCR). It processes a defined set of file formats.

Attachments are sent to Tika via HTTPS for processing, then the extracted text is sent back. Files are only kept during processing.

Tika should not be disabled as it is a critical component for email classification.

**If xorlab Tika cannot be reached,** text, domains and URLs are less reliably extracted from attachments and no OCR is performed. Can lead to degradation of detection.

### xorlab ML

The xorlab ML service uses machine learning based on indicators found in emails to further improve the message classification. The indicators are sent to the ML service over an HTTPS connection. The data does not contain personal or customer-identifying data, nor does it contain the message body data. The data is only kept during processing.

xorlab ML is active by default and cannot be disabled.

**If xorlab ML cannot be reached,** classification falls back to the local rule set alone. The rules keep working, so detection continues, but without the additional machine learning assessment of the indicators found in the email.

### xorlab NLU

The xorlab [NLU](/latest/xorlab-nlu) service uses natural language understanding to enhance the classification accuracy of the xorlab Security Platform by analyzing the semantics and intent of email content.

When enabled, selected content such as the subject line, message body, and extracted attachment text is securely transmitted to the NLU service via HTTPS. This data may include customer-identifying information and is therefore treated as sensitive.

The transmitted data is processed in-memory only and is never persisted or stored after analysis.

For on-premises deployments this service is disabled by default and needs to be [activated manually](/latest/xorlab-nlu#enable-xorlab-nlu-for-on-premises). You can also [limit which traffic it analyzes](/latest/xorlab-nlu#configuration-options).

**If xorlab NLU cannot be reached,** the emails analyzed in the meantime are assigned no [topics](/latest/topic-detection). They cannot be searched or grouped by topic, and detection that relies on topics does not contribute, so more false negatives can occur.

### xorlab xCloud

xorlab maintains a centralized service for information around IPs, domains and URLs that is queried by the xorlab Security Platform. These queries are sent via HTTPS and contain domain names or IP addresses found in messages analyzed by xorlab Security Platform. You can’t turn them off. In general, the xorlab xCloud does not store the IPs, domains, and URLs beyond the time of processing. It may do so only in case of an error.

For shortened URLs (e.g., `bit.ly/foo`), xorlab xCloud may forward only the shortened URL to the external shortener service in order to resolve it. The resolved destination address is then evaluated like any other URL. xorlab does not open, download, or render the page behind that address, so no request from xorlab ever reaches the destination site itself. The traffic is via HTTPS.

The xorlab xCloud is active by default and cannot be disabled.

**If xorlab xCloud cannot be reached,** xorlab falls back to the reputation information it has already cached, so detection stays effective for domains and URLs it has seen before. Anything first seen in the meantime is treated as having no reputation, which makes a false positive more likely — and increasingly so the longer the disruption lasts, as more of the traffic consists of domains that are not in the cache.

### External DNS Blocklists

Customers may enable the integration with third-party DNS TI services such as Abusix or Spamhaus. In such a case, xorlab may send domains, IPs, URLs and hashes to the third party TI service via DNS requests.

This integration is disabled by default and needs to be manually activated.


# Change Metadata Retention
Source: https://docs.xorlab.com/latest/data-retention-metadata

Bound the searchable history window with deliveredTtlDays. Quarantine is governed by its own separate setting.

<Warning>
  **Quarantined emails**

  Quarantined emails are not affected by the Metadata retention, see [Change Quarantine Retention](/latest/data-retention-quarantine).
</Warning>

You can configure it in the `shared/guarded_tenants.yml` file:

* `deliveredTtlDays`: Duration after which metadata of benign (non-quarantined) emails is deleted.
* `fileAnalysisTtlDays`: Duration after which file upload results are deleted.
* `reportedTtlDays`: Duration after which metadata of reported emails is deleted. This includes the reported email itself.

```yaml guarded_tenants.yml {7,9,11} theme={null}
tenants:
  - name: xorlab
    domains:
      - xorlab.com
    dataRetention:
      ## Default. Duration after which benign emails are deleted.
      deliveredTtlDays: 90
      ## Default. Duration after which file upload results are deleted.
      fileAnalysisTtlDays: 90
      ## Default. Duration after which reported emails are deleted.
      reportedTtlDays: 730
```


# Data Retention Overview
Source: https://docs.xorlab.com/latest/data-retention-overview

What xorlab stores, for how long by default, and which retention settings you can change.

The default settings are sufficient for most environments. The table below shows what you can configure if needed.

| Type | Description | Default |
| :- | :- | :- |
| [Change Metadata Retention](/latest/data-retention-metadata) | How long emails are searchable and visible in the web interface. | 90 days |
| [Change Quarantine Retention](/latest/data-retention-quarantine) | How long malicious emails are kept in the quarantine. | 30 days |
| [Change Storing of Subject](/latest/data-retention-subject) | If and when email subjects are stored. | Always stored |
| [Change Storing of Previews](/latest/data-retention-previews) | If and when email and attachment previews are stored. | Stored only for malicious emails |
| [Change Log and Metric Retention](/latest/monitoring-data-retention) (on-prem only) | How long to keep operational logs and monitoring metrics. Applicable only for on-premises setups. | 30 days |

## Multi-Tenancy

Everything except log and metric retention can be set per tenant:

| Type | In a multi-tenant deployment |
| :- | :- |
| [Change Metadata Retention](/latest/data-retention-metadata) | Per tenant in `shared/guarded_tenants.yml`. |
| [Change Quarantine Retention](/latest/data-retention-quarantine) | Per tenant in `shared/guarded_tenants.yml`. |
| [Change Storing of Subject](/latest/data-retention-subject) | Per tenant in `shared/guarded_tenants.yml`. |
| [Change Storing of Previews](/latest/data-retention-previews) | Configured in `local.properties`, which applies to all tenants. To change it for one tenant only, use a `tenant.properties` file instead, see [Manage Tenant Rules](/latest/multi-tenancy-rules#tenant-specific-parameters). |
| [Change Log and Metric Retention](/latest/monitoring-data-retention) (on-prem only) | **Instance-wide only.** Cannot be configured per tenant. |

To apply the same `guarded_tenants.yml` retention settings to many tenants at once, define them in a shared config template: [Using Tenant Config Templates](/latest/multi-tenancy-configsets).

For more information:

* [Data Storage](/latest/data-storage)
* [Data Flow Overview](/latest/data-flow-overview)


# Change Storing of Previews
Source: https://docs.xorlab.com/latest/data-retention-previews

Decide whether screenshots of messages and attachments are captured at all, and which verdicts trigger them.

<Note>
  **Preview retention**

  The retention time of the previews (if it's stored) is defined via [Change Metadata Retention](/latest/data-retention-metadata).
</Note>

## Change email previews

The default of email previews is:

* **Enabled** for malicious (red and orange) verdicts
* **Enabled** for all reported emails
* **Disabled** for benign (green) verdicts

To enable previews for all emails, add the following line to `local.properties`:

```shell local.properties theme={null}
DEFAULT_email_screenshot_value=true
```

To disable preview for a verdict, add the `*_email_screenshot=true` [variable](/latest/rule-parameters#parameters-for-email-classification) to `local.properties`. For example, to disable previews for all phishing emails:

```shell local.properties theme={null}
PHISHING_high_confidence_decision_email_screenshot=false
PHISHING_medium_confidence_decision_email_screenshot=false
PHISHING_low_confidence_decision_email_screenshot=false
```

## Change attachment previews

By default, attachment previews are only enabled if:

* A Sandbox analysis was made
* And the email is classified as malicious

To enable previews for all attachments that were scanned by the Sandbox, set all of the below parameters to `true` in `local.properties`.

To disable previews for all attachments, set all of the below parameters to `false` in `local.properties`.

| Property | Default value |
| - | - |
| `DEFAULT_keep_dana_assets_value` (default for all verdicts) | `false` |
| `SIMULATION_decision_keep_dana_assets` | `true` |
| `BEC_decision_keep_dana_assets` | `true` |
| `EXTORTION_decision_keep_dana_assets` | `true` |
| `BLACKLIST_decision_keep_dana_assets` | `true` |
| `FILTER_high_confidence_decision_keep_dana_assets` | `true` |
| `FILTER_medium_confidence_decision_keep_dana_assets` | `true` |
| `FILTER_low_confidence_decision_keep_dana_assets` | `true` |
| `IMPERSONATION_high_confidence_decision_keep_dana_assets` | `true` |
| `IMPERSONATION_medium_confidence_decision_keep_dana_assets` | `false` |
| `MALWARE_dynamic_decision_keep_dana_assets` | `true` |
| `MALWARE_static_decision_keep_dana_assets` | `true` |
| `PHISHING_high_confidence_decision_keep_dana_assets` | `true` |
| `PHISHING_medium_confidence_decision_keep_dana_assets` | `true` |
| `PHISHING_low_confidence_decision_keep_dana_assets` | `false` |
| `SPAM_short_circuit_decision_keep_dana_assets` | `true` |
| `SPAM_high_confidence_decision_keep_dana_assets` | `true` |
| `SPAM_medium_confidence_decision_keep_dana_assets` | `true` |
| `SPAM_low_confidence_decision_keep_dana_assets` | `true` |
| `VIP_FRAUD_high_confidence_decision_keep_dana_assets` | `true` |
| `VIP_FRAUD_medium_confidence_decision_keep_dana_assets` | `false` |
| `INTERNAL_EXTORTION_decision_keep_dana_assets` | `true` |
| `INTERNAL_PHISHING_high_confidence_decision_keep_dana_assets` | `true` |
| `INTERNAL_PHISHING_medium_confidence_decision_keep_dana_assets` | `true` |
| `INTERNAL_PHISHING_low_confidence_decision_keep_dana_assets` | `false` |


# Change Quarantine Retention
Source: https://docs.xorlab.com/latest/data-retention-quarantine

Change how long emails remain in quarantine before they are removed and stop being searchable.

<Warning>
  **Retention**

  As soon as an email is removed from the quarantine, it is not visible and searchable anymore in xorlab.
</Warning>

You can configure the quarantine retention in the `shared/guarded_tenants.yml` file:

* There is a default quarantine retention for all quarantines
* And you can overwrite the default per quarantine

```yaml guarded_tenants.yml {8,12,13} theme={null}
tenants:
  - name: xorlab
    domains:
      - xorlab.com
    dataRetention:
      ## Default quarantine retention
      ## This value can be overwritten per quarantine type.
      quarantinedDefaultTtlDays: 30
    quarantine:
      quarantines:
          ## Overwrite the default quarantinedDefaultTtlDays for a specific quarantine
          - name: Malware
            ttlDays: 10
```

You can find the list of all quarantines here: [List of Quarantines](/latest/ssq-list-of-quarantines).

When specifying entries under `quarantines`, it is not necessary to list all other built-in quarantines. Just add the quarantines that you want to change.


# Change Storing of Subject
Source: https://docs.xorlab.com/latest/data-retention-subject

Suppress subject-line storage entirely, or bound how long it is kept. Subjects are retained by default.

<Note>
  **Subject retention**

  The retention time of the subject (if it's stored) is defined via [Change Metadata Retention](/latest/data-retention-metadata).
</Note>

The configuration is done in the `shared/guarded_tenants.yml` file:

```yaml guarded_tenants.yml {6} theme={null}
tenants:
  - name: example
    messageProcessing:
      pipelines:
        emails:
          keepEmailSubject: ALWAYS
```

The following values are supported for `keepEmailSubject`:

| Value | Description |
| - | - |
| `NEVER` | Never store the subject |
| `ALWAYS` (default) | Always store the subject |
| `ON_DROP_BOUNCE_AND_QUARANTINE` | Keep only if the email was quarantined or dropped |
| `ON_DROP_BOUNCE_QUARANTINE_AND_REWRITE` | Keep only if the email was either quarantined or dropped, or if it was delivered with a modified subject |


# Data Storage
Source: https://docs.xorlab.com/latest/data-storage

A per-component inventory of what is kept and for how long, graded by whether the data can identify a customer or a person.

Everything below holds for on-premises and for SaaS. What differs is whose infrastructure
the data sits on — your own, or xorlab’s — not what is kept or how long it is kept for.
Which of these settings you can change is described in
[Data Retention Overview](/latest/data-retention-overview), and the components named here
are introduced in [Data Flow Overview](/latest/data-flow-overview).

For this documentation, we define the following data classifications:

**Sensitivity: Low** Data that does not contain Customer Identifying Data (CID) or Personally Identifiable Information (PII) and cannot typically be linked to a specific email.

**Sensitivity: Medium** Data that may include CID or PII, such as email metadata (Subject, Sender, Recipient), but does not include full email content or attachments.

**Sensitivity: High** Data such as full email bodies and/or attachments.

## XCC

XCC stores both structured and unstructured data. Key data types, such as Email metadata and Log files, are detailed below. All stored data is subject to a retention time.

| Data type | Sensitivity | Stored | Format | Retention time |
| :- | :- | :- | :- | :- |
| Email metadata | Medium | **Always** | Plaintext, structured | Configurable, default is 90 days |
| Email subject | Medium | Configurable, options:<br />- Do not store<br />- **Store only for malicious emails (default)**<br />- Store for all emails | Plaintext, structured | Configurable, default is 90 days |
| Email content | High | Always kept for quarantined or reported emails. For all other cases: configurable, options:<br />- **Do not store (default)**<br />- Store only for malicious emails<br />- Store for all emails | Plaintext (EML), unstructured | Configurable. Quarantined emails are kept according to the quarantine configuration. By default, quarantined emails are kept for 30 days and reported emails are kept for two years. |
| Email content screenshots | High | Configurable, options:<br />- Do not store<br />- **Store only for malicious emails (default)**<br />- Store for all emails | JPEG, rendered image | Configurable, default is 90 days |
| Email attachment screenshots and videos | High | Applies only to attachments analyzed in the Sandbox. Configurable, options:<br />- Do not store<br />- **Store for all attachments analyzed in the Sandbox (default)** | JPEG, MP4 | Configurable, default is 90 days |
| Email attachments | High | Configurable, options:<br />- **Do not store (default)**<br />- Store for all emails | Unstructured file, unencrypted | Configurable, default is 90 days |
| Trustmodel (communication relationships) | High | **Always** | Hashed, structured | Not configurable. Entities are removed from the trust model after three months of inactivity |

### Email metadata

The email metadata contains the following attributes:

| Data attribute | Example |
| :- | :- |
| All sender and recipient email addresses | `account@xorlab.com` |
| Sender and recipient display names | `Mr. xorlab` |
| Sending MTA IP address | `1.2.3.4` |
| Received at (timestamp) | `2020-01-01T01:01:01+00:00` |
| Body URLs | `https://www.xorlab.com` |
| Matched email content and subject keywords | Popular phishing or spam keywords like `payment`, `drugs`, `banks`, etc. |
| All email headers (except subject) | `Received`, `Date`, `From`, `To`, etc. |
| All analysis results | Authentication information, extracted VBS from office attachments, events observed in the Sandbox, etc. |
| Attachment names | `newsletter.pdf` |

## MTA

An MTA maintains a persistent cache for various information like local domain reputation, trust scores, shortened URLs, etc. The cache contains only aggregated information and does not reference or relate to single emails.

| Data type | Sensitivity | Stored | Format | Retention time |
| :- | :- | :- | :- | :- |
| Cache for:<br />- Domain and IP information<br />- Email addresses<br />- Shortened URLs | Low | **Always** | Plaintext. Aggregated, data does not relate to single emails | Varies between the entities. Between one hour and two weeks |

## Sandbox

The xorlab Sandbox only stores files while they are being analyzed. Files are deleted immediately after processing, typically within minutes. In any case, files are automatically removed within a few hours, even if the requesting MTA is unavailable.

## Log files

Every xorlab Security Platform component writes local logfiles containing runtime events of different severity.

| Data type | Sensitivity | Stored | Format | Retention time |
| :- | :- | :- | :- | :- |
| Log files | Low to Medium | Configurable. Can be disabled (not recommended) | Plaintext | Configurable, default is one month |

* The MTA and XCC log files may contain the same data which is described in the [Email metadata](#email-metadata) section, and thus may contain email related data. SaaS instances may send log files to a centralized logging server operated by xorlab in the same region as the SaaS instance, i.e. in Switzerland for CH instances and in Germany for instances outside of Switzerland.
* The log levels (DEBUG, INFO, WARN, ERROR) can be used to reduce the amount of email related data written to the log files, but overall there may always be email related data in the log files.
* The xorlab Sandbox log files contain less sensitive data. The only email related data that those log files may contain are the names of the files (attachments) that are scanned.


# List of Data Sub-Processors
Source: https://docs.xorlab.com/latest/data-third-party-subprocessors

Which external parties may handle data under each deployment model, and where the contractually binding list lives.

The information below is provided as an overview. Please refer to your Data Processing Agreement for contractually binding details.

For all entries below except Cloudflare, the data is processed by xorlab software running on (virtualized) hardware of the sub-processor.

Read the table for your deployment. The SaaS table lists two entries the on-premises table
does not — the xorlab MTA and the centralized logs — because in an on-premises deployment
those run on your own infrastructure, where no sub-processor is involved. The services
themselves are described in [Data Flow Overview](/latest/data-flow-overview).

## On-premises

| Service | Processed Personal Data | Sub-processor for Customers in CH | Sub-processors for Customers outside CH | Mandatory |
| :- | :- | :- | :- | :- |
| [xorlab Sandbox](/latest/data-flow-overview#xorlab-sandbox) | Email attachments | On-premises **OR** Green Datacenter CH | On-premises **OR** Hetzner DE | Optional |
| [xorlab Tika](/latest/data-flow-overview#xorlab-tika) | Email attachments | On-premises **OR** Green Datacenter CH | On-premises **OR** Hetzner DE | Mandatory |
| [xorlab xCloud](/latest/data-flow-overview#xorlab-xcloud) | Domains, URLs, IPs | Green Datacenter CH | Hetzner DE | Mandatory |
| [xorlab ML](/latest/data-flow-overview#xorlab-ml) | **None** | Azure CH | Azure West Europe | Mandatory |
| [xorlab NLU](/latest/data-flow-overview#xorlab-nlu) | Emails | Azure CH | Azure West Europe | Optional |

## SaaS

| Service | Processed Personal Data | Sub-processor for Customers in CH | Sub-processors for Customers outside CH |
| :- | :- | :- | :- |
| xorlab MTA | Emails | Azure CH | Hetzner DE |
| [xorlab Sandbox](/latest/data-flow-overview#xorlab-sandbox) | Email attachments | Green Datacenter CH | Hetzner DE |
| [xorlab Tika](/latest/data-flow-overview#xorlab-tika) | Email attachments | Green Datacenter CH | Hetzner DE |
| [xorlab xCloud](/latest/data-flow-overview#xorlab-xcloud) | Domains, URLs, IPs | Green Datacenter CH | Hetzner DE |
| [xorlab ML](/latest/data-flow-overview#xorlab-ml) | None | Azure CH | Azure West Europe |
| [xorlab NLU](/latest/data-flow-overview#xorlab-nlu) | Emails | Azure CH | Azure West Europe |
| Centralized Logs | Emails | Azure CH | Hetzner DE |
| DNS records | Domains, IPs | Cloudflare | Cloudflare |


# Data Sent to External Services
Source: https://docs.xorlab.com/latest/data-to-external-services

Every transfer that leaves the MTAs or the XCC while an email is analyzed, what it contains, and whether it can be switched off. Most destinations are xorlab’s own services.

**External** means external to the MTAs and the XCC, not outside xorlab. Most of the
destinations below are services xorlab operates itself; the ones that are genuinely
third parties are VirusTotal and the DNS-based threat intelligence services, and both
are switched off until you enable them. [Data Flow Overview](/latest/data-flow-overview)
introduces the components and the services.

Both tables apply to on-premises and SaaS deployments. Two rows are marked
**On-premises only** — they describe transfers that leave your own infrastructure, which
in a SaaS deployment is xorlab’s. The **Mandatory** column means the same in both: whether
the transfer is part of normal operation or something you turn on and off. In SaaS, xorlab
operates the platform and sets that configuration.

## Sent by the MTAs

| Data attribute | Encrypted | External Service | Mandatory | Comment |
| :- | :- | :- | :- | :- |
| Domains, IPs, URLs | Yes | xorlab xCloud | Yes | Query global information for domains, IPs, and URLs that are found in an email |
| Detection indicators | Yes | xorlab ML | Yes | Analyze an email by sending data to the machine learning service. The data is not client-identifying, meaning no sensitive information is transmitted. What is sent is already visible under the **CONTEXT VARIABLES** tab in the message detail view and limited to the variables that start with `dce.`. The data includes SHA-256 hashes of attachments and files, and otherwise only inferred metadata of the email |
| Attachments | Yes | xorlab Sandbox | No | Certain suspicious attachments are temporarily uploaded to a secure cloud environment for sandbox analysis. After the scan is completed, relevant data is automatically removed from the cloud, and the analysis results are stored locally. If a customer runs its own xorlab Sandbox locally, then the local service will be used instead. |
| Attachments | Yes | xorlab Tika | Yes | Used to extract text and URLs from attachments. Files are sent to Tika over HTTPS and processed in-memory; they are not retained after processing. Disabling this feature may reduce classification performance. If a customer runs its own xorlab Sandbox locally, then the local Tika service will be used instead (Tika runs on the same system as the xorlab Sandbox). |
| Email (full content) | Yes | xorlab NLU | No | Sensitive email content is sent to xorlab NLU for text analysis. This feature is optional and disabled by default for on-premises installations. An on-premises version is planned for a future release. |
| Domains, IPs (A, MX, PTR, TXT) | No | Local DNS server | Yes | **On-premises only.** Used to verify SPF/DKIM, resolve domains, and, if manually enabled, query third-party DNS-based TI services. DNS queries are made directly from the MTA and may appear in your internal DNS logs. In a SaaS deployment the MTAs are operated by xorlab, so these queries never touch your infrastructure. |

## Sent by the XCC

| Data attribute | Encrypted | External Service | Mandatory | Comment |
| :- | :- | :- | :- | :- |
| Attachment hashes and URLs | Yes | External TI (VirusTotal) | No | On-demand VirusTotal query to get more threat intelligence for attachments and URLs |
| Telemetry | Yes | Telemetry | Yes | **On-premises only.** Information on the hardware the XCC VM is running on (CPU, memory, ...), information on the XCC VM (versions, packages, ...), information on the product usage, guarded domains. In a SaaS deployment xorlab operates the XCC, so this data never leaves xorlab. |

## Misclassification reports

The data in these reports depends on the reporter's chosen options: it’s possible to share metadata, previews, and original email; share metadata only, or share anonymized metadata.

The metadata means the following information:

| Information | Description |
| - | - |
| `ggrid` | Unique ID |
| `direction` | Incoming, outgoing, internal |
| `contextFields` | [Context variables](/latest/context-vars) |
| `coreCreated` | Analysis start time |
| `coreCompleted` | Analysis end time |
| `xccReceived` | Time when XCC received the message |
| `coreVerdict` | Message verdict |
| `coreVersion` | – |
| `pipeline` | Email, AnalysisFile, AnalysisEmail, or Report |
| `tags` | Tags added by xorlab |
| `userTags` | Tags added by the admin/analyst |
| `appliedRules` | Rules applied to this message |
| `passiveRules` | Passive rules |
| `ruleSetEssentialInfo` | Finger printing |
| `decisionHistory` | Series of decisions made by Core |
| `spamScore` | – |
| `rspamdScore` | Rspamd: external |
| `reporterClassification` | Reporter’s expected classification if the message is reported |
| `reporterVerdict` | Reporter’s expected verdict if the message is reported |
| `tenantId` | Unique customer ID |
| `principal` | Reporter’s username and permissions |
| `submissionDate` | – |
| `perceivedSeverity` | [Misclassification severity](/latest/reporting-misclassification#severity-levels) as perceived by the reporter: low, moderate, major, critical |
| `expectedClassification` | Classification as expected by the reporter: benign, malicious, or other |
| `reporterMessage` | Message from the misclassification reporter |
| `event` | Where the misclassification is reported from: isolation, report, direct submission |

Most of this data is contained in the **Context** fields (you can see it by clicking the **Context** tab in the message detail view).

Reports are sent to xorlab Cloud via HTTPS, then they are processed by us and stored indefinitely on our infrastructure.


# Set Up DKIM Signing
Source: https://docs.xorlab.com/latest/dkim-and-dmarc-setup

Configure DKIM signing and DMARC on xorlab so your outgoing email is authenticated by recipients.

## Set Up DKIM

Configure DKIM to add a cryptographic signature header to outgoing emails processed by xorlab. Recipients can use the corresponding public key, stored in your domain's DNS records, to verify this signature, confirming that our MTAs are authorized to send emails on your behalf.

For further reading on DKIM:

* [Wikipedia: DomainKeys Identified Mail](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail)
* [mxtoolbox: How to set up DKIM](https://mxtoolbox.com/dmarc/dkim/setup/how-to-setup-dkim)
* [RFC 6376](https://tools.ietf.org/html/rfc6376), [RFC 8301](https://tools.ietf.org/html/rfc8301), [RFC 8463](https://tools.ietf.org/html/rfc8463)

### Generating DKIM keys

You have to create one public and a private key and use this key pair for each MTA. Keys can be generated locally or on one of the MTAs via SSH.

**Commands to generate keys:**

```shell theme={null}
# Install opendkim-tools
sudo apt install opendkim-tools
mkdir keys
cd keys
# Replace the example domain and the selector
opendkim-genkey -d example.com -b 2048 -r -s 202406
chmod 600 *.private
```

**Available flags**

| Flag | Description |
| - | - |
| `-d` | Specifies the domain for which the key will be generated. |
| `-b` | Sets the length of the key (2048-bit is recommended). |
| `-r` | Restricts the key usage to email signing only. |
| `-s` | Defines the selector (recommended format: YYYYMM). |

### Configure Opendkim

Once the keys are generated, you need to configure `opendkim` by creating six new files:

* `opendkim.local.conf`: General configuration.
* `signing.table`: Maps email domains to key IDs.
* `key.table`: Maps key IDs to domains and private keys.
* `trusted`: Lists trusted hosts whose emails should be signed.
* `*.private`: The private key used for signing.
* `*.txt`: DNS record containing the public key.

1. Go to the [Expert Editor](/latest/expert-editor) on xorlab
2. In `activeguard/mta/opendkim/`, create the folder: `local`
3. In `activeguard/mta/opendkim/local`, create the 6 configuration files
4. For each config file, copy/paste the content from the code blocks below
5. Adjust the parameters, if necessary.

**`activeguard/mta/opendkim/local/opendkim.local.conf`**

```text theme={null}
# signing (s) and verification (v)
Mode                    sv
 
# Identifies a set of "external" hosts that may send mail through
# the server as one of the signing domains without credentials as such
ExternalIgnoreList      refile:/etc/opendkim/local/trusted
# Identifies a set internal hosts whose mail should be signed rather than verified.
InternalHosts           refile:/etc/opendkim/local/trusted 
SigningTable            refile:/etc/opendkim/local/signing.table
KeyTable                /etc/opendkim/local/key.table      
SignatureAlgorithm      rsa-sha256
 
# Always oversign the From header (sign both the actual From and a null From) to prevent 
# the insertion of malicious headers between the sender and receiver. 
# The From header is oversigned by default in the Debian package because it is often 
# the key identity used by reputation systems and is therefore security-sensitive.
OversignHeaders         From
 
# Set only to false if opendkim complains about key permissions even though the
# are set to 600
RequireSafeKeys         true
```

### Signing table

**`activeguard/mta/opendkim/local/signing.table`**

```text theme={null}
# maps domain to key ID
*@xorlab.com xorlab
```

### Key table

<Warning>
  **Important**

  Do not alter the path in `key.table`.
</Warning>

**`activeguard/mta/opendkim/local/key.table`**

```text theme={null}
# maps key ID to domain, selector, and private key file
xorlab xorlab.com:202406:/etc/opendkim/keys/202406.private
```

### Trusted list

<Warning>
  **Important**

  Make sure that each IP and hostname of your internal infrastructure is included in the `trusted` file.
</Warning>

**`activeguard/mta/opendkim/local/trusted`**

```text theme={null}
# trusted should contain all IPs or hostnames of your servers from which mails should be 
# signed instead of verified
11.22.33.44

# CIDR support
10.0.0.0/8

# domains support
example.com
```

### DKIM record

**`activeguard/mta/opendkim/local/202406.txt`**

```text theme={null}
# DKIM DNS record,key is shortened for brevity
202406._domainkey    IN    TXT    ( "v=DKIM1; k=rsa; s=email; "
      "p=MIGfMA0GCS...IDAQAB" )  ; ----- DKIM key 202406 for xorlab.com
```

### Activate configurations

1. Connect to each MTA via SSH.
2. For each MTA, perform the following steps:
   1. Edit the file: `/etc/xorlab/activeguard/docker-compose.yml`
      * Go to `services`→ `mta` → `volumes`
      * Add the line `./mta/opendkim:/etc/opendkim/keys/`
   2. Create the folder: `/etc/xorlab/activeguard/mta/opendkim`
      * Copy your private key file into this folder
      * The name of the file must be the same as specified in the `key.table` file (Although the path is different).
   3. Set the permissions for the private key
      * Only opendkim process should access it (0600, with 2021:2021)
      * Use the following commands:
   ```bash theme={null}
   sudo chmod 0700 /etc/xorlab/activeguard/mta/opendkim
   sudo chmod 0600 /etc/xorlab/activeguard/mta/opendkim/*.private
   sudo chown -R 2021:2021 /etc/xorlab/activeguard/mta/opendkim
   ```
3. In the Expert Editor, click **Publish**. Then restart the MTAs so the new OpenDKIM configuration is loaded:
   * `cd /etc/xorlab/activeguard`
   * `docker compose down && docker compose up -d`

### Configuring DNS Records

To complete the DKIM setup, you must update the DNS TXT record for your domain. This record  can be found in the `.txt` file generated by `opendkim-tools`. It contains the public key and is used by receiving mail servers to verify your DKIM signatures.

```text theme={null}
dig +short TXT 20230601._domainkey.google.com
"v=DKIM1; k=rsa; p=MIIBIjANBgkq[...]DAQAB"
```

## DMARC Recommendations

DMARC Policies safeguard your domain against unauthorized use, like phishing or email spoofing.

DMARC uses DNS records to define how a receiving MTA should handle SPF and DKIM failures (`policy`), report these failures (`reporting`), and align the From (`5322.From`) with the Mail From (`Envelope From`, `5321.MailFrom`).

While your domain's DMARC policy doesn't affect the operation of the xorlab security platform, we strongly recommend configuring DMARC as part of good email security practices.

For more information, please refer to the following resources:

* [Wikipedia: DMARC](https://en.wikipedia.org/wiki/DMARC)
* [mxtoolbox: What is a DMARC DNS Record?](https://mxtoolbox.com/dmarc/details/what-is-a-dmarc-record)
* [RFC 7489](https://tools.ietf.org/html/rfc7489)

### DMARC tags

A text DMARC record consists of `name=value` tags, separated with semicolons.

| Tag Name | Description | Comments |
| :- | :- | :- |
| `v` | Protocol version | **Required**<br />Value: `DMARC1` |
| `p` | Policy | **Required**<br />Value: `none`, `quarantine`, `reject`<br /> |
| `fo` | Failure reporting options | Optional<br />Generate failure report when:<br />`0`: all evaluations fail (default)<br />`1`: any evaluation fails<br />`d`: DKIM evaluations fails<br />`s`: SPF evaluations fails |
| `pct` | Percentage of messages from the Domain Owner’s mail stream to which the DMARC policy is to be applied | Optional<br />Value: an integer between `0` and `100` (default), inclusive |
| `rf` | Format to be used for message-specific failure reports | Optional<br />Value: colon-separated plain-text list; default is [`AFRF`](https://tools.ietf.org/html/rfc6591) |
| `ri` | Interval in seconds requested between aggregate reports | Optional<br />Value: plain-text 32-bit unsigned integer; default is `86400` (24h) |
| `rua` | Addresses to which aggregate feedback is to be sent | Optional<br />Value: email address |
| `ruf` | Addresses to which message-specific failure information is to be reported | Optional<br />Value: email address |
| `sp` | Requested Mail Receiver policy for all subdomains | Optional<br />Value: see `p` |
| `aspf` | SPF alignment. In **relaxed** mode, the SPF-authenticated domain and RFC5322.From domain must have the same Organizational Domain. In **strict** mode, only an exact DNS domain match is considered to produce Identifier Alignment | Optional<br />Value: `r` (relaxed; default), `s` (strict) |
| `adkim` | DKIM alignment. In **relaxed** mode, the Organizational Domains of both the DKIM-authenticated signing domain (taken from the value of the `d=` tag in the signature) and that of the RFC5322.From domain must be equal if the identifiers are to be considered aligned. In **strict** mode, only an exact match between both of the Fully Qualified Domain Names (FQDNs) is considered to produce Identifier Alignment | Optional<br />Value: `r` (relaxed; default), `s` (strict) |

The descriptions in the table above are mostly direct quotations of [RFC 7489](https://tools.ietf.org/html/rfc7489)

### Examples

To observe:

```text theme={null}
# send aggregated feedback, but do not reject or quarantine emails
"v=DMARC1; p=none; pct=100; fo=s; rua=mailto:mailauth-reports@example.com;ruf=mailto:mailauth-reports@example.com;"
```

Reject:

```text theme={null}
# original Google setting, reject and report aggregated
v=DMARC1; p=reject; rua=mailto:mailauth-reports@google.com
```

In both examples, the DNS TXT record needs to be set for `_dmarc.example.com`.


# Expert Editor
Source: https://docs.xorlab.com/latest/expert-editor

Access the Expert Editor, the admin tool that gives full access to every xorlab configuration option.

## Accessing Expert Editor

1. Log in to the XCC web interface with the URL address and credentials provided by xorlab.
2. On the main screen, click the tiles icon next to your account name and click the **Admin** icon in the displayed menu.
3. On the resulting **Admin** page, click the **Expert** tile:

   <img alt="Selecting the Expert Editor" />

   This opens Expert Editor and you can see the folder tree:

   <img alt="Expert Editor" />

## Using Expert Editor

You can expand folders to navigate to the desired file or simply search for a file in the **Search** box. When you click the file, its content is displayed in the right pane, ready for editing.

All the changes you make are automatically saved, so you don’t have to worry about it. But these saved changes will not be deployed (in other words, will not have any effect) until you click the blue **Publish** button, describe your changes in the **Publish Changes** dialog, and confirm with **Publish**. And until then, you can quickly discard your edits and revert to the original file by clicking the good old **UNDO** button.

Throughout this documentation, "click **Publish**" refers to this action. Most files are hot-reloaded within about one minute afterward, but some require a component restart on top of publishing, see [How to Activate the Configuration](/latest/activate-configuration).

### Context menu: file/folder operations

Expert Editor is not limited to editing only. Basic file and folder operations are available in the context menu:

1. Hover the mouse cursor over a folder or file icon. The icon will change to a vertical ellipsis (`…`) or a hamburger:

   <img alt="Hamburger icon for the context menu" />

2. Click it to display the context menu. In the case of a folder, you can rename, delete, or move it, and add a new file/folder inside of it. In the case of a file, you can just rename, delete, or move it.

   <img alt="Context menu for a folder" />

3. If you choose to rename or add a folder/file, a dialog box for entering a name appears. When you’re done, click **Rename** or **Create**, respectively. If you choose to move the file, you will be asked to select the target location in the resulting dialog box. Click to select the parent folder and click **Move**.

   <img alt="New Folder name dialog box" />

   <img alt="Move File dialog box" />

### Commenting/uncommenting code

Expert Editor supports a common keyboard shortcut for commenting/uncommenting multiple lines of code. Just select the code to comment out or uncomment and press **Ctrl+/** (**Cmd+/** on macOS).

<Note>
  This shortcut works on lines of code only. It will not work if the selected block includes actual comments.
</Note>

### Information on the .vmx.N notation

When you add the suffix `.vmx.<client_id>` to a config file, that file will only be served to the specific MTA identified via `clientID`. This allows to have different config files per MTA. The suffix is supported for all files inside the `activeguard` and `monitored_mta` folder.

The following example shows different prometheus configuration files per MTA used for monitoring. Both MTAs will be served the file `prometheus.properties`, but MTA1 will receive a file named `prometheus.yml` with the content of `prometheus.yml.vmx.1`, whereas MTA2 will receive a file named `prometheus.yml` with the content of `prometheus.yml.vmx.2`.

<img alt="" />

If you are configuring a setup with more than two MTAs, you can duplicate existing config files in the web interface:

<img alt="" />

<img alt="" />

and in the save dialog, increment the filename, e.g. `prometheus.yml.vmx.3`.

<img alt="" />


# FAQ
Source: https://docs.xorlab.com/latest/frequently-asked-questions

Common questions about detection, configuration, integration, and day-to-day operation.

## Detection

1. **What are the default actions for handling emails in xorlab?**

   See the [Actions](/latest/detection-actions) configuration screen under **Admin → Actions**.

2. **How can I change an action?**

   Use the [Actions](/latest/detection-actions) configuration screen under **Admin → Actions**.

3. **Is there a way to fine-tune the detection engine to reduce false positives/negatives?**

   Please refer to [Tune Detection](/latest/detection-tuning).

4. **How can I allow delivering documents with macros that are normally blocked?**

   If your emails with documents containing macros are blocked by xorlab Security Platform, you can use **Macro file whitelist (hash)** described in [Whitelists](/latest/whitelists#accepted-files) to add the hash value of the macro to the whitelist. Just open the blocked message in XCC, and in the **Detail** view, click the **Context Variables** tab and type `dangerous` into the search box. You will see a list of potentially dangerous objects in your document. The problematic macro(s) will be named `dce.file[XXXXXX].indicator.office_dangerous_vbascript`, where the `XXXXXX` value inside the square brackets is the hash of the macro. Copy the hash value of every macro that should not be blocked and add it to the  **Macro file whitelist (hash)**.

   <img alt="Macro hash value" />

* Note that usually, no file hashes remain the same. Therefore, for every new blocked message, you need to copy the hash values into the whitelist again. But if you have a specific macro that is reused in different files, it can be useful to whitelist this macro once so that it’s not detected as suspicious anymore.

5. **Emails are being quarantined although we run in Monitoring mode. Is xorlab blocking them?**

   No. In Monitoring mode xorlab decides on every email exactly as it does in Inline mode, so an email that the configured actions would quarantine gets the `QUARANTINED` decision and is kept in the matching quarantine. What is held back is the copy xorlab received; the email itself was delivered by your own mail flow and was never touched. See [Decisions and quarantine in Monitoring mode](/latest/inline-and-monitoring-mode#decisions-and-quarantine-in-monitoring-mode).

6. **In Monitoring mode, no email ever gets the `QUARANTINED` decision. What is wrong?**

   Most likely the Toothless profile `no_subject_rewrite_no_quarantine.properties` is still listed under `ruleProfiles` in `shared/guarded_tenants.yml`, which deactivates every quarantine action regardless of the verdict. Remove it and click **Publish**, see [Rule Profiles](/latest/rule-profiles#toothless). If quarantining is meant to stay off for now, judge the results by verdict and confidence instead.

## Reported emails

1. **Are some reported emails handled automatically by default?**

   Yes, based on a verdict. Please see [Verdict based automation](/latest/abuse-mailbox#verdict-based-automation).

2. **How can I further automate reported emails, so more of them are handled automatically?**

   You can do that either by creating new campaigns, or by configuring more verdict-based automation. Please see [Abuse Mailbox](/latest/abuse-mailbox).

## M365 integration

1. **Is it possible to login to XCC with M365 credentials?**

   Sure! All you need to do is to perform the steps described in [Enable Entra ID SAML Login](/latest/m365-saml-entra-authentication).

2. **How can I make the Report Message button in M365 work with xorlab?**

   The process of configuring this button is described in \*[Reporting suspicious emails - Default Outlook button](/latest/m365-reporting-integration)

3. **Is it possible to delete a message from a user’s M365 mailbox directly from XCC?**

   Yes, but you have to configure your M365 instance properly as described in [Case Isolation for M365](/latest/m365-case-isolation).

## Email notification templates

1. **How can I customize or localize email notification templates?**

   Please follow the instructions described in [Email Template Customizations](/latest/email-template-modifications).

2. **Is it possible to disable a certain template?**

   Definitely! Please see [Disabling a template](/latest/email-template-modifications#disable-a-template).

3. **How to choose a default response template for emails categorized as a specific verdict?**

   xorlab is highly customizable and provides the functionality to send automated responses to users in case an email is quarantined, reported, and so on. The admin can decide if a response should be given, what kind of response it should be, and choose the actual email template. As a rule of thumb, xorlab usually returns its default templates in case an email is reported by the user, a reported email is processed by xorlab, and when an email is blocked. Please see [Creating a New Email Notification Template](/latest/email-template-modifications#create-a-new-template) for a detailed explanation.

## Miscellaneous

1. **You sent me a custom rule, but how can I enable it?**

   Please refer to [Adding a Custom Rule](/latest/adding-custom-rule).

2. **I would like to enable logging for some actions. What should I do?**

   All necessary steps are described in [Logging Overview](/latest/logging-overview).

3. **An email is missing. How can I check if it was delivered by xorlab, or if it is stuck on xorlab, or it has never arrived there?**

   Use search query language first to find the email in xorlab and verify that it has not been quarantined. If it’s not there, ask [support@xorlab.com](mailto:support@xorlab.com) (in case of a SaaS instance) or search in the SMTP logs on the MTA in `/var/log/xorlab/activeguard/mta/mail.info` for the sender and recipient of the email (in case of an on-prem instance). There you will find what happened to the email. If you can’t find it, the email was never sent to xorlab.

4. **I have an on-prem instance of xorlab. I changed some config files in XCC and now the web interface is no longer available. Is there a way to fix these files and bring the web interface back?**

   Please follow the instructions from the [Troubleshooting](/latest/troubleshooting#how-to-change-config-files-in-case-the-web-interface-is-not-reachable) guide.

5. **What DNS traffic do the xorlab servers utilize?**

   xorlab does DNS lookups only for domains of the email, not filenames. However, it might happen that a filename that is written in the email body is (mistakenly) treated as a URL and therefore a DNS lookup is done. You could do a [search](/latest/search) based on `domain:matches:<example>` or `file.name:matches:<example>`.

6. **What browsers are supported?**

   If you want to know which browsers are supported by xorlab, type this URL in a tab where you are already logged in to xorlab and replace `xyz` with your customer ID:

   `https://xyz.activeguard.cloud/supported-browsers.txt`

   For on-premises, replace the domain above with the domain of your XCC.


# Important Operational Resources
Source: https://docs.xorlab.com/latest/important-resources

Support address, release announcements, status page, and the contact for reporting a vulnerability.

| Topic | Resource |
| :- | :- |
| Support address | [support@xorlab.com](mailto:support@xorlab.com) |
| Release announcements | [Subscription form](https://share.hsforms.com/1yOHcQkvBQiOiO3j9qwv1Yg2u2pk) |
| Status page | [Status page](https://status.xorlab.com/) |
| Reporting a vulnerability | [security@xorlab.com](mailto:security@xorlab.com) |
| Data protection | [List of Data Sub-Processors](/latest/data-third-party-subprocessors) |

## Support address

If you have any questions or need our assistance, contact us via **[support@xorlab.com](mailto:support@xorlab.com)**.

## Mailing list & release announcements

Subscribe to xorlab release and security announcements here: [Subscription form](https://share.hsforms.com/1yOHcQkvBQiOiO3j9qwv1Yg2u2pk). We strongly recommend to subscribe there to be informed about important updates.

<Accordion title="Example release announcement">
  <img alt="Release Announcements mailing list" />
</Accordion>

## Status page

Here you can find the xorlab status page: [Status page](https://status.xorlab.com/). You can subscribe there to get informed about scheduled maintenance and incidents.

It includes the status of xorlab SaaS instances, as well as xorlab services used by on-premises deployments. For what an incident affecting one of those services means for detection, see [Data Flow Overview → Description of External Services](/latest/data-flow-overview#description-of-external-services).

Note that the `xcc - GUI` status information is for SaaS customers only, as well as `Rollout of xorlab Security Platform x.x.x` announcements.

## Data protection

Which external parties may handle data in your deployment is listed in [List of Data Sub-Processors](/latest/data-third-party-subprocessors). For what the platform sends out while analyzing email, and what it keeps afterwards, see [Data Sent to External Services](/latest/data-to-external-services) and [Data Storage](/latest/data-storage).

## Vulnerability reports

Send security vulnerability reports to **[security@xorlab.com](mailto:security@xorlab.com)**. This address can be used for all xorlab’s products, services, and websites. We can accept only security vulnerability reports at this address.

When we receive a security vulnerability report, we will evaluate it. And, if we agree it is a vulnerability, we’ll work to fix it and release the fix in a timeframe that matches the severity.

Let us know if you would like credit for discovering the issue. We can cite you as the discoverer if we weren’t previously aware of the issue.


# List API OpenAPI Spec
Source: https://docs.xorlab.com/latest/lists-api-spec

Read or copy the complete OpenAPI specification behind the List API, to generate a client, import it into your API tooling, or check the exact request and response schemas.

This is the complete specification behind the [List API](/latest/api-rule-list-management), in OpenAPI 3.1 format. Copy it with the button in the top right of the block.

Every endpoint is also documented individually, with an interactive playground you can call your own instance from, starting at [List available lists](/latest/api-reference/list-available-lists).

<Note>
  The `servers` entry uses an `{instance}` variable: replace it with the hostname of your own XCC, without the scheme, for example `xyz.activeguard.cloud`.
</Note>

<div>
  ```yaml lists-api-v1.yaml theme={null}
  openapi: 3.1.0
  info:
    title: xorlab Public Lists API
    version: "1.0.0"
    description: >
      Public API for tenant-scoped or deployment-global list operations.
      All endpoints are authenticated with API keys and exposed under
      `/api/public/lists/v1`.
  servers:
    - url: https://{instance}/api
      description: Your own xorlab Control Center.
      variables:
        instance:
          default: xyz.activeguard.cloud
          description: >-
            Hostname of your xorlab Control Center, without the scheme,
            for example xyz.activeguard.cloud.
  security:
    - apiKeyAuth: []
  paths:
    /public/lists/v1/getLists:
      post:
        summary: List available lists
        operationId: publicListsGetLists
        description: >
          Returns metadata for all lists in one tenant-scoped or deployment-global scope.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsGetListsRequest"
        responses:
          "200":
            description: List metadata.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PublicListsGetListsResponse"
          "400":
            description: Invalid request.
          "404":
            description: Unknown tenant scope.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
    /public/lists/v1/listEntries:
      post:
        summary: List all entries from one list
        operationId: publicListsListEntries
        description: >
          Streams all entries from one list scope as NDJSON. Each line is one `PublicListsEntry`.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsListEntriesRequest"
        responses:
          "200":
            description: NDJSON stream of list entries.
            content:
              application/x-ndjson:
                schema:
                  type: string
                  description: Newline-delimited JSON stream of `PublicListsEntry` records.
          "400":
            description: Invalid request.
          "404":
            description: Unknown tenant scope or unknown list.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                    - LIST_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
    /public/lists/v1/addEntries:
      post:
        summary: Add list entries in bulk
        operationId: publicListsAddEntries
        description: >
          Adds entries to one tenant-scoped or deployment-global list.
          Requests can contain at most 500 entries.
          Existing entries are updated and counted as modifications.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsBulkAddEntriesRequest"
        responses:
          "200":
            description: Number of entries effectively added.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PublicListsBulkModificationResponse"
          "400":
            description: Invalid request (for example too many entries).
          "404":
            description: Unknown tenant scope or unknown list.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                    - LIST_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
    /public/lists/v1/deleteEntries:
      post:
        summary: Delete list entries in bulk
        operationId: publicListsDeleteEntries
        description: >
          Deletes entries from one tenant-scoped or deployment-global list.
          Requests can contain at most 500 entries.
          Missing entries are ignored and not counted as modifications.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsBulkDeleteEntriesRequest"
        responses:
          "200":
            description: Number of entries effectively deleted.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PublicListsBulkModificationResponse"
          "400":
            description: Invalid request (for example too many entries).
          "404":
            description: Unknown tenant scope or unknown list.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                    - LIST_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
  components:
    securitySchemes:
      apiKeyAuth:
        type: apiKey
        in: header
        name: Authorization
        x-default: "apikey <your-api-key>"
        description: Use format `apikey <token>`.
    schemas:
      PublicListsGetListsRequest:
        type: object
        additionalProperties: false
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
      PublicListsGetListsResponse:
        type: object
        additionalProperties: false
        required:
          - listFileInfos
        properties:
          listFileInfos:
            type: array
            items:
              $ref: "#/components/schemas/PublicListsFileInfo"
      PublicListsFileInfo:
        type: object
        additionalProperties: false
        required:
          - listInfo
          - listName
        properties:
          listInfo:
            $ref: "#/components/schemas/PublicListsInfo"
          listName:
            type: string
      PublicListsInfo:
        type: object
        additionalProperties: false
        required:
          - displayName
          - category
          - description
          - maxSize
        properties:
          displayName:
            type: string
          category:
            type: string
          description:
            type: string
          maxSize:
            type: integer
            format: int64
      PublicListsListEntriesRequest:
        type: object
        additionalProperties: false
        required:
          - listName
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
          listName:
            type: string
      PublicListsAddEntryRequest:
        type: object
        additionalProperties: false
        required:
          - entry
        properties:
          entry:
            type: string
          comment:
            type:
              - string
              - "null"
      PublicListsBulkAddEntriesRequest:
        type: object
        additionalProperties: false
        required:
          - listName
          - entries
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
          listName:
            type: string
          entries:
            type: array
            maxItems: 500
            items:
              $ref: "#/components/schemas/PublicListsAddEntryRequest"
      PublicListsBulkDeleteEntriesRequest:
        type: object
        additionalProperties: false
        required:
          - listName
          - entries
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
          listName:
            type: string
          entries:
            type: array
            maxItems: 500
            items:
              type: string
      PublicListsBulkModificationResponse:
        type: object
        additionalProperties: false
        required:
          - modifiedEntries
        properties:
          modifiedEntries:
            type: integer
            format: int32
            minimum: 0
      PublicListsEntry:
        type: object
        additionalProperties: false
        required:
          - entry
        properties:
          entry:
            type: string
          comment:
            type:
              - string
              - "null"
          updatedBy:
            type:
              - string
              - "null"
          timeUpdated:
            type:
              - string
              - "null"
            format: date-time
          timeCreated:
            type:
              - string
              - "null"
            format: date-time
  ```
</div>


# Built-in Log Files
Source: https://docs.xorlab.com/latest/logging-built-in-properties

The log files each component writes without any configuration, and the logback.properties settings that change their pattern, size, and retention.

This page is only relevant for on-premises deployments. Every component writes its own logs to the local filesystem, whether or not you have configured anything on the other pages in this group. Three families of file are produced, and each has its own rolling policy:

| Family | Contains | Property prefix |
| :- | :- | :- |
| Operational | The verbose `INFO`/`DEBUG` log of what the component is doing | `file.default`, `console.default` |
| Error | Errors only | `file.error` |
| Audit | The audit events the component emits, in the same JSON as a configured audit logger | `file.audit`, `console.audit` |

The files are per component, under `/var/log/xorlab/<stack>/<container>/` — [Operation Reference](/latest/operation-reference#log-files) lists the names, and [Troubleshooting](/latest/troubleshooting#how-to-find-mta-logs-using-the-command-line) shows how to read them over SSH. They stay on the host: to get any of this off the platform, configure a channel as described in [Logging Overview](/latest/logging-overview).

## Change the defaults

Each component has a `logback.properties` next to its `logback-audit.xml`, for example `activeguard/core/logback.properties` and `xcc/backend/logback.properties`. Set only the properties you want to change; anything you leave out keeps the default below.

1. In the [Expert Editor](/latest/expert-editor), open `logback.properties` in the component's directory.
2. Add or change the property.
3. Click **Publish**. The logging configuration becomes active within about one minute.

```shell logback.properties theme={null}
# supported logback.properties with defaults
# ##############################################################
console.default.pattern=%-5level [%thread]: %logger{0} - %msg%n
console.audit.pattern=AUDIT [%versionGitDescription]: %auditLogType - %jsonMsg%n
file.default.pattern=%-5level %d{yyyy-MM-dd HH:mm:ss.SSSXXX} [%thread]: %logger{0} - %msg%n
file.audit.pattern=AUDIT %d{yyyy-MM-dd HH:mm:ss.SSSXXX} [%versionGitDescription]: %auditLogType - %jsonMsg%n
## rolling log file size policy
## 'default' corresponds to the operational events
file.default.maxFileSize=1GB
file.default.totalSizeCap=5GB
file.default.maxHistory=30
file.error.maxFileSize=1GB
file.error.totalSizeCap=5GB
file.error.maxHistory=30
file.audit.maxFileSize=1GB
file.audit.totalSizeCap=5GB
file.audit.maxHistory=30
# Override root logger level and log less events on stdout - actually logged events to stdout have log level >= max(`root.level`, `stdout.filter.level`)
stdout.filter.level=trace
# level of root appender
root.level=debug
```

| Property | Effect |
| :- | :- |
| `*.pattern` | The layout of a line. The converters are the same ones as in [Format Converters](/latest/logging-formats). |
| `file.*.maxFileSize` | Size at which one file rolls over. |
| `file.*.totalSizeCap` | Total compressed size kept for that family, across all rolled files. |
| `file.*.maxHistory` | Number of rolled files kept. |
| `root.level` | Verbosity of the root logger, and therefore the floor for everything the component logs. |
| `stdout.filter.level` | Verbosity on standard output only, which is what `docker compose logs` shows. |

<Warning>
  Making `root.level` less verbose than `debug` also removes the lines xorlab support needs to diagnose a problem. If you change it to save disk, put it back before you open a support case.
</Warning>

<Note>
  These properties change the built-in files only. The events you forward with a `logback-audit.xml` are unaffected — their format is the `pattern` in their own appender.
</Note>


# Choose What to Log
Source: https://docs.xorlab.com/latest/logging-choose-events

Work out which events, which payload format, and which component's configuration file you need, before you touch any file.

Nothing is forwarded off the platform until you name the events you want. Decide that first: the event determines which configuration file you edit.

## Start from a goal

Each row is a complete answer: the events, the format, and the component whose `logback-audit.xml` you edit. The directories behind the container names are in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component).

| Goal | Events | Format | Container |
| :- | :- | :- | :- |
| One rich record per email: verdict, sender, recipients, tags, scores, attachment hashes, extracted URLs | `trace.msg_analysis.complete` | JSON extended | `Core` |
| Every verdict decision, including a verdict that changes later because a Sandbox scan finished out of band | `trace.msg_verdict` | JSON extended | `Core` |
| SMTP mail flow tracing: what was accepted, what was relayed, with queue IDs | `trace.mta.received`, `trace.mta.send` | JSON | `Mta` |
| Correlate an SMTP queue ID with the email's GGRID | `trace.msg_delivered` | JSON | `Core` |
| Full analyst and admin audit trail: message views, downloads, releases, list and campaign changes, config changes | `audit` | JSON | `Backend` |
| Successful and failed logins | `audit.access` | JSON | `Auth` |
| Quarantine release workflow: who requested, approved, or denied | `audit.quarantine.release.request` | JSON | `Backend` |
| Emails evicted from a mailbox by case isolation | `audit.isolate.removed` | JSON | `Backend` |
| Threat intelligence extracted from your own mail | `ti.email`, `ti.ip`, `ti.file`, `ti.domain`, `ti.url` | JSON | `Backend` |
| Backup success and failure | `sys.backup` | JSON | `Backend` |
| Platform lifecycle: startup, shutdown, configuration commits | `sys` | JSON | any |

<Tip>
  **The most common starting point**

  Forward `trace.msg_analysis.complete` with the extended JSON format. That is one record per email carrying the full analysis result, which is what most email dashboards and correlation rules are built on. The complete file is in [Configuration Examples](/latest/logging-examples#log-detailed-email-results).
</Tip>

The full catalog, with event IDs, severities, and the container that emits each one, is [Log Events](/latest/logging-events). Names are prefixes, so `audit` in the table above means every `audit.*` event. See [Names are prefixes](/latest/logging-concept#names-are-prefixes).

## Choose a payload format

The format is a `pattern` inside the appender, so you can use any of these with any channel. No action is needed yet; you fill it into the appender in the channel guide.

<CardGroup>
  <Card title="JSON" icon="code" href="/latest/logging-formats#json">
    Default. Works for every event, and records that event's own attributes.

    ```xml theme={null}
    <pattern>%jsonMsg%n</pattern>
    ```
  </Card>

  <Card title="JSON extended" icon="code" href="/latest/logging-formats#json-extended">
    The complete result of the email analysis as a single record.

    ```xml theme={null}
    <pattern>%coreJsonMsg%n</pattern>
    ```

    <Note>
      Message-tracing (`trace.*`) events only.
    </Note>
  </Card>

  <Card title="CEF" icon="scroll" href="/latest/logging-formats#common-event-format-cef">
    ArcSight-style Common Event Format. Works for every event. Pick it when your platform expects CEF.

    ```xml theme={null}
    <pattern>%cef%n</pattern>
    ```
  </Card>

  <Card title="Single attributes" icon="key" href="/latest/logging-formats#specific-attributes">
    A few named fields instead of the whole record, for a lookup table or a compact alert.

    ```xml theme={null}
    <pattern>%logArg{item} %logArg{listName}%n</pattern>
    ```
  </Card>
</CardGroup>

## Next step

Pick the channel that carries the events you chose.

<CardGroup>
  <Card title="Forward Events over Syslog" icon="tower-broadcast" href="/latest/logging-via-syslog">
    A SIEM, a log collector, or any Syslog listener.
  </Card>

  <Card title="Send an Email When an Event Occurs" icon="envelope" href="/latest/logging-via-email">
    A mail per event, for rare events.
  </Card>

  <Card title="Write Events to a Log File" icon="file" href="/latest/logging-via-file">
    A rolling file on the xorlab host. On-premises only.
  </Card>
</CardGroup>


# How Logging Works
Source: https://docs.xorlab.com/latest/logging-concept

The model behind every logback-audit.xml file: what a logger and an appender do, how event names form a hierarchy, and why each component keeps its own configuration.

xorlab logging is built on the open-source [Logback](http://logback.qos.ch/manual/appenders.html) framework. A configuration is always a pair: a **logger**, which names the event you want, and an **appender**, which says where that event goes and in which format.

<img alt="Log event and appender" />

## Loggers

xorlab services produce log events and feed them into **loggers**. The logger name is the event name, so the [Log Events](/latest/logging-events) reference reflects logger names you can configure: an event called `audit.user.incident` is fed into the logger `audit.user.incident`.

Loggers are organized in a hierarchy, with the **ROOT logger** at the top. A log event travels up the tree from its own logger, and every logger it passes hands it to whatever appenders are attached there.

```
ROOT
+- audit -> [syslogAppender, customAppender1]
   +- user
      +- incident -> [incidentReportSyslogAppender]
      +- msg_delete
```

### Names are prefixes

Because the name is hierarchical, a shorter name catches more events. `name="audit"` logs every `audit.*` event, `name="audit.user"` only the user actions below it. The only valid prefixes are the ones you get by cutting the event name at a dot: `name="aud"` matches nothing.

Subscribing to `audit` and filtering in the SIEM is usually easier than listing every event name below it, as long as you can accept the volume.

### Additivity controls duplicates

By default an event keeps traveling up to ROOT, so a logger on `audit` and a second one on `audit.user.incident` both record an incident, twice. Set `additivity="false"` on the more specific logger to stop the event there:

```xml theme={null}
<logger additivity="false" name="ti.domain">
    <appender-ref ref="threatIntelFileAppender"/>
</logger>
```

A missing `additivity="false"` is the usual cause of duplicate records in a SIEM.

### Severity

Every event carries a fixed severity, listed in [Log Events](/latest/logging-events). It is not a threshold you configure: it travels with the event so your SIEM can prioritize on it.

| Severity | Importance |
| :- | :- |
| 0–3 | Low |
| 4–6 | Medium |
| 7–8 | High |
| 9–10 | Very high |

## Appenders

An **appender** is the destination and the shape of the record: a Syslog server, an email, or a file, formatted as JSON, extended JSON, CEF, or a pattern you assemble yourself. The format is set by the `pattern` inside the appender — see [Format Converters](/latest/logging-formats).

Three rules apply when you write the file:

* An appender must be declared **before** the logger that references it.
* One logger can reference several appenders, so the same event can go to a SIEM and to a local file at once.
* One appender can be referenced by several loggers, so a group of events can share a single destination.

## Flow of an event

1. A component produces an event, for example `audit.user.incident`, and hands it to the logger of that name.
2. The event travels up the hierarchy.
3. At each logger on the way, any attached appender records it.
4. A logger with `additivity="false"` stops the event there.
5. Otherwise it continues until it reaches ROOT.

## One configuration file per component

The platform runs as a set of containers, and a container can only log the events it produces itself. So there is no single logging configuration: each component has its own `logback-audit.xml`, and the event you picked decides which one you edit. If you edit the wrong one, nothing is logged and no error is raised.

The `Container` column in [Log Events](/latest/logging-events) maps to these directories:

| Component | Container | Directory |
| :- | :- | :- |
| MTA | Core | `activeguard/core/` |
| MTA | Mta | `activeguard/mta/audit/` |
| XCC | Backend | `xcc/backend/` |
| XCC | Auth | `auth/auth/` |
| Sandbox | Dana | `/etc/xorlab/dana/default/` |

<Note>
  **Sandbox (Dana) logging is not published**

  `/etc/xorlab/dana/default/` is not part of the [Expert Editor](/latest/expert-editor), so it is edited over SSH and there is no **Publish** step. Restart the Sandbox stack instead, as described in [Operation Reference](/latest/operation-reference#sandbox-dana-2).
</Note>

An event listed with several containers is produced by each of them independently. `audit.user.lists.item_added`, for example, is emitted by both `Core` and `Backend`, so configuring it in one directory records only that component's occurrences.

## The file

Each `logback-audit.xml` is an XML fragment that xorlab includes into the component's own logging configuration, so the root element is `<included>` and not `<configuration>`:

```xml logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
<!-- add <appender> elements on top -->
<!-- add <logger> elements below -->
</included>
```

The file is hot-reloaded: after you click **Publish**, the logging configuration becomes active within about one minute. No component restart is needed.


# Log Events
Source: https://docs.xorlab.com/latest/logging-events

Every event xorlab can log, with its ID, severity, and the container that emits it. Look up an event name here before configuring a logger for it.

This is the catalog of events you can subscribe to. The event name is also the logger name, so the value in **Event Name** is what goes into `<logger name="...">`.

<Tip>
  **A logger on its own logs nothing**

  Every `logger` needs at least one `appender` to say where the event goes. Start at [Choose What to Log](/latest/logging-choose-events) if you have not configured a channel yet.
</Tip>

## How to read the tables

| Column | What it tells you |
| :- | :- |
| **Event Name** | The logger name. It is hierarchical, so a prefix cut at a dot subscribes to everything below it: `name="sys"` catches every `sys.*` event. See [Names are prefixes](/latest/logging-concept#names-are-prefixes). |
| **Severity** | Travels with the event so your SIEM can prioritize on it. 0–3 low, 4–6 medium, 7–8 high, 9–10 very high. Not a threshold you configure. |
| **Components** | Which container emits the event, and therefore which `logback-audit.xml` you edit. The directory for each one is in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component). An event listed with several containers is emitted by each of them separately. |
| **ID** | A stable numeric identifier, also carried in the CEF payload. The ranges group the events: 0–999 system, 1000–1999 message tracing, 2000–2999 audit trail, 3000–3999 result publication, 4000–4999 threat analysis, 9000+ other. |

## System Events

System events, numbered from 0 to 999, cover basic system functions like startup, shutdown, and configuration changes.

| ID | Event Name | Severity | Description | Components |
| - | - | - | - | - |
| 1 | `sys.startup` | 0 | Startup sequence for system component initiated | `Core`, `Mta`, `Backend`, `Auth`, `Dana` |
| 2 | `sys.ready` | 0 | System component started up successfully and is ready for operation | `Core`, `Mta`, `Backend`, `Auth`, `Dana` |
| 3 | `sys.restart` | 0 | System component is being restarted | `Core` |
| 4 | `sys.shutdown.triggered` | 4 | System component initiated shutdown process | `Core`, `Mta`, `Backend`, `Auth`, `Dana` |
| 5 | `sys.shutdown` | 4 | System component completed shutdown process | `Core`, `Mta`, `Backend`, `Auth`, `Dana` |
| 10 | `sys.config.reloaded` | 0 | System component successfully reloaded configuration | `Core`, `Mta`, `Backend`, `Auth` |
| 11 | `sys.config.downloaded` | 0 | System component downloaded configuration | `Core`, `Mta`, `Backend`, `Auth` |
| 12 | `sys.config.migrated` | 4 | Configuration repository migrated to a new system version | `Core`, `Mta`, `Backend`, `Auth` |
| 13 | `sys.config.commit` | 4 | Revised system configuration committed to the repository | `Core`, `Mta`, `Backend`, `Auth` |
| 20 | `sys.backup.started` | 7 | The backup service started creating a backup | `Backend` |
| 21 | `sys.backup.resumed` | 7 | The backup service found an incomplete backup and is resuming it | `Backend` |
| 28 | `sys.backup.failed` | 10 | The backup service failed to create a backup | `Backend` |
| 29 | `sys.backup.completed` | 7 | The backup service successfully created a new backup | `Backend` |
| 30 | `sys.recovery.started` | 10 | The recovery service started the recovery process | `Backend` |
| 38 | `sys.recovery.failed` | 10 | The recovery service finished recovery with errors | `Backend` |
| 39 | `sys.recovery.completed` | 10 | The recovery service completed the recovery process | `Backend` |
| 43 | `sys.synchronizing.progress` | 0 | XCC data synchronization in progress | `Backend` |
| 44 | `sys.dynamic_rule_list.update` | 0 | Dynamic rule lists have been updated. | `Core` |
| 99 | `sys.admin.other` | 7 | Other administrative action affecting the system | `Core` |

## Message-tracing events

Message-tracing events, numbered from 1000 to 1999, track the flow of emails and messages through the system.

| ID | Event Name | Severity | Description | Components |
| - | - | - | - | - |
| 1000 | `trace.mta.received` | 3 | xorlab accepted an email (SMTP status code 2xx if successful) | `Mta` |
| 1001 | `trace.mta.send` | 3 | xorlab relayed an email (SMTP status code 2xx if successful). Use in combination with trace.msg\_delivered to correlate queue ID and GGRID | `Mta` |
| 1007 | `trace.msg_analysis.mail_import_command_queue_insert` | 0 | Mail import command queued | `Backend` |
| 1008 | `trace.msg_analysis.receiving` | 0 | Email analysis engine of xorlab received an email | `Core` |
| 1009 | `trace.msg_analysis.received` | 0 | Email analysis engine of xorlab accepted/rejected an email | `Core` |
| 1010 | `trace.msg_analysis.start` | 0 | Message analysis started | `Core` |
| 1100 | `trace.dynamic_analysis.request` | 0 | xorlab Core requested a Sandbox scan for one of the attached files | `Core` |
| 1120 | `trace.dynamic_analysis.queued` | 0 | Sandbox request queued | `Dana` |
| 1129 | `trace.dynamic_analysis.complete` | 0 | Sandbox request completed | `Dana` |
| 1130 | `trace.dynamic_analysis.cleanup` | 0 | Sandbox result removed | `Dana` |
| 1140 | `trace.dynamic_scan.start` | 0 | Sandbox spun up a VM for the in-depth analysis of a file | `Dana` |
| 1141 | `trace.dynamic_scan.retry` | 4 | Failed Sandbox scan retries an analysis step on a specific VM | `Dana` |
| 1149 | `trace.dynamic_scan.complete` | 0 | Sandbox completed an analysis step on a specific VM | `Dana` |
| 1199 | `trace.dynamic_analysis.response` | 0 | Sandbox file analysis completed | `Core` |
| 1300 | `trace.msg_verdict` | 0 | xorlab decided the message verdict. This event will be logged twice for emails with attachments for which a Sandbox scan was performed out-of-band | `Core` |
| 1301 | `trace.msg_analysis.complete` | 0 | Message analysis finalized<br />Notes:<br />1. Logged once per email<br />2. Decision code is appended to the key | `Core` |
| 1400 | `trace.msg_released` | 0 | Message released from quarantine<br />Note: Does not support email results extensions (`logging-formats.md#message-tracing`) | `Core` |
| 1402 | `trace.msg_delivered` | 0 | xorlab Core delivered an email to the Mta<br />Note: Contains SMTP queue ID for correlation with `trace.mta.send` | `Core` |
| 1403 | `trace.msg_delivered_internal` | 0 | A mail was delivered by relaying it internally to its destination tenant | `Core` |
| 1410 | `trace.msg_notification` | 0 | A notification mail was sent | `Core` |
| 1411 | `trace.delivery_status.delivered` | 0 | A message was put into the delivered state for a specific recipient | `Backend` |
| 1412 | `trace.delivery_status.removed` | 0 | A message was not delivered to a specific recipient and was removed from the queue | `Backend` |
| 1900 | `trace.msg_analysis.error` | 3 | xorlab encountered an error during message analysis | `Core` |
| 1901 | `trace.msg_analysis.resume` | 0 | xorlab has resumed message analysis (after being interrupted, e.g., because of an outage) | `Core` |
| 1950 | `trace.mail_import.indexing.start` | 0 | Mail import indexing phase started | `Backend` |
| 1951 | `trace.mail_import.indexing.complete` | 0 | Mail import indexing phase completed | `Backend` |
| 1952 | `trace.mail_import.importing.start` | 0 | Mail import importing phase started | `Backend` |
| 1953 | `trace.mail_import.importing.complete` | 0 | Mail import importing phase completed | `Backend` |
| 1954 | `trace.mail_import.complete` | 0 | Mail import job completed successfully | `Backend` |

## Audit trail events

Audit events, numbered from 2000 to 2999, capture user interactions and administrative actions within the XCC web interface.

| ID | Event Name | Severity | Description | Components |
| - | - | - | - | - |
| 2000 | `audit.access.granted` | 4 | User authentication succeeded | `Auth` |
| 2001 | `audit.access.denied` | 6 | User authentication failed | `Auth` |
| 2002 | `audit.access.mfa_required` | 0 | Authentication requires an additional MFA factor | `Auth` |
| 2003 | `audit.access.mfa_totp_secret_updated` | 0 | TOTP secret updated through onboarding | `Backend` |
| 2010 | `audit.user.msg_list` | 4 | User viewed message list information | `Backend` |
| 2011 | `audit.user.msg_details` | 4 | User viewed message details | `Backend` |
| 2012 | `audit.user.msg_download` | 6 | User downloaded an email-related asset | `Backend` |
| 2099 | `audit.user.msg_delete` | 7 | User deleted a message | `Backend` |
| 2100 | `audit.user.quarantine_release` | 6 | User released a quarantined message | `Backend` |
| 2103 | `audit.user.incident.resolved.verdict` | 7 | User resolved a reported incident with a verdict | `Backend` |
| 2104 | `audit.user.incident.comment` | 4 | User added a comment to a reported incident | `Backend` |
| 2130 | `audit.isolate.removed` | 7 | Analyst triggered the eviction of an email out of a recipient’s inbox | `Backend` |
| 2140 | `audit.quarantine.release.request.created` | 6 | User created a quarantine release request | `Backend` |
| 2141 | `audit.quarantine.release.request.approved` | 6 | Quarantine release request approved | `Backend` |
| 2142 | `audit.quarantine.release.request.denied` | 6 | Quarantine release request denied | `Backend` |
| 2150 | `audit.quarantine.archive` | 3 | User archived a quarantined message | `Backend` |
| 2200 | `audit.user.dynamic_analysis` | 4 | User requested a Sandbox scan for a file | `Backend` |
| 2300 | `audit.user.lists.item_added` | 7 | User added an item to a rule list | `Core`, `Backend` |
| 2301 | `audit.user.lists.item_removed` | 7 | User removed an item from a rule list | `Core`, `Backend` |
| 2302 | `audit.user.lists.item_replaced` | 7 | User replaced an item in a rule list | `Core`, `Backend` |
| 2399 | `audit.user.config.file_modified` | 7 | User modified system configuration | `Backend` |
| 2400 | `audit.user.data_export` | 4 | User exported data from a saved campaign, query, or metadata (result.json) | `Backend` |
| 2410 | `audit.user.misclassification.submitted` | 5 | User submitted a misclassification to xCloud | `Backend` |
| 2420 | `audit.user.incident.reanalyze` | 5 | User reanalyzed a message | `Backend` |
| 2500 | `audit.user.search.added` | 0 | User created a saved search | `Backend` |
| 2501 | `audit.user.search.removed` | 0 | User deleted a saved search | `Backend` |
| 2502 | `audit.user.search.updated` | 0 | User updated a saved search or its display text | `Backend` |
| 2600 | `audit.user.campaign.added` | 6 | User created a campaign | `Backend` |
| 2601 | `audit.user.campaign.removed` | 6 | User deleted a campaign | `Backend` |
| 2602 | `audit.user.campaign.updated` | 6 | User updated a campaign query, display text, or action | `Backend` |
| 2603 | `audit.user.campaign.archived` | 6 | User archived a campaign | `Backend` |
| 2700 | `audit.user.tag.added` | 0 | User manually added a tag to one or more messages | `Backend` |
| 2702 | `audit.user.tag.removed` | 0 | User manually removed a tag from one or more messages | `Backend` |
| 2800 | `audit.user.backup.triggered` | 7 | User manually triggered a backup | `Backend` |
| 2850 | `audit.user.mail_import.job.created` | 4 | User created a mail import job | `Backend` |
| 2851 | `audit.user.mail_import.job.paused` | 4 | User paused a mail import job | `Backend` |
| 2852 | `audit.user.mail_import.job.resumed` | 4 | User resumed a mail import job | `Backend` |
| 2853 | `audit.user.mail_import.job.cancelled` | 4 | User cancelled a mail import job | `Backend` |
| 2900 | `audit.quarantine.digest.enqueued` | 0 | Quarantine digest notifications enqueued in the MTA command queue | `Backend` |

## Result publication tracing events

Result publication tracing events, numbered from 3000 to 3999, capture result synchronization and publication flow.

| ID | Event Name | Severity | Description | Components |
| - | - | - | - | - |
| 3000 | `trace.res_pub.received` | 0 | Result publication received by XCC | `Backend` |

## Threat analysis events

Threat analysis events, numbered from 4000 to 4999, record details about detected threats and threat intelligence attributes.

| ID | Event Name | Severity | Description | Components |
| - | - | - | - | - |
| 4000 | `ti.email` | 7 | Threat intel entry for malicious sender email address | `Backend` |
| 4001 | `ti.ip` | 7 | Threat intel entry for malicious sending MTA IP address | `Backend` |
| 4002 | `ti.file` | 7 | Threat intel entry for malicious attachment | `Backend` |
| 4003 | `ti.domain` | 7 | Threat intel entry for malicious embedded domain | `Backend` |
| 4004 | `ti.url` | 7 | Threat intel entry for malicious embedded URL | `Backend` |

## Other events

Other events, numbered from 9000 to 9999, include miscellaneous or maintenance-related events.

| ID | Event Name | Severity | Description | Components |
| - | - | - | - | - |
| 9001 | `sys.mta` | 0 | Postfix activity log entry | `Mta` |
| 9004 | `audit.xcc_instance_metrics.submitted` | 0 | XCC submitted instance metrics to xCloud | `Backend` |
| 9990 | `sys.deprecation.warn` | 6 | Deprecated feature or configuration in use and requires attention | `Core` |


# Configuration Examples
Source: https://docs.xorlab.com/latest/logging-examples

Complete logback-audit.xml files for the goals people configure most: verdicts, the audit trail, SMTP tracing, and threat intelligence export.

Every example below is a whole file. Paste it into the directory it names, change the destination, and click **Publish** — the logging configuration becomes active within about one minute. Then confirm it works with [Verify and Troubleshoot Logging](/latest/logging-verify).

| Goal | File to edit |
| :- | :- |
| [Log detailed email results](#log-detailed-email-results) | `activeguard/core/logback-audit.xml` |
| [Log audit events](#log-audit-events) | `xcc/backend/logback-audit.xml` |
| [Log SMTP email traces](#log-smtp-email-traces) | `activeguard/mta/audit/logback-audit.xml` |
| [Log detailed email results per verdict](#log-detailed-email-results-per-verdict) | `activeguard/core/logback-audit.xml` |
| [Log threat intelligence](#log-threat-intelligence) | `xcc/backend/logback-audit.xml` |
| [Mail a quarantine release request](/latest/logging-via-email) | `xcc/backend/logback-audit.xml` |

If a file already exists in that directory, merge the `appender` and `logger` elements into it rather than replacing it. A new `logger` can reference an `appender` that is already in the file, so there is no need for a second one.

## Log detailed email results

One record per email carrying the complete analysis result, sent to a remote Syslog server. This is the configuration most SIEM projects start from.

| Setting | Value |
| :- | :- |
| Event | `trace.msg_analysis.complete` |
| Container | `Core` |
| Appender | `SyslogAppender` |
| Format | `%coreJsonMsg%n` |

```xml activeguard/core/logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>

  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%coreJsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Log once for each message when the processing has finished -->
  <logger name="trace.msg_analysis.complete">
     <appender-ref ref="syslogAppender"/>
  </logger>

</included>
```

<Warning>
  Extended JSON records exceed the 1500-byte UDP limit and are truncated. For this example in particular, switch to [TCP or TLS](/latest/logging-via-syslog#use-syslog-with-tcp-or-tls).
</Warning>

## Log audit events

Every action an analyst or admin takes in XCC, in JSON, to a remote Syslog server. The logger name is the prefix `audit`, so it covers all of the sub-categories.

| Setting | Value |
| :- | :- |
| Events | `audit` and everything below it |
| Container | `Backend` |
| Appender | `SyslogAppender` |
| Format | `%jsonMsg%n` |

```xml xcc/backend/logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Log all user audit events -->
  <logger name="audit">
    <appender-ref ref="syslogAppender"/>
  </logger>
</included>
```

<Tip>
  **Logins are missing from this one**

  Successful and failed logins are emitted by the `Auth` container, not by `Backend`. Put the same file in `auth/auth/` as well to capture `audit.access.*`.
</Tip>

## Log SMTP email traces

One JSON record when an email is accepted over SMTP, and another for each delivery attempt. This is the mail flow view, for checking whether an email reached xorlab and whether xorlab handed it on.

| Setting | Value |
| :- | :- |
| Events | `trace.mta.received`, `trace.mta.send` |
| Container | `Mta` |
| Appender | `SyslogAppender` |
| Format | `%jsonMsg%n` |

```xml activeguard/mta/audit/logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>192.168.1.100</syslogHost>
    <port>514</port>
    <hostName>xorlabhostname</hostName>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Log received and send SMTP events. Alternatively, you can name a single logger 'trace.mta'. -->
  <logger name="trace.mta.received">
    <appender-ref ref="syslogAppender"/>
  </logger>
  <logger name="trace.mta.send">
    <appender-ref ref="syslogAppender"/>
  </logger>
</included>
```

<Tip>
  **How to log all SMTP logs**

  To forward the complete SMTP log rather than the accept and relay events only, replace the name of the first logger with `trace.mta` and remove the second logger. That is the whole Postfix activity log, so check the volume first.
</Tip>

### Correlate the queue ID with the GGRID

The two events above carry the SMTP queue ID. To join it to the email's GGRID, the identifier used by XCC and the analysis, add this event on the `Core` container as well.

| Setting | Value |
| :- | :- |
| Event | `trace.msg_delivered` |
| Container | `Core` |
| Appender | `SyslogAppender` |
| Format | `%coreJsonMsg%n` |

```xml activeguard/core/logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>192.168.1.100</syslogHost>
    <port>514</port>
    <hostName>xorlabhostname</hostName>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%coreJsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Log the queue ID, which can be used to correlate with the trace.mta.send event -->
  <logger name="trace.msg_delivered">
    <appender-ref ref="syslogAppender"/>
  </logger>
</included>
```

## Log detailed email results per verdict

A record every time a verdict is reached, rather than once per email. The case this exists for:

* An email looks legitimate and is delivered, but
* a delayed or offline Sandbox scan later changes the verdict from benign to malicious.

You then get two records for the same email, one per verdict, so the change of status is visible in the SIEM instead of being overwritten.

| Setting | Value |
| :- | :- |
| Event | `trace.msg_verdict` |
| Container | `Core` |
| Appender | `SyslogAppender` |
| Format | `%coreJsonMsg%n` |

```xml activeguard/core/logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%coreJsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Log the trace.msg_verdict event -->
  <logger name="trace.msg_verdict">
    <appender-ref ref="syslogAppender"/>
  </logger>
</included>
```

## Log threat intelligence

One JSON record per malicious domain observed in your own mail, written to a local file **and** sent over Syslog. It is also the example to copy for sending any event to two destinations at once, and the only one here that needs `additivity`.

| Setting | Value |
| :- | :- |
| Event | `ti.domain` |
| Container | `Backend` |
| Appenders | `RollingFileAppender`, `SyslogAppender` |
| Format | `%jsonMsg%n` |

<Tip>
  **On-premises only**

  Writing to local files is only supported for xorlab on-premises. On a hosted deployment, keep the Syslog appender and drop the file appender.
</Tip>

```xml xcc/backend/logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>
  <!-- Write logs into a local file with a rollover policy -->
   <appender name="threatIntelFileAppender" class="ch.qos.logback.core.rolling.RollingFileAppender">
     <file>${log_dir}/domain_ti_json.log</file>
     <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
       <!-- roll over daily -->
       <fileNamePattern>${log_dir}/domain_ti_json_%d{yyyy-MM-dd}.%i.log.zip</fileNamePattern>
       <maxFileSize>100MB</maxFileSize>
       <!-- total (compressed) size of all parts  -->
       <totalSizeCap>500MB</totalSizeCap>
       <!-- Number of roll overs to keep -->
       <maxHistory>60</maxHistory>
     </rollingPolicy>
     <encoder>
       <pattern>%jsonMsg%n</pattern>
     </encoder>
   </appender>

  <appender name="threatIntelSyslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Log all ti.domain events -->
  <logger additivity="false" level="debug" name="ti.domain">
    <appender-ref ref="threatIntelFileAppender"/>
    <appender-ref ref="threatIntelSyslogAppender"/>
  </logger>
</included>
```

For the other indicator types, add a logger for `ti.email`, `ti.ip`, `ti.file`, and `ti.url` referencing the same appenders — or use the prefix `ti` for all of them. What each one carries is in [Connect a SIEM](/latest/integrations-siem#export-threat-intelligence).


# Format Converters
Source: https://docs.xorlab.com/latest/logging-formats

The payload shapes a log record can take, from JSON to CEF to a few named fields, and the pattern that selects each one.

The shape of a record is set by the `pattern` inside the `encoder` of an appender, so the same choice applies to Syslog, email, and file appenders alike:

```xml theme={null}
<appender>
  <encoder>
    <pattern>%jsonMsg%n</pattern>
  </encoder>
</appender>
```

| Converter | Pattern | Scope |
| :- | :- | :- |
| [JSON](#json) | `%jsonMsg%n` | Every event |
| [JSON extended](#json-extended) | `%coreJsonMsg%n` | Message-tracing (`trace.*`) events |
| [CEF](#common-event-format-cef) | `%cef%n` | Every event |
| [Specific attributes](#specific-attributes) | `%logArg{key}%n` | Every event |

Always end a pattern with `%n`, the line break. Without it, records run into each other.

## Converters

### JSON

The most common choice on xorlab, and the default in every guide. It records the attributes of the event itself, as one JSON object per record.

```xml theme={null}
<appender>
  <encoder>
    <pattern>%jsonMsg%n</pattern>
  </encoder>
</appender>
```

### JSON extended

Only for [Message-tracing events](/latest/logging-events#message-tracing-events), numbered 1000 to 1999. Instead of the attributes of that one event, it records the whole result of the email analysis as a single entry: verdict, scores, tags, participants, attachments with hashes, and extracted indicators.

```xml theme={null}
<appender>
  <encoder>
    <pattern>%coreJsonMsg%n</pattern>
  </encoder>
</appender>
```

<Accordion title="Example JSON">
  ```yaml theme={null}
    {
        "source": "activeguard",
        "version": "release-6.7.0",
        "ggrid": "1b35699e-5ca4-4ee6-84b6-3c4b54c3d5e2",
        "decision": "UNDECIDED",
        "type": "Emails",
        "created": "2020-03-30T16:51:48.433+0200",
        "decided": "",
        "completed": "",
        "risk": 0,
        "trust": 0,
        "threat": 20,
        "reputation": 0,
        "tags": [
            "#suspicious"
        ],
        "mail": {
            "headers": [
                {
                    "name": "x-spam-status",
                    "value": "-----spam-status-----"
                }
            ],
            "subject": "Good morning",
            "sent": "",
            "direction": "INCOMING",
            "from": [
                {
                    "email": "han.solo@lucasartsthe-rebels.com",
                    "display_name": ""
                }
            ],
            "to": [
                {
                    "email": "chewy@lucasartschewbacca@the-rebels.com",
                    "display_name": ""
                },
                {
                    "email": "luke@lucasartsthe-rebels.com",
                    "display_name": "Lightsaber Guy"
                }
            ],
            "reply_to": [
                {
                    "email": "theguy@lucasartsadmin@the-rebels.com",
                    "display_name": ""
                }
            ],
            "attachments": [
                {
                    "name": "archive.zip",
                    "sha256": "beef123",
                    "size": 1027
                },
                {
                    "name": "logo.png",
                    "sha256": "beef123",
                    "size": 127
                }
            ],
            "threat_intel_emails": [
                "admin@death-star.com"
            ],
            "threat_intel_domains": [
                "suspicious1.dangerous.com",
                "suspicious2.dangerous.com"
            ],
            "threat_intel_urls": [
                "http://www.ww3.com/foo.sh"
            ]
        }
    }
  ```
</Accordion>

<Warning>
  A record like the one above is well over the 1500-byte limit that UDP Syslog truncates at. Use [TCP or TLS](/latest/logging-via-syslog#use-syslog-with-tcp-or-tls) with this converter.
</Warning>

One exception is worth knowing: `trace.msg_released` does not support the email result extension, so a release from quarantine is recorded without the analysis result.

#### Parameters

Extended JSON takes parameters in curly brackets, `%coreJsonMsg{param1,param2,param3,...}`, to control the subject and to add email headers:

| Parameter | Description |
| :- | :- |
| `param1` | Include or exclude the subject in the JSON. Supported values:<br />`ALWAYS` (default)<br />`NEVER`<br />`ON_DROP_BOUNCE_AND_QUARANTINE` |
| `param2` to `paramX` | A list of headers of the email that will be added to the JSON message |

The following pattern leaves the subject out and always adds the `message-id` and `x-custom-header` headers, which is a common requirement where the subject line is treated as personal data:

```xml theme={null}
<encoder>
<pattern>%coreJsonMsg{NEVER,message-id,x-custom-header}%n</pattern>
</encoder>
```

`ON_DROP_BOUNCE_AND_QUARANTINE` is the middle ground: the subject is recorded only for mail that was dropped, bounced, or quarantined. See also [Change Storing of Subject](/latest/data-retention-subject).

### Specific attributes

`%logArg{}` records named key-value pairs instead of the whole event. It works for any event, in any appender, on every component. To find the key names, configure the appender with `%jsonMsg%n` first, look at one record, then narrow it down.

```xml theme={null}
<appender name="customListAppender" class="ch.qos.logback.core.FileAppender">
  <file>${log_dir}/Custom_list.log</file>
  <append>true</append>
  <encoder>
    <pattern>%logArg{item} %logArg{listName}%n</pattern>
  </encoder>
</appender>

<logger name="audit.user.lists.item_added">
  <appender-ref ref="customListAppender"/>
</logger>
```

This is also how you build a readable email body out of a single event. See [Send an Email When an Event Occurs](/latest/logging-via-email).

### Common Event Format (CEF)

CEF is what ArcSight-style platforms and CEF data connectors expect. Select it with `%cef`:

```xml theme={null}
<appender name="syslogCEFAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
  <syslogHost>syslog.xorlab.com</syslogHost>
  <port>514</port>
  <protocol>UDP</protocol>
  <encoder>
    <pattern>%cef%n</pattern>
  </encoder>
</appender>
```

A CEF record starts with static properties, the event ID and name among them, followed by the event-specific payload:

```text theme={null}
CEF:0|xorlab|ActiveGuard|release-6.7.0-253-gcce39f1b9|1300|trace.msg_verdict|4|ggrid=b950ffd2-00a1-498f-a248-d8376e47f9b9 decision=QUARANTINE direction=INCOMING from=hansolo <han.solo@lucasarts.com> to="Chewbacca" 'chewy' <chewy@lucasarts.com>; "Lightsaber Guy" <luke@lucasarts.com>
```

The static properties, present on every event:

| Name | Type | Example |
| :- | :- | :- |
| `format` | String | `CEF:0` |
| `vendor` | String | `xorlab` |
| `product` | String | `ActiveGuard` |
| `version` | String | `release-<MAJOR>.<MINOR>.<PATCH>` |
| `event_id` | Number (1-10000) | `1300` |
| `event_name` | String | `trace.msg_verdict` |
| `severity` | Number (1-10) | `7` |

### Additional converters

A pattern is not limited to one converter. Every standard Logback converter can be combined with the ones above — see the table under [Pattern Layout](http://logback.qos.ch/manual/layouts.html#ClassicPatternLayout) for the full list.

For example, this prefixes the CEF payload with a date:

```xml theme={null}
<appender name="syslogCEFAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
  <syslogHost>syslog.xorlab.com</syslogHost>
  <port>514</port>
  <protocol>UDP</protocol>
  <!-- Add a date string in front of the CEF payload -->
  <encoder>
    <pattern>%date %cef%n</pattern>
  </encoder>
</appender>
```


# Logging Overview
Source: https://docs.xorlab.com/latest/logging-overview

Which xorlab events can leave the platform, the three channels that carry them, and the order to work through the decisions.

xorlab writes its own local log files without any configuration. Everything beyond that is opt-in: no event is sent anywhere until you name it in a logging configuration file.

<Tip>
  **Connecting a SIEM?**

  Start with [Connect a SIEM](/latest/integrations-siem). It covers which events are worth forwarding, which payload format to pick, and where to look in the documentation of Splunk, Microsoft Sentinel, QRadar, Elastic, and others — then sends you back here for the configuration.
</Tip>

## Three decisions

Every logging configuration is the same three decisions, whichever channel you use:

| Decision | Example |
| :- | :- |
| **Which event** should be recorded, and therefore which component's configuration file you edit | `trace.msg_analysis.complete`, in `activeguard/core/` |
| **Which channel** carries it | Syslog, email, or a log file |
| **Which format** the payload uses | JSON, extended JSON, or CEF |

## Steps

| Step | Description |
| :- | :- |
| [How Logging Works](/latest/logging-concept) | **Recommended**. Explanation of loggers, appenders, and why the configuration is split across components. |
| [Choose What to Log](/latest/logging-choose-events) | **Mandatory**. Pick the events and the payload format for what you want to achieve. |
| [Forward Events over Syslog](/latest/logging-via-syslog) | **Optional**. Send events to a SIEM, a log collector, or any Syslog listener. |
| [Send an Email When an Event Occurs](/latest/logging-via-email) | **Optional**. Get a mail for a low-volume event, such as a quarantine release request. |
| [Write Events to a Log File](/latest/logging-via-file) | **Optional**. Write events to a rolling file on the xorlab host. On-premises deployments only. |
| [Verify and Troubleshoot Logging](/latest/logging-verify) | **Mandatory**. Confirm the events arrive, and work out why they do not. |

<Card title="Configuration Examples" icon="scroll" href="/latest/logging-examples">
  Complete, copy-ready configuration files for the most common goals. Start here if you already know which event you want.
</Card>

## What xorlab logs without any configuration

Each component writes an audit log, an error log, and a verbose operational log to the local filesystem, rotated and size-capped. Those files exist whether or not you configure anything in this group. For on-premises deployments, [Built-in Log Files](/latest/logging-built-in-properties) explains how to configure the built-in logs and [Operation Reference](/latest/operation-reference#log-files) shows where they are located.


# Verify and Troubleshoot Logging
Source: https://docs.xorlab.com/latest/logging-verify

Prove a new logging configuration works, and work through the reasons a record goes missing, arrives twice, or gets cut off.

If you suspect that the xorlab part of the logging is not working, the container's own log usually says why — see [Search the container logs for LOG- lines](#search-the-container-logs-for-log-lines).

## Verify a new configuration

1. Wait about a minute after clicking **Publish**, so the configuration is loaded.
2. Produce the event on purpose:
   * For a `trace.*` event, send a test email through xorlab.
   * For an `audit.*` event, do the action in XCC — log in, open a message, release a message from quarantine.
   * For `sys.*`, publish any configuration change.
3. Look for the record at the destination: your SIEM's search, the mailbox you configured, or the file you named.
4. If it is not there, [search the container logs for `LOG-`](#search-the-container-logs-for-log-lines), then work down the tables below.

## Search the container logs for LOG- lines

Logback reports its own problems into the log of the container it runs in, prefixed with `LOG-`.

1. Open **Monitoring** in the XCC side menu. It opens Grafana, which holds the collected container logs; see [Monitoring Overview](/latest/monitoring-overview). Access requires the **Monitoring User** role, see [List of Built-in Roles](/latest/built-in-user-roles).
2. Go to **Explore**.
3. Select the container whose configuration you edited, using the `container_name` label. The container names per component are in [Operation Reference](/latest/operation-reference#container-description).
4. Search for `LOG-`.

That returns every logback line for the container, so a configuration rejected shortly after you published it appears around that timestamp.

## When nothing arrives

| Check | How |
| :- | :- |
| Was the change published? | Saved edits in the Expert Editor do nothing until you click **Publish**. Reopen the file and confirm your appender is in the published version. Sandbox (Dana) logging is the exception: it is edited over SSH and activated by restarting the Sandbox stack, see [Operation Reference](/latest/operation-reference#sandbox-dana-2). |
| Is the file in the right container's directory? | The most common cause. Compare the `Container` column in [Log Events](/latest/logging-events) against the directory table in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component). `audit.access.*` lives in `auth/auth/`, not in `xcc/backend/`. |
| Is the logger name exactly the event name, or a prefix of it? | Only prefixes cut at a dot are valid. `audit.user` works; `audit.us` matches nothing and reports nothing. |
| Is the appender declared before the logger? | An appender must appear above the logger that references it in the file, and the `ref` must match the appender `name` character for character. |
| Is the destination reachable from xorlab? | Syslog leaves from the container that emits the event, so both the MTA and XCC may need the path open. Ports are in the [Network Guide](/latest/network-guide). |
| Does the event really occur? | Some events fire only in a specific mode or configuration. A Sandbox event needs a file to scan, and `trace.msg_delivered_internal` needs a multi-tenant relay. |

## When something arrives but looks wrong

| Symptom | Cause | Fix |
| :- | :- | :- |
| Every record is cut off mid-way | UDP truncates at 1500 bytes by default, and extended JSON is routinely larger | Switch to [TCP or TLS](/latest/logging-via-syslog#use-syslog-with-tcp-or-tls), or raise `messageSizeLimit` |
| The record is nearly empty, or the pattern appears literally | The converter does not apply to that event. `%coreJsonMsg` is for message-tracing (`trace.*`) events only | Use `%jsonMsg` instead, see [Format Converters](/latest/logging-formats) |
| One email produces two verdict records | Expected for `trace.msg_verdict` when an out-of-band Sandbox scan changes the verdict | Nothing to fix; correlate on the GGRID |
| The log source name in the SIEM is wrong or missing | `hostName` is unset | Set `hostName` in the appender, see [Available attributes](/latest/logging-via-syslog#available-attributes) |

## Keep a TCP connection alive

A firewall or load balancer between xorlab and the destination may drop an idle TCP connection, which shows up as records going missing after quiet periods. The `KeepAliveAppender` wraps another appender and makes it emit a periodic no-op, which keeps the connection up.

<Note>
  This is not needed for normal operation. Add it only if you have TCP connection problems.
</Note>

```xml logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>

  <!-- Standard Syslog appender -->
  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <hostName>xorlab</hostName>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Additional KeepAlive appender to trigger periodic keep alives via the Syslog appender.
      This appender should not be referenced by any logger. -->
  <appender name="keepAliveSyslogAppender" class="com.xorlab.sgappliance.shared.logback.KeepAliveAppender">
    <!-- Optional config showing their default values -->
    <!--
    <intervalHours>1</intervalHours>
    <intervalMinutes>60</intervalMinutes>
    <intervalSeconds>3600</intervalSeconds>
    <intervalMilliseconds>3600000</intervalMilliseconds>
    <logType>NOOP</logType>
    <message>noop</message>
    <level>DEBUG</level>
    -->
    <appender-ref ref="syslogAppender"/>
  </appender>

  <!-- Reference the keepAliveSyslogAppender, NOT the syslogAppender -->
  <logger name="audit">
    <appender-ref ref="keepAliveSyslogAppender"/>
  </logger>
</included>
```

Click **Publish**. The logging configuration becomes active within about one minute.


# Send an Email When an Event Occurs
Source: https://docs.xorlab.com/latest/logging-via-email

Attach an SMTP appender to a rare event, such as a reported email or a quarantine release request, so the platform mails an analyst instead of a log collector.

<Warning>
  **Prerequisites**

  * Know which event you want: [Choose What to Log](/latest/logging-choose-events)
</Warning>

This channel sends one mail every time the event occurs. That suits an event a person has to act on, such as a release request waiting for approval or a failed backup, and does not suit anything that happens more than a few times a day.

<Note>
  This is not the notification system your end users see. Quarantine digests, banners, and release notifications are templates, configured under [Notifications Overview](/latest/email-template-overview).
</Note>

## Configure the appender

1. In the [Expert Editor](/latest/expert-editor), go to the directory of the container that emits your event, listed in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component).

2. Open `logback-audit.xml`, or create it if it does not exist yet.

3. Add the appender and the logger. The mail is relayed differently depending on which component sends it, so pick the tab that matches your event's container:

   <Tabs>
     <Tab title="MTA (Core container)">
       Relays through the local MTA on its internal port, so no TLS is involved.

       ```xml activeguard/core/logback-audit.xml theme={null}
       <?xml version="1.0" encoding="UTF-8"?>
       <included>
           <!-- Set to your xorlab domain -->
           <property name="host.name" value="xyz.activeguard.cloud"/>

           <appender name="smtpMailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
               <from>no-reply@${host.name}</from>
               <to>example@xorlab.com</to>
               <subject>Email reported via ${host.name}</subject>

               <layout class="ch.qos.logback.classic.PatternLayout">
                   <pattern>An email was reported\nDate: %d{yyyy-MM-dd HH:mm}\nLink https://${host.name}/messages/all/message/%X{gr.id} \n%jsonMsg\n</pattern>
               </layout>

               <smtpHost>mta.activeguard.xor</smtpHost>
               <smtpPort>10026</smtpPort>
               <evaluator class="com.xorlab.sgappliance.shared.logback.evaluator.LevelEvaluator"/>
           </appender>

           <!-- Change the name to the event you chose -->
           <logger name="trace.msg_analysis.complete.reported">
               <appender-ref ref="smtpMailAppender"/>
           </logger>

       </included>
       ```
     </Tab>

     <Tab title="XCC (Backend container)">
       Submits to the xorlab MTAs over SMTP, so it needs your public MX name and STARTTLS.

       <Warning>
         **TLS limitation**

         This configuration requires that `smtpd_tls_req_ccert = no` is set inside `activeguard/mta/startup_cfg/postfix_custom/main.cf`.
       </Warning>

       ```xml xcc/backend/logback-audit.xml theme={null}
       <?xml version="1.0" encoding="UTF-8"?>
       <included>
           <!-- Set to your xorlab domain -->
           <property name="host.name" value="xyz.activeguard.cloud"/>

           <appender name="smtpMailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
               <from>no-reply@${host.name}</from>
               <to>example@xorlab.com</to>
               <subject>Email Release Request ${host.name}</subject>

               <layout class="ch.qos.logback.classic.PatternLayout">
               <!-- feel free to change the email content here -->
               <pattern>An email was requested for release\nDate: %d{yyyy-MM-dd HH:mm}\nLink: https://${host.name}/messages/all/message/%logArg{ggrid} \n\n</pattern>
               </layout>

               <!-- Set to the MX record that resolves to the xorlab MTAs -->
               <smtpHost>mx.xyz.activeguard.cloud</smtpHost>
               <smtpPort>25</smtpPort>
               <STARTTLS>true</STARTTLS>
               <evaluator class="com.xorlab.sgappliance.shared.logback.evaluator.LevelEvaluator"/>
           </appender>

           <!-- Change the name to the event you chose -->
           <logger name="audit.quarantine.release.request.created">
               <appender-ref ref="smtpMailAppender"/>
           </logger>

       </included>
       ```
     </Tab>
   </Tabs>

4. Set `host.name` to the domain of your xorlab, and `smtpHost` accordingly.

5. Set `to`, `subject` and `pattern` to the recipient and the message body you want. `%d` is the timestamp, `%jsonMsg` the whole event, and `%logArg{key}` a single field from it. The full list is in [Format Converters](/latest/logging-formats).

6. Set `logger name` to the event you chose.

7. Click **Publish**. The logging configuration becomes active within about one minute.

8. Trigger the event once and confirm the mail arrives: [Verify and Troubleshoot Logging](/latest/logging-verify).

<Warning>
  Attach this appender only to an event you know is rare. A logger name that is a prefix, `audit` rather than `audit.quarantine.release.request.created`, turns every analyst click into an email.
</Warning>

## Common use: approve release requests by mail

The Backend example above logs `audit.quarantine.release.request.created`, which is the event behind the Self-Service Quarantine release workflow. The approver gets a mail with a direct link to the message instead of having to watch a queue in XCC. See [Enable Release Requests](/latest/ssq-request-release) for the rest of that setup.


# Write Events to a Log File
Source: https://docs.xorlab.com/latest/logging-via-file

Write chosen events to a rolling file on the xorlab host, with your own size and retention policy, for an agent or a collector to pick up.

<Warning>
  **Prerequisites**

  * Know which event and which format you want: [Choose What to Log](/latest/logging-choose-events)
  * **On-premises deployments only.** There is no filesystem access on a xorlab-hosted deployment, so use [Forward Events over Syslog](/latest/logging-via-syslog) there instead.
</Warning>

This is separate from the log files xorlab writes anyway — those are described in [Built-in Log Files](/latest/logging-built-in-properties) and need no configuration.

## Configure the appender

1. In the [Expert Editor](/latest/expert-editor), go to the directory of the container that emits your event, listed in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component).

2. Open `logback-audit.xml`, or create it if it does not exist yet.

3. Add the appender and the logger:

   ```xml xcc/backend/logback-audit.xml theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <included>
       <appender name="rollingFileAppender" class="ch.qos.logback.core.rolling.RollingFileAppender">
           <file>${log_dir}/mylogfile.log</file>
           <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
               <fileNamePattern>${log_dir}/mylogfile-%d{yyyy-MM-dd}.%i.log.zip</fileNamePattern>
               <maxFileSize>10MB</maxFileSize>
               <maxHistory>30</maxHistory>
           </rollingPolicy>
           <encoder>
               <pattern>%d{yyyy-MM-dd HH:mm:ss} - %jsonMsg%n</pattern>
           </encoder>
       </appender>

       <!-- Change the name to the event you chose -->
       <logger name="audit">
           <appender-ref ref="rollingFileAppender"/>
       </logger>
   </included>
   ```

4. Set `file` and `fileNamePattern` to the file name you want. `${log_dir}` resolves to that component's own log directory on the host, under `/var/log/xorlab/` — see [Operation Reference](/latest/operation-reference#log-files).

5. Set the rolling policy. `maxFileSize` caps one file, `maxHistory` the number of rolled files kept, and `totalSizeCap` the compressed total. Set a bound you can afford. A file appender on a per-email event fills a disk quickly, and nothing else on the host trims it for you.

6. Set `logger name` to the event you chose.

7. Set `pattern` to the format you chose. The alternatives are in [Format Converters](/latest/logging-formats).

8. Click **Publish**. The logging configuration becomes active within about one minute.

9. Trigger the event and confirm the file appears: [Verify and Troubleshoot Logging](/latest/logging-verify).

<Tip>
  One event can go to a file **and** to a SIEM at once — declare both appenders and reference both from the same logger. There is a worked example in [Log threat intelligence](/latest/logging-examples#log-threat-intelligence).
</Tip>


# Forward Events over Syslog
Source: https://docs.xorlab.com/latest/logging-via-syslog

Add a Syslog appender to a component's logback-audit.xml, over UDP, TCP, or TLS, and point it at any listener that accepts Syslog.

<Warning>
  **Prerequisites**

  * Know which event and which format you want: [Choose What to Log](/latest/logging-choose-events)
</Warning>

Syslog is the channel a SIEM or a log collector expects, and the one most deployments use. xorlab appears on the other side as a generic Syslog source, so no vendor app or connector is involved.

## Configure the appender

1. In the [Expert Editor](/latest/expert-editor), go to the directory of the container that emits your event, listed in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component). For `audit.*` events that is `xcc/backend/`.

2. Open `logback-audit.xml`, or create it if it does not exist yet.

3. Add the appender and the logger:

   ```xml xcc/backend/logback-audit.xml theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <included>
       <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
           <syslogHost>syslog.example.com</syslogHost>
           <port>514</port>
           <hostName>xorlab</hostName>
           <protocol>UDP</protocol>
           <facility>LOCAL0</facility>
           <encoder>
               <pattern>%jsonMsg%n</pattern>
           </encoder>
       </appender>

       <!-- Change the name to the event you chose -->
       <logger name="audit">
           <appender-ref ref="syslogAppender"/>
       </logger>
   </included>
   ```

4. Set `syslogHost` and `port` to your Syslog destination, and `hostName` to the name your SIEM should show as the log source. Every parameter the appender accepts is under [Available attributes](#available-attributes).

5. Set `logger name` to the event you chose.

6. Set `pattern` to the format you chose. `%jsonMsg%n` above is the default; the alternatives are in [Format Converters](/latest/logging-formats).

7. For **TCP** or **TLS** instead of UDP, apply [Use Syslog with TCP or TLS](#use-syslog-with-tcp-or-tls) before publishing.

8. Click **Publish**. The logging configuration becomes active within about one minute.

9. Confirm the events arrive: [Verify and Troubleshoot Logging](/latest/logging-verify).

<Note>
  For a Sandbox event, the file is `/etc/xorlab/dana/default/logback-audit.xml`, which is not part of the Expert Editor. Edit it over SSH and restart the Sandbox stack instead of publishing, as described in [Operation Reference](/latest/operation-reference#sandbox-dana-2).
</Note>

<Tip>
  Repeat step 1 for each container that emits an event you want. A login audit trail, for example, needs the same appender in `auth/auth/` as well, because `audit.access.*` is emitted by `Auth` and not by `Backend`.
</Tip>

## Use Syslog with TCP or TLS

UDP truncates messages at 1500 bytes. Use TCP for anything you rely on, and TLS whenever the logs leave your network, for example to a cloud-hosted SIEM.

1. Set `protocol` to `TCP` or to `SSL` for TLS.

2. Wrap the Syslog appender in an `AsyncAppender` and reference that from the logger:

   ```xml xcc/backend/logback-audit.xml highlight={8,15-17,21} theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <included>
       <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
           <syslogHost>syslog.example.com</syslogHost>
           <port>514</port>
           <facility>LOCAL0</facility>
           <!-- Either TCP or SSL -->
           <protocol>TCP</protocol>
           <encoder>
               <pattern>%jsonMsg%n</pattern>
           </encoder>
       </appender>

       <!-- Wrap the AsyncAppender around the SyslogAppender -->
       <appender name="asyncSyslogAppender" class="ch.qos.logback.classic.AsyncAppender">
           <appender-ref ref="syslogAppender" />
       </appender>

       <!-- Reference the AsyncAppender, not the SyslogAppender -->
       <logger name="audit" >
           <appender-ref ref="asyncSyslogAppender"/>
       </logger>
   </included>
   ```

3. Click **Publish**. The logging configuration becomes active within about one minute.

<Warning>
  **The AsyncAppender is mandatory for TCP and TLS**

  Without it, a slow or unreachable destination blocks the component that is writing the log, and xorlab might not work properly.
</Warning>

For an unsigned certificate on the receiving side, add `trustAll`. If the TCP connection is dropped by an idle timeout on a firewall, see [Keep a TCP connection alive](/latest/logging-verify#keep-a-tcp-connection-alive).

## Available attributes

| Parameter | Description |
| :- | :- |
| `syslogHost` | Mandatory syslog daemon host |
| `port` | Configure port of the rsyslog daemon (default: 514) |
| `protocol` | `UDP`, `SSL`, or `TCP` (default: `UDP`)<br />**Note**: Use `AsyncAppender` for SSL and TCP as described in the [Use Syslog with TCP or TLS](#use-syslog-with-tcp-or-tls) section |
| `hostName` | Specify a host name to be included in the log. This is important for log source identifiers in SIEM systems. |
| `facility` | [Syslog facility](https://en.wikipedia.org/wiki/Syslog#Facility)<br />Pick one of these: `KERN`, `USER`, `MAIL`, `DAEMON`, `AUTH`, `SYSLOG`, `LPR`, `NEWS`, `UUCP`, `CRON`, `AUTHPRIV`, `FTP`, `NTP`, `LOG_AUDIT`, `LOG_ALERT`, `CLOCK`, `LOCAL0`, `LOCAL1`, `LOCAL2`, `LOCAL3`, `LOCAL4`, `LOCAL5`, `LOCAL6`, `LOCAL7` |
| `format` | Syslog message format: `RFC3164` (default) or `RFC5424` |
| `pattern` | Syslog message payload structure and format (e.g., JSON or CEF). For more information, please see [Format Converters](/latest/logging-formats) |
| `trustAll` | Allow the use of unsigned TLS certificates |
| `reconnectDelayMillis` | Duration between reconnect attempts in milliseconds (default: 30000) |
| `immediateFail` | `true`, `false` (default: `true`). If set to `false`, log messages will be blocked until (re)-connected.<br />**Important**: Only set to `false` while using `AsyncAppender` |
| `messageSizeLimit` | Optionally constrain message size by truncating it. While using UDP transport, this config's default value is set to 1500 bytes (as this is a common network MTU size). Example: `<messageSizeLimit>1500</messageSizeLimit>` |
| `socketOptions` | Supports the following two child parameters: `keepAlive` (`true` or `false`, default: `true`) and `tcpNoDelay` (`true` or `false`, default: `false`). Example: `<socketOptions><keepAlive>true</keepAlive></socketOptions>` |

## Where to configure the receiving side

The work on the other end is your platform's standard "add a Syslog source" procedure. [Connect a SIEM](/latest/integrations-siem#where-to-configure-it-in-your-siem) links the vendor documentation for Splunk, Microsoft Sentinel, QRadar, Elastic, Graylog, and others.


# Enable Alerts
Source: https://docs.xorlab.com/latest/monitoring-alerts

Create operational alerts in xorlab and forward them to external systems.

Alerting is intended for **operational** monitoring, and can only be used in a limited way to create alerts based on email (security) related data.

<Warning>
  **Prerequisites**

  * Complete [Set Up Monitoring](/latest/monitoring-guide)
</Warning>

Follow these steps to set up alerting:

1. Open the [Expert Editor](/latest/expert-editor).
2. In the following we will activate alerting for XCC. **Repeat all steps below** in the `monitored_mta` folder instead of `monitoring` to activate MTA alerts.
3. Open the file `/monitoring/alertmanager/alertmanager.yml`. Create it if it does not exist. All alert configuration will be done in this file.
4. Choose the desired alert channel and configure it in `alertmanager.yml`. Here we provide examples for email, webhook and Slack integration. You can find the full list of supported integrations on the official [Prometheus Documentation](https://prometheus.io/docs/alerting/latest/configuration/).

   <Tabs>
     <Tab title="Email receiver (basic)">
       This example configuration sends all alerts to a specified email address, see also [prometheus.io - email\_config](https://prometheus.io/docs/alerting/latest/configuration/#email_config).

       ```yaml theme={null}
       global:
         smtp_smarthost: localhost:25
         smtp_from: alertmanager@xorlab.example.com
         smtp_auth_username: <alertmanager>     # Only required if smtp auth is used
         smtp_auth_password: <password>         # Only required if smtp auth is used
         smtp_require_tls: true
         smtp_hello: localhost
         resolve_timeout: 2m

       templates:
       - /config/monitoring/alertmanager/template/email.tmpl
       #  - /config/monitoring/alertmanager/template/custom.tmpl

       receivers:
       - name: email
         email_configs:
         - to: <alert@on-call.example.com>
           from: <alertmanager@xorlab.example.com>
       ```
     </Tab>

     <Tab title="Email receiver (with routing)">
       This example configuration sends alerts to different email addresses, based on the severity of the alerts, see also [prometheus.io - email\_config](https://prometheus.io/docs/alerting/latest/configuration/#email_config). There are four levels of alert severities used by the default alerts: normal, medium, high, and critical.

       ```yaml highlight={2-5,36-37,40-41,44-45,48-49} theme={null}
       global:
         smtp_smarthost: <localhost:25>
         smtp_from: <alertmanager@xorlab.example.com>
         smtp_auth_username: <alertmanager>     # Only required if smtp auth is used
         smtp_auth_password: <password>         # Only required if smtp auth is used
         smtp_require_tls: true
         smtp_hello: localhost
         resolve_timeout: 2m

       templates:
       - /config/monitoring/alertmanager/template/email.tmpl
       #  - /config/monitoring/alertmanager/template/custom.tmpl

       route:
         receiver: email-normal                 # default receiver
         group_by:
         - alertname
         group_wait:       1m                   # initial wait to ensure alerts can be grouped
         group_interval:   5m                   # subsequent alerts wait 30m for new alerts if in an active group
         repeat_interval: 30m                   # wait for 'repeat_interval' before resending active alerts
         continue: false                        # whether an alert should continue matching against subsequent routes
         routes:
         - receiver: email-medium
           matchers:
           - severity="medium"
         - receiver: email-high
           matchers:
           - severity="high"
         - receiver: email-critical
           matchers:
           - severity="critical"

       receivers:
       - name: email-normal
         email_configs:
         - to: '<user1@example.com>, <user2@example.com>'
           from: <alertmanager@xorlab.example.com>
       - name: email-medium
         email_configs:
         - to: '<user1@example.com>, <user2@example.com>'
           from: <alertmanager@xorlab.example.com>
       - name: email-high
         email_configs:
         - to: <on-call@example.com>
           from: <alertmanager@xorlab.example.com>
       - name: email-critical
         email_configs:
         - to: <on-call@example.com>
           from: <alertmanager@xorlab.example.com>
       ```
     </Tab>

     <Tab title="Webhook receiver">
       This example configuration sends all alerts to a specified webhook, see also [prometheus.io - Receiver integration settings](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings)

       ```yaml theme={null}
       route:
         receiver: webhook
         group_by:
         - alertname
         group_wait: 1m
         group_interval: 5m
         repeat_interval: 30m

         routes:
         - receiver: webhook

       receivers:
       - name: webhook
         webhook_configs:
         - url: https://example.com/webhook
       ```
     </Tab>

     <Tab title="Slack receiver">
       This example configuration sends all alerts to a specified **Slack** channel, see also [prometheus.io - Receiver integration settings](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings) and the [Slack documentation](https://api.slack.com/messaging/webhooks).

       ```yaml theme={null}
       global:
         # REPLACE the following slack_api_url with a valid one.
         slack_api_url: https://hooks.slack.com/services/XXXXXXXXXXX/YYYYYYYYYYY/ZZZZZZZZZZZZZZZZZZZZZZZZ
         resolve_timeout: 2m

       receivers:
       - name: slack-alert
         slack_configs:
           channel: <alert>
           text: '{{ template "slack.text.alert" . }}'
       ```
     </Tab>

     <Tab title="No alerts (default)">
       By default, **Alertmanager** does not send alerts to any real receivers, all alerts are routed to a no-op / blackhole receiver.

       ```yaml theme={null}
       route:
         receiver: blackhole
         routes:
         - receiver: blackhole

       receivers:
       - name: blackhole
       ```
     </Tab>
   </Tabs>
5. Optional: You also find some predefined examples in the same folder. Only the file `alertmanager.yml` will be considered, so they can be safely ignored or deleted if not used.
   * `alertmanager.email.yml` - Email notification examples, one basic example and one with severity based routing.
   * `alertmanager.webhook.yml` - Generic webhook example
   * `alertmanager.slack.yml` - Slack integration example.
   <Accordion title="Mixing receivers">
     The different examples can be mixed by configuring different `receivers` and adjusting the `route` configuration accordingly, similar to the *Email receiver (with routing)* example. **Alertmanager** supports more receivers and allows for more advanced configuration (e.g. alerts being sent to more than one receiver, complex routing, etc.), see also [prometheus.io - Route-related settings](https://prometheus.io/docs/alerting/latest/configuration/#route-related-settings).
   </Accordion>
6. Click **Publish**. The alerting becomes active within about one minute. Have a look at [Test and Troubleshoot Alerts](/latest/monitoring-alerts-testing) to verify them.

## Optional: Enable notifications for resolved alerts

If you want to enable notifications about resolved alerts, you have to add the `send_resolved` property and set it to `true` for your selected receiver.

1. Open your active `alertmanager.yml` config file (once for the XCC and once for the MTA).
2. Find the `receivers` group, and under the chosen receiver config add `send_resolved: true`. For example, the receivers config for **email** alerts should look like this:
   ```yaml highlight={8} theme={null}
   (...)
   receivers:
     - name: email-normal
       email_configs:
         - to: alerts@example.com
           from: alertmanager@xorlab.example.com
           html: '{{ template "email.default.html" . }}'
           send_resolved: true
   (...)
   ```
3. Click **Publish**. The monitoring configuration becomes active within about one minute.


# Customize Alerts
Source: https://docs.xorlab.com/latest/monitoring-alerts-customizing

Add your own alerting rules on the XCC or an MTA, and restyle the messages Alertmanager sends.

<Warning>
  **Prerequisites**

  * Complete [Enable Alerting](/latest/monitoring-alerts)
</Warning>

## Create a new alert

Here we will add an XCC alert. To add an MTA alert, apply the same changes but in the `monitored_mta` folder.

<Accordion title="MTA and XCC alerts">
  Custom alerting rules should be added to `/monitoring/prometheus/alert/custom.yml` for alerting rules evaluated on XCC and to `/monitored_mta/prometheus/alert/custom.yml` for alerting rules evaluated on the MTAs. In addition, custom rules must be activated in `/monitoring/prometheus/prometheus.yml`, respectively `/monitored_mta/prometheus/prometheus.yml`.
</Accordion>

1. Open the [Expert Editor](/latest/expert-editor).

2. Navigate to the `/monitoring/prometheus/alert`.

3. Add the custom alert to `custom.yml`. How to write alerts is described in the official Prometheus [Documentation](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/).

4. Add `custom.yml` to the list of `rule_files` in `/monitoring/prometheus/prometheus.yml`:

   ```yaml {7} theme={null}
   rule_files:
     # Default alerting rules
     - /config/monitoring/prometheus/alert/monitoring_alerts.yml
     - /config/monitoring/prometheus/alert/system_alerts.yml
     - /config/monitoring/prometheus/alert/xcc_alerts.yml
     # Custom alerting rules
     - /config/monitoring/prometheus/alert/custom.yml
   ```

   <Note>
     **Use custom.yml**

     Do not edit default rules files. Changes made to the default files might be overwritten by software updates. However you can deactivate default rule files by commenting them out in, or removing them from the `rule_files` list.
   </Note>

5. Click **Publish**. The monitoring configuration becomes active within about one minute.

## Customize a notification template

The following instructions show how to customize a notification template for XCC alerts. For MTA alerts, apply the same changes but in the `monitored_mta` folder.

1. Open the [Expert Editor](/latest/expert-editor).

2. Navigate to the `/monitoring/alertmanager/template/custom.tmpl`, and edit the template. These templates use [Go templating](https://golang.org/pkg/text/template/), some examples can be found in the [Alerting documentation](https://prometheus.io/docs/alerting/latest/notification_examples/).

3. Enable the template by uncommenting the corresponding line in the current Alertmanager config file `monitoring/alertmanager/alertmanager.yml`, and comment out the default template line:

   ```yaml theme={null}
   templates:
     # - /config/monitoring/alertmanager/template/slack.tmpl
     - /config/monitoring/alertmanager/template/custom.tmpl
   ```

4. Click **Publish**. The notification template becomes active within about one minute.


# Test and Troubleshoot Alerts
Source: https://docs.xorlab.com/latest/monitoring-alerts-testing

Fire a synthetic alert to prove the delivery path works, and diagnose it when nothing arrives.

## Trigger a test alert

To trigger a test alert, and verify that the routing and configuration is correct, SSH to the host and execute the following command:

<Tabs>
  <Tab title="XCC">
    ```shell theme={null}
    docker exec -it monitoring_config trigger_an_alert "Summary" "Description" "Severity"
    ```
  </Tab>

  <Tab title="MTA">
    ```shell theme={null}
    docker exec -it monitored_mta_config trigger_an_alert "Summary" "Description" "Severity"
    ```
  </Tab>
</Tabs>

Be patient, as it takes some time for the **Alertmanager** to send the alert. To find out how long you should wait, check the value of `route.group_wait` (or the same value under the specific severity you have used) in the `/monitoring/alertmanager/alertmanager.yml` file opened in the [Expert Editor](/latest/expert-editor) (the default value is one minute).

## Troubleshoot alerts

When something is not working as expected, you can check the logs of **Prometheus** (which creates the Alerts) and **Alertmanager** (which sends the alerts to the external systems \[receivers]) to see if there are any errors:

<Tabs>
  <Tab title="XCC">
    Prometheus logs:

    ```shell theme={null}
    docker logs monitoring_prometheus
    ```

    Alertmanager logs:

    ```shell theme={null}
    docker logs monitoring_alertmanager
    ```
  </Tab>

  <Tab title="MTA">
    Prometheus logs:

    ```shell theme={null}
    docker logs monitored_mta_prometheus
    ```

    Alertmanager logs:

    ```shell theme={null}
    docker logs monitored_mta_alertmanager
    ```
  </Tab>
</Tabs>

If those logs are not enough, you can use the `log.level` setting to enable further debug logs of **Prometheus**. Go to the `/monitoring/prometheus/prometheus.properties` (for XCC monitoring) or `/monitored_mta/prometheus/prometheus.properties` (for MTA monitoring) and uncomment the following line:

```yaml theme={null}
#log.level=debug
```

You can also use this setting to only log messages with these severities (or above):

* `info`
* `warn`
* `error`

You can check if monitoring is running properly by executing the following command and confirming that the status of the containers is `healthy`:

```shell theme={null}
docker ps --filter "name=monitor*"
```


# Monitoring Architecture
Source: https://docs.xorlab.com/latest/monitoring-architecture

How the monitoring and monitored-mta stacks collect metrics and logs on the XCC and MTA VMs.

The monitoring stacks, called `monitoring` on the XCC VM (`/etc/xorlab/monitoring`) and `monitored_mta` on the MTA VMs (`/etc/xorlab/monitored_mta`), collect metrics and logs, and offer the option to send alerts based on those metrics/logs to configured receivers. They include the following components:

* **Node Exporter** to produce host metrics.
* **cAdvisor** to produce container metrics.
* **Prometheus** to collect and store metrics.
* **Promtail** to collect, process, and push logs to Loki.
* **Loki** to store logs (1)
* **Alertmanager** to route alerts to various consumers, e.g., via email, Slack, webhooks, etc.
* **Grafana** to present the metrics and logs on Dashboards, to search system logs and metrics from all VMs with queries, and check alerts. (2)

1. Loki is only part of the XCC `monitoring` stack and not present on the MTAs.
2. Grafana is only part of the XCC `monitoring` stack and not present on the MTAs.

Here's a diagram illustrating the monitoring architecture, connections between components, and their direction, i.e. which component initiates the connection.

<Tabs>
  <Tab title="Overview">
    <img alt="" />
  </Tab>

  <Tab title="XCC detailed">
    <img alt="" />
  </Tab>

  <Tab title="MTA detailed">
    <img alt="" />
  </Tab>
</Tabs>

There are three main aspects to the monitoring stacks: metrics, logs, and alerts.

## Logs

All logs written by Docker containers to `stdout` / `stderr` are captured by the Docker engine (1) and written to files on the host, where they are parsed by **Promtail** (2), which pushes the logs to **Loki** (3). Logs can then be searched and displayed in  Grafana (11). Loki can also create alerts based on regular expressions evaluated against these logs and forward these alerts to **Alertmanager** (13).

## Metrics

**Prometheus** collects metrics from xorlab containers (8), the Docker engine via **cAdvisor** (6), and the host via **Node Exporter** (7). All MTA metrics are first collected by the MTA **Prometheus** and then [federated](https://prometheus.io/docs/prometheus/latest/federation/) by the XCC **Prometheus** (9). Metrics can then be visualized on **Grafana**.

## Alerts

Alerts based on metrics are created by **Prometheus** and then forwarded by **Alertmanager** to the configured receivers. There are two ways to set up alerting:

* Alerts for both the MTAs and XCC can be generated centrally on XCC (14a). This is easier to configure but creates a single point of failure for alerting on the XCC VM.

* Alerts for MTAs and XCC can be generated on all VMs separately (14a + 14b), this is more resilient and the recommended configuration.

See [Alerting](/latest/monitoring-alerts) for more information on how to configure alerts.

Alerts based on logs can only be generated by Loki on XCC, and are routed via the XCC **Alertmanager**.


# Change Logs and Metrics Retention
Source: https://docs.xorlab.com/latest/monitoring-data-retention

Change how long operational logs and metrics are kept in the monitoring dashboard.

**This affects only the data visible in the monitoring dashboard under `/monitoring/`**. If you want to change the retention of email related data, have a look at [Data Retention Overview](/latest/data-retention-overview).

## Change logs retention

This affects the logs stored on the XCC that you can access in the **Monitoring** → **Explore** view.

1. Go to the [Expert Editor](/latest/expert-editor).

2. Open the `/monitoring/loki/local-config.yml`.

3. Change the default value for the `limits_config.retention_period` to set the logs retention period. For a daily load of 100 000 emails, approximately 2.5 GB of disk space is required for the default log retention period of 31 days.

   ```yaml {4} theme={null}
   (...)
   limits_config:
     # Setting to configure the retention time of logs
     retention_period: 31d
     allow_structured_metadata: false
   (...)
   ```

4. Click **Publish**. The new log retention setting becomes active within about one minute.

## Change metrics retention

You can change the retention time for the metrics stored on the XCC and MTAs independently, by adjusting `storage.tsdb.retention.time=30d` in file `prometheus.properties`.
The XCC Prometheus is used for visualizing data on Grafana, while the MTA Prometheus is used only to federate data from other components on the MTAs.

1. Go to the [Expert Editor](/latest/expert-editor).

2. Open the:

   * `/monitoring/prometheus/prometheus.properties` (XCC)

   * `/monitored_mta/prometheus/prometheus.properties` (MTA, changes apply to all MTAs)

3. Uncomment the following highlighted lines, and enter the desired values:

   ```yaml {5,9} theme={null}
   # How long to retain samples in storage. If neither this flag nor "storage.tsdb.retention" nor "storage.tsdb.retention.size"
   # is set, the retention time defaults to 30d. Units Supported: y, w, d, h, m, s, ms.
   #storage.tsdb.retention.time=30d

   # Maximum number of bytes that can be stored for blocks. A unit is required, supported units: B, KB, MB, GB, TB, PB, EB.
   # Ex: "512MB". Based on powers-of-2, so 1KB is 1024B
   #storage.tsdb.retention.size=10GB
   ```

4. Click **Publish**. The new metrics retention setting becomes active within about one minute.


# Set Up Monitoring
Source: https://docs.xorlab.com/latest/monitoring-guide

Set up monitoring so that all metrics and logs are centralized on XCC and visible in the dashboards.

<Warning>
  **Prerequisites**

  * You used the VM setup script to set up the xorlab VMs. If for any reason that was not the case, follow the **Hostname** changes there manually for the XCC: [Setup Script](/latest/vm-setup-script-breakdown#hostname).
</Warning>

1. Open the [Expert Editor](/latest/expert-editor).

2. Navigate to `/monitoring/prometheus/prometheus.yml`.

3. In the `scrape_configs` section, find the `mta` scrape job, and replace `example-mta1/2` with the hostnames of your MTA VMs. If you have more MTAs, add more targets with correct hostnames.

   ```yaml prometheus.yml {11,13} theme={null}
     - job_name: mta
       scheme: https
       tls_config:
         insecure_skip_verify: true
       metrics_path: /federate
       params:
         match[]:
         - '{job!=""}'
       static_configs:
       - targets:
         - example-mta1:9090
       - targets:
         - example-mta2:9090
   ```

4. Click **Publish**. The monitoring configuration becomes active within about one minute; after a few minutes you should start to see data in the monitoring dashboards.

## Set up more than two MTAs

This part is only required when you plan to use more than the default of two MTA VMs.

1. Navigate to `/monitored_mta/prometheus/`.

2. Duplicate an existing `prometheus.yml.vmx.N` file once for each additional MTA.

3. For every additional `prometheus.yml.vmx.N`: Change `external_labels.host` to the name of the respective MTA, e.g. `mta3`.

   ```yaml prometheus.yml.vmx.N {4} theme={null}
   global:
   #  (...)
     external_labels:
       host: mta3
   ```

   Note: Setting the `host` label in `monitored_mta/prometheus/prometheus.yml.vmx.N` as opposed to setting them centrally in the XCC Prometheus config, i.e. `monitoring/prometheus/prometheus.yml`, allows alerts generated on the MTAs to display their own hostname by using `{{ $labels.host }}` in the alert template.

4. Navigate to `/monitored_mta/promtail/`.

5. Duplicate an existing `config.yml.vmx.N` file once for each additional MTA.

6. For every additional `config.yml.vmx.N`: Update the `hosts` label to match the MTA:

   ```yaml config.yml.vmx.N {4} theme={null}
   #  (...)
   labels:
     job: docker-logs
     host: <label>
   ```

7. Click **Publish**. The monitoring configuration becomes active within about one minute.

## Set up Sandbox monitoring

This part is only required and applicable if you run your own Sandbox appliances (DANA) on-premises.

1. Open  `monitoring/prometheus/prometheus.yml`.

2. In the `scrape_configs` section, add the following `dana` job to the end. Set a unique `<HOSTX>` value for each target.

   ```yaml prometheus.yml theme={null}
     - job_name: dana
       scrape_interval: 1m
       scheme: https
       tls_config:
           insecure_skip_verify: true
       metrics_path: /noauth/metrics
       static_configs:
           - targets: [ dana1.example.com:443 ]
           labels:
               host: Dana.<HOST1>
           - targets: [ dana2.example.com:443 ]
           labels:
               host: Dana.<HOST2>
   ```

3. In the same file, scroll up and add `dana_alerts.yml` to `rule_files` to activate alert rules for the Sandbox:

   ```yaml prometheus.yml {6} theme={null}
     rule_files:
       # Default alerting rules
       - /config/monitoring/prometheus/alert/monitoring_alerts.yml
       - /config/monitoring/prometheus/alert/system_alerts.yml
       - /config/monitoring/prometheus/alert/xcc_alerts.yml  
       - /config/monitoring/prometheus/alert/dana_alerts.yml          # add this line
   ```

   <Note>
     **Sandbox Alerts**

     Sandbox alerts will trigger on the XCC. As a consequence, if XCC is down, no Sandbox alerts will be created (in contrast to the MTA alerts that are triggered on the MTAs).
   </Note>

   <img alt="Enabling the Sandbox rule file" />

4. Navigate to `monitoring/grafana/provisioning/dashboards/` and open `custom.yml`

5. Uncomment the `DANA Dashboards`:

   <img alt="Enabling the Sandbox provider" />

6. Click **Publish**. The monitoring configuration becomes active within about one minute.


# Monitoring Overview
Source: https://docs.xorlab.com/latest/monitoring-overview

The two parts of xorlab monitoring: central log and metric collection, and alerting to external systems.

The monitoring of xorlab consists of two parts:

* Collecting logs and metrics centrally on the XCC. This data can then be accessed via the **Monitoring** menu or via `/monitoring/`.
* Sending alerts to external systems based on the logs and metrics.

To set up monitoring for the first time, follow the **Set Up Monitoring** guide. Afterward you can **Enable Alerts**:

<Card title="Set Up Monitoring" icon="rocket-launch" href="/latest/monitoring-guide" />

<Card title="Enable Alerts" icon="sensor-alert" href="/latest/monitoring-alerts" />

Besides this there are additional resources for special topics:

| Topic | Description |
| :- | :- |
| [Change Log and Metric Retention](/latest/monitoring-data-retention) | Define how long monitoring logs and metrics should be stored. This impacts the required disk space. |
| [Customize Alerts](/latest/monitoring-alerts-customizing) | How to create new alerts, and how to customize alert notifications. |
| [Monitoring Architecture](/latest/monitoring-architecture) | Conceptual resource describing how the monitoring system is built up. |


# Enable Tenant Login
Source: https://docs.xorlab.com/latest/multi-tenancy-authentication

Sign-in options per tenant, and which to pick for analyst portals versus employee quarantine access.

We generally recommend to set up SAML to allow tenant analysts to login, and set up Auto-Login for end-users to access SSQ.

<CardGroup>
  <Card title="SAML Login" icon="wand-magic-sparkles" href="#saml-login">
    Can be used to give tenants access to the Analyst portal or for end-users to the SSQ.
  </Card>

  <Card title="Auto-Login" icon="link" href="#auto-login">
    Can be used to give end-users access to the SSQ. Does not require any integration.
  </Card>

  <Card title="Password File Login" icon="file" href="#password-file-login">
    Create local static users for the tenants. Supports optional TOTP onboarding, but is still generally not recommended compared to SAML or LDAP.
  </Card>

  <Card title="LDAP Login" icon="user-tag" href="#ldap-login">
    Can be used to give tenants access to the Analyst portal or for end-users to the SSQ.
  </Card>
</CardGroup>

## SAML Login

<Accordion title="Expand to read the instructions.">
  * List **SAML backend name** under `enabledAuthBackends`
  * Add additional config block to `saml2AuthBackends`
  * Enter the **App Federation Metadata Url** you copied behind the `metadataUrl` key.
  * Map the Entra ID roles to xorlab roles
</Accordion>

```yaml title="auth.yml" hl_lines="4 26-38" theme={null}
enabledAuthBackends:
  # Add the SAML backend name to the list of enabled backends. If you put it as first entry, it will be the new default.
  - entraSAML
  - nameSAML

saml2AuthBackends:
  entraSaml:
    idp:
      # Enter the App Federation Metadata URL from Entra ID
      metadataUrl: https://login.microsoftonline.com/*****************************
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
    roleMapping:
      xcc_admin:
      - entra_xor_admin
      xcc_monitor:
      - entra_xor_admin
      xcc_analyst:
      - entra_xor_analyst
      xcc_insights:
      - entra_xor_admin
      - entra_xor_analyst
  
  nameSAML:
    idp:
      # Enter the App Federation Metadata URL from Entra ID
      metadataUrl: https://login.microsoftonline.com/*****************************
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
      # Name of tenant should be enclosed by "'  '"
      tenant: "'<tenant_name>'" 
    roleMapping:
      xcc_tenant_analyst:
      - entra_xor_analyst
```

<Warning>
  * Make sure the tenant attribute refers to the name defined in guarded\_tenants.yml, e.g. `"'tenant_A'"` and that the SAML backend name matches the last part of the identifier and replyURL.

  * Make sure to assign tenant specific user roles in the roleMapping if you want to restrict this user to a specific tenant environment. For more info on the scope of roles, please refer to [List of Built-in Roles](/latest/built-in-user-roles)
</Warning>

After updating `auth/auth/auth.yml`, click **Publish**. The authentication configuration becomes active within about one minute.

You can test the login with the link `https://xyz.activeguard.cloud/?_agAuthBackend=nameSAML`. Replace `xyz` with your customer ID and `nameSAML` with the **SAML backend name**.

## Auto-Login

The [Auto-Login](/latest/authentication-auto-login-link) authentication method is compatible with multi-tenancy environments and can be enabled separately for each tenant.

1. Open  `/shared/guarded_tenants.yml` in the Expert Editor.

2. Add the following configuration to each tenant:

   <Accordion title="Expand to read the instructions.">
     * Include the `autoLoginLink` block for each tenant.
     * `expirationDays` defines the validity period of the authentication link.
     * The default of `expirationDays` is 7 days.
     * To make links permanent, set `expirationDays` to `-1`.
   </Accordion>

   ```yaml /shared/guarded_tenants.yml {5-7,12-14} theme={null}
   tenants:
     - name: tenantA
       domains:
         - tenantA.com
       autoLoginLink:
         enabled: true
         expirationDays: 7  

     - name: tenantB
       domains:
         - tenantB.com
       autoLoginLink:
         enabled: true
         expirationDays: -1 
   ```

3. Click **Publish**. The tenant configuration becomes active within about one minute.

## Password File Login

<Accordion title="Expand to read the instructions.">
  * The `tenant` attribute should reference `name` defined in `guarded_tenants.yml`
  * For `passwordHash`, generate a password hash [password hash generator](/latest/authentication-with-a-password-file#password-hash-generator)
  * Map to a [tenant-restricted user roles](/latest/built-in-user-roles)

  > Using a password file for authentication is generally not recommended. If you use it, prefer enabling TOTP onboarding for privileged users.
</Accordion>

```yaml /auth/auth/passwordFile.yml {3,9} theme={null}
users:
  - username: user1
    tenant: tenantA # Corresponds to <name> in guarded_tenants.yml
    passwordHash: "{bcrypt}$2y$10$.4If2RFwcvHRrxlR98m9ju/mCRYCHLAYULByGXvJY.jBuK2/bckZu"
    roles:
      - xcc_tenant_analyst
    
  - username: user2
    tenant: tenantB # Corresponds to <name> in guarded_tenants.yml
    passwordHash: "{bcrypt}$2y$10$nBZobaznyYv0Ki.lY8jNV.ls2uGh3VmsZivoG4XcdzKQU66qCHAAa"
    roles:
      - xcc_tenant_analyst
```

After updating `auth/auth/passwordFile.yml`, click **Publish**. The users become available within about one minute.

## LDAP Login

<Accordion title="Expand to read the instructions.">
  * Follow the [LDAP-based Authentication Setup Guide](/latest/authentication-ldap)
  * The `tenant` attribute should reference `name` defined in `guarded_tenants.yml`
  * For `roleMapping`, make sure to map [tenant-restricted user roles](/latest/built-in-user-roles)
</Accordion>

```yaml /auth/auth/auth.yml {21} theme={null}
ldapAuthBackends:
    ldapAuthDataSources:
      xorlabLDAP:
        host: ldap.tenantA.com
        port: 10636
        authentication:
          withQueryDn:
            bindDn: ""
            bindPassword: ""
            userBase: "ou=users,dc=tenant,dc=com"
            userSearch: "(uid={0})"
        authorization:
          query:
            roleBase: "ou=groups,dc=tenant,dc=com"
            roleSearch: "(uniqueMember={0})"
            nestedRoleDepth: 5
        attributeMapping:
          userName: "attr('uid')"
          displayName: "attr('cn')"
          emails: "attr('mail')"
          tenant: "'tenantA'" # Corresponds to "'<name>'" in guarded_tenants.yml
        roleMapping:
          xcc_tenant_analyst: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_tenant_analyst_audit: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
```

After updating `auth/auth/auth.yml`, click **Publish**. The LDAP authentication configuration becomes active within about one minute.


# Using Tenant Config Templates
Source: https://docs.xorlab.com/latest/multi-tenancy-configsets

Define reusable tenant configuration templates with configSets in guarded_tenants.yml.

A config set supports the following parameters. All those parameters can also be set directly on a tenant.

```yaml guarded_tenants.yml theme={null}
configSets:
  default:
    interTenantMessageSplitting: true
    tenantSelector: {}
    tenantSelectors: []
    autoLoginLink: {}
    quarantine: {}
    dataRetention: {}
    emailTemplateStyle: default
    messageProcessing: {}
    emailReporting: {}
    trustedMTAs: {}
    ruleProfiles: {}

```

Checkout the [guarded\_tenants.yml](/latest/guarded_tenants_yml) for more details what each attribute supports.

<Note>
  You can overwrite single parameters of the `default` set without having to specify all other parameters.
</Note>

You can create new config sets and reference them in some tenants. The `default` set is always applied to all tenants with the least precedence.

```yaml guarded_tenants.yml theme={null}
configSets:
  allowPhishingRequest:
    quarantine:
      quarantines:
          - name: Phishing
            canRelease: true

tenants:
    name: xorlab
    ## Applied config sets, notice that later occurrences will override earlier config set occurrences.
    ## Further, the "default" set is implicitly referenced with least precedence.
    configSets:
        - allowPhishingRequest

```


# Configure Tenant Domains and Routing
Source: https://docs.xorlab.com/latest/multi-tenancy-domain-and-routing

Configure tenant domains and SMTP routing for each supported multi-tenant topology.

The configuration is different depending on the topology. Choose the one below that fits your setup best.

## Deployment Topologies

The xorlab Security Platform supports several deployment options. If you're unsure which to choose, we recommend starting with the `Default Chain`.

* [Default Chain](#default-chain-topology): xorlab is located between your gateway and the internal mailbox server like Exchange.
* [Microsoft 365](#m365-topology): xorlab is integrated directly with M365 via connectors.
* [Star](#star-topology): A central gateway integrates xorlab in a Star layout.
* [Front MTA](#front-mta-topology): xorlab is the gateway (front MTA) and receives emails directly from the internet.
* [Full Chain](#full-chain-topology): Same as Default Chain, but inter-tenant emails pass twice through xorlab.

### Default Chain Topology

#### Guarded Tenants

<Accordion title="Expand to read the instructions.">
  `name`: Define the name of the tenant. Also visible in the web interface.

  `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.

  `tenantSelector`: Reference the `headerName` and `headerValue` of a header that will be used to identify the tenant.
</Accordion>

```yaml /shared/guarded_tenants.yml theme={null}
# Config example for Default Chain Topology

## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant.
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"

### Begin Tenant Config
tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    domains:
      - tenantB.com
      - tenant-B.net
```

#### Transport Map

<Accordion title="Expand to read the instructions.">
  The transport map is used to ensure that incoming emails are delivered to the appropriate next-hop destination (such as the front MTA) based on the recipient’s domain.

  * Define a rule for each guarded domain, specifying the correct next-hop destination.
  * Use the `smtp` command to specify the SMTP endpoint (e.g., the front MTA).
  * The last line should be a default route to handle outgoing email traffic.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/transport theme={null}
# Route incoming emails to the SMTP endpoints of each tenant domains
tenantA.ch      smtp:<inbound-next-hop>
tenantA.com     smtp:<inbound-next-hop>
tenantB.com     smtp:<inbound-next-hop>
tenantB.net     smtp:<inbound-next-hop>

# Define a default route for all outgoing emails
*               smtp:<outbound-next-hop>
```

#### Client Access

<Accordion title="Expand to read the instructions.">
  Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

  * Specify the IP address of the SMTP client, typically the Front MTA or Exchange Server, responsible for routing emails to xorlab.
  * Use the `permit` command to allow these connections to access xorlab and forward emails.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access theme={null}
## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each front MTA that receives emails and forward them to xorlab
<ip-address1>   permit
<ip-address2>   permit
```

#### Client Access Tenant

<Accordion title="Expand to read the instructions.">
  This file defines which headers xorlab should add to incoming and outgoing emails.

  * Structure: `<CIDRblock>    PREPEND  <headerName>: <headerValue>`
  * The `<CIDRblock>` specifies the IP range of the SMTP client responsible for routing emails to xorlab
  * Add `/32` to restrict to a single IP address.
  * The `<headerName>` and `<headerValue>` refer to the `tenantSelector` or the `tenantSelectors`.
  * The file should always end with an `0.0.0.0/0` entry to prevent header spoofing.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access_tenant theme={null}
# Allow-list specific SMTP clients for Multi-tenant deployments

198.51.100.1/32       PREPEND x-xor-trusted-client: trusted
192.0.2.1/32          PREPEND x-xor-trusted-client: trusted
203.0.113.1/32        PREPEND x-xor-trusted-client: trusted

# Always include a 0.0.0.0/0 entry in the end of this file to sanitize the headerValue
0.0.0.0/0             PREPEND x-xor-trusted-client: unknown
```

When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute.

### M365 Topology

#### Guarded Tenants

<Accordion title="Expand to read the instructions.">
  `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.

  `tenantSelectors`: Refer to the x-originatororg header of each accepted domain in your Microsoft Exchange environment.
</Accordion>

<Accordion title="Recommendation: List every 'Accepted Domain' as tenantSelector.">
  * Go to admin.cloud.microsoft/exchange#/accepteddomains
  * For **each domain listed**, define a separate `selector` in `guarded_tenants.yml`
  * Use the following format for each selector:
    * HeaderName: `"x-originatororg"`
    * Header value: The domain listed in the "Accepted Domain" column, between double quotation marks.
</Accordion>

```yaml /shared/guarded_tenants.yml theme={null}
tenants:
  - name: tenantA
    domains:
     - tenantA.com
     - tenantA.ch
    tenantSelectors:
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenanta.com"
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenantaaa.onmicrosoft.com"

  - name: tenantB
    domains:
      - tenantB.com
      - tenantB.net
    tenantSelectors:
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenantb.com"
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenantbbb.onmicrosoft.com"

```

#### Header Checks

<Accordion title="Expand to read the instructions.">
  This config file contains the routing rules of your mail flow. It refers to the headers specified for each tenant in the previous step.

  * `x-originatororg` should correspond to the `headerName` of the `tenantSelectors` defined in `guarded_tenants`.
  * `tenantA.com` and `tenantB.com` should correspond to the `headerValue` of the `tenantSelectors` defined in `guarded_tenants`.
  * `tenant` `a/b` `-com.mail.protection.outlook.com` should correspond to the SMTP endpoint (MX server) of the `headerValue` of the `tenantSelectors` defined in `guarded_tenants`.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/header_checks_core theme={null}
# Header-based routing
# Define mail routes as specified in the shared/guarded_tenants.yml 

/^x-originatororg: tenantA.com/                 FILTER smtp:tenanta-com.mail.protection.outlook.com
/^x-originatororg: tenantaaa.onmicrosoft.com/   FILTER smtp:tenantaaa.mail.protection.outlook.com
/^x-originatororg: tenantB.com/                 FILTER smtp:tenantb-com.mail.protection.outlook.com
/^x-originatororg: tenantbbb.onmicrosoft.com    FILTER smtp:tenantbbb-com.mail.protection.outlook.com
```

When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute.

### Star Topology

#### Guarded Tenants

<Accordion title="Expand to read the instructions.">
  `name`: Define the name of the tenant. Also visible in the web interface.

  `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.

  `tenantSelector`: Identifies the header that will be set when the email is coming from the trusted infrastructure.
</Accordion>

```yaml /shared/guarded_tenants.yml theme={null}
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"

tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    domains:
      - tenantB.com
      - tenantB.net
```

#### Transport Rules

<Accordion title="Expand to read the instructions.">
  The transport rules for a multi-tenancy star integration only require one route that redirects all traffic to the central email gateway.

  * The `*` wildcard matches all traffic.
  * `<email-next-hop>` should contain the domain of the central email gateway.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/transport theme={null}
# Make sure a default route is defined.
*               smtp:<email-next-hop>
```

#### Client Access

<Accordion title="Expand to read the instructions.">
  Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

  * Specify the IP address of central gateway that will send emails to xorlab.
  * Use the `permit` command to allow these connections to access xorlab and forward emails.
</Accordion>

```yaml activeguard/mta/startup_cfg/postfix_custom/client_access theme={null}
## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each front MTA that will send emails to xorlab
<ip-address1>   permit
<ip-address2>   permit
```

When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute.

### Front MTA Topology

#### Guarded Tenants

<Accordion title="Expand to read the instructions.">
  `name`: Define the name of the tenant. Also visible in the web interface.

  `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.

  `tenantSelector`: Reference the `headerName` and `headerValue` of a header that will be added by xorlab.

  > The headers referenced in `tenantSelector` need to match the entries in the `client_access_tenant` configuration.
</Accordion>

```yaml /shared/guarded_tenants.yml theme={null}
## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant.
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"


tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    domains:
      - tenantB.com
      - tenant-B.net

```

#### Client Access

<Accordion title="Expand to read the instructions.">
  Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

  * Specify the IP address of the allowed SMTP client, typically the Exchange server.
  * Use the `permit` command to allow these connections to access xorlab and forward emails.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access theme={null}
## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each server that will send emails to xorlab
<ip-address1>   permit
<ip-address2>   permit
```

#### Client Access Tenant

<Accordion title="Expand to read the instructions.">
  This file defines which headers xorlab should add to incoming and outgoing emails.

  * Structure: `<CIDRblock>    PREPEND  <headerName>: <headerValue>`
  * The `<CIDRblock>` specifies the IP range of each tenant's mail server
  * Add `/32` to restrict to a single IP address.
  * The `<headerName>` and `<headerValue>` refer to the `tenantSelector` or the `tenantSelectors`.
  * The file should always end with an `0.0.0.0/0` entry to prevent header spoofing.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access_tenant theme={null}
# Allow-list specific SMTP clients for Multi-tenant deployments

198.51.100.1/32       PREPEND x-xor-trusted-client: trusted
192.0.2.1/32          PREPEND x-xor-trusted-client: trusted
203.0.113.1/32        PREPEND x-xor-trusted-client: trusted

# Always include a 0.0.0.0/0 entry in the end of this file to sanitize the headerValue
0.0.0.0/0             PREPEND x-xor-trusted-client: unknown
```

#### Transport Map

<Accordion title="Expand to read the instructions.">
  The transport map is used to ensure that incoming emails are delivered to the appropriate next-hop destination (such as the front MTA) based on the recipient’s domain.

  * Define a rule for each guarded domain, specifying the correct next-hop destination.
  * Use the `smtp` command to specify the SMTP endpoint (e.g., the front MTA).
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/transport theme={null}
# Route incoming emails to the SMTP endpoints of each tenant domains
tenantA.ch      smtp:<inbound-next-hop>
tenantA.com     smtp:<inbound-next-hop>
tenantB.com     smtp:<inbound-next-hop>
tenantB.net     smtp:<inbound-next-hop>
```

When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute.

### Full Chain Topology

In the Full Chain Topology xorlab sits between a front MTA and the Exchange server. The difference to the default chain is that inter-tenant emails are routed to the front MTA and back.
Important: the front MTA needs to strip away all x-xor-trusted-client headers from all emails to ensure proper routing.

#### Guarded Tenants

<Accordion title="Expand to read the instructions.">
  `domains`: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.

  `tenantSelector`: If needed, reference a unique trusted `headerName` and `headerValue` for specific tenants.

  `interTenantMessageSplitting`: Controls whether xorlab splits emails sent between tenants into separate incoming and outgoing messages. By default, this attribute is set to `true` but for the `Full Chain Topology` you are required to set it to `false`.

  `configSets` - `tenantSelector`: Reference the `headerName` and `headerValue` of a header that will be added by xorlab.

  > The headers referenced in `tenantSelector` and `tenantSelectors` need to match the entries in the `client_access_tenant` configuration.
</Accordion>

```yaml /shared/guarded_tenants.yml theme={null}
## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant
configSets:
  default:
    # This is required when inter-tenant emails are passing through xorlab twice
    interTenantMessageSplitting: false
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"

tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.de

  - name: tenantB
    domains:
      - tenantB.com
      - tenantB.net
        
```

#### Header Checks

<Accordion title="Expand to read the instructions.">
  This config file defines how messages are routed based on the headers assigned in guarded\_tenants.yml.

  * Structure: `/^<headerName>:<headerValue>/  FILTER smtp:[<SMTP endpoint>]`
  * The `<SMTP endpoint>` should include the domain of either the frontMta or the guarded domain's mail server.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/header_checks_core theme={null}
# Header-based routing

/^x-xor-trusted-client: unknown/   FILTER smtp:<inbound-next-hop>
/^x-xor-trusted-client: trusted/   FILTER smtp:<outbound-next-hop>

```

#### Client Access

<Accordion title="Expand to read the instructions.">
  Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

  * Specify the IP address of the SMTP client, typically the Front MTA or Exchange Server, responsible for routing emails to xorlab.
  * Use the `permit` command to allow these connections to access xorlab and forward emails.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access theme={null}
## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each front MTA that receives emails and forward them to xorlab
<ip-address1>   permit
<ip-address2>   permit
```

#### Client Access Tenant

<Accordion title="Expand to read the instructions.">
  This file defines which headers xorlab should add to incoming and outgoing emails.

  * Structure: `<CIDRblock>    PREPEND  <headerName>: <headerValue>`
  * The `<CIDRblock>` specifies the IP range of the **Exchange Server**.
  * Add `/32` to restrict to a single IP address.
  * The `<headerName>` and `<headerValue>` refer to the `tenantSelector` or the `tenantSelectors`.
  * The file should always end with an `0.0.0.0/0` entry to prevent header spoofing.
</Accordion>

```yaml /activeguard/mta/startup_cfg/postfix_custom/client_access_tenant theme={null}
# Set the Exchange servers as trusted. Do not add the front MTA as trusted.
198.51.100.1/32       PREPEND x-xor-trusted-client: trusted
192.0.2.1/32          PREPEND x-xor-trusted-client: trusted

# Always include a 0.0.0.0/0 entry in the end of this file to prevent spoofing of the headerValue
0.0.0.0/0             PREPEND x-xor-trusted-client: unknown
```

When you finish editing the files above, click **Publish**. The new configuration becomes active within about one minute.

## How to define tenant selectors

Tenant selectors are used to assign emails to the correct tenant by evaluating specific mail headers.

There are two configuration options:

* `tenantSelector`: Defines a single set of headers that must all match to assign the message to a tenant (AND logic).

* `tenantSelectors`: One property that enables you to define more then one `selector`. A `selector` can reference one or more header sets. If multiple header sets are referenced, all need to match (AND-logic). The message matches a tenant if at least one `Selector` matches (OR logic).

Both options can be used for a specific tenant, as well as default within `configSets`.

<Warning>
  **Avoid External Header Manipulation**

  Only use sanitized and trusted mail headers for tenant identification. Never rely on headers that could be set or modified by external senders.
</Warning>

```yaml /shared/guarded_tenants.yml theme={null}
## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant.
## In this example, it applies to tenant C and D.
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trustedMailRoute"

tenants:
  - name: tenantA
    domains:
      - tenantA.com
      # Assigned to tenantA only if both headers match (AND logic)
    tenantSelector:
      - headerName:  "x-xor-trusted-client"
        headerValue: "specialRoute"
      - headerName:  "another-trusted-header"
        headerValue: "i-know-this-is-tenantA"

  - name: tenantB
    domains:
      - tenantB.com
    
    # Assigned to tenantB if either of these selectors match (OR logic between selectors)
    tenantSelectors:
      - selector:
        - headerName:  "x-xor-trusted-client"
          headerValue: "specialRoute2"
      - selector:
        - headerName:  "x-xor-trusted-client"
          headerValue: "specialRoute3_part1"
        - headerName:  "another-trusted-header"
          headerValue: "specialRoute3_part2"

  - name: tenantC
    domains:
      - tenantC.com

  - name: tenantD
    domains:
      - tenantD.com

```

After updating `shared/guarded_tenants.yml`, click **Publish**. The new configuration becomes active within about one minute.

### Explanation of tenant selection logic

When processing an email, the system determines which Tenant it belongs to based on the following rules.

**Step 1: Single Match:** If exactly one Tenant Selector matches the email, the email is assigned to that Tenant.

**Step 2: No Match:** If no Tenant Selector matches the email, choose the Tenant based on the recipient addresses. If no Tenant can be identified, assign the email to the special `UNKNOWN` Tenant.

**Step 3: Multiple Matches:** If multiple Tenant Selectors match, the selection is resolved using the logic below in the specified order.

1. Assign Tenant based on sender address.

   1. Prefer a match on the sender’s envelope-from address.
   2. If no match, check the header-from address.

2. Assign Tenant based on recipient addresses. Choose only from the matched Tenant Selectors.

3. If no Tenant can be identified, assign the email to the special `UNKNOWN` Tenant.

<Note>
  **Recipient address matching**

  For step 2 and 3: If the Tenant is chosen based on the recipients, and the recipients belong to different Tenants, the email is split for each Tenant. Each split email is assigned a separate GGRID and will be shown as separate email in the web interface.
</Note>

After the tenant is selected, the email is processed. Because the email can have multiple different recipients, even from different tenants, xorlab applies the following logic when delivering emails:

* For all recipients of the email that do not match any tenants (outgoing email) or match the tenant of the email itself (internal or incoming email), deliver the email.
* For all recipients of the email that match a different tenant than the one of the email itself (inter-tenant email):

  * If `interTenantMessageSplitting` is active, re-process the email again with a separate `GGRID` and assigned to the recipient tenant. No email delivery at this point.
  * Else deliver the email. We expect the email to pass again through xorlab.


# Customize Tenant Notifications
Source: https://docs.xorlab.com/latest/multi-tenancy-email-templates

Customize end-user email notifications separately for each tenant.

To get more general information about email notifications, have a look at [Customize Templates](/latest/email-template-modifications).

To customize the notification for a tenant:

1. Open `shared/guarded_tenants.yml` in the Expert Editor

2. Add `emailTemplateStyle` for each tenant that should have custom notifications. The same value can be re-used for multiple tenants.

   ```yaml guarded_tenants.yml {8} theme={null}
   tenants:
     - name: xorlab
       domains:
         - xorlab.com
     
     # Tenant with different style
     - name: example
       emailTemplateStyle: exampleDarkModeNoLogo
       domains:
         - example.com
   ```

3. Use the value of `emailTemplateStyle` to customize the notification for that tenant:

   * [Customize text](#customize-text)
   * [Customize style and logo](#customize-style-and-logo)
   * [Customize footer](#customize-footer)

## Customize text

To customize the notification text for a tenant:

1. Copy the content of `shared/email_templates/locale/default.yml` to the clipboard.
2. Use the context menu for the `locale` folder to create a new file inside of it.
3. Name it `<emailTemplateStyle>_<language>_<COUNTRY>.yml`, where `<language>` and `<COUNTRY>` follow the IETF BCP 47 standard, as used by [Java Locale](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Locale.html).

* `_<COUNTRY>` is optional and can be omitted.
* More specific localization files take precedence.

4. Paste the content into the file.
5. For each template in the file, replace the content with a tenant specific localized text.

## Customize style and logo

To customize the look of email notifications for a tenant:

1. Copy the content of `shared/email_templates/style/default.yml` to the clipboard.
2. Use the context menu for the `style` folder to create a new file inside of it.
3. Name it `<emailTemplateStyle>.yml`.
4. Paste the content into the file.
5. Change the values according to the tenant style. Here you can [set the logo](/latest/email-template-modifications#change-the-logo) for the tenant.

## Customize footer

To customize the company information shown in the footer of the email notifications for a tenant:

1. Copy the content of `shared/email_templates/info/default.yml` to the clipboard.
2. Use the context menu for the `info` folder to create a new file inside of it.
3. Name it `<emailTemplateStyle>.yml`.
4. Paste the content into the file.
5. Change the values according to the tenant company information.

After completing any of these template changes, click **Publish**. The template configuration becomes active within about one minute.


# Add a New Tenant
Source: https://docs.xorlab.com/latest/multi-tenancy-new-tenant

Step-by-step onboarding of a new tenant, including the one-time prerequisites for the first tenant.

<Warning>
  **Prerequisites (only for first tenant)**

  * Make sure your xorlab is in the correct mode: Inline vs Monitoring, follow [Choose between Inline and Monitoring mode](/latest/before-begin-integration#choose-between-inline-and-monitoring-mode).
</Warning>

## Configure guarded domains and routing

The first step is to add all domains of the tenant and configure their routing (where should their emails be sent to).

1. Follow the guide below that matches the topology where your new tenant will be integrated. On top are the two most common ones.
   | Topology | Description |
   | :- | :- |
   | [Default](/latest/multi-tenancy-domain-and-routing#default-chain-topology) | xorlab is located between your gateway and your internal Exchange server. |
   | [M365](/latest/multi-tenancy-domain-and-routing#m365-topology) | xorlab integrates directly with M365. |
   | [Front MTA](/latest/multi-tenancy-domain-and-routing#front-mta-topology) | xorlab is your gateway/front MTA. |
   | [Star](/latest/multi-tenancy-domain-and-routing#star-topology) | Your gateway integrates xorlab in a Star layout. |
   | [Full Chain](/latest/multi-tenancy-domain-and-routing#full-chain-topology) (Rare) | Same as Default, but inter-tenant emails pass through xorlab twice. |
2. Optional: If you need a special mode (like *toothless* or Monitoring) specifically for that tenant, contact [support@xorlab.com](mailto:support@xorlab.com).

## Activate mail flow

The next step is outside of xorlab and involves activating the mail flow. Choose the matching guide, depending on:

* **Topology**: M365 vs. all others
* **Mode**: Inline vs Monitoring

<Tabs>
  <Tab title="M365">
    <CardGroup>
      <Card title="Inline" icon="shield" href="/latest/m365-inline-mode">
        Emails pass from M365 through xorlab and then back to M365.
      </Card>

      <Card title="Monitoring" icon="envelope-open-text" href="/latest/m365-monitoring-mode">
        xorlab receives only a copy of every email from M365, and discards it after processing.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Others">
    The actual activation of the mail flow depends on the system you are using. Here we provide instructions for a few common ones.

    <CardGroup>
      <Card title="Inline" icon="shield">
        To configure on-premises Exchange for inline mode with xorlab, follow:

        * [On-premises Exchange](/latest/on-prem-exchange-inline)
      </Card>

      <Card title="Monitoring" icon="envelope-open-text">
        For monitoring mode, we have available guides for:

        * [On-premises Exchange](/latest/on-prem-exchange-monitoring-mode)
        * [Cisco ESA](/latest/on-prem-esa-monitoring-mode)
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

Now xorlab should be receiving emails for that tenant.

## Reduce reputation complexity for small tenants

For tenants below 50 seats, we recommend to reduce the `complexityFactor` in the `guarded_tenants.yml` file. This helps xorlab to learn faster from processed emails. Otherwise, learning can take quite a while to stabilize for small tenants, since fewer emails are available.

We recommend the following values:

| Number of seats | Value |
| :- | :- |
| Above 50 | Keep the default (100) |
| Between 25 and 50 | 50 |
| Below 25 | 25 |

```yaml /shared/guarded_tenants.yml highlight={5-6} theme={null}
tenants:
  - name: tenantA
    domains:
      - tenantA.com
    reputation:
      complexityFactor: 50
```

After updating `shared/guarded_tenants.yml`, click **Publish**. The new configuration becomes active within about one minute.

## Configure detection for the tenant

Detection is configured per tenant, so a new tenant starts without the manual inputs that xorlab needs for optimal protection.

1. Open the **Admin** view in the upper right and select the new tenant in the dropdown on top.
2. [Configure the built-in lists](/latest/detection-overview#configure-built-in-lists) for that tenant, in particular the VIP names and high value targets.
3. [Review the default actions](/latest/detection-overview#review-default-actions) for that tenant.

Both steps use the same screens as in a single-tenant deployment and apply only to the tenant selected in the dropdown.

## Optional: Enable Tenant Login

You can give the tenant access to xorlab:

* **End-user** access to the Self-Service Quarantine (SSQ)
* **Analyst** access to the analyst portal, to manage various tasks like releasing emails from quarantine or adding senders to the blacklist

Follow the instructions here: [Enable Tenant Login](/latest/multi-tenancy-authentication).

## Optional: Enable SSQ

You can enable the SSQ for the tenant, such that their end-users can release their own emails from the quarantine.

You can find the full instructions for setting up and customizing the SSQ here: [Set Up the SSQ](/latest/ssq-setup).

For convenience, we summarize here the mandatory steps to enable SSQ for a tenant:

1. Complete the previous chapter, to [Enable Tenant Login](/latest/multi-tenancy-authentication) such that they can login to the SSQ.
2. Enable notifications for that tenant in `guarded_tenants.yml`:
   ```yaml shared/guarded_tenants.yml highlight={4-6} theme={null}
   tenants:
     - name: xorlab
       quarantine:
         notifications:
           enabled: true
           frequency: DAILY
           ## - NEVER: Sending of a quarantine notification is disabled for the user.
           ## - IMMEDIATELY: Sending of a quarantine notification happens immediately if a message for the user is quarantined.
           ## - DAILY: Sending the quarantine notification every day at the time specified in the dailyCron option.
           ## - WEEKLY: Sending the quarantine notification once a week at the time specified in the weeklyCron option.
   ```
3. Click **Publish**. The notification settings become active within about one minute.
4. This is not strictly mandatory, but recommended: Customize the quarantine notifications for that tenant to for example add their logo: [Customize Tenant Notifications](/latest/multi-tenancy-email-templates).

## Optional: Integrate Abuse Mailbox

You can enable the Abuse Mailbox for the tenant, such that their reported emails are managed in xorlab.

1. Follow the integration guide below that matches the tenant setup. You can ignore their *Prerequisites* as they are already covered by this page.

   <CardGroup>
     <Card title="M365" icon="microsoft" href="/latest/m365-reporting-integration">
       Use the built-in M365 reporting button to send emails to xorlab.
     </Card>

     <Card title="On-premises" icon="server" href="/latest/on-prem-reporting-integration">
       Use a custom reporting button integrated via on-premises Exchange.
     </Card>
   </CardGroup>
2. Follow [Assign Reported Emails to Tenants](/latest/multi-tenancy-reported-emails) to make sure xorlab assigns the reported emails to the correct tenant.


# Multi-Tenancy Overview
Source: https://docs.xorlab.com/latest/multi-tenancy-overview

Protect and manage multiple organizations from a single xorlab instance, with links to each configuration area.

To onboard a new tenant to xorlab, follow this guide:

<Card title="Add a Tenant" icon="rocket-launch" href="/latest/multi-tenancy-new-tenant" />

And here you can find an overview over the most important guides for multi-tenancy:

| Step | Description |
| :- | :- |
| [Add a Tenant](/latest/multi-tenancy-new-tenant) | Step-by-step guide for adding a new tenant to xorlab. |
| [Configure Tenant Domains and Routing](/latest/multi-tenancy-domain-and-routing) | Configure the guarded domains of the tenant and their routing. |
| [Enable Tenant Login](/latest/multi-tenancy-authentication) | Give tenants access to xorlab for the SSQ and for analyst tasks. |
| [Customize Tenant Notifications](/latest/multi-tenancy-email-templates) | Customize notifications per tenant. For example, change the logo in quarantine notifications. |
| [Assign Reported Emails to Tenants](/latest/multi-tenancy-reported-emails) | Make sure reported emails end up in the tenant they belong to. |
| [Using Tenant Config Templates](/latest/multi-tenancy-configsets) | Share one configuration across many tenants instead of repeating it on each of them. |
| [Tenant Rules and Properties](/latest/multi-tenancy-rules) | How to change rules and properties per tenant for more advanced topics. |

## Multi-Tenancy on the feature pages

The guides above cover multi-tenancy from the tenant's point of view. If you are instead configuring one specific feature and want to know how it behaves per tenant, each feature page carries its own **Multi-Tenancy** section:

| Feature | Page |
| :- | :- |
| Integration and routing | [Integration Overview](/latest/setup-integration-overview), [Advanced SMTP Configurations](/latest/smtp-configuration), [Trusted MTAs In-Depth](/latest/trusted-mtas) |
| User authentication | [Authentication Overview](/latest/authentication-overview), [Enable SAML Login](/latest/authentication-saml), [Enable LDAP Login](/latest/authentication-ldap), [Auto-Login](/latest/authentication-auto-login-link), [Password File](/latest/authentication-with-a-password-file), [List of Built-in Roles](/latest/built-in-user-roles) |
| Detection | [Detection Overview](/latest/detection-overview), [Rule Profiles](/latest/rule-profiles), [Rule Parameters](/latest/rule-parameters), [Adding a Custom Rule](/latest/adding-custom-rule) |
| Self-Service Quarantine | [SSQ Overview](/latest/ssq-overview), [Set Up the SSQ](/latest/ssq-setup) |
| Email notifications | [Notifications Overview](/latest/email-template-overview), [Customize Templates](/latest/email-template-modifications) |
| Abuse Mailbox | [Integrate M365 Abuse Mailbox](/latest/m365-reporting-integration), [Integrate On-prem Abuse Mailbox](/latest/on-prem-reporting-integration) |
| Data retention | [Data Retention Overview](/latest/data-retention-overview) |


# Assign Reported Emails to Tenants
Source: https://docs.xorlab.com/latest/multi-tenancy-reported-emails

Assign reported emails to the correct tenant using the x-ag-tenant header on the carrier email.

1. Add a `x-ag-tenant` email header that contains the tenant name to the outer email of a reported email.

2. xorlab will parse the header and assign the reported email to the correct tenant.

3. Optional: Follow [Tenant-Specific Notifications](/latest/multi-tenancy-email-templates) to customize notifications per tenant.

<Note>
  **Custom email header**

  To read the tenant from a different header, for example, `my-custom-tenant-header` instead of `x-ag-tenant`, you need to edit `activeguard/core/active_guard.yml` the following way:

  ```yaml active_guard.yml theme={null}
  emailReporting:
      ## Header name for tenant identification (default = x-ag-tenant)
      tenantIdentifyingMailHeaderName: my-custom-tenant-header
  ```

  Afterward, click **Publish**, then restart all MTAs. The `emailReporting` setting in `active_guard.yml` requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

  The tenant value must consist of letters (a-z, A-Z), numbers (0-9), underscores (\_), and hyphens (-). Note: periods (.) are not allowed.
</Note>


# Manage Tenant Rules
Source: https://docs.xorlab.com/latest/multi-tenancy-rules

Create rules and parameters per tenant, and override global parameters for individual tenants.

In `/activeguard/core/rule_sets/`, you have two kinds of folders. Everything in `90_local` acts as the default configuration for all tenants. In the `_tenant` folders, you can override the configuration by adding new files or overwrite those from `90_local`.

This structure is automatically used when you create a campaign or add list entries for a single tenant.

```yaml Folder structure of /activeguard/core theme={null}
/
├─ activeguard/
│  ├─ core/
│  │  ├─ active_guard.yml
│  │  ├─ rule_sets/
│  │  │  ├─ 90_local/
│  │  │  ├─ _tenant1/
│  │  │  ├─ _tenant2/
│  │  │  ├─ ...
├─ ...
```

## Tenant-Specific Rules

If you want to create a rule that only applies to a single tenant, place the rule file in: `/activeguard/core/rule_sets/_tenantX/rules/custom/`.

## Tenant-Specific Parameters

You can do the same for `.properties` files. To set different rule parameters for individual tenants, set up `tenant.properties` like this:

* In `/shared/guarded_tenants.yml`, add `tenant.properties` to the rule profiles:
  ```yaml guarded_tenants.yml theme={null}
  tenants:
    - name: example
      ruleProfiles:
        - tenant.properties
  ```
* Create `/activeguard/core/rule_sets/90_local/params/tenant.properties` and add a placeholder comment:
  ```yaml /activeguard/core/rule_sets/90_local/params/tenant.properties theme={null}
  # This is a placeholder for the tenant-specific properties file.
  # Create and edit the tenant-specific file at:
  # /activeguard/core/rule_sets/_tenantX/params/tenant.properties
  ```
* Add your configurations in `/activeguard/core/rule_sets/_tenantX/params/tenant.properties` for the individual tenants.
* For example, you can add the contents of `profile_no_subject_rewrite_no_quarantine.properties` to `tenant.properties` to enable a tenant-specific “toothless mode.”


# Network Guide
Source: https://docs.xorlab.com/latest/network-guide

The network connections required between xorlab components and external services, for firewall and proxy configuration.

## System architecture

xorlab consists of three different components:

* **xorlab XCC**: One VM that offers a complete view of all processed emails and stores all persistent data.
* **xorlab MTA**: Email processing node. Depending on the expected load, you can operate multiple redundant MTA VMs to distribute email traffic.
* **xorlab Sandbox (DANA)**: Analyzes email attachments in an isolated environment. By default it is integrated as cloud service. You can opt to run it locally, but it requires direct hardware access and cannot be virtualized.

<img alt="Network schema" />

This diagram shows the standard locations of the components. The MTAs and Sandbox appliances can be placed in the DMZ and the XCC in the internal network.

## Required connections

**xorlab VMs to the Internet**

| Source | Destination | Protocol | Port | Description |
| :- | :- | :- | :- | :- |
| MTA | Internet | HTTPS | 443/TCP | Destinations: [xorlab services](#xorlab-services-destinations) |
| XCC | Internet | HTTPS | 443/TCP | Destinations: [xorlab services](#xorlab-services-destinations). Optional: [VirusTotal](#optional-virustotal), [Case Isolation](#optional-case-isolation-via-m365-graph-api) |

**Internal network to xorlab VMs**

| Source | Destination | Protocol | Port | Description |
| :- | :- | :- | :- | :- |
| Internal network | MTA | SMTP | 25/TCP | Receive outgoing emails |
| Internal network | MTA | HTTPS | 8443/TCP | MTA GUI |
| Internal network | MTA | SSH | 22/TCP | SSH access |
| Internal network | XCC | HTTPS | 443/TCP | XCC web interface |
| Internal network | XCC | SSH | 22/TCP | SSH access |

**xorlab VMs to internal network**

| Source | Destination | Protocol | Port | Description |
| :- | :- | :- | :- | :- |
| MTA | Internal network | SYSLOG | 514/UDP | Logging (Security logs, Audit logs, etc.) to SIEM/SOAR |
| MTA | Internal network | SMTP | 25/TCP | Send incoming emails |
| MTA | Internal network | DNS | 53/UDP | Connect to internal DNS server - **external domain resolution required** |
| MTA | Internal network | NTP | 123/UDP | Time synchronization via NTP |
| XCC | Internal network | DNS | 53/UDP | Connect to internal DNS server |
| XCC | Internal network | SYSLOG | 514/UDP | Logging (Security logs, Audit logs, etc.) to SIEM/SOAR |
| XCC | Internal network | NTP | 123/UDP | Time synchronization via NTP |

**xorlab VMs to xorlab VMs**

| Source | Destination | Protocol | Port | Description |
| :- | :- | :- | :- | :- |
| MTA | XCC | HTTPS | 9080/TCP | Publish analysis results and retrieve configuration |
| MTA | XCC | Custom | 6379/TCP | Stores hashed text fragments to identify and group similar emails |
| MTA | XCC | HTTPS | 3100/TCP | Sending logs via Promtail for centralized monitoring |
| XCC | MTA | HTTPS | 9090/TCP | Collect Prometheus monitoring data from MTAs |

**ONLY with an on-premises Sandbox**

<Note>
  In the table below, the Sandbox host is listed as **DANA** — that is the hostname of the Sandbox appliance in on-premises deployments.
</Note>

| Source | Destination | Protocol | Port | Description |
| :- | :- | :- | :- | :- |
| DANA | Internet | HTTPS | 443/TCP | Destinations: [xorlab services](#xorlab-services-destinations) |
| MTA | DANA | HTTPS | 8444/TCP | Sandbox analysis |
| XCC | DANA | HTTP | 9090/TCP | Collect Prometheus monitoring data from DANA |
| DANA | Internal network | NTP | 123/UDP | Time synchronization via NTP |
| DANA | Internal network | DNS | 53/UDP | Connect to internal DNS server |
| DANA | Internal network | SYSLOG | 514/UDP | Logging (Security logs, Audit logs, etc.) to SIEM/SOAR |
| Internal network | DANA | HTTPS | 8444/TCP | Technical management user interface for DANA |
| Internal network | DANA | SSH | 22/TCP | SSH access |

## xorlab services destinations

Below we list the external xorlab destinations that you need to allow for HTTPS. We provide both domains and IPs here:

* Allow based on **domains** when using a **proxy** for outgoing HTTPS requests
* Allow based on **IPs** when using only a **firewall**

It is enough to just allow the following two wildcard domains:

| Domain | Description |
| :- | :- |
| `*.activeguard.io` | Used for xorlab services |
| `*.xorlab.com` | Used for product updates |

If you want to be more specific, you can allowlist the individual sub-domains instead.

<Info>
  The production IP addresses of these endpoints, for environments where outbound rules cannot be
  expressed by domain, are documented in
  [Deployment Defaults → Production endpoint addresses](/latest/deployment-defaults#production-endpoint-addresses).
  Access to that page is restricted.
</Info>

## **(Optional)** Case Isolation via M365 Graph API

If you have a hybrid setup where your mailboxes are already in M365, you can enable [Case Isolation](/latest/m365-case-isolation) to allow removing emails from mailboxes.

For this, the **XCC** must have access (proxy supported) to the following destinations:

* graph.microsoft.com
* login.microsoftonline.com

## **(Optional)** VirusTotal

xorlab supports VirusTotal integration to get additional threat intelligence for analysis purposes. If configured, **XCC** will query VirusTotal for every email which is opened in the web interface in the **Detail View**.

Note that the VirusTotal queries are done only on-demand whenever an analyst opens an email in the Detail View. There are no VirusTotal queries done for the automated email classification.

In order to issue VirusTotal queries, the **XCC** must have access (proxy supported) to the following destination:

* **virustotal**: virustotal.com on port 443/TCP


# Operation Reference
Source: https://docs.xorlab.com/latest/operation-reference

Component architecture, CLI commands like restart and reboot procedures, the shell aliases on the VMs, and where the log files live.

## xorlab Security Platform architecture

Every xorlab Security Platform component (Sandbox, MTA, and XCC) comprises a set of Docker containers which have different responsibilities. MTA and XCC components are delivered to on-prem customers as separate VMs. xorlab Cloud (xCloud) and the xorlab Sandbox are components in the SaaS infrastructure that are needed by our platform. In rare cases, the Sandbox is run on-prem.

The following picture shows the most important containers, their dependencies, and a typical mail flow:

<img alt="xorlab mail flow" />

*Mail flow, containers and their dependencies in xorlab Security Platform (not exhaustive)*

Note that this is not an exhaustive list of dependencies. For all inter-component dependencies, full network traffic information, and other details regarding data flow from/to xorlab and within the platform, please see [Network Guide](/latest/network-guide).

The mail flow can be described in the following steps:

1. An email arrives at the MTA (xorlab Mail Transfer Agent) component using SMTP and is received by the `mta` container (basically, a postfix mail server).
2. The `mta` container forwards the email—still using SMTP—to the `core` container. If this transmission fails—e.g., because `core` is not ready to process the email—the email will be deferred by core, and you should see the following alert: `Emails Older Than 100 Seconds Stuck In the Deferred Queue`. `core` then performs a static analysis of the message. Depending on the settings and the message itself, the message attachments can additionally be scanned by sending them to the xorlab Sandbox (DANA). When the Sandbox scan is done, the email will be shown in **Messages → Pending** in the web interface.
3. The analysis results are published to the XCC component, where the results are persisted in a database and accessible through the XCC web interface. If the result publishing fails, you will receive the following alert: `Core System Test Failed`, with the description containing the name of the failing test—here, `ResultPublishSystemTest`.
4. If the message is allowed to be delivered, the `core` container hands it over back to the `mta` container for sending to the recipient. As in step #2, errors will trigger the following alert: `Emails Older Than 100 Seconds Stuck In the Deferred Queue`.

Generally, all containers are grouped into stacks. You can find all containers with their respective stacks in the following picture. Based on the stack and container name, you can later derive the location of the container log files on the host, e.g., `xcc_backend`.

<img alt="xorlab docker containers" />

## Container description

### MTA

| Container | Description |
| :- | :- |
| `core` | Email processing engine. Parses the email, applies rules and policies, classifies the email, and decides if it is legitimate or not |
| `mta` | Responsible for email routing. Accepts and forwards emails. Sends the emails to `core` for processing before forwarding them |
| `rspamd` | Spam detection module used by `core` |
| `rproxy_mta` | Reverse proxy for the MTA |

### XCC

| Container | Description |
| :- | :- |
| `backend` | Heart of XCC. Provides the API for MTAs, maintains the configuration, computes the trust model, provides the web interface, etc. |
| `db` | Database for all email related data |
| `web` | Reverse proxy handling access to the `backend` API |
| `redis` | Fast, in-memory key-value pair data store |
| `elasticsearch` | Refines the data from `db` to support advanced data search and processing. Used internally to provide search in the web interface |
| `kibana` | Provides the dashboards accessible through the **Insights** menu |
| `auth` | Performs user authentication. Can integrate external systems through, for example, LDAP or SAML. Provides user and role information to the backend for access control |

### Sandbox (DANA)

| Container | Description |
| :- | :- |
| `analysisnode` | Responsible for the Sandbox. Receives files and scans them in internal VMs |
| `tika` | Text processing engine. Extracts text from various documents and supports OCR |
| `nginx` | Reverse proxy handling access to the `analysisnode` API |

### Shared monitoring containers

| Container | Description |
| :- | :- |
| `prometheus` | Monitoring system and time series database: stores all monitoring metrics and applies the alert rules to see if an alert must be triggered. Additionally, Prometheus on XCC can collect the monitoring metrics from other Prometheus instances on MTAs and DANAs for a centralized view of all metrics |
| `grafana` | Data analytics and monitoring |
| `node_exporter` | Gathers metrics from the host (node) |
| `cadvisor` | Gathers Docker metrics |
| `alertmanager` | Collects and sends alerts to users |
| `config` | Pulls config from the config providers (`xcloud` for global and `xcc_backend` for local configuration) |
| `loki` | Log aggregation system for storing and querying logs |
| `promtail` | Sends the contents of local logs to the `loki` service |

## Start and stop

Generic procedure to start and stop stacks on the xorlab Security Platform components is performed within the stack folder and looks like this.

```shell theme={null}
## Execute inside the stack folder, e.g., for xcc:
cd /etc/xorlab/xcc

## Stop stack
docker compose down

## Start stack (starts all not running containers)
docker compose up -d

## Stop single container
docker compose stop <container>
```

### MTA

Stop and start:

```shell theme={null}
cd /etc/xorlab/activeguard

# Stop activeguard stack; make sure to stop the core container first.
docker compose down

# Start it again
docker compose up -d
```

If you only want to restart the core container due to configuration changes, use the restart button in the MTA GUI.

### XCC

Stop and start:

```shell theme={null}
## The ordering is important

# Stop all stacks
cd /etc/xorlab/auth
docker compose down
cd /etc/xorlab/xcc
docker compose down
cd /etc/xorlab/elastic
docker compose down

# Start all stacks again
cd /etc/xorlab/elastic
docker compose up -d
cd /etc/xorlab/xcc
docker compose up -d
cd /etc/xorlab/auth
docker compose up -d
```

### Sandbox (DANA)

Stop and start:

```shell theme={null}
cd /etc/xorlab/dana

# Stop the Sandbox stack
docker compose down

# Start it again
docker compose up -d
```

Note that current dynamic scans will be lost and there will be no re-scan. To prevent this, make sure the queue is empty before stopping.

## Shell aliases

From release 11.0.5, each VM comes with shell aliases for the commands on this page. The upgrade installs them into `/etc/profile.d/xorlab-aliases-<component>.sh`, so they are available in every new SSH session after the upgrade. Only the aliases for the stacks present on the VM are installed. Run `alias` to list the ones on the VM you are logged in to.

### Generic Docker Compose aliases

These are available on every component and act on the stack folder you are in, e.g., `/etc/xorlab/xcc`.

| Alias | What it does |
| :- | :- |
| `dcup` | Starts the stack: `docker compose up -d` |
| `dcdown` | Stops the stack: `docker compose down` |
| `dcdownup` | Stops the stack and starts it again |
| `dcdownuplogf` | Stops the stack, starts it again, and follows its logs |
| `dclogf` | Follows the logs of the stack, starting from the latest line |

### MTA

| Alias | What it does |
| :- | :- |
| `cdactiveguard` | Changes to the stack folder `/etc/xorlab/activeguard` |
| `mta-up` | Starts the activeguard stack |
| `mta-up-logf` | Starts the activeguard stack and follows its logs. Leaves you in the stack folder |
| `mta-down-now` | Stops the activeguard stack immediately, without draining the queues. To shut down gracefully, use [`mta-down`](#graceful-mta-shutdown) instead |
| `mta-stop-core` | Stops the `core` container |
| `mta-start-core` | Starts the `core` container |
| `mta-restart-core` | Restarts the `core` container |
| `mta-restart-core-logf` | Restarts the `core` container and follows its log |
| `mta-core-health` | Prints the health status of the `core` container (release 11.0.7 and later) |
| `xorlab-mailq` | Lists all queued emails |
| `xorlab-postqueue-flush` | Flushes (resends) all queues |
| `xorlab-bash-core` | Opens a shell in the `core` container |
| `xorlab-bash-mta` | Opens a shell in the `mta` container |
| `tail-activeguard` | Follows `activeguard.log` |
| `tail-activeguarderr` | Follows `activeguard_err.log` |
| `tail-mailinfo` | Follows the `mta` container’s `mail.info` log |
| `tail-mailwarn` | Follows the `mta` container’s `mail.warn` log |
| `tail-mailerr` | Follows the `mta` container’s `mail.err` log |

### XCC

The `-all` aliases stop and start the auth, xcc, and elastic stacks in the order given in [Start and stop](#xcc).

| Alias | What it does |
| :- | :- |
| `cdxcc` | Changes to `/etc/xorlab/xcc` |
| `cdauth` | Changes to `/etc/xorlab/auth` |
| `cdelastic` | Changes to `/etc/xorlab/elastic` |
| `cdmonitoring` | Changes to `/etc/xorlab/monitoring` |
| `cdlog` | Changes to the log folder `/var/log/xorlab/` |
| `cdaglocal` | Changes to the local MTA configuration folder `/var/lib/xorlab/xcc/config/work/ag_local/` |
| `xcc-up` | Starts the xcc stack |
| `xcc-up-logf` | Starts the xcc stack and follows its logs |
| `xcc-down` | Stops the xcc stack |
| `xcc-downup` | Stops the xcc stack and starts it again |
| `xcc-downup-logf` | Stops the xcc stack, starts it again, and follows its logs |
| `xcc-up-all` | Starts all stacks |
| `xcc-up-all-logf` | Starts all stacks and follows the logs of the xcc stack |
| `xcc-down-all` | Stops all stacks |
| `xcc-downup-all` | Stops all stacks and starts them again |
| `xcc-downup-all-logf` | Stops all stacks, starts them again, and follows the logs of the xcc stack |
| `tail-xcc` | Follows `xcc.log` |
| `tail-xccerr` | Follows `xcc_err.log` |

### Sandbox (DANA)

| Alias | What it does |
| :- | :- |
| `cddana` | Changes to `/etc/xorlab/dana` |
| `cdlog` | Changes to the log folder `/var/log/xorlab/` |
| `dana-up` | Starts the dana stack |
| `dana-up-logf` | Starts the dana stack and follows its logs |
| `dana-down` | Stops the dana stack |
| `dana-downup` | Stops the dana stack and starts it again |
| `dana-downup-logf` | Stops the dana stack, starts it again, and follows its logs |

### Graceful MTA shutdown

The upgrade also installs the `mta-down` command on the MTA. It finishes the emails the MTA has already accepted before it shuts down the activeguard stack:

1. Blocks new incoming SMTP connections on port 25 of every physical network interface.
2. Flushes the Postfix queues.
3. Waits up to five minutes for the `core` container to finish processing, then up to one minute for it to publish the results to XCC.
4. Stops the activeguard stack and lifts the block again.

If the `core` container is not running, `mta-down` stops the stack right away. Use `mta-down --block` and `mta-down --unblock` to apply or lift only the SMTP block, as an alternative to the `iptables` commands in [Stopping and resuming accepting emails by MTA](#stopping-and-resuming-accepting-emails-by-mta).

## Reboot

To reboot a component, execute the following command:

```shell theme={null}
sudo reboot
```

* **XCC**: can be rebooted at any time.

* **MTA**: stop the `ag` stack before reboot, preferably with [`mta-down`](#graceful-mta-shutdown).

<Tip>
  Emails that are being processed when a shutdown command is issued, will not be lost but are delayed until the MTA is fully operational again. To avoid this delay, you can block new incoming SMTP connections using the `iptables` commands described in the [Email queue](#stopping-and-resuming-accepting-emails-by-mta) section below. The inserted firewall block, `iptables -I`, will be cleared by a reboot or the corresponding `iptables -D` command. It is strongly recommended to only reboot one MTA at a time to ensure continuous email processing.
</Tip>

## Log files

Most xorlab Security Platform internal containers write log files to a standardized location:

```shell theme={null}
/var/log/xorlab/<stack>/<container>/
```

For example:

* `/var/log/xorlab/xcc/backend/`
* `/var/log/xorlab/auth/auth/`
* `/var/log/xorlab/activeguard/core/`
* `/var/log/xorlab/dana/analysisnode/`

The following log files are available:

```shell theme={null}
# Error log file
<container>_err.log
# Verbose log (INFO/DEBUG)
<container>.log
```

The most important container log files:

* backend: `xcc.log` and `xcc_err.log`
* auth: `auth.log` and `auth_err.log`
* core: `activeguard.log` and `activeguard_err.log`
* analysisnode: `analysisnode.log` and `analysisnode_err.log`

<Note>
  **Standard out**

  The following containers do not have log files: `elasticsearch`, `kibana`, `db`, and all monitoring containers. For those, logs are written to the standard output which you can read by executing `docker compose logs <container>` inside the `/etc/xorlab/<stack>` folder.
</Note>

## Email queue

The email queue sizes can be conveniently observed in the grafana monitoring dashboards. For more advanced email queue handling, connect to each MTA separately.

**List all queued emails:**

```shell theme={null}
docker exec -it ag_mta mailq
```

**Flush (resend) all queues:**

```shell theme={null}
docker exec -it ag_mta postqueue -f
```

**Requeue all queued emails:**

```shell theme={null}
docker exec -it ag_mta postsuper -r ALL
```

<Note>
  **Requeue vs. flush**

  A **flush** is a lightweight operation where xorlab Security Platform will try to resend all queued emails.
  A **requeue** will treat all queued emails as if they were completely new emails. This will re-apply all header checks, address rewrites, routing decisions, etc. If you use this when there are emails in the deferred queue that already passed through core, they will be sent again to core (which will cause the email to be shown twice in the XCC).
</Note>

**Delete an email from the queue:**

```shell theme={null}
# Find the queue ID of the email that should be deleted
docker exec -it ag_mta mailq
# Replace <mail_queue_id> with the queue ID of the actual email
docker exec -it ag_mta postsuper -d <mail_queue_id>
```

**Delete all emails in a specific queue:**

```shell theme={null}
# Deletes all emails in the deferred queue. "deferred" can be replaced with other queue names like "incoming" or "active".
docker exec -it ag_mta postsuper -d ALL deferred
```

### Exporting an email from the queue to EML format

The email files of a particular queue—`active`, `incoming`, or `deferred`—are in the `/var/lib/docker/volumes/activeguard_mta_spool/_data/<queue_name>` directory on the MTAs. You must be root to access this folder (`sudo su`).

The email file in the queue directory will have the queue ID as a name (e.g., `9A2821FE2`). If you want to convert the email file to the EML format, you can use the following instructions:

1. Run

   ```shell theme={null}
   docker exec -it ag_mta bash
   ```

2. Execute

   ```shell theme={null}
   cd /var/spool/postfix/<queue_name>
   ```

3. Find the email file.

4. Run

   ```shell theme={null}
   postcat -bh <file_name> > /var/log/file_name.eml
   ```

5. Press <kbd>Ctrl</kbd>+<kbd>D</kbd>.

6. Now, you can find the EML file in the `/var/log/xorlab/activeguard/mta/` directory.

### Stopping and resuming accepting emails by MTA

Sometimes you might want to prevent an MTA from accepting emails because, for example, you would like to empty the MTA from messages before performing an update. In this case, use SSH and run the following command (port 25 is used here as an example):

```shell theme={null}
# block incoming emails on MTA (e.g., for maintenance) on port 25
sudo iptables -I DOCKER-USER -i eth0 -p tcp --dport 25 -m state --state NEW -j REJECT
```

where `eth0` is the interface name, which can be found, for example, with `ip -4 a`.

When you execute the command, wait one minute—or check in XCC for emails being processed—then shut down xorlab Security Platform.

After the maintenance, you can resume accepting emails:

```shell theme={null}
# accept incoming emails again on port 25
sudo iptables -D DOCKER-USER -i eth0 -p tcp --dport 25 -m state --state NEW -j REJECT
```

<Note>
  **Docker packet filtering**

  To learn more, see the [Packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/) and [Match the original IP and ports for requests](https://docs.docker.com/engine/network/packet-filtering-firewalls/#match-the-original-ip-and-ports-for-requests) from the official Docker Engine documentation.
</Note>


# Upgrading to a Patch Release
Source: https://docs.xorlab.com/latest/patch-upgrade

Apply a Major.Minor.Patch increment to an existing installation, with the backup and rollback steps around it.

<Warning>
  **Prerequisites**

  * Read the [Changelog](/changelog) to see the list of all changes.
  * Have a recent backup available, see [Manual backup](/latest/backup-recovery#manual-backup) and [Patch rollback](/latest/backup-recovery#patch-rollback).
</Warning>

xorlab version numbering follows the `Major.Minor.Patch` semantics. Use this guide to upgrade from e.g. `X.X.2` to `X.X.4`. For a major or minor upgrade, see [Upgrade xorlab](/latest/upgrade-guide) instead.

## Upgrade xorlab

To upgrade xorlab to a newer patch, run the following command as the `admin` user on all xorlab hosts in the provided order:

```shell theme={null}
# Replace the X letters with the correct patch and version numbers
xorlab-upgrade 11.0.X
```

Upgrade order:

1. Sandbox (only applicable for on-prem DANA appliances)
2. XCC
3. MTA

After you ran the command on all hosts, the upgrade is finished. You can use `docker ps` on each host to verify that the new version is running.

## Troubleshooting

If you experience issues or have questions, refer to the support documentation or contact our support team at [support@xorlab.com](mailto:support@xorlab.com).


# Customize QR Code Analysis
Source: https://docs.xorlab.com/latest/qr-code-extraction

Customize how xorlab extracts and analyzes URLs from QR codes in attachments and rendered previews.

xorlab analyzes QR codes by default and extracts their URLs where available. By default, it applies QR code analysis on:

* Images attached to the email
* Rendered previews of the email body (only done for some emails)
* Rendered previews of attachments (only done for some emails)

## Change rendering policy

xorlab has a separate rendering policy for email body previews as well as for attachment previews.

<Info>
  Which emails and attachments are rendered by default, and the delivered values of the parameters below, are
  documented in [Detection Defaults → QR code analysis](/latest/detection-defaults#qr-code-analysis).
  Access to that page is restricted.
</Info>

You can change this behavior in [Expert Editor](/latest/expert-editor) in the `local.properties` file located at `activeguard/core/rule_sets/90_local/params/` by setting the following parameters to `ACTIVE` or `DISABLED`:

<Warning>
  **Increased resources**

  Enabling `FILE` or `MAIL` rendering can significantly increase the resource usage on the MTA.
</Warning>

```
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_analysis_pipelines_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_incoming_emails_qr_code_keywords_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_incoming_emails_sender_unknown_never_delivered_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_incoming_emails_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_incoming_emails_untrusted_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_external_emails_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_reported_emails_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_internal_emails_state
EXECUTE_MAIL_RENDER_PREVIEW_INSTRUCTION_for_outgoing_emails_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_incoming_emails_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_incoming_emails_untrusted_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_external_emails_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_reported_emails_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_internal_emails_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_outgoing_emails_state
EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_analysis_pipelines_state
```

<Note>
  **QR code analysis for internal/outgoing emails**

  When enabling one of these `FILE_RENDER` rules:

  ```
  EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_internal_emails_state=ACTIVE
  EXECUTE_FILE_RENDER_PREVIEW_INSTRUCTION_for_outgoing_emails_state=ACTIVE
  ```

  you must also enable the two `FILE_QR_EXTRACTION` rules, otherwise they have no impact:

  ```
  EXECUTE_FILE_QR_EXTRACTION_INSTRUCTION_for_internal_emails_state=ACTIVE
  EXECUTE_FILE_QR_EXTRACTION_INSTRUCTION_for_outgoing_emails_state=ACTIVE
  ```
</Note>

After changing the rule properties, click **Publish**. The rule-set configuration becomes active within about one minute.

## Enabling/disabling QR code URL extraction

1. Open [Expert Editor](/latest/expert-editor) and go to the file located at `activeguard/core/active_guard.yml`.

2. The following configuration represents the default settings, which are automatically applied in the absence of explicit `qrCodeService` configurations in the `active_guard.yml` file.

   ```yaml active_guard.yml theme={null}
   # QR code service: enabled by default. This service is responsible for extracting QR codes from files.
   qrCodeService:
     # Enable or disable service
     enabled: true
   ```

3. To disable the QR Code URL Extraction feature, simply change `enabled: true` to `enabled: false`.

4. Click **Publish**, then restart all MTAs. The `qrCodeService` setting is in `active_guard.yml` and requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

## Customizing extraction from PDF attachments

For a more tailored approach to handling PDF attachments, you can adjust how the system renders PDF pages for QR code extraction:

1. In [Expert Editor](/latest/expert-editor), open the `activeguard/core/active_guard.yml` file.

2. Locate or add the `pdfFileRenderService` section to adjust the rendering settings for PDF attachments as needed:

   ```yaml active_guard.yml theme={null}
   # PDF File Render Service config
   pdfFileRenderService:
     # Sets how many pages to render, starting with the first page. For example, a value of 1 would render only the first page. A value of 3 would render the
     # first 3 pages. Must be greater than or equal to 1.
     numberOfPages: <pages>
     # Sets the x resolution of the rendered images. Must be greater than or equal to 600 and less than or equal to 3840. Be careful with this setting,
     # as this can significantly increase memory usage during PDF rendering.
     xResolution: <x_resolution>
     # Sets the y resolution of the rendered images. Must be greater than or equal to 600 and less than or equal to 3840. Be careful with this setting,
     # as this can significantly increase memory usage during PDF rendering.
     yResolution: <y_resolution>
   ```

3. Click **Publish**, then restart all MTAs. The `pdfFileRenderService` setting is in `active_guard.yml` and requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

<Info>
  The delivered PDF rendering values are documented in
  [Detection Defaults → QR code analysis](/latest/detection-defaults#qr-code-analysis).
  Access to that page is restricted.
</Info>

By following these steps, you can activate and configure the QR Code URL Extraction feature according to your organization’s specific needs. Adjusting the PDF rendering settings allows for flexibility in balancing performance with the thoroughness of QR code scanning within your documents.


# Release Lifecycle Support
Source: https://docs.xorlab.com/latest/release-lifecycle-support

How long each major version stays supported, and what that means for planning an upgrade.

This policy is designed to provide predictable support timelines for customers while reducing operational risk and maintenance overhead.

## Release support timeline

| Release | Initial Release Date | Support End Date |
| - | - | - |
| 10.0 | October 31, 2025 | September 17, 2026 |
| 11.0 | June 5, 2026 | March 5, 2027 |

## Scope and definitions

* A release refers to a major xorlab release (e.g. 9.0, 10.0, 11.0).
* The policy applies primarily to on-premises deployments as SaaS instances get automatically updated.
* Release support refers to security updates, bug fixes, and technical assistance.
* Remaining on unsupported releases may expose systems to security and stability risks.

## Release support policy

xorlab follows a time-based release support model:

* Each major release is officially supported for 9 months from its initial public release date.
* Customers are expected to upgrade to a newer release at least twice per year.
* Once a release reaches end of support, there will be no further patches released.

This approach aligns xorlab with common industry practices and improves predictability for upgrade planning.


# Rule Parameters
Source: https://docs.xorlab.com/latest/rule-parameters

The low-level knobs behind the Actions screen, with the suffix conventions for inbound and outbound defense.

Normally, these parameters do not need to be used directly, instead one can use the [Actions](/latest/detection-actions) configuration screen.

## Parameters for email classification

<Accordion title="Available parameters">
  ```shell theme={null}
  BEC_decision_action
  BEC_decision_email_screenshot
  BEC_decision_keep_dana_assets
  BEC_decision_notify_user
  BEC_decision_subject_rewrite
  EXTORTION_decision_action
  EXTORTION_decision_email_screenshot
  EXTORTION_decision_keep_dana_assets
  EXTORTION_decision_notify_user
  EXTORTION_decision_subject_rewrite
  BLACKLIST_decision_action
  BLACKLIST_decision_email_screenshot
  BLACKLIST_decision_keep_dana_assets
  BLACKLIST_decision_notify_user
  BLACKLIST_decision_subject_rewrite
  FILTER_high_confidence_decision_action
  FILTER_high_confidence_decision_email_screenshot
  FILTER_high_confidence_decision_keep_dana_assets
  FILTER_high_confidence_decision_notify_user
  FILTER_high_confidence_decision_subject_rewrite
  FILTER_medium_confidence_decision_action
  FILTER_medium_confidence_decision_email_screenshot
  FILTER_medium_confidence_decision_keep_dana_assets
  FILTER_medium_confidence_decision_notify_user
  FILTER_medium_confidence_decision_subject_rewrite
  FILTER_low_confidence_decision_action
  FILTER_low_confidence_decision_email_screenshot
  FILTER_low_confidence_decision_keep_dana_assets
  FILTER_low_confidence_decision_notify_user
  FILTER_low_confidence_decision_subject_rewrite
  IMPERSONATION_high_confidence_decision_action
  IMPERSONATION_high_confidence_decision_email_screenshot
  IMPERSONATION_high_confidence_decision_keep_dana_assets
  IMPERSONATION_high_confidence_decision_notify_user
  IMPERSONATION_high_confidence_decision_subject_rewrite
  IMPERSONATION_medium_confidence_decision_action
  IMPERSONATION_medium_confidence_decision_email_screenshot
  IMPERSONATION_medium_confidence_decision_keep_dana_assets
  IMPERSONATION_medium_confidence_decision_notify_user
  IMPERSONATION_medium_confidence_decision_subject_rewrite
  IMPERSONATION_low_confidence_decision_action
  IMPERSONATION_low_confidence_decision_email_screenshot
  IMPERSONATION_low_confidence_decision_keep_dana_assets
  IMPERSONATION_low_confidence_decision_notify_user
  IMPERSONATION_low_confidence_decision_subject_rewrite
  MALWARE_dynamic_decision_action
  MALWARE_dynamic_decision_email_screenshot
  MALWARE_dynamic_decision_keep_dana_assets
  MALWARE_dynamic_decision_notify_user
  MALWARE_dynamic_decision_subject_rewrite
  MALWARE_static_decision_action
  MALWARE_static_decision_email_screenshot
  MALWARE_static_decision_keep_dana_assets
  MALWARE_static_decision_notify_user
  MALWARE_static_decision_subject_rewrite
  PHISHING_high_confidence_decision_action
  PHISHING_high_confidence_decision_email_screenshot
  PHISHING_high_confidence_decision_keep_dana_assets
  PHISHING_high_confidence_decision_notify_user
  PHISHING_high_confidence_decision_subject_rewrite
  PHISHING_medium_confidence_decision_action
  PHISHING_medium_confidence_decision_email_screenshot
  PHISHING_medium_confidence_decision_keep_dana_assets
  PHISHING_medium_confidence_decision_notify_user
  PHISHING_medium_confidence_decision_subject_rewrite
  PHISHING_low_confidence_decision_action
  PHISHING_low_confidence_decision_email_screenshot
  PHISHING_low_confidence_decision_keep_dana_assets
  PHISHING_low_confidence_decision_notify_user
  PHISHING_low_confidence_decision_subject_rewrite
  SPAM_high_confidence_decision_action
  SPAM_high_confidence_decision_email_screenshot
  SPAM_high_confidence_decision_keep_dana_assets
  SPAM_high_confidence_decision_notify_user
  SPAM_high_confidence_decision_subject_rewrite
  SPAM_medium_confidence_decision_action
  SPAM_medium_confidence_decision_email_screenshot
  SPAM_medium_confidence_decision_keep_dana_assets
  SPAM_medium_confidence_decision_notify_user
  SPAM_medium_confidence_decision_subject_rewrite
  SPAM_low_confidence_decision_action
  SPAM_low_confidence_decision_email_screenshot
  SPAM_low_confidence_decision_keep_dana_assets
  SPAM_low_confidence_decision_notify_user
  SPAM_low_confidence_decision_subject_rewrite
  VIP_FRAUD_high_confidence_decision_action
  VIP_FRAUD_high_confidence_decision_email_screenshot
  VIP_FRAUD_high_confidence_decision_keep_dana_assets
  VIP_FRAUD_high_confidence_decision_notify_user
  VIP_FRAUD_high_confidence_decision_subject_rewrite
  VIP_FRAUD_medium_confidence_decision_action
  VIP_FRAUD_medium_confidence_decision_email_screenshot
  VIP_FRAUD_medium_confidence_decision_keep_dana_assets
  VIP_FRAUD_medium_confidence_decision_notify_user
  VIP_FRAUD_medium_confidence_decision_subject_rewrite
  VIP_FRAUD_low_confidence_decision_action
  VIP_FRAUD_low_confidence_decision_email_screenshot
  VIP_FRAUD_low_confidence_decision_keep_dana_assets
  VIP_FRAUD_low_confidence_decision_notify_user
  VIP_FRAUD_low_confidence_decision_subject_rewrite
  INTERNAL_EXTORTION_decision_action
  INTERNAL_EXTORTION_decision_email_screenshot
  INTERNAL_EXTORTION_decision_keep_dana_assets
  INTERNAL_EXTORTION_decision_notify_user
  INTERNAL_EXTORTION_decision_subject_rewrite
  INTERNAL_PHISHING_high_confidence_decision_action
  INTERNAL_PHISHING_high_confidence_decision_email_screenshot
  INTERNAL_PHISHING_high_confidence_decision_keep_dana_assets
  INTERNAL_PHISHING_high_confidence_decision_notify_user
  INTERNAL_PHISHING_high_confidence_decision_subject_rewrite
  INTERNAL_PHISHING_medium_confidence_decision_action
  INTERNAL_PHISHING_medium_confidence_decision_email_screenshot
  INTERNAL_PHISHING_medium_confidence_decision_keep_dana_assets
  INTERNAL_PHISHING_medium_confidence_decision_notify_user
  INTERNAL_PHISHING_medium_confidence_decision_subject_rewrite
  INTERNAL_PHISHING_low_confidence_decision_action
  INTERNAL_PHISHING_low_confidence_decision_email_screenshot
  INTERNAL_PHISHING_low_confidence_decision_keep_dana_assets
  INTERNAL_PHISHING_low_confidence_decision_notify_user
  INTERNAL_PHISHING_low_confidence_decision_subject_rewrite
  WHITELIST_decision_action
  SIMULATION_decision_action
  ```
</Accordion>

Available suffixes to the parameters for inbound email defense:

| General parameter suffix | Function | Values |
| :- | :- | :- |
| `_action` | Decides what should happen with the email | `QUARANTINE`, `DROP`, `DELIVER` or `UNDECIDED`  `UNDECIDED` will result in a `DELIVER` if no other rule specifies another action |
| `_email_screenshot` | Enables or disables [email content preview](/latest/data-retention-previews#change-email-previews) as a static image | `true` or `false` |
| `_keep_dana_assets` | Enables or disables [storing Sandbox screenshots](/latest/xorlab-sandbox#show-screenshots-for-benign-attachments) | `true` or `false` |
| `_notfiy_user` | Sends the recipient a notification that an incoming email has been quarantined | `true` or `false` |
| `_subject_rewrite` | Prepends a specified text to the email when delivered. Usually used in conjunction with the `DELIVER` or `UNDECIDED` action | text string |

Those rule parameters can be adjusted per verdict and confidence. For example, the following configuration activates quarantining for high-confidence phishing, but delivers medium-confidence phishing with a subject rewrite:

```shell local.properties theme={null}
# Quarantine high-confidence phishing emails
PHISHING_high_confidence_decision_action=QUARANTINE
# Do not send a quarantine notification
PHISHING_high_confidence_decision_notify_user=false
# Do not do a subject rewrite
PHISHING_high_confidence_decision_subject_rewrite=
 
# Deliver medium-phishing confidence emails (if no other verdict has another decision)
# Specifying DELIVER would force-deliver this email even if another verdict also applies
PHISHING_medium_confidence_decision_action=UNDECIDED
# Do not send a quarantine notification
PHISHING_medium_confidence_decision_notify_user=false
# Do a subject rewrite with [SPAM]
PHISHING_medium_confidence_decision_subject_rewrite=[SPAM]
```

## Parameters for reported emails

<Accordion title="Available parameters">
  ```shell theme={null}
  REPORTED_enable_filter_decision_state
  REPORTED_enable_receipt_acknowledgement_state
  REPORTED_enable_receipt_acknowledgement_template
  REPORTED_BEC_decision_action
  REPORTED_BEC_decision_template
  REPORTED_BENIGN_early_decision_action
  REPORTED_BENIGN_early_decision_template
  REPORTED_EXTORTION_decision_action
  REPORTED_EXTORTION_decision_template
  REPORTED_FILTER_high_confidence_decision_action
  REPORTED_FILTER_high_confidence_decision_template
  REPORTED_FILTER_medium_confidence_decision_action
  REPORTED_FILTER_medium_confidence_decision_template
  REPORTED_FILTER_low_confidence_decision_action
  REPORTED_FILTER_low_confidence_decision_template
  REPORTED_BLACKLIST_decision_action
  REPORTED_BLACKLIST_decision_template
  REPORTED_IMPERSONATION_high_confidence_decision_action
  REPORTED_IMPERSONATION_high_confidence_decision_template
  REPORTED_IMPERSONATION_medium_confidence_decision_action
  REPORTED_IMPERSONATION_medium_confidence_decision_template
  REPORTED_IMPERSONATION_low_confidence_decision_action
  REPORTED_IMPERSONATION_low_confidence_decision_template
  REPORTED_INTERNALLY_FORWARDED_decision_action
  REPORTED_INTERNALLY_FORWARDED_decision_template
  REPORTED_MALWARE_dynamic_decision_action
  REPORTED_MALWARE_dynamic_decision_template
  REPORTED_MALWARE_static_decision_action
  REPORTED_MALWARE_static_decision_template
  REPORTED_PHISHING_high_confidence_decision_action
  REPORTED_PHISHING_high_confidence_decision_template
  REPORTED_PHISHING_low_confidence_decision_action
  REPORTED_PHISHING_low_confidence_decision_template
  REPORTED_PHISHING_medium_confidence_decision_action
  REPORTED_PHISHING_medium_confidence_decision_template
  REPORTED_SIMULATION_decision_action
  REPORTED_SIMULATION_decision_template
  REPORTED_NOT_JUNK_decision_action
  REPORTED_NOT_JUNK_decision_template
  REPORTED_SPAM_high_confidence_decision_action
  REPORTED_SPAM_high_confidence_decision_template
  REPORTED_SPAM_low_confidence_decision_action
  REPORTED_SPAM_low_confidence_decision_template
  REPORTED_SPAM_medium_confidence_decision_action
  REPORTED_SPAM_medium_confidence_decision_template
  REPORTED_VIP_FRAUD_high_confidence_decision_action
  REPORTED_VIP_FRAUD_high_confidence_decision_template
  REPORTED_VIP_FRAUD_medium_confidence_decision_action
  REPORTED_VIP_FRAUD_medium_confidence_decision_template
  REPORTED_VIP_FRAUD_low_confidence_decision_action
  REPORTED_VIP_FRAUD_low_confidence_decision_template
  REPORTED_WHITELIST_decision_action
  REPORTED_WHITELIST_decision_template
  ```
</Accordion>

The parameters for the handling of reported emails allow you to specify when a case should be handled automatically and with which feedback email:

| General parameter suffix | Function | Values |
| :- | :- | :- |
| `_action` | Specifies whether the case should be kept open or automatically closed | `QUARANTINE` (keep case open), `DROP` (auto-handle case) and `UNDECIDED`<br /><br />`UNDECIDED` will result in `QUARANTINE` if no other rule specifies a different action |
| `_template` | Specifies which feedback template should be sent back to the reporter. If the case is auto-handled, this feedback template will be automatically sent. If the case is kept open, this feedback template will be pre-selected in the web interface, but not sent. If this parameter is left empty, no feedback template is sent. All available templates can be seen under `shared/email_templates` | Name of a template (for a list of all available templates, please refer to [Email Notification Templates](/latest/email-template-overview)) |

The following example shows how to auto-handle high-confidence phishing, but keep medium-confidence phishing cases open:

```shell local.properties theme={null}
# Auto-handle emails classified as high-confidence phishing
REPORTED_PHISHING_high_confidence_decision_action=DROP
# Send back the phishing template
REPORTED_PHISHING_high_confidence_decision_template=PHISHING

# Keep case open if the email is classified as medium-confidence phishing
REPORTED_PHISHING_medium_confidence_decision_action=UNDECIDED
# Preselect the phishing template, but don't send it
REPORTED_PHISHING_medium_confidence_decision_template=PHISHING
```

Benign emails must fulfill additional requirements in order to be auto-handled based on the benign verdict (i.e., with `REPORTED_BENIGN_early_decision_action=DROP`). This should ensure that no malicious email is accidentally auto-handled as benign. Therefore, reported emails may be marked as benign, but not auto-handled.

The most important requirements for auto-handling benign emails are:

* All links must have a local reputation above 0.
* Email must be internal or the sender must have at least medium trust.
* No suspicious files attached (e.g., no HTML files).
* No high spam or risk score.
* No cloud storage links.

#### Disable acknowledgment emails

Normally, acknowledgment emails are disabled via the *Actions* configuration screen. In special cases, you can configure the following in `activeguard/core/rule_sets/90_local/params/local.properties`:

```shell theme={null}
# Disable acknowledgment emails. Set to ACTIVE to enable it again
REPORTED_enable_receipt_acknowledgement_state=DISABLED
```

The email template used for the acknowledgment email can be configured in the following way (`ACKNOWLEDGE_RECEIPT` is the default):

```shell theme={null}
# Specify the template used for acknowledgment emails
REPORTED_enable_receipt_acknowledgement_template=ACKNOWLEDGE_RECEIPT
```

## Multi-Tenancy

The `local.properties` file used throughout this page lives in `90_local` and therefore applies to **all** tenants.

To set a parameter for a single tenant only, use a `tenant.properties` file in that tenant's rule set instead of `local.properties`. See [Manage Tenant Rules](/latest/multi-tenancy-rules#tenant-specific-parameters) for the setup.

To switch a tenant to a completely different set of parameters, reference a different [rule profile](/latest/rule-profiles) for that tenant.


# Rule Profiles
Source: https://docs.xorlab.com/latest/rule-profiles

A set of predefined rule parameters, mostly used to switch between monitoring and inline mode.

Rule profiles are used to:

* Switch between Inline and Monitoring mode
* Switch between Toothless and Active protection

The active profiles are configured in the `shared/guarded_tenants.yml` file:

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    ruleProfiles:
      - <profile1>
      - ...
```

You only need to list the additional profiles that you want to apply. The built-in default profiles `default.properties`, `local.properties`, and `ui.properties` are included automatically and must not be configured explicitly. All added rule profiles are added in order between `default.properties` and `local.properties`.

Configured `ruleProfiles` are applied in the specified order between the implicit `default.properties` and the implicit `local.properties` / `ui.properties`. This means that `local.properties` still overwrites the configured profiles, and the configuration that a user sets in UI (`ui.properties`) still has the highest precedence.

<Note>
  Do not add `default.properties`, `local.properties`, or `ui.properties` to `ruleProfiles`. They are applied automatically.
</Note>

The following table lists the available profiles:

| Profile | Description |
| :- | :- |
| `default_actions.properties` | **Default profile for active inbound email security**<br /><br />It uses subject rewrites for lower confidence decisions and quarantine actions for higher confidence decisions. Subject rewrite text is `[SPAM]`<br /><br />It does not use attachment removal nor quarantine notifications |
| `no_subject_rewrite_no_quarantine.properties` | **“Toothless” mode**<br /><br />This profile deactivates all quarantine actions and subject rewrites. This profile is usually used for evaluation purposes where xorlab should not perform any actions on the email traffic |
| `no_auto_feedback.properties` | **Deactivates all automatic feedback and acknowledgment emails for reported emails**<br /><br />If used, users will not get any automatic reply after reporting an email<br /><br />**Note:** this profile does not prevent the sending of manual feedback through the web interface |
| `default_dana.properties` | **Configures the default SaaS Sandbox (DANA) settings**<br /><br />Applies the default Sandbox scope, including the additional coverage for recipients in the *Exposed accounts*, *High-value targets*, and *Recipient dynamic analysis* lists |
| `monitoring_dana_offline_only.properties` | **Configures the default SaaS Sandbox (DANA) settings for monitoring mode**<br /><br />Same scope as `default_dana.properties`, but scans are performed offline |
| `no_dana_except_for_specific_recipients.properties` | Disables the Sandbox except for recipients in the *Recipient dynamic analysis* list |
| `fp_low.properties` | **Configures the detection to be less aggressive to avoid false positives**<br /><br />This profile should be added per default in all deployments and only removed when a more aggressive detection is required |
| `learning_mode.properties` | **Can be used for active inbound email security during the learning phase of xorlab Security Platform**<br /><br />Basic defense is active (quarantining and subject rewrites), but advanced filters that depend on the learning are disabled to prevent false positives |

Deprecated profiles that will be removed in future releases:

* `fp_sensitive.properties`: It can still be used, but new deployments should instead use `fp_low.properties`.

<Info>
  The duration of the learning phase, and the delivered parameter values behind
  `default_dana.properties`, are documented in
  [Detection Defaults](/latest/detection-defaults#sandbox). Access to that page is restricted.
</Info>

## Common profile configurations

### Standard - inline and active

Standard inbound email security:

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    ruleProfiles:
      - default_dana.properties
      - default_actions.properties
      - fp_low.properties
```

### Toothless

Disable all actions on emails. Can be used as an evaluation mode as well as during learning phase if no actions should be taken:

```yaml guarded_tenants.yml theme={null}
tenants:
  - name: example
    ruleProfiles:
      - default_dana.properties
      - default_actions.properties
      # Disable quarantining and subject rewrites
      - no_subject_rewrite_no_quarantine.properties
      # Disable feedback and acknowledgments for reported emails
      - no_auto_feedback.properties
      - fp_low.properties
```

Because it deactivates the quarantine action itself, no email gets the `QUARANTINED` decision while this profile is active — in Monitoring mode just as much as in Inline mode. That is the most common reason for an instance that reports verdicts but shows nothing in quarantine: remove the profile and click **Publish**.

## Multi-Tenancy

`ruleProfiles` is a per-tenant setting, so in a multi-tenant deployment each tenant can run with a different profile combination. For example, you can keep a newly onboarded tenant in *Toothless* mode while all other tenants run the standard configuration.

* To apply the same profiles to many tenants without repeating them, put `ruleProfiles` into a shared config template, see [Using Tenant Config Templates](/latest/multi-tenancy-configsets).
* To override individual rule parameters for a single tenant instead of switching the whole profile, see [Manage Tenant Rules](/latest/multi-tenancy-rules#tenant-specific-parameters).


# Sizing Guide
Source: https://docs.xorlab.com/latest/sizing-guide

Pick a size profile from your mailbox count and daily message throughput, with the parameters each one implies.

The sizing is flexible to some extent, so contact us if you'd like to adjust some parameters.

## Size Profiles and System Requirements

Size profiles:

| | Minimal | Small | Medium | Large |
| :- | :- | :- | :- | :- |
| **Users** | Up to 100 | 100 to 2,000 | 2,000 to 10,000 | 10,000 to 40,000 |
| **Emails/Day** | \<10k | 10k–25k | 25k–100k | 100k–300k |

Required infrastructure:

| | Minimal | Small | Medium | Large |
| :- | :- | :- | :- | :- |
| **VM: MTA** | 2 VMs | 2 load-balancing VMs | 3–4 load-balancing VMs | 3–4 load-balancing VMs |
| CPU / vCPU (MTA) | 2 vCPU | 8 vCPU | 12 vCPU | 16 vCPU |
| AVX2 (MTA) | Required | Required | Required | Required |
| Memory (MTA) | 5 GB | 8 GB | 16 GB | 32 GB |
| Disk (MTA)<sup>1</sup> | 100 GB SSD | 150 GB SSD | 300 GB SSD | 500 GB SSD |
| **VM: XCC** | 1 VM | 1 VM | 1 VM | 1 VM |
| CPU / vCPU (XCC) | 2 vCPU | 8 vCPU | 8 vCPU | 12 vCPU |
| Memory (XCC) | 12 GB | 16 GB | 32 GB | 48 GB |
| Disk (XCC)<sup>2</sup> | 200 GB SSD | 750 GB SSD | 3.5 TB SSD | 10 TB SSD |

<sup>1</sup> Depends on whether archiving should be enabled.<br />
<sup>2</sup> Can be reduced with lower retention time (30 days assumed).

<Note>
  **X-Large size profile**

  For environments with more than 40,000 users or over 300,000 emails per day, an **X-Large** size profile may be required. These setups involve custom infrastructure planning and higher performance requirements.\
  Please contact us via [mail](<mailto:support@xorlab.com?subject=xorlab x-large sizing info request>) for tailored recommendations and assistance.
</Note>

## Docker volume storage location and size

We recommend that the disk size requirements [specified above](#size-profiles-and-system-requirements) are available on root (`/`). Should this pose a problem, we require a minimum of 100 GB on `/` and you can allocate the rest to `/var/lib/xorlab`. You can reduce disk size requirements by limiting asset and/or log [retention times](/latest/data-retention-overview).

If you want to change the default location, or your disk is full and you don’t want to decrease retention times, please contact our customer support team.


# Replace MTA GUI Certificate
Source: https://docs.xorlab.com/latest/tls-certificates-for-mta-proxy

Replace the TLS certificate used by the MTA GUI reverse proxy.

<Warning>
  **Prerequisites**

  * New certificate and key available as two separate files in PEM format
  * We recommend that the certificate [SAN](https://en.wikipedia.org/wiki/Subject_Alternative_Name) matches the hostname
</Warning>

## Replace certificate

1. Copy the new certificate files as `<certificate>.crt` (certificate) and `<private_key>.key` (private key) into the folder `/etc/xorlab/tls`.

2. Execute the following commands to change the file names and permissions:

   ```shell theme={null}
   cd /etc/xorlab/tls
   sudo cp <private_key>.key rproxy.key
   sudo cp <certificate>.crt rproxy.crt
   sudo chmod 400 rproxy.key
   sudo chmod 644 rproxy.crt
   sudo chown 2050:2050 rproxy.key
   sudo chown 2050:2050 rproxy.crt
   ```

3. Reload the reverse proxy to use the new certificate:

   ```shell theme={null}
   docker exec rproxy_rproxy nginx -s reload
   ```

4. Verify the certificate using `openssl c_client`:

   ```shell theme={null}
   openssl s_client -showcerts -servername <mta_server_name> -connect <mta_server_name>:8443 </dev/null
   ```


# Replace MTA SMTP Certificate
Source: https://docs.xorlab.com/latest/tls-certificates-for-mta-smtp

Replace the TLS certificate the MTA presents on SMTP connections.

<Warning>
  **Prerequisites**

  * New certificate and key available as two separate files in PEM format
  * We recommend that the certificate [SAN](https://en.wikipedia.org/wiki/Subject_Alternative_Name) matches the hostname
</Warning>

xorlab uses Postfix to handle SMTP connections. For additional information, have a look at the official [Postfix TLS documentation](http://www.postfix.org/TLS_README.html).

## Replace certificate

1. Copy the new certificate files as `tls.crt` (certificate) and `tls.key` (private key) into the folder `/etc/xorlab/tls`.
2. Execute the following commands to set the permission and ownership. The files need to be readable by user `ag_mta` (uid: 2020, gid: 2020):
   ```shell theme={null}
   sudo chmod 400 tls.key
   sudo chmod 644 tls.crt
   sudo chown 2020:2020 tls.key
   sudo chown 2020:2020 tls.crt
   ```
   Then it should look like this:
   ```shell theme={null}
   admin@mta1:/etc/xorlab/tls$ ll
   -rw-r--r-- 1 ag_mta ag_mta 3456 Dec  2 03:04 tls.crt
   -r-------- 1 ag_mta ag_mta 1704 Dec  2 03:04 tls.key
   ```
3. [Restart](/latest/operation-reference#start-and-stop) the MTA containers. This will lead to a 1-2 minute downtime, where the MTA does not accept emails:
   ```shell theme={null}
   cd /etc/xorlab/activeguard/ && docker compose down && docker compose up -d
   ```
4. Go to the folder `/var/log/xorlab/activeguard/mta/` and check in the files `mail.warn` and `mail.err` that there are no errors related to the TLS certificates.

## **(Optional)** Initial setup for older VMs

For older xorlab VMs, it may be required to reconfigure xorlab the first time before you can use the above procedure to replace certificates.

### Change the docker config

In `/etc/xorlab/activeguard/docker-compose.yml` add a bind mount to the `mta` service to map the folder on the host containing the certificates files to the `mta` container. You are free to choose any path inside the container, however, do not choose `/etc/ssl/my_certs` as this directory will be overwritten by the internal config service. In this example, we will use `/etc/ssl/custom/`:

```yaml theme={null}
mta:
    image: ${XOR_REGISTRY}/ag/mta:${MTA_VERSION}
    container_name: ag_mta
    volumes:
      - $TLS_CERT_DIR:/etc/ssl/custom/                   # add this line
```

In `/etc/xorlab/activeguard/.env` set the `$TLS_CERT_DIR` variable:

```shell theme={null}
TLS_CERT_DIR=/etc/xorlab/tls
```

### Change the postfix config

1. In the XCC [Expert Editor](/latest/expert-editor), open the `main.cf` file located in `activeguard/mta/startup_cfg/postfix_custom/`.
2. Set `smtpd_tls_cert_file` and `smtpd_tls_key_file` parameters based on the chosen path above, in this case `/etc/ssl/custom/`:
   ```text theme={null}
   smtpd_tls_cert_file=/etc/ssl/custom/tls.crt
   smtpd_tls_key_file=/etc/ssl/custom/tls.key
   ```
3. Click **Publish** and add a comment to these edits, for example,  `Add custom TLS certificates`.

The new Postfix setting becomes active within about one minute. If you do not want to wait, you can do a manual config reload in the MTA GUI on each MTA.


# Replace XCC Certificate
Source: https://docs.xorlab.com/latest/tls-certificates-for-xcc

Replace the TLS certificate used by the XCC web interface and its HTTPS connections.

<Warning>
  **Prerequisites**

  * New certificate and key available as two separate files in PEM format
  * We recommend that the certificate [SAN](https://en.wikipedia.org/wiki/Subject_Alternative_Name) matches the hostname
</Warning>

## Replace certificate

1. Copy the new certificate files as `<certificate>.crt` (certificate) and `<private_key>.key` (private key) into the folder `/etc/xorlab/tls`.

2. Execute the following commands to change the file names and permissions:

   ```shell theme={null}
   cd /etc/xorlab/tls
   # Backup old certificates
   sudo cp ssl.crt ssl.crt.xor
   sudo cp ssl.key ssl.key.xor
   sudo chmod 400 <private_key>.key
   sudo chmod 644 <certificate>.crt
   sudo rm ssl.crt ssl.key
   sudo ln -s <certificate>.crt ssl.crt
   sudo ln -s <private_key>.key ssl.key
   ```

3. Reload the `xcc_web` container to apply the changes:

   ```shell theme={null}
   docker exec xcc_web nginx -s reload
   ```

4. Verify the certificate using `openssl c_client`:

   ```shell theme={null}
   openssl s_client -showcerts -servername <xcc_domain> -connect <xcc_url>:443 </dev/null
   ```


# Troubleshooting
Source: https://docs.xorlab.com/latest/troubleshooting

Solutions to the most common problems, including editing configuration files when the web interface is unreachable.

## How to change config files in case the web interface is not reachable

When you made changes to config files in XCC [Expert Editor](/latest/expert-editor) and XCC no longer starts due to some errors in the files, you need to access those files from the command line, fix errors, save the files and restart XCC.

The procedure is as follows:

1. Make an SSH connection to your XCC instance.

2. Stop the XCC backend container:

   `cd /etc/xorlab/xcc && docker compose down`

3. Enter the commands listed below:

   `sudo su -s /bin/bash xcc_backend`

   then

   `cd /var/lib/xorlab/xcc/config/work/ag_local/`

4. You are now in the folder containing config files presented in Expert Editor. Find and adjust (with vim) the required file.

5. Enter the commands listed below:

   `git add <changed file>`

   then

   `git commit -m "<comment the change>"`

6. Press **Ctrl+D** to close the current shell (exit).

7. Start the container again:

   `docker compose up -d`

## How to find MTA logs using the command line

If you want to check the MTA logs, you can do this using SSH connection and the following commands in terminal:

1. Go to the right location: `cd /var/log/xorlab/activeguard/core/` for the email processing logs or `cd /var/log/xorlab/activeguard/mta/` for SMTP logs.
2. Make all files visible: `ll`
3. Select the log file of the date relevant to your investigation and open it with `less` (for `.log` files) or `zless` (for `.zip` files).

For a summary of all log file locations in xorlab, please have a look at [Operation Guide](/latest/operation-reference#log-files).

## How to connect to MTA GUI

You can connect with your MTA GUI using the following URL: `your.domain.name:8443`. Keep in mind that the URL might differ if you change the setup.

## How to find a GGRID of an email

You can use a unique identifier (GGRID) of an email used by xorlab to make your search easier in the core logs:

1. Go to XCC in your browser.

2. Select the email you are looking for so that it opens on the **Message Detail** page.

3. In the address bar of your browser you will see the GGRID of this email. It can be used to find the specific email in the core logs, for example using the `grep <ggrid> activeguard.log` command.

   <img alt="Mail GGRID" />

   *Mail GGRID*

## An email didn’t appear in a user’s inbox

If a message got lost on the way to a user’s inbox, you can search for some information:

1. We recommend to start checking the main XCC web interface if the email can be retrieved. You could search for the sender or even refine your query to find the exact email—please see [Search](/latest/search).

   <img alt="Searching for a lost email" />

2. If you find the email and it's status is `DELIVERED`, it means that xorlab could send the email successfully to the next hop. In all other cases, proceed below.

3. Start [checking the SMTP logs](#how-to-find-mta-logs-using-the-command-line) to see if the email arrived at xorlab and whether postfix could forward it to the core or not. SMTP logs are available on MTA: `/var/log/xorlab/activeguard/mta/mail.info`.

4. Check SMTP logs if the core sent the email back to postfix after processing and whether postfix could forward the email to the external system: use `grep` for `message-id` in `mail.info`. There should be two entries: one when the email arrives at postfix, and one when it is coming from the core. Verify that the email has been forwarded to the external destination.

5. If the email got stuck on the core, then [check the Processing log](#how-to-find-mta-logs-using-the-command-line) (`activeguard.log`). Processing logs on MTA are located here: `/var/log/xorlab/activeguard/core/activeguard.log`. We recommend to `grep` for the [email GGRID](#how-to-find-a-ggrid-of-an-email) to find all logs for a specific email (`zgrep <ggrid> <logfile.zip>`, e.g., `zgrep 7ce1d657-3a0b-48d3-9bbe-cea302d535db activeguard_2022-05-11.0.log.zip`).

## SSQ no mailbox configured error

If you open the SSQ and see the following error

<img alt="No mailbox configured error message" />

This means that your user has an empty `emails` attribute. This attribute is populated as part of the login mechanism. Follow the guide below to see how to configure it for your login mechanism:

* [SAML login](/latest/authentication-saml#attribute-mapping)
* [LDAP login](/latest/authentication-ldap#attribute-mapping)
* [Local user](/latest/authentication-with-a-password-file#quickstart)

## What to do with external blacklist false positives

When an external service such as Spamhaus flags some messages as spam, but their senders are legitimate, you can use a special whitelist called [Spam blacklist exclusion](/latest/whitelists#spam-blacklist-exclusion)—simply add domains that should be excluded from the spam blacklist.

## How to view the current permissions of a user

To check what permissions a particular user has:

1. Log in to xorlab as the said user.

2. Go to the `/api/v2/user/v1/getInfo` endpoint on your xorlab instance, e.g., `xyz.activeguard.cloud/api/v2/user/v1/getInfo`.

3. You will see a list of permissions:

   <img alt="Checking the permissions of a user" />

To learn more about them, please refer to [List of Built-in Permissions](/latest/create-custom-user-role#permissions-role-matrix).

## SAML ADFS troubleshooting

1. Use the URL claims from the authentication success log for the `attributeMapping`.

2. Make sure the user is allowed to authenticate: check the logs on the AD side to ensure that the user has the required permissions.

3. Install a SAML Tracer browser add-on. A SAML Tracer is a tool designed for debugging and analyzing Security Assertion Markup Language (SAML) communications between a service provider (SP) and an identity provider (IdP). This tool is especially useful in Single Sign-On (SSO) and federation services, where SAML is often used to convey authentication and authorization data.

   As you authenticate or complete the SAML exchange, the extension will capture and display the SAML messages. You can click any captured message to view the detailed contents of the SAML assertions, requests, and responses.

4. Enable extensive debug logs for SAML authentication. Contact [support@xorlab.com](mailto:support@xorlab.com) for the required configuration.

5. Check the ADFS configuration: xorlab requires `nameID`. Make sure `nameID` is sent in the response; it might be necessary to create a new property for it if xorlab says the subject is missing. For more information, please refer to [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization).


# Upgrading to Version 11.0.X
Source: https://docs.xorlab.com/latest/upgrade-guide

Upgrade xorlab across major and minor releases, including the configuration files to review for each release.

xorlab follows semantic versioning using the `Major.Minor.Patch` format. For example, `X.Y.2` means patch no. 2 to minor release Y of major version X of the software.

<Warning>
  **Prerequisites**

  * Read the [Changelog](/changelog) to see the list of all changes.
  * Have a recent backup available, see [Manual backup](/latest/backup-recovery#manual-backup) and [Patch rollback](/latest/backup-recovery#patch-rollback).
</Warning>

xorlab follows semantic versioning using the `Major.Minor.Patch` format. To apply only a patch increment, see [Upgrading to a Patch Release](/latest/patch-upgrade) instead.

<Warning>
  **Wait for Release Announcement**

  Releases are always rolled out gradually to SaaS customers first and are closely monitored for any unexpected issues. For xorlab on-prem, please wait to upgrade until the release has been officially announced via email.
</Warning>

## Release support lifecycle

xorlab follows a time-based release support lifecycle. Each major release is supported for 9 months after its initial public release. Customers are expected to upgrade xorlab at least twice per year to remain within a supported release.

Please refer to the [Release Lifecycle Support](/latest/release-lifecycle-support) page to verify support timelines and end-of-support dates.

## Reading the changelog

Before starting with the upgrade, read through the most important parts of the Changelog:

1. Read the [Highlights](/changelog#highlights)
2. Read the [Breaking Changes](/changelog#breaking-changes)

## Upgrade xorlab

To upgrade xorlab, run the following command as the `admin` user on all xorlab hosts in the provided order:

```shell theme={null}
# Replace X.Y.Z with the version number you would like to upgrade to, e.g. 11.0.2
xorlab-upgrade X.Y.Z
```

Upgrade order:

1. Sandbox (only applicable for on-prem DANA appliances)
2. XCC
3. MTA

<Warning>
  The 11 upgrade requires an additional restart of the MTA containers. After you finished the above steps, connect again to your MTAs and restart the containers:

  ```shellscript theme={null}
  cd /etc/xorlab/activeguard 
  docker compose down
  docker compose up -d
  ```
</Warning>

After you ran the command on all hosts, the upgrade is finished. You can use `docker ps` on each host to verify that the new version is running.

## Post-upgrade check

After the upgrade, review the migration logs for any warnings or errors that may occur. To do this, use the following link (be sure to replace `<xcc_domain:xcc.customer.tld>` with your actual XCC domain in the browser):

```html theme={null}
https://<xcc_domain:xcc.customer.tld>/monitoring/explore?panes=%7B%22ZU4%22:%7B%22datasource%22:%22loki_monitoring_cbef60b6%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22expr%22:%22%7Blevel%3D~%5C%22WARN%7CERROR%5C%22,%20container_name%3D%5C%22xcc_backend%5C%22%7D%20%7C%3D%20%60MigrationLogger%60%22,%22queryType%22:%22range%22,%22datasource%22:%7B%22type%22:%22loki%22,%22uid%22:%22loki_monitoring_cbef60b6%22%7D,%22editorMode%22:%22builder%22%7D%5D,%22range%22:%7B%22from%22:%22now-24h%22,%22to%22:%22now%22%7D%7D%7D&schemaVersion=1&orgId=1
```

## New features configuration

After upgrading, review the documentation pages below for the new features introduced in this release and apply configurations as needed.

* The SSQ now supports archiving emails. By default, all SSQ users get access to this functionality. However, if you use custom roles, make sure to add the permission `xcc_quarantine_archive` to any role that should have access to this feature.
* By default, all analyst users have access to the retrospective email scanning feature. If you use custom roles, add the `xcc_mail_import_read` permission to let users view the status of import jobs, or `xcc_mail_import_update` to let them manage import jobs.

## Troubleshooting

If you experience issues or have questions, refer to the support documentation or contact our support team at [support@xorlab.com](mailto:support@xorlab.com).


# VM Resource Configuration
Source: https://docs.xorlab.com/latest/vm-resource-configuration

The sizing-dependent parameters to set on each xorlab VM, listed per sizing tier.

Determine your size profile with the [Sizing Guide](/latest/sizing-guide), find it in the table below, and then configure each parameter accordingly.

After configuration, restart the corresponding component as described in [Operation Guide](/latest/operation-reference#start-and-stop).

| | **Minimal** | **Small** | **Medium** | **Large** | **X-Large** |
| :-: | :-: | :-: | :-: | :-: | :-: |
| **Emails/Day** | \<10k | 10k-25k | 25k-100k | 100k-300k | 300k-1000k |

## MTA

* Value: `CORE_JVM_ARGS`

  Location: `/etc/xorlab/activeguard/.env`

  | **Minimal** | **Small** | **Medium** | **Large** | **X-Large** |
  | :-: | :-: | :-: | :-: | :-: |
  | -Xmx6g | -Xmx6g | -Xmx12g | -Xmx24g | -Xmx24g |

## XCC

* Value: `XCC_START_PARAMS`

  Location: `/etc/xorlab/xcc/backend/backend.env`

  | **Minimal** | **Small** | **Medium** | **Large** | **X-Large** |
  | :-: | :-: | :-: | :-: | :-: |
  | 32 | 32 | 64 | 128 | 128 |

* Value: `XCC_JVM_ARGS`

  Location: `/etc/xorlab/xcc/backend/backend.env`

  | **Minimal** | **Small** | **Medium** | **Large** | **X-Large** |
  | :-: | :-: | :-: | :-: | :-: |
  | -Xmx6g | -Xmx6g | -Xmx8g | -Xmx10g | -Xmx10g |

* Value: `ES_JAVA_OPTS`

  Location: `/etc/xorlab/elastic/docker-compose.yml`

  <Warning>
    Values in the table are not ranges. Each is a single value in the form of `-Xms6g -Xmx6g` which sets both the initial and maximum heap size allocated to the Java Virtual Machine
  </Warning>

  | **Minimal** | **Small** | **Medium** | **Large** | **X-Large** |
  | :-: | :-: | :-: | :-: | :-: |
  | -Xms6g -Xmx6g | -Xms6g -Xmx6g | -Xms12g -Xmx12g | -Xms16g -Xmx16g | -Xms16g -Xmx16g |

* Value: `REDIS_MAXMEMORY`

  Location: `/etc/xorlab/xcc/.env`

  | **Minimal** | **Small** | **Medium** | **Large** | **X-Large** |
  | :-: | :-: | :-: | :-: | :-: |
  | 1GB | 1GB | 4GB | 10GB | 10GB |

## Expert Editor

* Value: `reputationComplexityFactor`

  Location in Expert Editor: `/xcc/backend/xcc.yml`

  This factor roughly controls how fast local reputation is learned. Use the value `25` for 1-25 mailboxes, `50` for 25-50 mailboxes, and keep the default otherwise.

  * Minimal value: `0`

  * Maximal value: `100`

  * Default value: `100`

After changing `reputationComplexityFactor`, click **Publish** and restart XCC. This general `xcc/backend/xcc.yml` setting requires an XCC restart; see [How to Activate the Configuration](/latest/activate-configuration).

* Value: `smtpd_client_connection_count_limit`

  Location in Expert Editor: `activeguard/mta/startup_cfg/postfix_custom/main.cf.vmx.N`

  Controls how many simultaneous connections any client is allowed to make to the Postfix service; useful only when handling very high volumes of mail traffic (**X-Large** sizing and beyond).

  After changing `smtpd_client_connection_count_limit`, click **Publish**. The new Postfix setting becomes active within about one minute.

  See the official [Postfix parameter documentation](https://www.postfix.org/postconf.5.html#:~:text=3.1%20and%20later.-,smtpd_client_connection_count_limit,-\(default%3A%2050\)) or [Postfix performance tuning guide](https://www.postfix.org/TUNING_README.html#:~:text=breaks%20the%20connection.-,Measures%20against%20clients%20that%20make%20too%20many%20connections,-Note%3A%20these%20features).


# VM Setup Guide
Source: https://docs.xorlab.com/latest/vm-setup-guide

Provision the XCC and one or more MTAs on your own virtual infrastructure.

xorlab consists of two on-premises components: XCC and MTA. MTAs are email processing nodes that can be operated redundantly, depending on the expected load and availability requirements. XCC consolidates the analysis results from the MTAs and hosts the web interface.

The optional setup of on-premises Sandbox (DANA) hardware is not covered by this page.

## Preparation

### Hardware requirements

XCC and the MTAs are provided as images in the OVF format. Our [Sizing Guide](/latest/sizing-guide) will help you determine the right configuration for the resulting VMs. Download credentials can be requested [via email](<mailto:support@xorlab.com?subject=xorlab download request>).

### Network requirements

Prepare your firewall and/or proxy such that the connections described in [xorlab Network Guide](/latest/network-guide) are supported.

<Note>
  **Unfiltered DNS**

  Make sure your DNS service for xorlab is unfiltered. Otherwise, xorlab requests for malicious domains/IPs will not be answered and processed messages will be stuck in a queue because of DNS timeouts.
</Note>

### Register required DNS records

1. Register DNS A records for the XCC and MTA VMs with your internal DNS server(s). For XCC, you can also use a CNAME record instead of an A record. For the MTA VMs, A records are required; see also [RFC 2181](https://datatracker.ietf.org/doc/html/rfc2181#section-10.3). The table below shows an example setup for example.com:

   | Component | Record | Type |
   | :- | :- | :- |
   | XCC | `xcc.example.com` | A or CNAME |
   | MTA1 | `mta1.example.com` | A |
   | MTA2 | `mta2.example.com` | A |

2. Add an MX record for every MTA in your setup. Use the same priority for all MTAs to achieve automatic load-balancing. In our example, we use `mx.example.com` and the DNS query result is:

   ```shell theme={null}
   dig MX mx.example.com
   [...]
   ;; ANSWER SECTION:
   mx.example.com. 3600    IN  MX  10 mta1.example.com.
   mx.example.com. 3600    IN  MX  10 mta2.example.com.
   ```

### Prepare the VMs

1. Download the XCC and MTA images (OVF format). The link and credentials will be provided by us.
2. Decompress the zip files and instantiate the XCC and MTA virtual machines using your Hypervisor.

## Setup

### Configure the network

The XCC and MTA VM images have DHCP configured on all network interfaces, which names match `en*`.

If your environment requires static addresses, proceed with the steps below:

1. Open a shell on the VM using your hypervisor, log in and open the `/etc/netplan/00-xorlab-config.yaml` file with elevated privileges (`sudo`). Comment the dynamic configuration out, uncomment the static configuration, and set the appropriate values. In this example, for the `ens192` interface, the config file should look like this:

   ```yaml theme={null}
   network:
     version: 2
     renderer: networkd
     ethernets:
       ens192:
         dhcp4: false
         dhcp6: false
         addresses:
           - 192.168.0.1/16
         routes:
           - to: default
             via: 192.168.0.254
         nameservers:
           search:
             - "example.com"
           addresses:
             - 192.168.0.254
             - 192.168.0.253
   ```

   <Warning>
     **Avoid using certain special-use domain names**

     Some special-use domain names can cause issues. For example, `.local` is reserved for [multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) (mDNS) and should not be used for private networks, since it can lead to name resolution conflicts. Instead, if you need a dedicated naming space for a local network, better use a subdomain under `.home.arpa.`, which is specifically [reserved](https://en.wikipedia.org/wiki/.arpa) for that purpose.
   </Warning>

2. In case you want to add a second interface (or more) to your VM, you need to add a configuration for each:

   <Accordion title="Static IP configuration example for more interfaces">
     `nameservers` block can have either `search` or `addresses`, or both defined.

     ```yaml theme={null}
       version: 2
       renderer: networkd
       ethernets:
         ens192:
           dhcp4: false
           dhcp6: false
           addresses:
             - 192.168.0.1/16
           routes:
             - to: default
               via: 192.168.0.254
           nameservers:
             search:
               - "example.com"
             addresses:
               - 192.168.0.254
               - 192.168.0.253
         ens224:
           dhcp4: false
           dhcp6: false
           addresses:
             - 192.168.0.2/16
           routes:
             - to: default
               via: 192.168.0.254
           nameservers:
             search:
               - "example.com"
             addresses:
               - 192.168.0.254
               - 192.168.0.253
     ```
   </Accordion>

3. Apply the configuration by executing `sudo netplan apply`.

4. Restart all docker containers.

After changing the configuration on all your destination VMs, you should be able to connect to them using SSH.

### Connect via SSH

All our virtual machines are running Ubuntu Linux. The OS comes with a pre-configured admin account. Use the credentials provided to you by xorlab to open an SSH connection.

### Resize the disk

Now, resize the disks of the VMs so that they meet the requirements from the [Sizing Guide](/latest/sizing-guide):

1. Configure your hypervisor to provide the correct amount of storage to the VMs. This step is not described any further here since it depends on your hypervisor.

2. Execute the following steps on every xorlab VM (XCC and MTAs)

3. Run `lsblk` to show the current structure of the disks and partitions.
   ```shell theme={null}
   lsblk
   NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
   sda      8:0    0  100G  0 disk 
   ├─sda1   8:1    0    1M  0 part 
   └─sda2   8:2    0  100G  0 part /
   ```

4. Run `sudo fdisk /dev/<disk>` - replace `<disk>` with the desired disk as shown before. Then follow the highlighted instructions below. The partition number might be different.

   <Note>
     **fdisk**

     No changes will be written to the disk before you execute the `w` command. You can accept the defaults by pressing the <kbd>Enter</kbd> key.
   </Note>

   ```shell {1,2,16,17,21,22,23,24,29,31} theme={null}
   sudo fdisk /dev/sda
   Command (m for help): p

   Disk /dev/sda: 100 GiB, 107374182400 bytes, 209715200 sectors
   Disk model: Virtual disk    
   Units: sectors of 1 * 512 = 512 bytes
   Sector size (logical/physical): 512 bytes / 512 bytes
   I/O size (minimum/optimal): 512 bytes / 512 bytes
   Disklabel type: gpt
   Disk identifier: 0E4A82CF-8961-476F-B565-F53F562FD9CE

   Device     Start       End   Sectors  Size Type
   /dev/sda1   2048      4095      2048    1M BIOS boot
   /dev/sda2   4096 209713151 209709056  100G Linux filesystem

   Command (m for help): d
   Partition number (1,2, default 2): 

   Partition 2 has been deleted.

   Command (m for help): n
   Partition number (2-128, default 2): 
   First sector (4096-209715166, default 4096): 
   Last sector, +/-sectors or +/-size{K,M,G,T,P} (4096-209715166, default 209715166): 

   Created a new partition 2 of type 'Linux filesystem' and of size 100 GiB.
   Partition #2 contains a ext4 signature.

   Do you want to remove the signature? [Y]es/[N]o: n

   Command (m for help): w

   The partition table has been altered.
   Syncing disks.
   ```

5. Resize the file system with:
   ```shell theme={null}
   sudo resize2fs /dev/sda2
   ```

6. Verify that the partition has the correct size with `df -h`.

### Run the Setup Script

`xorlab-setup` will first determine the VM type it's running on.

1. Connect to the XCC VM via SSH and run `xorlab-setup`.
2. Connect to the MTA VM via SSH and run `xorlab-setup`.

The script can be safely run multiple times. It logs additional information to `/var/log/xorlab/host/host_bootstrap.log`.

When you invoke it without arguments, it offers to update to the newest wrapper-managed setup script version before starting the interactive set-up. Direct invocation with arguments such as `--help`, `--restart-services`, or `--reachability-test` omits the update prompt and forwards the arguments directly to the local role-specific script.

Here you can find more information about the script:

* [Script Breakdown](/latest/vm-setup-script-breakdown#script-breakdown): Step-by-step instruction on what the script does. Use this in case you need to manually apply certain steps.
* [Script Coverage Overview](/latest/vm-setup-script-breakdown#script-coverage): Overview of all config files changed by the script.
* [Script Usage](/latest/vm-setup-script-breakdown#using-the-script): Save and re-use inputs to the setup script.

### EHLO configuration

Set the hostnames used by the MTAs for the `EHLO` when the SMTP connection is established. For every xorlab MTA, you will see one `main.cf.vmx.<id>` file: `main.cf.vmx.1` will be applied on MTA 1, `main.cf.vmx.2` on MTA 2, and so on. If there is only one MTA, you will only find the `main.cf` file.

1. Open [Expert Editor](/latest/expert-editor).
2. Navigate to the `activeguard/mta/startup_cfg/postfix_custom/`.
3. Edit each `main.cf*` file and set the `myhostname` parameter to the hostname that points to this MTA in your DNS (A record).

A sample `activeguard/mta/startup_cfg/postfix_custom/main.cf` file should look like this:

```shell main.cf theme={null}
# This hostname will be used by xorlab for SMTP, e.g. in the EHLO message
myhostname = mta1.example.com
```

Click **Publish**. The `main.cf*` changes become active within about one minute.

### Set local NTP servers

xorlab uses the time provided by the OS. In order to configure the OS settings set the `NTP` line in `/etc/systemd/timesyncd.conf`:

```text theme={null}
[Time]
NTP=ntp.example.com ntp.ubuntu.com ...
```

Then restart the NTP service by executing:

```shell theme={null}
sudo systemctl restart systemd-timesyncd.service
```

### Configure performance resources

This is informational only: The VMs are normally already pre-configured according to your expected email load.

However if you expect that your load is different from the ordered VM, adjust the performance configuration according to [VM Resource Configuration](/latest/vm-resource-configuration).

## Optional settings

### Add host mapping for XCC

This is only required if **the MTAs cannot resolve the domain of the XCC via DNS**:

1. SSH connect to each MTA
2. Edit `/etc/hosts`, e.g. `sudo nano /etc/hosts`
3. Add a line with the IP and domain of the XCC:
   ```bash hosts theme={null}
   1.2.3.4 xcc.example.com
   ```

### Change Docker IP range

This is only required if **your local network uses the `172.16.0.0/12` IP address range.** As xorlab uses the same IP range internally, this can lead to routing problems.

Follow these instructions to change the xorlab internal Docker network. This must be done for every xorlab VM (MTA and XCC).

1. To verify that xorlab actually uses 172.16.0.0/12 internally, you can execute `ip r` on the command line. The output usually looks like this:

   ```shell theme={null}
   ip r
   ...
   172.17.0.0/16 dev docker0 proto kernel scope link src 172.17.0.1 linkdown
   172.18.0.0/16 dev br-74362b0b174e proto kernel scope link src 172.18.0.1
   ...
   ```

2. Open the `daemon.json` file:

   ```shell daemon.json theme={null}
   sudo vi /etc/docker/daemon.json
   ```

3. Specify the new IP range that xorlab should use internally. You have to set a subnet for `bip` and a different one for `default-address-pools`. Make sure you don’t use those subnets in your network. More information can be found on the official Docker documentation: [Networking overview](https://docs.docker.com/network/) and [dockerd](https://docs.docker.com/engine/reference/commandline/dockerd/).

   ```json theme={null}
   {
   ...
     "bip": "10.200.0.1/24",
     "default-address-pools":[
       {"base":"10.201.0.0/16","size":24}
     ]
   }
   ```

4. To activate the changes, stop all running containers by executing `docker compose down` in the following directories:

   * MTA: `/etc/xorlab/activeguard`, and `/etc/xorlab/monitored_mta`
   * XCC: `/etc/xorlab/xcc`, `/etc/xorlab/auth`, `/etc/xorlab/elastic`, and `/etc/xorlab/monitoring`

5. Restart the Docker service with:

   ```shell theme={null}
   service docker restart
   ```

6. Recreate the existing networks by executing `docker network rm <network> && docker network create <network>` for the following `<network>`:

   * MTA: `activeguard.xor` and `monitored_mta.xor`. You can display existing networks with `docker network ls`.
   * XCC: `xcc.xor`, `auth.xor`, and `monitoring.xor`

7. Restart the VM:

   ```shell theme={null}
   sudo reboot
   ```

### Replace built-in certificates

This is only applicable if **you want to replace the pre-installed dummy certificates**.

These certificates allow for encryption of traffic but not for authentication. To install new TLS certificates, you have to:

1. Replace the dummy certificate files on both the XCC and MTAs in `/etc/xorlab/tls` with your certificate files in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format:
   1. [Replace MTA SMTP Certificate](/latest/tls-certificates-for-mta-smtp)
   2. [Replace MTA GUI Certificate](/latest/tls-certificates-for-mta-proxy)
   3. [Replace XCC Certificate](/latest/tls-certificates-for-xcc)

2. If certificates are used that are not signed by a generally trusted CA, i.e. self-issued / locally trusted certificates, you need to configure XCC and MTA VMs to trust all certificates:

   <Tabs>
     <Tab title="XCC">
       * `/etc/xorlab/<stack>/bootstrap.env` (`auth`, `monitoring` and `xcc` stacks)

         ```yaml {4} theme={null}
         ## xorlab bootstrap configuration
         (...)
         # If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
         configServiceProvider_ag_local={'serviceProvider': {'hosts': ['http://backend.xcc.xor:9080'], 'ssl': {'trustAll': True}}}
         ```

       * `/activeguard/core/active_guard.yml` (using [Expert Editor](/latest/expert-editor))

         ```yaml {6,7} theme={null}
         serviceProviders:
         (...)
           xcc:
             hosts:
               - https://xcc.example.com:9080
             ssl:
               trustAll: true
         ```

       * `/monitored_mta/promtail/config.yml` (using [Expert Editor](/latest/expert-editor))

         ```yaml {3,4} theme={null}
         clients:
           - url: https://xcc.example.com:3100/loki/api/v1/push
             tls_config:
               insecure_skip_verify: true
         ```

       * `/activeguard/mta/audit/audit.yml` (using [Expert Editor](/latest/expert-editor))

         ```yaml {6,7} theme={null}
         serviceProviders:
         (...)
           xcc:
             hosts:
               - https://xcc.example.com:9080
             ssl:
               trustAll: true
         ```
     </Tab>

     <Tab title="MTA">
       * `/etc/xorlab/<stack>/bootstrap.env` (`activeguard`, `monitored_mta`, `rproxy_mta` stacks)

         ```yaml {4} theme={null}
         ## xorlab bootstrap configuration
         (...)
         # If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
         configServiceProvider_ag_local={'serviceProvider': {'hosts': ['https://xcc.example.com:9080'], 'ssl': {'trustAll': True}}}
         ```
     </Tab>
   </Tabs>

3. Click **Publish** for the files edited in Expert Editor, then restart all containers on the XCC and MTAs to activate the changes. The `active_guard.yml`, audit, Promtail, and Grafana settings listed above include entries that require component restarts; see [How to Activate the Configuration](/latest/activate-configuration).

### Activate the firewall

This is only applicable if **you want to manage a host firewall on the xorlab hosts**.

By default, new MTA and XCC VMs have their firewalls disabled, although the necessary iptables config files are present. To enable the firewalls, for XCC and each MTA VM, execute the following command:

```shell theme={null}
sudo systemctl enable --now /etc/xorlab/firewall/iptables.service
```

## Post-installation checks

1. Log in to the xorlab MTA admin interface on port 8443.
2. Go to **Health Check** and confirm that the status is `RUNNING`.
3. Go to **Configuration → System Tests** and confirm that all System Tests are green.

## Further steps

1. When the VM setup is finished, proceed to configuring [monitoring tools](/latest/monitoring-guide).
2. Start integrating xorlab into your environment: [On-prem Integration](/latest/on-prem-integration-overview).


# VM Setup Script Description
Source: https://docs.xorlab.com/latest/vm-setup-script-breakdown

Every configuration value the setup script prompts for, for operators who need to understand or automate it.

This page is used as part of the [VM Setup Guide](/latest/vm-setup-guide) and is informational only — normally not required for a standard VM setup.

## Script coverage

In the tables below, you can find all configuration settings needed to set up the XCC and MTA VMs with their respective config files; if they are covered by the setup script, and whether the change is mandatory or optional. Each `Setting / topic` links to a detailed description of the configuration changes. If the step is covered by the setup script, it is not necessary to manually execute these steps again.

<Tabs>
  <Tab title="XCC">
    | Setting / topic | Config files | Setup Script | Mandatory |
    | :- | :- | :- | :- |
    | [Hostname](/latest/vm-setup-script-breakdown#hostname) | `GUI:/activeguard/core/active_guard.yml` `GUI:/activeguard/mta/audit/audit.yml` `GUI:/monitoring/grafana/grafana.ini` `GUI:/monitored_mta/promtail/config.yml.vmx.N` `/etc/xorlab/elastic/kibana/kibana.yml` | <Icon icon="check" /> | Yes |
    | [Bind IP](/latest/vm-setup-script-breakdown#bind-ip) | `/etc/xorlab/xcc/.env` | <Icon icon="check" /> | Yes |
    | [Proxy](/latest/vm-setup-script-breakdown#proxy-configuration) | `/etc/apt/apt.conf.d/proxy.conf` `/etc/systemd/system/docker.service.d/http-proxy.conf` `/etc/xorlab/xcc/backend/bootstrap.yml` `/etc/xorlab/auth/bootstrap.env` `/etc/xorlab/monitoring/bootstrap.env` `GUI:activeguard/core/active_guard.yml` | <Icon icon="check" /> | If proxies are used |
    | [EHLO](/latest/vm-setup-guide#ehlo-configuration) | `GUI:activeguard/mta/startup_cfg/postfix_custom/main.cf.vmx.N` | <Icon icon="xmark" /> | Yes |
    | [Network](/latest/vm-setup-guide#configure-the-network) | `/etc/netplan/00-xorlab-config.yaml` | <Icon icon="xmark" /> | If static IPs are used |
    | [Disk Resizing](/latest/vm-setup-guide#resize-the-disk) | | <Icon icon="xmark" /> | Yes |
    | [NTP servers](/latest/vm-setup-guide#set-local-ntp-servers) | `/etc/systemd/timesyncd.conf` | <Icon icon="xmark" /> | Optional |
    | [Resource Configuration](/latest/vm-setup-guide#configure-performance-resources) | `/etc/xorlab/xcc/backend/backend.env` `/etc/xorlab/xcc/backend/backend.env` `GUI:xcc/backend/xcc.yml` `/etc/xorlab/elastic/docker-compose.yml` `/etc/xorlab/xcc/.env` | <Icon icon="xmark" /> | Yes |
    | [Locally Trusted Certificates](/latest/vm-setup-guide#replace-built-in-certificates) | `/etc/xorlab/tls` `/etc/xorlab/xcc/backend/bootstrap.yml` `/activeguard/core/active_guard.yml` `/etc/xorlab/auth/bootstrap.env` `/etc/xorlab/monitoring/bootstrap.env` `/monitored_mta/promtail/config.yml` `/activeguard/mta/audit/audit.yml` | <Icon icon="xmark" /> | If locally trusted certificates are used |
    | [Firewall](/latest/vm-setup-guide#activate-the-firewall) | `/etc/xorlab/firewall/iptables.service` | <Icon icon="xmark" /> | Optional |
  </Tab>

  <Tab title="MTA">
    | Setting / topic | Config files | Setup Script | Mandatory |
    | :- | :- | :- | :- |
    | [Hostname](/latest/vm-setup-script-breakdown#hostname) | `/etc/xorlab/activeguard/.env` | <Icon icon="check" /> | Yes |
    | [Bind IP](/latest/vm-setup-script-breakdown#bind-ip) | `/etc/xorlab/activeguard/.env` `/etc/xorlab/rproxy_mta/.env` `/etc/xorlab/monitored_mta/.env` | <Icon icon="check" /> | Yes |
    | [XCC URL](/latest/vm-setup-script-breakdown#xcc-url) | `/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env` `/etc/xorlab/activeguard/.env` | <Icon icon="check" /> | Yes |
    | [Client ID](/latest/vm-setup-script-breakdown#client-id) | `/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env` | <Icon icon="check" /> | Yes |
    | [Proxy](/latest/vm-setup-script-breakdown#proxy-configuration) | `/etc/apt/apt.conf.d/proxy.conf` `/etc/systemd/system/docker.service.d/http-proxy.conf` `/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env` | <Icon icon="check" /> | If proxies are used |
    | [Network](/latest/vm-setup-guide#configure-the-network) | `/etc/netplan/00-xorlab-config.yaml` | <Icon icon="xmark" /> | If static IPs are used |
    | [Disk Resizing](/latest/vm-setup-guide#resize-the-disk) | | <Icon icon="xmark" /> | Yes |
    | [NTP servers](/latest/vm-setup-guide#set-local-ntp-servers) | `/etc/systemd/timesyncd.conf` | <Icon icon="xmark" /> | Optional |
    | [Resource Configuration](/latest/vm-setup-guide#configure-performance-resources) | `/etc/xorlab/activeguard/.env` `GUI:activeguard/mta/startup_cfg/postfix_custom/main.cf.vmx.N` | <Icon icon="xmark" /> | Yes |
    | [Locally Trusted Certificates](/latest/vm-setup-guide#replace-built-in-certificates) | `/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env` | <Icon icon="xmark" /> | If locally trusted certificates are used |
    | [Firewall](/latest/vm-setup-guide#activate-the-firewall) | `/etc/xorlab/firewall/iptables.service` | <Icon icon="xmark" /> | Optional |
  </Tab>
</Tabs>

## Using the script

The first run of the script is always interactive. You answer a series of questions, inputting desired values, which you can save in the config file. Subsequent runs can be non-interactive, provided you have made changes directly in the config file.

After setting the desired values, `xorlab-setup` offers to restart the services and Docker daemon. It then checks xorlab update and backend services. On MTA VMs, it also checks XCC reachability; on the XCC VM, it prompts for the MTA hostnames to check.

`xorlab-setup` supports these switches:

* `--help` prints the available switches and exits.
* `--restart-services` restarts the xorlab services without changing configuration.
* `--reachability-test` loads the saved `/etc/xorlab/bootstrap_config` when available and runs only the reachability checks.

Settings common to XCC and MTA that you can change:

* **hostname** - sets the hostname on the VM itself (via hostnamectl) and updates all relevant entries in xorlab configuration files.
* **bind IP** - the IP address of the interface to which xorlab stack components bind
* **proxy** - APT, Docker daemon, bootstrap, and `active_guard.yml` proxies. `PROXY_USER` and `PROXY_PASS` are optional settings

MTA specific settings:

* **client ID** - unique ID number of the MTA VM
* **XCC FQDN** - fully qualified domain name (or hostname) of the XCC VM

Script outputs basic information about the changes being made, and logs them in more detail to the `/var/log/xorlab/host/host_bootstrap.log`. In the file you can find commands with arguments that the script executes. It should be the first place to look whenever there are problems, or the script does not execute properly. To see the log file, open it with `less -R`, `more`, `tail`, or other program which interprets colors.

Config values entered by the user can be saved to a config file (`/etc/xorlab/bootstrap_config`), which also serves as a history of changes. The config generated on one MTA can then be copied to other MTAs, adjusted, and sourced by the script, without the need to give the same answers again.

Reachability test prompts are transient and answers are not stored in `/etc/xorlab/bootstrap_config`.
Enter optional internal service destinations as `host` or `host:port`. IPv6 literals are not supported; the script reports inputs containing more than one colon as invalid and skips the corresponding check.

<Accordion title="Example config file">
  ```bash theme={null}
  # [2026-02-26 14:41:14]
  XCC_BIND_IP=192.168.1.100
  XCC_HOSTNAME=new-xcc-hostname
  TEMPLATE_DOMAIN=mx.example.com
  MTA1_DOMAIN=mx1.example.com
  MTA2_DOMAIN=mx2.example.com
  SET_PROXY=y
  PROXY_TYPE=HTTP
  PROXY_HOST=proxyhost
  PROXY_PORT=9876
  PROXY_USER=proxyuser
  PROXY_PASS="proxypassword"
  ```
</Accordion>

<Accordion title="Logic of the setup script">
  The initial setup of the VM and xorlab is done by running `xorlab-setup`. This is a wrapper which will execute the following steps:

  * Determine whether it is run on a XCC or an MTA VM.
  * When started without arguments, optionally update the actual setup script `xorlab-set-up-[xcc|mta]`. If the update process fails, or the update is skipped, a preinstalled local version will be run.
  * When started with arguments such as `--help`, `--restart-services`, or `--reachability-test`, skip the update prompt and forward the arguments directly to the local role-specific script.
  * Execute `xorlab-set-up-xcc` or `xorlab-set-up-mta`, depending on the VM type.

  The following diagram depicts described logic:

  <img alt="Setup script logic" />

  The diagram is simplified. In current releases, the wrapper prompts for an update only when started without arguments. Argument-based invocations skip that prompt and call the local role-specific script directly.
</Accordion>

## Script breakdown

### Hostname

<Tabs>
  <Tab title="XCC">
    Connect to the XCC VM

    ```shell theme={null}
    ssh admin@xcc.example.com
    ```

    and set the new VM hostname.

    ```bash theme={null}
    sudo hostnamectl hostname new-xcc-hostname
    ```

    Open `/etc/xorlab/elastic/kibana/kibana.yml` config, and set the `server.publicBaseUrl`:

    ```yaml {3} theme={null}
    (...)
    # The public URL for end-users to access Kibana.
    server.publicBaseUrl: https://new-xcc-hostname/insights
    (...)
    ```

    Open the [Expert Editor](/latest/expert-editor), you will need to set new hostname value in these files:

    * `activeguard/mta/audit/audit.yml`

      ```yaml {6} theme={null}
      serviceProviders:
      xcc:
          # Service provider definition, see documentation of active_guard.yml for details. There is a maximum of 1 XCC host allowed.
          hosts:
          # REPLACE before Go-Live
          - https://new-xcc-hostname:9080
          ssl:
          trustAll: true
      ```

    * `monitoring/grafana/grafana.ini`

      ```yaml {1,9} theme={null}
      instance_name = new-xcc-hostname

      [paths]
      data = /var/lib/grafana
      logs = /var/log/grafana

      [server]
      protocol = http
      domain = new-xcc-hostname
      root_url = %(protocol)s://%(domain)s/monitoring/
      (...)
      ```

    * `monitored_mta/promtail/config.yml.vmx.N`

      ```bash {4} theme={null}
      (...)
      clients:
      # REPLACE before Go-Live
      - url: https://new-xcc-hostname:3100/loki/api/v1/push
          tls_config:
          insecure_skip_verify: true
      # - url: <OTHER-LOG-SINK>
      (...)
      ```

    * `activeguard/core/active_guard.yml`

      ```yaml {5} theme={null}
      (...)
      xcc:
        hosts:
          # REPLACE before Go-Live
          - https://new-xcc-hostname:9080
        ssl:
          trustAll: true
      (...)
      ```

    Deploy your changes by clicking the **Publish** button (1). In the pop-up window describe your changes (2), and press the **Publish** button (3) in the bottom right corner of the pop-up dialog. <img alt="Publish pop-up window" />
  </Tab>

  <Tab title="MTA">
    Connect to the MTA VM

    ```shell theme={null}
    ssh admin@mta1.example.com
    ```

    and set the new VM hostname.

    ```bash theme={null}
    sudo hostnamectl hostname new-mta1-hostname
    ```

    Open the `/etc/xorlab/activeguard/.env` file, set the `core_hostname` to the hostname

    ```shell {3} theme={null}
    (...)
    # CORE_SPAMD_MIN_CHILD=5
    core_hostname=new-mta1-hostname
    CORE_JVM_ARGS=-Xmx6g
    (...)
    ```

    and restart the activeguard stack.

    ```bash theme={null}
    cd /etc/xorlab/activeguard/ && docker compose down && docker compose up -d
    ```

    <Note>
      **Repeat the steps for each MTA VM.**
    </Note>
  </Tab>
</Tabs>

### Bind IP

<Tabs>
  <Tab title="XCC">
    Connect to the XCC VM:

    ```shell theme={null}
    ssh admin@xcc.example.com
    ```

    Enable browser access to the XCC web interface by opening the `/etc/xorlab/xcc/.env` file and changing the `XCCWEB_BIND_IP` variable to the IP that the XCC web interface should bind to:

    ```bash {2} theme={null}
    XOR_REGISTRY=registry.xorlab.com
    XCCWEB_BIND_IP=xxx.xxx.xxx.xxx
    (...)
    ```

    and restart the `xcc` stack.

    ```bash theme={null}
    cd /etc/xorlab/xcc && docker compose down && docker compose up -d
    ```
  </Tab>

  <Tab title="MTA">
    Connect to the MTA VM:

    ```shell theme={null}
    ssh admin@mta1.example.com
    ```

    Open the `/etc/xorlab/<STACK>/.env` file for each stack (`activeguard`,`rproxy_mta`,`monitored_mta`) and change the `BIND_IP` variable to the IP that the service should bind to:

    ```bash {2} theme={null}
    XOR_REGISTRY=registry.xorlab.com
    BIND_IP=xxx.xxx.xxx.xxx
    (...)
    ```

    and restart the stack.

    ```bash theme={null}
    cd /etc/xorlab/<STACK> && docker compose down && docker compose up -d
    ```

    <Note>
      **Repeat the steps for each MTA VM.**
    </Note>
  </Tab>
</Tabs>

### Template Domain

1. Open `/activeguard/core/active_guard.yml` in the [Expert Editor](/latest/expert-editor).
2. Set `templateDomain` to the domain that resolves via MX to all MTAs, as set in 2. step in [DNS registration](/latest/vm-setup-guide#register-required-dns-records).

```yaml active_guard.yml theme={null}
templateDomain: mx.example.com
```

3. Click **Publish**, then restart all MTAs. The `templateDomain` setting is in `active_guard.yml` and requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

### Trusted MTA Profiles

1. Open `/activeguard/core/active_guard.yml` in the [Expert Editor](/latest/expert-editor).

2. Insert all MTA Fully Qualified Domain Names (**A** records) registered in the 1. step in [DNS registration](/latest/vm-setup-guide#register-required-dns-records):

   ```yaml theme={null}
   trustedMTAProfiles:
   - name: default
     trusted:
       - hostNamePattern: mx1\.example\.com
       - hostNamePattern: mx2\.example\.com
   ```

3. Click **Publish**, then restart all MTAs. The `trustedMTAProfiles` setting is in `active_guard.yml` and requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

### Client ID

Connect to the MTA VM:

```shell theme={null}
ssh admin@mta1.example.com
```

Open the `/etc/xorlab/<STACK>/bootstrap.env` file for each stack (`activeguard`,`rproxy_mta`,`monitored_mta`) and change the `clientId` variable to the number of the MTA VM:

```bash {6} theme={null}
# xorlab bootstrap configuration
licenseId=EXAMPLE
licenseKey=REDACTED

## Set to the MTA host number, e.g. clientId=2 for the 2nd MTA, and so on...
clientId=1
(...)
```

and restart the stack.

```bash theme={null}
cd /etc/xorlab/<STACK> && docker compose down && docker compose up -d
```

<Note>
  **Repeat the steps for each MTA VM.**
</Note>

### XCC URL

Connect to the MTA VM:

```shell theme={null}
ssh admin@mta1.example.com
```

Open the `/etc/xorlab/activeguard/.env` file, and change the `redis_url` variable to the Fully Qualified Domain Name or the Hostname of the XCC VM.

```bash {3} theme={null}
(...)
# Set address of xcc VM (hosting redis) here, e.g. xcc.example.com
redis_url=new-xcc-hostname
```

Open the `/etc/xorlab/<STACK>/bootstrap.env` file for each stack (`activeguard`,`rproxy_mta`,`monitored_mta`) and change the Fully Qualified Domain Name or the Hostname of the XCC VM in the `configServiceProvider_ag_local` variable:

```bash {3} theme={null}
(...)
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['https://new-xcc-hostname:9080'], 'ssl': {'trustAll': True}}}
```

and restart the stack.

```bash theme={null}
cd /etc/xorlab/<STACK> && docker compose down && docker compose up -d
```

<Note>
  **Repeat the steps for each MTA VM.**
</Note>

### Proxy Configuration

If the xorlab can only connect to external servers through an HTTP proxy, you’ll need to execute the following steps:

* Enable APT to pull OS updates
* Enable the Docker daemon to pull new Docker images
* Configure the XCC and MTA containers
* Update `active_guard.yml` in the [Expert Editor](/latest/expert-editor) to enable SystemTests
* If integrated, configure the VirusTotal service

<Note>
  **Optional and mandatory proxy settings**

  **User** (`PROXY_USER`) and **password** (`PROXY_PASS`) are optional, whereas **type** (`PROXY_TYPE`), **port** (`PROXY_PORT`), and **host** (`PROXY_HOST`) are mandatory across all the config files.
</Note>

#### APT proxy

Connect to the XCC or MTA VM:

```shell theme={null}
ssh admin@xcc.example.com
```

Open the `/etc/apt/apt.conf.d/proxy.conf` file:

```shell theme={null}
vim /etc/apt/apt.conf.d/proxy.conf
```

uncomment the config, and provide your credentials to the proxy server:

```shell theme={null}
Acquire::http::Proxy "http://user:password@proxy.example.com:port/";
Acquire::https::Proxy "http://user:password@proxy.example.com:port/";
```

Save the file. Test the configuration by executing the following command and verifying that no connection error appears:

```shell theme={null}
sudo apt update && sudo apt upgrade
```

<Note>
  **Repeat the steps for each MTA VM.**
</Note>

#### Docker Daemon proxy

The proxy for the Docker daemon is set using environment variables using `systemd`. XCC and MTA VMs come with prepared, commented out proxy configuration in the `/etc/systemd/system/docker.service.d/http-proxy.conf`.

Connect to the XCC or MTA VM:

```shell theme={null}
ssh admin@xcc.example.com
```

Uncomment config lines and replace the exemplary proxy values.

```bash theme={null}
[Service]
Environment="HTTP_PROXY=http(s)://user:password@proxy.example.com:80"
Environment="HTTPS_PROXY=http(s)://user:password@proxy.example.com:443"
Environment="NO_PROXY=localhost,127.0.0.1/8,.xor"

# NOTE: Depending on your proxy configuration, the HTTPS_PROXY variable might also need to use http:// scheme.
```

Before proceeding, use `docker compose down` to shut down all running container stacks. Then reload the service configuration and restart the Docker service:

```bash theme={null}
sudo systemctl daemon-reload && sudo systemctl restart docker
```

```bash theme={null}
# Verify that the new environment settings were loaded:
sudo systemctl show docker --property Environment
```

<Note>
  **Repeat the steps for each MTA VM.**
</Note>

#### ServiceProvider proxy

Configure the proxy used by containers for most outgoing connections, including downloading the latest global configuration, in the bootstrap files (`bootstrap.yml` and `bootstrap.env`).

Connect to the XCC VM:

```shell theme={null}
ssh admin@xcc.example.com
```

Open the `bootstrap.env` file in your favorite editor for the `auth`, `monitoring` and `xcc` stacks:

```shell theme={null}
vim /etc/xorlab/<stack>/bootstrap.env
```

Uncomment `configServiceURL_ag_global` (line `12`), uncomment `configServiceProvider_ag_global` (line `11`) and add the value in the JSON format to use the corresponding proxy and xCloud:

```yaml {11,12} theme={null}
## xorlab bootstrap configuration
licenseId=EXAMPLE
licenseKey=REDACTED


# Where to find the ConfigurationService (URL(s) where to find the ConfigService)
# e.g. "https://xcc.example.com:9080"
# e.g. "https://xcc.example.com:9080,https://fallback.example.com:9080"
# If a proxy for external connections is used, remove configServiceURL_ag_global and use configServiceProvider_ag_global
# If the proxy uses TLS inspection and provides an untrusted certificate, set 'trustAll' to 'True'
configServiceProvider_ag_global={"serviceProvider":{"hosts": ['https://xcloud.ch1.activeguard.io', 'https://xcloud.ch2.activeguard.io', 'https://xcloud.ch3.activeguard.io'], "proxy": {'type': 'HTTP', 'host': 'proxy.example.com', 'port': 8080, 'user': 'proxy_user', 'password': 'proxy_password'}, 'ssl': {'trustAll': False}}}
# configServiceURL_ag_global=https://xcloud.ch1.activeguard.io,https://xcloud.ch2.activeguard.io,https://xcloud.ch3.activeguard.io
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['http://backend.xcc.xor:9080'], 'ssl': {'trustAll': True}}}
```

Restart container stacks:

```bash theme={null}
cd /etc/xorlab/<stack> && docker compose down && docker compose up -d
```

Connect to the MTA VM:

```shell theme={null}
ssh admin@mta1.example.com
```

Open the `bootstrap.env` file in your favorite editor for  the `activeguard`, `monitored_mta`, and `rproxy_mta` stacks:

```shell theme={null}
vim /etc/xorlab/<stack>/bootstrap.env
```

Uncomment `configServiceURL_ag_global` (line `12`), uncomment `configServiceProvider_ag_global` (line `11`) and add the value in the JSON format to use the corresponding proxy and xCloud:

```yaml {13,14} theme={null}
## xorlab bootstrap configuration
licenseId=EXAMPLE
licenseKey=REDACTED

## Set to the MTA host number, e.g. clientId=2 for the 2nd MTA, and so on...
clientId=1

# Where to find the ConfigurationService (URL(s) where to find the ConfigService)
# e.g. "https://xcc.example.com:9080"
# e.g. "https://xcc.example.com:9080,https://fallback.example.com:9080"
# If a proxy for external connections is used, remove configServiceURL_ag_global and use configServiceProvider_ag_global
# If the proxy uses TLS inspection and provides an untrusted certificate, set 'trustAll' to 'True'
configServiceProvider_ag_global={"serviceProvider":{"hosts": ['https://xcloud.ch1.activeguard.io', 'https://xcloud.ch2.activeguard.io', 'https://xcloud.ch3.activeguard.io'], "proxy": {'type': 'HTTP', 'host': 'proxy.example.com', 'port': 8080, 'user': 'proxy_user', 'password': 'proxy_password'}, 'ssl': {'trustAll': False}}}
# configServiceURL_ag_global=https://xcloud.ch1.activeguard.io,https://xcloud.ch2.activeguard.io,https://xcloud.ch3.activeguard.io
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['https://new-xcc-hostname:9080'], 'ssl': {'trustAll': True}}}
```

Restart container stacks:

```bash theme={null}
cd /etc/xorlab/<stack> && docker compose down && docker compose up -d
```

<Note>
  **Repeat the steps for each MTA VM.**
</Note>

#### xorlab Services and SystemTests

To enable connection to the xorlab backend services (DANA, xCloud, ML), open the [Expert Editor](/latest/expert-editor) and navigate to `/activeguard/core/active_guard.yml`. Here you can uncomment and set proxy values for each backend service.

```yaml {10-13,25-28,34-37,43-46,55-58,66-69} theme={null}
(...)
## xorlab services
serviceProviders:
  xcloud:
    hosts:
      - https://xcloud.ch1.activeguard.io
      - https://xcloud.ch2.activeguard.io
      - https://xcloud.ch3.activeguard.io
    retryRequestCount: 1
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  xcc:
    hosts:
      - https://new-xcc-hostname:9080
    ssl:
      trustAll: true

  dana1.ch:
    hosts:
      - https://dana.ch1.activeguard.io
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  dana2.ch:
    hosts:
      - https://dana.ch2.activeguard.io
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  dana3.ch:
    hosts:
      - https://dana.ch3.activeguard.io
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  tika:
    hosts:
      - https://tika.ch1.activeguard.io
      - https://tika.ch2.activeguard.io
      - https://tika.ch3.activeguard.io
    retryRequestCount: 1
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  ml:
    hosts:
      - https://ml1.ch.activeguard.io
      - https://ml2.ch.activeguard.io
    retryRequestCount: 1
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
(...)
```

There are two system tests that can use proxy: `ReachXorlabSystemTest` and `URLRedirectFollowerSystemTest`. In order to configure them, you need to insert the `httpProxy` block into `/activeguard/core/active_guard.yml`.

```yaml theme={null}
httpProxy:
  type: HTTP
  host: proxy.example.com
  port: 8080
  # user: proxy-user
  # password: proxy-password
```

Click **Publish**, then restart the `activeguard` stack on each MTA. These `active_guard.yml` service and proxy settings require an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).


# xorlab NLU
Source: https://docs.xorlab.com/latest/xorlab-nlu

The Natural Language Understanding service that classifies email content using xorlab's in-house machine learning models.

NLU stands for Natural Language Understanding. It classifies email into predefined topics, which you can search for and use in campaigns.

For on-premises, the service is disabled by default.

## Enable xorlab NLU for on-premises

1. Open the file `activeguard/core/active_guard.yml` in the Expert Editor.

2. Add a `mltopic` block to `serviceProviders`, and set the `hosts` to the same one as the existing `ml` service provider:

```yaml active_guard.yml theme={null}
serviceProviders:
  mltopic:
    hosts:
      - https://ml1.de.activeguard.io
      - https://ml2.de.activeguard.io

topicService:
  enabled: true
  serviceProviderName: mltopic
```

2. In the Expert Editor, click **Publish**, then restart all MTAs. The `serviceProviders` and `topicService` settings in `active_guard.yml` require an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

## Configuration options

As an on-prem user, you can define which types of email traffic should undergo topic detection.

To modify this behavior, adjust the following parameters in the `local.properties` file located at:
`activeguard/core/rule_sets/90_local/params/` in the Expert Editor.

Set each parameter to ACTIVE or DISABLED as needed:

```shell local.properties theme={null}
EXECUTE_TOPIC_CLASSIFICATION_for_analysis_pipelines_state
EXECUTE_TOPIC_CLASSIFICATION_for_incoming_emails_untrusted_state
EXECUTE_TOPIC_CLASSIFICATION_for_incoming_emails_extended_state
EXECUTE_TOPIC_CLASSIFICATION_for_reported_emails_state
```

After changing these rule properties, click **Publish**. They become active within about one minute and do not require a restart.

<Info>
  The shipped defaults — which traffic is classified after activation, and how to limit topic
  detection to untrusted senders only — are documented in
  [Detection Defaults → Topic classification](/latest/detection-defaults#topic-classification).
  Access to that page is restricted.
</Info>


# xorlab Sandbox (DANA)
Source: https://docs.xorlab.com/latest/xorlab-sandbox

Tuning options for the Sandbox. Self-hosted deployments only; in SaaS xorlab manages these settings.

<Note>
  The Sandbox appliance, its containers, and its configuration files are named **DANA**. This page uses *Sandbox* for the feature and *DANA* only where it refers to those.
</Note>

## Show screenshots for benign attachments

For benign verdicts, xorlab does not store and show the screenshots of the attachment.

If you want to change this behavior, follow [Change Storing of Attachment Previews](/latest/data-retention-previews#change-attachment-previews).

## Apply the Sandbox for quarantined emails

By default, the Sandbox is not applied if an email is put into quarantine already without a Sandbox scan.

If you want to change this behavior and force a Sandbox scan for all quarantined emails, apply the following:

1. Open the file `/activeguard/core/rule_sets/90_local/params/local.properties` in the Expert Editor.

2. Add the following properties:
   ```shell local.properties theme={null}
   DYNAMIC_ANALYSIS_default_mode=AlwaysInline
   DYNAMIC_ANALYSIS_always_for_office_with_vbascript_mode=AlwaysInline
   DYNAMIC_ANALYSIS_always_for_office_with_xlmscript_mode=AlwaysInline
   DYNAMIC_ANALYSIS_always_for_office_with_vbascript_trusted_mode=AlwaysInline
   DYNAMIC_ANALYSIS_always_for_office_with_xlmscript_trusted_mode=AlwaysInline
   DYNAMIC_ANALYSIS_exposed_accounts_mode=AlwaysInline
   DYNAMIC_ANALYSIS_exposed_high_value_targets_mode=AlwaysInline
   DYNAMIC_ANALYSIS_always_for_specific_recipients_mode=AlwaysInline
   ```

3. Click **Publish**. These rule-set settings become active within about one minute.

## Disable the Sandbox except for specific recipients

To apply the Sandbox *only* for specific recipients:

1. Open the file `shared/guarded_tenants.yml` in the Expert Editor.

2. Add the [Profile](/latest/rule-profiles) `no_dana_except_for_specific_recipients.properties`. Make sure to add it after `default_dana.properties`:
   ```yaml guarded_tenants.yml highlight={8} theme={null}
   tenants:
     - name: example
       ruleProfiles:
         - default_dana.properties
         - no_dana_except_for_specific_recipients.properties
         - ...
   ```

3. Add the specific recipients to the list `Recipient dynamic analysis (regex)` in the List editor.

4. Click **Publish**. The new configuration becomes active within about one minute.

## Disable the Sandbox completely

It is possible to disable the xorlab Sandbox completely:

1. Open the file `activeguard/core/active_guard.yml` in the Expert Editor.

2. Add the following lines:
   ```yaml active_guard.yml theme={null}
   dynamicAnalysisService:
     enabled: false
   ```

3. Click **Publish**, then restart all MTAs. The `dynamicAnalysisService` setting in `active_guard.yml` requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

## Default behavior

The Sandbox is applied to a defined set of document types, configured via the [Profile](/latest/rule-profiles) `default_dana.properties`.

The `*_mode` parameters can have the following values:

* `NoDynamicScan`— no scan
* `Inline`— wait with email delivery until the scan results are fully processed (if there was no quarantine decision before)
* `AlwaysInline`— same as `Inline`, but additionally forces a dynamic scan even if the email is already quarantined for other reasons
* `Offline`— force a scan but don’t wait for its result; decisions are based on static analysis only

More specific rules overrule the generic ones. This is implemented via `_weight` parameters, which accept integer values between 1 and 10 (inclusive). The higher the weight value, the higher the precedence.

<Info>
  The scanned file types and the delivered `*_mode` and `_weight` values are documented in
  [Detection Defaults → Sandbox](/latest/detection-defaults#sandbox).
  Access to that page is restricted.
</Info>


# xorlab Tika
Source: https://docs.xorlab.com/latest/xorlab-tika

The Tika service that improves URL and text extraction from attachments, including OCR.

Tika runs on the Sandbox appliance (DANA) if you have an on-premises Sandbox, otherwise the SaaS Tika service of xorlab will be used.

Tika is mandatory for detection, and is applied to the following emails:

* **Disabled by default**: outgoing
* **Active by default**: incoming, coming from internal and external servers, and reported by users

## Enable Tika for outgoing emails

1. Open `activeguard/core/rule_sets/90_local/params/local.properties` in the Expert Editor.

2. Add the following line:

   ```shell local.properties theme={null}
   EXECUTE_TEXT_EXTRACTION_for_outgoing_emails_state=ACTIVE
   ```

3. Click **Publish**. The rule-set setting becomes active within about one minute.

## Disable Tika

Tika should not be disabled in any production environment as it will severely impact classification accuracy. However, if needed, it can be disabled using the [Expert Editor](/latest/expert-editor). In the `activeguard/core/active_guard.yml` file, add the following lines:

```yaml active_guard.yml theme={null}
tikaService:
  enabled: false
```

Click **Publish**, then restart all MTAs. The `tikaService` setting in `active_guard.yml` requires an MTA restart; see [How to Activate the Configuration](/latest/activate-configuration).

## List of configuration parameters

Tika is controlled via the following rule properties:

```shell theme={null}
EXECUTE_TEXT_EXTRACTION_for_analysis_pipelines_state=ACTIVE
EXECUTE_TEXT_EXTRACTION_for_external_emails_state=ACTIVE
EXECUTE_TEXT_EXTRACTION_for_incoming_emails_state=ACTIVE
EXECUTE_TEXT_EXTRACTION_for_internal_emails_state=ACTIVE
EXECUTE_TEXT_EXTRACTION_for_reported_emails_state=ACTIVE
EXECUTE_TEXT_EXTRACTION_for_outgoing_emails_state=DISABLED
```

## Processed file formats

Tika extracts text and URLs from a defined set of file formats.

<Info>
  The full list of processed file formats is documented in
  [Detection Defaults → Tika processed file formats](/latest/detection-defaults#tika-processed-file-formats).
  Access to that page is restricted.
</Info>


# Privacy
Source: https://docs.xorlab.com/privacy

How this documentation site handles your data.

This notice covers the xorlab documentation site. For xorlab AG's products, services
and main website, see the [xorlab privacy policy](https://www.xorlab.com/en/privacy).

## No cookies, no consent banner

This site sets no cookies, which is why you are not asked for cookie consent here.
Nothing is stored on your device for analytics. The only item stored is whether the AI
assistant panel is open, which belongs to a feature you switch on yourself. The cookie
banner on [www.xorlab.com](http://www.xorlab.com) applies to that site only.

## What we measure

We use Matomo to understand which pages are read and what people search for, so that
we can improve the documentation. For each page you open, Matomo records:

* the address and title of the page, and the page you came from
* search terms you enter in the documentation search
* your browser, operating system and language
* your approximate location, derived from a shortened IP address

Because no identifier is stored on your device, Matomo groups requests into a single
visit using a short-lived value derived from your shortened IP address and your
browser. We do not assign you a user ID, we do not track you across other websites,
and we do not use this data for advertising.

Search terms are recorded as they are typed, so please do not enter personal data into
the search box.

## AI assistant

This site offers an AI assistant. When you use it, your question and the answer are
sent to Mintlify, the platform this documentation runs on. Mintlify generates the
answer using an AI model and stores the conversation, and we can read those
conversations in Mintlify's dashboard in order to find gaps in the documentation.

This is separate from the measurement described above. We have switched Mintlify's own
analytics off, but conversations with the assistant are stored by Mintlify regardless.
Using the assistant is voluntary, and the rest of the documentation works without it.

Please do not enter personal data or confidential information into the assistant.

## Who processes the data

* **Mintlify** (United States) hosts this site, runs the AI assistant, and, together
  with its infrastructure providers, processes your IP address in order to deliver the
  pages.
* **Matomo Cloud**, operated by InnoCraft Ltd (New Zealand), stores the analytics data
  on servers in Germany.

## Legal basis and retention

The controller is xorlab AG. We process the data described above on the basis of our
legitimate interest in understanding how our documentation is used and improving it
(Art. 6(1)(f) GDPR).

Analytics data is deleted after 24 months.

## Your right to object

Because this processing is based on our legitimate interest, you have the right to
object to it at any time (Art. 21 GDPR). If your browser sends a "Do Not Track"
signal, no data is collected and no objection on your part is required. You can also
object by contacting us at the address given in the
[xorlab privacy policy](https://www.xorlab.com/en/privacy).

## Your other rights

You have the right to access your data and to have it corrected or erased, and the
right to have its processing restricted. You can also lodge a complaint with a data
protection supervisory authority. For how to exercise these rights, and for our
contact details, see the [xorlab privacy policy](https://www.xorlab.com/en/privacy).