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

# Switch Between Inline and Monitoring Mode

> Switch between monitoring mode, which observes a copy out of band, and inline mode, which can block and quarantine.

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 actively intervene). Usually, it receives the email traffic as an additional BCC recipient and all emails are dropped after processing. This mode allows email traffic Monitoring with low impact on the infrastructure.
* **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 [Configure for on-premises](/latest/on-prem-smtp#configure-for-monitoring) or [Configure for M365](/latest/m365-smtp).

4. [Disable delivery status notifications](/latest/inline-and-monitoring-mode#disable-delivery-status-notifications-eg-bounce-messages).

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>

<Warning>
  For M365 integrations, the value for `senderRecipientExtraction.senderExtraction` should be `MAIL_ENVELOPE`.
</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 (e.g., bounce messages)

For Monitoring mode, we recommend to generally disable delivery status notifications. This will make sure that xorlab Security Platform 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.

## 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 [Configure for on-premises](/latest/on-prem-smtp) or [Configure for M365](/latest/m365-smtp).
6. Click **Publish**. The inline mode configuration becomes active within about one minute.