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

# Create a Custom Role

> Define a custom role from permissions and scopes when the built-in roles do not fit.

For the list of built-in roles, see [Built-in User Roles](/latest/built-in-user-roles).

xorlab defines the concepts of *Roles*, *Permissions* and *Scopes*:

* A *Permission* denotes a specific action bound to a specific *Scope*. Example: Releasing an email from the quarantine.
* A *Scope* limits a permission to a specific context. Example: Releasing an email is only allowed for a specific tenant.
* A *Role* is a set of *Scopes* with *Permissions*. If needed, *Roles* can be arbitrarily composed and assigned to users.

Only roles can be assigned to users.

## Create a new role

1. Open the file `xcc.yml` in the Expert Editor.

2. Add the name and permissions of the new role to `roleToPermissionMappings`. You can find all permissions below at [Permissions-role matrix](#permissions-role-matrix). Optionally, you can restrict the scope of permissions as shown in [Set the permission scope](#set-the-permission-scope)

   ```yaml xcc.yml theme={null}
   roleToPermissionMappings:
   # We advise to use lower snake case for custom role names.
   # Notice, that you must not use built-in role names like xcc_admin, etc.
   custom_role1:
       # The set of granted permissions associated to the role
       - xcc_asset_fetch|tenant:primary
       - xcc_rule_list_fetch
   custom_role2:
       - xcc_soc_portal|tenant:primary
   ```

**Hint:** You can query your current permissions as described [here](/latest/troubleshooting#how-to-view-the-current-permissions-of-a-user).

## Set the permission scope

Optional: you can restrict the permission scope with the following syntax. If you omit the scope, the permission will have global scope.

```
<grantDefinition>           := <permissionName>(|<scopeDefinition>)*
<scopeDefinition>           := <mailScopeDefinition>|<verdictScopeDefinition>|<quarantineScopeDefinition>|<perTenantScope>
<mailScopeDefinition>       := email:|sender:|recipient:(primary|all|(specific:<emailAddress>))
<quarantineScopeDefinition> := quarantine:(Airlock|BEC|Extortion|Filter|Impersonation|Malware|Phishing|Spam)
<perTenantScope>            := tenant:(primary|<tenantUid>)
<permissionName>            := See Permissions-Role Matrix
```

Examples:

| Definition                                                                           | Explanation                                                                      |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `xcc_quarantine_release`                                                             | Allows releasing any quarantined email.                                          |
| `xcc_quarantine_release\|email:primary\|tenant:11111111-1111-1111-1111-111111111111` | Allows releasing emails quarantined for the user's primary email address.        |
| `xcc_quarantine_release\|recipient:all\|quarantine:Spam`                             | Allows releasing only spam emails quarantined for all of the user's addresses.   |
| `xcc_quarantine_release\|tenant:primary\|quarantine:Spam`                            | Allows releasing only spam emails quarantined for the user's primary tenant.     |
| `xcc_quarantine_release\|sender:primary\|quarantine:Phishing`                        | Allows releasing only sent phishing emails for the user's primary email address. |

When you finish editing `roleToPermissionMappings` in `xcc.yml`, click **Publish**. The role mapping becomes active within about one minute.

## Permissions-role matrix

This table shows whether a specific built-in role has a `Permission` or not and if so with what `Scope`.

* Table entry `global` means that the role has unrestricted access for a specific permission.
* Table entry `tenant:primary` means that the role has access for a specific permission but only within the bounds of the current user's tenant.
* A missing table entry indicates that the role does not have that permission at all.

| Permission                                                                                                                                                                                | xcc\_admin | xcc\_admin\_audit | xcc\_analyst | xcc\_analyst\_audit | xcc\_tenant\_analyst | xcc\_tenant\_analyst\_audit | xcc\_insights | xcc\_monitor | xcc\_quarantine\_user                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------- | ------------ | ------------------- | -------------------- | --------------------------- | ------------- | ------------ | ----------------------------------------------------------------------------- |
| `config_service_read`<p />Allows reading of configuration file from the config service in Expert Editor                                                                                   | global     | global            |              |                     |                      |                             |               |              |                                                                               |
| `config_service_write`<p />Allows editing of a configuration file in the config service in Expert Editor                                                                                  | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_api_key_create`<p />Allows creation of new API keys.                                                                                                                                 | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_api_key_delete`<p />Allows deletion of API keys.                                                                                                                                     | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_api_key_fetch`<p />Allows listing API keys.                                                                                                                                          | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_asset_fetch`<p />Allows retrieving analysis artifacts of messages, reported emails, and uploaded files                                                                               | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canView`\*)           |
| `xcc_backup_info_fetch`<p />Allows access to information about the current backup status                                                                                                  | global     | global            |              |                     |                      |                             |               |              |                                                                               |
| `xcc_backup_trigger`<p />Allows manually triggering of a backup                                                                                                                           | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_campaign_add`<p />Allows creation of a new campaign                                                                                                                                  | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_campaign_archive`<p />Allows archiving of a campaign                                                                                                                                 | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_campaign_fetch`<p />Allows retrieval of the campaigns                                                                                                                                | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              |                                                                               |
| `xcc_campaign_remove`<p />Allows removal of a campaign                                                                                                                                    | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_campaign_update`<p />Allows update of existing campaigns                                                                                                                             | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_config_m365_credentials`<p />Allows managing (setting or clearing) stored credentials for Microsoft 365 integrations                                                                 | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_core_result_delete`<p />Allows to delete a result from xcc                                                                                                                           | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_file_upload`<p />Allows uploading files for analysis                                                                                                                                 | global     |                   | global       |                     | global               |                             |               |              |                                                                               |
| `xcc_incident_isolate`<p />Allows isolation of one or multiple messages                                                                                                                   | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_incident_resolve`<p />Allows resolving one or multiple incidents                                                                                                                     | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_login`<p />Allows performing a login from the UI                                                                                                                                     | global     | global            | global       | global              | global               | global                      |               |              | global                                                                        |
| `xcc_mail_import_read`<p />Allows reading of mail imports                                                                                                                                 | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_mail_import_update`<p />Allows updating/managing of mail imports                                                                                                                     | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_quarantine_archive`<p />Allows archiving of a quarantined message.                                                                                                                   | global     |                   | global       |                     | tenant:primary       |                             |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canView`\*)           |
| `xcc_quarantine_release`<p />Allows the release of one or more quarantined messages                                                                                                       | global     |                   | global       |                     | tenant:primary       |                             |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canRelease`\*)        |
| `xcc_quarantine_release_request_create`<p />Allows creating a release request for one or more quarantined messages                                                                        | global     |                   | global       |                     | tenant:primary       |                             |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canRequestRelease`\*) |
| `xcc_quarantine_release_request_resolve`<p />Allows resolving a message which has been requested to be released either by approving or denying the request.                               | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_result_detail_dana_screenshots`<p />Allows viewing of screenshots and videos from the dynamic analysis (if available)                                                                | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canView`\*)           |
| `xcc_result_detail_fetch`<p />Allows view of the email details                                                                                                                            | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canView`\*)           |
| `xcc_result_detail_preview`<p />Allows viewing of email previews (if available)                                                                                                           | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canView`\*)           |
| `xcc_result_detail_unlock`<p />Allows unlocking of emails with encrypted attachments (Attachment Airlock)                                                                                 | global     |                   | global       |                     | tenant:primary       |                             |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canUnlock`\*)         |
| `xcc_result_list_fetch`<p />Allows view of search query results (e.g., the <b>Messages</b> overview)                                                                                      | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              | recipient:all\|quarantine:myQuarantine\|tenant:primary(`canView`\*)           |
| `xcc_result_query_check`<p />Internal permission required for all roles                                                                                                                   | global     | global            | global       | global              | global               | global                      |               |              | global                                                                        |
| `xcc_result_report_log_add`<p />Allows to add a new message to the report log                                                                                                             | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_result_report_log_fetch`<p />Allows viewing of the case log                                                                                                                          | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              |                                                                               |
| `xcc_rule_list_add`<p />Allows addition of entries on black- and whitelists                                                                                                               | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_rule_list_fetch`<p />Allows retrieval of black- and whitelists                                                                                                                       | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              |                                                                               |
| `xcc_rule_list_remove`<p />Allows removal of entries of rule lists                                                                                                                        | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_rule_list_update`<p />Allows editing of black- and whitelists                                                                                                                        | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_search_add`<p />Allows creation of a new saved query                                                                                                                                 | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_search_fetch`<p />Allows retrieval of the saved queries                                                                                                                              | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              |                                                                               |
| `xcc_search_remove`<p />Allows removal of existing saved queries                                                                                                                          | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_search_update`<p />Allows update of existing saved queries                                                                                                                           | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_share_misclassification`<p />Allows submission of misclassification reports                                                                                                          | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_sidebar_file_upload`<p />Allows access to the list of files uploaded using the `File Upload` menu item                                                                               | global     | global            | global       | global              | global               | global                      |               |              |                                                                               |
| `xcc_sidebar_insights`<p />Allows access to the `Insights` menu item<br /><b>Note: </b>To access the actual dashboards, the user must also have role `xcc_insights`                       |            |                   |              |                     |                      |                             | global        |              |                                                                               |
| `xcc_sidebar_messages`<p />Allows display of the <b>Messages</b> menu item                                                                                                                | global     | global            | global       | global              | global               | global                      |               |              |                                                                               |
| `xcc_sidebar_monitor`<p />Allows access to `Monitoring` menu item<br /><b>Note: </b>To access the actual dashboards, the user must also have role `xcc_monitor`                           |            |                   |              |                     |                      |                             |               | global       |                                                                               |
| `xcc_sidebar_quarantines`<p />Allows display of the <b>Quarantines</b> menu item                                                                                                          | global     | global            | global       | global              | global               | global                      |               |              |                                                                               |
| `xcc_sidebar_reported`<p />Allows display of the <b>Reported</b> menu item                                                                                                                | global     | global            | global       | global              | global               | global                      |               |              |                                                                               |
| `xcc_sidebar_threat_intelligence`<p />Allows access to the `Threat Intelligence` menu item<br /><b>Note: </b>To access the actual dashboards, the user must also have role `xcc_insights` |            |                   |              |                     |                      |                             | global        |              |                                                                               |
| `xcc_soc_portal`<p />Allows general access to the main analyst UI                                                                                                                         | global     | global            | global       | global              | global               | global                      |               |              |                                                                               |
| `xcc_ssq_portal`<p />Allows access to the self-service user quarantine UI                                                                                                                 | global     | global            | global       | global              | global               | global                      |               |              | global                                                                        |
| `xcc_topics_fetch`<p />Allows viewing of the extracted topics from email (if available)                                                                                                   | global     | global            | global       | global              | tenant:primary       | tenant:primary              |               |              |                                                                               |
| `xcc_user_impersonate`<p />Allows impersonation of another user                                                                                                                           | global     |                   |              |                     |                      |                             |               |              |                                                                               |
| `xcc_user_settings_change_language`<p />Allows the user to change their language                                                                                                          | global     | global            | global       | global              | global               | global                      |               |              | global                                                                        |
| `xcc_user_settings_change_quarantine_notification`<p />Allows the user to change their quarantine notification settings                                                                   | global     | global            | global       | global              | global               | global                      |               |              | global                                                                        |
| `xcc_user_settings_change_theme`<p />Allows the user to change their settings (e.g., the theme)                                                                                           | global     | global            | global       | global              | global               | global                      |               |              | global                                                                        |
| `xcc_user_tags_add`<p />Allows adding of one or multiple tags for an analyzed message, reported incident, and uploaded file                                                               | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |
| `xcc_user_tags_fetch`<p />Allows retrieval of user tags attached to an analyzed message, reported incident, and uploaded file                                                             | global     | global            | global       | global              | global               | global                      |               |              |                                                                               |
| `xcc_user_tags_remove`<p />Allows removal of one or multiple tags for an analyzed message, reported incident, and uploaded file                                                           | global     |                   | global       |                     | tenant:primary       |                             |               |              |                                                                               |