> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.
# Trusted MTAs In-Depth
> 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.
*Received headers of an incoming email where xorlab Security Platform is integrated with M365.*
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.
### 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`.
**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.
#### 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:
## 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).