> ## 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.
# Loggers
> Reference of the loggers you can configure and the events each one records.
**Remember to Configure the Appender**
In 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.
```xml theme={null}
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` |