Loggers - xorlab

Remember to Configure the AppenderIn order to write logs, the logger element must be paired with at least one appender element.

Configuration

Name

The name attribute in a logger specifies the unique identifier for an event on xorlab. It defines the scope and position of the event within the logging hierarchy, allowing precise control over logging behavior. Logger names follow a hierarchical structure, with each part of the name separated by dots, similar to a family tree. It is possible to only specify a prefix of an event as name. This will then log all events that start with this prefix. For example, name="sys" will log all sys events. Note that the only prefixes that are allowed are the ones derived from splitting the event name with a dot.

ROOT
 +- sys ->[customAppender1]
    - startup
    - restart
    - ready
    - ...
    - config
      + - ...

In this case, the logger named sys is the parent of sys.startup, sys.restart, sys.ready, and so on. All log events with names starting with sys are handled by the sys logger and its appenders, unless a more specific logger (like sys.startup) exists. It is also possible to specify only a prefix in the logger name to capture all events that start with that prefix. For example, setting name="sys" will log all sys events. Note that the only prefixes that are allowed are the ones derived from splitting the event name with a dot.

Severity

The severity attribute indicates the importance of a log event, with values ranging from 0-3 for low importance, 4-6 for medium, 7-8 for high, and 9-10 for very high importance. This helps prioritize monitoring and alerts, ensuring that the most critical issues are addressed quickly while still maintaining visibility over less urgent events.

Component

After identifying the log event you want to capture, refer to the Components column for the configuration file path. Configuration files are spread across directories because each xorlab component operates independently, requiring separate logging setups.

Component	Container	Directory
MTA	Core	activeguard/core/
MTA	Mta	activeguard/mta/audit/
XCC	Backend	xcc/backend/
XCC	Auth	auth/auth/
Sandbox	Dana	/etc/xorlab/dana/default/ - Modify configurations via ssh

System Events

System events, numbered from 0 to 999, cover basic system functions like startup, shutdown, and configuration changes.

ID	Event Name	Severity	Description	Components
1	`sys.startup`	0	Startup sequence for system component initiated	`Core`, `Mta`, `Backend`, `Auth`, `Dana`
2	`sys.ready`	0	System component started up successfully and is ready for operation	`Core`, `Mta`, `Backend`, `Auth`, `Dana`
3	`sys.restart`	0	System component is being restarted	`Core`
4	`sys.shutdown.triggered`	4	System component initiated shutdown process	`Core`, `Mta`, `Backend`, `Auth`, `Dana`
5	`sys.shutdown`	4	System component completed shutdown process	`Core`, `Mta`, `Backend`, `Auth`, `Dana`
10	`sys.config.reloaded`	0	System component successfully reloaded configuration	`Core`, `Mta`, `Backend`, `Auth`
11	`sys.config.downloaded`	0	System component downloaded configuration	`Core`, `Mta`, `Backend`, `Auth`
12	`sys.config.migrated`	4	Configuration repository migrated to a new system version	`Core`, `Mta`, `Backend`, `Auth`
13	`sys.config.commit`	4	Revised system configuration committed to the repository	`Core`, `Mta`, `Backend`, `Auth`
20	`sys.backup.started`	7	The backup service started creating a backup	`Backend`
21	`sys.backup.resumed`	7	The backup service found an incomplete backup and is resuming it	`Backend`
28	`sys.backup.failed`	10	The backup service failed to create a backup	`Backend`
29	`sys.backup.completed`	7	The backup service successfully created a new backup	`Backend`
30	`sys.recovery.started`	10	The recovery service started the recovery process	`Backend`
38	`sys.recovery.failed`	10	The recovery service finished recovery with errors	`Backend`
39	`sys.recovery.completed`	10	The recovery service completed the recovery process	`Backend`
43	`sys.synchronizing.progress`	0	XCC data synchronization in progress	`Backend`
44	`sys.dynamic_rule_list.update`	0	Dynamic rule lists have been updated.	`Core`
99	`sys.admin.other`	7	Other administrative action affecting the system	`Core`

Message-tracing events

Message-tracing events, numbered from 1000 to 1999, track the flow of emails and messages through the system.

