Create a Custom Role

For the list of built-in roles, see 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

Open the file xcc.yml in the Expert Editor.

Add the name and permissions of the new role to roleToPermissionMappings. You can find all permissions below at Permissions-role matrix. Optionally, you can restrict the scope of permissions as shown in Set the permission scope

xcc.yml

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.

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

​Create a new role

​Set the permission scope

​Permissions-role matrix

Create a new role

Set the permission scope

Permissions-role matrix