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

# Logging

Logging is crucial for monitoring and maintaining the xorlab Security Platform (XSP). This page explores the core concepts of logging, outlines the configuration process, and presents real-world examples to guide your setup.

On this page you'll find:

* [Instructions for the configuration](#setup-guide-logging)
* [Configuration examples](#configuration-examples)

Other pages that relate to logging:

* [Deepdive into the concept behind logging](/9.0/logging-concept)
* [A complete list of logger events on XSP](/9.0/logging-events)
* [The different types of appender types](/9.0/logging-appenders)
* [How to customize the formatting of logs](/9.0/logging-formats)
* [Insights into the built-in logging configuration](/9.0/logging-configuration-files)

## Setup Guide: Logging

### Identify the event

1. Visit the [Log Events](/9.0/logging-events) page
2. Locate the event in the table
3. Take note of the `event name` and `container`

### Locate the config file

1. Open the [XSP Expert Editor](/9.0/expert-editor)
2. Based on the table below, navigate to the right directory

| Container | Directory                                                              |
| :-------- | :--------------------------------------------------------------------- |
| Core      | **activeguard/core/**                                                  |
| Mta       | **activeguard/mta/audit/**                                             |
| Backend   | **xcc/backend/**                                                       |
| Auth      | **auth/auth/**                                                         |
| Dana      | **/etc/xorlab/dana/default/** <br /> *- Modify configurations via ssh* |

### Open or create `logback-audit.xml`

Open either the existing `logback-audit.xml` configuration file or create a new file based on the instructions below.

<Tip>
  **Do not publish incomplete logging configuration files!**

  Incomplete logging configurations can lead to critical issues that could disrupt the XSP platform.
</Tip>

1. Create a new file via the Expert Editor
   * Hover over the parent directory icon
   * Click on the 3 dots
   * Select `New File`
   * Name the file `logback-audit.xml`

2. Enter an XML declaration on the first line of `logback-audit.xml`

3. Enter the XML root element `<included>` and `</included>`

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>

 <!-- add <appender> elements on top -->

 <!-- add <logger> elements below -->

</included>
```

### Configure the logger

<Tip>
  **Configure multiple logs**

  You can define various `<appender>` elements in `logback-audit.xml` to generate multiple logs in different locations. It's best practice to group `<logger>` elements together, as they can be referenced by multiple appenders simultaneously.
</Tip>

1. Modify the `<logger>` element:

* Set the event name: Use the name attribute to specify the log event.
* Link to the appender: Choose any name to connect the logger to the appender.

```xml theme={null}
  <logger name="trace.mta.received">
  <appender-ref ref="Logging.Example"/>
  </logger>
```

### Configure the appender

1. Visit the [Appender](/9.0/logging-appenders) page
2. Choose a type of appender
3. Copy/paste the configuration from an example
4. Update the `appender name` to match the `appender-ref` specified in the logging element

```xml theme={null}
<appender name="Logging.Example" class="ch.qos.logback.core.FileAppender">
  <file>${log_dir}/logging_example.log</file>
  <append>true</append>
  <encoder>
    <pattern>%jsonMsg%n</pattern>
  </encoder>
</appender>
```

### Adjust the formatting

You can customize log entries by adjusting the format for timestamps, log levels, messages, and other details.

1. Visit the [Log Formatting](/9.0/logging-formats) page
2. Choose your preferred formatting
3. Modify the `<pattern>` element as desired

```xml theme={null}
<appender name="loggingExampleAppender" class="ch.qos.logback.core.FileAppender">
  <file>${log_dir}/logging_example.log</file>
  <append>true</append>
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss} - %msg%n</pattern>
  </encoder>
</appender>
```

### Double check before publishing

1. Check if the file path points to the correct directory
2. Make sure that `logback-audit.xml` contains:
   * An XML declaration on the first line
   * `<included>` as the first element
   * `</included>` as the last element
   * `<logger>` element that ends with `</logger>`
   * `<appender>` element that ends with `</appender>`
   * `<appender name =" ">` matches `<appender-ref ref=" ">`

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>
 
 <!-- insert <appender> element (step 4) -->
  <appender name="exampleFileAppender" class="ch.qos.logback.core.FileAppender">
    <file>${log_dir}/logging_example.log</file>
    <append>true</append>
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss} - %msg%n</pattern>
    </encoder>
  </appender>
  
 <!-- insert <logger> element (step 3) -->
  <logger name="trace.mta.received">
     <appender-ref ref="exampleFileAppender"/>
  </logger>

</included>
```

## Configuration Examples

### Log to an External System

Log event-specific attributes in JSON format to an external system whenever a user archives a campaign.

* Event: `audit.user.campaign.archived`
* Container: `XCC backend`
* File Path: `xcc/backend/logback-audit.xml`
* Appender: `Log as syslog`
* Formatting: `%jsonMsg%n`

**File Path: xcc/backend/logback-audit.xml**

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>
 
  <appender name="exampleSyslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>siem.example.com</syslogHost>
    <port>514</port>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>
 
      <!-- Event: Message Analysis Completed -->

  <logger name="trace.msg_analysis.complete">
     <appender-ref ref="exampleSyslogAppender"/>
  </logger>
 
</included>
```

### Log detailed email results

Records the complete result of the email analysis in JSON format to a remote syslog server:

* Event: `trace.msg_analysis.complete`
* Container: `MTA core`
* File Path: `activeguard/core/logback-audit.xml`
* Appender: `Log as syslog` to a remote host.
* Formatting: `%coreJsonMsg%n`

**File Path: activeguard/core/logback-audit.xml**

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>
 
  <appender name="Example_JSONtoRemote" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>siem.example.com</syslogHost>
    <port>514</port>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>
 
      <!-- Event: Message Analysis Completed -->

  <logger name="trace.msg_analysis.complete">
     <appender-ref ref="Example_JSONtoRemote"/>
  </logger>
 
</included>
```

### Log all XCC audit events

Send event-specific attributes in JSON format to a remote syslog server each time an audit event occurs on xorlab's user interface (XCC):

* Event: `audit` (includes sub-categories)
* Container: `XCC backend`
* File path: `xcc/backend/logback-audit.xml`
* Appender: `Log as syslog`
* Formatting: `%jsonMsg%n`

**File Path: xcc/backend/logback-audit.xml**

```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 xcc user audit events -->
  <logger name="audit">
    <appender-ref ref="syslogAppender"/>
  </logger>
</included>
```

<Tip>
  In order to also log **successful and failed logins**, configure `auth/auth/logback-audit.xml` as well with the same parameters as above.
</Tip>

### Log SMTP email traces

Send a JSON message when an email has been accepted through SMTP and another when a delivery attempt has been made.

* Events: `trace.mta.received`, `trace.mta.send`
* Container: `Mta`
* File path: `activeguard/mta/audit/logback-audit.xml`
* Appender: `syslogAppender`
* Format: `%jsonMsg%n`

**File Path: activeguard/mta/audit/logback-audit.xml**

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

  If you want to log the complete SMTP log and not only the send and receive events, then replace the name of the first logger with `trace.mta` and remove the second logger completely.
</Tip>

If you want to correlate the SMPT queue ID from the two events above with the GGRID, you can additionally activate the following log event.

* Event: `trace.msg_delivered`
* Container: `Core`
* File path: `activeguard/core/logback-audit.xml`
* Appender: `syslogAppender`
* Format: `%jsonMsg%n`

**File Path: activeguard/core/logback-audit.xml**

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

The following configuration ensures that a JSON message is sent each time a verdict is made on an email. This setup is particularly useful in scenarios where:

* An email initially appears legitimate and is delivered to the user, but
* A delayed or offline dynamic analysis later updates the verdict from benign to malicious.

In such cases, the configuration below would generate two separate JSON messages for the same email—one for each verdict, reflecting the change in status.

* Event: `trace.msg_verdict`
* Container: `Core`
* File path: `activeguard/core/logback-audit.xml`
* Appender: `syslogAppender`
* Format: `%coreJsonMsg%n`

**File Path: activeguard/core/logback-audit.xml**

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

The following configuration will write one JSON message for every domain threat intelligence event into a local file and also logs the event over syslog:

* Event: `ti.domain`
* Container: `Backend`
* File path: `xcc/backend/logback-audit.xml`
* Appenders: `syslogAppender`, `RollingFileAppender`
* Format: `%jsonMsg%n`

<Tip>
  **xorlab Security Platform (SaaS)**

  Writing to local files is not supported by XSP (SaaS) and can only be used for on-premises XSP installations.
</Tip>

**File Path: `xcc/backend/logback-audit.xml`**

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

### Send  logs via email

The Email appender sends log events via email. This is particularly useful for critical alerts that require immediate attention. It’s configured to send emails when certain log events are triggered. In the example below, an email containing a summary of the analysis is sent to `example@xorlab` whenever someone reports an email.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>

<included>
  
    <!-- TODO: update property.value with your xorlab url -->
  <property name="host.name" value="example.activeguard.ch"/>
  
  <appender name="smtpMailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
      <!-- TODO: update <to> attribute with the email address of the receiver-->
    <to>example@xorlab.com</to>
          
        <from>no-reply@${host.name}</from>
        <subject>Email reported via ${host.name}</subject>

        <layout class="ch.qos.logback.classic.PatternLayout">
            <!-- feel free to fiddle around here --> 
        <pattern>An email was reported\nDate: %d{yyyy-MM-dd HH:mm}\nLink https://${host.name}/messages/all/message/%X{gr.id} \nSoftware Version: %versionGitDescription\n%jsonMsg\n</pattern>
        </layout>
          
        <smtpHost>mta.activeguard.xor</smtpHost>
        <smtpPort>10026</smtpPort>
        <evaluator class="com.xorlab.sgappliance.shared.logback.evaluator.LevelEvaluator"/>
    </appender>

      <logger name="trace.msg_analysis.complete.reported">
        <appender-ref ref="smtpMailAppender"/>
    </logger>
    
</included>
```