ID	Event Name	Severity	Description	Components
1000	`trace.mta.received`	3	xorlab accepted an email (SMTP status code 2xx if successful)	`Mta`
1001	`trace.mta.send`	3	xorlab relayed an email (SMTP status code 2xx if successful). Use in combination with trace.msg_delivered to correlate queue ID and GGRID	`Mta`
1007	`trace.msg_analysis.mail_import_command_queue_insert`	0	Mail import command queued	`Backend`
1008	`trace.msg_analysis.receiving`	0	Email analysis engine of xorlab received an email	`Core`
1009	`trace.msg_analysis.received`	0	Email analysis engine of xorlab accepted/rejected an email	`Core`
1010	`trace.msg_analysis.start`	0	Message analysis started	`Core`
1100	`trace.dynamic_analysis.request`	0	xorlab Core requested a Sandbox scan for one of the attached files	`Core`
1120	`trace.dynamic_analysis.queued`	0	Sandbox request queued	`Dana`
1129	`trace.dynamic_analysis.complete`	0	Sandbox request completed	`Dana`
1130	`trace.dynamic_analysis.cleanup`	0	Sandbox result removed	`Dana`
1140	`trace.dynamic_scan.start`	0	Sandbox spun up a VM for the in-depth analysis of a file	`Dana`
1141	`trace.dynamic_scan.retry`	4	Failed Sandbox scan retries an analysis step on a specific VM	`Dana`
1149	`trace.dynamic_scan.complete`	0	Sandbox completed an analysis step on a specific VM	`Dana`
1199	`trace.dynamic_analysis.response`	0	Sandbox file analysis completed	`Core`
1300	`trace.msg_verdict`	0	xorlab decided the message verdict. This event will be logged twice for emails with attachments for which a Sandbox scan was performed out-of-band	`Core`
1301	`trace.msg_analysis.complete`	0	Message analysis finalized Notes: 1. Logged once per email 2. Decision code is appended to the key	`Core`
1400	`trace.msg_released`	0	Message released from quarantine Note: Does not support email results extensions (`logging-formats.md#message-tracing`)	`Core`
1402	`trace.msg_delivered`	0	xorlab Core delivered an email to the Mta Note: Contains SMTP queue ID for correlation with `trace.mta.send`	`Core`
1403	`trace.msg_delivered_internal`	0	A mail was delivered by relaying it internally to its destination tenant	`Core`
1410	`trace.msg_notification`	0	A notification mail was sent	`Core`
1411	`trace.delivery_status.delivered`	0	A message was put into the delivered state for a specific recipient	`Backend`
1412	`trace.delivery_status.removed`	0	A message was not delivered to a specific recipient and was removed from the queue	`Backend`
1900	`trace.msg_analysis.error`	3	xorlab encountered an error during message analysis	`Core`
1901	`trace.msg_analysis.resume`	0	xorlab has resumed message analysis (after being interrupted, e.g., because of an outage)	`Core`
1950	`trace.mail_import.indexing.start`	0	Mail import indexing phase started	`Backend`
1951	`trace.mail_import.indexing.complete`	0	Mail import indexing phase completed	`Backend`
1952	`trace.mail_import.importing.start`	0	Mail import importing phase started	`Backend`
1953	`trace.mail_import.importing.complete`	0	Mail import importing phase completed	`Backend`
1954	`trace.mail_import.complete`	0	Mail import job completed successfully	`Backend`

Audit trail events

Audit events, numbered from 2000 to 2999, capture user interactions and administrative actions within the XCC web interface.

