Logging - xorlab

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
Configuration examples

Other pages that relate to logging:

Setup Guide: Logging

Identify the event

Visit the Log Events page
Locate the event in the table
Take note of the event name and container

Locate the config file

Open the XSP Expert Editor
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/ - 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.

Do not publish incomplete logging configuration files!Incomplete logging configurations can lead to critical issues that could disrupt the XSP platform.

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
Enter an XML declaration on the first line of logback-audit.xml
Enter the XML root element <included> and </included>

<?xml version="1.0" encoding="UTF-8"?>

<included>

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

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

</included>

Configure the logger

Configure multiple logsYou 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.

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.

  <logger name="trace.mta.received">
  <appender-ref ref="Logging.Example"/>
  </logger>

Configure the appender

Visit the Appender page
Choose a type of appender
Copy/paste the configuration from an example
Update the appender name to match the appender-ref specified in the logging element

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

Visit the Log Formatting page
Choose your preferred formatting
Modify the <pattern> element as desired

<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

Check if the file path points to the correct directory
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 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 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 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 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>

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

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

How to log all SMTP logsIf 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.

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

xorlab Security Platform (SaaS)Writing to local files is not supported by XSP (SaaS) and can only be used for on-premises XSP installations.

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

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

​Setup Guide: Logging

​Identify the event

​Locate the config file

​Open or create logback-audit.xml

​Configure the logger

​Configure the appender

​Adjust the formatting

​Double check before publishing

​Configuration Examples

​Log to an External System

​Log detailed email results

​Log all XCC audit events

​Log SMTP email traces

​Log detailed email results per verdict

​Log threat intelligence

​Send logs via email

Setup Guide: Logging

Identify the event

Locate the config file

Open or create `logback-audit.xml`

Configure the logger

Configure the appender

Adjust the formatting

Double check before publishing

Configuration Examples

Log to an External System

Log detailed email results

Log all XCC audit events

Log SMTP email traces

Log detailed email results per verdict

Log threat intelligence

Send logs via email