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 or Start from a built-in role.

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_analyst_portal|tenant:primary

Hint: You can query your current permissions as described here.

A custom role for SSQ users is not supported. It is required to use the built-in role xcc_quarantine_user. If you need to adjust the available permissions for your SSQ users, contact support@xorlab.com.

Start from a built-in role

Rather than assembling a role permission by permission, copy the full set of a built-in role and remove what you do not need. Each block below is the complete permission list of one built-in role, ready to paste into roleToPermissionMappings. Rename my_custom_role first — a custom role must not reuse a built-in role name.

xcc_admin

56 permissions

xcc.yml

# Admin
roleToPermissionMappings:
  my_custom_role:
      - config_service_read
      - config_service_write
      - xcc_analyst_portal
      - xcc_api_key_create
      - xcc_api_key_delete
      - xcc_api_key_fetch
      - xcc_asset_fetch
      - xcc_backup_info_fetch
      - xcc_backup_trigger
      - xcc_campaign_add
      - xcc_campaign_archive
      - xcc_campaign_fetch
      - xcc_campaign_remove
      - xcc_campaign_update
      - xcc_config_m365_credentials
      - xcc_core_result_delete
      - xcc_file_upload
      - xcc_incident_isolate
      - xcc_incident_resolve
      - xcc_login
      - xcc_mail_import_read
      - xcc_mail_import_update
      - xcc_quarantine_archive
      - xcc_quarantine_release
      - xcc_quarantine_release_request_create
      - xcc_quarantine_release_request_resolve
      - xcc_result_detail_dana_screenshots
      - xcc_result_detail_fetch
      - xcc_result_detail_preview
      - xcc_result_detail_unlock
      - xcc_result_list_fetch
      - xcc_result_query_check
      - xcc_result_report_log_add
      - xcc_result_report_log_fetch
      - xcc_rule_list_add
      - xcc_rule_list_fetch
      - xcc_rule_list_remove
      - xcc_rule_list_update
      - xcc_search_add
      - xcc_search_fetch
      - xcc_search_remove
      - xcc_search_update
      - xcc_share_misclassification
      - xcc_sidebar_file_upload
      - xcc_sidebar_messages
      - xcc_sidebar_quarantines
      - xcc_sidebar_reported
      - xcc_ssq_portal
      - xcc_topics_fetch
      - xcc_user_impersonate
      - xcc_user_settings_change_language
      - xcc_user_settings_change_quarantine_notification
      - xcc_user_settings_change_theme
      - xcc_user_tags_add
      - xcc_user_tags_fetch
      - xcc_user_tags_remove

xcc_admin_audit

24 permissions

xcc.yml

# Admin audit
roleToPermissionMappings:
  my_custom_role:
      - config_service_read
      - xcc_analyst_portal
      - xcc_asset_fetch
      - xcc_backup_info_fetch
      - xcc_campaign_fetch
      - xcc_login
      - xcc_result_detail_dana_screenshots
      - xcc_result_detail_fetch
      - xcc_result_detail_preview
      - xcc_result_list_fetch
      - xcc_result_query_check
      - xcc_result_report_log_fetch
      - xcc_rule_list_fetch
      - xcc_search_fetch
      - xcc_sidebar_file_upload
      - xcc_sidebar_messages
      - xcc_sidebar_quarantines
      - xcc_sidebar_reported
      - xcc_ssq_portal
      - xcc_topics_fetch
      - xcc_user_settings_change_language
      - xcc_user_settings_change_quarantine_notification
      - xcc_user_settings_change_theme
      - xcc_user_tags_fetch

xcc_analyst

45 permissions

xcc.yml

# Analyst
roleToPermissionMappings:
  my_custom_role:
      - xcc_analyst_portal
      - xcc_asset_fetch
      - xcc_campaign_add
      - xcc_campaign_archive
      - xcc_campaign_fetch
      - xcc_campaign_remove
      - xcc_campaign_update
      - xcc_file_upload
      - xcc_incident_isolate
      - xcc_incident_resolve
      - xcc_login
      - xcc_mail_import_read
      - xcc_quarantine_archive
      - xcc_quarantine_release
      - xcc_quarantine_release_request_create
      - xcc_quarantine_release_request_resolve
      - xcc_result_detail_dana_screenshots
      - xcc_result_detail_fetch
      - xcc_result_detail_preview
      - xcc_result_detail_unlock
      - xcc_result_list_fetch
      - xcc_result_query_check
      - xcc_result_report_log_add
      - xcc_result_report_log_fetch
      - xcc_rule_list_add
      - xcc_rule_list_fetch
      - xcc_rule_list_remove
      - xcc_rule_list_update
      - xcc_search_add
      - xcc_search_fetch
      - xcc_search_remove
      - xcc_search_update
      - xcc_share_misclassification
      - xcc_sidebar_file_upload
      - xcc_sidebar_messages
      - xcc_sidebar_quarantines
      - xcc_sidebar_reported
      - xcc_ssq_portal
      - xcc_topics_fetch
      - xcc_user_settings_change_language
      - xcc_user_settings_change_quarantine_notification
      - xcc_user_settings_change_theme
      - xcc_user_tags_add
      - xcc_user_tags_fetch
      - xcc_user_tags_remove