ID	Event Name	Severity	Description	Components
2000	`audit.access.granted`	4	User authentication succeeded	`Auth`
2001	`audit.access.denied`	6	User authentication failed	`Auth`
2002	`audit.access.mfa_required`	0	Authentication requires an additional MFA factor	`Auth`
2003	`audit.access.mfa_totp_secret_updated`	0	TOTP secret updated through onboarding	`Backend`
2010	`audit.user.msg_list`	4	User viewed message list information	`Backend`
2011	`audit.user.msg_details`	4	User viewed message details	`Backend`
2012	`audit.user.msg_download`	6	User downloaded an email-related asset	`Backend`
2099	`audit.user.msg_delete`	7	User deleted a message	`Backend`
2100	`audit.user.quarantine_release`	6	User released a quarantined message	`Backend`
2103	`audit.user.incident.resolved.verdict`	7	User resolved a reported incident with a verdict	`Backend`
2104	`audit.user.incident.comment`	4	User added a comment to a reported incident	`Backend`
2130	`audit.isolate.removed`	7	Analyst triggered the eviction of an email out of a recipient’s inbox	`Backend`
2140	`audit.quarantine.release.request.created`	6	User created a quarantine release request	`Backend`
2141	`audit.quarantine.release.request.approved`	6	Quarantine release request approved	`Backend`
2142	`audit.quarantine.release.request.denied`	6	Quarantine release request denied	`Backend`
2150	`audit.quarantine.archive`	3	User archived a quarantined message	`Backend`
2200	`audit.user.dynamic_analysis`	4	User requested a Sandbox scan for a file	`Backend`
2300	`audit.user.lists.item_added`	7	User added an item to a rule list	`Core`, `Backend`
2301	`audit.user.lists.item_removed`	7	User removed an item from a rule list	`Core`, `Backend`
2302	`audit.user.lists.item_replaced`	7	User replaced an item in a rule list	`Core`, `Backend`
2399	`audit.user.config.file_modified`	7	User modified system configuration	`Backend`
2400	`audit.user.data_export`	4	User exported data from a saved campaign, query, or metadata (result.json)	`Backend`
2410	`audit.user.misclassification.submitted`	5	User submitted a misclassification to xCloud	`Backend`
2420	`audit.user.incident.reanalyze`	5	User reanalyzed a message	`Backend`
2500	`audit.user.search.added`	0	User created a saved search	`Backend`
2501	`audit.user.search.removed`	0	User deleted a saved search	`Backend`
2502	`audit.user.search.updated`	0	User updated a saved search or its display text	`Backend`
2600	`audit.user.campaign.added`	6	User created a campaign	`Backend`
2601	`audit.user.campaign.removed`	6	User deleted a campaign	`Backend`
2602	`audit.user.campaign.updated`	6	User updated a campaign query, display text, or action	`Backend`
2603	`audit.user.campaign.archived`	6	User archived a campaign	`Backend`
2700	`audit.user.tag.added`	0	User manually added a tag to one or more messages	`Backend`
2702	`audit.user.tag.removed`	0	User manually removed a tag from one or more messages	`Backend`
2800	`audit.user.backup.triggered`	7	User manually triggered a backup	`Backend`
2850	`audit.user.mail_import.job.created`	4	User created a mail import job	`Backend`
2851	`audit.user.mail_import.job.paused`	4	User paused a mail import job	`Backend`
2852	`audit.user.mail_import.job.resumed`	4	User resumed a mail import job	`Backend`
2853	`audit.user.mail_import.job.cancelled`	4	User cancelled a mail import job	`Backend`
2900	`audit.quarantine.digest.enqueued`	0	Quarantine digest notifications enqueued in the MTA command queue	`Backend`

Result publication tracing events

Result publication tracing events, numbered from 3000 to 3999, capture result synchronization and publication flow.

ID	Event Name	Severity	Description	Components
3000	`trace.res_pub.received`	0	Result publication received by XCC	`Backend`

Threat analysis events

Threat analysis events, numbered from 4000 to 4999, record details about detected threats and threat intelligence attributes.

ID	Event Name	Severity	Description	Components
4000	`ti.email`	7	Threat intel entry for malicious sender email address	`Backend`
4001	`ti.ip`	7	Threat intel entry for malicious sending MTA IP address	`Backend`
4002	`ti.file`	7	Threat intel entry for malicious attachment	`Backend`
4003	`ti.domain`	7	Threat intel entry for malicious embedded domain	`Backend`
4004	`ti.url`	7	Threat intel entry for malicious embedded URL	`Backend`

Other events

Other events, numbered from 9000 to 9999, include miscellaneous or maintenance-related events.

ID	Event Name	Severity	Description	Components
9001	`sys.mta`	0	Postfix activity log entry	`Mta`
9004	`audit.xcc_instance_metrics.submitted`	0	XCC submitted instance metrics to xCloud	`Backend`
9990	`sys.deprecation.warn`	6	Deprecated feature or configuration in use and requires attention	`Core`

​Configuration

​Name

​Severity

​Component

​System Events

​Message-tracing events

​Audit trail events

​Result publication tracing events

​Threat analysis events

​Other events

Configuration

Name

Severity

Component

System Events

Message-tracing events

Audit trail events

Result publication tracing events

Threat analysis events

Other events