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

# Inline and Monitoring Mode

xorlab Security Platform can run in either of the following modes:

* **Monitoring**: xorlab Security Platform is located out-of-band of the email 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 Security Platform is inline in the email flow and actively filters emails. This mode is configured whenever XSP is used for inbound email security. Emails are forwarded after they have been processed.

By default, XSP runs in inline mode. Have a look at the sections below if you want to configure either of the modes. After you finish configuring, please set up SMTP properly as described in [Email routing](/9.0/smtp-configuration#email-routing).

## Monitoring mode

The following changes are necessary to run xorlab Security Platform in monitoring mode:

1. Open [Expert Editor](/9.0/expert-editor) and navigate to the `activeguard/core/active_guard.yml` file.

2. Under `scanSources.handler`, add the `smtpOffline {}` entry to the list and remove any existing entries named `smtpInline {}`.

3. Under `pipelineTypeConfig`, set `recipientRetrievalStrategy: MAIL_HEADER` and `envelopeFromRetrievalStrategy: HEADER`:

   <Warning>
     For M365 integrations, the value for the `envelopeFromRetrievalStrategy` key should be `ENVELOPE_FROM`.
   </Warning>

   ```yaml theme={null}
   pipelineTypeConfig:
     emails:
       # Get the recipients from the TO and CC headers
       recipientRetrievalStrategy: MAIL_HEADER
       # Get the envelope `FROM` from email headers
       envelopeFromRetrievalStrategy: HEADER # (1)!
   ...
   scanSources:
   - smtp
     port: 10025
     handler:
     - smtpReport {}
     # The following line activates monitoring mode.
     # All emails will be dropped after processing.
     - smtpOffline {}
   ```

   1. `ENVELOPE_FROM` in M365 integrations

4. Under `rules.params`, add the `monitoring_mode.properties` entry as described in [*Profiles*](/9.0/actions-rules-and-profiles#monitoring-mode) and change any DANA profile to `monitoring_dana_offline_only.properties`:
   ```yaml theme={null}
   rules:
     params:
     - default.properties
     - monitoring_dana_offline_only.properties
     - monitoring_mode.properties
     - local.properties
     - ui.properties
   ```

5. Set up SMTP properly as described in [*Email routing*](/9.0/smtp-configuration#monitoring-mode).

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

7. Restart MTAs. For all MTAs, SSH connect to the MTA and execute:

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

This configuration sets xorlab Security Platform into monitoring mode. For more information about the envelope `FROM` and recipient configuration, please see the [next section](#envelope-from-and-recipient-configuration).

It is possible to omit the `handler` block as it is set to `smtpOffline {}` by default:

```yaml 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, XSP tries to parse the envelope `FROM` from any `Received`, `Received-spf`, and `Return-path` headers present in the email. Further possibilities are described in the next chapter.
</Warning>

### Envelope `FROM` and recipient configuration

In monitoring mode, emails are often forwarded as copies (BCC) to xorlab Security Platform. 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 XSP itself like, for example, `emails@activeguard.internal` when the email arrives at xorlab Security Platform. Therefore, you need to configure XSP to get the envelope `FROM` and recipients from the correct location:

```yaml theme={null}
pipelineTypeConfig:
  emails:
    recipientRetrievalStrategy: MAIL_HEADER
    envelopeFromRetrievalStrategy: HEADER # (1)!
```

1. `ENVELOPE_FROM` in M365 integrations

<Warning>
  For M365 integrations, the value for the `envelopeFromRetrievalStrategy` key in `pipelineTypeConfig.emails` should be `ENVELOPE_FROM`.
</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 xorlab Control Center (XCC). Consequently, XSP cannot do various checks like, for example, SPF verification.
</Note>

The following values are supported for `envelopeFromRetrievalStrategy`:

| Value              | Description                                                                                                                                                                                              |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HEADER` (default) | Try to get the original envelope `FROM` by parsing the following headers:<br />- `Received`<br />- `Received-spf`<br />- `Return-path`<br />- A custom header specified through `envelopeFromHeaderName` |
| `ENVELOPE_FROM`    | Take the envelope `FROM` from the SMTP `MAIL FROM` command                                                                                                                                               |

The following values are supported for `recipientRetrievalStrategy`:

| Value                   | Description                                         |
| :---------------------- | :-------------------------------------------------- |
| `MAIL_HEADER` (default) | Use the `TO` and `CC` headers to get all recipients |
| `MAIL_ENVELOPE`         | Take the recipients from the SMTP `RCPT TO` command |

You can also provide the original envelope `FROM` in a custom header. This header can then be specified in the following way:

```yaml theme={null}
pipelineTypeConfig:
  emails:
    recipientRetrievalStrategy: MAIL_HEADER
    envelopeFromRetrievalStrategy: HEADER
    # Specify a custom header that contains the original envelope `FROM`
    envelopeFromHeaderName: "x-original-envelope-from"
```

It’s also possible to use regex to provide the original envelope `FROM` when you have multiple custom headers to check—just enter these headers without double quotes in a regular expression as the value for the `envelopeFromHeaderName` key:

```yaml theme={null}
    envelopeFromHeaderName: 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.
   ```
   ## ActiveGuard bcc deployment specific settings
   # Disable Delivery Status Notification (DSN) for bcc deployments
   smtpd_discard_ehlo_keywords = silent-discard, dsn
   ```

## 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](/9.0/expert-editor) and navigate to the `activeguard/core/active_guard.yml` file.
2. Under `scanSources.handler`, add the `smtpInline {}` entry to the list and remove any existing entries named `smtpOffline {}`.
3. Under `pipelineTypeConfig`, set `envelopeFromRetrievalStrategy: ENVELOPE_FROM` and `recipientRetrievalStrategy: MAIL_ENVELOPE`:
   ```yaml theme={null}
   pipelineTypeConfig:
     emails:
       # Get the recipients from the SMTP connection (RCPT TO command)
       recipientRetrievalStrategy: MAIL_ENVELOPE
       # Get the envelope `FROM` from the SMTP connection (MAIL FROM command)
       envelopeFromRetrievalStrategy: ENVELOPE_FROM
   ...
   scanSources:
   - smtp
     port: 10025
     handler:
     - smtpReport {}
     # The following line activates the inline mode.
     - smtpInline {}
   ```
4. Under `rules.params`, add the `default_actions.properties` entry as described in [*Profiles*](/9.0/actions-rules-and-profiles#standard) and change any Sandbox profile to `default_dana.properties`:
   ```yaml theme={null}
   rules:
     params:
     - default.properties
     - default_dana.properties
     - default_actions.properties
     - local.properties
     - ui.properties
   ```
5. 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
   ```
6. 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
   ```
7. Set up SMTP properly as described in [*Email routing*](/9.0/smtp-configuration#email-routing).
8. Make sure to `Publish` the configuration changes in the Expert Editor.
9. Restart MTAs. For all MTAs, SSH connect to the MTA and execute:

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