xcc_analyst_audit

22 permissions

xcc.yml

# Analyst audit
roleToPermissionMappings:
  my_custom_role:
      - xcc_analyst_portal
      - xcc_asset_fetch
      - xcc_campaign_fetch
      - xcc_login
      - xcc_result_detail_dana_screenshots
      - xcc_result_detail_fetch
      - xcc_result_detail_preview
      - xcc_result_list_fetch
      - xcc_result_query_check
      - xcc_result_report_log_fetch
      - xcc_rule_list_fetch
      - xcc_search_fetch
      - xcc_sidebar_file_upload
      - xcc_sidebar_messages
      - xcc_sidebar_quarantines
      - xcc_sidebar_reported
      - xcc_ssq_portal
      - xcc_topics_fetch
      - xcc_user_settings_change_language
      - xcc_user_settings_change_quarantine_notification
      - xcc_user_settings_change_theme
      - xcc_user_tags_fetch

xcc_tenant_analyst

45 permissions

xcc.yml

# Tenant analyst
roleToPermissionMappings:
  my_custom_role:
      - xcc_analyst_portal
      - xcc_asset_fetch|tenant:primary
      - xcc_campaign_add|tenant:primary
      - xcc_campaign_archive|tenant:primary
      - xcc_campaign_fetch|tenant:primary
      - xcc_campaign_remove|tenant:primary
      - xcc_campaign_update|tenant:primary
      - xcc_file_upload
      - xcc_incident_isolate|tenant:primary
      - xcc_incident_resolve|tenant:primary
      - xcc_login
      - xcc_mail_import_read|tenant:primary
      - xcc_quarantine_archive|tenant:primary
      - xcc_quarantine_release|tenant:primary
      - xcc_quarantine_release_request_create|tenant:primary
      - xcc_quarantine_release_request_resolve|tenant:primary
      - xcc_result_detail_dana_screenshots|tenant:primary
      - xcc_result_detail_fetch|tenant:primary
      - xcc_result_detail_preview|tenant:primary
      - xcc_result_detail_unlock|tenant:primary
      - xcc_result_list_fetch|tenant:primary
      - xcc_result_query_check
      - xcc_result_report_log_add|tenant:primary
      - xcc_result_report_log_fetch|tenant:primary
      - xcc_rule_list_add|tenant:primary
      - xcc_rule_list_fetch|tenant:primary
      - xcc_rule_list_remove|tenant:primary
      - xcc_rule_list_update|tenant:primary
      - xcc_search_add|tenant:primary
      - xcc_search_fetch|tenant:primary
      - xcc_search_remove|tenant:primary
      - xcc_search_update|tenant:primary
      - xcc_share_misclassification|tenant:primary
      - xcc_sidebar_file_upload
      - xcc_sidebar_messages
      - xcc_sidebar_quarantines
      - xcc_sidebar_reported
      - xcc_ssq_portal
      - xcc_topics_fetch|tenant:primary
      - xcc_user_settings_change_language
      - xcc_user_settings_change_quarantine_notification
      - xcc_user_settings_change_theme
      - xcc_user_tags_add|tenant:primary
      - xcc_user_tags_fetch
      - xcc_user_tags_remove|tenant:primary

xcc_tenant_analyst_audit

22 permissions

xcc.yml

# Tenant analyst audit
roleToPermissionMappings:
  my_custom_role:
      - xcc_analyst_portal
      - xcc_asset_fetch|tenant:primary
      - xcc_campaign_fetch|tenant:primary
      - xcc_login
      - xcc_result_detail_dana_screenshots|tenant:primary
      - xcc_result_detail_fetch|tenant:primary
      - xcc_result_detail_preview|tenant:primary
      - xcc_result_list_fetch|tenant:primary
      - xcc_result_query_check
      - xcc_result_report_log_fetch|tenant:primary
      - xcc_rule_list_fetch|tenant:primary
      - xcc_search_fetch|tenant:primary
      - xcc_sidebar_file_upload
      - xcc_sidebar_messages
      - xcc_sidebar_quarantines
      - xcc_sidebar_reported
      - xcc_ssq_portal
      - xcc_topics_fetch|tenant:primary
      - xcc_user_settings_change_language
      - xcc_user_settings_change_quarantine_notification
      - xcc_user_settings_change_theme
      - xcc_user_tags_fetch

xcc_insights

2 permissions

xcc.yml

# Insights
roleToPermissionMappings:
  my_custom_role:
      - xcc_sidebar_insights
      - xcc_sidebar_threat_intelligence

xcc_monitor

1 permission

xcc.yml

# Monitor
roleToPermissionMappings:
  my_custom_role:
      - xcc_sidebar_monitor

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

​Create a new role

​Start from a built-in role

​Set the permission scope

​Permissions-role matrix

Create a new role

Start from a built-in role

Set the permission scope

Permissions-role matrix